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>
|
| ~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< 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 () 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 const int32_t | DEFAULT_TIMEOUT_MS = 500 |
| The default timeout for any send-with-acknowledgement or request operation is 500 ms. More...
|
|
Represents a group of physical HEBI modules, and allows Command, Feedback, and Info objects to be sent to and received from the hardware.
◆ ~Group()
Destructor cleans up group.
◆ 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_command | The GroupCommand object containing information to be sent to the group. |
- Returns
- true if the command was successfully sent, false otherwise.
◆ sendCommandWithAcknowledgement()
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()
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()
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()
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 |
( |
| ) |
const |
Gets the frequency of the internal feedback request + callback thread.
- Returns
- The current feedback request loop frequency (in Hz).
◆ addFeedbackHandler()
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
◆ util::MobileIO
◆ 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: