HarpCore Class Reference

Harp Core that handles management of common bank registers. Implemented as a singleton to simplify attaching interrupt callbacks (and since you can only have one per device.) More...

#include <harp_core.h>

Collaboration diagram for HarpCore:

Public Member Functions
	HarpCore ()=delete
	HarpCore (HarpCore &other)=delete
void	operator= (const HarpCore &other)=delete
void	run ()
	Periodically handle tasks based on the current time, state, and inputs. Should be called in a loop. Calls tud_task() and process_cdc_input().
msg_header_t &	get_buffered_msg_header ()
	return a reference to the message header in the rx_buffer_.
msg_t	get_buffered_msg ()
	return a reference to the message in the rx_buffer_. Inline.
bool	new_msg ()
	flag indicating whether or not a new message is in the rx_buffer_.
void	clear_msg ()
	flag that new message has been handled. Inline.

Static Public Member Functions
static HarpCore &	init (uint16_t who_am_i, uint8_t hw_version_major, uint8_t hw_version_minor, uint8_t assembly_version, uint8_t harp_version_major, uint8_t harp_version_minor, uint8_t fw_version_major, uint8_t fw_version_minor, uint16_t serial_number, const char name[], const uint8_t tag[])
	initialize the harp core singleton with parameters and init Tinyusb.
static HarpCore &	instance ()
	returns the singleton.
static void	write_reg_generic (msg_t &msg)
	generic handler function to write a message payload to a core or app register and issue a harp reply (unless is_muted()).
static void	read_reg_generic (uint8_t reg_name)
	generic handler function to read a message payload to a core or app register and issue a harp reply (unless is_muted()).
static void	write_to_read_only_reg_error (msg_t &msg)
	write handler function. Sends a harp reply indicating a write error to the specified register.
static void	copy_msg_payload_to_register (msg_t &msg)
	update local (app or core) register data with the payload provided in the input msg.
static void	send_harp_reply (msg_type_t reply_type, uint8_t reg_name, const volatile uint8_t *data, uint8_t num_bytes, reg_type_t payload_type, uint64_t harp_time_us)
	Construct and send a Harp-compliant timestamped reply message from provided arguments.
static void	send_harp_reply (msg_type_t reply_type, uint8_t reg_name, const volatile uint8_t *data, uint8_t num_bytes, reg_type_t payload_type)
	Construct and send a Harp-compliant timestamped reply message from provided arguments. Timestamp is generated automatically at the time this function is called.
static void	send_harp_reply (msg_type_t reply_type, uint8_t reg_name)
	Construct and send a Harp-compliant timestamped reply message where payload data is written from the specified register.
static void	send_harp_reply (msg_type_t reply_type, uint8_t reg_name, uint64_t harp_time_us)
	Send a Harp-compliant reply with a specific timestamp.
static bool	is_muted ()
	true if the mute flag has been set in the R_OPERATION_CTRL register.
static bool	is_synced ()
	true if the device is synchronized via external CLKIN input.
static bool	events_enabled ()
	true if the "events enabled" flag has been set in the R_OPERATION_CTRL register.
static uint64_t	harp_time_us_64 ()
	get the total elapsed microseconds (64-bit) in "Harp" time.
static uint32_t	harp_time_s ()
	get the current elapsed seconds in "Harp" time.
static uint64_t	harp_to_system_us_64 (uint64_t harp_time_us)
	convert harp time (in 64-bit microseconds) to local system time (in 64-bit microseconds).
static uint32_t	harp_to_system_us_32 (uint64_t harp_time_us)
	convert harp time (in 32-bit microseconds) to local system time (in 32-bit microseconds).
static uint64_t	system_to_harp_us_64 (uint64_t system_time_us)
	convert system time (in 64-bit microseconds) to local system time (in 64-bit microseconds).
static void	set_harp_time_us_64 (uint64_t harp_time_us)
	Override the current Harp time with a specific time.
static void	set_synchronizer (HarpSynchronizer *sync)
	attach a synchronizer. If the synchronizer is attached, then calls to harp_time_us_64() and harp_time_us_32() will reflect the synchronizer's time.
static void	set_visual_indicators_fn (void(*func)(bool))
	attach a callback function to control external visual indicators (i.e: LEDs).
static void	force_state (op_mode_t next_state)
	force the op mode state. Useful to put the core in an error state.
static void	set_uuid (uint8_t *uuid, size_t num_bytes, size_t offset=0)
	set the 16 bytews in the R_UUID register. Any unspecified bytes will be set to zero. Usage:

Public Attributes
RegValues &	regs = regs_.regs_
	reference to the struct of reg values for easy access.

Static Public Attributes
static HarpCore *	self = nullptr

