Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

RFC-0020 dispersion payload #26

Open
wants to merge 21 commits into
base: master
Choose a base branch
from
Open

RFC-0020 dispersion payload #26

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
2c61f53
RFC-0020 dispersion payload
wes-public-apps Feb 18, 2025
f880e74
add pyka reference
wes-public-apps Feb 18, 2025
18de873
address come typos
wes-public-apps Feb 18, 2025
93e51a9
Remove target component and system since this is a broadcast
wes-public-apps Feb 20, 2025
54ee701
v2 - switch to command infrastructure and document as standalone mavl…
wes-public-apps Feb 25, 2025
6202bb5
rename commands to match naming convention per mission microservice
wes-public-apps Feb 25, 2025
18a18fc
add xml definition
wes-public-apps Feb 25, 2025
fd7519f
dispersion on -> active
wes-public-apps Feb 26, 2025
0f41c41
address comments
wes-public-apps Feb 26, 2025
f7a4092
update missed detector reference
wes-public-apps Feb 26, 2025
bfe8b6a
update logging format to be consistent with message timestamps. micro…
wes-public-apps Feb 26, 2025
9a7862e
update uuid to be 128bit char
wes-public-apps Feb 26, 2025
ff51a20
update logging format
wes-public-apps Feb 27, 2025
8f050db
Add support for COMPONENT_BASIC_INFORMATION
wes-public-apps Feb 27, 2025
18adb1c
v3 major changes to support ground rig systems with independent nozzl…
wes-public-apps Mar 4, 2025
6f046cf
check off test cases
wes-public-apps Mar 4, 2025
9ced6ce
minor cleanup
wes-public-apps Mar 4, 2025
e56be8e
trim excess in status message
wes-public-apps Mar 4, 2025
e5755de
Update lock values
wes-public-apps Mar 4, 2025
5b8735d
remove redundant message definitions
wes-public-apps Mar 5, 2025
95a24f3
Add connected autopilot option to docs.
wes-public-apps Mar 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added dispersion_protocol/configuration_sequence.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added dispersion_protocol/control_sequence.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added dispersion_protocol/discovery_sequence.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
184 changes: 184 additions & 0 deletions dispersion_protocol/dispersion.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,184 @@
<?xml version="1.0"?>
<mavlink>
<include>standard.xml</include>
<version>3</version>
<dialect>0</dialect>
<enums>
<!-- From minimal.xml -->
<enum name="MAV_TYPE">
<description>MAVLINK component type reported in HEARTBEAT message. Flight controllers must report the type of the vehicle on which they are mounted (e.g. MAV_TYPE_OCTOROTOR). All other components must report a value appropriate for their type (e.g. a camera must use MAV_TYPE_CAMERA).</description>
<entry value="45" name="MAV_TYPE_DISPERSION">
<description>A device that can disperse a payload</description>
</entry>
</enum>
<enum name="MAV_COMPONENT">
<description>
Component ids (values) for the different types and instances of onboard hardware/software that might make up a MAVLink system (autopilot, cameras, servos, GPS systems, avoidance systems etc.).
Components must use the appropriate ID in their source address when sending messages. Components can also use IDs to determine if they are the intended recipient of an incoming message. The MAV_COMP_ID_ALL value is used to indicate messages that must be processed by all components.
When creating new entries, components that can have multiple instances (e.g. cameras, servos etc.) should be allocated sequential values. An appropriate number of values should be left free after these components to allow the number of instances to be expanded.
</description>
<entry value="110" name="MAV_COMP_ID_DISPERSION">
<description>Dispersion device #1</description>
</entry>
</enum>
<!-- End from minimal.xml -->
<!-- From common.xml -->
<enum name="DISPERSION_DEVICE_CAP_FLAGS" bitmask="true">
<description>Gimbal device (low level) capability flags (bitmap).</description>
<entry value="1" name="DISPERSION_DEVICE_CAP_FLAGS_SPRAYER">
<description>Device supports dispersing granular payloads.</description>
</entry>
<entry value="2" name="DISPERSION_DEVICE_CAP_FLAGS_SPREADER">
<description>Device supports dispersing liquid payloads.</description>
</entry>
<entry value="4" name="DISPERSION_DEVICE_CAP_FLAGS_DYNAMIC_SPEED_CORRECTIONS">
<description>Device supports varying dispersion rate with speed changes up to provided limits.</description>
</entry>
<entry value="8" name="DISPERSION_DEVICE_CAP_FILL_LEVEL_DETECTION">
<description>Device supports measuring its own fill level.</description>
</entry>
</enum>
<enum name="DISPERSION_DEVICE_STATUS_FLAGS" bitmask="true">
<description>Flags for the dispersion device (lower level) operation. These flags work together to communicate dispersion device state.</description>
<entry value="1" name="DISPERSION_DEVICE_STATUS_FLAGS_DISPERSION_ON">
<description>Dispersion device is delivering payload</description>
</entry>
<entry value="2" name="DISPERSION_DEVICE_STATUS_FLAGS_LOCKED">
<description>Dispersion device is locked and wont respond to control inputs</description>
</entry>
<entry value="4" name="DISPERSION_DEVICE_STATUS_FLAGS_CONFIGURED">
<description>System has necessary parameters to properly disperse payload</description>
</entry>
<entry value="8" name="DISPERSION_DEVICE_STATUS_FLAGS_FILL_AT_TARGET">
<description>Dispersion device tank is filled to target amount</description>
</entry>
</enum>
<enum name="DISPERSION_DEVICE_ERRORS" bitmask="true">
<description>Dispersion device error flags. Any error flag indicates the device has turned off.</description>
<entry value="1" name="DISPERSION_DEVICE_ERRORS_UNKNOWN">
<description>Device has had an unknown error</description>
</entry>
<entry value="2" name="DISPERSION_DEVICE_ERRORS_CLOGGED">
<description>Device is clogged</description>
</entry>
<entry value="4" name="DISPERSION_DEVICE_ERRORS_MOTOR_FAILURE">
<description>Device dispersion motor or pump has failed</description>
</entry>
<entry value="8" name="DISPERSION_DEVICE_ERRORS_IMPROPER_CONFIGURATION">
<description>Device configuration is not compatible with device limits</description>
</entry>
<entry value="16" name="DISPERSION_DEVICE_ERRORS_OVER_SPEED">
<description>System is moving faster than the device can deliver</description>
</entry>
<entry value="32" name="DISPERSION_DEVICE_ERRORS_UNDER_SPEED">
<description>System is moving slower than the device can support</description>
</entry>
<entry value="64" name="DISPERSION_DEVICE_ERRORS_UNEXPECTED_FILL">
<description>Device tank was filled to an unexpected level</description>
</entry>
<entry value="128" name="DISPERSION_DEVICE_ERRORS_NO_CONFIGURATION">
<description>Device was not configured before trying to disperse payload</description>
</entry>
<entry value="256" name="DISPERSION_DEVICE_ERRORS_LEAK">
<description>Device is not maintaining pressure as expected</description>
</entry>
<entry value="512" name="DISPERSION_DEVICE_ERRORS_UNEXPECTED_FLIGHT_BEHAVIOR">
<description>Device detected an unexpected event like a crash</description>
</entry>
</enum>
<enum name="DISPERSION_DEVICE_WARNINGS" bitmask="true">
<description>Dispersion device warning flags. Any warning flag indicates an issue that does not block operation of the device.</description>
<entry value="1" name="DISPERSION_DEVICE_WARNINGS_UNKNOWN">
<description>Device has had an unknown warning</description>
</entry>
<entry value="2" name="DISPERSION_DEVICE_WARNINGS_LOG_FULL">
<description>Device log file has reached its memory limit.</description>
</entry>
<entry value="4" name="DISPERSION_DEVICE_WARNINGS_FILL_LEVEL_DETECTOR_BROKEN">
<description>There is an issue with the fill level detector system.</description>
</entry>
</enum>
<enum name="MAV_DISPERSION_TYPE">
<description>The dispersion type a device is setup for. Dispersion types specify the units for capacity and dispersion rate.</description>
<entry value="0" name="MAV_DISPERSION_TYPE_UNKNOWN">
<description>Not specified</description>
</entry>
<entry value="1" name="MAV_DISPERSION_TYPE_SPRAY">
<description>A generic liquid payload is being dispersed. Units are in Liters for capacity and Liters/min for dispersion rate</description>
</entry>
<entry value="2" name="MAV_DISPERSION_TYPE_SPREAD">
<description>A generic solid payload of granules is being dispersed. Units are in Kg for capacity and Kg/min for dispersion rate</description>
</entry>
</enum>
<enum name="MAV_CMD">
<description>Commands to be executed by the MAV. They can be executed on user request, or as part of a mission script. If the action is used in a mission, the parameter mapping to the waypoint/mission message is as follows: Param 1, Param 2, Param 3, Param 4, X: Param 5, Y:Param 6, Z:Param 7. This command list is similar what ARINC 424 is for commercial aircraft: A data format how to interpret waypoint/mission data. NaN and INT32_MAX may be used in float/integer params (respectively) to indicate optional/default values (e.g. to use the component's current yaw or latitude rather than a specific value). See https://mavlink.io/en/guide/xml_schema.html#MAV_CMD for information about the structure of the MAV_CMD entries</description>
<!-- BEGIN of dispersion device commands-->
<entry value="30010" name="MAV_CMD_DO_CONFIG_DISPERSION_PARAMS" hasLocation="false" isDestination="false">
<description>This command provides the necessary run time information for the dispersion device to support a specific configuration associated with the target dispersion profile.</description>
<param index="1" label="Dispersion Type" enum="MAV_DISPERSION_TYPE">The type of dispersion this device supports. This indicates target units as outlined in enum</param>
<param index="2" label="Reference Speed" units="m/s">The target speed for which any target dispersion rate applies, since the rate should change with speed</param>
<param index="3" label="Dispersion Rate Min" units="liters/min or kg/min">Minimum dispersion rate the current configuration supports</param>
<param index="4" label="Dispersion Rate Max" units="liters/min or kg/min">Maximum dispersion rate the current configuration supports</param>
<param index="5" label="Pressure Min" units="Pa">If this is a spray dispersion system, minimum pressure the current configuration supports</param>
<param index="6" label="Pressure Max" units="Pa">If this is a spray dispersion system, maximum pressure the current configuration supports</param>
<param index="7" label="Target Fill Level" units="liters or kg">Target payload amount for device. This will be ignored if the capability flags do not indicate fill level detection support</param>
</entry>
<entry value="30011" name="MAV_CMD_DO_SET_DISPERSION_RATE" hasLocation="false" isDestination="false">
<description>Command to provide real time adjustment to dispersion device output for a given dispersion profile configured using MAV_CMD_CONFIG_DISPERSION_DEVICE_PARAMS.</description>
<param index="1" label="Timestamp Ns" units="ns">The unix timestamp for message creation</param>
<param index="2" label="Dispersion Type" enum="MAV_DISPERSION_TYPE">The type of dispersion this device supports. This indicates units as outlined in enum</param>
<param index="3" label="Target Dispersion Rate" units="liters/min or kg/min">Target dispersion rate for the system</param>
<param index="4">Empty</param>
<param index="5">Empty</param>
<param index="6">Empty</param>
<param index="7">Empty</param>
</entry>
<entry value="30012" name="MAV_CMD_DO_SET_DISPERSION_LOCK" hasLocation="false" isDestination="false">
<description>Command for locking/unlocking the device from responding to MAV_CMD_SET_DISPERSION_DEVICE_RATE messages. When locked, the device should stop dispersing.</description>
<param index="1" label="Timestamp Ns" units="ns">The unix timestamp for message creation</param>
<param index="2" label="Lock">Stop dispersion and prevent the dispersion device from responding to input for live dispersion rate changes until unlocked. 1 for locked. Otherwise unlocked.</param>
<param index="3">Empty</param>
<param index="4">Empty</param>
<param index="5">Empty</param>
<param index="6">Empty</param>
<param index="7">Empty</param>
</entry>
<!-- END of dispersion device commands -->
</enum>
<!-- End from common.xml -->
</enums>
<messages>
<!-- From common.xml -->
<message id="360" name="DISPERSION_DEVICE_INFORMATION">
<description>Information about a dispersion device. This message should be requested by a source such as the ground control station using MAV_CMD_REQUEST_MESSAGE. The min/max limits are driven by the underlying hardware. Software defined limits will be a subset of the limits specified here.</description>
<field type="uint64_t" name="timestamp_ns" units="ns">Unix time stamp in nanoseconds</field>
<field type="char[32]" name="vendor_name">Name of the payload vendor</field>
<field type="char[32]" name="model_name">Name of the payload model</field>
<field type="char[32]" name="custom_name">Custom name given by the user</field>
<field type="uint32_t" name="firmware_version">Version of the payload firmware, encoded as: (Dev & 0xff) << 24</field>
<field type="uint32_t" name="hardware_version">Version of the payload hardware, encoded as: (Dev & 0xff) << 24</field>
<field type="uint64_t" name="uid">Integer to uniquely identify this hardware. (0 if unknown)</field>
<field type="uint16_t" name="cap_flags" enum="DISPERSION_DEVICE_CAP_FLAGS", display="bitmask">Bitmap of dispersion device capability flags.</field>
<field type="uint16_t" name="custom_cap_flags" display="bitmask">Bitmap for use for dispersion-specific capability flags. flags.</field>
<field type="char[64]" name="logger_dir_ftp_url">File transfer protocol (FTP) url-like string pointing to the directory of log files</field>
<field type="float" name="dispersion_rate_min" units="liters/min or kg/min">Minimum dispersion rate this device can support</field>
<field type="float" name="dispersion_rate_max" units="liters/min or kg/min">Maximum dispersion rate this device can support</field>
<field type="uint32_t" name="pressure_min" units="Pa">If this is a spray dispersion system, minimum pressure the hardware supports independent of nozzle configuration</field>
<field type="uint32_t" name="pressure_max" units="Pa">If this is a spray dispersion system, maximum pressure the hardware supports independent of nozzle configuration</field>
<field type="float" name="max_capacity" units="liters or kg">Maximum fill capacity of this device in Liters for sprayers and Kg for spreaders</field>
</message>
<message id="361" name="DISPERSION_DEVICE_STATUS">
<description>Message reporting the status of a dispersion device. This message should be published at a low regular rate (e.g. 5 Hz) but also during key events such as a mavlink command, flag change, or rapid pressure change.</description>
<field type="uint64_t" name="timestamp_ns" units="ns">Unix time stamp in nanoseconds</field>
<field type="uint32_t" name="dispersion_type", enum="MAV_DISPERSION_TYPE">Dispersion type. Defines units for device capacity and dispersion rate</field>
<field type="uint16_t" name="flags" enum="DISPERSION_DEVICE_STATUS_FLAGS" display="bitmask">Current flags set by the device</field>
<field type="uint32_t" name="failure_flags" enum="DISPERSION_DEVICE_ERRORS" display="bitmask">Bitmap for failure flags (0 for no failure). Any failure indicates the system has stopped</field>
<field type="uint32_t" name="warning_flags" enum="DISPERSION_DEVICE_WARNINGS" display="bitmask">Bitmap for warning flags (0 for no warning)</field>
<field type="uint8_t" name="custom_codes">Leave some flexibility for device manufacturers to pass more information through. This gives up to 255 codes to represent internal system state.</field>
<field type="float" name="dispersion_rate" units="liters/min or kg/min">Current dispersion rate of the device. Negative during refill.</field>
<field type="uint16_t" name="fill_level" units="liters or kg">Current tank fill level. This field should be ignored if the device capability flags indicate fill level detection is not supported.</field>
<field type="uint32_t" name="pressure" units="Pa">Current pressure of the dispersion system if dispersion type indicates it is a sprayer</field>
</message>
<!-- End from common.xml -->
</messages>
</mavlink>
Binary file added dispersion_protocol/hardware_config.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading