harp-serial#

A Python library for communicating with Harp devices over serial connections.

Installation#

uv add harp-serial
# or
pip install harp-serial

Quick Start#

from harp.protocol import MessageType, PayloadType
from harp.protocol.messages import HarpMessage
from harp.serial.device import Device

# Connect to a device
device = Device("/dev/ttyUSB0")
#device = Device("COM3")  # for Windows

# Get device information
device.info()

# define register_address
register_address = 32

# Read from register
reply = device.send(HarpMessage.create(MessageType.READ, register_address, PayloadType.U8))

# Write to register
device.send(HarpMessage.create(MessageType.WRITE, register_address, PayloadType.U8, reply.payload))

# Disconnect when done
device.disconnect()

or using the with statement:

from harp.protocol import MessageType, PayloadType
from harp.protocol.messages import HarpMessage
from harp.serial.device import Device

with Device("/dev/ttyUSB0") as device:
    # Get device information
    device.info()

    # define register_address
    register_address = 32

    # Read from register
    reply = device.send(HarpMessage.create(MessageType.READ, register_address, PayloadType.U8))

    # Write to register
    device.send(HarpMessage.create(MessageType.WRITE, register_address, PayloadType.U8, reply.payload))

for Linux#

Install UDEV Rules#

Install by either copying 10-harp.rules over to your /etc/udev/rules.d folder or by symlinking it with:

sudo ln -s /absolute/path/to/10-harp.rules /etc/udev/rules.d/10-harp.rules

Then reload udev rules with

sudo udevadm control --reload-rules

`harp.serial.Device` #

The Device class provides the interface for interacting with Harp devices. This implementation of the Harp device was based on the official documentation available on the harp-tech website.

Attributes:

Name	Type	Description
`WHO_AM_I`	`int`	The device ID number. A list of devices can be found here
`DEFAULT_DEVICE_NAME`	`str`	The device name, i.e. "Behavior". This name is derived by cross-referencing the `WHO_AM_I` identifier with the corresponding device name in the `device_names` dictionary
`HW_VERSION_H`	`int`	The major hardware version
`HW_VERSION_L`	`int`	The minor hardware version
`ASSEMBLY_VERSION`	`int`	The version of the assembled components
`HARP_VERSION_H`	`int`	The major Harp core version
`HARP_VERSION_L`	`int`	The minor Harp core version
`FIRMWARE_VERSION_H`	`int`	The major firmware version
`FIRMWARE_VERSION_L`	`int`	The minor firmware version
`DEVICE_NAME`	`str`	The device name stored in the Harp device
`SERIAL_NUMBER`	`(int, optional)`	The serial number of the device

`enter()` #

Support for using Device with 'with' statement.

Returns:

Type	Description
`Device`	The Device instance

`exit(exc_type, exc_val, exc_tb)` #

Cleanup resources when exiting the 'with' block.

Parameters:

Name	Type	Description	Default
`exc_type`	`Exception type or None`	Type of the exception that caused the context to be exited	required
`exc_val`	`Exception or None`	Exception instance that caused the context to be exited	required
`exc_tb`	`traceback or None`	Traceback if an exception occurred	required

`init(serial_port, dump_file_path=None, read_timeout_s=1, timeout_strategy=TimeoutStrategy.RAISE)` #

Parameters:

Name	Type	Description	Default
`serial_port`	`str`	The serial port used to establish the connection with the Harp device. It must be denoted as `/dev/ttyUSBx` in Linux and `COMx` in Windows, where `x` is the number of the serial port	required
`dump_file_path`	`Optional[str]`	The binary file to which all Harp messages will be written	`None`
`read_timeout_s`	`float`	TODO	`1`

`alive_en(enable)` #

Sets the ALIVE_EN bit of the device.

Parameters:

Name	Type	Description	Default
`enable`	`bool`	If True, enables the ALIVE_EN bit. If False, disables it	required

Returns:

Type	Description
`bool`	True if the operation was successful, False otherwise

`connect()` #

Connects to the Harp device.

`disconnect()` #

Disconnects from the Harp device.

`dump_registers()` #

Asserts the DUMP bit to dump the values of all core and app registers as Harp Read Reply Messages. More information on the DUMP bit can be found here.

Returns:

Type	Description
`list`	The list containing the reply Harp messages for all the device's registers

`event_count()` #

Gets the number of events in the event queue.

Returns:

Type	Description
`int`	The number of events in the event queue

`get_events()` #

Gets all events from the event queue.

Returns:

Type	Description
`list`	The list containing every Harp event message that were on the queue

`info()` #

Prints the device information.

