Link Class¶

class Link¶

LinkClass: The Link class provides an interface to a BrainStem link. The link is used to create interfaces to modules on a BrainStem network. The link represents a connection to the BrainStem network from a host computer. The link is always associated with a transport (e.g.: USB, Ethernet, etc.) and a link module, but there are several ways to make this association.

The link can be fully specified with a transport and module serial number

The link can be created by searching a transport and connecting to the first module found.

Calling connect on a link will start a connection to the module based on The link specification. Calling disconnect will disconnect the link from the the current connection.

Public Types

enum STREAM_PACKET¶

Enumeration of stream packet types.

Values:

enumerator kSTREAM_PACKET_UNKNOWN¶

enumerator kSTREAM_PACKET_U8¶

enumerator kSTREAM_PACKET_U16¶

enumerator kSTREAM_PACKET_U32¶

enumerator kSTREAM_PACKET_BYTES¶

enumerator kSTREAM_PACKET_SUBINDEX_U8¶

enumerator kSTREAM_PACKET_SUBINDEX_U16¶

enumerator kSTREAM_PACKET_SUBINDEX_U32¶

enumerator kSTREAM_PACKET_LAST¶

enum STREAM_KEY¶

Enumeration for element types within a stream key.

Values:

enumerator STREAM_KEY_MODULE_ADDRESS¶

enumerator STREAM_KEY_CMD¶

enumerator STREAM_KEY_OPTION¶

enumerator STREAM_KEY_INDEX¶

enumerator STREAM_KEY_SUBINDEX¶

enumerator STREAM_KEY_LAST¶

typedef enum Acroname::BrainStem::Link::STREAM_PACKET STREAM_PACKET_t¶

Enumeration of stream packet types.

typedef std::function<uint8_t(const aPacket *packet, void *pRef)> streamCallback_t¶

Function signature for streaming callbacks.

Param packet:

reference to streaming packet

Param pRef:

User provided reference

Return:

non zero error code on failure. Return value is not currently used.

typedef struct Acroname::BrainStem::Link::StreamStatusEntry StreamStatusEntry_t¶

StreamStatusEntry structure - It contains members of streaming entries in the form of key value pairs. Keys are comprised of the devices module address, command, option, index, and subindex API values.

typedef enum Acroname::BrainStem::Link::STREAM_KEY STREAM_KEY_t¶

Enumeration for element types within a stream key.

Public Functions

aErr getConfig(aEtherConfig *config)¶

Gets the links current aEther configuration

Parameters:

config – Pointer to the configuration to be filled

Returns:

aErrNone on success; aErrParam if config is NULL

aErr setConfig(const aEtherConfig config)¶

Sets the links aEther configuration. Configuration must be applied BEFORE connecting

Parameters:

config – Configuration to be applied

Returns:

aErrNone on success. aErrPermission if the module is currently connected.

Link(const linkSpec linkSpecifier, const char *name = "Link")¶

Link Constructor. Takes a fully specified linkSpec pointer and creates a link instance with this specifier information.

Parameters:

linkSpecifier – The connection details for a specific module.

name – A name for the link to be created. This name can be used to reference the link during later interactions.

Link(const char *name = "Link")¶

Link constructor without a specifier will most likely use the discoverAndConnect call to create a connection to a link module.

Parameters:

name – A name for the link to be created.

~Link(void)¶

Destructor.

aErr discoverAndConnect(const linkType type, const uint32_t serialNumber = 0, const uint8_t model = 0)¶

A discovery-based connect. This member function will connect to the first available BrainStem found on the given transport. If the serial number is passed, it will only connect to the module with that serial number. Passing 0 as the serial number will create a link to the first link module found on the specified transport. If a link module is found on the specified transport, a connection will be made.

Parameters:

type – Transport on which to search for available BrainStem link modules. See the transport enum for supported transports.

serialNumber – Specify a serial number to connect to a specific link module. Use 0 to connect to the first link module found.

model – Acroname model number for the device.

Return values:

aErrBusy – if the module is already in use.

aErrParam – if the transport type is undefined.

aErrNotFound – if the module cannot be found or if no modules found.

aErrNone – If the connect was successful.

aErr connect(void)¶

Connect to a link with a fully defined specifier.

Return values:

aErrBusy – if the module is running, starting or stopping. Try again in a bit.

aErrDuplicate – If the module is already connected and running.

aErrConnection – If there was an error with the connection. User needs to disconnect, then reconnect.

aErrConfiguration – If the link has an invalid linkSpec.

aErrNotFound – if the module cannot be found.

aErrNone – If the connect was successful.

aErr connectThroughLinkModule(Link &link)¶

