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

Usage

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.