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 notification callback for asynchronous I3C events.

Parameters:
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.