Connect using a pre-existing link. This member function will connect to the same BrainStem used by given Link. If a link module is found on the specified transport, a connection will be made.

Parameters:

link – - Reference to the link to be used.

Return values:

aErrInitialization – If the referenced link does not exist yet.

aErrConnection – If the connection could not be made.

aErrConfiguration – If the device or connection is in properly configured.

aErrNone – if the connect was successful.

bool isConnected(void)¶

Check to see if a module is connected. isConnected looks for a connection to an active module.

Returns:

true: connected, false: not connected.

linkStatus getStatus(void)¶

Check the status of the module connection.

Returns:

linkStatus (see aLink.h for status values)

aErr disconnect(void)¶

Disconnect from the BrainStem module.

Return values:

aErrResource – If the there is no valid connection.

aErrConnection – If the disconnect failed, due to a communication issue.

aErrNone – If the disconnect was successful.

aErr reset(void)¶

Reset The underlying link stream.

Return values:

aErrResource – If the there is no valid connection.

aErrConnection – If the reset failed, due to a communication issue.

aErrNone – If the reset was successful.

const char *getName(void)¶

Accessor for link Name. Returns a pointer to the string representing the link. This string is part of the link, and will be destroyed with it. If you need access to the link name beyond the life of the link, then copy the char* returned.

Returns:

Pointer to character array containing the name of the link.

aErr getLinkSpecifier(linkSpec *spec)¶

Accessor for current link specification.

Parameters:

spec – - an allocated empty link spec reference.

Returns:

aErrNotFound - If no linkSpec set for current link.

aErr setLinkSpecifier(const linkSpec linkSpecifier)¶

Accessor Set current link specification.

Parameters:

linkSpecifier – - The specifier that will replace the current spec.

Returns:

aErrBusy - If link is currently connected.

aErr getModuleAddress(uint8_t *address)¶

Gets the module address of the module the link is connected too. A zero is returned if no module can not be determined or if the link is not connected.

aErr sendUEI(const uei packet)¶

Sends a BrainStem protocol UEI packet on the link. This is an advanced interface, please see the relevant section of the reference manual for more information about UEIs.

Parameters:

packet – The command UEI packet to send.

Return values:

aErrConnection – link not connected.

aErrParam – data too long or short.

aErrPacket – invalid module address.

aErrNone – success.

aErr sendUEI(const uei packet, const uint8_t subindex)¶

Sends a BrainStem protocol UEI packet on the link where the packet contains a subindex. This is an advanced interface, please see the relevant section of the reference manual for more information about UEIs.

Parameters:

packet – The command UEI packet to send.

subindex – The subindex of the command option.

Return values:

aErrConnection – link not connected.

aErrParam – data too long or short.

aErrPacket – invalid module address.

aErrNone – success.

aErr receiveUEI(const uint8_t module, const uint8_t command, const uint8_t option, const uint8_t index, uei *packet)¶

Awaits receipt of the first available matching UEI packet from the link. The first four arguments describe the packet to wait for. When successful, the supplied uei ref is filled with the received UEI. This is an advanced interface, please see the relevant section of the reference manual for more information about UEIs.

Parameters:

module – The module address.

command – The command.

option – The uei option.

index – The index of the uei entity.

packet – The uei packet reference to be filled on success.

Return values:

aErrConnection – link not connected.

aErrPacket – invalid module address.

aErrTimeout – no packet available.

aErrNone – success.

aErr receiveUEI(const uint8_t module, const uint8_t command, const uint8_t option, const uint8_t index, uei *packet, aPacketMatchPacketProc proc)¶

Awaits receipt of the first available matching UEI packet from the link. The first four arguments and proc describe the packet to wait for. When successful, the supplied uei ref is filled with the received UEI. This is an advanced interface, please see the relevant section of the reference manual for more information about UEIs.

Parameters:

module – The module address.

command – The command.

option – The uei option.

index – The index of the uei entity.

packet – The uei packet reference to be filled on success.

proc – The callback used for determining a matching packet.

Return values:

aErrConnection – link not connected.

aErrPacket – invalid module address.

aErrTimeout – no packet available.

aErrNone – success.

aErr dropMatchingUEIPackets(const uint8_t module, const uint8_t command, const uint8_t option, const uint8_t index)¶

Drops all existing queued packets that match. from the link. The arguments describe the packets to be matched This is an advanced interface, please see the relevant section of the reference manual for more information about UEIs.

Parameters:

module – The module address.

command – The command.

option – The uei option.

index – The index of the uei entity.

Return values:

aErrConnection – link not connected.

aErrPacket – invalid module address.

aErrNone – success.

