Illuminator Protocol
The illuminator protocol allows MAVLink control over the behavior of lights, LEDs, and/or emitters mounted or integrated on the drone. The protocol currently allows for the following control: brightness, on/off, and a strobe feature.
Along with this, the illuminator protocol also publishes status information for developers or users. The status messaging encompasses the current configuration of the illuminator and the health of the illuminator device.
MAVLink Illuminator Implementations
These illuminators have built-in MAVLink support:
- Skydio Spotlight for X10
Message/Enum Summary
| Message | Description |
|---|---|
| COMPONENT_INFORMATION_BASIC | Basic illuminator information data. Should be requested using MAV_CMD_REQUEST_MESSAGE on startup, or when required. |
| MAV_CMD_ILLUMINATOR_ON_OFF | Turns illuminators ON/OFF. |
| MAV_CMD_DO_ILLUMINATOR_CONFIGURE | Configures illuminator settings. |
| ILLUMINATOR_STATUS | Current status of the illuminator. Recommended to publish this at a regular rate. |
| Enum Values | Description |
|---|---|
| MAV_TYPE_ILLUMINATOR | Type of the component (illuminator). |
| MAV_COMP_ID_ILLUMINATOR | ID of the component (illuminator). |
| Enum | Description |
|---|---|
| ILLUMINATOR_MODE | Illuminator modes. |
| ILLUMINATOR_ERROR_FLAGS | Fault/health indications. |
Implementation and Messages
Illuminator Connection
Illuminators are expected to follow the Heartbeat/Connection Protocol and send a constant flow of heartbeats (nominally at 1Hz). Illuminators are identified via their type MAV_TYPE_ILLUMINATOR. Individual illuminators are distinguished via their unique component ID, which by default should be MAV_COMP_ID_ILLUMINATOR (though this is not mandated and any ID may be used). Once a heartbeat is received, the drone can then send a MAV_CMD_REQUEST_MESSAGE command to the illuminator to receive information, set settings, or control the illuminator. An example below illustrates how a drone can request the status of the illuminator.
COMPONENT_INFORMATION_BASIC
While the MAV_TYPE and Component ID help identify the system and component, the COMPONENT_INFORMATION_BASIC command can be requested to retrieve component information data, which can help further identify the component being communicated with. This data includes time_boot_ms, MAV_PROTOCOL_CAPABILITY, vendor_name, model_name, software_version, hardware_version, and serial_number.
| Parameter | Description |
|---|---|
time_boot_ms | Time since system boot up in milliseconds. |
MAV_PROTOCOL_CAPABILITY | Bitmask detailing the component capability flags. |
vendor_name | Name of the component vendor (optional). |
model_name | Name of the component's model (optional). |
software_version | Software version on the module, recommended format is SEMVER: 'major.minor.patch' but any format can be used (24-character string) (optional). |
hardware_version | Hardware version on the module, recommended format is SEMVER: 'major.minor.patch' but any format can be used (24-character string) (optional). |
serial_number | Hardware's serial number (optional). |
Optional parameters can be left empty or set to zero.
ON/OFF
The MAV_CMD_ILLUMINATOR_ON_OFF command is used to enable/disable the illuminator. It's usage can be seen below:
CONFIGURE
The MAV_CMD_DO_ILLUMINATOR_CONFIGURE command controls the illuminator's settings. This will adjust how the illuminator behaves when enabled. The operation follows the normal Command Protocol rules for command/acknowledgment. The four parameters for this command are: Mode, Brightness, Strobe Period, Strobe Duty.
Illuminators can be set in different modes which can change the behavior of the illuminator (described in a separate section, Modes). The brightness can be set via "Brightness" as a percentage value (0-100%). Illuminators may also have the functionality to strobe the light source. This behavior is configured via "Strobe Period" and "Strobe Duty". These parameters can be set to 0 when not used. "Strobe Period" is in seconds and "Strobe Duty" is a percentage value (indicating the % of time in the "Strobe Period" the illuminator is enabled).
MODES
If the mode is unknown, the mode parameter value will be set to 0.
A mode value of 1 is ILLUMINATOR_MODE_INTERNAL_CONTROL, where the illuminator behavior is controlled by MAV_CMD_DO_ILLUMINATOR_CONFIGURE settings.
When the value is set to 2, it indicates that the illuminator mode is ILLUMINATOR_MODE_EXTERNAL_SYNC. This mode is for instances where the illuminator behavior is controlled by external factors: e.g. an external hardware signal.
STATUS
The ILLUMINATOR_STATUS message can be requested to receive information about the status of the illuminator. This includes information such as uptime, errors, whether the illuminator is enabled via MAV_CMD_ILLUMINATOR_ON_OFF, current settings from the MAV_CMD_DO_ILLUMINATOR_CONFIGURE command, and the temperature of the illuminator.
ILLUMINATOR_ERROR_FLAGS
The ILLUMINATOR_ERROR_FLAGS can be used to indicate if there is any issue with the illuminator. At this time, there are three flags. If there is no error and the illuminator is behaving as normal, the ILLUMINATOR_ERROR_FLAGS bitmap will be 0. If ILLUMINATOR_ERROR_FLAGS is set to 1 or 2, this indicates an error related to the temperature of the illuminator.
1 indicates ILLUMINATOR_ERROR_FLAGS_THERMAL_THROTTLING as in the illuminator is throttling its output due to a thermal issue. 2 indicates ILLUMINATOR_ERROR_FLAGS_OVER_TEMPERATURE_SHUTDOWN which means that the illuminator is shutting off due to passing some temperature threshold.
The status message utilization can be seen below:
Test Script
Description
The test suite included in assets/services/illuminators allows for testing both sides of the illuminator interaction.
- illuminator.py emulates a standard illuminator module.
- test_illuminator.py runs a standard test suite against the emulator, testing all commands listed in this document.
Instructions
- Run simple illuminator emulator
python3 illuminator.py - Run test
python3 -m unittest -v test_illuminator.py