harp-protocol#
The Harp Protocol is a binary communication protocol created in order to facilitate and unify the interaction between different devices. It was designed with efficiency and ease of parsing in mind.
For more detail please check Harp Tech's official documentation here.
harp.protocol.MessageType
#
Bases: IntEnum
An enumeration of the allowed message types of a Harp message. More information on the MessageType byte of a Harp message can be found here.
Attributes:
| Name | Type | Description |
|---|---|---|
READ |
int
|
The value that corresponds to a Read Harp message (1) |
WRITE |
int
|
The value that corresponds to a Write Harp message (2) |
EVENT |
int
|
The value that corresponds to an Event Harp message (3). Messages of this type are only meant to be send by the device |
READ_ERROR |
int
|
The value that corresponds to a Read Error Harp message (9). Messages of this type are only meant to be send by the device |
WRITE_ERROR |
int
|
The value that corresponds to a Write Error Harp message (10). Messages of this type are only meant to be send by the device |
harp.protocol.PayloadType
#
Bases: IntEnum
An enumeration of the allowed payload types of a Harp message. More information on the PayloadType byte of a Harp message can be found here.
Attributes:
| Name | Type | Description |
|---|---|---|
U8 |
int
|
The value that corresponds to a message of type U8 |
S8 |
int
|
The value that corresponds to a message of type S8 |
U16 |
int
|
The value that corresponds to a message of type U16 |
S16 |
int
|
The value that corresponds to a message of type S16 |
U32 |
int
|
The value that corresponds to a message of type U32 |
S32 |
int
|
The value that corresponds to a message of type S32 |
U64 |
int
|
The value that corresponds to a message of type U64 |
S64 |
int
|
The value that corresponds to a message of type S64 |
Float |
int
|
The value that corresponds to a message of type Float |
Timestamp |
int
|
The value that corresponds to a message of type Timestamp. This is not a valid PayloadType, but it is used to indicate that the message has a timestamp. |
TimestampedU8 |
int
|
The value that corresponds to a message of type TimestampedU8 |
TimestampedS8 |
int
|
The value that corresponds to a message of type TimestampedS8 |
TimestampedU16 |
int
|
The value that corresponds to a message of type TimestampedU16 |
TimestampedS16 |
int
|
The value that corresponds to a message of type TimestampedS16 |
TimestampedU32 |
int
|
The value that corresponds to a message of type TimestampedU32 |
TimestampedS32 |
int
|
The value that corresponds to a message of type TimestampedS32 |
TimestampedU64 |
int
|
The value that corresponds to a message of type TimestampedU64 |
TimestampedS64 |
int
|
The value that corresponds to a message of type TimestampedS64 |
TimestampedFloat |
int
|
The value that corresponds to a message of type TimestampedFloat |
harp.protocol.CommonRegisters
#
Bases: IntEnum
An enumeration with the registers that are common to every Harp device. More information on the common registers can be found here.
Attributes:
| Name | Type | Description |
|---|---|---|
WHO_AM_I |
int
|
The number of the |
HW_VERSION_H |
int
|
The number of the |
HW_VERSION_L |
int
|
The number of the |
ASSEMBLY_VERSION |
int
|
The number of the |
HARP_VERSION_H |
int
|
The number of the |
HARP_VERSION_L |
int
|
The number of the |
FIRMWARE_VERSION_H |
int
|
The number of the |
FIRMWARE_VERSION_L |
int
|
The number of the |
TIMESTAMP_SECOND |
int
|
The number of the |
TIMESTAMP_MICRO |
int
|
The number of the |
OPERATION_CTRL |
int
|
The number of the |
RESET_DEV |
int
|
The number of the |
DEVICE_NAME |
int
|
The number of the |
SERIAL_NUMBER |
int
|
The number of the |
CLOCK_CONFIG |
int
|
The number of the |
TIMESTAMP_OFFSET |
int
|
The number of the |
harp.protocol.OperationMode
#
Bases: IntEnum
An enumeration with the operation modes of a Harp device. More information on the operation modes can be found here.
Attributes:
| Name | Type | Description |
|---|---|---|
STANDBY |
int
|
The value that corresponds to the Standby operation mode (0). The device has all the Events turned off |
ACTIVE |
int
|
The value that corresponds to the Active operation mode (1). The device turns ON the Events detection. Only the enabled Events will be operating |
RESERVED |
int
|
The value that corresponds to the Reserved operation mode (2) |
SPEED |
int
|
The value that corresponds to the Speed operation mode (3). The device enters Speed Mode |
harp.protocol.OperationCtrl
#
Bases: IntFlag
An enumeration with the operation control bits of a Harp device. More information on the operation control bits can be found here.
Attributes:
| Name | Type | Description |
|---|---|---|
OP_MODE |
int
|
Bits 1:0 (0x03): Operation mode of the device. 0: Standby Mode (all Events off, mandatory) 1: Active Mode (Events detection enabled, mandatory) 2: Reserved 3: Speed Mode (device enters Speed Mode, optional; only responds to Speed Mode commands) |
DUMP |
int
|
Bit 3 (0x08): When set to 1, the device adds the content of all registers to the streaming buffer as Read messages. Always read as 0 |
MUTE_RPL |
int
|
Bit 4 (0x10): If set to 1, replies to all commands are muted (not sent by the device) |
VISUALEN |
int
|
Bit 5 (0x20): If set to 1, visual indications (e.g., LEDs) operate. If 0, all visual indications are turned off |
OPLEDEN |
int
|
Bit 6 (0x40): If set to 1, the LED indicates the selected Operation Mode (see LED feedback table in documentation) |
ALIVE_EN |
int
|
Bit 7 (0x80): If set to 1, the device sends an Event Message with the R_TIMESTAMP_SECONDS content each second (heartbeat) |
harp.protocol.ResetMode
#
Bases: IntEnum
An enumeration with the reset modes and actions for the R_RESET_DEV register of a Harp device. More information on the reset modes can be found here.
Attributes:
| Name | Type | Description |
|---|---|---|
RST_DEF |
int
|
Bit 0 (0x01): If set, resets the device and restores all registers (Common and Application) to default values. EEPROM is erased and defaults become the permanent boot option |
RST_EE |
int
|
Bit 1 (0x02): If set, resets the device and restores all registers (Common and Application) from non-volatile memory (EEPROM). EEPROM values remain the permanent boot option |
SAVE |
int
|
Bit 3 (0x08): If set, saves all non-volatile registers (Common and Application) to EEPROM and reboots. EEPROM becomes the permanent boot option |
NAME_TO_DEFAULT |
int
|
Bit 4 (0x10): If set, reboots the device with the default name |
BOOT_DEF |
int
|
Bit 6 (0x40, read-only): Indicates the device booted with default register values |
BOOT_EE |
int
|
Bit 7 (0x80, read-only): Indicates the device booted with register values saved on the EEPROM |
harp.protocol.ClockConfig
#
Bases: IntFlag
An enumeration with the clock configuration bits for the R_CLOCK_CONFIG register of a Harp device. More information can be found here.
Attributes:
| Name | Type | Description |
|---|---|---|
CLK_REP |
int
|
Bit 0 (0x01): If set to 1, the device will repeat the Harp Synchronization Clock to the Clock Output connector, if available. Acts as a daisy-chain by repeating the Clock Input to the Clock Output. Setting this bit also unlocks the Harp Synchronization Clock |
CLK_GEN |
int
|
Bit 1 (0x02): If set to 1, the device will generate Harp Synchronization Clock to the Clock Output connector, if available. The Clock Input will be ignored. Read as 1 if the device is generating the Harp Synchronization Clock |
REP_ABLE |
int
|
Bit 3 (0x08, read-only): Indicates if the device is able (1) to repeat the Harp Synchronization Clock timestamp |
GEN_ABLE |
int
|
Bit 4 (0x10, read-only): Indicates if the device is able (1) to generate the Harp Synchronization Clock timestamp |
CLK_UNLOCK |
int
|
Bit 6 (0x40): If set to 1, the device will unlock the timestamp register counter (R_TIMESTAMP_SECOND) and accept new timestamp values. Read as 1 if the timestamp register is unlocked |
CLK_LOCK |
int
|
Bit 7 (0x80): If set to 1, the device will lock the current timestamp register counter (R_TIMESTAMP_SECOND) and reject new timestamp values. Read as 1 if the timestamp register is locked |
harp.protocol.messages.HarpMessage
#
The HarpMessage class implements the Harp message as described in the protocol.
Attributes:
| Name | Type | Description |
|---|---|---|
frame |
bytearray
|
The bytearray containing the whole Harp message |
message_type |
MessageType
|
The message type |
length |
int
|
The length parameter of the Harp message |
address |
int
|
The address of the register to which the Harp message refers to |
port |
int
|
Indicates the origin or destination of the Harp message in case the device is a hub of Harp devices. The value 255 points to the device itself (default value). |
payload_type |
PayloadType
|
The payload type |
checksum |
int
|
The sum of all bytes contained in the Harp message |
address
property
#
The address of the register to which the Harp message refers to.
Returns:
| Type | Description |
|---|---|
int
|
The address of the register to which the Harp message refers to |
checksum
property
#
The sum of all bytes contained in the Harp message.
Returns:
| Type | Description |
|---|---|
int
|
The sum of all bytes contained in the Harp message |
frame
property
#
The bytearray containing the whole Harp message.
Returns:
| Type | Description |
|---|---|
bytearray
|
The bytearray containing the whole Harp message |
length
property
#
The length parameter of the Harp message.
Returns:
| Type | Description |
|---|---|
int
|
The length parameter of the Harp message |
message_type
property
#
payload
property
#
The payload sent in the write Harp message.
Returns:
| Type | Description |
|---|---|
Union[int, list[int]]
|
The payload sent in the write Harp message |
payload_type
property
#
port
property
writable
#
Indicates the origin or destination of the Harp message in case the device is a hub of Harp devices. The value 255 points to the device itself (default value).
Returns:
| Type | Description |
|---|---|
int
|
The port value |
__repr__()
#
Prints debug representation of the reply message.
Returns:
| Type | Description |
|---|---|
str
|
The debug representation of the reply message |
__str__()
#
Prints friendly representation of a Harp message.
Returns:
| Type | Description |
|---|---|
str
|
The representation of the Harp message |
calculate_checksum()
#
Calculates the checksum of the Harp message.
Returns:
| Type | Description |
|---|---|
int
|
The value of the checksum |
create(message_type, address, payload_type, value=None)
staticmethod
#
Creates a Harp message.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message_type
|
MessageType
|
The message type. It can only be of type READ or WRITE |
required |
address
|
int
|
The address of the register that the message will interact with |
required |
payload_type
|
PayloadType
|
The payload type |
required |
value
|
Optional[int | list[int] | float | list[float]]
|
The payload of the message. If message_type == MessageType.WRITE, the value cannot be None |
None
|
parse(frame)
staticmethod
#
Parses a bytearray to a (reply) Harp message.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
frame
|
bytearray
|
The bytearray will be parsed into a (reply) Harp message |
required |
Returns:
| Type | Description |
|---|---|
ReplyHarpMessage
|
The Harp message object parsed from the original bytearray |
harp.protocol.messages.ReplyHarpMessage
#
Bases: HarpMessage
A response message from a Harp device.
Attributes:
| Name | Type | Description |
|---|---|---|
payload |
Union[int, list[int]]
|
The message payload formatted as the appropriate type |
timestamp |
float
|
The Harp timestamp at which the message was sent |
is_error
property
#
Indicates if this HarpMessage is an error message or not.
Returns:
| Type | Description |
|---|---|
bool
|
Returns True if this HarpMessage is an error message, False otherwise. |
timestamp
property
#
The Harp timestamp at which the message was sent.
Returns:
| Type | Description |
|---|---|
float
|
The Harp timestamp at which the message was sent |
__init__(frame)
#
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
frame
|
bytearray
|
The Harp message in bytearray format |
required |
payload_as_string()
#
Returns the payload as a str.
Returns:
| Type | Description |
|---|---|
str
|
The payload parsed as a str |
harp.protocol.messages.ReadHarpMessage
#
harp.protocol.messages.WriteHarpMessage
#
Bases: HarpMessage
A write Harp message sent to a Harp device.
Attributes:
| Name | Type | Description |
|---|---|---|
payload |
Union[int, list[int]]
|
The payload sent in the write Harp message |
__init__(payload_type, address, value)
#
Create a WriteHarpMessage to send to a device.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
payload_type
|
PayloadType
|
Type of payload (U8, S8, U16, etc.) |
required |
address
|
int
|
Register address to write to |
required |
value
|
int, float, List[int], or List[float]
|
Value(s) to write - can be a single value or list of values |
required |
Note
The message frame is constructed according to the HARP binary protocol. The length is calculated as BASE_LENGTH + payload size in bytes.