System API

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

group CosmicSDK System API

Constants and APIs related to System operations.

Functions

void onResponse(std::function<void(const std::vector<uint8_t>&)> callback)

Sets the callback function to be called when a response is received from the device.

Parameters:: callback – The callback function that takes a vector of uint8_t as parameter.

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”

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

Connects to the device using the provided path.

Parameters:: devicePath – The path to the device. 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 the device using the provided 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 device.

uint16_t resetDevice(uint16_t id)

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 to the device after reset.

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

Return values:

SUCCESS – The reset command was accepted by the device.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

inline bool isConnected()

Checks if the device is connected.

Returns:: true if the device is connected.
Returns:: false if the device is not connected.

uint16_t enterBootMode(uint16_t id)

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.

Parameters:

id – uint16_t Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

Return values:

SUCCESS – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t setUsbConfig(uint16_t id, const UsbConfig &config)

Sets the USB CDC operating mode.

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.
config – The USB CDC configuration to set. See UsbConfig for supported values.

Return values:

SUCCESS – The USB configuration was successfully sent.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t getUsbConfig(uint16_t id)

Gets the current USB CDC configuration.

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

Return values:

SUCCESS – The USB configuration was successfully retrieved.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t getBulkCapabilities(uint16_t id)

Queries which bulk commands the connected device implements and their payload ceilings.

Sends CMD_SYS_GET_BULK_CAPABILITIES. The reply carries, per protocol group, the largest payload the device accepts and a bitmask of which bulk commands it implements; the blocking CosmicSDK::getBulkCapabilities

wrapper decodes that reply and caches it for the connection. Firmware that predates this command does not answer, which the blocking wrapper reads as “no

bulk support” — the safe interpretation.

Parameters:

id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

Return values:

SUCCESS – The command was successfully sent to the host adapter.
SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

bool isBulkTransportAvailable() const

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 this check fails. They do not consult the device’s capabilities: a bulk command the device does not advertise is sent anyway and its response never arrives. Query getBulkCapabilities first, or use CosmicSDK, which checks both.

Returns:: True if the bulk transport is usable, false otherwise.

std::string getLastBulkError() const

Why the vendor bulk transport last failed, in words.

The transport’s own account of its last failure – a claim that did not happen at connect time, or a payload that stalled – which the status codes alone cannot carry. Empty when the last transport operation succeeded. See CosmicSDK::getLastBulkError.

Returns:: The last failure reason, or an empty string.

bool receivePayload(uint8_t *data, size_t length, unsigned timeoutMs)

Collects a bulk read’s payload from the vendor bulk IN endpoint.

Call only after the firmware’s reply for the read command has arrived through the onResponse callback — the reply is what announces how many bytes are coming. Used to collect the payload for spiReadBulk, i2cTargetReadMemory, and spiTargetReadMemory; the blocking CosmicSDK counterparts call this internally so it rarely needs to be invoked directly.

Parameters:

data – Caller-owned buffer that receives the payload; must be at least length bytes.
length – Number of bytes to collect, as announced by the command’s reply.
timeoutMs – Maximum time, in milliseconds, to wait for the full payload to arrive.

Returns:

True if length bytes were collected before the timeout elapsed, false otherwise (for example if the transport is unavailable or the transfer stalls).