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

# Terminal Mode

> An interactive shell over the virtual COM port for driving I2C, I3C and GPIO by typing commands. Supernova only.

**Mode `1` · Supernova only · Introduced in firmware v4.4.0**

Terminal Mode turns the virtual COM port into an **interactive text shell**. Open
the port in any serial terminal (PuTTY, `screen`, `minicom`, the Arduino Serial
Monitor) and type commands to drive I2C, I3C and GPIO directly. No Mission
Control, no SDK, no code.

It's built for quick bring-up work: scanning a bus, poking at a register,
toggling a pin to see what happens.

:::danger
**Not available on Binho Pulsar.** Selecting this mode on a Pulsar is rejected
with an invalid-parameter error. The shell's I2C and I3C both run over the I3C
peripheral, which Pulsar's MCU does not have.

:::

## Quick start

{% stepper %}
{% step %}
### Put the device in terminal mode

```sh
python device_settings_cli.py set --cdc-mode terminal
```

The tool resets the device: the mode only takes effect at boot.
{% endstep %}

{% step %}
### Open the COM port

Any serial terminal will do. Baud rate, parity and stop bits are ignored: this is
a USB CDC endpoint, not a real UART, so pick anything.
{% endstep %}

{% step %}
### Press Enter

The banner and prompt appear:

```text
Binho Supernova Interactive Shell
Type 'help' for commands.
>
```
{% endstep %}

{% step %}
### Explore

`help` lists every command with a short description. `info` reports the device
name and firmware version.
{% endstep %}
{% endstepper %}

## What the shell can do

* **I2C:** speed select (100k / 400k / 1M), bus scan, read, write, and combined
  write-read.
* **I3C:** clock configuration, scan, ENTDAA / RSTDAA / target reset, SDR
  read/write/write-read, broadcast and direct CCCs, HDR-DDR read/write, IBI
  enable/disable/wait/read, and hot-join polling.
* **GPIO:** per-pin read and write on pins 1–6.
* **Built-ins:** `help` and `info`.

Line editing is included: 16 commands of history on the arrow keys, Tab
completion of the first word, Ctrl-C to cancel a line, and a `@` prefix for
silent mode. Lines are limited to 256 characters and 32 arguments.

:::note
**Which I2C bus?** The shell drives I2C through the I3C peripheral's legacy-I2C
mode, which means devices must be on the **I3C / Tiger-Eye port**: not the Qwiic
connector that the HID interface's I2C uses.

:::

## What it can't do

* **SPI:** no shell commands.
* **UART bridging:** the COM port *is* the terminal here. Use
  [UART Passthrough](/guides/usb-interfaces/usb-cdc-operating-modes/uart-passthrough/) for bridging.
* **Analog reads, DAC, VREF, and the RGB LED:** not exposed.
* **Power rail control:** the shell powers both switchable rails to 1.8 V at
  startup so the buses and level shifters work, but there is no command to change
  the voltage or turn a rail off.
* **Firmware update or bootloader entry:** no shell command. Both remain
  reachable over HID.
* **More than one session:** a single USB host, single port.

Transfers are capped at 256 bytes by the shell's buffers, and commands run one at
a time, blocking until they finish. An operation that doesn't complete within two
seconds prints `ERROR(timeout)`.

## Getting back out

:::caution
While Terminal Mode is active, the **HID protocol commands are not serviced**:
the shell owns the bus hardware, so Mission Control and the SDKs cannot drive
I2C, SPI, UART, GPIO or I3C.

:::

The HID **system** channel does keep running, which is the way back:

```sh
python device_settings_cli.py set --cdc-mode uart_passthrough
```

This works while the device is still in Terminal Mode. Device info, reset,
bootloader entry and voltage control stay available over HID for the same reason.

## Credit

The shell is a deliberate emulation of the open-source
[I3CBlaster](https://github.com/xyphro/I3CBlaster) project, which inspired its
design and command style.