Add-ons

Introduction

Add-ons are Docker containers that run on the same system as the operational layer. The SystemManager process maintains the add-ons and can start, stop, and update the add-on at request. The add-ons in the system are configured in the system add-on web app, using the Docker Engine API (1.46) syntax.

The system is shipped with the system add-on and the node-red add-on. The as-applied add-on can be added when needed.

Python package

The artof_utils Python package supports new Python add-ons. The package provides the interaction with the operational layer including:

1. ARTOF Redis interface interaction (artof_utils.redis)

2. Field, traject, polygon and task manipulation (artof_utils.helpers)

3. Platform and implement configuration access, validated with pydantic schemas (artof_utils.schemas)

4. As-applied session reading and writing (artof_utils.as_applied)

pip install artof-utils

The package reads the robot configuration from the folder in the ILVO_PATH environment variable (/var/lib/ilvo on a robot). You can find the source code of the Python package in the artof-utils project.

Add-on configuration

Each add-on is described by one JSON object. Every add-on section below has an example configuration to get started quickly: open the Addons page, press , switch the editor to JSON, paste the example and save.

• Name: the add-on and container name. It cannot be changed later.

• AutoStart: start the add-on when the system manager starts (Start with the robot). Defaults to true.

• DockerRegistry: the registry to pull the image from. Add username and password for a private image; leave them out for a public image.

• DockerConfig: the container configuration in the Docker Engine API (1.46) syntax, e.g. Image, Env ("NAME=value") and HostConfig with Binds ("host:container"), NetworkMode and RestartPolicy.

The system manager adds its own state fields (Running, Pid, StartTimeISO, …) to the configuration; you do not need to provide them.

Note

The examples are written for a robot, where the add-ons use the host network. In the Docker setup, set HostConfig.NetworkMode to ilvo_artof_network, add REDIS_HOST=redis to Env, and publish the ports the add-on serves through ExposedPorts and HostConfig.PortBindings (e.g. 1880/tcp for node-red).

Warning

Never put registry credentials in a configuration you share or commit; enter them on the robot only.

System add-on

The system add-on is implemented in Python-Django and provides the web application to operate and configure the robot. It runs on the robot itself (--network=host) and is available from any phone, tablet or laptop on the robot’s network. By default, the web application is hosted at port 80 (PORT environment variable). The source code is in the artof-system project.

The system add-on is installed with the robot. If it was removed, add it again with this configuration:

Listing 1. Example configuration of the system add-on

{
  "Name": "system",
  "AutoStart": true,
  "DockerRegistry": {
    "serveraddress": "https://registry.hub.docker.com/v2/"
  },
  "DockerConfig": {
    "Image": "axelwillekens/artof-system",
    "Env": [
      "PORT=80"
    ],
    "HostConfig": {
      "Binds": [
        "/var/lib/ilvo:/var/lib/ilvo"
      ],
      "NetworkMode": "host",
      "RestartPolicy": {
        "Name": "on-failure",
        "MaximumRetryCount": 3
      }
    }
  }
}

The menu bar holds the operator pages Fields, Map, Applied and Settings, and on the right the Admin area. The pages adapt to phone screens: the menu collapses and tables are shown as cards.

Warning

Many controls act directly on the real robot: the navigation state, hitch heights, navigation settings, map uploads and values written on the Monitor page. Make sure the area around the robot is safe before you change them.

Status bar

Below the menu, the status bar shows the robot’s state, updated live several times per second.

Figure 1. Status bar

• The state selector shows the navigation state (e.g. normal or auto, as defined in the auto_modes of the settings.json file). Tap another state to switch the robot to it.

• The substate chips highlight the current PLC substate: Programming, Implement control, Inhibited, Aware or Stay clear (see Robot status).

• The cross-track error gauge shows how far the robot is beside the traject.

• The GPS chip shows the GNSS fix (green: RTK fix, orange: float, red: no fix).

• The battery chip shows the remaining charge.

• The live heartbeat pulses as long as the connection with the robot is alive.

