# Examples

The examples/ directory included in the CosmicSDK package provides working sample projects that demonstrate how to use the SDK in both blocking and asynchronous modes, across various communication protocols.

These examples are categorized by:

- API Mode: Blocking or Async

- Language: C, C++, Python, C#, Java

- Protocol: I2C, SPI, UART, I3C, GPIO, etc.

You can use these examples as a starting point for your own applications or to validate your SDK installation and device setup.

## Async API Examples (C++)

Protocol | Directory
--- | ---
I2C | `examples/async_api/i2c/`

## Blocking API Examples (C and C++)

Protocol | Language | Directory
--- | --- | ---
I2C | C | `examples/blocking_api/i2c/c/`
I2C | C++ | `examples/blocking_api/i2c/cpp/`
SPI | C | `examples/blocking_api/spi/c/`
SPI | C++ | `examples/blocking_api/spi/cpp/`
UART | C | `examples/blocking_api/uart/c/`
UART | C++ | `examples/blocking_api/uart/cpp/`
GPIO | C | `examples/blocking_api/gpio/c/`
GPIO | C++ | `examples/blocking_api/gpio/cpp/`
I3C (Basic API) | C | `examples/blocking_api/i3c/basic/c/`
I3C (Basic API) | C++ | `examples/blocking_api/i3c/basic/cpp/`
I3C (CCC) | C | `examples/blocking_api/i3c/ccc/c/`
I3C (CCC) | C++ | `examples/blocking_api/i3c/ccc/cpp/`
I3C (DAA) | C | `examples/blocking_api/i3c/daa/c/`
I3C (DAA) | C++ | `examples/blocking_api/i3c/daa/cpp/`
I3C (HDR-DDR) | C | `examples/blocking_api/i3c/hdr-ddr/c/`
I3C (HDR-DDR) | C++ | `examples/blocking_api/i3c/hdr-ddr/cpp/`
I3C (Hot-Join + IBI) | C | `examples/blocking_api/i3c/hj-ibi/c/`
I3C (Hot-Join + IBI) | C++ | `examples/blocking_api/i3c/hj-ibi/cpp/`
System | C | `examples/blocking_api/system/c/`
System | C++ | `examples/blocking_api/system/cpp/`

## Language Bindings Examples

CosmicSDK includes sample code demonstrating how to use the SDK from other programming languages via bindings. For further details on integrating the CosmicSDK into other language platforms, refer to section Language Bindings.

Language | Directory
--- | ---
Python | `examples/language_bindings/python/`
C# | `examples/language_bindings/csharp/`
Java | `examples/language_bindings/java/`

## Protocol-Specific Example Guides

Use the following protocol pages for hardware setup details and walkthroughs:

- I2C Examples (Blocking API)
- SPI Examples (Blocking API)
- UART Examples (Blocking API)
- GPIO Examples (Blocking API)
- I3C Examples (Blocking API)
- System Examples (Blocking API)

## How to Build and Run the C and C++ Examples

This section provides instructions on building and running the C/C++ examples on different operating systems. As for the language bindings examples, refer to section Language Bindings.

To build any of the C or C++ examples, follow the instructions below based on your operating system:

(Optional) Define environment variables

These variables shorten commands in the steps below:

bash:

    export SDK_PATH=<path-to-package-root>
    export SDK_LIB_PATH="$SDK_PATH/lib"
    export SDK_INCLUDE_PATH="$SDK_PATH/include"
    export EXAMPLE_PATH="$SDK_PATH/examples/blocking_api/i2c/cpp"

cmd:

    set SDK_PATH=<path-to-package-root>
    set SDK_LIB_PATH=%SDK_PATH%\lib
    set SDK_INCLUDE_PATH=%SDK_PATH%\include
    set EXAMPLE_PATH=%SDK_PATH%\examples\blocking_api\i2c\cpp

Note

- Replace `<path-to-package-root>` with the root folder of your package contents (for example: `/home/username/CosmicSDK` or `C:\CosmicSDK`).

- Adjust `EXAMPLE_PATH` to match the example you want to build and run.

- Use one console consistently for all commands in a section:

    - Windows sections use Command Prompt syntax.

    - Linux/macOS sections use Bash syntax.

