search

harp-tech / protocol

Description of the Harp protocol.
https://harp-tech.org/protocol/BinaryProtocol-8bit.html
MIT License
3 stars 5 forks source link

Discourage register polymorphic behavior #26

Open bruno-f-cruz opened 6 months ago

bruno-f-cruz commented 6 months ago

Summary

Most of the app register's functionality that has been implemented to date relies on an assumption that, as far as I can tell, is not described in the protocol. Each register, regardless of the message type (i.e. READ, WRITE, EVENT) always returns the same "data", ideally the latest value kept in said register. This is essential from the host side as returns from the device can simply be interpreted as "READS" (i.e. WRITE messages are reads after setting a value, EVENT and READ are reads of a register without/with a requests, respectively) and piped through the same pipeline and parsed using the interface.

Motivation

A couple of edge cases that violate this assumption have surfaced and I think we should either 1: accept them or 2: make sure the protocol/standard is explicit on this behavior.

Detailed Design

My proposal is to actively discourage this polymorphic behavior by adding the following language to the protocol:

"Every payload returned from a given register must have the same datatype, length and always return the value of that register, regardless of the message type being returned. If a computation is required to be made on top of the register value for a specific message type. that will not be kept in the register's value, this event should be implemented in a second register"

Drawbacks

If we indeed want to allow polymorphic behavior per register this would effectively make that impossible

Alternatives

Not doing this will make users learn more app-specific edge cases and might break the automatically generated interfaces for some devices

Unresolved Questions

N\A

Design Meetings

TBD

bruno-f-cruz commented 3 months ago

Additionally, although obvious, we should make it very clear that registers not only share the same "function" or "behavior" but also payload structure (e.g. data type, payload size, etc...).

bruno-f-cruz commented 2 months ago

Add to the protocol: Examples of what to do (use frequency/period as an example) / what not to do (use camera frequency set and possible) Concept of "units" or "quantity" the thing they represent Make sure to add that register have the same data type and length regardless of message type

bruno-f-cruz commented 2 months ago

Related to #9