Robot notifications appear in a notification box; closing it acknowledges the notification on the robot.

Fields

The Fields page is the first page you see when browsing the web application. It gives an overview of the available fields. The robot always works on exactly one selected field.

Figure 2. Fields page

• Select a field by clicking its name or the button.

• Create a field with New field.

• Duplicate a field using the button.

• Edit a field by clicking on the button.

• Download a field as a .zip file (shapefiles and settings) by pressing the button.

• Delete a field by clicking on the button. The selected field cannot be deleted.

Edit field

The field editor shows a side panel with the name, traject, geofence and tasks of the field, and a map with the shapes.

Figure 3. Field editor

1. Change the name and press Save. Names may only contain letters, digits and underscores.

2. Create the traject and the geofence. For each shape, choose its source and press Save:

   • Original keeps the shape that is already stored on the robot.

   • File uploads a shapefile. Select all its parts together: .shp, .shx, .dbf and preferably .prj and .cpg. The attributes and coordinate system of the file are kept.

   • Draw draws the shape with the drawing tools on the map.

   • Drive leaves the shape to be driven in later with the robot on the Map page.

3. Add one or more tasks with Add task. Choose the hitch, the task type and the implement, and provide the task shape. An implement can only be chosen when it shares a task type with the hitch.

4. After a task is saved, its features are listed with their rate (continuous, cardan) or routine (discrete, intermittent). Edit the values and save the list.

Done returns to the Fields page.

Tip

Prepare large or precise shapes in QGIS and upload them as shapefiles, e.g. with the sampling route generator.

Map

The Map page shows the selected field and the robot with its hitches and implement sections, live.

Figure 4. Map page with the robot driving in auto mode, the swept sections and the as-applied panel

On the map you can see:

• the traject: lines with arrows in the driving direction;

• the geofence: the outline around the field;

• the tasks, in the colour of their task;

• the robot with its outline, hitches and sections. Active sections are highlighted;

• the visualizations of the navigation algorithm: the robot reference, the closest point on the trajectory, and the look-ahead point.

The toolbar on the right contains:

• Follow the robot: keeps the robot in the centre of the map.

• Rotate with heading: turns the map so that the robot always drives upwards.

• Edit field: opens the edit panel (see below).

• Sim activates simulation mode. When the operational layer communicates with the mechatronic layer, the robot goes in Hardware In The Loop (HIL) testing; if not, you perform an integration test in the operational layer.

  • With the Speed factor (+ / −, 0 to 32×) you can multiply the simulation speed.

  • The button lets you drive the simulated robot with the arrow keys, or place it with a click on the map.

• The record button (red dot) starts or stops an as-applied recording. It is disabled in auto mode, because recording then follows auto mode automatically.

The As-applied panel shows a recording on top of the field: the latest (running) session, a specific session, or none. Rec appears while a recording runs (Rec · auto when it follows auto mode).

Editing shapes on site

The edit panel corrects shapes in the field, for example to extend rows or shift them onto the real crop rows.

Figure 5. Map edit panel with the traject selected

1. Choose the shape to edit: the traject, the geofence or one of the tasks.

2. Apply one or more operations. Each result is first shown as a dashed preview; press to accept it.

3. Press Upload to save the accepted changes to the field. Until then, nothing is stored.

Traject operations work on the rows in the Rows box: a single row (0), a list (0,1,3) or a range (0-3).

• Extend rows: make the selected rows longer (negative: shorter) at the begin, the end or both.

• Shift rows: move the selected rows sideways.

• Add rows: add parallel rows next to the first or last row.

• Remove rows: delete the selected rows.

• Change direction: Reverse drives the rows in the opposite direction, Flip changes the order in which the rows are driven.

• Drive in: record a new row with the robot. Drive to the start and press A, press / at each waypoint and B at the end of the row.

For a geofence or polygon task, Buffer grows (positive distance) or shrinks (negative distance) the polygon.

Applied

The Applied page reviews as-applied recordings after the work.

