Planktoscope MQTT API Reference🔗

The MQTT API is the primary programming interface for controlling the PlanktoScope. The API is served by the PlanktoScope's Python backend, and data is sent across the API with the following architecture:

flowchart TD
    API[API Client] -->|Command| Broker[MQTT Broker]
    Broker -->|Command| Backend[Python Backend]
    Backend -->|Status Update| Broker[MQTT Broker]
    Broker -->|Status Update| API

Most messages in the MQTT API are organized according to a request-response pattern in which the API client sends a command as a request to take some action, and then the Python backend sends one or more responses as status updates about how the Python backend's state has changed as a result of the command:

• API clients send commands to the Python backend (via the MQTT broker), and receive status updates from the Python backend (also via the MQTT broker). The PlanktoScope's Node-RED dashboard is an API client, but other programs are also allowed to act as API clients.
• The MQTT broker passes commands and status updates between the API client(s) and the Python backend. The MQTT broker runs on the PlanktoScope and accepts connections from API clients on port 1883.
• The Python backend handles commands, takes actions (e.g. changing the state of hardware actuators), and publishes status updates both in response to commands and in response to changes in internal state. Currently, parts of the Python backend also act as MQTT API clients to other parts of the Python backend.

Every MQTT message in the PlanktoScope's MQTT API is published on a specific topic, which is a slash-delimited path of strings (e.g. actuator/pump). Every MQTT message in the PlanktoScope's MQTT API carries a payload, which is a JSON object serialized as a string:

• Messages which are commands usually specify the type of command in an action field of the payload object; other fields of the payload object are parameters of the command.
• Messages which are status updates have a single field in the payload object, status, which is a string containing a status or error message.

In the rest of this reference document, we organize our description of the MQTT API into sections corresponding to distinct functionalities of the Python backend:

Pump🔗

The Pump API controls the movement of fluid through the PlanktoScope:

• MQTT topics for commands: actuator/pump
• MQTT topics for status updates: status/pump
• Commands: move, stop

move command🔗

The move command initiates movement of fluid through the PlanktoScope by driving the PlanktoScope pump's stepper motor. For example, this command makes the pump move 10 mL of fluid forwards through the PlanktoScope's fluidic path, at a rate of 1 mL/min:

{
  "action": "move",
  "direction": "FORWARD",
  "volume": 10,
  "flowrate": 1
}

The move command has the following parameters:

move command responses🔗

The Python backend can send status updates on the status/pump topic, in response to the move command. The status field of such status updates can have any of the following values:

Note: the MQTT API does not yet completely specify error messages in response to invalid values for the direction, volume, and flowrate parameters.

stop command🔗

The stop command interrupts any ongoing movement of fluid through the PlanktoScope and cuts off power to the PlanktoScope pump's stepper motor:

{
  "action": "stop"
}

The stop command has the following parameters:

stop command responses🔗

The Python backend can send status updates on the status/pump topic, in response to the stop command. The status field of such status updates can have any of the following values:

Non-response status updates🔗

The Python backend can send status updates on the status/pump topic which are not triggered by any command. The status field of such status updates can have any of the following values:

Focus🔗

The Focus API controls the movement of the sample stage focusing motors in the PlanktoScope:

• MQTT topics for commands: actuator/focus
• MQTT topics for status updates: status/focus
• Commands: move, stop

move command🔗

The move command initiates movement of the focusing stage by a specified displacement. For example, this command makes the stage move up by 0.26 mm at a speed of 1 mm/s:

{
  "action": "move",
  "direction": "UP",
  "distance": 0.26,
  "speed": 1
}

The move command has the following parameters:

move command responses🔗

The Python backend can send status updates on the status/focus topic in response to the move command. The status field of such status updates can have any of the following values:

stop command🔗

The stop command interrupts any ongoing movement of the focusing stage and cuts off power to the focusing motors:

{
  "action": "stop"
}

The stop command has the following parameters:

stop command responses🔗

The Python backend can send status updates on the status/focus topic, in response to the stop command. The status field of such status updates can have any of the following values:

Non-response status updates🔗

The Python backend can send status updates on the status/focus topic which are not triggered by any command. The status field of such status updates can have any of the following values:

