System API

This page aggregates all System-related functions for the C API.

group CosmicSDK System API

Constants and APIs related to System operations.

Functions

void CosmicSDK_onNotification(CosmicSDK_Handle *handle, void (*callback)(const Notification*))

Registers a callback for unsolicited notifications (I3C, GPIO, UART and target bus events).

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_* function from it. The call waits for a reply that only this thread can deliver, so it waits out the full timeout – forever on a handle created with a timeout of -1.
The Notification and its payload are valid only for the duration of the call: the payload points into a buffer owned by handle that the next notification overwrites. Copy what you need before returning.

Parameters:

handle – Handle to the CosmicSDK instance
callback – Function pointer invoked with a Notification.

const char *CosmicSDK_GetVersion(void)

Gets the CosmicSDK library version string.

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

Note

The returned string is statically allocated and must not be freed. The pointer remains valid for the lifetime of the application.

Returns:: A null-terminated version string in the format “MAJOR.MINOR.PATCH”, e.g. “1.2.3”

bool CosmicSDK_Connect(CosmicSDK_Handle *handle, const char *devicePath)

Opens connection to the device.

Parameters:

handle – Handle to the CosmicSDK instance
devicePath – Optional path to the device. Pass NULL to use default device.

Returns:

true if connection successful, false otherwise

bool CosmicSDK_ConnectWithSerialNumber(CosmicSDK_Handle *handle, const char *serialNumber)

Opens connection to the device using its serial number.

Parameters:

handle – Handle to the CosmicSDK instance
serialNumber – Serial number of the device to connect to

Returns:

true if connection successful, false otherwise

void CosmicSDK_Disconnect(CosmicSDK_Handle *handle)

Closes connection to the device.

Parameters:

handle – Handle to the CosmicSDK instance

uint16_t CosmicSDK_ResetDevice(CosmicSDK_Handle *handle)

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 CosmicSDK_Connect or CosmicSDK_ConnectWithSerialNumber to reconnect.

Note

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

Parameters:

handle – Handle to the CosmicSDK instance.

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 CosmicSDK_GetDeviceInfo(CosmicSDK_Handle *handle, C_DeviceInfo *deviceInfoOut)

Gets the connected device information, like Manufacturer, Product Name, FW and HW versions and Serial Number.

Parameters:

handle – Handle to the CosmicSDK instance
deviceInfoOut – DeviceInfo object to write the connected devices data

Returns:

SUCCESS on success, error code otherwise

uint16_t CosmicSDK_EnterBootMode(CosmicSDK_Handle *handle)

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:

handle – Handle to the CosmicSDK instance

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 CosmicSDK_SetUsbConfig(CosmicSDK_Handle *handle, const UsbConfig *config)

Sets the USB CDC operating mode.

Note

To change the USB configuration, the device must be reset to apply the new settings.

Parameters:

handle – Handle to the CosmicSDK instance.
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 CosmicSDK_GetUsbConfig(CosmicSDK_Handle *handle, UsbConfig *config)

Gets the current USB CDC configuration.

Parameters:

handle – Handle to the CosmicSDK instance.
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.

bool CosmicSDK_IsBulkTransportAvailable(CosmicSDK_Handle *handle)

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 CosmicSDK_GetBulkCapabilities answers. Every bulk-transfer function in this API returns SDK_ERROR_BULK_UNAVAILABLE when either check fails: the I2C controller pair (CosmicSDK_I2cWriteBulk, CosmicSDK_I2cReadBulk), the six I3C controller calls (CosmicSDK_I3cSdrWriteBulk, CosmicSDK_I3cSdrReadBulk, CosmicSDK_I3cHdrDdrWriteBulk, CosmicSDK_I3cHdrDdrReadBulk, CosmicSDK_I3cLegacyI2cWriteBulk, CosmicSDK_I3cLegacyI2cReadBulk), the three SPI controller calls (CosmicSDK_SpiWriteBulk, CosmicSDK_SpiReadBulk, CosmicSDK_SpiTransferBulk), and the I2C and SPI target arenas (CosmicSDK_I2cTargetWriteMemory, CosmicSDK_I2cTargetReadMemory, CosmicSDK_SpiTargetWriteMemory, CosmicSDK_SpiTargetReadMemory). See Bulk transfers: the four checks.

Parameters:

handle – Handle to the CosmicSDK instance.

Returns:

True if the bulk transport is usable. False if it is not, or if handle is NULL.

uint16_t CosmicSDK_GetBulkCapabilities(CosmicSDK_Handle *handle, uint8_t *structVersion, uint8_t *supported, CosmicSDK_BulkGroup *groups, uint8_t maxGroups, uint8_t *groupCount)

Queries 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 result without another round trip. Firmware that predates the capabilities command does not answer the query; that is reported as *supported == 0 with *groupCount == 0 and SDK_ERROR_TIMEOUT. Treat an unqueryable device as having no bulk support rather than guessing a payload ceiling it may not honor; the status is what tells it apart from a device that answered “no bulk”.

Note

Prefer each group’s reported maxPayloadLength 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.

Parameters:

handle – Handle to the CosmicSDK instance.
structVersion – Receives the wire format version of the capabilities reply. May be NULL.
supported – Receives 1 if the connected device implements the bulk-capabilities query at all, 0 otherwise. May be NULL.
groups – Caller’s array, filled with up to maxGroups entries describing the groups the device reported. May be NULL to query only structVersion, supported, and groupCount.
maxGroups – Capacity of groups, in entries; the copy is bounded by this. Ignored when groups is NULL.
groupCount – Receives how many groups the device reported (which may exceed maxGroups if groups was too small to hold them all). May be NULL.

Return values:

SUCCESS – The device answered (now or earlier on this connection). This is returned even when the device does not support the bulk plane; check supported to tell the two apart.
SDK_ERROR_TIMEOUT – The device did not answer the query. The out-parameters read as “no bulk support”, which is the safe reading, but nothing was learned about the device and the next call asks again. Firmware that predates the command lands here.
SDK_ERROR_DISCONNECT – handle is NULL.

uint16_t CosmicSDK_GetLastBulkError(CosmicSDK_Handle *handle, char *buffer, size_t capacity, size_t *outLength)

Why the vendor bulk transport last failed, in words.

The transport’s own account of its last failure, which the status codes cannot carry: 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 CosmicSDK_IsBulkTransportAvailable is true and a bulk call returns SDK_ERROR_BULK_UNAVAILABLE, the device’s capability record refused it and the text is empty.

Pass buffer NULL and capacity 0 to learn the length first.

Parameters:

handle – Handle to the CosmicSDK instance.
buffer – Receives the text, always NUL-terminated when capacity is non-zero, truncated to capacity - 1 characters if it does not fit. May be NULL only when capacity is 0.
capacity – Size of buffer in bytes, including room for the terminator.
outLength – Receives the full length of the text, excluding the terminator. May be NULL.

Return values:

SUCCESS – The whole text (possibly empty) is in buffer.
SDK_ERROR_WRONG_REQUEST – The text did not fit and was truncated, or buffer is NULL with a non-zero capacity. outLength still says how large a buffer is needed.
SDK_ERROR_DISCONNECT – handle is NULL.