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/9] 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/9] 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/9] 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. From a5736c9db60b817b18883f8aed8b9dbfeaeac856 Mon Sep 17 00:00:00 2001 From: brunocruz <7049351+bruno-f-cruz@users.noreply.github.com> Date: Sun, 5 Jan 2025 20:30:57 -0800 Subject: [PATCH 4/9] Clarify language of the read-dump procedure Co-authored-by: glopesdev --- BinaryProtocol-8bit.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/BinaryProtocol-8bit.md b/BinaryProtocol-8bit.md index c1b67e3..73e0649 100644 --- a/BinaryProtocol-8bit.md +++ b/BinaryProtocol-8bit.md @@ -257,7 +257,7 @@ else 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. +> Exceptions to the previous contract are possible but should be avoided. The single supported exception is the `R_OPERATION_CTRL` register (via **DUMP [Bit 3]**) which allows the controller to request a dump of all registers in the device. In this case, the device replies with a single `Write` message from `R_OPERATION_CTRL`, honoring the above contract, but it will also emit a sequence of `Read` messages back-to-back, containing the state of 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. From f598f38ca2a1de48073023b5122877d4a7f6776a Mon Sep 17 00:00:00 2001 From: brunocruz <7049351+bruno-f-cruz@users.noreply.github.com> Date: Sun, 5 Jan 2025 20:34:37 -0800 Subject: [PATCH 5/9] Correct minor typos and improve clarity Co-authored-by: glopesdev --- BinaryProtocol-8bit.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/BinaryProtocol-8bit.md b/BinaryProtocol-8bit.md index 73e0649..7da9269 100644 --- a/BinaryProtocol-8bit.md +++ b/BinaryProtocol-8bit.md @@ -294,7 +294,7 @@ The timestamp information in [EVT] represents the time when the register with [A #### 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. +While it is technically 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 unnecessarily 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) have a payload with the same "function"/"meaning" regardless of the message type (see examples below), and (3) have the same payload size for all message types coming from the device. 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`. From c64d3f6bb3823ce6bf9ff80504d8ed503baa6d62 Mon Sep 17 00:00:00 2001 From: brunocruz <7049351+bruno-f-cruz@users.noreply.github.com> Date: Sun, 5 Jan 2025 20:36:46 -0800 Subject: [PATCH 6/9] Improve clarity Co-authored-by: glopesdev --- BinaryProtocol-8bit.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/BinaryProtocol-8bit.md b/BinaryProtocol-8bit.md index 7da9269..16a8117 100644 --- a/BinaryProtocol-8bit.md +++ b/BinaryProtocol-8bit.md @@ -295,7 +295,7 @@ The timestamp information in [EVT] represents the time when the register with [A While it is technically 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 unnecessarily 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) have a payload with the same "function"/"meaning" regardless of the message type (see examples below), and (3) have the same payload size for all message types coming from the device. -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`. +It should be noted that this recommendation does not require 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** From 17451d997a68a45458e047104d87ff43434ad79f Mon Sep 17 00:00:00 2001 From: brunocruz <7049351+bruno-f-cruz@users.noreply.github.com> Date: Sun, 5 Jan 2025 20:38:46 -0800 Subject: [PATCH 7/9] Reformat to follow Bonsai Do/Dont list format Co-authored-by: glopesdev --- BinaryProtocol-8bit.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/BinaryProtocol-8bit.md b/BinaryProtocol-8bit.md index 16a8117..2edc129 100644 --- a/BinaryProtocol-8bit.md +++ b/BinaryProtocol-8bit.md @@ -310,16 +310,12 @@ It should be noted that this recommendation does not require that the payload is > - Description: Sets the frequency of the camera in Hz. >``` > -> DO NOT ❌ +> ❌ 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.) +> ❌ DO NOT 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.) > -> - 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. +> ✅ DO return the frequency in U8 for both a `Read` and `Write` command. +> ✅ DO return the frequency in Hz for both a `Read` and a `Write` command. +> ✅ DO allow writing 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. --- From c79f7f8e6359c0cf497f8bd936034f1be25950f4 Mon Sep 17 00:00:00 2001 From: brunocruz <7049351+bruno-f-cruz@users.noreply.github.com> Date: Thu, 9 Jan 2025 14:36:57 -0800 Subject: [PATCH 8/9] Improve clarity Co-authored-by: glopesdev --- BinaryProtocol-8bit.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/BinaryProtocol-8bit.md b/BinaryProtocol-8bit.md index 2edc129..6df0d7d 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 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)). +The device that implements this Harp Protocol receives `Write` and `Read` commands from the controller. As a rule of thumb, for each `Write` and `Read` command, a single reply message should be returned from the device with the same register address and register type, timestamped with the hardware time at which the command was evaluated. This behavior is fundamental to the protocol and is expected to be implemented by all Harp devices. + +It should be noted that the payload of the returned value might be different from the one issued by a `Write` command, as the device may have to transform or adapt the actual value written on the register. ([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` register (via **DUMP [Bit 3]**) which allows the controller to request a dump of all registers in the device. In this case, the device replies with a single `Write` message from `R_OPERATION_CTRL`, honoring the above contract, but it will also emit a sequence of `Read` messages back-to-back, containing the state of each register in the device. @@ -294,8 +296,14 @@ The timestamp information in [EVT] represents the time when the register with [A #### Register polymorphism -While it is technically 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 unnecessarily 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) have a payload with the same "function"/"meaning" regardless of the message type (see examples below), and (3) have the same payload size for all message types coming from the device. -It should be noted that this recommendation does not require 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`. +While it is technically 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 unnecessarily more complex. + +As a general rule, each register should: + 1. have a single data type (e.g. `U8`) for all message types (`Read`, `Write`, `Event`), + 2. have a payload with the same functional semantics regardless of the message type (see examples below), and + 3. have the same payload size for all message types coming from the device. + +It should be noted that this recommendation does not require that the payload issued by a `Write` message be the same as the one issued by a `Read` message, as the device may have to transform or update the actual value stored in the register. > **Examples** @@ -315,7 +323,7 @@ It should be noted that this recommendation does not require that the payload is > > ✅ DO return the frequency in U8 for both a `Read` and `Write` command. > ✅ DO return the frequency in Hz for both a `Read` and a `Write` command. -> ✅ DO allow writing 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. +> ✅ DO allow writing a value of `101` to set the frequency even if both `Read` and `Write` replies will only 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. --- From 47eac57c0c6be10c5d2d49048c38f9eaf41f8ed9 Mon Sep 17 00:00:00 2001 From: brunocruz <7049351+bruno-f-cruz@users.noreply.github.com> Date: Thu, 9 Jan 2025 16:04:28 -0800 Subject: [PATCH 9/9] Fix minor typo Co-authored-by: glopesdev --- BinaryProtocol-8bit.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/BinaryProtocol-8bit.md b/BinaryProtocol-8bit.md index 6df0d7d..49f8431 100644 --- a/BinaryProtocol-8bit.md +++ b/BinaryProtocol-8bit.md @@ -257,7 +257,7 @@ else The device that implements this Harp Protocol receives `Write` and `Read` commands from the controller. As a rule of thumb, for each `Write` and `Read` command, a single reply message should be returned from the device with the same register address and register type, timestamped with the hardware time at which the command was evaluated. This behavior is fundamental to the protocol and is expected to be implemented by all Harp devices. -It should be noted that the payload of the returned value might be different from the one issued by a `Write` command, as the device may have to transform or adapt the actual value written on the register. ([see "Register Polymorphism" section below](#register-polymorphism)). +It should be noted that the payload of the returned value might be different from the one issued by a `Write` command, as the device may have to transform or adapt the actual value written on the register ([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` register (via **DUMP [Bit 3]**) which allows the controller to request a dump of all registers in the device. In this case, the device replies with a single `Write` message from `R_OPERATION_CTRL`, honoring the above contract, but it will also emit a sequence of `Read` messages back-to-back, containing the state of each register in the device.