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
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...

float	getFeedbackFrequencyHz ()
	Gets the frequency of the internal feedback request + callback thread. 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...

	Group (HebiGroupPtr group, float initial_feedback_frequency=0.0f, int32_t initial_command_lifetime=0)

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	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	setCommandLifetimeMs (int32_t ms)
	Sets the command lifetime for the modules in this group. More...

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

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

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

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

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

	~Group () noexcept
	Destructor cleans up group. 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...

Private Member Functions
void	callAttachedHandlers (HebiGroupFeedbackPtr group_feedback)

Private Attributes
std::mutex	handler_lock_

std::vector< GroupFeedbackHandler >	handlers_

HebiGroupPtr	internal_

const int	number_of_modules_

Friends
void	callbackWrapper (HebiGroupFeedbackPtr group_feedback, void *user_data)

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.

Definition at line 49 of file group.hpp.

Constructor & Destructor Documentation

hebi::Group::Group	(	HebiGroupPtr	group,
		float	initial_feedback_frequency = `0.0f`,
		int32_t	initial_command_lifetime = `0`
	)

Creates a group from the underlying C-style group object. This should only be called to create groups from the lookup class, not from user code!

Definition at line 36 of file group.cpp.

hebi::Group::~Group ( )

noexcept

Destructor cleans up group.

Definition at line 52 of file group.cpp.

Member Function Documentation

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

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

Definition at line 158 of file group.cpp.

void hebi::Group::callAttachedHandlers ( HebiGroupFeedbackPtr group_feedback )

private

Calls any attached C++ handler functions. Should only be called from the internal C thread via the callbackWrapper translation function.

Definition at line 16 of file group.cpp.

void hebi::Group::clearFeedbackHandlers ( )

Removes all feedback handlers presently added.

Definition at line 166 of file group.cpp.

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

Definition at line 47 of file group.cpp.

float hebi::Group::getFeedbackFrequencyHz ( )

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

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

Definition at line 153 of file group.cpp.

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).

Definition at line 84 of file group.cpp.

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'.

Definition at line 89 of file group.cpp.

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.

Definition at line 69 of file group.cpp.

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.

Definition at line 74 of file group.cpp.

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).

Definition at line 79 of file group.cpp.

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.

Definition at line 64 of file group.cpp.

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).

Definition at line 148 of file group.cpp.

int hebi::Group::size ( )

Returns the number of modules in the group.

Definition at line 59 of file group.cpp.

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

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

Definition at line 94 of file group.cpp.

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

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

Definition at line 115 of file group.cpp.

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

Stops any active log.

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

Definition at line 136 of file group.cpp.

Friends And Related Function Documentation

void callbackWrapper	(	HebiGroupFeedbackPtr	group_feedback,
		void *	user_data
	)

friend

Intermediary to convert C-style function callbacks to C++ style, and change callback parameter types.

Definition at line 10 of file group.cpp.

Member Data Documentation

const int32_t hebi::Group::DEFAULT_TIMEOUT_MS = 500

static

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

Definition at line 92 of file group.hpp.

std::mutex hebi::Group::handler_lock_

private

Protects access to the group feedback handler vector.

Definition at line 65 of file group.hpp.

std::vector<GroupFeedbackHandler> hebi::Group::handlers_

private

A list of handler functions that are called when the internal C API feedback callback is made.

Definition at line 71 of file group.hpp.

HebiGroupPtr hebi::Group::internal_

private

C-style group object

Definition at line 55 of file group.hpp.

const int hebi::Group::number_of_modules_

private

The number of modules in this group.

Definition at line 60 of file group.hpp.

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

Public Member Functions

Static Public Member Functions

Static Public Attributes

Private Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation