Metadata-Version: 2.4
Name: pycosmicsdk
Version: 1.9.1
Summary: Python SDK for the Binho Supernova and Pulsar host adapters and the Binho Atira debug probe, built on the C/C++ CosmicSDK.
Author: Binho Inc
License-Expression: LicenseRef-Binho-Proprietary AND LGPL-2.1-or-later AND BSD-3-Clause
License-File: LICENSE
License-File: LICENSE.libusb
License-File: NOTICE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Hardware :: Hardware Drivers
Classifier: Typing :: Typed
Project-URL: Homepage, https://binho.io
Project-URL: Support, https://support.binho.io
Project-URL: Documentation, https://binhollc.github.io/pycosmicsdk/
Project-URL: Migration guide, https://binhollc.github.io/pycosmicsdk/migration.html
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# pycosmicsdk

Python SDK for the **Binho Supernova** and **Binho Pulsar** USB host adapters (I2C, I3C, SPI,
UART and GPIO) and the **Binho Atira** debug probe (SWD debug, target flash, target power), with
a blocking API and an `asyncio` twin for every call.

```bash
pip install pycosmicsdk
```

Binary wheels ship for CPython 3.10–3.14 on Linux `x86_64`, macOS `arm64` and Windows
`AMD64`. The native CosmicSDK library is linked into the wheel, so there is nothing else to
install and no path to configure.

## First steps

```python
import pycosmicsdk as p

print(p.list_devices())                      # every attached Supernova / Pulsar

with p.Device.open() as dev:                 # the first adapter found
    print(dev.info.fw_version)
    i2c = dev.i2c()
    i2c.set_voltage(voltage_mv=3300)
    i2c.bring_up(frequency_hz=400_000, pull_up=p.I2cPullUp.KOHM_1_0)
    print(sorted(i2c.scan().addresses_7bit))  # addresses that ACKed
```

| Protocol | Supernova | Pulsar |
| --- | --- | --- |
| I2C controller and target | bus A | buses A and B |
| I3C controller (all CCCs) and target | yes | — |
| SPI controller and target | yes (target not on rev B) | yes |
| UART | yes | yes |
| GPIO, with interrupts | yes | yes |

Large transfers can use the adapter's USB bulk endpoint: up to 32 KB on a Supernova and 16 KB
on a Pulsar per call.

## Binho Atira debug probe

`DebugProbe` drives the Atira: SWD debug (attach, halt, step, breakpoints, registers, memory),
target flash through the vendor's CMSIS flash algorithm straight from a `.pack`, target power,
SPI NOR flash on its header, and its UART bridge. It needs fw-atira 1.0 or newer; 1.9 pairs
with fw-atira 1.1, which splits the signal voltage and target power and handles self-powered
targets.

```python
from pycosmicsdk import DebugProbe, list_debug_probes
from pycosmicsdk.debugprobe import SignalVoltageState, TargetFlash

print(list_debug_probes())

with DebugProbe.open(serial=list_debug_probes()[0].serial_number) as probe:
    power = probe.power()                                  # fw-atira 1.1
    if power.signal_voltage_check().state == SignalVoltageState.NO_SUPPLY:
        power.set_signal_voltage_level(3300)               # pin 1 dead: the probe powers it
        power.set_signal_voltage_enabled(True)
        power.set_target_power_enabled(True)
    else:
        power.signal_voltage_use_external()                # self-powered: match its level

    probe.debug().attach()
    pack = "Keil.STM32H5xx_DFP.2.3.1.pack"                 # the vendor's device family pack
    info = probe.target_flash().load_pack_device(pack, "STM32H503RBTx", confirmed_connect_steps=[])
    probe.target_flash().write(info.flash_base, open("app.bin", "rb").read(), verify=True)
    probe.debug().run()
```

Parts whose pack declares vendor connect steps list as `NEEDS_CONNECT_STEPS`: the SDK does not
run those steps, so pass them in `confirmed_connect_steps` only once the user has accepted that.
Only the STM32H503 is verified on hardware so far. The guide covers the rest:
<https://binhollc.github.io/pycosmicsdk/guides/debugprobe.html>.

## Linux

The adapters and the Atira need no driver on any platform. On Linux, add udev rules so they are
reachable without `root` (`82fc` Supernova, `82fd` Pulsar, `8347` Atira). Without it, `list_devices()` still finds the adapter but
its serial number comes back empty.

```
# /etc/udev/rules.d/65-binho.rules
SUBSYSTEM=="hidraw", ATTRS{idVendor}=="1fc9", ATTRS{idProduct}=="82fc", MODE="0660", GROUP="plugdev"
SUBSYSTEM=="usb",    ATTRS{idVendor}=="1fc9", ATTRS{idProduct}=="82fc", MODE="0660", GROUP="plugdev"
SUBSYSTEM=="hidraw", ATTRS{idVendor}=="1fc9", ATTRS{idProduct}=="82fd", MODE="0660", GROUP="plugdev"
SUBSYSTEM=="usb",    ATTRS{idVendor}=="1fc9", ATTRS{idProduct}=="82fd", MODE="0660", GROUP="plugdev"
SUBSYSTEM=="hidraw", ATTRS{idVendor}=="1fc9", ATTRS{idProduct}=="8347", MODE="0660", GROUP="plugdev"
SUBSYSTEM=="usb",    ATTRS{idVendor}=="1fc9", ATTRS{idProduct}=="8347", MODE="0660", GROUP="plugdev"
```

Then run `sudo udevadm control --reload && sudo udevadm trigger` and add your user to `plugdev`.

## Versions and firmware

`MAJOR.MINOR` follows the CosmicSDK release embedded in the wheel: pycosmicsdk 1.6 carries
CosmicSDK 1.6. Features that need newer adapter firmware say so, and older firmware answers
them with `FW_UNSUPPORTED_COMMAND` rather than failing silently. Update the adapter's firmware
from [Mission Control](https://binho.io).

## Support

- Product pages and Mission Control: <https://binho.io>
- Support: <https://support.binho.io> · support@binho.io
