Represents a group of physical HEBI modules, and allows Command, Feedback, and Info objects to be sent to and recieved from the hardware. More...

#include <group.hpp>

Public Member Functions
	~Group () noexcept
	Destructor cleans up group. More...

int	size ()
	Returns the number of modules in the group. More...

bool	setCommandLifetimeMs (int32_t ms)
	Sets the command lifetime for the modules in this group. More...

bool	sendCommand (const GroupCommand &group_command)
	Send a command to the given group without requesting an acknowledgement. More...

bool	sendCommandWithAcknowledgement (const GroupCommand &group_command, int32_t timeout_ms=DEFAULT_TIMEOUT_MS)
	Send a command to the given group, requesting an acknowledgement of transmission to be sent back. More...

bool	sendFeedbackRequest ()
	Requests feedback from the group. More...

bool	getNextFeedback (GroupFeedback &feedback, int32_t timeout_ms=DEFAULT_TIMEOUT_MS)
	Returns the most recently stored feedback from a sent feedback request, or returns the next one received (up to the requested timeout). More...

bool	requestInfo (GroupInfo &info, int32_t timeout_ms=DEFAULT_TIMEOUT_MS)
	Request info from the group, and store it in the passed-in info object. More...

bool	requestInfoExtra (GroupInfo &info, InfoExtraFields extra_fields, int32_t timeout_ms=DEFAULT_TIMEOUT_MS)
	Request info from the group, and store it in the passed-in info object. Include extra fields. More...

std::string	startLog (const std::string &dir) const
	Starts log (stopping any active log). More...

std::string	startLog (const std::string &dir, const std::string &file) const
	Starts log (stopping any active log). More...

std::shared_ptr< LogFile >	stopLog () const
	Stops any active log. More...

bool	setFeedbackFrequencyHz (float frequency)
	Sets the frequency of the internal feedback request + callback thread. More...

float	getFeedbackFrequencyHz ()
	Gets the frequency of the internal feedback request + callback thread. More...

void	addFeedbackHandler (GroupFeedbackHandler handler)
	Adds a handler function to be called by the internal feedback request thread. More...

void	clearFeedbackHandlers ()
	Removes all feedback handlers presently added. More...

Static Public Member Functions
static std::shared_ptr< Group >	createImitation (size_t size)
	Creates an imitation group of provided size. More...

Static Public Attributes
static const int32_t	DEFAULT_TIMEOUT_MS = 500
	The default timeout for any send-with-acknowledgement or request operation is 500 ms. More...

Detailed Description

Represents a group of physical HEBI modules, and allows Command, Feedback, and Info objects to be sent to and recieved from the hardware.

Constructor & Destructor Documentation

◆ ~Group()

hebi::Group::~Group ( )

noexcept

Destructor cleans up group.

Member Function Documentation

◆ size()

int hebi::Group::size ( )

Returns the number of modules in the group.

◆ setCommandLifetimeMs()

bool hebi::Group::setCommandLifetimeMs ( int32_t ms )

Sets the command lifetime for the modules in this group.

This parameter defines how long a module will execute a command set point sent to it. Note the commands from other systems/applications are ignored during this time. A value of '0' indicates commands last forever, and there is no lockout behavior.

See docs.hebi.us for more information.

◆ sendCommand()

bool hebi::Group::sendCommand ( const GroupCommand & group_command )

Send a command to the given group without requesting an acknowledgement.

Appropriate for high-frequency applications.

Parameters

group_command The GroupCommand object containing information to be sent to the group.

Returns: true if the command was successfully sent, false otherwise.

◆ sendCommandWithAcknowledgement()

bool hebi::Group::sendCommandWithAcknowledgement	(	const GroupCommand &	group_command,
		int32_t	timeout_ms = `DEFAULT_TIMEOUT_MS`
	)

Send a command to the given group, requesting an acknowledgement of transmission to be sent back.

Parameters

group_command	The GroupCommand object containing information to be sent to the group.
timeout_ms	Indicates how many milliseconds to wait for a response after sending a packet. For typical networks, '15' ms is a value that can be reasonably expected to encompass the time required for a round-trip transmission.

Returns: true if an acknowledgement was successfully received (guaranteeing the group received this command), or a negative number for an error otherwise.

Note: A non-true return does not indicate a specific failure, and may result from an error while sending or simply a timeout/dropped response packet after a successful transmission.

◆ sendFeedbackRequest()

bool hebi::Group::sendFeedbackRequest ( )

Requests feedback from the group.

Sends a background request to the modules in the group; if/when all modules return feedback, any associated handler functions are called. This returned feedback is also stored to be returned by the next call to getNextFeedback (any previously returned data is discarded).

Returns: true if feedback was request was successfully sent, otherwise false on failure (i.e., connection error).

◆ getNextFeedback()

bool hebi::Group::getNextFeedback	(	GroupFeedback &	feedback,
		int32_t	timeout_ms = `DEFAULT_TIMEOUT_MS`
	)

Returns the most recently stored feedback from a sent feedback request, or returns the next one received (up to the requested timeout).

Note that a feedback request can be sent either with the sendFeedbackRequest function, or by setting a background feedback frequency with setFeedbackFrequencyHz.

Warning: other data in the provided 'Feedback' object is erased!

Parameters

feedback	On success, the group feedback read from the group are written into this structure.
timeout_ms	Indicates how many milliseconds to wait for feedback. For typical networks, '15' ms is a value that can be reasonably expected to allow for a round trip transmission after the last 'send feedback request' call.

Returns: true if feedback was returned, otherwise false on failure (i.e., connection error or timeout waiting for response).

◆ requestInfo()

bool hebi::Group::requestInfo	(	GroupInfo &	info,
		int32_t	timeout_ms = `DEFAULT_TIMEOUT_MS`
	)

Request info from the group, and store it in the passed-in info object.

Returns: true if the request was successful within the specified timeout; in this case 'info' has been updated. Otherwise, returns false and does not update 'info'.

◆ requestInfoExtra()

bool hebi::Group::requestInfoExtra	(	GroupInfo &	info,
		InfoExtraFields	extra_fields,
		int32_t	timeout_ms = `DEFAULT_TIMEOUT_MS`
	)

Request info from the group, and store it in the passed-in info object. Include extra fields.

Returns: true if the request was successful within the specified timeout; in this case 'info' has been updated. Otherwise, returns false and does not update 'info'.

◆ startLog() [1/2]

std::string hebi::Group::startLog ( const std::string & dir ) const

Starts log (stopping any active log).

Parameters

dir	The relative or absolute path to the directory to log in. To use the current directory, just use an empty string.

Returns: the path to the log file, otherwise an empty string on failure

◆ startLog() [2/2]

std::string hebi::Group::startLog	(	const std::string &	dir,
		const std::string &	file
	)		const

Starts log (stopping any active log).

Parameters

dir	The relative or absolute path to the directory to log in. To use the current directory, just use an empty string.
file	The name of the file within the directory

Returns: the path to the log file, otherwise an empty string on failure

◆ stopLog()

std::shared_ptr< LogFile > hebi::Group::stopLog ( ) const

Stops any active log.

Returns: shared pointer to the created log file. If the file was not successfully created, this will return null.

◆ setFeedbackFrequencyHz()

bool hebi::Group::setFeedbackFrequencyHz ( float frequency )

Sets the frequency of the internal feedback request + callback thread.

Returns: true if the frequency successfully was set, or false if the parameter was outside the accepted range (less than zero or faster than supported maximum).

◆ getFeedbackFrequencyHz()

float hebi::Group::getFeedbackFrequencyHz ( )

Gets the frequency of the internal feedback request + callback thread.

Returns: The current feedback request loop frequency (in Hz).

◆ addFeedbackHandler()

void hebi::Group::addFeedbackHandler ( GroupFeedbackHandler handler )

Adds a handler function to be called by the internal feedback request thread.

◆ clearFeedbackHandlers()

void hebi::Group::clearFeedbackHandlers ( )

Removes all feedback handlers presently added.

◆ createImitation()

std::shared_ptr< Group > hebi::Group::createImitation ( size_t size )

static

Creates an imitation group of provided size.

Parameters

size	the number of modules in the group

Returns: A shared pointer to the created imitation group

Member Data Documentation

◆ DEFAULT_TIMEOUT_MS

const int32_t hebi::Group::DEFAULT_TIMEOUT_MS = 500

static

The default timeout for any send-with-acknowledgement or request operation is 500 ms.

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

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ~Group()

Member Function Documentation

◆ size()

◆ setCommandLifetimeMs()

◆ sendCommand()

◆ sendCommandWithAcknowledgement()

◆ sendFeedbackRequest()

◆ getNextFeedback()

◆ requestInfo()

◆ requestInfoExtra()

◆ startLog() [1/2]

◆ startLog() [2/2]

◆ stopLog()

◆ setFeedbackFrequencyHz()

◆ getFeedbackFrequencyHz()

◆ addFeedbackHandler()

◆ clearFeedbackHandlers()

◆ createImitation()

Member Data Documentation

◆ DEFAULT_TIMEOUT_MS