Class Group

Class Documentation

class Group

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

Public Functions

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!

~Group() noexcept

Destructor cleans up group.

int size() const

Returns the number of modules in the group.

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

int32_t getCommandLifetimeMs() const

Returns the command lifetime for the modules in this group.

See setCommandLifetimeMs for more information.

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

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.

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.

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.

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

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

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

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.

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

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.

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

std::string 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

std::string 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

std::shared_ptr<LogFile> 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.

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

float getFeedbackFrequencyHz() const

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

Returns:

The current feedback request loop frequency (in Hz).

void addFeedbackHandler(GroupFeedbackHandler handler)

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

void clearFeedbackHandlers()

Removes all feedback handlers presently added.

Public Static Functions

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

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

Public Static Attributes

static const int32_t DEFAULT_TIMEOUT_MS = 500

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

Friends

friend class util::MobileIO