System API

This page aggregates all C++ System-related public methods of the class CosmicSDK.

group CosmicSDK System API

Constants and APIs related to System operations.

Functions

void onNotification(NotificationCallback callback)

Registers a callback to be invoked when an asynchronous notification is received.

The callback runs on the SDK’s receive thread – the same thread that delivers every command reply. Keep it short and hand work to a thread of your own:

  • Do not call a blocking CosmicSDK method from it. The call waits for a reply that only this thread can deliver, so it waits out the full timeout – forever with the default of -1.

  • The Notification and the bytes its payload points to are valid only for the duration of the call. Copy what you need before returning.

Safe to call while notifications are arriving. A notification already being delivered finishes on the callback it started with, so the old callback can still run once after this returns.

Parameters:

callback – Function that will receive a const reference to a Notification object.

uint64_t getDiscardedResponseCount() const

Number of command responses discarded because no command was waiting for them, or their transaction id did not match the command in flight.

Purely diagnostic, and the cheapest signal that something is wrong with the channel rather than with the caller’s arguments. It becomes non-zero when responses arrive that nobody asked for, which happens when commands time out before the firmware answers (raise the timeout passed to the constructor) or when another client has the same adapter open (Windows delivers every HID input report to every open handle, so both clients see each other’s replies).

Returns:

The cumulative count of discarded command responses.

bool connect(const std::string &devicePath = "")

Connects to a Binho Host Adapter device, such as Pulsar or Supernova. If no device path is provided, it will attempt to connect to the first available device.

Parameters:

devicePath – The path to the device (e.g., COM3 on Windows or /dev/ttyUSB0 on Linux). If empty, connects to the first available device.

Returns:

True if the connection was successful, false otherwise.

bool connectWithSerialNumber(const std::string &serial)

Connects to a Binho Host Adapter device using its serial number.

Parameters:

serial – The serial number of the device to connect to.

Returns:

True if the connection was successful, false otherwise.

void disconnect()

Disconnects from the currently connected Binho Host Adapter device.

uint16_t resetDevice()

Resets the connected device.

Sends a reset command to the device. The device will restart and the connection will be lost. After the device has rebooted, a new connection must be established before issuing further commands. Use connect or connectWithSerialNumber to reconnect.

Note

  • Allow sufficient time for the device to reboot before reconnecting (typically a few seconds).

Return values:

  • SUCCESS – The reset command was accepted by the device.

  • SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t getDeviceInfo(DeviceInfo &info)

Gets the device information.

Parameters:

info – The device information object to be filled with data

Returns:

The status code of the operation

static inline std::string getVersion()

Gets the CosmicSDK library version string.

Returns a string containing the version number of the linked CosmicSDK library. This allows verification at startup that the linked library matches what they were built against.

Returns:

A version string in the format “MAJOR.MINOR.PATCH”, e.g. “1.2.3”

uint16_t enterBootMode()

Puts the device into boot mode. Once the device process the request, it immediately jumps into the bootloader. After the user has flashed the device with a firmware, a new connection needs to be done to continue using the device.

Return values:

  • SUCCESS – The request was successfully sent to the device.

  • SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t setUsbConfig(const UsbConfig &config)

Sets the USB CDC operating mode.

Note

To change the USB CDC configuration, the device must be reset to apply the new settings. This is done automatically by the device after a successful call to this function.

Parameters:

config – The USB CDC configuration to set. See UsbConfig for supported values.

Return values:

  • SUCCESS – The USB CDC configuration was successfully set (a device reset is required to take effect).

  • FW_INVALID_PARAMETER – The provided configuration contains invalid parameters.

  • FW_SETTINGS_SAVE_FAILED – The new configuration could not be saved to the device’s flash memory.

  • SDK_TIMEOUT – The operation timed out.

  • SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t getUsbConfig(UsbConfig &config)

Gets the current USB CDC configuration.

Parameters:

config – The USB configuration to be filled with data. See UsbConfig for supported values.

Return values:

  • SUCCESS – The USB configuration was successfully retrieved.

  • SDK_TIMEOUT – The operation timed out.

  • SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

  • SDK_ERROR_WRONG_RESPONSE – The device returned an unexpected response.

  • SDK_ERROR_UNEXPECTED_RESPONSE – The device returned a response that does not match the request.

uint16_t maxPayloadFor(uint8_t group) const

Largest payload the device will accept for a protocol group.

Parameters:

group – Protocol group id to look up (e.g. I2C = 2, SPI = 3; see the GROUP_* constants in definitions.h).

Returns:

The group’s advertised payload ceiling in bytes, or 0 if the group is not present (i.e. not supported).

