Adapter Stops Responding

Most cases recover without unplugging anything. Start at the top of the ladder and go down only when a step does not help. Then check Known Situations: several have a documented cause and a fix in newer firmware.

The Recovery Ladder

Step	How	What it clears
1. Reconnect	Mission Control 3: Disconnect, then Connect. PyCosmicSDK: close the Device and open a new one.	A stuck session in the host software
2. Reset the adapter	PyCosmicSDK: device.reboot(into=ResetTarget.RUNTIME), then open the adapter again.	Interface roles left configured, a stuck SPI bulk transfer, a busy I3C engine
3. Replug USB	Unplug the adapter’s USB cable, wait 5 seconds, plug it back in.	An adapter that no longer answers any command, including the reset
4. Power-cycle the target	Set the target voltage to 0 V and back, or switch the target’s own supply off and on.	A target that holds the bus or dropped off it

import time
import pycosmicsdk
from pycosmicsdk import Device, ResetTarget

serial = pycosmicsdk.list_devices()[0].serial_number   # pick your adapter

with Device.open(serial=serial) as device:
    device.reboot(into=ResetTarget.RUNTIME)

# The adapter re-enumerates; wait until it is listed again (under 1 s on the bench).
while not any(d.serial_number == serial for d in pycosmicsdk.list_devices()):
    time.sleep(0.1)

with Device.open(serial=serial) as device:
    print(device.info.fw_version)

What a reset keeps and what it does not:

• On firmware 4.6.x and earlier, the multifunction rail can come back at about 3.3 V. The I3C rail switches off, because I3C voltage is never saved.
• Every interface must be initialized again.
• A reset cannot help an adapter that has stopped decoding commands: the reset command never arrives. Replug USB.

Replug, do not just reset, when:

• Every command times out, or PyCosmicSDK raises AdapterNotAnsweringError again on a new handle.
• A program crashed, or was killed, in the middle of a transfer.
• The adapter is listed but no program can open it.

Note

PyCosmicSDK raises AdapterNotAnsweringError after three commands in a row time out on one handle, and sends nothing more on it. Open a new Device. If the adapter answers, reset it (step 2); if not, replug it (step 3).

Known Situations

Symptom	Firmware	Cause	Fix
After an HDR-DDR read, the next I3C command times out and every later one answers I3C_ENGINE_BUSY	4.6.0 (about 90 % of DDR read cycles); 4.5.1 (about 2 in 300)	The controller answered before the HDR exit pattern finished	Reset the adapter. Fixed in 4.6.1.
I3C stops working a few transfers after a very large transfer, with no error on the large one	All	An I3C frame holds at most 32,767 bytes, including the register address. A 32,768-byte frame reports success, drops its last byte and leaves the controller busy.	Reset the adapter and initialize I3C again. Keep frames at 32,767 bytes or less; PyCosmicSDK refuses larger ones.
An I3C target disappears after a legacy I2C transfer to its dynamic address	4.5.1 and earlier	The target read the legacy header as an I3C read of itself	Power-cycle the target (I3C voltage to 0 V and back). 4.6.0 and later refuse that transfer with INVALID_PARAMETER.
I2C_TARGET_INIT times out after a session that used bulk transfers; the adapter otherwise looks healthy	4.6.1 and earlier	Bulk staging memory not released	Reset the adapter before starting I2C target mode. Fixed in 4.6.2 (upcoming).
After an SPI timeout, every SPI transfer comes back one byte late, with success	4.6.1 and earlier	The timeout path did not re-initialize the SPI block	Reset the adapter. Fixed in 4.6.2 (upcoming).
A flash status (WIP) poll over SPI never ends	All	The SPI read clock is above what the wiring supports, so reads come back shifted by one bit	Lower the SPI clock for reads, and bound the poll. Supernova on jumper wires: 20 MHz read clean, 30 MHz shifted.
An I2C bus stays stuck (SDA or SCL held low) and the adapter resets itself about 8 s later	4.6.1 and earlier	The adapter keeps waiting for the stuck bus to free up, until its watchdog restarts it	Open the adapter again after it re-enumerates. If a target holds SDA low, power-cycle it. Fixed in 4.6.2 (upcoming): the transfer ends with a timeout, and a failed scan clears the bus with up to 9 SCL pulses.
I2C set above 3 MHz (for example 3.4 MHz) or below 11 Hz reports success, then the bus runs at about 11 Hz or the adapter re-enumerates	4.6.1 and earlier	The frequency is out of range but accepted. On 4.5.0 and earlier the adapter could re-enumerate; on 4.6.0–4.6.1 the bus runs at about 11 Hz.	Open the adapter again if needed and initialize I2C between 11 Hz and 3 MHz. Fixed in 4.6.2 (upcoming): the request returns INVALID_PARAMETER.
I2C commands go unanswered after an arbitration-lost error, then the adapter resets	4.5.0	The controller was not re-initialized after the error	Fixed in 4.5.1.

To check the firmware version and update it, see Updating Firmware.

Collect Information for Support

Send these to [email protected]:

1. Adapter, serial number and firmware version:

   python -c "import pycosmicsdk; print([(d.model.name, d.serial_number, d.hw_version, d.fw_version) for d in pycosmicsdk.list_devices()])"

   On Linux, an empty serial number means the udev rule is missing. See Solving USB Connection Issues on Linux.

2. Host: operating system and version, and whether the adapter is on a hub.

3. Software and version: Mission Control 3 (desktop or mc3.binho.io) or PyCosmicSDK (python -c "import pycosmicsdk; print(pycosmicsdk.__version__)").

4. Actions taken: the last commands before it stopped, the wiring and the target voltage. In Mission Control 3, export the Transaction Log from the tool.

5. What recovered it: reconnect, reset, replug, or none.

6. On Linux: the kernel log from the moment it stopped: sudo dmesg | tail -n 50.