CosmicSDK (C/C++)

Summary

CosmicSDK is the C and C++ library for the Binho Supernova and Binho Pulsar host adapters and the Binho Atira debug probe. It talks to the adapter directly over USB, with no bridge or helper application to install.

• A blocking C++ API (CosmicSDK) for most programs, and a non-blocking C++ API (CosmicAsyncSDK) that reports results through a callback.
• A C API (CosmicSDK_API_c.h) for C programs and for calling the library from other languages.
• I2C, I3C, SPI, UART and GPIO, including target mode (the adapter acting as a device on the bus) and large transfers over a second USB pipe (up to 32 KB on a Supernova, 16 KB on a Pulsar).

The Atira has its own library, libdebugprobe, with C++ (debugprobe/DebugProbe.hpp) and C (DebugProbe_API_c.h) headers. It needs CosmicSDK 1.7.0 or newer and Atira firmware 1.0 or newer. See Binho Atira and the debug probe guide.

Note

Writing Python? Use PyCosmicSDK, which is built on CosmicSDK and installs with pip.

Supported Platforms

• Windows: x64 (MSVC or MinGW) and x86 (MSVC).
• macOS: Apple Silicon and Intel.
• Linux: x64 and ARM64.

Building against it requires a C++17 compiler and CMake 3.10 or later. On Linux, a program that uses the prebuilt library only needs the libusb-1.0 and libudev runtimes (libusb-1.0-0 and libudev1 on Debian and Ubuntu); the Linux download includes udev/65-binho-hid.rules and scripts/install_udev_rules.sh, which installs it (sudo ./scripts/install_udev_rules.sh, then replug the adapter). See Solving USB Connection Issues on Linux.

Download

The links below always point to the latest release (CosmicSDK 1.7.0). Each download has the libraries, headers, documentation and example projects:

Platform	Download
Windows x64 (MSVC)	cosmic_sdk-x64-msvc.exe
Windows x64 (MinGW)	cosmic_sdk-x64-mingw.exe
Windows x86 (MSVC)	cosmic_sdk-x86-msvc.exe
macOS (Apple Silicon)	cosmic_sdk-mac-arm-binaries.zip
macOS (Intel)	cosmic_sdk-mac-intel-binaries.zip
Linux x64	cosmic_sdk-linux-x64-binaries.zip
Linux ARM64	cosmic_sdk-linux-arm64-binaries.zip

If the browser or network blocks .exe downloads, the same Windows installers are also published with a .rename extension; see the download page in the CosmicSDK documentation.

Firmware

CosmicSDK 1.7 works with Supernova and Pulsar firmware 4.x and with Atira firmware 1.0 or newer. Use the latest firmware: the APIs added in 1.6.0 (below) need firmware 4.6.0 or later; older firmware refuses them. See Updating Firmware.

What’s New

Version	For Supernova and Pulsar programs
1.7.1 (upcoming)	Large SPI and I2C transfers at slow clock rates wait long enough for the bus to finish.
1.7.0	Adds the Atira debug probe library. No change to the Supernova and Pulsar API: nothing a program calls through CosmicSDK, CosmicAsyncSDK or the C API changed name, signature or behaviour since 1.6.0.
1.6.0	APIs for firmware 4.6.0: i2cSetDutyCycle() (SCL duty cycle), i3cSetI2cClockStretching() (clock-stretching I2C and SMBus targets on the I3C port), i3cHoldSclLow() (SMBus bus reset) and i3cSetSdaPullUp() (I3C port SDA pull-up).
1.5.1	getLastBulkError() says why a large transfer could not use the bulk USB pipe.

A First Program

This program connects to the first adapter it finds, prints what it is, brings up I2C bus A at 400 kHz and lists the devices on the bus:

#include <iomanip>
#include <iostream>
#include <vector>

#include "CosmicSDK.hpp"

int main() {
  CosmicSDK device(2000);  // 2000 ms timeout per command
  if (!device.connect()) {  // first Supernova or Pulsar found
    std::cerr << "No Binho adapter found" << std::endl;
    return 1;
  }

  CosmicSDK::DeviceInfo info;
  if (device.getDeviceInfo(info) != SUCCESS) return 1;
  std::cout << info.productName << " " << info.serialNumber << " " << info.fwVersion << std::endl;

  device.i2cSetBusVoltage(3300, false);  // target voltage first
  uint16_t status = device.i2cControllerInit(I2C_BUS_A, 400000, I2C_PULLUP_2_2kOhm);
  if (status != SUCCESS && status != FW_INTERFACE_ALREADY_INITIALIZED) return 1;

  std::vector<uint8_t> addresses;
  uint8_t count7 = 0, count10 = 0;
  if (device.i2cScanBus(addresses, &count7, &count10, I2C_BUS_A) != SUCCESS) return 1;
  for (uint8_t i = 0; i < count7; ++i) {
    std::cout << "Found 0x" << std::hex << std::setw(2) << std::setfill('0') << int(addresses[i]) << std::endl;
  }

  device.disconnect();
  return 0;
}

To add CosmicSDK to a CMake project, see Adding CosmicSDK to a project. The download also includes example projects for every protocol.

Documentation

The full CosmicSDK documentation covers every API, the example projects, and guides for large transfers and target mode:

https://binhollc.github.io/CosmicSDK/

Topic	Page
Download, install, prerequisites	Download and installation · Prerequisites
Add the library to a CMake project	Integration
Examples per protocol	I2C · I3C · SPI · UART · GPIO · System
Large transfers	Bulk transport
Target mode	Target mode
Status codes a call returns	Result codes
Common questions (selecting a device, threads, buses, pull-ups)	FAQ
C#, Java and Python wrappers around the C API	Language bindings

Coming From the BMC C++ SDK

The BMC C++ SDK is the earlier library for the Nova and the Supernova, and needs the Binho Mission Control Bridge installed. For the Supernova and the Pulsar, CosmicSDK replaces it and needs no bridge. The two libraries have different APIs, so moving over means rewriting the calls rather than changing an include.