Discourage polymorphic behavior (Discourage register polymorphic behavior #26)

Author: bruno-f-cruz

BinaryProtocol-8bit.md

@@ -107,7 +107,7 @@ If the bit is set, indicates that the [`Payload`] contains integers with signal.
 
 ### 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.
+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)).
 
 > **Note**
 >
@@ -129,20 +129,51 @@ 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<T>` `Checksum`       OK
 - [RPL] **Device**: `9` `10`     `Address` `Port` `PayloadType` `Timestamp<T>` `Checksum`        ERROR
 
 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<T>` `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:
@@ -182,4 +213,5 @@ The timestamp information in [EVT] represents the time when the register with [A
   * Change device naming to Controller and Device.
 
 - v1.4.2
-  * Clarify request-reply contract.
+  * Clarify request-reply contract.
+  * Discourage the use of polymorphic register behavior.