> ## Documentation Index
> Fetch the complete documentation index at: https://dcc-5ccd5152.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# loco CLI: DCC Decoder Programming and Control Tool

> Use the loco CLI to read and write CVs, program addresses, adjust volume and brightness, control functions, and reset decoders — all from a terminal.

The `loco` binary is a standalone command-line tool for working with DCC-equipped locomotives. You use it to read and write configuration variables (CVs), program decoder addresses, adjust sound volume and lighting brightness, map function keys to outputs, and send direct throttle commands — all from a terminal, without the BigFred web UI. Because `loco` writes to stdout and reads from stdin, it fits naturally into scripts and backup workflows.

## Setup

Before running any `loco` command, create a configuration file at `~/.loco.yaml` that tells the tool how to reach your command station.

<Steps>
  ### Create the config file

  ```bash theme={null}
  nano ~/.loco.yaml
  ```

  ### Set your connection details

  For a Roco Z21 or compatible station connected over the network:

  ```yaml ~/.loco.yaml theme={null}
  server:
    type: "z21"           # z21 | loconet_serial | loconet_tcp
    address: "192.168.0.111"
    port: "21105"
  ```

  For a LocoNet command station connected via USB serial:

  ```yaml ~/.loco.yaml theme={null}
  server:
    type: "loconet_serial"
    device: "/dev/ttyUSB0"
    baudrate: 57600
  ```
</Steps>

<Note>
  The config file is read from `~/.loco.yaml` or from a `.loco.yaml` in the current working directory, whichever is found first. CLI flags always take precedence over the file.
</Note>

***

## CV commands — `loco prog cv`

Configuration Variables (CVs) store all decoder settings — address, speed curves, motor control, lighting behaviour, and more. The `loco prog cv` command group lets you read and write them individually, in comma-separated lists, or as ranges.

### Reading CVs

```bash theme={null}
# Read a single CV — output is the bare value (e.g. "17")
loco prog cv get cv1

# Read multiple CVs by name
loco prog cv get cv1,cv2,cv5

# Read a contiguous range
loco prog cv get cv1-cv10

# Read with a default fallback value when the CV is unreadable
loco prog cv get cv52-53=0,cv1,cv5
```

By default, `loco` uses the **programming track** when no locomotive address is given. To read CVs from a locomotive sitting on the **main track** (Programming on Main, PoM), pass `-t pom` and supply the DCC address with `-l`:

```bash theme={null}
# PoM read — locomotive must be on the main track, address 17
loco prog cv get cv2 -t pom -l 17
```

<Note>
  PoM reads are not acknowledged by all decoders. If `cv get` returns `ERROR` on the main track, fall back to the programming track.
</Note>

### Writing CVs

```bash theme={null}
# Write a single CV
loco prog cv set cv29=5

# Write multiple CVs in one command
loco prog cv set cv1=17,cv29=5

# Write and read back to verify the result
loco prog cv set cv29=5 --verify
```

The `--settle` flag (default `300` ms) controls the pause between consecutive writes. Increase it if your decoder needs more recovery time between programming operations.

### Bit-level writes — `cv set-bit`

When you only need to flip one or two bits inside a CV without disturbing the rest, use `set-bit`. Each assignment is `CVnbn=<0|1>` where `b0` is the least significant bit.

```bash theme={null}
# Set bit 5 of CV29 (enable long address) without touching other bits
loco prog cv set-bit cv29b5=1

# Clear bit 2 and set bit 5 in one pass
loco prog cv set-bit cv29b5=1,cv29b2=0

# Apply on the main track for loco 3
loco prog cv set-bit cv29b5=1 -l 3
```

### Backup and restore

Because `loco` prints results to stdout and accepts input from stdin, you can build complete backup and restore workflows with standard shell tools.

```bash theme={null}
# Back up CVs 1 through 10 to a file
loco prog cv get cv1-cv10 > backup.txt

# Restore those CVs from the backup file
cat backup.txt | loco prog cv set -- -
```

You can also maintain a hand-curated list of CVs to snapshot:

```bash theme={null}
# cv-list.txt contains one CV or range per line, e.g.:
#   cv1
#   cv2
#   cv3-cv4
cat cv-list.txt | loco prog cv get -- -
```

<Tip>
  Keep a backup file before experimenting with sound or motor tuning settings. If results are unsatisfactory, restore the original values with a single `cat backup.txt | loco prog cv set -- -` command.
</Tip>

### CV verbosity and timeouts

All `cv` subcommands accept `-v` / `--debug` to print raw packet bytes to stderr (useful for diagnosing command station communication issues):

```bash theme={null}
loco prog cv get -v cv1,cv5
```

You can also raise or lower the response timeout:

```bash theme={null}
# Wait up to 30 seconds per CV (useful over a slow serial link)
loco prog cv get cv1-cv10 --timeout 30
```

<Note>
  `--timeout 0` means **zero seconds**, not "no timeout". Every command will fail immediately with `no response or unrecognized response`. Always use a value of at least `1`.
</Note>

***

## Function commands — `loco drive fn`

The `loco drive fn` command group controls DCC functions (F0–F28) on a locomotive that is already running on the main track. Function state is managed through the command station.

### Listing active functions

```bash theme={null}
# Show all functions that are currently ON for loco 3
loco drive fn list -l 3
```

Example output when two functions are active:

```text theme={null}
F0 = On
F5 = On
```

### Turning functions on and off

```bash theme={null}
# Turn F0 on (lights on)
loco drive fn set 0 -l 3

# Turn F5 on (sound effect)
loco drive fn set 5 -l 3

# Turn F5 off
loco drive fn set 5 -l 3 --off
```

***

## Drive commands — `loco drive speed`