`load()` #

Loads the data stored in the device's common registers.

`mute_reply(enable)` #

Sets the MUTE_REPLY bit of the device.

Parameters:

Name	Type	Description	Default
`enable`	`bool`	If True, the Replies to all the Commands are muted. If False, un-mutes them	required

Returns:

Type	Description
`bool`	True if the operation was successful, False otherwise

`op_led_en(enable)` #

Sets the operation LED of the device.

Parameters:

Name	Type	Description	Default
`enable`	`bool`	If True, enables the operation LED. If False, disables it	required

Returns:

Type	Description
`bool`	True if the operation was successful, False otherwise

`read_float(address)` #

Reads the value of a register of type Float.

Parameters:

Name	Type	Description	Default
`address`	`int`	The register to be read	required

Returns:

Type	Description
`ReplyHarpMessage`	The reply to the Harp message that will contain the value read from the register

Raises:

Type	Description
`HarpTimeoutError`	If no reply is received and the effective strategy requires raising

`read_operation_ctrl()` #

Reads the OPERATION_CTRL register of the device.

Returns:

Type	Description
`ReplyHarpMessage`	The reply to the Harp message

`read_s16(address)` #

Reads the value of a register of type S16.

Parameters:

Name	Type	Description	Default
`address`	`int`	The register to be read	required

Returns:

Type	Description
`ReplyHarpMessage`	The reply to the Harp message that will contain the value read from the register

Raises:

Type	Description
`HarpTimeoutError`	If no reply is received and the effective strategy requires raising

`read_s32(address)` #

Reads the value of a register of type S32.

Parameters:

Name	Type	Description	Default
`address`	`int`	The register to be read	required

Returns:

Type	Description
`ReplyHarpMessage`	The reply to the Harp message that will contain the value read from the register

Raises:

Type	Description
`HarpTimeoutError`	If no reply is received and the effective strategy requires raising

`read_s64(address)` #

Reads the value of a register of type S64.

Parameters:

Name	Type	Description	Default
`address`	`int`	The register to be read	required

Returns:

Type	Description
`ReplyHarpMessage`	The reply to the Harp message that will contain the value read from the register

Raises:

Type	Description
`HarpTimeoutError`	If no reply is received and the effective strategy requires raising

`read_s8(address)` #

Reads the value of a register of type S8.

Parameters:

Name	Type	Description	Default
`address`	`int`	The register to be read	required

Returns:

Type	Description
`ReplyHarpMessage`	The reply to the Harp message that will contain the value read from the register

Raises:

Type	Description
`HarpTimeoutError`	If no reply is received and the effective strategy requires raising

`read_u16(address)` #

Reads the value of a register of type U16.

Parameters:

Name	Type	Description	Default
`address`	`int`	The register to be read	required

Returns:

Type	Description
`ReplyHarpMessage`	The reply to the Harp message that will contain the value read from the register

Raises:

Type	Description
`HarpTimeoutError`	If no reply is received and the effective strategy requires raising

`read_u32(address)` #

Reads the value of a register of type U32.

Parameters:

Name	Type	Description	Default
`address`	`int`	The register to be read	required

Returns:

Type	Description
`ReplyHarpMessage`	The reply to the Harp message that will contain the value read from the register

Raises:

Type	Description
`HarpTimeoutError`	If no reply is received and the effective strategy requires raising

`read_u64(address)` #

Reads the value of a register of type U64.

Parameters:

Name	Type	Description	Default
`address`	`int`	The register to be read	required

Returns:

Type	Description
`ReplyHarpMessage`	The reply to the Harp message that will contain the value read from the register

Raises:

Type	Description
`HarpTimeoutError`	If no reply is received and the effective strategy requires raising

`read_u8(address)` #

Reads the value of a register of type U8.

Parameters:

Name	Type	Description	Default
`address`	`int`	The register to be read	required

Returns:

Type	Description
`ReplyHarpMessage`	The reply to the Harp message that will contain the value read from the register

Raises:

Type	Description
`HarpTimeoutError`	If no reply is received and the effective strategy requires raising

`reset_device(reset_mode=ResetMode.RST_DEF)` #

Resets the device and reboots with all the registers with the default values. Beware that the EEPROM will be erased. More information on the reset device register can be found here.

Returns:

Type	Description
`ReplyHarpMessage`	The reply to the Harp message

`send(message, *, expect_reply=True, timeout_strategy=None)` #

Sends a Harp message and (optionally) waits for a reply.

Parameters:

