v4 CLI

CLI tool for deploying bytecode to V4 VM devices via the V4-link protocol over USB Serial.

Features

• Interactive REPL for Forth development (v4 repl)
  • Compiler Context Management - Persistent word definitions across REPL sessions
  • Command history with arrow key navigation
  • Debugging meta-commands:
    • .stack - Display data and return stack contents
    • .rstack - Show call trace via return stack
    • .dump - Hexdump memory at any address
    • .see - Disassemble word bytecode
    • .words - List all defined words
    • .reset - Reset VM and compiler context
• Deploy bytecode to V4 VM devices (v4 push)
• Check connection to devices (v4 ping)
• Reset VM state (v4 reset)
• Progress bar for bytecode deployment
• Configurable timeout
• Works with ESP32-C6, CH32V203, and other V4-enabled devices

Installation

From source

cargo install --path .

Build release binary

cargo build --release
# Binary will be in target/release/v4

Security checks

Run the same dependency checks as the Security Audit workflow:

cargo install cargo-audit --version 0.22.2 --locked
cargo install cargo-deny --version 0.20.2 --locked
cargo audit --deny warnings
cargo deny --locked check

The audit fails on advisory warnings, including unmaintained and unsound crates. New duplicate dependency versions fail under deny.toml. Three exact-version exceptions cover platform dependencies still required by serialport 4.10.1: bitflags 1.3.2, nix 0.26.4 and windows-sys 0.52.0. Revisit these when serialport updates its dependencies. Advisory checks remain enabled for these crates. Security Audit runs daily and on dependency or audit configuration changes, and can also be started manually from Actions. If GitHub disables it for inactivity, re-enable the workflow before running it; a successful regular CI run is not a security audit.

Usage

With V4-link 0.5+, engine failures are reported consistently, for example VM error -11: division by zero. Messages are generated from the engine's error definitions. Legacy devices without a detailed code still report VM_ERROR; unknown future engine codes retain their numeric value. Protocol/CRC, serial, compiler and VM failures remain separate error categories. The runtime must return from its VM diagnostic callback to send a reply (V4-runtime 0.3.2+). Failures do not undo earlier VM effects; inspect the state or reset before retrying.

Interactive REPL

Start an interactive Forth REPL session:

v4 repl --port /dev/ttyACM0

Example REPL session:

V4 REPL v0.5.0
Connected to /dev/ttyACM0
Type 'bye' or press Ctrl+D to exit
Type '.help' for help

v4> 1 2 +
 ok [1]: 3

v4> : SQUARE DUP * ;
 ok

v4> 5 SQUARE
 ok [1]: 25

v4> .words
Defined words (1):
  SQUARE

v4> .help
Available commands:
  .help              - Show this help
  .words             - List all defined words
  .ping              - Check device connection
  .reset             - Reset VM and compiler context
  .stack             - Show data and return stack contents
  .rstack            - Show return stack with call trace
  .dump [addr] [len] - Hexdump memory (default: continue from last)
  .see <word_idx>    - Show word bytecode disassembly
  .exit              - Exit REPL (same as 'bye')
  bye                - Exit REPL

v4> .stack
Data Stack (depth: 1 / 256):
  [0]: 0x00000019 (25)

Return Stack (depth: 0 / 64):
  <empty>

v4> bye
Goodbye!

Push bytecode to device

v4 push app.v4b --port /dev/ttyACM0
v4 push app.v4b --port /dev/ttyACM0 --timeout 10
v4 push app.v4b --port /dev/ttyACM0 --detach  # Don't wait for response

Check device connection

v4 ping --port /dev/ttyACM0

Reset VM

v4 reset --port /dev/ttyACM0

Get help

v4 --help
v4 push --help
v4 repl --help

V4-link Protocol

The V4-link protocol is a simple frame-based protocol for transferring bytecode to V4 VM devices over serial.

Frame Format

[STX][LEN_L][LEN_H][CMD][DATA...][CRC8]

- STX:   0xA5 (start marker)
- LEN_L: Payload length low byte (little-endian u16)
- LEN_H: Payload length high byte
- CMD:   Command code
- DATA:  Payload (0-512 bytes)
- CRC8:  Checksum (polynomial 0x07, init 0x00)

Commands

• 0x10 - EXEC: Execute bytecode
• 0x20 - PING: Connection check
• 0xFF - RESET: VM reset

Response Format

[STX][0x01][0x00][ERR_CODE][CRC8]

Error codes:
- 0x00 OK
- 0x01 ERROR
- 0x02 INVALID_FRAME
- 0x03 BUFFER_FULL
- 0x04 VM_ERROR

Development

Run tests

cargo test

Build documentation

cargo doc --open

Examples

The examples/ directory contains sample V4 bytecode files for testing with ESP32-C6 devices:

# Turn LED on
v4 push examples/led_on.v4b --port /dev/ttyACM0

# Start blinking pattern
v4 push examples/led_blink.v4b --port /dev/ttyACM0

# SOS morse code
v4 push examples/led_sos.v4b --port /dev/ttyACM0

# Turn LED off
v4 push examples/led_off.v4b --port /dev/ttyACM0

See examples/README.md for full list of available examples.

For the Python reference implementation, see ../V4-ports/esp32c6/examples/v4-link-demo/host/v4_link_send.py.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.