Ping protocol message definitions

[EliotBR (Eliot)]

Hi @psupine,

For some context here, ping protocol is intended as a means of collaboration between device designers (who aren’t directly working together) and interfacing software developers (who may have no connection to the device designers / firmware developers).

I’ve just touched on this in my latest response in your Ping1D firmware thread, but the protocol started out with message sets relevant for two specific devices, and has expanded from there largely at the whims of device designers, without much consideration for cross-device consistency. I consider it in need of a cleanup, so it can better serve as a unifying protocol, ideally without redundancy, and fully supportive of new features which may not yet be implemented.

@psupine

• message 5 has the protocol version as [u8]:[u8]:[u8].

The protocol version is intended to capture updates, but is challenging to increment in a synchronised fashion with changes in individual message sets, especially since firmware versions (which currently need to report the protocol version they support) may be released before official support for their new features is recognised in the protocol.

I believe it got updated to v1.1.0 to reflect some updates in the ping360 message set, but beyond that I don’t believe it has been meaningfully updated or accounted for in existing software or firmware - changes have just been made in firmware releases and eventually trickled into the protocol so they can be supported in the official versions of the available libraries and the like.

@psupine

message 1200 has device type [u8] and device model [u8] that both seem to be covered by the dev_type field from common message 4

There is indeed some redundancy in the device type field, although the device model (e.g. Ping Sonar) and device revision (e.g. original variant) are principally distinct, so the messages aren’t completely identical. That said, I don’t expect fields other than the device type to be particularly meaningful (or adhered to) at the moment

@psupine

• message 1200 also has the firmware version, but this time as a [u16]:[u16], so the major and minor fields can takes on unlikely large values and patch field is absent.

I’m not sure why the common one wasn’t just used for this, since the extra number range seems unnecessary, and the patch field can actually be meaningful in some instances (although it’s yet to be used in Ping Sonar firmware). I’d be inclined to just use the common one (4) for this, although it’s worth at least a cursory check that the devices you’re explicitly supporting actually implement the message.

@psupine

All I really need to know is how much I need to read to ensure that the driver can recognise when it should be allowed to talk to the device that is plugged in and when it should instead report a compatibility error.

Right now the key components would be:

• device type
  • if unknown, maybe provide a warning that it’s likely unsupported, even if you then allow the driver to try to perform its other functions?
• protocol version
  • if major > 1 then expect it doesn’t work and raise an error, and if minor > 1 then maybe provide a warning that some new protocol features may not be supported?