aErr sendPacket(const uint8_t module, const uint8_t command, const uint8_t length, const uint8_t *data)¶

Sends a raw BrainStem protocol packet on the link. where the length does not include the module or the command. address byte and can be 0 to aBRAINSTEM_MAXPACKETBYTES - 1. This is an advanced interface, please see the relevant section of the reference manual for more information about BrainStem Packet protocol.

Parameters:

module – The address of the destination module.

command – The length of the data being sent.

length – The length of the data being sent.

data – The data to send.

Return values:

aErrConnection – link not connected.

aErrParam – data too long or short.

aErrPacket – invalid module address.

aErrNone – success.

aErr receivePacket(const uint8_t module, const uint8_t *match, uint8_t *length, uint8_t *data)¶

Awaits receipt of the first available matching raw BrainStem protocol packet from the link where the length does not include the module or command bytes and can be zero. The provided module and match array are compared to packets available and the first match is returned. The supplied data pointer must point to at least aBRAINSTEM_MAXPACKETBYTES - 1 bytes. When successful, the data is filled in with the packet data not including the module and command and the length pointer is updated with the length of the returned data.

This is an advanced interface, please see the relevant section of the reference manual for more information about BrainStem Packet protocol.

Parameters:

module – The module address.

match – A byte array of the values to match for received packets.

length – The length of the match data on entry and length of the returned data filled on success.

data – The data filled on success.

Return values:

aErrConnection – link not connected.

aErrPacket – invalid module address.

aErrTimeout – no packet available.

aErrNone – success.

aErr loadStoreSlot(const uint8_t module, const uint8_t store, const uint8_t slot, const uint8_t *pData, const size_t length)¶

Loads data into a BrainStem Slot. See the relevant section of the BrainStem reference for information about BrainStem Slots and Stores.

Parameters:

module – - Module address.

store – - BrainStem store to access, possibilities include Internal, RAM, and SD.

slot – - The Slot within the Brainstem store to place the data.

pData – - Pointer to a buffer containing the data to load.

length – - The length in bytes of the data buffer to write.

Return values:

aErrConnection – link not connected.

aErrParam – invalid module address.

aErrCancel – The write process is closing and this call was unable to successfully complete.

aErrNone – success.

aErr unloadStoreSlot(const uint8_t module, const uint8_t store, const uint8_t slot, uint8_t *pData, const size_t dataLength, size_t *pNRead)¶

Unloads data from a BrainStem Slot. If there are no read.

reference for information about BrainStem Slots and Stores.

Parameters:

module – - Module address.

store – - BrainStem store to access, possibilities include Internal, RAM, and SD.

slot – - The Slot within the Brainstem store to place the data.

pData – - Pointer to a buffer with dataLength space in bytes that will be filled by the call.

dataLength – - Expected length of the data, and at most the size of the pData buffer.

pNRead – - The number of bytes actually read.

Return values:

aErrConnection – link not connected.

aErrParam – invalid module address.

aErrCancel – The write process is closing and this call was unable to successfully complete.

aErrOverrun – The read would overrun the buffer, i.e there is more data in the slot than the buffer can handle.

aErrNone – success.

aErr storeSlotSize(const uint8_t module, const uint8_t store, const uint8_t slot, size_t *size)¶

Returns the current size of the data loaded in the slot specified.

Parameters:

module – - Module address.

store – - BrainStem store to access, possibilities include Internal, RAM, and SD.

slot – - The Slot within the Brainstem store to place the data.

size – - size in bytes of the data stored in the slot.

Return values:

aErrConnection – link not connected.

aErrParam – invalid module address.

aErrCancel – The write process is closing and this request was unable to successfully complete.

aErrNone – success.

aErr storeSlotCapacity(const uint8_t module, const uint8_t store, const uint8_t slot, size_t *capacity)¶

Returns the maximum data capacity of the slot specified.

Parameters:

module – - Module address.

store – - BrainStem store to access, possibilities include Internal, RAM, and SD.

slot – - The Slot within the Brainstem store to place the data.

capacity – - size in bytes of the data stored in the slot.

Return values:

aErrConnection – link not connected.

aErrParam – invalid module address.

aErrCancel – The write process is closing and this request was unable to successfully complete.

aErrNone – success.

aErr enableStream(const uint8_t moduleAddress, const uint8_t cmd, const uint8_t option, const uint8_t index, const bool enable)¶

Enables streaming for the supplied criteria.

Parameters:

moduleAddress – Address to filter on.

cmd – cmd to filter by (supports Wildcards)

option – option to filter by (supports Wildcards)

index – index to filter by (supports Wildcards)

