mavlink-devguide/zh/services/illuminator.md

Illuminator Protocol

The illuminator protocol allows MAVLink control over the behaviour 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/Command/Enum Summary

消息	描述
COMPONENT_INFORMATION_BASIC	Basic illuminator information data. Should be requested using MAV_CMD_REQUEST_MESSAGE on startup, or when required.
ILLUMINATOR_STATUS	Current status of the illuminator. Recommended to publish this at a regular rate.

Command	描述
MAV_CMD_ILLUMINATOR_ON_OFF	Turns illuminators ON/OFF.
MAV_CMD_DO_ILLUMINATOR_CONFIGURE	Configures illuminator settings.

Enum Values	描述
MAV_TYPE_ILLUMINATOR	Type of the component (illuminator).
MAV_COMP_ID_ILLUMINATOR	ID of the component (illuminator).

Enum	描述
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	描述
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

描述

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

1. Run simple illuminator emulator python3 illuminator.py
2. Run test python3 -m unittest -v test_illuminator.py