Clarify request-reply contract

Author: bruno-f-cruz

BinaryProtocol-8bit.md

@@ -104,158 +104,14 @@ This bit indicates whether the [`Payload`] represents fractional values. If the
 
 If the bit is set, indicates that the [`Payload`] contains integers with signal.
 
-> **Note**
->
-> The bits [`IsFloat`] and [`IsSigned`] must never be set simultaneously.
-
-### Payload (? bytes)
-
-The content of the Harp Message.
-
-If the [`HasTimestamp`] flag is set, the following optional fields are present at the beginning of the message payload:
-
-#### Seconds (4 bytes)
 
-Contains the number of seconds (`U32`) of the Harp Timestamp clock. This field is optional. In order to indicate that this field is available, the bit [`HasTimestamp`] in the field [`PayloadType`] needs to be set.
-
-#### Microseconds (2 bytes)
-
-It contains the fractional part of the Harp Timestamp clock in microseconds (`U16` containing the number of microseconds divided by 32).
+### Commands
 
-This field is optional. In order to indicate that this field is available, the bit [`HasTimestamp`] in the field [`PayloadType`] needs to be set.
+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.
 
 > **Note**
 >
-> The full timestamp information can thus be retrieved using the formula:
-> Timestamp(s) = [`Seconds`] + [`Microseconds`] * 32 * 10-6
-
-### Checksum (1 byte)
-
-The sum of all bytes (`U8`) contained in the Harp Message.
-The receiver of the message should calculate the checksum and compare it with the received. If they don’t match, the Harp Message should be discarded.
-
----
-
-## Features and Code Examples
-
-Some of the fields described on the previous chapter have special features. These are presented next.
-
-### MessageType and ErrorFlag
-
-The field [`Command`] has an Error flag on the 4th least significant bit. When this bit is set it means that an error has occured.
-Examples of possible errors cane be:
-
-  1. The controller tries to read from a register that doesn’t exist;
-  2. The controller tries to write invalid data to a certain register;
-  3. The [`PayloadType`] doesn’t match the target register specification.
-
-A simple code in C to check for error will be:
-
-```C
-    int errorMask = 0x08;
-
-    if (Command & errorMask)
-    {
-    printf(“Error detected.\n”);
-    }
-```
-
-### Harp Message Length
-
-If one byte is not enough to express the length of the Harp Message, use [`Length`] equal to 255 and add after an unsigned 16 bits word with the Harp Message length.
-
-Replace the [`Length`] with:
-    [255] (1 byte) [`ExtendedLength`] (2 bytes)
-
-### Parsing PayloadType
-
-For the definition of the `PayloadType` types, a `C#` code snippet is presented.
-
-Note that the time information can appear without an element Timestamp<>.
-
-```C#
-  int isUnsigned = 0x00;
-  int isSigned = 0x80;
-  int isFloat = 0x40;
-  int hasTimestamp = 0x10;
-
-  enum PayloadType 
-  {
-      U8  = (isUnsigned | 1),
-      S8  = (isSigned   | 1),
-      U16 = (isUnsigned | 2),
-      S16 = (isSigned   | 2),
-      U32 = (isUnsigned | 4),
-      S32 = (isSigned   | 4),
-      U64 = (isUnsigned | 8),
-      S64 = (isSigned   | 8),
-      Float = (isFloat  | 4),
-      Timestamp = hasTimestamp,
-      TimestampedU8  = (hasTimestamp | U8),
-      TimestampedS8  = (hasTimestamp | S8),
-      TimestampedU16 = (hasTimestamp | U16),
-      TimestampedS16 = (hasTimestamp | S16),
-      TimestampedU32 = (hasTimestamp | U32),
-      TimestampedS32 = (hasTimestamp | S32),
-      TimestampedU64 = (hasTimestamp | U64),
-      TimestampedS64 = (hasTimestamp | S64),
-      TimestampedFloat = (hasTimestamp | Float)
-  }
-```
-
-The field `PayloadType` has a flag on the 5th least significant bit that indicates if the time information is available on the Harp Message. The existence of this flag is useful to know if the fields [`Seconds`] and [`Microseconds`] are present on the Harp Message.
-In `C` one can check if the time information is avaible by using the following snippet:
-
-```C
-int hasTimestamp = 0x10;
-
-if (PayloadType &  hasTimestamp )
-{
-    printf(“The time information is available on the Harp Message’s Payload.\n”);
-}
-```
-
-### Using Checksum to validate communication integrity
-
-The [`Checksum`] field is the sum of all bytes contained in the Harp Message. The receiver of the message should calculate the checksum and compare it with the received. If they don’t match, the Harp Message should be discarded.
-Example on how to calculate the [`Checksum`] in C language:
-
-```C
-unsigned char Checksum = 0;
-int i = 0;
-for (; i < Length + 1; i++ )
-{
-    Checksum += HarpMessage(i);
-}
-```
-
-### Parsing [Payload] with Arrays
-
-The [`Payload`] element can contain a single, or an array of values of the same type. The first step to parse these payloads is to first find the number of values contained on the [`Payload`] element. This can be done using the following `C` code example:
-
-```C
-int arrayLength;
-int hasTimestamp = 0x10;
-int sizeMask = 0x0F;
-
-if (PayloadType & hasTimestamp)
-{
-    // Harp Message has time information
-    arrayLength = (Length – 10) / (PayloadType & sizeMask )
-}
-else
-{
-    // Harp Message doesn’t have time information
-    arrayLength = (Length – 4) / (PayloadType & sizeMask )
-}
-```
----
-
-## Typical usage
-
-### 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.
+> 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.
 
@@ -323,4 +179,7 @@ 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.
+  * Change device naming to Controller and Device.
+
+- v1.4.2
+  * Clarify request-reply contract.