Figure 6. Applied page with a recording coloured by rate

1. Choose the field and the recording (session). The running session is marked (recording).

2. Choose the layer: Sections (the area covered by each section, with its rate) or Points (the robot position log with all Redis variables).

3. Choose an attribute in Colour by, and optionally add filters on any attribute.

4. Click a feature on the map to see all its attributes.

The download button saves the recording as a GeoPackage (.gpkg) that opens directly in QGIS.

Settings

The Settings page holds the settings an operator adjusts while working. Changes are applied as soon as you release a slider or change a selection.

Figure 7. Settings page

• For every hitch: the height setpoint (cm) and, if provided by the robot’s hardware, the Float mode.

• The navigation mode, as explained in Platform.

• The operational and non-operational velocity. The robot uses the operational velocity when it is in a task polygon; otherwise, it uses the non-operational velocity.

• The navigation controller parameters (Pure pursuit, Steady state and Rough).

Admin area

The Admin area is meant for the robot administrator. Its menu has Settings, Implements, Processes, Addons and Monitor.

The form editors (system settings, implements and add-ons) have a Form | JSON switch. Both modes edit the same data. Invalid content is refused with an error, and nothing is saved.

Settings

In the admin Settings, the configuration files can be edited:

• settings.json (system settings) in a form editor with a live top and side preview of the robot and its hitches, or as JSON;

• config.json and types.json in a JSON editor.

Hitch names are checked against the hitches in config.json.

Figure 8. Form editor of settings.json with the robot preview

Note

Changes in the admin Settings require a restart of the robot (computer).

Implements

You can add (), edit () or delete () implements. The implement editor shows the general settings and the sections on the left, and a top and side preview of the implement on a chosen hitch on the right.

Figure 9. Implement editor with its preview

Note

When you are modifying an enabled implement in the selected field, you first need to toggle another field for the changes to occur.

Processes

The Processes page lists the processes of the operational layer with their start time and state.

Figure 10. Processes page

• Start the process by pressing the button.

• Stop the process by pressing the button. Stopping a core process can stop the robot.

• Show the process configuration (read only) by pressing the button.

Add-ons

The Addons page lists the add-ons in the system with their start time and status.

Figure 11. Addons page

• Add a new add-on using the button.

• Start the add-on by pressing the button (the image is pulled when needed).

• Stop the add-on by pressing the button.

• Update the add-on by pressing the button. The latest image is pulled and the container is recreated.

• Edit the add-on by pressing the button.

• Delete the add-on by pressing the button.

The add-on editor sets the name (also the container name, cannot be changed later), Start with the robot, the Docker image, the shared folders, the environment variables, the network and restart policy, and the registry credentials for private images. The side panel shows the add-on status and the equivalent docker run command.

Figure 12. Add-on editor, here for the as-applied add-on under its former name taskmap

Note

The add-on configuration uses the Docker Engine API (1.46) syntax. A configuration that would crash the system manager (no image, an image Docker cannot find, a container-name conflict) is refused. The system manager only uses a changed configuration after it restarts: restart it, then press on the Addons page.

Monitor

The Monitor page shows all Redis variables with their live value.

Figure 13. Monitor page with pinned variables in the live graph

• Search a variable with the search bar.

• Pin a variable to keep it at the top. The pinned set is remembered by the browser.

• Graph adds a numeric or boolean variable to the live graph of the last 30 seconds.

• Write a value in the New value field and press .

• Pulse sets the opposite value of a boolean for 0.5 s and then restores it, like pressing a button.

Note

Altering plc.monitor variables does not have any effect, as they are immediately updated again by the RobotPlc process. Never write an empty string to a variable that the operational layer reads; use a placeholder such as -.

Node-red add-on

The node-red add-on provides flow programming, used for logging and implement interaction. It can be reached at the URL http://<ip-robot>:1880/. The add-on has access to the field and implement folders and the config.json, settings.json and types.json files of the robot. The flows are stored in /var/lib/ilvo/node-red.

Listing 2. Example configuration of the node-red add-on