Protected Member Functions
	HarpCore (uint16_t who_am_i, uint8_t hw_version_major, uint8_t hw_version_minor, uint8_t assembly_version, uint8_t harp_version_major, uint8_t harp_version_minor, uint8_t fw_version_major, uint8_t fw_version_minor, uint16_t serial_number, const char name[], const uint8_t tag[])
	~HarpCore ()
void	handle_buffered_core_message ()
	entry point for handling incoming harp messages to core registers. Dispatches message to the appropriate handler.
virtual void	handle_buffered_app_message ()
	Handle incoming messages for the derived class. Does nothing here, but not pure virtual since we need to be able to instantiate a standalone harp core.
virtual void	update_app_state ()
	update state of the derived class. Does nothing in the base class, but not pure virtual since we need to be able to instantiate a standalone harp core.
virtual void	reset_app ()
	reset the app. Called when the writing to the RESET_DEF register. Does nothing in the base class, but not pure virtual since we need to be able to instantiate a standalone harp core.
void	set_visual_indicators (bool enabled)
	Enable or disable external virtual indicators.
virtual void	dump_app_registers ()
	send one harp reply read message per app register. Called when the writing to the R_OPERATION_CTRL's DUMP bit. Does nothing in the base class, but not pure virtual since we need to be able to instantiate a standalone harp core.
virtual const RegSpecs &	address_to_app_reg_specs (uint8_t address)

Protected Attributes
bool	new_msg_
	flag indicating whether or not a new message is in the rx_buffer_.
void(*	set_visual_indicators_fn_ )(bool)
	function pointer to function that enables/disables visual indicators.
HarpSynchronizer *	sync_
	function pointer to synchronizer if configured.

Detailed Description

Harp Core that handles management of common bank registers. Implemented as a singleton to simplify attaching interrupt callbacks (and since you can only have one per device.)

Constructor & Destructor Documentation

HarpCore() [1/3]

HarpCore::HarpCore ( uint16_t who_am_i, uint8_t hw_version_major, uint8_t hw_version_minor, uint8_t assembly_version, uint8_t harp_version_major, uint8_t harp_version_minor, uint8_t fw_version_major, uint8_t fw_version_minor, uint16_t serial_number, const char name[], const uint8_t tag[] )

protected

~HarpCore()

HarpCore::~HarpCore ( )

protected

HarpCore() [2/3]

HarpCore::HarpCore ( )

delete

HarpCore() [3/3]

HarpCore::HarpCore ( HarpCore & other )

delete

Member Function Documentation

address_to_app_reg_specs()

virtual const RegSpecs & HarpCore::address_to_app_reg_specs ( uint8_t address )

inlineprotectedvirtual

clear_msg()

void HarpCore::clear_msg ( )

inline

flag that new message has been handled. Inline.

Note

Does not affect internal behavior.

copy_msg_payload_to_register()

static void HarpCore::copy_msg_payload_to_register ( msg_t & msg )

inlinestatic

update local (app or core) register data with the payload provided in the input msg.

dump_app_registers()

virtual void HarpCore::dump_app_registers ( )

inlineprotectedvirtual

send one harp reply read message per app register. Called when the writing to the R_OPERATION_CTRL's DUMP bit. Does nothing in the base class, but not pure virtual since we need to be able to instantiate a standalone harp core.

events_enabled()

static bool HarpCore::events_enabled ( )

inlinestatic

true if the "events enabled" flag has been set in the R_OPERATION_CTRL register.

force_state()

static void HarpCore::force_state ( op_mode_t next_state )

inlinestatic

force the op mode state. Useful to put the core in an error state.

get_buffered_msg()

msg_t HarpCore::get_buffered_msg

(

)

return a reference to the message in the rx_buffer_. Inline.

Warning

this should only be accessed if new_msg() is true.

get_buffered_msg_header()

msg_header_t & HarpCore::get_buffered_msg_header ( )

inline

return a reference to the message header in the rx_buffer_.

Warning

this should only be accessed if new_msg() is true.

handle_buffered_app_message()

virtual void HarpCore::handle_buffered_app_message ( )

inlineprotectedvirtual

Handle incoming messages for the derived class. Does nothing here, but not pure virtual since we need to be able to instantiate a standalone harp core.

handle_buffered_core_message()

void HarpCore::handle_buffered_core_message ( )

protected

entry point for handling incoming harp messages to core registers. Dispatches message to the appropriate handler.

harp_time_s()

static uint32_t HarpCore::harp_time_s ( )

inlinestatic

get the current elapsed seconds in "Harp" time.

Note

the returned seconds are rounded down to the most recent second that has elapsed.

harp_time_us_64()

static uint64_t HarpCore::harp_time_us_64 ( )