- If you use PowerShell on Windows, translate as follows:

    - `set VAR=value` -> `$env:VAR = "value"`

    - `%VAR%` -> `$env:VAR`

    - Command continuation `^` -> PowerShell continuation `` ` `` (or run in one line).

### Windows (MSVC)

#### Building the C++ Example

1. Open a Developer Command Prompt for Visual Studio.

2. Navigate to the C++ example directory:

Use the EXAMPLE_PATH variable defined above.

    cd /d "%EXAMPLE_PATH%"

3. Configure and Build with CMake:

If using MSBuild:

    cmake -B build ^
          -DLIBRARY_PATH=%SDK_LIB_PATH% ^
          -DINCLUDE_PATH=%SDK_INCLUDE_PATH% ^
          -G "Visual Studio 17 2022" -A [Win32|x64]

    cmake --build build --config [Debug|Release]

Note

- Replace [Win32|x64] with Win32 for a 32-bit build or x64 for a 64-bit build.

- For CMake versions 4.x.x it may be required to add the -DCMAKE_POLICY_VERSION_MINIMUM=3.5 flag.

If using Ninja:

    call "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" [x86|x64]

    cmake -B build ^
          -DLIBRARY_PATH=%SDK_LIB_PATH% ^
          -DINCLUDE_PATH=%SDK_INCLUDE_PATH% ^
          -G "Ninja"

    cmake --build build

Note

- Replace [x86|x64] with the architecture you need.

- For CMake versions 4.x.x it may be required to add the -DCMAKE_POLICY_VERSION_MINIMUM=3.5 flag.

#### Running the C++ Example

1. Set the `PATH` to include the CosmicSDK library: Ensure SDK_LIB_PATH points to your package library folder (lib or libdebug).

    set PATH=%PATH%;%SDK_LIB_PATH%

2. Run the examples:

- Dynamic Example:

    cd /d %EXAMPLE_PATH%\build\Release
    example_cpp_dynamic.exe

- Static Example:

    cd /d %EXAMPLE_PATH%\build\Release
    example_cpp_static.exe

Note

- Ensure %SDK_LIB_PATH% points to the directory containing the CosmicSDK library.

- Ensure you use a Developer Command Prompt for Visual Studio to build the project.

- If using Ninja, ensure that it’s installed and available in your PATH.

### Windows (MinGW)

#### Prerequisites

##### Install MinGW-w64

Option 1: Manual installation.

1. Download the installer from MinGW-w64 Downloads .

2. Install it to C:\mingw64 (recommended to avoid spaces and permission issues).

3. Add the bin directory to your system PATH:

    set PATH=%PATH%;C:\mingw64\bin

Option 2: Install with Chocolatey (Recommended for Simplicity)

If you have Chocolatey installed, you can use it to install MinGW-w64 easily:

1. Open a Command Prompt as Administrator.

2. Run the following command:

    choco install mingw --version=11.2.0 -y

3. Once installed, ensure the MinGW bin directory is in your PATH:

    set PATH=%PATH%;C:\ProgramData\chocolatey\lib\mingw\tools\install\mingw64\bin

Chocolatey typically installs MinGW-w64 under C:ProgramDatachocolatey.

##### Install Ninja

Download Ninja manually from the Ninja Build System , or use Chocolatey:

    choco install ninja -y

After installation, verify that ninja is available in your PATH by running:

    ninja --version

#### Building the C++ Example

1. Open a Command Prompt and ensure the environment is correctly configured. In particular, ensure the path to mingw-w64bin was set correctly as explained above.

2. Navigate to the C++ example directory:

   Use the EXAMPLE_PATH variable defined above.

    cd /d %EXAMPLE_PATH%

3. Run CMake with Ninja as the generator and build the project:

    cmake -B build ^
          -DCMAKE_C_COMPILER="gcc.exe" ^
          -DCMAKE_CXX_COMPILER="g++.exe" ^
          -DLIBRARY_PATH=%SDK_LIB_PATH% ^
          -DINCLUDE_PATH=%SDK_INCLUDE_PATH% ^
          -G "Ninja"

    cmake --build build

Note

- For CMake versions 4.x.x it may be required to add the -DCMAKE_POLICY_VERSION_MINIMUM=3.5 flag.

#### Running the C++ Example

1. Set the `PATH` to include the CosmicSDK library: Ensure SDK_LIB_PATH points to your package library folder (lib or libdebug).

    set PATH=%PATH%;%SDK_LIB_PATH%

2. Run the examples:

- Dynamic Example:

    cd /d %EXAMPLE_PATH%\build
    example_cpp_dynamic.exe

- Static Example:

    cd /d %EXAMPLE_PATH%\build
    example_cpp_static.exe

Note

- Ensure %SDK_LIB_PATH% points to the directory containing the CosmicSDK library.

- Use C:\mingw64 for MinGW installation to simplify configuration and prevent permission issues.

- Ensure windres is accessible via C:\mingw64\bin in your PATH.

### macOS

#### Building and Running the C++ Example

1. Navigate to the C++ example directory:

Use the EXAMPLE_PATH variable defined above.

    cd $EXAMPLE_PATH

2. Run CMake with the specified library and include paths:

    cmake -B build -DLIBRARY_PATH="$SDK_LIB_PATH" -DINCLUDE_PATH="$SDK_INCLUDE_PATH"

3. Build the example:

    cmake --build build

4. Run the dynamic and static examples:

For the dynamic example:

    DYLD_LIBRARY_PATH="$SDK_LIB_PATH":$DYLD_LIBRARY_PATH ./build/example_cpp_dynamic

For the static example:

    ./build/example_cpp_static

### Linux

#### Building and Running the C++ Example

1. (Recommended) Install udev rules for non-root access:

    chmod +x "$SDK_PATH/scripts/install_udev_rules.sh"
    sudo "$SDK_PATH/scripts/install_udev_rules.sh"

Unplug and replug the device after installing the rules.

2. Navigate to the C++ example directory:

    cd $EXAMPLE_PATH

3. Run CMake with the specified library and include paths:

    cmake -B build -DLIBRARY_PATH="$SDK_LIB_PATH" -DINCLUDE_PATH="$SDK_INCLUDE_PATH"

4. Build the example:

    cmake --build build

5. Run the dynamic and static examples:

    LD_LIBRARY_PATH="$SDK_LIB_PATH":$LD_LIBRARY_PATH ./build/example_cpp_dynamic
    LD_LIBRARY_PATH="$SDK_LIB_PATH":$LD_LIBRARY_PATH ./build/example_cpp_static

Note

- Binary names vary according to the language.

- For C++ examples, the binaries are example_cpp_dynamic and example_cpp_static.

- For C examples, binaries are example_c_dynamic and example_c_static.