Name	Type	Description	Default
`message`	`HarpMessage`	The HarpMessage to be sent to the device	required
`expect_reply`	`bool`	If False, do not wait for a reply (fire-and-forget)	`True`
`timeout_strategy`	`TimeoutStrategy \| None`	Override the device-level timeout strategy for this call	`None`

Returns:

Type	Description
`ReplyHarpMessage \| None`	Reply (or None when allowed by the timeout strategy or expect_reply=False)

Raises:

Type	Description
`HarpTimeoutError`	If no reply is received and the effective strategy requires raising

`set_clock_config(clock_config)` #

Sets the clock configuration of the device.

Parameters:

Name	Type	Description	Default
`clock_config`	`ClockConfig`	The clock configuration value	required

Returns:

Type	Description
`ReplyHarpMessage`	The reply to the Harp message

`set_mode(mode)` #

Sets the operation mode of the device.

Parameters:

Name	Type	Description	Default
`mode`	`DeviceMode`	The new device mode value	required

Returns:

Type	Description
`ReplyHarpMessage`	The reply to the Harp message

`set_timestamp_offset(timestamp_offset)` #

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.

Parameters:

Name	Type	Description	Default
`timestamp_offset`	`int`	The timestamp offset value	required

Returns:

Type	Description
`ReplyHarpMessage`	The reply to the Harp message

`visual_en(enable)` #

Sets the status led of the device.

Parameters:

Name	Type	Description	Default
`enable`	`bool`	If True, enables the status led. If False, disables it	required

Returns:

Type	Description
`bool`	True if the operation was successful, False otherwise

`write_float(address, value)` #

Writes the value of a register of type Float.

Parameters:

Name	Type	Description	Default
`address`	`int`	The register to be written on	required
`value`	`float \| list[float]`	The value to be written to the register	required

Returns:

Type	Description
`ReplyHarpMessage`	The reply to the Harp message

Raises:

Type	Description
`HarpTimeoutError`	If no reply is received and the effective strategy requires raising

`write_operation_ctrl(mode=None, mute_rpl=None, visual_en=None, op_led_en=None, alive_en=None)` #

Writes the OPERATION_CTRL register of the device.

Parameters:

Name	Type	Description	Default
`mode`	`OperationMode`	The new operation mode value	`None`
`mute_rpl`	`bool`	If True, the Replies to all the Commands are muted	`None`
`visual_en`	`bool`	If True, enables the status led	`None`
`op_led_en`	`bool`	If True, enables the operation LED	`None`
`alive_en`	`bool`	If True, enables the ALIVE_EN bit	`None`

Returns:

Type	Description
`ReplyHarpMessage`	The reply to the Harp message

`write_s16(address, value)` #

Writes the value of a register of type S16.

Parameters:

Name	Type	Description	Default
`address`	`int`	The register to be written on	required
`value`	`int \| list[int]`	The value to be written to the register	required

Returns:

Type	Description
`ReplyHarpMessage`	The reply to the Harp message

Raises:

Type	Description
`HarpTimeoutError`	If no reply is received and the effective strategy requires raising

`write_s32(address, value)` #

Writes the value of a register of type S32.

Parameters:

Name	Type	Description	Default
`address`	`int`	The register to be written on	required
`value`	`int \| list[int]`	The value to be written to the register	required

Returns:

Type	Description
`ReplyHarpMessage`	The reply to the Harp message

Raises:

Type	Description
`HarpTimeoutError`	If no reply is received and the effective strategy requires raising

`write_s64(address, value)` #

Writes the value of a register of type S64.

Parameters:

Name	Type	Description	Default
`address`	`int`	The register to be written on	required
`value`	`int \| list[int]`	The value to be written to the register	required

Returns:

Type	Description
`ReplyHarpMessage`	The reply to the Harp message

Raises:

Type	Description
`HarpTimeoutError`	If no reply is received and the effective strategy requires raising

`write_s8(address, value)` #

Writes the value of a register of type S8.

Parameters:

Name	Type	Description	Default
`address`	`int`	The register to be written on	required
`value`	`int \| list[int]`	The value to be written to the register	required

Returns:

Type	Description
`ReplyHarpMessage`	The reply to the Harp message

Raises:

Type	Description
`HarpTimeoutError`	If no reply is received and the effective strategy requires raising

`write_u16(address, value)` #

Writes the value of a register of type U16.

Parameters:

Name	Type	Description	Default
`address`	`int`	The register to be written on	required
`value`	`int \| list[int]`	The value to be written to the register	required

Returns:

Type	Description
`ReplyHarpMessage`	The reply to the Harp message

Raises:

Type	Description
`HarpTimeoutError`	If no reply is received and the effective strategy requires raising

