Skip to main content
Version: latest

Handle

Haply::HardwareAPI::Devices::Handle

Encapsulates the logic required to interact with a Haply handle.

WARNING Handles are still an area of active development and the API is not stable or guaranteed to be backwards compatible.

This class must be specialized to override one of the protected virtual methods which will be invoked when a particular event is received from the device:

  • OnReceiveHandleInfo: Invoked after waking up the device.
  • OnReceiveHandleStatusMessage Invoked when a new state update is received from the device.
  • OnReceiveHandleErrorResponse Invoked the device reports an error.

An instance of the SerialStream class representing the serial port of the handle is required as a parameter to the constructor. Once constructed, the SendDeviceWakeup command will wakeup the handle and allow for RequestStatus commands to be sent to retrieve the latest device status. The Receive method should follow any command method to process the device's response and trigger one of the overloaded virtual methods.

Handle implementations are customizable using a field in the device's status whose length is determined by the field. The Haply Quill's user fields are defined as follows:

  • : The state of the button on the flat surface of the handle where 1 indicate that it's held down.
  • : The battery level where the value 100 means that the battery is full.

All methods within this class will block until their respective IO operations are completed or error out. Handles operate at a frequency of approximately 50Hz. If multiple devices are managed by the same thread, the overall processing frequency will cap at the lowest frequency of all the device. Mixing handles and Inverse3 within the same thread is therefore not recommended.

Index​

Classes​

Members​

NameTypeDescription
USER_DATA_MAXstatic constexpr uint8_tThe maximum amount of bytes that can be contained in the ...

Methods​

NameTypeDescription
Handle(...)Constructs a Handle object from the ...
SendDeviceWakeupvoid()Wakeup the handle to allow for additional commands.
RequestStatusvoid()Request the latest state from the handle.
SendHandleStatevoid(const uint16_t, const uint8_t, ...)Update the handle-specific user state with the provided ...
SendHandleErrorRequestvoid(const uint16_t)Request the latest error information from the handle.
Receiveint()Receive and processe a response from the handle.
GetVersegripStatusVersegripStatusResponse(...)Get the Versegrip Status object as a response.

Members​

USER_DATA_MAX​

static constexpr uint8_t USER_DATA_MAX = 255

The maximum amount of bytes that can be contained in the user field of any any specialized implementations of the Haply handle.

Methods​

Handle​

Handle(         Haply::HardwareAPI::IO::SerialStream * stream,         float timeout)

Constructs a Handle object from the provided stream.

Parameters​

  • stream The stream object representing the serial port associated with the device. The lifetime of the stream must match or exceed the lifetime of the Handle object. We recommend constructing this stream using the SerialStream class.

  • timeout The maximum amount of time to wait for a response from the device. If the device fails to respond within this time, the operation will fail and an error will be printed to stderr.

The default timeout is 5 seconds, a negative value will disable the timeout.

SendDeviceWakeup​

void SendDeviceWakeup()

Wakeup the handle to allow for additional commands.

This command is required to be sent to the device before any other commands can be sent.

Must be followed by a call to Receive to process the handle's response which will in turn call the OnReceiveHandleInfo overloaded method.

RequestStatus​

void RequestStatus()

Request the latest state from the handle.

Must be followed by a call to Receive to process the handle's response which will in turn call the OnReceiveHandleStatusMessage overloaded method.

SendHandleState​

void SendHandleState(         const uint16_t device_id,         const uint8_t user_data_length,         const uint8_t * user_data)

Update the handle-specific user state with the provided arguments.

Must be followed by a call to Receive to process the handle's response which will in turn call the OnReceiveHandleStatusMessage overloaded method.

Parameters​

  • device_id The id of the device. This field is currently ignored by the handle and can be safely set to 0.

  • user_data_length The number of bytes to read from user_data. Must be smaller then USER_DATA_MAX.

  • user_data The bytes that will be read and used to update the handle-specific state. Consult the documentation of your handle to determine how to format these bytes.

SendHandleErrorRequest​

void SendHandleErrorRequest(const uint16_t device_id)

Request the latest error information from the handle.

Must be followed by a call to Receive to process the handle's response which will in turn call the OnReceiveHandleErrorResponse overloaded method.

Parameters​

  • device_id The id of the device. This field is currently be ignored by the handle and can be safely set to 0.

Receive​

int Receive()

Receive and processe a response from the handle.

Must follow any call to one of the following methods and will invoke the associated overloaded method:

Will block until a message is received from the device or an error is encountered.

Returns​

0 if the operation completed successfully. If an error occurred then the method will return a negative value, an error will be printed to stderr and may return false.

GetVersegripStatus​

VersegripStatusResponse GetVersegripStatus()

Get the Versegrip Status object as a response.

The new VerseGrip is designed to work with a dongle connected on a usb port and combine the ease of use of the wired handle to the freedom of the wireless handle. As we achieved more than 1kHz communication on wireless communication it’s now possible to use the handle in a wireless mode in a very simple way. 'GetVersegripStatus' can simply be called in the standard loop of the application to get the status of the handle.

Returns​

VersegripStatusResponse