Light🔗

The Light API controls the state of the LED lighting system in the PlanktoScope:

• MQTT topics for commands: actuator/light
• MQTT topics for status updates: status/light
• Commands: on, off

on command🔗

The on command turns on the sample illumination LED. For example:

{
  "action": "on"
  "led": "1"
}

The on command has the following parameters:

on command responses🔗

The Python backend can send status updates on the status/light topic in response to the on command. The status field of such status updates can have any of the following values:

off command🔗

The off command turns off the sample illumination LED. For example:

{
  "action": "off"
}

The off command has the following parameters:

off command responses🔗

The Python backend can send status updates on the status/light topic in response to the off command. The status field of such status updates can have any of the following values:

Non-response status updates🔗

The Python backend can send status updates on the status/light topic which are not triggered by any command. The status field of such status updates can have any of the following values:

Imager🔗

The Imager API controls image acquisition with the PlanktoScope's hardware, as well as the PlanktoScope's camera:

• MQTT topics for commands: imager/image
• MQTT topics for status updates: status/imager
• Commands: settings, update_config, image, stop

For details on how images are acquired, refer to our technical reference on sample imaging in the PlanktoScope.

Generally, commands should be sent in the following order:

1. settings command: Configure the camera settings.
2. update_config command: Update the dataset metadata for the next image acquisition.
3. image command: Initiate image acquisition.
4. stop command: Stop any in-progress image acquisition.

settings command🔗

The settings command changes the camera settings. The fields iso, shutter_speed, white_balance_gain and white_balance are optional - if a field is omitted, its setting will not be changed. Here's an example of a command with values specified for all fields:

{
  "action": "settings",
  "settings": {
    "iso": 100,
    "shutter_speed": 40,
    "white_balance_gain": { "red": 100, "blue": 100 },
    "white_balance": "auto",
  }
}

The settings command has the following parameters:

settings command responses🔗

The Python backend can send status updates on the status/imager topic in response to the settings command. The status field of such status updates can have any of the following values:

update_config command🔗

The update_config command sets/changes the metadata which will be saved with the dataset which to be acquired by the next image command. For example:

{
  "action": "update_config",
  "config": {
    "sample_project": "fairscope bzh",
    "sample_id": "fairscope_bzh_estacade",
    "sample_uuid": "uuid-1234",
    "sample_ship": "Fairscope",
    "sample_operator": "jeremy",
    "sample_sampling_gear": "net",
    "sample_concentrated_sample_volume": 70,
    "sample_total_volume": 100,
    "sample_dilution_factor": 10,
    "sample_speed_through_water": "5 knots",
    "sample_instrument": "PlanktoScope v2.6",
    "sample_bottom_depth": "N/A",
    "sample_depth_min": 0.1,
    "sample_depth_max": 0.5,
    "sample_temperature": "N/A",
    "sample_salinity": "N/A",
    "sample_date": "2024-05-15",
    "acq_id": "fairscope_bzh_estacade_2",
    "acq_instrument": "PlanktoScope v2.6",
    "acq_magnification": "1.2",
    "acq_camera_id": "deep-point-8125",
    "acq_camera_lens": "N/A",
    "acq_software": "PlanktoScope v2024.0.0-alpha.1",
    "acq_atlas_id": "N/A",
    "acq_resolution": "1080p",
    "acq_stacks_count": "N/A",
    "acq_time_between_frames": 0.3,
    "acq_brightness": "N/A",
    "acq_contrast": "N/A",
    "acq_sharpness": "N/A",
    "acq_saturation": "N/A",
    "acq_gamma": "N/A",
    "acq_uuid": "acq-uuid-5678",
    "acq_volume": 2.50,
    "acq_imaged_volume": 1.04,
    "acq_minimum_mesh": 300,
    "acq_maximum_mesh": 300,
    "acq_min_esd": 300,
    "acq_max_esd": 300,
    "acq_camera_name": "HQ Camera",
    "acq_nb_frame": 500,
    "acq_local_datetime": "2024-05-15T09:00:00Z",
    "acq_caamera_iso": 400,
    "acq_camera_shutter_speed": 500,
    "object_date": "2024-05-15",
    "object_time": "09:00:00Z",
    "object_lat": 48.7273,
    "object_lon": -3.9814,
    "object_depth_min": 0.1,
    "object_depth_max": 0.5,
    "process_pixel": 0.75,
    "process_datetime": "2024-05-15T09:00:00Z",
    "process_id": "Process01",
    "process_uuid": "proc-uuid-7890",
    "process_source": "https://www.github.com/PlanktonPlanet/PlanktoScope",
    "process_commit": "CommitHash",
    "sample_gear_net_opening": 300,
    "object_date_end": "2024-05-15",
    "object_time_end": "10:00:00Z",
    "object_lat_end": 48.7274,
    "object_lon_end": -3.9815
  }
}