{
  "Name": "node-red",
  "AutoStart": true,
  "DockerRegistry": {
    "serveraddress": "https://registry.hub.docker.com/v2/"
  },
  "DockerConfig": {
    "Image": "nodered/node-red",
    "HostConfig": {
      "Binds": [
        "/var/lib/ilvo/node-red:/data",
        "/var/lib/ilvo/field:/var/lib/ilvo/field",
        "/var/lib/ilvo/implement:/var/lib/ilvo/implement",
        "/var/lib/ilvo/config.json:/var/lib/ilvo/config.json",
        "/var/lib/ilvo/settings.json:/var/lib/ilvo/settings.json",
        "/var/lib/ilvo/types.json:/var/lib/ilvo/types.json"
      ],
      "NetworkMode": "host",
      "RestartPolicy": {
        "Name": "on-failure",
        "MaximumRetryCount": 3
      }
    }
  }
}

You can install the submodules for extracting the Redis variables and logging them to an InfluxDB instance by

<Coming soon>

As-applied add-on

The as-applied add-on records as-applied sessions. While the Redis variable pc.as_applied.record is true, it polls Redis and writes one session folder per recording.

• Recording is switched on when the robot enters auto mode (a navigation state in auto_modes of settings.json, or pc.simulation.auto in simulation) and off when it leaves it. Outside auto mode it can be toggled from the Map page.

• A new session starts each time recording is switched on or the active field (pc.field.name) changes. The running session id is published in pc.as_applied.session.

• pc.as_applied.heartbeat (unix time, every second) tells the web pages the add-on is alive. Without it, the Map page shows Task-map addon is not running.

• Sections are written once they moved more than TASKMAP_MIN_DISTANCE.

• Points are equidistant: one every TASKMAP_POINT_DISTANCE meters along the driven path, interpolated between polls so the spacing does not depend on the speed or the poll rate. While the robot stands still, a point is logged every TASKMAP_POINT_PERIOD seconds.

The source code is in the artof-addon-as-applied project (formerly artof-addon-taskmap). Add it on the Addons page with the image axelwillekens/artof-addon-as-applied, the host network and the folder /var/lib/ilvo shared with the container. The configuration below does this, with the environment variables at their default values (see the table below). The environment variables keep the TASKMAP_ prefix of the former name:

Listing 3. Example configuration of the as-applied add-on

{
  "Name": "artof-addon-as-applied",
  "AutoStart": true,
  "DockerRegistry": {
    "serveraddress": "https://registry.hub.docker.com/v2/"
  },
  "DockerConfig": {
    "Image": "axelwillekens/artof-addon-as-applied:dev",
    "Env": [
      "TASKMAP_POLL_PERIOD=0.2",
      "TASKMAP_FLUSH_PERIOD=1.0",
      "TASKMAP_MIN_DISTANCE=0.1",
      "TASKMAP_POINT_DISTANCE=1.0",
      "TASKMAP_POINT_PERIOD=5.0"
    ],
    "HostConfig": {
      "Binds": [
        "/var/lib/ilvo:/var/lib/ilvo"
      ],
      "NetworkMode": "host",
      "RestartPolicy": {
        "Name": "on-failure",
        "MaximumRetryCount": 3
      }
    }
  }
}

Or run it manually:

docker run --rm --network=host -v /var/lib/ilvo:/var/lib/ilvo --name artof-addon-as-applied axelwillekens/artof-addon-as-applied:dev

Environment variable	Default	Meaning
TASKMAP_POLL_PERIOD	0.2	Period (s) to poll Redis
TASKMAP_FLUSH_PERIOD	1.0	Period (s) to write the GeoPackages
TASKMAP_MIN_DISTANCE	0.1	Minimum distance (m) before a new section is written
TASKMAP_POINT_DISTANCE	1.0	Distance (m) between points along the driven path
TASKMAP_POINT_PERIOD	5.0	Period (s) to log a point while standing still
REDIS_HOST, REDIS_PORT		Redis server