RFC-0020 dispersion payload

text/0020-dispersion-payload.md

@@ -49,34 +49,51 @@ A procotol can be very difficult to analyze in isolation so I started by creatin
 [x] spot spraying. This happens at the planning level. This protocol supports setting flow rate at specific locations which is enough for spot spraying.
 [x] communication buses might be lossy so protocol must handle failure detection.
 [x] ability to construct a synchronized timestamp across mavlink nodes to account for latency in commands when generating reports
+[x] multiple dispersion devices are connected to the autopilot and need independent control
+[x] a single dispersion device has multiple nozzles that require independent nozzle control
+[x] the user can adjust droplet size on the ground station during a mission to account for changing wind conditions
+[x] a dispersion device could correct flow rate for individual nozzles during turning
+[x] a dispersion device can reduce overspray when intersecting an existing not perpendicular spray line by individually turning off one nozzle at a time
+[x] protocol supports nozzle count of largest existing sprayer with some additional room for expansion
 
 ### Implementation
 
 After reviewing other submissions, I think I might have gone too far down this path but I wanted something complete to get reviewed by industry relevant people in my network before submitting here to the MAVLink community. I created a messages.md file with the full set of message definitions and a microservice.md file detailing how the protocol should work that is submitted with this PR. I have a couple of versions: one with a manager and one without. I used the one without because it is less complex and conveys the same concept.
 
+Every enum that is not a bitmask uses the zero value as a default UNKNOWN value. This, in my experience, results in more robust systems since it is very common to initialize values to zero in the background. Developers can miss this and if zero is a common valid value, the issue often wont surface until late run time. By having a default value that is useless, systems will almost immediately surface an error.
+
+This protocol should at a minimum support the capability of existing systems and then project into the future a little bit to be a timely, durable, and valuable solution. So, this protocol is designed to support a system with multiple dispersion devices and multiple subcomponents on that device. For the sake of this design, we consider a dispersion device to be a system containing one chemical mix and the infrastructure to deliver that to a field. The dipsersion device must have one gateway compute node that is responsible for communicating over a MAVLink interface. In the most simple form, a disperison device could be a microprocessor, tank, esc, motor, and spreader wheel that needs rate assigned at specific GPS locations but it can take on a more complex form factor for large ground based spray systems. These might have multiple feeder tanks with n number of subcomponents allowing independent control of subcomponent droplet size and flow rate to support many powerful features such as spot spraying and turn compenstation.
+
 ### Questions
 
 1. ~~This is a combined protocol for spraying and spreading since there are many common elements. Should this be split up?~~
 1. ~~For any kind of effective reporting, not only do the messages needs to be defined but there should also be a degree of standardization on how that information gets logged so utilities can interact with it. Making logging suggestions seemed out of scope here but is there anything I should add to nudge people in the right direction?~~
 1. ~~Is a dispersion manager needed? I genuinely believe the source should not matter. Anything should be able to send a request and it get processed in the order it is received. The only time any prioritization should occur is manual triggers vs automated. No this could be handled through a manager but it is pretty easy implement with just the deivce using the MANUAL vs AUTO request type. I also expect there to be multiple possible viable sources for manual on/off live at any given moment. All should be immediately respected. I feel like the overhead with a manager only allowign two control sources could make this over complicated.~~
 1. Am I missing any critical workflows or test cases? Ie Debug level motor controller and motor information (deemed out of scope, should be a separate protocol for general motor controller and motor information)
-1. should we encourage using something like the parameter protocol rather than a command message for configuration?
+1. ~~should we encourage using something like the parameter protocol rather than a command message for configuration?~~
+1. with the device and device component architecture should I switch to manager/device concept
+1. with the device and device component sharing a message definition should I use FUEL_STATUS to handle fill level since it is only relevant to the device and not subcomponents?
 
 ### Tentative Decisions
 
-1. the combined protocol makes sense with the addition of an enum indicating type in the relevant messages
+1. this protocol supports the current state of aerial and ground spray systems
+1. the protocol will combine spreader and sprayer into one with the addition of an enum indicating dispersion type in the relevant messages
 1. dispersion payloads will be implemented as standalone MAVLink devices
 1. a logging infrastructure is proposed
 1. a dispersion manager will not be used
-1. eliminate request message in favor of mav command infrastructure
+1. eliminated request message in favor of mav command infrastructure
+1. the parameter protocol will be used for configuration since supporting devices with multiple independent sub components significant increased configuration overhead
+1. unix timestamps will be used where possible to ensure accurate reporting on dispersion quality
+1. switched status flags and error flags bitmask to continuous enums since almost all of the time the flags would be mutually exclusive. It is worth the size reduction. If multiple codes do happen at the same time, it is common to combine them into a unqiue enum or oscillate between the codes on publish. Warning flags were left as a bit mask since they dont block operation and can be ignored. This makes multiple overlapping warnings likely.
 
 ## Alternatives
 
 1. Do nothing. Solutions are already evolving organically. While the problem will be solved, it is subject to the issues documented in the motivation section.
-1. Create documentation on how to use the generic payload messaging infrastructure to accomplish this goal. (I think this will lose a lot of critical information)
+1. Create documentation on how to use the generic payload messaging infrastructure to accomplish this goal. [ArduPilot Crop Sprayer](https://ardupilot.org/copter/docs/sprayer.html)
 
 ## References
 
+- ISOBUS (HSI) Agriculture Comm Standards: https://www.aef-online.org/about-us/activities/high-speed-isobus.html
 - Pix4D Spot Spraying Article: https://www.pix4d.com/blog/variable-rate-application-wheat-field/
 - Aerial Applicator's Manual: https://www.epa.gov/system/files/documents/2023-11/national-aerial-applicator-manual-2014.pdf
 - MAVLink Gimbal Protocol: https://mavlink.io/en/services/gimbal_v2.html
@@ -86,3 +103,10 @@ After reviewing other submissions, I think I might have gone too far down this p
 - Rotor: https://rotor.ai/
 - Guardian Agriculture: https://guardian.ag/
 - PYKA: https://www.flypyka.com/
+- TeeJet Dynajet: https://www.teejet.com/precision-farming/application-control-and-monitoring/dynajet
+- TeeJet Precision Ag Products: https://www.farmco.com/price%20lists/teejet/2024%2009-01%20teejet%20precision%20picture%20price.pdf
+- CPNozzles Accuflow: https://www.cpnozzles.com/products/accu-flo-nozzles/
+
+## TODO
+
+1. um (micron) should be added as an allowed xml unit