enable – True - Enables streaming; False - disables streaming

aErr isLinkStreaming(const uint8_t moduleAddress, uint8_t *enabled)¶

Determines if the module is actively streaming. Does not indicate what is streaming, only if streaming is currently active.

Parameters:

moduleAddress – The devices module address.

enabled – Variable to be populated.

Returns:

Returns common entity return values

aErr registerStreamCallback(const uint8_t moduleAddress, const uint8_t cmd, const uint8_t option, const uint8_t index, const bool enable, streamCallback_t cb, void *pRef)¶

Registers a callback function based on a specific module, cmd, option, and index.

Parameters:

moduleAddress – Address to filter on (supports Wildcards)

cmd – cmd to filter by (supports Wildcards)

option – option to filter by (supports Wildcards)

index – index to filter by (supports Wildcards)

enable – True - installs/updates callback and ref; False - uninstalls callback

cb – Callback to be executed when a new packet matching the criteria is received.

pRef – Pointer to user reference for use inside the callback function.

Returns:

aErrNotFound - Item not found (uninstalling only)

Returns:

aErrNone - success

aErr getStreamValue(const uint8_t moduleAddress, const uint8_t cmd, const uint8_t option, const uint8_t index, const uint8_t subindex, uint32_t *value)¶

Gets stream value based on the search criteria

Parameters:

moduleAddress – Address to filter on (supports Wildcards)

cmd – cmd to filter by (supports Wildcards)

option – option to filter by (supports Wildcards)

index – index to filter by (supports Wildcards)

Returns:

aErrStreamStale if the value has not been updated since the last read.

Returns:

aErrNotFound if no such stream element exists.

Returns:

aErrNone - success

aErr getStreamStatus(const uint8_t moduleAddress, const uint8_t cmd, const uint8_t option, const uint8_t index, const uint8_t subindex, StreamStatusEntry_t *buffer, const size_t bufferLength, size_t *unloadedSize)¶

Gets all available stream values based on the search criteria.

Parameters:

moduleAddress – Address to filter on (supports Wildcards)

cmd – cmd to filter by (supports Wildcards)

option – option to filter by (supports Wildcards)

index – index to filter by (supports Wildcards)

subindex – subindex to filter by (supports Wildcards)

buffer – Buffer of user allocated memory to be filled with stream data Note: Link::getStreamKeyElement should be used to decode the keys

bufferLength – Number of elements the buffer can hold.

unloadedSize – Number of elements that were placed in the buffer

Returns:

aErrParam if status or unloadedSize is null

Returns:

aErrNone - success

std::vector<uint64_t> filterActiveStreamKeys(const uint8_t moduleAddress, const uint8_t cmd, const uint8_t option, const uint8_t index, const uint8_t subindex, const bool acquireLock)¶

Provides a list of active stream keys based on the supplied criteria. Exposed for unit-testing purposes only.

Parameters:

moduleAddress – Address to filter on (supports Wildcards)

cmd – cmd to filter by (supports Wildcards)

option – option to filter by (supports Wildcards)

index – index to filter by (supports Wildcards)

acquireLock – Option to acquire mutex before getting list elements.

Returns:

List of keys meeting the search criteria

aErr enablePacketLog(const char *logname)¶

Enable Packet logging.

Enable packet logging for this link. Enables the packet logging buffer, and writes packet traffic out to the file specified by logname.

Parameters:

logname – the path and filename indicating where to write the packet log.

Returns:

aErr returns appropriate errors if it fails to enable the packet log.

aErr disablePacketLog(void)¶

Disable Packet logging.

disable packet logging for this link. Disables the packet log.

Returns:

aErr returns appropriate errors if it fails to disable the debug log.

aErr getFactoryData(const uint8_t module, const uint8_t command, uint8_t *pData, const size_t dataLength, size_t *unloadedLength)¶

For Internal use only!

aErr setFactoryData(const uint8_t module, const uint8_t command, const uint8_t *pData, const size_t dataLength)¶

For Internal use only!

Public Static Functions

static inline aErr sDiscover(const linkType type, aDiscoveryModuleFoundProc cbLinkFound, void *vpCBRef, const uint32_t networkInterface = LOCALHOST_IP_ADDRESS)¶

Discover is called with a specified transport to search for link modules on that transport. The callback is called with a fully filled in specifier for any link module found. The sDiscover returns aErrNone if the discovery process is successful, regardless of if any links are found. An error is only returned if the link discovery process fails. Discovery can take some time. The callback will occur in the same thread context as this routine call.

Parameters:

type – Transport to search for available BrainStem link modules on. See the transport enum for supported transports.

cbLinkFound – Process that is called when a module is discovered.

