This document defines the common set of standard functionality that new Harp Device hardware should aim to provide. The goal is to create a common ground for the development and operation of Harp devices, and to allow quick and easy integration of new devices into the existing ecosystem. While some registers and functionalities are not mandatory, it is strongly recommended that they are implemented or, at least, considered with compatibility in mind.
The Common Registers are a set of registers that are common to all Harp Devices. These registers are used to identify the device, its version, and its operation mode. The Common Registers are mandatory and should be implemented in all Harp Devices. Summary description of each register can be found in [this table](ref missing).
All other registers pertaining to the operation of a specific device (Application Registers) should always take a register number equal, or greater, than 32. Moreoever, numbering and naming of these registers will be left to the developer, as they are specific to each device.
A Harp Device is expected to implement the following Operation Modes:
Standby Mode:Replies to host commands. Events are disabled and must not be sent.Active Mode:Replies to host commands. Events are enabled and sent to host whenever the device deems it so.Speed Mode:Allows the implementation of a different and specific communication protocol. On this mode, the Harp Binary Protocol is no longer used. The specific protocol designed must implement the possibility to exit this mode.
The mandatory Operation Modes are the Standby Mode and Active Mode. The Speed Mode is optional and, in many of the applications, not needed.
Harp Devices should continuously check if the communication with the host is active and healthy. This status check will be largely dependent on the transport layer implementing the harp protocol between host and device. Each implementation should clearly distinguish between Connected and Not Connected states, and it is up to the developer to decide how to implement this status check. When the device transitions to the Not Connected state, it should immediately enter Standy Mode and stop transmission of further event messages.
As an application example, devices using USB as the transport layer can poll for an active USB connection by checking that the state of the DTR pin is set to HIGH. Once this pin is set LOW it may be assumed that the host closed the connection and the device should enter Standby Mode. In this case, the host is responsible for setting the state of the DTR line when opening or closing a new connection.
| Name | Volatile | Read Only | Type | Add. | Default | Brief Description | Mandatory |
|---|---|---|---|---|---|---|---|
| R_WHO_AM_I | - | Yes | U16 | 000 | a) | Who am I | Yes |
| R_HW_VERSION_H | - | Yes | U8 | 001 | a) | Major Hardware version | Yes |
| R_HW_VERSION_L | - | Yes | U8 | 002 | a) | Minor Hardware version | Yes |
| R_ASSEMBLY_VERSION | - | Yes | U8 | 003 | a) | Version of the assembled components | Optional |
| R_CORE_VERSION_H | - | Yes | U8 | 004 | a) | Major core version | Optional |
| R_CORE_VERSION_L | - | Yes | U8 | 005 | a) | Minor core version | Optional |
| R_FW_VERSION_H | - | Yes | U8 | 006 | a) | Major Firmware version of the application | Yes |
| R_FW_VERSION_L | - | Yes | U8 | 007 | a) | Minor Firmware version of the application | Yes |
| R_TIMESTAMP_SECOND | Yes | No | U32 | 008 | 0 | System timestamp: seconds | Yes |
| R_TIMESTAMP_MICRO | Yes | Yes | U16 | 009 | 0 | System timestamp: microseconds | Optional |
| R_OPERATION_CTRL | No | No | U8 | 010 | b) | Configuration of the operation mode | c) |
| R_RESET_DEV | No | No | U8 | 011 | b) | Reset device and save non-volatile registers | Optional |
| R_DEVICE_NAME | No | No | U8 | 012 | b) | Name of the device given by the user | Optional |
| R_SERIAL_NUMBER | No | No | U16 | 013 | b) | Unique serial number of the device | Optional |
| R_CLOCK_CONFIG | No | No | U8 | 014 | b) | Synchronization clock configuration | Optional |
| R_TIMESTAMP_OFFSET | No | No | U8 | 015 | b) | Adds an offset if user updates the Timestamp | Optional |
| R_UID | No | Yes | U8 | 016 | b) | Stores a unique identifier (UID) | Optional |
| R_TAG | - | Yes | U8 | 017 | b) | Firmware tag | Optional |
| R_HEARTBEAT | Yes | Yes | U16 | 018 | b) | Provides information about the state of the device | Yes |
| a) These values are stored during factory process and are persistent, i.e., they cannot be changed by the user. b) Check register notes on the specific register explanation c) Only parts of the functionality is mandatory. Check register notes on the explanation. |
|---|
Address: 000
Used to verify the identity of the device. A list of devices can be found at https://github.com/harp-tech/protocol. To reserve a range or certain IDs for your project or company, please follow the instructions in this repository. If the device doesn’t have a pre-allocated ID on the IDs list, this register should be set as 0.
---
displayMode: compact
---
gantt
title R_WHO_AM_I (000) [U16]
dateFormat X
axisFormat %
tickInterval 0
section Bit
15-8 :byte1, 0, 1
7-0 :byte0, after byte1 , 2
section Id
WHO_AM_I :id1, 0, 2
section Default
0 :d1, 0, 2
Address: 008
Contains the current system timestamp in whole seconds. The default value is 0 (ZERO) and will increment one unit for each elapsed second.
---
displayMode: compact
---
gantt
title R_TIMESTAMP_SECONDS (008) [U32]
dateFormat X
axisFormat %
tickInterval 0
section Bit
31-24 :byte3, 0, 1
23-16 :byte2, after byte3 , 2
15-8 :byte1, after byte2 , 3
7-0 :byte0, after byte1 , 4
section Id
SECONDS :id1, 0, 4
section Default
0 :d1, 0, 4
Address: 009
Contains the microseconds count within each second. Each LSB corresponds to 32 microseconds. The maximum value is 31249.
---
displayMode: compact
---
gantt
title R_TIMESTAMP_SECONDS (009) [U16]
dateFormat X
axisFormat %
tickInterval 0
section Bit
15-8 :byte1, 0, 1
7-0 :byte0, after byte1 , 2
section Id
USECONDS :id1, 0, 2
section Default
- :d1, 0, 2
Address: 010
---
displayMode: compact
---
gantt
title R_OPERATION_CTRL (010)
dateFormat X
axisFormat %
section Bit
7 :bit7, 0, 1
6 :bit6, after bit7 , 2
5 :bit5, after bit6 , 3
4 :bit4, after bit5 , 4
3 :bit3, after bit4 , 5
2 :bit2, after bit3 , 6
1 :bit1, after bit2 , 7
0 :bit0, after bit1 , 8
section Id
ALIVE_EN :id7, 0, 1
OPLEDEN :id6, after bit7 , 2
VISUALEN :id5, after bit6 , 3
MUTE_RPL :id4, after bit5 , 4
DUMP :id3, after bit4 , 5
- :id2, after bit3 , 6
OP_MODE :id1, after id2 , 8
section Default
1 :d7, 0, 1
1 :d6, after bit7 , 2
1 :d5, after bit6 , 3
0 :d4, after bit5 , 4
0 :d3, after bit4 , 5
- :d2, after bit3 , 6
0 :d1, after d2 , 8
section Implementation
Optional :i7, 0, 1
Optional :i6, after bit7 , 2
Optional :i5, after bit6 , 3
Optional :i4, after bit5 , 4
Optional :i3, after bit4 , 5
- :i2, after bit3 , 6
a) :i1, after i2 , 8
a) Standby Mode and Active Mode are mandatory. Speed Mode is optional.
- OP_MODE [Bits 1:0]: These bits define the operation mode of the device. Note that, if Speed Mode is selected, the device will no longer reply to the HARP commands, only to its specific Speed Mode commands.
Table - Available Operation modes
| OP_MODE[1:0] | Configuration |
|---|---|
| 0 | Standby Mode. The device has all the Events turned off. |
| 1 | Active Mode. The device turns ON the Events detection. Only the enabled Events will be operating. |
| 2 | Reserved. |
| 3 | Speed Mode. The device enters Speed Mode. |
- DUMP [Bit 3]: When written to 1, the device adds the content of all registers to the streaming buffer as
Readmessages. This bit is always read as 0. - MUTE_RPL [Bit 4]: If set to 1, the
Repliesto all theCommandsare muted, i.e., they will not be sent by the device. - VISUALEN [Bit 5]: If set to 1, visual indications, typically LEDs, available on the device will operate. If equals to 0, all the visual indications should turn off.
- OPLEDEN [Bit 6]: If set to 1, the LED present on the device will indicate the Operation Mode selected.
Table - Visual LED toggle feedback
| Period (s) | Operation Mode |
|---|---|
| 4 | Standby Mode. |
| 2 | Active Mode. |
| 1 | Speed Mode. |
| 0.1 | A critical error occurred. Only a hardware reset or a new power up can remove the device from this Mode. |
- ALIVE_EN [Bit 7]: If set to 1, the device sends an
EventMessage with theR_HEARTBEATcontent each second. This allows the host to check the status of the device periodically. This is a required feature.
Address: 011
---
displayMode: compact
---
gantt
title R_RESET_DEV (011)
dateFormat X
axisFormat %
section Bit
7 :bit7, 0, 1
6 :bit6, after bit7 , 2
5 :bit5, after bit6 , 3
4 :bit4, after bit5 , 4
3 :bit3, after bit4 , 5
2 :bit2, after bit3 , 6
1 :bit1, after bit2 , 7
0 :bit0, after bit1 , 8
section Id
BOOT_EE :id7, 0, 1
BOOT_DEF :id6, after bit7 , 2
- :id5, after bit6 , 3
- :id4, after bit5 , 4
NAME_TO_DEFAULT :id3, after bit4 , 5
SAVE :id2, after bit3 , 6
RST_EE :id1, after id2 , 7
RST_DEF :id0, after id1 , 8
section Default
- :d7, 0, 1
- :d6, after bit7 , 2
- :d5, after bit6 , 3
- :d4, after bit5 , 4
0 :d3, after bit4 , 5
0 :d2, after bit3 , 6
0 :d1, after bit2 , 7
0 :d0, after bit1 , 8
-
RST_DEF [Bit 0]: If set to 1, the device resets and, reboots with all the registers, both
CommonandApplication, with the default values. EEPROM will be erased, and the default values will be restored as the permanent boot option. This bit is always read as 0. -
RST_EE [Bit 1]: If set to 1, the device resets and reboots with all the registers, both
CommonandApplicatinregisters, with the values saved on the non-volatile memory, usually an EEPROM. The EEPROM values will remain the permanent boot option. This bit is always read as 0. -
SAVE [Bit 3]: If set to 1, the device will save all the non-volatile registers (both
CommonandApplication) to the internal non-volatile memory, and reboot. The non-volatile memory should be the permanent boot option. -
NAME_TO_DEFAULT [Bit 4]: If set to 1, the device will reboot with the default name. This bit is always read as 0.
-
BOOT_DEF [Bit 6]: A read-only state bit that indicates whether the device booted with the default register values or not.
-
BOOT_EE [Bit 7]: A read-only state bit that indicates whether the device booted with the register values saved on the EEPROM or not.
Note
To avoid unexpected behaviors, only one bit at a time should be written to register
R_RESET_DEV.
Address: 012
An array of 25 bytes that should contain the device name. The last, and unused, bytes must be equal to 0. This register is non-volatile. The device will reset if this register is written to.
Address: 013
---
displayMode: compact
---
gantt
title R_SERIAL_NUMBER (013) [U16]
dateFormat X
axisFormat %
tickInterval 0
section Bit
15-8 :byte1, 0, 1
7-0 :byte0, after byte1 , 2
section Id
SERIAL_NUMBER :id1, 0, 2
section Default
- :d1, 0, 2
This number should be unique for each unit of the same Device ID.
To write to this register a two-step write command is needed. First, write the value 0xFFFF, and then the desired serial number (as a U16). The device will reset after the second write command is received.
Note
This register is to be deprecated in the near future in favor of the
R_UIDregister. Until then, we strongly encourage the value of this register to duplicate the first two bytes ofR_UID. In this case, similarly to the harp protocol specification, the two bytes should be packed in little-endian order.
Address: 014
---
displayMode: compact
---
gantt
title R_CLOCK_CONFIG (014)
dateFormat X
axisFormat %
section Bit
7 :bit7, 0, 1
6 :bit6, after bit7 , 2
5 :bit5, after bit6 , 3
4 :bit4, after bit5 , 4
3 :bit3, after bit4 , 5
2 :bit2, after bit3 , 6
1 :bit1, after bit2 , 7
0 :bit0, after bit1 , 8
section Id
CLK_LOCK :id7, 0, 1
CLK_UNLOCK :id6, after bit7 , 2
- :id5, after bit6 , 3
GEN_ABLE :id4, after bit5 , 4
REP_ABLE :id3, after bit4 , 5
- :id2, after bit3 , 6
CLK_GEN :id1, after id2 , 7
CLK_REP :id0, after id1 , 8
section Default
0 :d7, 0, 1
1 :d6, after bit7 , 2
- :d5, after bit6 , 3
- :d4, after bit5 , 4
- :d3, after bit4 , 5
- :d2, after bit3 , 6
- :d1, after bit2 , 7
- :d0, after bit1 , 8
-
CLK_REP [Bit 0]: If set to 1, the device will repeat the Harp Synchronization Clock to the Clock Output connector, if available. It will act has a daisy-chain, by repeating the Clock Input to the Clock Output. Setting this bit, also unlocks the Harp Synchronization Clock.
-
CLK_GEN [Bit 1]: If set to 1, the device will generate Harp Synchronization Clock to the Clock Output connector, if available. The Clock Input will be ignored. The bit is read as 1 if the device is generating the Harp Synchronization Clock.
-
REP_ABLE [Bit 3]: This is a read-only bit signaling if the device is able (1) to repeat the Harp Synchronization Clock timestamp.
-
GEN_ABLE [Bit 4]: This is a read-only bit signaling if the device is able (1) to generate the Harp Synchronization Clock timestamp.
-
CLK_UNLOCK [Bit 6]: If set to 1, the device will unlock the timestamp register counter (register
R_TIMESTAMP_SECOND) and it will now accept new timestamp values. The bit is read as 1 if the timestamp register is unlocked. -
CLK_LOCK [Bit 7]: If set to 1, the device will lock the current timestamp register counter (register
R_TIMESTAMP_SECOND) and it will reject any new timestamp values. The bit is read as 1 if the timestamp register is locked.
Note
The device always wakes up in the
unlockstate.
Address: 015
---
displayMode: compact
---
gantt
title R_TIMESTAMP_OFFSET (000) [U8]
dateFormat X
axisFormat %
tickInterval 0
section Bit
7-0 :byte1, 0, 1
section Id
UOFFSET :id1, 0, 1
section Default
0 :d1, 0, 1
When the value of this register is above 0 (zero), the device’s timestamp will be offset by this amount. The register is sensitive to 500 microsecond increments. This register is non-volatile.
Address: 016
An array of 16 bytes that should contain a (128bit) UID (Unique Identifier) of the current device. This register is non-volatile and should be read-only. The byte-order is little-endian.
Address: 017
An array of 8 bytes that can be used to store a tag for a specific firmware version. For instance, it could be used to store the git hash of a specific release/commit. If not used, all bytes should be set to 0. The byte-order is little-endian.
Address: 018
---
displayMode: compact
---
gantt
title R_HEARTBEAT (018)
dateFormat X
axisFormat %
section Bit
15-2 :reserved, 0, 1
1 :bit1, 1, 2
0 :bit0, 2, 3
section Id
- :idr, 0, 1
IS_ACTIVE :id0, 1, 2
IS_SYNCHRONIZED :id1, 2, 3
section Default
- :dr, 0, 1
- :d7, 1, 2
- :d6, 2, 3
Note
This register is read-only and is used to provide status information about the device. The bits are set by the device and sent through a period event. If enabled (via
R_OPERATION_CTRLbitALIVE_EN), the event will be periodically emitted at a rate of 1Hz, triggered by updates to theR_TIMESTAMP_SECONDregister.
The status of the device is given by the following bits:
-
IS_STANDBY [Bit 0]: If 1, the device will be in Standby Mode. Any other modes will be coded as 0. (See
R_OPERATION_CTRLbitOP_MODEfor more information). -
IS_SYNCHRONIZED [Bit 1]: If set to 1, the device is synchronized with an external Harp clock generator. If the device is itself a clock generator (see
R_CLOCK_CONFIGbitCLK_GEN), by definition, this bit will always be set to 1.
-
v0.2
- First draft released.
-
v1.0
- R_RESET_DEV and R_DEVICE_NAME are now optional.
- Changed Normal Mode to Standby Mode.
- Added bit ALIVE_EN to register R_OPERATION_CTRL. This is an important feature.
- Major release.
-
v1.1
- Added bit MUTE_RPL to register R_OPERATION_CTRL.
-
v1.2
- Corrected some wrong names.
-
v1.3
- Added the bit NAME_TO_DEFAULT.
-
v1.4
- Added the register R_SERIAL_NUMBER.
-
v1.5
- Added the register R_CLOCK_CONFIG.
-
v1.6
- Changed device naming to Controller and Peripheral.
-
v1.7
- Raised version to 1.2 since all the foreseen features are included at this point.
- Added the register R_TIMESTAMP_OFFSET.
-
v1.8
- Replaced HARP_VERSION with CORE_VERSION.
-
v1.9.0
- Refactor documentation to markdown format.
- Minor typo corrections.
- Improve clarity of some sections.
- Adopt semantic versioning.
-
v1.9.1
- Remove table of contents to avoid redundancy with doc generators.
- Minor improvements to clarity of introduction.
-
v1.9.2
- Clarify
Connectedbehavior between host and device and add application examples.
- Clarify
-
v1.10.0
- Add
UIDregister - Add future deprecation warning to
R_SERIAL_NUMBERregister.
- Add
-
v1.11.0
- Add new
Tagregister.
- Add new
-
v1.12.0
- Add heartbeat register providing status information
- Fix typo in
OPERATION_CTRLregister data type (U16 -> U8)