Migrating to PyCosmicSDK

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:

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.
• bootloader: the adapter is waiting in its bootloader instead of running firmware. Finish the firmware update, following Updating Firmware.

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 before updating the firmware.

Step 2: Install PyCosmicSDK

pip install pycosmicsdk

See PyCosmicSDK for the supported Python versions and platforms.

Step 3: Change the Import

The rest of the script stays the same.

BinhoSupernova

# 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:

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

# after
from pycosmicsdk.legacy.supernovasdk import I2cPullUpResistorsValue

SupernovaController

# before
from supernovacontroller.sequential import SupernovaDevice

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

BinhoPulsar

# 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 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.

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 for an introduction and PyCosmicSDK Examples for runnable scripts.

If a script behaves differently after migrating, contact us with the script and the output of the list_devices() example above.