bool supportsCommand(uint16_t commandCode) const

Whether the connected device implements a particular bulk command.

Parameters:

commandCode – Full 16-bit command code to check, e.g. CMD_SPI_CONTROLLER_WRITE_BULK.

Returns:

True if the command’s bit is set in its protocol group’s capability mask.

const BulkCapabilities &getBulkCapabilities()

Queries and returns the connected device’s bulk-transport capabilities.

Sent once, on the first call after connecting, and cached for the rest of the connection’s lifetime; subsequent calls return the cached BulkCapabilities without another round trip. A query that goes unanswered is not cached – the next call asks again – and connecting discards the previous connection’s record. Every bulk-transfer method in this class calls this internally to validate the request, so it rarely needs to be called directly — call it explicitly when sizing a transfer ahead of time. Those methods are the I2C controller pair (i2cWriteBulk, i2cReadBulk), the six I3C controller calls (i3cSdrWriteBulk, i3cSdrReadBulk, i3cHdrDdrWriteBulk, i3cHdrDdrReadBulk, i3cLegacyI2cWriteBulk, i3cLegacyI2cReadBulk), the three SPI controller calls (spiWriteBulk, spiReadBulk, spiTransferBulk), and the I2C and SPI target arenas (i2cTargetWriteMemory, i2cTargetReadMemory, spiTargetWriteMemory, spiTargetReadMemory). See Bulk transfers: the four checks for the whole flow.

Note

Prefer BulkCapabilities::maxPayloadFor over a compile-time constant such as SPI_BULK_MAX_PAYLOAD when sizing a request: the ceiling differs between products (for example, Supernova’s I2C/SPI target arena is 32 KB, Pulsar’s is 16 KB), and a host that assumes one product’s ceiling gets its oversized requests refused with SDK_ERROR_WRONG_REQUEST on another.

Returns:

A reference to the cached capabilities, owned by this CosmicSDK instance and valid for the lifetime of the connection.

bool isBulkTransportAvailable()

Whether the vendor bulk endpoints are usable on this connection.

True only when the host was able to claim the device’s vendor-specific bulk IN/OUT endpoints at connect time. This is a transport-level check only: it does not mean the connected device implements a particular bulk command, which getBulkCapabilities answers. Every bulk-transfer method in this class returns SDK_ERROR_BULK_UNAVAILABLE when either check fails.

Returns:

True if the bulk transport is usable, false otherwise.

std::string getLastBulkError() const

Why the vendor bulk transport last failed, in words.

Every bulk failure reaches the caller as a status code – SDK_ERROR_BULK_UNAVAILABLE when the endpoints were never claimed, SDK_ERROR_TIMEOUT when a payload stalled – and the code alone does not say what to fix. This is the transport’s own account of the last failure, for example "libusb_open failed (is the vendor interface bound to WinUSB?)", "could not claim the vendor interface" or "bulk read timed out with 512 of 4096 bytes".

Empty when the last transport operation succeeded. It describes the host side only: when isBulkTransportAvailable is true and a bulk call still returns SDK_ERROR_BULK_UNAVAILABLE, the refusal came from the device’s getBulkCapabilities record and this string stays empty.

Returns:

The last failure reason, or an empty string.

struct BulkGroupSupport
#include <CosmicSDK.hpp>

One command group’s bulk-transfer support, as reported by the connected device.

One entry per protocol group (I2C, SPI, I3C, …) the connected device knows about. Populated inside BulkCapabilities::groups by getBulkCapabilities.

Public Members

uint8_t group = {0}

Protocol group id the entry describes (e.g. I2C = 2, SPI = 3; see the GROUP_* constants in definitions.h).

uint16_t maxPayloadLength = {0}

Largest payload, in bytes, this device accepts for a single bulk command in the group. 0 if the group is not supported.

uint32_t commandMask = {0}

Bit N set when the command whose 7-bit value field equals N is implemented for this group.

struct BulkCapabilities
#include <CosmicSDK.hpp>

Snapshot of the connected device’s bulk-transport capabilities.

Populated by getBulkCapabilities, which queries the device once per connection and caches the result. Firmware that predates the capabilities command does not answer the query; that is reported as supported == false with an empty groups list, which is the safe interpretation — treat an unqueryable device as having no bulk support rather than guessing a payload ceiling it may not honor.

Public Members

bool queried = {false}

True once the device has answered the query for this connection. Stays false after an unanswered query, which is retried on the next call.

uint8_t structVersion = {0}

Wire format version of the capabilities reply, as reported by the device.

bool supported = {false}

True if the connected device implements the bulk-capabilities query at all.

std::vector<BulkGroupSupport> groups

One entry per protocol group the device reported support for.