v4_cli 0.1.0

CLI tool for V4 VM bytecode deployment
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

# v4 CLI

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

## Features

- **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

```bash
cargo install --path .
```

### Build release binary

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

## Usage

### Push bytecode to device

```bash
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

```bash
v4 ping --port /dev/ttyACM0
```

### Reset VM

```bash
v4 reset --port /dev/ttyACM0
```

### Get help

```bash
v4 --help
v4 push --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

```bash
cargo test
```

### Build documentation

```bash
cargo doc --open
```

## Examples

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

```bash
# 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](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))

at your option.