`write_u32(address, value)` #

Writes the value of a register of type U32.

Parameters:

Name	Type	Description	Default
`address`	`int`	The register to be written on	required
`value`	`int \| list[int]`	The value to be written to the register	required

Returns:

Type	Description
`ReplyHarpMessage`	The reply to the Harp message

Raises:

Type	Description
`HarpTimeoutError`	If no reply is received and the effective strategy requires raising

`write_u64(address, value)` #

Writes the value of a register of type U64.

Parameters:

Name	Type	Description	Default
`address`	`int`	The register to be written on	required
`value`	`int \| list[int]`	The value to be written to the register	required

Returns:

Type	Description
`ReplyHarpMessage`	The reply to the Harp message

Raises:

Type	Description
`HarpTimeoutError`	If no reply is received and the effective strategy requires raising

`write_u8(address, value)` #

Writes the value of a register of type U8.

Parameters:

Name	Type	Description	Default
`address`	`int`	The register to be written on	required
`value`	`int \| list[int]`	The value to be written to the register	required

Returns:

Type	Description
`ReplyHarpMessage`	The reply to the Harp message

Raises:

Type	Description
`HarpTimeoutError`	If no reply is received and the effective strategy requires raising

`harp.serial.TimeoutStrategy` #

Bases: Enum

Strategy to handle timeouts when waiting for a reply from the device.

Attributes:

Name	Type	Description
`RAISE`	`str`	Raise HarpTimeoutError
`RETURN_NONE`	`str`	Return None
`LOG_AND_RAISE`	`str`	Log the timeout and raise HarpTimeoutError
`LOG_AND_NONE`	`str`	Log the timeout and return None

harp-serial#

Installation#

Quick Start#

for Linux#

Install UDEV Rules#

harp.serial.Device #

__enter__() #

__exit__(exc_type, exc_val, exc_tb) #

__init__(serial_port, dump_file_path=None, read_timeout_s=1, timeout_strategy=TimeoutStrategy.RAISE) #

alive_en(enable) #

connect() #

disconnect() #

dump_registers() #

event_count() #

get_events() #

info() #

load() #

mute_reply(enable) #

op_led_en(enable) #

read_float(address) #

read_operation_ctrl() #

read_s16(address) #

read_s32(address) #

read_s64(address) #

read_s8(address) #

read_u16(address) #

read_u32(address) #

read_u64(address) #

read_u8(address) #

reset_device(reset_mode=ResetMode.RST_DEF) #

send(message, *, expect_reply=True, timeout_strategy=None) #

set_clock_config(clock_config) #

set_mode(mode) #

set_timestamp_offset(timestamp_offset) #

visual_en(enable) #

write_float(address, value) #

write_operation_ctrl(mode=None, mute_rpl=None, visual_en=None, op_led_en=None, alive_en=None) #

write_s16(address, value) #

write_s32(address, value) #

write_s64(address, value) #

write_s8(address, value) #

write_u16(address, value) #

write_u32(address, value) #

write_u64(address, value) #

write_u8(address, value) #

harp.serial.TimeoutStrategy #

`harp.serial.Device` #

`enter()` #

`exit(exc_type, exc_val, exc_tb)` #

`init(serial_port, dump_file_path=None, read_timeout_s=1, timeout_strategy=TimeoutStrategy.RAISE)` #

`alive_en(enable)` #

`connect()` #

`disconnect()` #

`dump_registers()` #

`event_count()` #

`get_events()` #

`info()` #

`load()` #

`mute_reply(enable)` #

`op_led_en(enable)` #

`read_float(address)` #

`read_operation_ctrl()` #

`read_s16(address)` #

`read_s32(address)` #

`read_s64(address)` #

`read_s8(address)` #

`read_u16(address)` #

`read_u32(address)` #

`read_u64(address)` #

`read_u8(address)` #

`reset_device(reset_mode=ResetMode.RST_DEF)` #

`send(message, *, expect_reply=True, timeout_strategy=None)` #

`set_clock_config(clock_config)` #

`set_mode(mode)` #

`set_timestamp_offset(timestamp_offset)` #

`visual_en(enable)` #

`write_float(address, value)` #

`write_operation_ctrl(mode=None, mute_rpl=None, visual_en=None, op_led_en=None, alive_en=None)` #

`write_s16(address, value)` #

`write_s32(address, value)` #

`write_s64(address, value)` #

`write_s8(address, value)` #

`write_u16(address, value)` #

`write_u32(address, value)` #

`write_u64(address, value)` #

`write_u8(address, value)` #

`harp.serial.TimeoutStrategy` #