v4_cli 0.2.0

CLI tool for V4 VM bytecode deployment
docs.rs failed to build v4_cli-0.2.0
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
Visit the last successful build: v4_cli-0.1.0

v4 CLI

CI Security Audit Crates.io License: MIT OR Apache-2.0

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)
  • Deploy bytecode to V4 VM devices (v4 push)
  • Check connection to devices (v4 ping)
  • Reset VM state (v4 reset)
  • Progress bar for bytecode deployment
  • Persistent word definitions across REPL lines
  • Command history with arrow key navigation
  • 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.1.0
Connected to /dev/ttyACM0
Type 'bye' or press Ctrl+D to exit
Type '.help' for help

v4> 1 2 +
 ok

v4> : SQUARE DUP * ;
 ok

v4> 5 SQUARE
 ok

v4> .help
Available commands:
  .help    - Show this help
  .ping    - Check device connection
  .reset   - Reset VM and compiler context
  .exit    - Exit REPL (same as 'bye')
  bye      - Exit REPL

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:

at your option.