vpCBRef – This is passed to cbLinkFound when a module is discovered.

Return values:

aErrNone – on success.

aErrNotFound – if no devices were found.

static inline bContinueSearch sFindAll(const linkSpec *spec, bool *bSuccess, void *vpCBRef)¶

sFindAll is a callback function which matches any found stem. SFindAll is used by sDiscover(const linkType, list<linkSpec>*) to fill the list provided with any found modules on the specified link type.

Parameters:

spec – The linkspec pointer for the device currently being evaluated.

bSuccess – a returned value indicating whether the search has succeeded.

vpCBRef – Reference pointer to the std::list that was passed in.

Return values:

true – Caller should continue to call this function.

false – Caller should stop calling this function.

static inline aErr sDiscover(const linkType type, list<linkSpec> *devices, const uint32_t networkInterface = LOCALHOST_IP_ADDRESS)¶

Discover is called with a specified transport to search for link modules on that transport. The devices list is filled with device specifiers. sDiscover returns aErrNone if the discovery process is successful, regardless of whether any links are found. An error is only returned if the link discovery process fails. Discovery can take some time.

Parameters:

type – Transport to search for available BrainStem link modules on. See the transport enum for supported transports.

devices – an empty list of specifiers that will be filled in.

Return values:

aErrNotFound – if no devices were found.

aErrNone – on success.

static bool getStreamPacketType(const aPacket *packet, STREAM_PACKET_t *type)¶

Decodes the streaming packet type from a provided packet.

Parameters:

packet – - The packet to be interrogated.

type – - variable to be populated. Filled with kSTREAM_PACKET_UNKNOWN on failure.

Returns:

true on success; false on failure.

static bool isSubindexType(STREAM_PACKET_t type)¶

Helper function for indicating wether the packet is a subindex type. The subindex can be queried through Link::getStreamKeyElement

Parameters:

type – - The element to evaluate.

Returns:

true if the type contains a subindex; false if it does not.

static uint8_t getStreamKeyElement(const uint64_t key, STREAM_KEY_t element)¶

Convenience function to unpack a stream key. Note: This function will assert if an out of range STREAM_KEY_t is used.

Parameters:

key – The key to be unpacked

element – The element to unpack from the key.

Returns:

The requested element from the key.

static bool isStreamPacket(const aPacket *packet)¶

Convenience function to determine wether the value is a stream packet. Stream “Packets” encompass all STREAM_PACKET_t valid elements.

Parameters:

packet – UEI stream packet to be checked.

Returns:

Wether the packet is a stream sample or not

static bool isStreamSample(const aPacket *packet)¶

Convenience function to determine wether the value is a stream sample. Stream “Sample” encompasses all STREAM_KEY_t except for kSTREAM_PACKET_BYTES which have a varied structure and depend on the cmd/option/index. Calling isStreamPacket prior is not required as this function will verify the packet type

Parameters:

packet – UEI stream packet to be checked.

Returns:

Wether the packet is a stream sample or not

static aErr getStreamSample(const aPacket *packet, uint64_t *timestamp = NULL, uint32_t *value = NULL, uint8_t *subindex = NULL)¶

Convenience function to unpack the stream samples timestamp and value. Calling isStreamSample prior is not required as this function will verify the packet type.

Parameters:

packet – UEI stream packet to be unpacked.

timestamp – Variable to be filled with stream sample timestamp. (optional)

value – Variable to be filled with the stream sample (optional). May require casting to signed value depending on the cmd/option code.

Return values:

aErrPacket – Not a stream packet

aErrUnknown – Unknown decoding issue.

aErrNone – success.

static void getTimestampParts(const uint64_t timestamp, uint32_t *seconds, uint32_t *uSeconds)¶

Helper function for extracting the parts of a timestamp.

Parameters:

timestamp – - Value acquired from Link::getStreamSample

seconds – - Seconds element from timestamp. Refers to the seconds since firmware boot.

uSeconds – - Micro second element from the timestamp. Refers to the micro seconds from firmware boot. Micro seconds rolls over to seconds. Value range: 0-99999

static bool linkStreamFilter(const aPacket *packet, void *ref)¶

Filter function for Streaming packets. This is used internally whenever streaming is enabled. Exposed for unit-testing purposes only.

Parameters:

packet – UEI stream packet to be checked/filtered.

ref – Opaque reference handle

struct StreamStatusEntry¶

StreamStatusEntry structure - It contains members of streaming entries in the form of key value pairs. Keys are comprised of the devices module address, command, option, index, and subindex API values.

Public Members

uint64_t key¶

The stream key.

uint32_t value¶

The value associated with the key