0
# Command Line Interface
1
2
Command-line tool for flashing Arduino boards directly from the terminal, with support for custom board configurations, port selection, and hardware testing.
3
4
## Capabilities
5
6
### Flash Command
7
8
Flash a hex file to an Arduino board with automatic board detection and protocol handling.
9
10
```bash { .api }
11
avrgirl-arduino flash -f <file> -a <arduino_type> [-p <port>] [-v]
12
```
13
14
**Parameters:**
15
- `-f <file>`: Path to the hex file to flash (required)
16
- `-a <arduino_type>`: Arduino board type or path to custom board file (required)
17
- `-p <port>`: Serial port path (optional, auto-detected if not specified)
18
- `-v`: Enable verbose debug output (optional)
19
20
**Usage Examples:**
21
22
```bash
23
# Flash sketch to Arduino Uno (auto-detect port)
24
avrgirl-arduino flash -f sketch.hex -a uno
25
26
# Flash to Leonardo on specific port
27
avrgirl-arduino flash -f firmware.hex -a leonardo -p /dev/ttyACM0
28
29
# Flash with verbose output
30
avrgirl-arduino flash -f blink.hex -a nano -v
31
32
# Windows example
33
avrgirl-arduino flash -f sketch.hex -a uno -p COM3
34
35
# Flash to Arduino Mega with debugging
36
avrgirl-arduino flash -f complex_sketch.hex -a mega -p COM5 -v
37
```
38
39
**Custom Board File:**
40
41
```bash
42
# Create custom board configuration file (my-board.js)
43
echo "module.exports = {
44
name: 'my-custom-board',
45
baud: 115200,
46
signature: Buffer.from([0x1e, 0x95, 0x0f]),
47
pageSize: 128,
48
numPages: 256,
49
timeout: 400,
50
productId: ['0x0043'],
51
protocol: 'stk500v1'
52
};" > my-board.js
53
54
# Use custom board configuration
55
avrgirl-arduino flash -f sketch.hex -a my-board.js
56
```
57
58
### Boards Command
59
60
List all supported Arduino board types.
61
62
```bash { .api }
63
avrgirl-arduino boards
64
```
65
66
**Usage Examples:**
67
68
```bash
69
# List all supported boards
70
avrgirl-arduino boards
71
72
# Output:
73
# Supported Boards:
74
# - adk
75
# - arduboy
76
# - bqZum
77
# - circuit-playground-classic
78
# - duemilanove168
79
# - esplora
80
# - feather
81
# - imuduino
82
# - leonardo
83
# - lilypad-usb
84
# - mega
85
# - micro
86
# - nano
87
# - pinoccio
88
# - pro-mini
89
# - qduino
90
# - sparkfun-pro-micro
91
# - tinyduino
92
# - uno
93
# - xprov4
94
# - yun
95
# - zumcore2
96
# - zumjunior
97
98
# Filter boards (using grep on Unix systems)
99
avrgirl-arduino boards | grep nano
100
# Output: - nano
101
102
# Count supported boards
103
avrgirl-arduino boards | grep -c " - "
104
# Output: 27
105
```
106
107
### List Command
108
109
Display all available serial ports on the system.
110
111
```bash { .api }
112
avrgirl-arduino list
113
```
114
115
**Usage Examples:**
116
117
```bash
118
# List all serial ports
119
avrgirl-arduino list
120
121
# Example output on Linux:
122
# [
123
# {
124
# "path": "/dev/ttyUSB0",
125
# "manufacturer": "Arduino (www.arduino.cc)",
126
# "serialNumber": "55432333038351F03170",
127
# "vendorId": "0x2341",
128
# "productId": "0x0043"
129
# },
130
# {
131
# "path": "/dev/ttyS0",
132
# "manufacturer": "",
133
# "serialNumber": "",
134
# "vendorId": "",
135
# "productId": ""
136
# }
137
# ]
138
139
# Parse output with jq (if available)
140
avrgirl-arduino list | jq '.[].path'
141
# Output:
142
# "/dev/ttyUSB0"
143
# "/dev/ttyS0"
144
145
# Filter for Arduino devices
146
avrgirl-arduino list | jq '.[] | select(.manufacturer | contains("Arduino"))'
147
```
148
149
### Test Pilot Command
150
151
Run the hardware test pilot program to verify Arduino connectivity and functionality.
152
153
```bash { .api }
154
avrgirl-arduino test-pilot
155
```
156
157
**Usage Examples:**
158
159
```bash
160
# Run test pilot
161
avrgirl-arduino test-pilot
162
163
# Output (if not installed):
164
# running preflight check...
165
# installing test pilot, won't be long...
166
# [installation progress for avrga-tester package]
167
168
# Output (if already installed):
169
# running preflight check...
170
# [comprehensive hardware connectivity tests]
171
```
172
173
The test pilot program:
174
1. Checks for existing `avrga-tester` dependency installation
175
2. Automatically installs test pilot if not present (requires npm permissions)
176
3. Runs comprehensive hardware connectivity tests
177
4. Provides detailed feedback on Arduino board detection and communication capabilities
178
5. Tests serial port communication and protocol verification
179
180
### Help Command
181
182
Display usage information and command help.
183
184
```bash { .api }
185
avrgirl-arduino help
186
```
187
188
**Usage Examples:**
189
190
```bash
191
# Show help
192
avrgirl-arduino help
193
194
# Output:
195
# Usage:
196
# avrgirl-arduino flash -f <file> -a <arduino spec> [-p <port>] [-v]
197
# avrgirl-arduino boards
198
# avrgirl-arduino list
199
# avrgirl-arduino test-pilot
200
201
# Show help for invalid command
202
avrgirl-arduino invalid-command
203
# Shows help and exits with error code 9
204
```
205
206
## Error Handling
207
208
The CLI provides specific error messages and appropriate exit codes:
209
210
### Exit Codes
211
212
```bash
213
# Success
214
echo $? # 0
215
216
# Flash failure
217
avrgirl-arduino flash -f missing.hex -a uno
218
echo $? # 1
219
220
# Invalid command or missing arguments
221
avrgirl-arduino flash
222
echo $? # 1
223
224
# Invalid command
225
avrgirl-arduino invalid-command
226
echo $? # 9
227
```
228
229
### Common Error Scenarios
230
231
**Missing Required Arguments:**
232
```bash
233
$ avrgirl-arduino flash -f sketch.hex
234
# Shows help and exits with code 1
235
236
$ avrgirl-arduino flash -a uno
237
# Shows help and exits with code 1
238
```
239
240
**Invalid Board Type:**
241
```bash
242
$ avrgirl-arduino flash -f sketch.hex -a invalid-board
243
# Output: Error: Oops! That board is not supported, sorry.
244
# Exit code: 1
245
```
246
247
**Missing Hex File:**
248
```bash
249
$ avrgirl-arduino flash -f missing.hex -a uno
250
# Output: Error: ENOENT: no such file or directory, open 'missing.hex'
251
# Exit code: 1
252
```
253
254
**Invalid Custom Board File:**
255
```bash
256
$ avrgirl-arduino flash -f sketch.hex -a missing-board.js
257
# Output: Error: Oops! We could not read the custom board file.
258
# Exit code: 1
259
```
260
261
**Permission Issues (Test Pilot):**
262
```bash
263
$ avrgirl-arduino test-pilot
264
# If permission denied:
265
# Output: Error: Oops! We ran into a permissions issue...
266
# you might want to check out this resource
267
# https://docs.npmjs.com/getting-started/fixing-npm-permissions
268
```
269
270
## Global Installation
271
272
Install globally to use the CLI from anywhere:
273
274
```bash
275
# Install globally
276
npm install -g avrgirl-arduino
277
278
# Verify installation
279
which avrgirl-arduino
280
# Output: /usr/local/bin/avrgirl-arduino
281
282
# Check version (via npm)
283
npm list -g avrgirl-arduino --depth=0
284
```
285
286
## Integration Examples
287
288
### Shell Scripts
289
290
```bash
291
#!/bin/bash
292
# flash-sketch.sh
293
294
SKETCH_FILE="$1"
295
BOARD_TYPE="$2"
296
PORT="$3"
297
298
if [ -z "$SKETCH_FILE" ] || [ -z "$BOARD_TYPE" ]; then
299
echo "Usage: $0 <sketch.hex> <board_type> [port]"
300
exit 1
301
fi
302
303
echo "Flashing $SKETCH_FILE to $BOARD_TYPE..."
304
305
if [ -n "$PORT" ]; then
306
avrgirl-arduino flash -f "$SKETCH_FILE" -a "$BOARD_TYPE" -p "$PORT" -v
307
else
308
avrgirl-arduino flash -f "$SKETCH_FILE" -a "$BOARD_TYPE" -v
309
fi
310
311
if [ $? -eq 0 ]; then
312
echo "Flash completed successfully!"
313
else
314
echo "Flash failed!"
315
exit 1
316
fi
317
```
318
319
### Makefile Integration
320
321
```makefile
322
# Makefile for Arduino project
323
324
BOARD_TYPE = uno
325
SKETCH_HEX = build/sketch.hex
326
PORT = /dev/ttyUSB0
327
328
.PHONY: flash flash-auto list-ports boards
329
330
flash:
331
avrgirl-arduino flash -f $(SKETCH_HEX) -a $(BOARD_TYPE) -p $(PORT) -v
332
333
flash-auto:
334
avrgirl-arduino flash -f $(SKETCH_HEX) -a $(BOARD_TYPE) -v
335
336
list-ports:
337
avrgirl-arduino list
338
339
boards:
340
avrgirl-arduino boards
341
342
test-connection:
343
avrgirl-arduino test-pilot
344
```
345
346
### CI/CD Integration
347
348
```yaml
349
# .github/workflows/arduino-flash.yml
350
name: Arduino Flash Test
351
352
on: [push, pull_request]
353
354
jobs:
355
flash-test:
356
runs-on: ubuntu-latest
357
358
steps:
359
- uses: actions/checkout@v2
360
361
- name: Setup Node.js
362
uses: actions/setup-node@v2
363
with:
364
node-version: '16'
365
366
- name: Install avrgirl-arduino
367
run: npm install -g avrgirl-arduino
368
369
- name: List supported boards
370
run: avrgirl-arduino boards
371
372
- name: Validate hex file exists
373
run: test -f firmware.hex
374
375
- name: Dry run (no actual hardware)
376
run: |
377
# Would flash if hardware was connected:
378
# avrgirl-arduino flash -f firmware.hex -a uno
379
echo "Would flash firmware.hex to Arduino Uno"
380
```