Device Registers

---

Registers

The Harp protocol relies on registers with specific functionalities and data types, and are essentially used to exchange information with the device.

The Harp Current Driver registers are declared in the device's device.yml file.

These register names are used by the software and will be described here according with their functionality, for quick reference and easier understanding.

Some registers support multiple states, by using bit masks, where each bit represents a specific state. In contrast, group masks are typically used for configuration, allowing only one state to be active at a time.

bit mask

A bit mask is a binary pattern used to manipulate specific bits within a value. It helps selectively enable, disable, or extract particular bits in the registers.

---

LED current

The current of each LED output is configured, in mA, through the Led0Current and Led1Current registers. The accepted range is 0 to 500 mA, and the new value is applied immediately.

The Led0MaxCurrent and Led1MaxCurrent registers specify the maximum current, in mA, allowed for the corresponding LED output, and can be used to protect LEDs rated for currents below 500 mA. The default value is 100 mA.

maximum current

Always check the maximum continuous and pulsed current of the connected LED in its datasheet before configuring the current of the output.

---

DAC voltage

The voltage of each DAC output is configured, in mV, through the Dac0Voltage and Dac1Voltage registers. The accepted range is 0 to 5000 mV.

The DAC of each channel is shared between its DAC output and its LED output. For the LED output, the DacXVoltage value corresponds to a current of:

I_LED [mA] = DacXVoltage [mV] / 5

i.e. Dac0Voltage = 2500 mV corresponds to the full scale of 500 mA in the LED0 output.

pulses and ramps

In the current firmware version, the pulse and ramp functions act on the value of the DacXVoltage registers. To generate pulses or ramps on an LED output, configure the corresponding DacXVoltage register (with values up to 2500 mV, according to the equation above) instead of the LedXCurrent register.

---

LED drivers

Each LED driver can be enabled or disabled without changing its configured set point. Both drivers are enabled after power-up.

For each one of the registers LedEnable, LedDisable and LedState, you can set the correspondent bit mask for the LED output(s) you need to configure:

Name	Hex mask	Binary mask
LED0	0x01	0b00000001
LED1	0x02	0b00000010

• LedEnable: enables the LED drivers whose bits are set in the written mask.
• LedDisable: disables the LED drivers whose bits are set in the written mask.
• LedState: writes the state of both LED drivers at once (bit set enables the driver, bit cleared disables it).

---

Pulses

The pulse function makes a channel alternate between its configured value and zero. It is enabled through the PulseEnable register, using the same bit mask as the LED drivers:

Name	Hex mask	Binary mask
LED0	0x01	0b00000001
LED1	0x02	0b00000010

The pulse train of each channel is configured through:

• PulseFrequencyLed0 / PulseFrequencyLed1: frequency of the pulse train, in Hz (1 to 255).
• PulseDutyCycleLed0 / PulseDutyCycleLed1: percentage of each period in which the output is on (1 to 100).

Pulses are generated by the device with a time resolution of 1 ms, so the on and off times are rounded to the millisecond. At high frequencies, choose duty cycles that result in integer on times (e.g. at 100 Hz, the period is 10 ms and each 10 % of duty cycle corresponds to 1 ms).

configuration order

Configure the frequency before the duty cycle, as the pulse timings are computed from both values.

---

Ramps

Ramps make the transitions between two different values of a channel linear over time, instead of immediate. The duration of the ramp of each channel is configured, in ms, through the RampLed0 and RampLed1 registers (1 to 65535 ms).

The RampConfig register selects on which transitions the ramps are applied, using the following bit mask:

Name	Hex mask	Binary mask	Description
LED0_UP	0x01	0b00000001	Ramp on rising transitions of LED0
LED0_DOWN	0x02	0b00000010	Ramp on falling transitions of LED0
LED1_UP	0x04	0b00000100	Ramp on rising transitions of LED1
LED1_DOWN	0x08	0b00001000	Ramp on falling transitions of LED1

ramps and pulses

Ramps are only applied while the pulse function of the corresponding channel is disabled.

---

Digital IOs

Two digital inputs and two digital outputs are available in the device.

Digital inputs

The state of the digital inputs is reported by the DigitalInputState event, which is emitted every time a transition is detected on an input line. The register uses the following bit mask:

Name	Hex mask	Binary mask
DI0	0x01	0b00000001
DI1	0x02	0b00000010

events

If no events are received from the DigitalInputState register, ensure that the correspondent bit of the EnableEvents register bit mask is set, specifically DIs(0x1).

Digital outputs

The digital outputs can be controlled through the registers OutputSet, OutputClear, OutputToggle and OutputState.

For each one of these registers, you can set the correspondent bit mask for the digital output(s) you need to configure:

Name	Hex mask	Binary mask
DO0	0x01	0b00000001
DO1	0x02	0b00000010

• OutputSet: sets the output lines whose bits are set in the written mask.
• OutputClear: clears the output lines whose bits are set in the written mask.
• OutputToggle: toggles the output lines whose bits are set in the written mask.
• OutputState: writes the state of all output lines at once.

state registers

State registers enable setting and clearing multiple states simultaneously, which is especially useful for precise timing, e.g. when the user needs to switch multiple outputs with different states at the same time.

---

Events

The events published by the device are configured through the EnableEvents register, using the bit mask below. Only the events whose bit is set are sent by the device. The digital inputs event is enabled by default.

Name	Hex mask	Binary mask
DIs	0x01	0b00000001

---

Register summary

Address	Register	Access	Type	Description
32	DigitalInputState	Event	U8	State of the digital inputs.
33	OutputSet	Write	U16	Sets the specified digital output lines.
34	OutputClear	Write	U16	Clears the specified digital output lines.
35	OutputToggle	Write	U16	Toggles the specified digital output lines.
36	OutputState	Write	U16	Writes the state of all digital output lines.
37	Led0Current	Write	Float	Current of LED 0 output [0:500] mA.
38	Led1Current	Write	Float	Current of LED 1 output [0:500] mA.
39	Dac0Voltage	Write	Float	Voltage of DAC 0 output [0:5000] mV.
40	Dac1Voltage	Write	Float	Voltage of DAC 1 output [0:5000] mV.
41	LedEnable	Write	U8	Enables the specified LED drivers.
42	LedDisable	Write	U8	Disables the specified LED drivers.
43	LedState	Write	U8	Writes the state of both LED drivers.
44	Led0MaxCurrent	Write	Float	Maximum current allowed in LED 0 output, in mA.
45	Led1MaxCurrent	Write	Float	Maximum current allowed in LED 1 output, in mA.
46	PulseEnable	Write	U8	Enables the pulse function for the specified channels.
47	PulseDutyCycleLed0	Write	U8	Duty cycle of the channel 0 pulses [1:100] %.
48	PulseDutyCycleLed1	Write	U8	Duty cycle of the channel 1 pulses [1:100] %.
49	PulseFrequencyLed0	Write	U8	Frequency of the channel 0 pulses, in Hz.
50	PulseFrequencyLed1	Write	U8	Frequency of the channel 1 pulses, in Hz.
51	RampLed0	Write	U16	Duration of the channel 0 ramps, in ms.
52	RampLed1	Write	U16	Duration of the channel 1 ramps, in ms.
53	RampConfig	Write	U8	Specifies on which transitions the ramps are applied.
54–57	Reserved0–Reserved3	Read	U8	Reserved.
58	EnableEvents	Write	U8	Specifies the active events in the device.