Add support for illuminators (#2047)

* Add support for illuminators - Add MAV_TYPE and MAV_COMPONENT enums for illuminators - Remove MAV_CMD_ILLUMINATOR_ON_OFF from wip - Add command to configure illuminator settings - Add messages to report illuminator status and information * Update common.xml Address PR comments and add `enable` field in `ILLUMINATOR_STATUS` to indicate if the illuminator is on or off * Update common.xml Address PR comments and fix formatting * Update common.xml Address PR comments (remove PID/VID), add illuminator firmware version, and add illuminator error flags * Update common.xml * Update common.xml Address PR comments: remove `serial_number` and `firmware_version` from `ILLUMINATOR_INFORMATION` and use `COMPONENT_INFORMATION_BASIC` instead * Update common.xml and development.xml Address PR comments: move COMPONENT_INFORMATION_BASIC from development to common and remove ILLUMINATOR_INFORMATION * 1. Resolve conflight: sync to most-up-to-date master and assign a new message id 440 to ILLUMINATOR_STATUS 2. Fix type and add `ILLUMINATOR_ERROR_FLAGS_THERMISTOR_FAILURE` error flag
mavlink · Apr 10, 2024 · 2561b79 · 2561b79
1 parent 966503a
commit 2561b79
Show file tree

Hide file tree

Showing 3 changed files with 62 additions and 13 deletions.
diff --git a/message_definitions/v1.0/common.xml b/message_definitions/v1.0/common.xml
@@ -1993,11 +1993,16 @@
         </description>
       </entry>
       <entry value="405" name="MAV_CMD_ILLUMINATOR_ON_OFF" hasLocation="false" isDestination="false">
-        <wip/>
-        <!-- This message is work-in-progress and it can therefore change. It should NOT be used in stable production environments. -->
         <description>Turns illuminators ON/OFF. An illuminator is a light source that is used for lighting up dark areas external to the system: e.g. a torch or searchlight (as opposed to a light source for illuminating the system itself, e.g. an indicator light).</description>
         <param index="1" label="Enable" minValue="0" maxValue="1" increment="1">0: Illuminators OFF, 1: Illuminators ON</param>
       </entry>
+      <entry value="406" name="MAV_CMD_DO_ILLUMINATOR_CONFIGURE" hasLocation="false" isDestination="false">
+        <description>Configures illuminator settings. An illuminator is a light source that is used for lighting up dark areas external to the system: e.g. a torch or searchlight (as opposed to a light source for illuminating the system itself, e.g. an indicator light).</description>
+        <param index="1" label="Mode" enum="ILLUMINATOR_MODE">Mode</param>
+        <param index="2" label="Brightness" units="%" minValue="0" maxValue="100">0%: Off, 100%: Max Brightness</param>
+        <param index="3" label="Strobe Period" units="s" minValue="0">Strobe period in seconds where 0 means strobing is not used</param>
+        <param index="4" label="Strobe Duty" units="%" minValue="0" maxValue="100">Strobe duty cycle where 100% means it is on constantly and 0 means strobing is not used</param>
+      </entry>
       <entry value="410" name="MAV_CMD_GET_HOME_POSITION" hasLocation="false" isDestination="false">
         <deprecated since="2022-04" replaced_by="MAV_CMD_REQUEST_MESSAGE"/>
         <description>Request the home position from the vehicle.
@@ -5073,6 +5078,30 @@
         <description>Safety switch is NOT engaged and motors, propellers and other actuators should be considered active.</description>
       </entry>
     </enum>
+    <enum name="ILLUMINATOR_MODE">
+      <description>Modes of illuminator</description>
+      <entry value="0" name="ILLUMINATOR_MODE_UNKNOWN">
+        <description>Illuminator mode is not specified/unknown</description>
+      </entry>
+      <entry value="1" name="ILLUMINATOR_MODE_INTERNAL_CONTROL">
+        <description>Illuminator behavior is controlled by MAV_CMD_DO_ILLUMINATOR_CONFIGURE settings</description>
+      </entry>
+      <entry value="2" name="ILLUMINATOR_MODE_EXTERNAL_SYNC">
+        <description>Illuminator behavior is controlled by external factors: e.g. an external hardware signal</description>
+      </entry>
+    </enum>
+    <enum name="ILLUMINATOR_ERROR_FLAGS" bitmask="true">
+      <description>Illuminator module error flags (bitmap, 0 means no error)</description>
+      <entry value="1" name="ILLUMINATOR_ERROR_FLAGS_THERMAL_THROTTLING">
+        <description>Illuminator thermal throttling error.</description>
+      </entry>
+      <entry value="2" name="ILLUMINATOR_ERROR_FLAGS_OVER_TEMPERATURE_SHUTDOWN">
+        <description>Illuminator over temperature shutdown error.</description>
+      </entry>
+      <entry value="3" name="ILLUMINATOR_ERROR_FLAGS_THERMISTOR_FAILURE">
+        <description>Illuminator thermistor failure.</description>
+      </entry>
+    </enum>
   </enums>
   <messages>
     <message id="1" name="SYS_STATUS">
@@ -7560,6 +7589,17 @@
       <field type="uint32_t" name="peripherals_metadata_file_crc">CRC32 of peripherals metadata file (peripherals_metadata_uri).</field>
       <field type="char[100]" name="peripherals_metadata_uri">(Optional) MAVLink FTP URI for the peripherals metadata file (COMP_METADATA_TYPE_PERIPHERALS), which may be compressed with xz. This contains data about "attached components" such as UAVCAN nodes. The peripherals are in a separate file because the information must be generated dynamically at runtime. The string needs to be zero terminated.</field>
     </message>
+    <message id="396" name="COMPONENT_INFORMATION_BASIC">
+      <description>Basic component information data. Should be requested using MAV_CMD_REQUEST_MESSAGE on startup, or when required.</description>
+      <field type="uint32_t" name="time_boot_ms" units="ms">Timestamp (time since system boot).</field>
+      <field type="uint64_t" name="capabilities" enum="MAV_PROTOCOL_CAPABILITY" display="bitmask">Component capability flags</field>
+      <field type="uint32_t" name="time_manufacture_s" units="s" invalid="0">Date of manufacture as a UNIX Epoch time (since 1.1.1970) in seconds.</field>
+      <field type="char[32]" name="vendor_name">Name of the component vendor. Needs to be zero terminated. The field is optional and can be empty/all zeros.</field>
+      <field type="char[32]" name="model_name">Name of the component model. Needs to be zero terminated. The field is optional and can be empty/all zeros.</field>
+      <field type="char[24]" name="software_version">Software version. The recommended format is SEMVER: 'major.minor.patch'  (any format may be used). The field must be zero terminated if it has a value. The field is optional and can be empty/all zeros.</field>
+      <field type="char[24]" name="hardware_version">Hardware version. The recommended format is SEMVER: 'major.minor.patch'  (any format may be used). The field must be zero terminated if it has a value. The field is optional and can be empty/all zeros.</field>
+      <field type="char[32]" name="serial_number">Hardware serial number. The field must be zero terminated if it has a value. The field is optional and can be empty/all zeros.</field>
+    </message>
     <message id="397" name="COMPONENT_METADATA">
       <wip/>
       <!-- This message is work-in-progress it can therefore change, and should NOT be used in stable production environments -->
@@ -7631,6 +7671,20 @@
       <field type="uint16_t" name="sequence_oldest_available">Oldest Sequence number that is still available after the sequence set in REQUEST_EVENT.</field>
       <field type="uint8_t" name="reason" enum="MAV_EVENT_ERROR_REASON">Error reason.</field>
     </message>
+    <message id="440" name="ILLUMINATOR_STATUS">
+      <description>Illuminator status</description>
+      <field type="uint32_t" name="uptime_ms" units="ms">Time since the start-up of the illuminator in ms</field>
+      <field type="uint8_t" name="enable">0: Illuminators OFF, 1: Illuminators ON</field>
+      <field type="uint8_t" name="mode_bitmask" enum="ILLUMINATOR_MODE" display="bitmask">Supported illuminator modes</field>
+      <field type="uint32_t" name="error_status" enum="ILLUMINATOR_ERROR_FLAGS" display="bitmask">Errors</field>
+      <field type="uint8_t" name="mode" enum="ILLUMINATOR_MODE">Illuminator mode</field>
+      <field type="float" name="brightness" units="%">Illuminator brightness</field>
+      <field type="float" name="strobe_period" units="s">Illuminator strobing period in seconds</field>
+      <field type="float" name="strobe_duty_cycle" units="%">Illuminator strobing duty cycle</field>
+      <field type="float" name="temp_c">Temperature in Celsius</field>
+      <field type="float" name="min_strobe_period" units="s">Minimum strobing period in seconds</field>
+      <field type="float" name="max_strobe_period" units="s">Maximum strobing period in seconds</field>
+    </message>
     <!-- The message ids 510 and 511 are reserved for ABSOLUTE_TARGET and RELATIVE_TARGET, currently in development.xml. -->
     <message id="387" name="CANFD_FRAME">
       <description>A forwarded CANFD frame as requested by MAV_CMD_CAN_FORWARD. These are separated from CAN_FRAME as they need different handling (eg. TAO handling)</description>

diff --git a/message_definitions/v1.0/development.xml b/message_definitions/v1.0/development.xml
@@ -490,17 +490,6 @@
       <field type="uint8_t" name="percent_remaining" units="%" invalid="UINT8_MAX">Remaining battery energy. Values: [0-100], UINT8_MAX: field not provided.</field>
       <field type="uint32_t" name="status_flags" display="bitmask" enum="MAV_BATTERY_STATUS_FLAGS">Fault, health, readiness, and other status indications.</field>
     </message>
-    <message id="396" name="COMPONENT_INFORMATION_BASIC">
-      <description>Basic component information data. Should be requested using MAV_CMD_REQUEST_MESSAGE on startup, or when required.</description>
-      <field type="uint32_t" name="time_boot_ms" units="ms">Timestamp (time since system boot).</field>
-      <field type="uint64_t" name="capabilities" enum="MAV_PROTOCOL_CAPABILITY" display="bitmask">Component capability flags</field>
-      <field type="uint32_t" name="time_manufacture_s" units="s" invalid="0">Date of manufacture as a UNIX Epoch time (since 1.1.1970) in seconds.</field>
-      <field type="char[32]" name="vendor_name">Name of the component vendor. Needs to be zero terminated. The field is optional and can be empty/all zeros.</field>
-      <field type="char[32]" name="model_name">Name of the component model. Needs to be zero terminated. The field is optional and can be empty/all zeros.</field>
-      <field type="char[24]" name="software_version">Software version. The recommended format is SEMVER: 'major.minor.patch'  (any format may be used). The field must be zero terminated if it has a value. The field is optional and can be empty/all zeros.</field>
-      <field type="char[24]" name="hardware_version">Hardware version. The recommended format is SEMVER: 'major.minor.patch'  (any format may be used). The field must be zero terminated if it has a value. The field is optional and can be empty/all zeros.</field>
-      <field type="char[32]" name="serial_number">Hardware serial number. The field must be zero terminated if it has a value. The field is optional and can be empty/all zeros.</field>
-    </message>
     <message id="414" name="GROUP_START">
       <description>Emitted during mission execution when control reaches MAV_CMD_GROUP_START.</description>
       <field type="uint32_t" name="group_id">Mission-unique group id (from MAV_CMD_GROUP_START).</field>

diff --git a/message_definitions/v1.0/minimal.xml b/message_definitions/v1.0/minimal.xml
@@ -203,6 +203,9 @@
       <entry value="43" name="MAV_TYPE_GENERIC_MULTIROTOR">
         <description>Generic multirotor that does not fit into a specific type or whose type is unknown</description>
       </entry>
+      <entry value="44" name="MAV_TYPE_ILLUMINATOR">
+        <description>Illuminator. An illuminator is a light source that is used for lighting up dark areas external to the sytstem: e.g. a torch or searchlight (as opposed to a light source for illuminating the system itself, e.g. an indicator light).</description>
+      </entry>
     </enum>
     <enum name="MAV_MODE_FLAG" bitmask="true">
       <description>These flags encode the MAV mode.</description>
@@ -695,6 +698,9 @@
       <entry value="242" name="MAV_COMP_ID_TUNNEL_NODE">
         <description>Component handling TUNNEL messages (e.g. vendor specific GUI of a component).</description>
       </entry>
+      <entry value="243" name="MAV_COMP_ID_ILLUMINATOR">
+        <description>Illuminator</description>
+      </entry>
       <entry value="250" name="MAV_COMP_ID_SYSTEM_CONTROL">
         <deprecated since="2018-11" replaced_by="MAV_COMP_ID_ALL">System control does not require a separate component ID. Instead, system commands should be sent with target_component=MAV_COMP_ID_ALL allowing the target component to use any appropriate component id.</deprecated>
         <description>Deprecated, don't use. Component for handling system messages (e.g. to ARM, takeoff, etc.).</description>