C API

This page describes the basic functions of the C API interface. For each specific protocol APIs, please refer to the corresponding sections.

group CosmicSDK C binding blocking API.

C bindings for the CosmicSDK blocking API.

This module exposes a C API suitable for C applications.

Typedefs

typedef struct CosmicSDK_Handle CosmicSDK_Handle

Opaque handle for CosmicSDK instance.

Functions

CosmicSDK_Handle *CosmicSDK_Create(int timeout_ms)

Creates a new CosmicSDK instance.

Parameters:

• timeout_ms – Timeout in milliseconds for operations.

Returns:

Handle to the created instance

void CosmicSDK_Destroy(CosmicSDK_Handle *handle)

Destroys a CosmicSDK instance and frees associated resources.

Parameters:

• handle – Handle to the instance to destroy

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

Registers a notification callback for asynchronous I3C events.

Parameters:

• handle – Handle to the CosmicSDK instance

• callback – Function pointer invoked with a Notification.

bool CosmicSDK_notificationAsI3cHotJoin(const Notification *c_notification, I3cHotJoinNotification *HJInfo)

Attempts to parse a Hot-Join notification. If c_notification contains a valid Hot-Join payload, the fields are decoded into HJInfo and the function returns true.

Parameters:

• c_notification – Pointer to a generic notification.

• HJInfo – Output structure for parsed Hot-Join information.

Returns:

true if parsing succeeded, otherwise false.

bool CosmicSDK_notificationAsI3cIbi(const Notification *c_notification, I3cIbiNotification *IBIInfo)

Attempts to parse an In-Band Interrupt (IBI) notification. If c_notification contains a valid IBI payload, the fields are decoded into IBIInfo and the function returns true.

Parameters:

• c_notification – Pointer to a generic notification.

• IBIInfo – Output structure for parsed IBI information.

Returns:

true if parsing succeeded, otherwise false.

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_notificationAsGpio(const Notification *c_notification, GpioInterruptNotification *GpioInfo)

Attempts to parse an GPIO Interrupt notification. If c_notification contains a valid GPIO payload, the fields are decoded into GpioInfo and the function returns true.

Parameters:

• c_notification – Pointer to a generic notification.

• GpioInfo – Output structure for parsed GPIO information.

Returns:

true if parsing succeeded, otherwise false.

bool CosmicSDK_notificationAsUartRx(const Notification *c_notification, UartRxNotification *uartInfo)

Attempts to parse a UART notification. If c_notification contains a valid UART payload, the fields are decoded into uartInfo and the function returns true.

Parameters:

• c_notification – Pointer to a generic notification.

• uartInfo – Output structure for parsed UART information.

Returns:

true if parsing succeeded, otherwise false.

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_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

Returns:

SUCCESS or SDK_ERROR_DISCONNECT if the device is not connected

struct C_DeviceInfo

#include <CosmicSDK_API_c.h>

Structure to hold device information from C API.

Public Members

char *manufacturer

Null-terminated manufacturer string.

size_t manufacturerLength

Manufacturer string length, excluding null terminator.

char *productName

Null-terminated product name string.

size_t productNameLength

Product name string length, excluding null terminator.

char *serialNumber

Null-terminated device serial number string.

size_t serialNumberLength

Serial number string length, excluding null terminator.

char *fwVersion

Null-terminated firmware version string.

size_t fwVersionLength

Firmware version string length, excluding null terminator.

char *hwVersion

Null-terminated hardware version string.

size_t hwVersionLength

Hardware version string length, excluding null terminator.