Summary
This proposal makes two longstanding conventions about Read requests explicit in Device.md: that the request carries an empty Payload, and that it MUST NOT set the ExtendedLength flag introduced by #218. Both are documentation-only changes; no device or client behaviour is affected.
Motivation
Both conventions are followed in practice by every existing Harp client and device, but neither is stated explicitly in the prose of Device.md.
The Read Message example shows the request as:
[REQ] Controller: 1 4 Address Port PayloadType Checksum
The Length value of 4 implies an empty Payload, but a reader who is not already familiar with the protocol has to deduce this from the example layout rather than read it as a stated requirement. Codegen authors and new contributors landing on the spec for the first time have flagged this as an ambiguity.
The second convention, about the ExtendedLength flag, becomes relevant once the binary protocol gains the flag through #218. A Read request carries no payload and therefore has no use for the extended framing; setting the flag would add 6 bytes of overhead (3 for the wider Length field plus 3 additional for the wider CRC-32 Checksum) for no benefit, and would create ambiguity about whether the device should treat the request as something other than a plain read.
Detailed Design
Two additions to the prose of Device.md, both in the Request-Reply section.
Read requests carry an empty payload
Add to the prose preceding the Read Message example:
A Read request from the Controller MUST contain an empty Payload field, regardless of the register's declared PayloadType. The request Length is therefore fixed at the number of bytes required by the message header and trailing checksum, independent of the register being read.
This makes the rule explicit without changing the wire format. The existing Read Message example continues to illustrate the rule.
Read requests do not use ExtendedLength framing
Add to the same section, after the empty-payload sentence:
A Read request MUST NOT set the ExtendedLength flag in MessageType, regardless of the register being read. Since the request carries no payload, the extended Length and Checksum fields would add overhead for no benefit, and the request remains compact enough to fit within regular framing in every case.
This convention applies once the binary protocol gains the ExtendedLength flag specified in #218.
Drawbacks
None substantial. The conventions are already followed by every implementation. The change is documentation only and adds no constraints that are not already operative.
Alternatives
Leave the conventions implicit
Reading the existing Read Message example carefully implies both rules: the example shows no Payload for the request, and the ExtendedLength flag does not appear because the framing in the example is the regular one. We could rely on the example alone.
Rejected because the spec uses RFC 2119 keywords throughout and is meant to be readable as a normative document, not derived from worked examples. A future reader scanning the prose for "MUST", "MUST NOT", and "SHOULD" would not find these rules and might encode them differently in a new client or device. Codegen pipelines, in particular, are easier to maintain when every constraint they enforce is grounded in a normative statement.
Bundle the second convention into the Device.md blob-register conventions PR
The second convention only makes sense once the ExtendedLength flag exists, and the related Device.md blob-register conventions issue (linked below) is the natural home for many similar device-operation rules. We could file the empty-payload clarification standalone and place the ExtendedLength flag rule in the larger PR.
Rejected because both conventions concern Read request shape specifically and read naturally as one paragraph. Keeping them together avoids fragmenting closely related rules across two PRs.
Unresolved Questions
None.
Related Issues
Design Meetings
To be populated as this proposal progresses through SRM.
Summary
This proposal makes two longstanding conventions about
Readrequests explicit inDevice.md: that the request carries an emptyPayload, and that it MUST NOT set theExtendedLengthflag introduced by #218. Both are documentation-only changes; no device or client behaviour is affected.Motivation
Both conventions are followed in practice by every existing Harp client and device, but neither is stated explicitly in the prose of
Device.md.The Read Message example shows the request as:
The
Lengthvalue of4implies an emptyPayload, but a reader who is not already familiar with the protocol has to deduce this from the example layout rather than read it as a stated requirement. Codegen authors and new contributors landing on the spec for the first time have flagged this as an ambiguity.The second convention, about the
ExtendedLengthflag, becomes relevant once the binary protocol gains the flag through #218. AReadrequest carries no payload and therefore has no use for the extended framing; setting the flag would add 6 bytes of overhead (3 for the widerLengthfield plus 3 additional for the wider CRC-32Checksum) for no benefit, and would create ambiguity about whether the device should treat the request as something other than a plain read.Detailed Design
Two additions to the prose of
Device.md, both in theRequest-Replysection.Read requests carry an empty payload
Add to the prose preceding the Read Message example:
This makes the rule explicit without changing the wire format. The existing Read Message example continues to illustrate the rule.
Read requests do not use ExtendedLength framing
Add to the same section, after the empty-payload sentence:
This convention applies once the binary protocol gains the
ExtendedLengthflag specified in #218.Drawbacks
None substantial. The conventions are already followed by every implementation. The change is documentation only and adds no constraints that are not already operative.
Alternatives
Leave the conventions implicit
Reading the existing Read Message example carefully implies both rules: the example shows no
Payloadfor the request, and theExtendedLengthflag does not appear because the framing in the example is the regular one. We could rely on the example alone.Rejected because the spec uses RFC 2119 keywords throughout and is meant to be readable as a normative document, not derived from worked examples. A future reader scanning the prose for "MUST", "MUST NOT", and "SHOULD" would not find these rules and might encode them differently in a new client or device. Codegen pipelines, in particular, are easier to maintain when every constraint they enforce is grounded in a normative statement.
Bundle the second convention into the Device.md blob-register conventions PR
The second convention only makes sense once the
ExtendedLengthflag exists, and the related Device.md blob-register conventions issue (linked below) is the natural home for many similar device-operation rules. We could file the empty-payload clarification standalone and place theExtendedLengthflag rule in the larger PR.Rejected because both conventions concern
Readrequest shape specifically and read naturally as one paragraph. Keeping them together avoids fragmenting closely related rules across two PRs.Unresolved Questions
None.
Related Issues
Design Meetings
To be populated as this proposal progresses through SRM.