> Complete documentation index: [llms.txt](/llms.txt). Markdown versions of all pages are available by appending `.md` to page URLs.

# Migrating to PyCosmicSDK

> Move scripts from BinhoSupernova, SupernovaController or BinhoPulsar to PyCosmicSDK

[PyCosmicSDK](/software/pycosmicsdk/) replaces the older Python packages for the Supernova and the Pulsar. It includes compatibility layers that keep the old method names, argument order and return values, so for most scripts the move is **a firmware update plus a changed import line**.

| If the script uses          | Replace the import with                   |
| ---------------------------- | ----------------------------------------- |
| `BinhoSupernova` (`binhosupernova`) | `pycosmicsdk.legacy.supernovasdk`  |
| `SupernovaController`        | `pycosmicsdk.legacy.supernovacontroller`  |
| `BinhoPulsar` (`binhopulsar`) | `pycosmicsdk.legacy.pulsarsdk`           |

Each compatibility layer was run side by side with the package it replaces, on the same adapter, before PyCosmicSDK 0.1.1, the first release that included them.

## Step 1: Make Sure the Adapter Runs Firmware 4.x

PyCosmicSDK only talks to **firmware 4.x**. Changing the import is not enough if the adapter runs firmware 3.x, or if the scripts use `SupernovaController`, which only supports firmware 3.x.

| Package in use today             | Firmware it works with |
| --------------------------------- | ---------------------- |
| `SupernovaController` 2.1.0       | 3.x only               |
| `BinhoSupernova` 3.2.0 / 4.2.0    | 3.x / 4.x              |
| `BinhoPulsar` 0.3.0 / 1.2.0       | 3.x / 4.x              |

Check the firmware without opening the adapter:

```python
from pycosmicsdk import list_devices

for found in list_devices():
    print(found.model.name, found.serial_number, "firmware", found.fw_version)
```

* `4.6.1` or any other 4.x version: go to Step 2. Update to the latest firmware anyway.
* `3.x.x`: update the firmware first, following [Updating Firmware](/guides/firmware-updates/).
* `bootloader`: the adapter is waiting in its bootloader instead of running firmware. Finish the firmware update, following [Updating Firmware](/guides/firmware-updates/).

:::caution
On firmware 3.x the serial number the adapter reports over USB is one character shorter than the full 32-character serial, so `list_devices()` shows 31 characters. After the update to firmware 4.x the adapter reports all 32. Opening by serial accepts either form, so scripts that store the serial keep working.

:::

:::danger
If test programs are qualified on firmware 3.2.0 and cannot be requalified, [contact us](/support/contact-us/) before updating the firmware.

:::

## Step 2: Install PyCosmicSDK

```sh
pip install pycosmicsdk
```

See [PyCosmicSDK](/software/pycosmicsdk/) for the supported Python versions and platforms.

## Step 3: Change the Import

The rest of the script stays the same.

**BinhoSupernova**

```python
# before
from binhosupernova.supernova import Supernova
from binhosupernova import getConnectedSupernovaDevicesList

# after
from pycosmicsdk.legacy.supernovasdk import Supernova, getConnectedSupernovaDevicesList
```

Enums and constants that used to come from `binhosupernova.commands.<protocol>.definitions` are now imported directly from `pycosmicsdk.legacy.supernovasdk`:

```python
# before
from binhosupernova.commands.i2c.definitions import I2cPullUpResistorsValue

# after
from pycosmicsdk.legacy.supernovasdk import I2cPullUpResistorsValue
```

**SupernovaController**

```python
# before
from supernovacontroller.sequential import SupernovaDevice

# after
from pycosmicsdk.legacy.supernovacontroller.sequential import SupernovaDevice
```

**BinhoPulsar**

```python
# before
from binhopulsar.pulsar import Pulsar
from binhopulsar import getConnectedPulsarDevicesList

# after
from pycosmicsdk.legacy.pulsarsdk import Pulsar, getConnectedPulsarDevicesList
```

The compatibility layers print a `DeprecationWarning` when imported, as a reminder that they are a migration path. If the test runner treats warnings as errors, run Python with `-W ignore::DeprecationWarning`.

## What Is Different

A small number of calls behave differently, and each one says so instead of failing silently:

* **SupernovaController, I3C:** `get_i3c_connector_status()`, `ccc_getacccr()`, `ccc_unicast_endxfer()` and `ccc_broadcast_endxfed()` return a failure explaining that the call is not available, and nothing is sent to the device. Connector plug and unplug arrive as `I3cConnectorEventNotification` events on the native API. GETACCCR and ENDXFER can still be sent through the `pycosmicsdk.legacy.supernovasdk` layer (`i3cGETACCCR`, `i3cDirectENDXFER`, `i3cBroadcastENDXFER`) or `AsyncI3cCcc.transfer()`.
* **SupernovaController, analog measurement:** `measure_analog_signal()` returns a failure explaining that it is not available. The same measurement is available from the native API as `AsyncDevice.get_analog_measurements()`.
* **SupernovaController, I3C rates:** the few rates firmware 4.x does not have (for example 3.75 MHz) run at the nearest slower rate, with a warning that names both.
* **SupernovaController, SETGRPA:** `ccc_unicast_setgrpa()` now needs the group address to assign: `ccc_unicast_setgrpa(0x08, group_address=0x0C)`.
* **All three:** entering the chip's ISP mode (`enterIspMode`) is not available.

The [migration guide](https://binhollc.github.io/pycosmicsdk/migration.html) in the PyCosmicSDK documentation lists every difference per package, and maps the old calls to the native API. Errors in the native API are described in the [errors reference](https://binhollc.github.io/pycosmicsdk/reference/errors.html).

## Next Step: The Native API

The compatibility layers are meant to get existing scripts running. New code should use the native API, which is typed, covers both adapters with the same calls, and adds large transfers, target mode and `asyncio`. See [PyCosmicSDK](/software/pycosmicsdk/) for an introduction and [PyCosmicSDK Examples](/software/pycosmicsdk/examples/) for runnable scripts.

If a script behaves differently after migrating, [contact us](/support/contact-us/) with the script and the output of the `list_devices()` example above.