inlinestatic

get the total elapsed microseconds (64-bit) in "Harp" time.

Internally, an offset is tracked and updated where \(t_{Harp} = t_{local} - t_{offset} \)

Warning

this value is not monotonic and can change at any time if (1) an external synchronizer is physically connected and operating and (2) this class instance has configured a synchronizer with set_synchronizer().

harp_to_system_us_32()

static uint32_t HarpCore::harp_to_system_us_32 ( uint64_t harp_time_us )

inlinestatic

convert harp time (in 32-bit microseconds) to local system time (in 32-bit microseconds).

this utility function is useful for setting alarms in the device's local time domain, which is monotonic and unchanged by adjustments to the harp time.

Note

if synchronizer is attached, the conversion will be in reference to the externally synchronized time.

Parameters

harp_time_us

the current time in microseconds

harp_to_system_us_64()

static uint64_t HarpCore::harp_to_system_us_64 ( uint64_t harp_time_us )

inlinestatic

convert harp time (in 64-bit microseconds) to local system time (in 64-bit microseconds).

this utility function is useful for setting alarms in the device's local time domain, which is monotonic and unchanged by adjustments to the harp time.

Note

if synchronizer is attached, the conversion will be in reference to the externally synchronized time.

Parameters

harp_time_us

the current time in microseconds

init()

HarpCore & HarpCore::init ( uint16_t who_am_i, uint8_t hw_version_major, uint8_t hw_version_minor, uint8_t assembly_version, uint8_t harp_version_major, uint8_t harp_version_minor, uint8_t fw_version_major, uint8_t fw_version_minor, uint16_t serial_number, const char name[], const uint8_t tag[] )

static

initialize the harp core singleton with parameters and init Tinyusb.

Note

default constructor, copy constructor, and assignment operator have been disabled.

instance()

static HarpCore & HarpCore::instance ( )

inlinestatic

returns the singleton.

is_muted()

static bool HarpCore::is_muted ( )

inlinestatic

true if the mute flag has been set in the R_OPERATION_CTRL register.

is_synced()

static bool HarpCore::is_synced ( )

inlinestatic

true if the device is synchronized via external CLKIN input.

true if the device has received and handled at least one synchronization signal from its external CLKIN input. As implemented, this function will never return false after synchronizing at least once, but that may change later.

new_msg()

bool HarpCore::new_msg ( )

inline

flag indicating whether or not a new message is in the rx_buffer_.

operator=()

void HarpCore::operator= ( const HarpCore & other )

delete

read_reg_generic()

void HarpCore::read_reg_generic ( uint8_t reg_name )

static

generic handler function to read a message payload to a core or app register and issue a harp reply (unless is_muted()).

Note

this function may be used in cases where (1) the register value is up-to-date and (2) no actions must trigger from reading this register.

reset_app()

virtual void HarpCore::reset_app ( )

inlineprotectedvirtual

reset the app. Called when the writing to the RESET_DEF register. Does nothing in the base class, but not pure virtual since we need to be able to instantiate a standalone harp core.

run()

void HarpCore::run

(

)

Periodically handle tasks based on the current time, state, and inputs. Should be called in a loop. Calls tud_task() and process_cdc_input().

send_harp_reply() [1/4]

static void HarpCore::send_harp_reply ( msg_type_t reply_type, uint8_t reg_name )

inlinestatic

Construct and send a Harp-compliant timestamped reply message where payload data is written from the specified register.

this function will lookup the particular core-or-app register's specs for the provided address and construct a reply based on those specs.

Note

this function is static such that we can write functions that invoke it before instantiating the HarpCore singleton.

Calls tud_task().

Parameters

reply_type	READ, WRITE, EVENT, READ_ERROR, or WRITE_ERROR enum.
reg_name	address to mark the origin point of the data.

send_harp_reply() [2/4]

static void HarpCore::send_harp_reply ( msg_type_t reply_type, uint8_t reg_name, const volatile uint8_t * data, uint8_t num_bytes, reg_type_t payload_type )

inlinestatic

Construct and send a Harp-compliant timestamped reply message from provided arguments. Timestamp is generated automatically at the time this function is called.

Note

this function is static such that we can write functions that invoke it before instantiating the HarpCore singleton.

Calls tud_task().

Parameters

reply_type	READ, WRITE, EVENT, READ_ERROR, or WRITE_ERROR enum.
reg_name	address to mark the origin point of the data.
data	pointer to payload content of the data.
num_bytes	sizeof(data)
payload_type	U8, S8, U16, U32, U64, S64, or Float enum.

send_harp_reply() [3/4]

