HEBI C++ API  3.12.0
hebi::Group Class Referencefinal

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

#include <group.hpp>

Public Member Functions

 ~Group () noexcept
 Destructor cleans up group. More...
 
int size () const
 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...
 
int32_t getCommandLifetimeMs () const
 Returns 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< LogFilestopLog () const
 Stops any active log. More...
 
bool setFeedbackFrequencyHz (float frequency)
 Sets the frequency of the internal feedback request + callback thread. More...
 
float getFeedbackFrequencyHz () const
 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< GroupcreateImitation (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...
 

Friends

class util::MobileIO
 

Detailed Description

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

Constructor & Destructor Documentation

◆ ~Group()

hebi::Group::~Group ( )
noexcept

Destructor cleans up group.

Member Function Documentation

◆ size()

int hebi::Group::size ( ) const

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.

◆ getCommandLifetimeMs()

int32_t hebi::Group::getCommandLifetimeMs ( ) const

Returns the command lifetime for the modules in this group.

See setCommandLifetimeMs 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_commandThe 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_commandThe GroupCommand object containing information to be sent to the group.
timeout_msIndicates 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
feedbackOn success, the group feedback read from the group are written into this structure.
timeout_msIndicates 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
dirThe 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
dirThe relative or absolute path to the directory to log in. To use the current directory, just use an empty string.
fileThe 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 ( ) const

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
sizethe number of modules in the group
Returns
A shared pointer to the created imitation group

Friends And Related Function Documentation

◆ util::MobileIO

friend class util::MobileIO
friend

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: