From e200c7592e2a49862be34ca58947db7769396827 Mon Sep 17 00:00:00 2001 From: glopesdev Date: Thu, 27 Nov 2025 22:46:23 +0000 Subject: [PATCH 1/6] Use consistent notation for array registers Array registers should be clearly indicated in the table and hyperlinks. The length of all array registers is now clearly indicated in the register specification. --- Device.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/Device.md b/Device.md index cc4501a..9d807bd 100644 --- a/Device.md +++ b/Device.md @@ -59,14 +59,14 @@ The following set of Device core registers MUST be implemented. These reserved r |[`R_TIMESTAMP_MICRO`](#r_timestamp_micro-u16--system-timestamp-microseconds)|Yes|Yes|U16|009|0|System timestamp: microseconds|Required| |[`R_OPERATION_CTRL`](#r_operation_ctrl-u8--operation-mode-configuration)|No|No|U8|010|b)|Configuration of the device operation mode|Required| |[`R_RESET_DEV`](#r_reset_dev-u8--reset-device-and-save-non-volatile-registers)|No|No|U8|011|b)|Reset device and save non-volatile registers|Optional| -|[`R_DEVICE_NAME`](#r_device_name-u8-array--human-readable-device-name)|No|No|U8|012|b)|Human-readable device name|Optional| +|[`R_DEVICE_NAME`](#r_device_name-u8-array--human-readable-device-name)|No|No|U8 Array|012|b)|Human-readable device name|Optional| |[`R_SERIAL_NUMBER`](#r_serial_number-u16--device-serial-number)|No|No|U16|013|b)|Unique serial number of the device|Deprecated| |[`R_CLOCK_CONFIG`](#r_clock_config-u8--synchronization-clock-configuration)|No|No|U8|014|b)|Synchronization clock configuration|Optional| |[`R_TIMESTAMP_OFFSET`](#r_timestamp_offset-u8--clock-calibration-offset)|No|No|U8|015|b)|Configures an offset for Timestamp updates|Deprecated| -|[`R_UID`](#r_uid-u8-array--unique-identifier)|No|Yes|U8|016|b)|Stores a unique identifier (UID) |Optional| -|[`R_TAG`](#r_tag-u8-array--firmware-tag)|-|Yes|U8|017|b)|Firmware tag|Optional| +|[`R_UID`](#r_uid-u8-array--unique-identifier)|No|Yes|U8 Array|016|b)|Stores a unique identifier (UID) |Optional| +|[`R_TAG`](#r_tag-u8-array--firmware-tag)|-|Yes|U8 Array|017|b)|Firmware tag|Optional| |[`R_HEARTBEAT`](#r_heartbeat-u16--device-status-information)|Yes|Yes|U16|018|b)|Monitors device status|Required| -|[`R_VERSION`](#r_version-u8--device-version-information)|-|Yes|U8|019|a)|Device version information|Required| +|[`R_VERSION`](#r_version-u8-array--device-version-information)|-|Yes|U8 Array|019|a)|Device version information|Required| ||a) These values MUST be stored during the firmware build process and are persistent, i.e. they SHALL NOT be changeable by the Controller.
b) Check notes on the specific register specification. | | :- | :- | @@ -471,7 +471,7 @@ This register is read-only and used to provide status information about the Devi * **IS_SYNCHRONIZED [Bit 1]:** If this bit is set, the Device MUST be synchronized with an external Harp clock generator. If the Device is itself a clock generator (see [`R_CLOCK_CONFIG`](#r_clock_config-u8--synchronization-clock-configuration) bit `CLK_GEN`), this bit MUST always be set. -### **`R_VERSION` (U8) – Device version information** +### **`R_VERSION` (U8 Array) – Device version information** Address: `019` @@ -512,7 +512,7 @@ gantt - :d4, after sdk_id, 32 ``` -The bytes in this register specify the [semantic version](https://semver.org/) of the components making up the Device. Each component version is made up of three bytes, following the order `major`, `minor`, `patch`. The register also includes a unique identifier of the core microcontroller SDK and a hash digest of the interface schema file describing the Device Interface. +An array of 32 bytes specifying the [semantic version](https://semver.org/) of the components making up the Device. Each component version is made up of three bytes, following the order `major`, `minor`, `patch`. The register also includes a unique identifier of the core microcontroller SDK and a hash digest of the interface schema file describing the Device Interface. * **PROTOCOL:** The semantic version of the Harp protocol implemented by the Device. @@ -532,7 +532,7 @@ The following registers are deprecated and their functionality SHOULD NOT be imp > [!WARNING] > -> This register is deprecated in favor of [`R_VERSION`](#r_version-u8--device-version-information). The value of this register MUST be equal to the major `HARDWARE` version in `R_VERSION`. +> This register is deprecated in favor of [`R_VERSION`](#r_version-u8-array--device-version-information). The value of this register MUST be equal to the major `HARDWARE` version in `R_VERSION`. Address: `001` @@ -562,7 +562,7 @@ Specifies the major hardware version number. The value of this register is persi > [!WARNING] > -> This register is deprecated in favor of [`R_VERSION`](#r_version-u8--device-version-information). The value of this register MUST be equal to the minor `HARDWARE` version in `R_VERSION`. +> This register is deprecated in favor of [`R_VERSION`](#r_version-u8-array--device-version-information). The value of this register MUST be equal to the minor `HARDWARE` version in `R_VERSION`. Address: `002` @@ -622,7 +622,7 @@ Specifies the version number of the assembled components. The value of this regi > [!WARNING] > -> This register is deprecated in favor of [`R_VERSION`](#r_version-u8--device-version-information). The value of this register MUST be equal to the major `PROTOCOL` version in `R_VERSION`. +> This register is deprecated in favor of [`R_VERSION`](#r_version-u8-array--device-version-information). The value of this register MUST be equal to the major `PROTOCOL` version in `R_VERSION`. Address: `004` @@ -652,7 +652,7 @@ Contains the major version of the Harp protocol specification. The value of this > [!WARNING] > -> This register is deprecated in favor of [`R_VERSION`](#r_version-u8--device-version-information). The value of this register MUST be equal to the minor `PROTOCOL` version in `R_VERSION`. +> This register is deprecated in favor of [`R_VERSION`](#r_version-u8-array--device-version-information). The value of this register MUST be equal to the minor `PROTOCOL` version in `R_VERSION`. Address: `005` @@ -682,7 +682,7 @@ Contains the minor version of the Harp Protocol specification. The value of this > [!WARNING] > -> This register is deprecated in favor of [`R_VERSION`](#r_version-u8--device-version-information). The value of this register MUST be equal to the major `FIRMWARE` version in `R_VERSION`. +> This register is deprecated in favor of [`R_VERSION`](#r_version-u8-array--device-version-information). The value of this register MUST be equal to the major `FIRMWARE` version in `R_VERSION`. Address: `006` @@ -712,7 +712,7 @@ Contains the major firmware version number. The value of this register is persis > [!WARNING] > -> This register is deprecated in favor of [`R_VERSION`](#r_version-u8--device-version-information). The value of this register MUST be equal to the minor `FIRMWARE` version in `R_VERSION`. +> This register is deprecated in favor of [`R_VERSION`](#r_version-u8-array--device-version-information). The value of this register MUST be equal to the minor `FIRMWARE` version in `R_VERSION`. ```mermaid --- From 88de5b1000b919e2f0f7179961685236888855ca Mon Sep 17 00:00:00 2001 From: glopesdev Date: Thu, 27 Nov 2025 22:52:07 +0000 Subject: [PATCH 2/6] Remove leading address zeroes for space --- Device.md | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/Device.md b/Device.md index 9d807bd..ab12e04 100644 --- a/Device.md +++ b/Device.md @@ -47,26 +47,26 @@ The following set of Device core registers MUST be implemented. These reserved r |**Name**|**Volatile**|**Read Only**|**Type**|**Add.**|**Default**|**Brief Description**|**Necessity**| | :- | :-: | :-: | :-: | :-: | :-: | :- | :-: | -|[`R_WHO_AM_I`](#r_who_am_i-u16--device-identity-class)|-|Yes|U16|000|a)|Device identity class|Required| -|[`R_HW_VERSION_H`](#r_hw_version_h-u8--major-hardware-version)|-|Yes|U8|001|a)|Major Hardware version|Deprecated| -|[`R_HW_VERSION_L`](#r_hw_version_l-u8--minor-hardware-version)|-|Yes|U8|002|a)|Minor Hardware version|Deprecated| -|[`R_ASSEMBLY_VERSION`](#r_assembly_version-u8--version-of-assembled-components)|-|Yes|U8|003|a)|Version of assembled components|Deprecated| -|[`R_CORE_VERSION_H`](#r_core_version_h-u8--major-core-version)|-|Yes|U8|004|a)|Major core version|Deprecated| -|[`R_CORE_VERSION_L`](#r_core_version_l-u8--minor-core-version)|-|Yes|U8|005|a)|Minor core version|Deprecated| -|[`R_FW_VERSION_H`](#r_fw_version_h-u8--major-firmware-version)|-|Yes|U8|006|a)|Major Firmware version of the application|Deprecated| -|[`R_FW_VERSION_L`](#r_fw_version_l-u8--minor-firmware-version)|-|Yes|U8|007|a)|Minor Firmware version of the application|Deprecated| -|[`R_TIMESTAMP_SECOND`](#r_timestamp_second-u32--system-timestamp-seconds)|Yes|No|U32|008|0|System timestamp: seconds|Required| -|[`R_TIMESTAMP_MICRO`](#r_timestamp_micro-u16--system-timestamp-microseconds)|Yes|Yes|U16|009|0|System timestamp: microseconds|Required| -|[`R_OPERATION_CTRL`](#r_operation_ctrl-u8--operation-mode-configuration)|No|No|U8|010|b)|Configuration of the device operation mode|Required| -|[`R_RESET_DEV`](#r_reset_dev-u8--reset-device-and-save-non-volatile-registers)|No|No|U8|011|b)|Reset device and save non-volatile registers|Optional| -|[`R_DEVICE_NAME`](#r_device_name-u8-array--human-readable-device-name)|No|No|U8 Array|012|b)|Human-readable device name|Optional| -|[`R_SERIAL_NUMBER`](#r_serial_number-u16--device-serial-number)|No|No|U16|013|b)|Unique serial number of the device|Deprecated| -|[`R_CLOCK_CONFIG`](#r_clock_config-u8--synchronization-clock-configuration)|No|No|U8|014|b)|Synchronization clock configuration|Optional| -|[`R_TIMESTAMP_OFFSET`](#r_timestamp_offset-u8--clock-calibration-offset)|No|No|U8|015|b)|Configures an offset for Timestamp updates|Deprecated| -|[`R_UID`](#r_uid-u8-array--unique-identifier)|No|Yes|U8 Array|016|b)|Stores a unique identifier (UID) |Optional| -|[`R_TAG`](#r_tag-u8-array--firmware-tag)|-|Yes|U8 Array|017|b)|Firmware tag|Optional| -|[`R_HEARTBEAT`](#r_heartbeat-u16--device-status-information)|Yes|Yes|U16|018|b)|Monitors device status|Required| -|[`R_VERSION`](#r_version-u8-array--device-version-information)|-|Yes|U8 Array|019|a)|Device version information|Required| +|[`R_WHO_AM_I`](#r_who_am_i-u16--device-identity-class)|-|Yes|U16|0|a)|Device identity class|Required| +|[`R_HW_VERSION_H`](#r_hw_version_h-u8--major-hardware-version)|-|Yes|U8|1|a)|Major Hardware version|Deprecated| +|[`R_HW_VERSION_L`](#r_hw_version_l-u8--minor-hardware-version)|-|Yes|U8|2|a)|Minor Hardware version|Deprecated| +|[`R_ASSEMBLY_VERSION`](#r_assembly_version-u8--version-of-assembled-components)|-|Yes|U8|3|a)|Version of assembled components|Deprecated| +|[`R_CORE_VERSION_H`](#r_core_version_h-u8--major-core-version)|-|Yes|U8|4|a)|Major core version|Deprecated| +|[`R_CORE_VERSION_L`](#r_core_version_l-u8--minor-core-version)|-|Yes|U8|5|a)|Minor core version|Deprecated| +|[`R_FW_VERSION_H`](#r_fw_version_h-u8--major-firmware-version)|-|Yes|U8|6|a)|Major Firmware version of the application|Deprecated| +|[`R_FW_VERSION_L`](#r_fw_version_l-u8--minor-firmware-version)|-|Yes|U8|7|a)|Minor Firmware version of the application|Deprecated| +|[`R_TIMESTAMP_SECOND`](#r_timestamp_second-u32--system-timestamp-seconds)|Yes|No|U32|8|0|System timestamp: seconds|Required| +|[`R_TIMESTAMP_MICRO`](#r_timestamp_micro-u16--system-timestamp-microseconds)|Yes|Yes|U16|9|0|System timestamp: microseconds|Required| +|[`R_OPERATION_CTRL`](#r_operation_ctrl-u8--operation-mode-configuration)|No|No|U8|10|b)|Configuration of the device operation mode|Required| +|[`R_RESET_DEV`](#r_reset_dev-u8--reset-device-and-save-non-volatile-registers)|No|No|U8|11|b)|Reset device and save non-volatile registers|Optional| +|[`R_DEVICE_NAME`](#r_device_name-u8-array--human-readable-device-name)|No|No|U8 Array|12|b)|Human-readable device name|Optional| +|[`R_SERIAL_NUMBER`](#r_serial_number-u16--device-serial-number)|No|No|U16|13|b)|Unique serial number of the device|Deprecated| +|[`R_CLOCK_CONFIG`](#r_clock_config-u8--synchronization-clock-configuration)|No|No|U8|14|b)|Synchronization clock configuration|Optional| +|[`R_TIMESTAMP_OFFSET`](#r_timestamp_offset-u8--clock-calibration-offset)|No|No|U8|15|b)|Configures an offset for Timestamp updates|Deprecated| +|[`R_UID`](#r_uid-u8-array--unique-identifier)|No|Yes|U8 Array|16|b)|Stores a unique identifier (UID) |Optional| +|[`R_TAG`](#r_tag-u8-array--firmware-tag)|-|Yes|U8 Array|17|b)|Firmware tag|Optional| +|[`R_HEARTBEAT`](#r_heartbeat-u16--device-status-information)|Yes|Yes|U16|18|b)|Monitors device status|Required| +|[`R_VERSION`](#r_version-u8-array--device-version-information)|-|Yes|U8 Array|19|a)|Device version information|Required| ||a) These values MUST be stored during the firmware build process and are persistent, i.e. they SHALL NOT be changeable by the Controller.
b) Check notes on the specific register specification. | | :- | :- | From c1aff67ef89f2d2ade6ae197a0138a52589d6326 Mon Sep 17 00:00:00 2001 From: glopesdev Date: Thu, 27 Nov 2025 23:06:27 +0000 Subject: [PATCH 3/6] Simplify register description and normalize casing --- Device.md | 62 +++++++++++++++++++++++++++---------------------------- 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/Device.md b/Device.md index ab12e04..a3595f0 100644 --- a/Device.md +++ b/Device.md @@ -47,26 +47,26 @@ The following set of Device core registers MUST be implemented. These reserved r |**Name**|**Volatile**|**Read Only**|**Type**|**Add.**|**Default**|**Brief Description**|**Necessity**| | :- | :-: | :-: | :-: | :-: | :-: | :- | :-: | -|[`R_WHO_AM_I`](#r_who_am_i-u16--device-identity-class)|-|Yes|U16|0|a)|Device identity class|Required| -|[`R_HW_VERSION_H`](#r_hw_version_h-u8--major-hardware-version)|-|Yes|U8|1|a)|Major Hardware version|Deprecated| -|[`R_HW_VERSION_L`](#r_hw_version_l-u8--minor-hardware-version)|-|Yes|U8|2|a)|Minor Hardware version|Deprecated| -|[`R_ASSEMBLY_VERSION`](#r_assembly_version-u8--version-of-assembled-components)|-|Yes|U8|3|a)|Version of assembled components|Deprecated| -|[`R_CORE_VERSION_H`](#r_core_version_h-u8--major-core-version)|-|Yes|U8|4|a)|Major core version|Deprecated| -|[`R_CORE_VERSION_L`](#r_core_version_l-u8--minor-core-version)|-|Yes|U8|5|a)|Minor core version|Deprecated| -|[`R_FW_VERSION_H`](#r_fw_version_h-u8--major-firmware-version)|-|Yes|U8|6|a)|Major Firmware version of the application|Deprecated| -|[`R_FW_VERSION_L`](#r_fw_version_l-u8--minor-firmware-version)|-|Yes|U8|7|a)|Minor Firmware version of the application|Deprecated| -|[`R_TIMESTAMP_SECOND`](#r_timestamp_second-u32--system-timestamp-seconds)|Yes|No|U32|8|0|System timestamp: seconds|Required| -|[`R_TIMESTAMP_MICRO`](#r_timestamp_micro-u16--system-timestamp-microseconds)|Yes|Yes|U16|9|0|System timestamp: microseconds|Required| -|[`R_OPERATION_CTRL`](#r_operation_ctrl-u8--operation-mode-configuration)|No|No|U8|10|b)|Configuration of the device operation mode|Required| -|[`R_RESET_DEV`](#r_reset_dev-u8--reset-device-and-save-non-volatile-registers)|No|No|U8|11|b)|Reset device and save non-volatile registers|Optional| -|[`R_DEVICE_NAME`](#r_device_name-u8-array--human-readable-device-name)|No|No|U8 Array|12|b)|Human-readable device name|Optional| -|[`R_SERIAL_NUMBER`](#r_serial_number-u16--device-serial-number)|No|No|U16|13|b)|Unique serial number of the device|Deprecated| -|[`R_CLOCK_CONFIG`](#r_clock_config-u8--synchronization-clock-configuration)|No|No|U8|14|b)|Synchronization clock configuration|Optional| -|[`R_TIMESTAMP_OFFSET`](#r_timestamp_offset-u8--clock-calibration-offset)|No|No|U8|15|b)|Configures an offset for Timestamp updates|Deprecated| -|[`R_UID`](#r_uid-u8-array--unique-identifier)|No|Yes|U8 Array|16|b)|Stores a unique identifier (UID) |Optional| -|[`R_TAG`](#r_tag-u8-array--firmware-tag)|-|Yes|U8 Array|17|b)|Firmware tag|Optional| -|[`R_HEARTBEAT`](#r_heartbeat-u16--device-status-information)|Yes|Yes|U16|18|b)|Monitors device status|Required| -|[`R_VERSION`](#r_version-u8-array--device-version-information)|-|Yes|U8 Array|19|a)|Device version information|Required| +|[`R_WHO_AM_I`](#r_who_am_i-u16--device-identity-class)|-|Yes|U16|0|a)|Device Identity Class|Required| +|[`R_HW_VERSION_H`](#r_hw_version_h-u8--major-hardware-version)|-|Yes|U8|1|a)|Major Hardware Version|Deprecated| +|[`R_HW_VERSION_L`](#r_hw_version_l-u8--minor-hardware-version)|-|Yes|U8|2|a)|Minor Hardware Version|Deprecated| +|[`R_ASSEMBLY_VERSION`](#r_assembly_version-u8--version-of-assembled-components)|-|Yes|U8|3|a)|Version of Assembled Components|Deprecated| +|[`R_CORE_VERSION_H`](#r_core_version_h-u8--major-core-version)|-|Yes|U8|4|a)|Major Core Version|Deprecated| +|[`R_CORE_VERSION_L`](#r_core_version_l-u8--minor-core-version)|-|Yes|U8|5|a)|Minor Core Version|Deprecated| +|[`R_FW_VERSION_H`](#r_fw_version_h-u8--major-firmware-version)|-|Yes|U8|6|a)|Major Firmware Version|Deprecated| +|[`R_FW_VERSION_L`](#r_fw_version_l-u8--minor-firmware-version)|-|Yes|U8|7|a)|Minor Firmware Version|Deprecated| +|[`R_TIMESTAMP_SECOND`](#r_timestamp_second-u32--system-timestamp-seconds)|Yes|No|U32|8|0|System Timestamp (seconds)|Required| +|[`R_TIMESTAMP_MICRO`](#r_timestamp_micro-u16--system-timestamp-microseconds)|Yes|Yes|U16|9|0|System Timestamp (microseconds)|Required| +|[`R_OPERATION_CTRL`](#r_operation_ctrl-u8--operation-mode-configuration)|No|No|U8|10|b)|Operation Mode Configuration|Required| +|[`R_RESET_DEV`](#r_reset_dev-u8--reset-device-and-save-non-volatile-registers)|No|No|U8|11|b)|Reset Device|Optional| +|[`R_DEVICE_NAME`](#r_device_name-u8-array--human-readable-device-name)|No|No|U8 Array|12|b)|Human-readable Device Name|Optional| +|[`R_SERIAL_NUMBER`](#r_serial_number-u16--device-serial-number)|No|No|U16|13|b)|Device Serial Number|Deprecated| +|[`R_CLOCK_CONFIG`](#r_clock_config-u8--synchronization-clock-configuration)|No|No|U8|14|b)|Synchronization Clock Configuration|Optional| +|[`R_TIMESTAMP_OFFSET`](#r_timestamp_offset-u8--clock-calibration-offset)|No|No|U8|15|b)|Clock Calibration Offset|Deprecated| +|[`R_UID`](#r_uid-u8-array--unique-identifier)|No|Yes|U8 Array|16|b)|Unique Identifier|Optional| +|[`R_TAG`](#r_tag-u8-array--firmware-tag)|-|Yes|U8 Array|17|b)|Firmware Tag|Optional| +|[`R_HEARTBEAT`](#r_heartbeat-u16--device-status-information)|Yes|Yes|U16|18|b)|Device Status Information|Required| +|[`R_VERSION`](#r_version-u8-array--device-version-information)|-|Yes|U8 Array|19|a)|Device Version Information|Required| ||a) These values MUST be stored during the firmware build process and are persistent, i.e. they SHALL NOT be changeable by the Controller.
b) Check notes on the specific register specification. | | :- | :- | @@ -103,7 +103,7 @@ gantt Specifies the identity class of the Device. The list of reserved device identity classes can be found at [harp-tech/whoami](https://github.com/harp-tech/whoami). To reserve specific device identity classes for your project or company, please follow the instructions in that repository. If the Device does not have a pre-allocated identity class, this register MUST be set to its default value of `0` (Zero). -### **`R_TIMESTAMP_SECOND` (U32) – System timestamp (seconds)** +### **`R_TIMESTAMP_SECOND` (U32) – System Timestamp (seconds)** Address: `008` @@ -132,7 +132,7 @@ gantt Contains the current system timestamp in whole seconds. The default value is `0` (Zero) and will increment one unit for each elapsed second. -### **`R_TIMESTAMP_MICRO` (U16) – System timestamp (microseconds)** +### **`R_TIMESTAMP_MICRO` (U16) – System Timestamp (microseconds)** Address: `009` @@ -159,7 +159,7 @@ gantt Contains the microseconds count within each second. Each LSB corresponds to 32 microseconds. The maximum value is 31249. The default value is `0` (Zero). -### **`R_OPERATION_CTRL` (U8) – Operation mode configuration** +### **`R_OPERATION_CTRL` (U8) – Operation Mode Configuration** Address: `010` @@ -250,7 +250,7 @@ b) `Standby` and `Active` modes are mandatory. `Speed` mode is deprecated. * **ALIVE_EN [Bit 7]:** If this bit is set, the Device SHOULD send an `Event` message every second with the contents of [`R_TIMESTAMP_SECOND`](#r_timestamp_second-u32--system-timestamp-seconds). This feature has been deprecated and may be removed from future protocol versions. The Controller SHOULD set the `HEARTBEAT_EN` bit and monitor [`R_HEARTBEAT`](#r_heartbeat-u16--device-status-information) instead for periodically checking the status of the Device. -### **`R_RESET_DEV` (U8) – Reset device and save non-volatile registers** +### **`R_RESET_DEV` (U8) – Reset Device** Address: `011` @@ -313,7 +313,7 @@ This register is used to reboot the Device, optionally save or restore non-volat > > To avoid unexpected behavior, the Controller SHOULD set only one bit at a time when sending a `Write` request to `R_RESET_DEV`. -### **`R_DEVICE_NAME` (U8 Array) – Human-readable device name** +### **`R_DEVICE_NAME` (U8 Array) – Human-readable Device Name** Address: `012` @@ -321,7 +321,7 @@ An array of 25 bytes specifying a human-readable device name. Any unused bytes M Providing a non-empty device name is OPTIONAL. If no name is provided, the default value of this register MUST be `0` (Zero). -### **`R_CLOCK_CONFIG` (U8) – Synchronization clock configuration** +### **`R_CLOCK_CONFIG` (U8) – Synchronization Clock Configuration** Address: `014` @@ -408,7 +408,7 @@ gantt An array of 16 bytes specifying a (128-bit) UID (Unique Identifier) for the Device. This register is non-volatile and read-only. The byte-order is little-endian. If not implemented, the Device MUST return a default value of `0` (Zero) for all bytes. -### **`R_TAG` (U8 Array) – Firmware tag** +### **`R_TAG` (U8 Array) – Firmware Tag** Address: `017` @@ -436,7 +436,7 @@ An array of 8 bytes that can be used to store a tag for a specific firmware buil If not implemented, the Device MUST return a default value of `0` (Zero) for all bytes. -### **`R_HEARTBEAT` (U16) – Device status information** +### **`R_HEARTBEAT` (U16) – Device Status Information** Address: `018` @@ -471,7 +471,7 @@ This register is read-only and used to provide status information about the Devi * **IS_SYNCHRONIZED [Bit 1]:** If this bit is set, the Device MUST be synchronized with an external Harp clock generator. If the Device is itself a clock generator (see [`R_CLOCK_CONFIG`](#r_clock_config-u8--synchronization-clock-configuration) bit `CLK_GEN`), this bit MUST always be set. -### **`R_VERSION` (U8 Array) – Device version information** +### **`R_VERSION` (U8 Array) – Device Version Information** Address: `019` @@ -736,7 +736,7 @@ gantt Contains the minor firmware version number. The value of this register is persistent and MUST NOT be changeable by the Controller. -### **`R_SERIAL_NUMBER` (U16) – Device serial number** +### **`R_SERIAL_NUMBER` (U16) – Device Serial Number** > [!WARNING] > @@ -774,7 +774,7 @@ Supporting `Write` requests to this register is OPTIONAL. If `Write` requests ar Otherwise, if `Write` requests are not supported, the Device MUST reply to any `Write` requests with the fixed device serial number. -### **`R_TIMESTAMP_OFFSET` (U8) – Clock calibration offset** +### **`R_TIMESTAMP_OFFSET` (U8) – Clock Calibration Offset** > [!WARNING] > From e19aff4efcc6faae2fe0883918f5a6c490ee642f Mon Sep 17 00:00:00 2001 From: glopesdev Date: Thu, 27 Nov 2025 23:08:42 +0000 Subject: [PATCH 4/6] Restore leading zeroes and fix hyperlink --- Device.md | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/Device.md b/Device.md index a3595f0..661f265 100644 --- a/Device.md +++ b/Device.md @@ -47,26 +47,26 @@ The following set of Device core registers MUST be implemented. These reserved r |**Name**|**Volatile**|**Read Only**|**Type**|**Add.**|**Default**|**Brief Description**|**Necessity**| | :- | :-: | :-: | :-: | :-: | :-: | :- | :-: | -|[`R_WHO_AM_I`](#r_who_am_i-u16--device-identity-class)|-|Yes|U16|0|a)|Device Identity Class|Required| -|[`R_HW_VERSION_H`](#r_hw_version_h-u8--major-hardware-version)|-|Yes|U8|1|a)|Major Hardware Version|Deprecated| -|[`R_HW_VERSION_L`](#r_hw_version_l-u8--minor-hardware-version)|-|Yes|U8|2|a)|Minor Hardware Version|Deprecated| -|[`R_ASSEMBLY_VERSION`](#r_assembly_version-u8--version-of-assembled-components)|-|Yes|U8|3|a)|Version of Assembled Components|Deprecated| -|[`R_CORE_VERSION_H`](#r_core_version_h-u8--major-core-version)|-|Yes|U8|4|a)|Major Core Version|Deprecated| -|[`R_CORE_VERSION_L`](#r_core_version_l-u8--minor-core-version)|-|Yes|U8|5|a)|Minor Core Version|Deprecated| -|[`R_FW_VERSION_H`](#r_fw_version_h-u8--major-firmware-version)|-|Yes|U8|6|a)|Major Firmware Version|Deprecated| -|[`R_FW_VERSION_L`](#r_fw_version_l-u8--minor-firmware-version)|-|Yes|U8|7|a)|Minor Firmware Version|Deprecated| -|[`R_TIMESTAMP_SECOND`](#r_timestamp_second-u32--system-timestamp-seconds)|Yes|No|U32|8|0|System Timestamp (seconds)|Required| -|[`R_TIMESTAMP_MICRO`](#r_timestamp_micro-u16--system-timestamp-microseconds)|Yes|Yes|U16|9|0|System Timestamp (microseconds)|Required| -|[`R_OPERATION_CTRL`](#r_operation_ctrl-u8--operation-mode-configuration)|No|No|U8|10|b)|Operation Mode Configuration|Required| -|[`R_RESET_DEV`](#r_reset_dev-u8--reset-device-and-save-non-volatile-registers)|No|No|U8|11|b)|Reset Device|Optional| -|[`R_DEVICE_NAME`](#r_device_name-u8-array--human-readable-device-name)|No|No|U8 Array|12|b)|Human-readable Device Name|Optional| -|[`R_SERIAL_NUMBER`](#r_serial_number-u16--device-serial-number)|No|No|U16|13|b)|Device Serial Number|Deprecated| -|[`R_CLOCK_CONFIG`](#r_clock_config-u8--synchronization-clock-configuration)|No|No|U8|14|b)|Synchronization Clock Configuration|Optional| -|[`R_TIMESTAMP_OFFSET`](#r_timestamp_offset-u8--clock-calibration-offset)|No|No|U8|15|b)|Clock Calibration Offset|Deprecated| -|[`R_UID`](#r_uid-u8-array--unique-identifier)|No|Yes|U8 Array|16|b)|Unique Identifier|Optional| -|[`R_TAG`](#r_tag-u8-array--firmware-tag)|-|Yes|U8 Array|17|b)|Firmware Tag|Optional| -|[`R_HEARTBEAT`](#r_heartbeat-u16--device-status-information)|Yes|Yes|U16|18|b)|Device Status Information|Required| -|[`R_VERSION`](#r_version-u8-array--device-version-information)|-|Yes|U8 Array|19|a)|Device Version Information|Required| +|[`R_WHO_AM_I`](#r_who_am_i-u16--device-identity-class)|-|Yes|U16|000|a)|Device Identity Class|Required| +|[`R_HW_VERSION_H`](#r_hw_version_h-u8--major-hardware-version)|-|Yes|U8|001|a)|Major Hardware Version|Deprecated| +|[`R_HW_VERSION_L`](#r_hw_version_l-u8--minor-hardware-version)|-|Yes|U8|002|a)|Minor Hardware Version|Deprecated| +|[`R_ASSEMBLY_VERSION`](#r_assembly_version-u8--version-of-assembled-components)|-|Yes|U8|003|a)|Version of Assembled Components|Deprecated| +|[`R_CORE_VERSION_H`](#r_core_version_h-u8--major-core-version)|-|Yes|U8|004|a)|Major Core Version|Deprecated| +|[`R_CORE_VERSION_L`](#r_core_version_l-u8--minor-core-version)|-|Yes|U8|005|a)|Minor Core Version|Deprecated| +|[`R_FW_VERSION_H`](#r_fw_version_h-u8--major-firmware-version)|-|Yes|U8|006|a)|Major Firmware Version|Deprecated| +|[`R_FW_VERSION_L`](#r_fw_version_l-u8--minor-firmware-version)|-|Yes|U8|007|a)|Minor Firmware Version|Deprecated| +|[`R_TIMESTAMP_SECOND`](#r_timestamp_second-u32--system-timestamp-seconds)|Yes|No|U32|008|0|System Timestamp (seconds)|Required| +|[`R_TIMESTAMP_MICRO`](#r_timestamp_micro-u16--system-timestamp-microseconds)|Yes|Yes|U16|009|0|System Timestamp (microseconds)|Required| +|[`R_OPERATION_CTRL`](#r_operation_ctrl-u8--operation-mode-configuration)|No|No|U8|010|b)|Operation Mode Configuration|Required| +|[`R_RESET_DEV`](#r_reset_dev-u8--reset-device)|No|No|U8|011|b)|Reset Device|Optional| +|[`R_DEVICE_NAME`](#r_device_name-u8-array--human-readable-device-name)|No|No|U8 Array|012|b)|Human-readable Device Name|Optional| +|[`R_SERIAL_NUMBER`](#r_serial_number-u16--device-serial-number)|No|No|U16|013|b)|Device Serial Number|Deprecated| +|[`R_CLOCK_CONFIG`](#r_clock_config-u8--synchronization-clock-configuration)|No|No|U8|014|b)|Synchronization Clock Configuration|Optional| +|[`R_TIMESTAMP_OFFSET`](#r_timestamp_offset-u8--clock-calibration-offset)|No|No|U8|015|b)|Clock Calibration Offset|Deprecated| +|[`R_UID`](#r_uid-u8-array--unique-identifier)|No|Yes|U8 Array|016|b)|Unique Identifier|Optional| +|[`R_TAG`](#r_tag-u8-array--firmware-tag)|-|Yes|U8 Array|017|b)|Firmware Tag|Optional| +|[`R_HEARTBEAT`](#r_heartbeat-u16--device-status-information)|Yes|Yes|U16|018|b)|Device Status Information|Required| +|[`R_VERSION`](#r_version-u8-array--device-version-information)|-|Yes|U8 Array|019|a)|Device Version Information|Required| ||a) These values MUST be stored during the firmware build process and are persistent, i.e. they SHALL NOT be changeable by the Controller.
b) Check notes on the specific register specification. | | :- | :- | From ad7be16a778db88c951544f61b311636abb52820 Mon Sep 17 00:00:00 2001 From: glopesdev Date: Thu, 27 Nov 2025 23:34:31 +0000 Subject: [PATCH 5/6] Add length to all register specifications --- Device.md | 60 +++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 41 insertions(+), 19 deletions(-) diff --git a/Device.md b/Device.md index 661f265..18cf226 100644 --- a/Device.md +++ b/Device.md @@ -78,7 +78,8 @@ Mermaid plots can be generated here: https://mermaid.live/ ### **`R_WHO_AM_I` (U16) – Device Identity Class** -Address: `000` +Address: `000` +Length: 1 ```mermaid --- @@ -105,7 +106,8 @@ Specifies the identity class of the Device. The list of reserved device identity ### **`R_TIMESTAMP_SECOND` (U32) – System Timestamp (seconds)** -Address: `008` +Address: `008` +Length: 1 ```mermaid --- @@ -134,7 +136,8 @@ Contains the current system timestamp in whole seconds. The default value is `0` ### **`R_TIMESTAMP_MICRO` (U16) – System Timestamp (microseconds)** -Address: `009` +Address: `009` +Length: 1 ```mermaid --- @@ -161,7 +164,8 @@ Contains the microseconds count within each second. Each LSB corresponds to 32 m ### **`R_OPERATION_CTRL` (U8) – Operation Mode Configuration** -Address: `010` +Address: `010` +Length: 1 ```mermaid @@ -252,7 +256,8 @@ b) `Standby` and `Active` modes are mandatory. `Speed` mode is deprecated. ### **`R_RESET_DEV` (U8) – Reset Device** -Address: `011` +Address: `011` +Length: 1 ```mermaid --- @@ -315,7 +320,8 @@ This register is used to reboot the Device, optionally save or restore non-volat ### **`R_DEVICE_NAME` (U8 Array) – Human-readable Device Name** -Address: `012` +Address: `012` +Length: 25 An array of 25 bytes specifying a human-readable device name. Any unused bytes MUST be set to `0` (Zero). This register is non-volatile. If a `Write` request to this register is received and non-volatile memory is available, the Device MUST reset and save the new register value to persistent storage. Otherwise, if non-volatile memory is not available, the Device MUST reply to any `Write` requests with the default register value. @@ -323,7 +329,8 @@ Providing a non-empty device name is OPTIONAL. If no name is provided, the defau ### **`R_CLOCK_CONFIG` (U8) – Synchronization Clock Configuration** -Address: `014` +Address: `014` +Length: 1 ```mermaid --- @@ -384,7 +391,8 @@ The implementation of this register is RECOMMENDED if the Device provides a [Syn ### **`R_UID` (U8 Array) – Unique Identifier** -Address: `016` +Address: `016` +Length: 16 ```mermaid --- @@ -410,7 +418,8 @@ An array of 16 bytes specifying a (128-bit) UID (Unique Identifier) for the Devi ### **`R_TAG` (U8 Array) – Firmware Tag** -Address: `017` +Address: `017` +Length: 8 ```mermaid --- @@ -438,7 +447,8 @@ If not implemented, the Device MUST return a default value of `0` (Zero) for all ### **`R_HEARTBEAT` (U16) – Device Status Information** -Address: `018` +Address: `018` +Length: 1 ```mermaid --- @@ -473,7 +483,8 @@ This register is read-only and used to provide status information about the Devi ### **`R_VERSION` (U8 Array) – Device Version Information** -Address: `019` +Address: `019` +Length: 32 ```mermaid --- @@ -534,7 +545,8 @@ The following registers are deprecated and their functionality SHOULD NOT be imp > > This register is deprecated in favor of [`R_VERSION`](#r_version-u8-array--device-version-information). The value of this register MUST be equal to the major `HARDWARE` version in `R_VERSION`. -Address: `001` +Address: `001` +Length: 1 ```mermaid --- @@ -564,7 +576,8 @@ Specifies the major hardware version number. The value of this register is persi > > This register is deprecated in favor of [`R_VERSION`](#r_version-u8-array--device-version-information). The value of this register MUST be equal to the minor `HARDWARE` version in `R_VERSION`. -Address: `002` +Address: `002` +Length: 1 ```mermaid --- @@ -594,7 +607,8 @@ Specifies the minor hardware version number. The value of this register is persi > > This register is deprecated as we do not require tracking the version of assembled components directly in the Device firmware. -Address: `003` +Address: `003` +Length: 1 ```mermaid --- @@ -624,7 +638,8 @@ Specifies the version number of the assembled components. The value of this regi > > This register is deprecated in favor of [`R_VERSION`](#r_version-u8-array--device-version-information). The value of this register MUST be equal to the major `PROTOCOL` version in `R_VERSION`. -Address: `004` +Address: `004` +Length: 1 ```mermaid --- @@ -654,7 +669,8 @@ Contains the major version of the Harp protocol specification. The value of this > > This register is deprecated in favor of [`R_VERSION`](#r_version-u8-array--device-version-information). The value of this register MUST be equal to the minor `PROTOCOL` version in `R_VERSION`. -Address: `005` +Address: `005` +Length: 1 ```mermaid --- @@ -684,7 +700,8 @@ Contains the minor version of the Harp Protocol specification. The value of this > > This register is deprecated in favor of [`R_VERSION`](#r_version-u8-array--device-version-information). The value of this register MUST be equal to the major `FIRMWARE` version in `R_VERSION`. -Address: `006` +Address: `006` +Length: 1 ```mermaid --- @@ -714,6 +731,9 @@ Contains the major firmware version number. The value of this register is persis > > This register is deprecated in favor of [`R_VERSION`](#r_version-u8-array--device-version-information). The value of this register MUST be equal to the minor `FIRMWARE` version in `R_VERSION`. +Address: `007` +Length: 1 + ```mermaid --- displayMode: compact @@ -742,7 +762,8 @@ Contains the minor firmware version number. The value of this register is persis > > This register is deprecated in favor of [`R_UID`](#r_uid-u8-array--unique-identifier). The value of this register MUST duplicate the first two bytes of `R_UID`, in little-endian order. -Address: `013` +Address: `013` +Length: 1 ```mermaid --- @@ -780,7 +801,8 @@ Otherwise, if `Write` requests are not supported, the Device MUST reply to any ` > > This register is deprecated and MUST NOT be implemented on any new devices. -Address: `015` +Address: `015` +Length: 1 ```mermaid --- From f69cd1d7bbe5642e0fffeb3b129e7a838f550287 Mon Sep 17 00:00:00 2001 From: glopesdev Date: Thu, 27 Nov 2025 23:36:57 +0000 Subject: [PATCH 6/6] Avoid duplicating register length --- Device.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Device.md b/Device.md index 18cf226..b450dcc 100644 --- a/Device.md +++ b/Device.md @@ -323,7 +323,7 @@ This register is used to reboot the Device, optionally save or restore non-volat Address: `012` Length: 25 -An array of 25 bytes specifying a human-readable device name. Any unused bytes MUST be set to `0` (Zero). This register is non-volatile. If a `Write` request to this register is received and non-volatile memory is available, the Device MUST reset and save the new register value to persistent storage. Otherwise, if non-volatile memory is not available, the Device MUST reply to any `Write` requests with the default register value. +The bytes in this register specify a human-readable device name. Any unused bytes MUST be set to `0` (Zero). This register is non-volatile. If a `Write` request to this register is received and non-volatile memory is available, the Device MUST reset and save the new register value to persistent storage. Otherwise, if non-volatile memory is not available, the Device MUST reply to any `Write` requests with the default register value. Providing a non-empty device name is OPTIONAL. If no name is provided, the default value of this register MUST be `0` (Zero). @@ -414,7 +414,7 @@ gantt 0 :d1, 0, 1 ``` -An array of 16 bytes specifying a (128-bit) UID (Unique Identifier) for the Device. This register is non-volatile and read-only. The byte-order is little-endian. If not implemented, the Device MUST return a default value of `0` (Zero) for all bytes. +An array of bytes specifying a (128-bit) UID (Unique Identifier) for the Device. This register is non-volatile and read-only. The byte-order is little-endian. If not implemented, the Device MUST return a default value of `0` (Zero) for all bytes. ### **`R_TAG` (U8 Array) – Firmware Tag** @@ -441,7 +441,7 @@ gantt 0 :d1, 0, 1 ``` -An array of 8 bytes that can be used to store a tag for a specific firmware build. For instance, it could be used to store the Git hash of a specific release/commit. The byte-order is little-endian. This register is read-only. +An array of bytes that can be used to store a tag for a specific firmware build. For instance, it could be used to store the Git hash of a specific release/commit. The byte-order is little-endian. This register is read-only. If not implemented, the Device MUST return a default value of `0` (Zero) for all bytes. @@ -523,7 +523,7 @@ gantt - :d4, after sdk_id, 32 ``` -An array of 32 bytes specifying the [semantic version](https://semver.org/) of the components making up the Device. Each component version is made up of three bytes, following the order `major`, `minor`, `patch`. The register also includes a unique identifier of the core microcontroller SDK and a hash digest of the interface schema file describing the Device Interface. +The bytes in this register specify the [semantic version](https://semver.org/) of the components making up the Device. Each component version is made up of three bytes, following the order `major`, `minor`, `patch`. The register also includes a unique identifier of the core microcontroller SDK and a hash digest of the interface schema file describing the Device Interface. * **PROTOCOL:** The semantic version of the Harp protocol implemented by the Device.