void HarpCore::send_harp_reply ( msg_type_t reply_type, uint8_t reg_name, const volatile uint8_t * data, uint8_t num_bytes, reg_type_t payload_type, uint64_t harp_time_us )

static

Construct and send a Harp-compliant timestamped reply message from provided arguments.

Note

this function is static such that we can write functions that invoke it before instantiating the HarpCore singleton.

Calls tud_task().

Parameters

reply_type	READ, WRITE, EVENT, READ_ERROR, or WRITE_ERROR enum.
reg_name	address to mark the origin point of the data.
data	pointer to payload content of the data.
num_bytes	sizeof(data)
payload_type	U8, S8, U16, U32, U64, S64, or Float enum.
harp_time_us	the harp time (in microseconds) to timestamp onto the outgoing message.

send_harp_reply() [4/4]

static void HarpCore::send_harp_reply ( msg_type_t reply_type, uint8_t reg_name, uint64_t harp_time_us )

inlinestatic

Send a Harp-compliant reply with a specific timestamp.

Note

this function is static such that we can write functions that invoke it before instantiating the HarpCore singleton.

Calls tud_task().

Parameters

reply_type	READ, WRITE, EVENT, READ_ERROR, or WRITE_ERROR enum.
reg_name	address to mark the origin point of the data.
harp_time_us	the harp time (in microseconds) to timestamp onto the outgoing message.

set_harp_time_us_64()

static void HarpCore::set_harp_time_us_64 ( uint64_t harp_time_us )

inlinestatic

Override the current Harp time with a specific time.

Note

useful if a separate entity besides the synchronizer input jack needs to set the time (i.e: specifying the time over Harp protocol by writing to timestamp registers).

If a synchronizer is attached, this function will override the synchronizer's time also.

set_synchronizer()

static void HarpCore::set_synchronizer ( HarpSynchronizer * sync )

inlinestatic

attach a synchronizer. If the synchronizer is attached, then calls to harp_time_us_64() and harp_time_us_32() will reflect the synchronizer's time.

set_uuid()

static void HarpCore::set_uuid ( uint8_t * uuid, size_t num_bytes, size_t offset = 0 )

inlinestatic

set the 16 bytews in the R_UUID register. Any unspecified bytes will be set to zero. Usage:

uint64_t uuid = 0xCAFE;
// This works as-is on little-endian systems.
HarpCore::set_uuid((uin8_t*)&uuid, sizeof(uuid));

set_visual_indicators()

void HarpCore::set_visual_indicators ( bool enabled )

inlineprotected

Enable or disable external virtual indicators.

set_visual_indicators_fn()

static void HarpCore::set_visual_indicators_fn ( void(* func )(bool) )

inlinestatic

attach a callback function to control external visual indicators (i.e: LEDs).

system_to_harp_us_64()

static uint64_t HarpCore::system_to_harp_us_64 ( uint64_t system_time_us )

inlinestatic

convert system time (in 64-bit microseconds) to local system time (in 64-bit microseconds).

this utility function is useful for timestamping events in the local time domain and then calculating when they happened in Harp time.

Note

If the synchronizer is attached, the conversion will be in referenced to the synchronized time.

A system_to_harp_us_32() command does not exist because Harp time is only available in 64-bit time.

Parameters

system_time_us

the current system time in microseconds

update_app_state()

virtual void HarpCore::update_app_state ( )

inlineprotectedvirtual

update state of the derived class. Does nothing in the base class, but not pure virtual since we need to be able to instantiate a standalone harp core.

write_reg_generic()

void HarpCore::write_reg_generic ( msg_t & msg )

static

generic handler function to write a message payload to a core or app register and issue a harp reply (unless is_muted()).

Note

this function may be used in cases where no actions must trigger from writing to this register.

since the struct is byte-aligned, writing more data than the size of the register will sequentially write to the next register within the app range and core range. In this way, you can write to multiple sequential registers starting from the msg.address.

write_to_read_only_reg_error()

void HarpCore::write_to_read_only_reg_error ( msg_t & msg )

static

write handler function. Sends a harp reply indicating a write error to the specified register.

Member Data Documentation

new_msg_

bool HarpCore::new_msg_

protected

flag indicating whether or not a new message is in the rx_buffer_.

regs

RegValues& HarpCore::regs = regs_.regs_

reference to the struct of reg values for easy access.

self

HarpCore* HarpCore::self = nullptr

inlinestatic

set_visual_indicators_fn_

void(* HarpCore::set_visual_indicators_fn_) (bool)

protected

function pointer to function that enables/disables visual indicators.

sync_

HarpSynchronizer* HarpCore::sync_

protected

function pointer to synchronizer if configured.

---

The documentation for this class was generated from the following files:

• firmware/inc/harp_core.h
• firmware/src/harp_core.cpp