The `loco drive speed` command sets or reads the speed and direction of a locomotive on the main track.

```bash theme={null}
# Read current speed and direction
loco drive speed get -l 3

# Set speed to 50 (128-step mode), moving forward
loco drive speed set 50 -l 3 --forward

# Stop the locomotive
loco drive speed set 0 -l 3

# Emergency stop (speed step 1)
loco drive speed set 1 -l 3

# Use 28-step mode
loco drive speed set 20 -l 5 --steps 28
```

Speed values depend on the speed-step mode in use:

| Steps | Range | Notes                                             |
| ----- | ----- | ------------------------------------------------- |
| 14    | 0–15  | 0 = stop, 1 = emergency stop, 2–15 = steps 1–14   |
| 28    | 0–28  | 0 = stop, 1 = emergency stop, 2–28 = steps 1–27   |
| 128   | 0–127 | 0 = stop, 1 = emergency stop, 2–127 = steps 1–126 |

<Warning>
  `--loco` is required for `speed set` and `speed get`. The command will refuse to run without it.
</Warning>

***

## Programming commands — `loco prog`

The `loco prog` command group provides higher-level decoder operations that work on top of CV reads and writes: address programming, decoder detection, volume, brightness, function mapping, and factory reset.

All `prog` subcommands default to the **programming track** (when `-l 0` or no `-l` flag). Passing a non-zero loco address with `-l` switches to **PoM**.

### Decoder detection

Identify the decoder fitted to a locomotive by reading CV7 (version) and CV8 (manufacturer):

```bash theme={null}
loco prog detect-decoder
```

### Address programming

```bash theme={null}
# Read the current address (reads CV1, CV17, CV18, and CV29)
loco prog addr get

# Program a long address (128–9999)
loco prog addr set 1234

# Program and verify the written values
loco prog addr set 1234 --verify
```

### Volume — sound decoders only

```bash theme={null}
# Read master volume as a percentage (0–100)
loco prog volume get

# Set master volume to 50%
loco prog volume set 50
```

<Note>
  The `volume` commands have no effect on decoders that do not support sound. `detect-decoder` can help confirm whether your decoder is a sound variant.
</Note>

### Brightness — per-output lighting levels

```bash theme={null}
# List brightness for all addressable lighting outputs
loco prog brightness list

# Set O1 to 50% and O2 to 10% in one command
loco prog brightness set O1=50,O2=10

# Set multiple outputs with space-separated assignments
loco prog brightness set O1=10 O6=50

# Read the current brightness for output 1 (pass the output number)
loco prog brightness get 1
```

#### Identifying which output controls which light — `brightness test`

Before you can set meaningful brightness levels, you need to know which physical light on the model corresponds to each decoder output. The interactive `test` command lights one output at a time while you watch the model and press Enter to advance.

```bash theme={null}
# Start the interactive identification sequence (5-second lead-in by default)
loco prog brightness test
```

Turn on all lighting functions on the vehicle before the test starts. The tool will:

1. Turn all outputs off.
2. Light each output in turn at 50% brightness (configurable with `--brightness`).
3. Pause and wait for you to press Enter after noting which light is on.
4. Restore all original brightness values when done.

Use the output numbers reported by the test when running `loco prog mapping set`.

### Function mapping

Map DCC function keys to physical decoder outputs. Each assignment is `FUNCTION=OUTPUTS`; multiple outputs for the same function are comma-separated.

```bash theme={null}
# Map F0 to outputs O1 and O2, F1 to O4 and O6
loco prog mapping set F0=O1,O2 F1=O4,O6

# Map F0 forward headlight only
loco prog mapping set F0=F0_F --forward

# Map F0 reverse headlight only
loco prog mapping set F0=F0_R --reverse

# Map F2 to AUX outputs, PoM on loco 3
loco prog mapping set F2=AUX3,AUX5 -l 3
```

Supported output tokens: `O<n>`, `FO<n>`, `AUX<n>`, `F0_F` (F0 forward), `F0_R` (F0 reverse). On RailBOX RB 2112/2110, use `F0_F` and `F0_R` instead of `O1` for the headlight outputs.

### Factory reset

Reset the decoder back to factory defaults by writing to CV8. The exact reset value is decoder-specific (RailBOX RB23xx: `1`; ESU LokSound 5 and ZIMO MS/MN: `8`). BigFred detects the decoder type automatically.

```bash theme={null}
# Full factory reset
loco prog factory-reset

# Reset but restore the existing DCC address afterwards
loco prog factory-reset --preserve-addr
```

<Warning>
  A factory reset overwrites **all** CV values, including any motor tuning, sound configuration, and function mappings you have set. Back up your CVs first with `loco prog cv get cv1-cv255 > backup.txt`.
</Warning>

***

## Common flags

These flags are accepted by most `loco` subcommands:

| Flag        | Short | Default  | Description                                                             |
| ----------- | ----- | -------- | ----------------------------------------------------------------------- |
| `--debug`   | `-v`  | false    | Verbose output: prints raw packet bytes to stderr                       |
| `--loco`    | `-l`  | `0`      | Locomotive DCC address. `0` = programming track; non-zero = PoM on main |
| `--timeout` |       | `10`     | Command station response timeout in seconds                             |
| `--track`   | `-t`  | *(auto)* | Force track type: `prog` for programming track, `pom` for main track    |
| `--verify`  |       | false    | Read back after writing to confirm the value was accepted               |
| `--retry`   |       | `0`      | Retry the read request this many additional times on failure            |

<Note>
  When `--loco` is `0` and `--track` is not set, `loco` automatically selects the programming track. When `--loco` is a non-zero address and `--track` is not set, it automatically selects PoM. You can override this with an explicit `--track` flag.
</Note>