From ae0a7214ce6e49445487f20a8ec5a44ad03f9f96 Mon Sep 17 00:00:00 2001 From: bruno-f-cruz <7049351+bruno-f-cruz@users.noreply.github.com> Date: Tue, 9 Apr 2024 19:04:19 -0700 Subject: [PATCH 1/3] Clarify request-reply contract --- BinaryProtocol-8bit.md | 46 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 42 insertions(+), 4 deletions(-) diff --git a/BinaryProtocol-8bit.md b/BinaryProtocol-8bit.md index 7fe97a2..e2e04b3 100644 --- a/BinaryProtocol-8bit.md +++ b/BinaryProtocol-8bit.md @@ -255,7 +255,9 @@ else ### Commands -The device that implements this Harp Protocol receives `Write` and `Read` commands from the controller, and replies with a copy of the message, timestamped with the hardware time at which the command was applied. +The device that implements this Harp Protocol receives `Write` and `Read` commands from the controller, and replies with a copy of the message, timestamped with the hardware time at which the command was applied. This behavior is core to the protocol and is expected to be implemented by all devices that use it. As a rule of thumb, for each `Write` or `Read` command, a single reply message should be returned from the device. The message should be emitted from the same register that the command was issued to. It should be noted that the payload of the returned value might be different from the one issued by the command, as the device can operate/transform the issued `Write` command. ([see "Register Polymorphism" section below](#register-polymorphism)). + +> Exceptions to the previous contract are possible but should be avoided. The single supported exception is the `R_OPERATION_CTRL` (via **DUMP [Bit 3]**) that allows the controller to request a dump of all registers in the device. In this case, the device should reply with a single `Write` message from `R_OPERATION_CTRL`, honoring the previous contract, but will it also emit a volley of `Read` messages, one for each register in the device. Some Harp Messages are shown below to demonstrate the typical usage of the protocol between a device and a controller. Note that timestamp information is usually omitted in messages sent from the controller to the device, since actions are expected to run as soon as possible. @@ -273,7 +275,7 @@ We will use the following abbreviations: The timestamp information in the [RPL] represents the time when the register with [Address] was updated. -### Read Message +#### Read Message - [CMD] **Controller**: `1` `4` `Address` `Port` `PayloadType` `Checksum` - [RPL] **Device**: `1` `Length` `Address` `Port` `PayloadType` `Timestamp` `Checksum` OK @@ -281,12 +283,44 @@ The timestamp information in the [RPL] represents the time when the register wit The timestamp information in the [RPL] represents the time when the register with [Address] was read. -### Event message +#### Event message - [EVT] **Device**: `3` `Length` `Address` `Port` `PayloadType` `Timestamp` `Checksum` OK The timestamp information in [EVT] represents the time when the register with [Address] was read. +### Intended Usage + +#### Register polymorphism + + +While it is possible to have different types of data in the same register, we **STRONGLY** discourage this practice. The protocol was designed to be as simple as possible, and having different types of data in the same register would make the parsing of the messages unnecessary more complex. As a rule, each register should: (1) have a single data type (e.g. `U8`) for all message types (`Read`, `Write`, `Event`), (2) the payload should have the same "function"/"meaning" regardless of the message type (see examples below), and (3) the payload data should be of the same size for all message types. +It should be noted that this guide doesnt necessarly mean that the payload issued by a `Write` message should be the same as the one issued by a `Read` message, as the device can operate/transform the issued `Write`. + + +> **Examples** +> +> Consider the following register: +> +>``` +> CameraFrequency: +> - Address: 32 +> - Type: U8 +> - Access: Raad, Write +> - Description: Sets the frequency of the camera in Hz. +>``` +> +> DO NOT ❌ +> +> - Return the frequency in U16 for a `Read` command and the frequency in U8 for a `Write` command. (i.e. Share the same data type.) +> - Return the frequency in Hz for a `Read` command and the period in seconds for a `Write` command. (i.e. share the same function/meaning.) +> +> DO ✅ +> +> - Return the frequency in U8 for both a `Read` and `Write` command. +> - Return the frequency in Hz for both a `Read` and a `Write` command. +> - `Write` a value of `101` to set the frequency, but both `Read` and `Write` return the frequency of 100Hz. This behavior is perfectly acceptable as the device might not be able to set the frequency to the exact value requested by the controller, and instead returns the value that was set. + --- ## Release notes: @@ -323,4 +357,8 @@ The timestamp information in [EVT] represents the time when the register with [A - v1.4.1 * Remove table of contents to avoid redundancy with doc generators. * Avoid using verbatim literals in titles. - * Change device naming to Controller and Device. \ No newline at end of file + * Change device naming to Controller and Device. + +- v1.4.2 + * Clarify request-reply contract. + * Discourage the use of polymorphic register behavior. \ No newline at end of file From 34f8526ec2e1a1accfc6e02dd0622f3b066d0097 Mon Sep 17 00:00:00 2001 From: brunocruz <7049351+bruno-f-cruz@users.noreply.github.com> Date: Tue, 23 Apr 2024 11:07:51 -0700 Subject: [PATCH 2/3] Correct typo --- BinaryProtocol-8bit.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/BinaryProtocol-8bit.md b/BinaryProtocol-8bit.md index e2e04b3..4deb4df 100644 --- a/BinaryProtocol-8bit.md +++ b/BinaryProtocol-8bit.md @@ -306,7 +306,7 @@ It should be noted that this guide doesnt necessarly mean that the payload issue > CameraFrequency: > - Address: 32 > - Type: U8 -> - Access: Raad, Write +> - Access: Read, Write > - Description: Sets the frequency of the camera in Hz. >``` > From ad1e1d449f0f91623cafd52f25c97f5dc279a055 Mon Sep 17 00:00:00 2001 From: brunocruz <7049351+bruno-f-cruz@users.noreply.github.com> Date: Tue, 23 Apr 2024 11:08:04 -0700 Subject: [PATCH 3/3] Update BinaryProtocol-8bit.md Clarify language --- BinaryProtocol-8bit.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/BinaryProtocol-8bit.md b/BinaryProtocol-8bit.md index 4deb4df..c1b67e3 100644 --- a/BinaryProtocol-8bit.md +++ b/BinaryProtocol-8bit.md @@ -255,7 +255,7 @@ else ### Commands -The device that implements this Harp Protocol receives `Write` and `Read` commands from the controller, and replies with a copy of the message, timestamped with the hardware time at which the command was applied. This behavior is core to the protocol and is expected to be implemented by all devices that use it. As a rule of thumb, for each `Write` or `Read` command, a single reply message should be returned from the device. The message should be emitted from the same register that the command was issued to. It should be noted that the payload of the returned value might be different from the one issued by the command, as the device can operate/transform the issued `Write` command. ([see "Register Polymorphism" section below](#register-polymorphism)). +The device that implements this Harp Protocol receives `Write` and `Read` commands from the controller, and replies with a message from the same address and same type, timestamped with the hardware time at which the command was applied. This behavior is core to the protocol and is expected to be implemented by all devices that use it. As a rule of thumb, for each `Write` or `Read` command, a single reply message should be returned from the device. The message should be emitted from the same register that the command was issued to. It should be noted that the payload of the returned value might be different from the one issued by the command, as the device can operate/transform the issued `Write` command. ([see "Register Polymorphism" section below](#register-polymorphism)). > Exceptions to the previous contract are possible but should be avoided. The single supported exception is the `R_OPERATION_CTRL` (via **DUMP [Bit 3]**) that allows the controller to request a dump of all registers in the device. In this case, the device should reply with a single `Write` message from `R_OPERATION_CTRL`, honoring the previous contract, but will it also emit a volley of `Read` messages, one for each register in the device.