The metadata should contain comprehensive information about the sample, acquisition process, object details, and processing parameters to ensure accurate tracking and reproducibility of the dataset. The update_config command has the following parameters:

Sample information:

Acquisition information:

Object information:

Processing information:

update_config command responses🔗

The Python backend can send status updates on the status/imager topic in response to the update_config command. The status field of such status updates can have any of the following values:

image command🔗

The image command initiates acquisition of one raw image dataset consisting of a specified number of images, via stop-flow imaging. For example, this command initiates acquisition of 200 images, with 1 mL of sample pumped between each image and an image stabilization period of 0.1 seconds between the end of pumping and the triggering of the image capture for each acquired image:

{
  "action": "image",
  "pump_direction": "FORWARD",
  "volume": 1,
  "nb_frame": 200,
  "sleep": 0.1
}

A valid update_config command with a unique (object_date, sample_id, acq_id) combination must be sent some time before each image command. If an update_config command has not been sent before the image command, the image command will trigger a “Started” response status and then do nothing (this is a software bug which needs to be fixed so that an error status is reported instead).

The image command has the following parameters:

image command responses🔗

The Python backend can send status updates on the status/imager topic, in response to the image command. The status field of such status updates can have any of the following values:

stop command🔗

This message interrupts any in-progress image acquisition routine and stops any ongoing sample pumping.

{
  "action": "stop"
}

The stop command has the following parameters:

stop command responses🔗

The Python backend can send status updates on the status/imager topic, in response to the stop command. The status field of such status updates can have any of the following values:

Non-response status updates🔗

The Python backend can send status updates on the status/imager topic which are not triggered by any command. The status field of such status updates can have any of the following values:

Segmenter🔗

The Segmenter API controls the processing of acquired images:

• MQTT topics for commands: segmenter/segment
• MQTT topics for status updates: status/segmenter, status/segmenter/object_id, status/segmenter/metric
• Commands: segment

For details on how images are processed, refer to our technical reference on image segmentation in the PlanktoScope.

segment command🔗

The segment command initiates processing of images stored in the specified path, optionally exporting the results to an EcoTaxa-compatible archive. The various settings parameters of this command provide control over the behavior of image processing. For example, this command initiates processing of all images in the /path/to/segment directory:

{
  "action": "segment",
  "path": "/path/to/segment",
  "settings": {
    "force": false,
    "recursive": true,
    "ecotaxa": true,
    "keep": true
  }
}

The segment command has the following parameters:

segment command responses🔗

The Python backend can send status updates on the status/segmenter topic, in response to the segment command. The status field of such status updates can have any of the following values:

As the Python backend performs segmentation, it will repeatedly send additional status updates on the status/segmenter/object_id topic, once for each object isolated by the segmenter. Each status update is a JSON object with the following fields:

As the Python backend performs segmentation, it will repeatedly send additional status updates on the status/segmenter/metric topic, once for each object isolated by the segmenter. Each status update is a JSON object with the following fields:

The metadata field of status updates sent on the status/segmenter/metric topic is an object with the following fields:

stop command🔗

The stop command interrupts any ongoing image processing. For example:

{
  "action": "stop"
}

The stop command has the following parameters:

stop command responses🔗

The Python backend can send status updates on the segmenter/segment topic, in response to the stop command. The status field of such status updates can have any of the following values:

Non-response status updates🔗

The Python backend can send status updates on the status/segmenter topic which are not triggered by any command. The status field of such status updates can have any of the following values: