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

# USB CDC Operating Modes

> The five mutually exclusive operating modes of the USB CDC interface on Binho Supernova and Pulsar, and how to switch between them.

The USB CDC interface (the virtual COM port the device presents alongside its
[USB HID interface](/guides/usb-interfaces/)) can do one of five different jobs. Which one
it does is controlled by a single **persistent device setting**, stored in flash.

The modes are **mutually exclusive**: exactly one is active at a time.

:::caution
Changing the mode writes the setting to flash, but the device keeps running in
its current mode until it **resets**. The choice is made once, at boot.

:::

## The five modes

* [UART Passthrough](/guides/usb-interfaces/usb-cdc-operating-modes/uart-passthrough/)

Mode `0`, the default, on both boards. The COM port is a transparent bridge to
the device's UART pins.

* [Terminal Mode](/guides/usb-interfaces/usb-cdc-operating-modes/terminal-mode/)

Mode `1`, **Supernova only**. The COM port becomes an interactive shell for
driving I2C, I3C and GPIO by typing commands.

* [Nova Compatible Mode](/guides/usb-interfaces/usb-cdc-operating-modes/nova-compatible-mode/)

Mode `2`, on both boards. The COM port speaks the legacy Binho Nova ASCII
protocol, so existing Nova host software works unmodified.

* [RS-485 Bridge Mode](/guides/usb-interfaces/usb-cdc-operating-modes/rs485-bridge-mode/)

Mode `3`, **Pulsar only**. The COM port becomes a transparent half-duplex RS-485
bridge.

* [CAN-FD Bridge Mode](/guides/usb-interfaces/usb-cdc-operating-modes/canfd-bridge-mode/)

Mode `4`, **Pulsar only**. The COM port speaks SLCAN, so `python-can` and CANable
tooling can drive the CAN bus.

## Availability by device

| Mode | Value | Supernova | Pulsar |
| --- | :---: | :---: | :---: |
| UART Passthrough | `0` | Yes | Yes |
| Terminal | `1` | Yes | No |
| Nova Compatible | `2` | Yes | Yes |
| RS-485 Bridge | `3` | No | Yes |
| CAN-FD Bridge | `4` | No | Yes |

Selecting a mode the device doesn't support is rejected outright, so a device can't
be stranded in an unusable configuration this way.

## Switching modes with `device_settings_cli.py`

`device_settings_cli.py` is a small host-side tool that reads and changes these
settings over USB HID. It is the recommended way to switch modes: no Mission
Control and no SDK code required.

It needs Python 3 with `hidapi`:

```sh
pip install hidapi
```

:::tip
The tool talks to the device over **HID**, which stays available in every CDC
mode. That is what makes it always possible to switch back out of a mode: even
one like Terminal or Nova Compatible, where the COM port is busy doing something
other than accepting settings commands.

:::

### Subcommands

| Command | What it does |
| --- | --- |
| `show` | Print the current settings: `webusb_enabled`, `cdc_enabled`, `cdc_mode`. |
| `set` | Change one or more settings, then reset the device to persist them. |
| `reset` | Restore factory defaults (`webusb=1`, `cdc=1`, `cdc_mode=0`) and reset. |

### Flags

| Flag | Applies to | Meaning |
| --- | --- | --- |
| `--cdc-mode <mode>` | `set` | `uart_passthrough`, `terminal`, `nova_compat`, `rs485`, `canfd`, or the numeric value `0`–`4`. |
| `--cdc on\|off` | `set` | Enable or disable the CDC interface entirely. |
| `--webusb on\|off` | `set` | Enable or disable WebUSB. |
| `--device supernova\|pulsar` | all | Target one board when both are connected. Auto-detects otherwise. |
| `--no-save` | `set` | Apply in RAM only, without resetting. The change is lost on the next power cycle, and a `cdc_mode` change won't take effect at all until a reset. |

### Common commands

```sh
# What mode is the device in right now?
python device_settings_cli.py show

# Switch modes: the device resets automatically to apply
python device_settings_cli.py set --cdc-mode terminal

# Go back to the default
python device_settings_cli.py set --cdc-mode uart_passthrough

# ...or restore everything to factory defaults
python device_settings_cli.py reset

# Target one board when both are plugged in
python device_settings_cli.py --device pulsar set --cdc-mode canfd
```

A successful `set` prints the updated settings and then resets the device:

```text
Connected to Binho Supernova
Settings updated:
  webusb_enabled : 1  (on)
  cdc_enabled    : 1  (on)
  cdc_mode       : 1  (terminal)

Resetting device to persist settings to flash...
Device is resetting. Settings will be saved to flash.
```

## Switching modes programmatically

The CLI is a thin wrapper over the **SetUsbConfig** HID command, which can be
sent from Mission Control, a Binho SDK, or custom HID code. It carries three
fields (`webusb_enabled`, `cdc_enabled` and `cdc_mode`), and each accepts `0xFF`
to mean "leave unchanged".

`SetUsbConfig` only writes the setting. Send the reset command, or power-cycle
the device, for the new mode to take effect.