tessl/npm-avrgirl-arduino

A NodeJS library for flashing compiled sketch files to Arduino microcontroller boards.

Overview

Eval results

Files

Command Line Interface

Name: tessl/npm-avrgirl-arduino
Author: tessl

Command-line tool for flashing Arduino boards directly from the terminal, with support for custom board configurations, port selection, and hardware testing.

Capabilities

Flash Command

Flash a hex file to an Arduino board with automatic board detection and protocol handling.

avrgirl-arduino flash -f <file> -a <arduino_type> [-p <port>] [-v]

Parameters:

-f <file>: Path to the hex file to flash (required)
-a <arduino_type>: Arduino board type or path to custom board file (required)
-p <port>: Serial port path (optional, auto-detected if not specified)
-v: Enable verbose debug output (optional)

Usage Examples:

# Flash sketch to Arduino Uno (auto-detect port)
avrgirl-arduino flash -f sketch.hex -a uno

# Flash to Leonardo on specific port
avrgirl-arduino flash -f firmware.hex -a leonardo -p /dev/ttyACM0

# Flash with verbose output
avrgirl-arduino flash -f blink.hex -a nano -v

# Windows example
avrgirl-arduino flash -f sketch.hex -a uno -p COM3

# Flash to Arduino Mega with debugging
avrgirl-arduino flash -f complex_sketch.hex -a mega -p COM5 -v

Custom Board File:

# Create custom board configuration file (my-board.js)
echo "module.exports = {
  name: 'my-custom-board',
  baud: 115200,
  signature: Buffer.from([0x1e, 0x95, 0x0f]),
  pageSize: 128,
  numPages: 256,
  timeout: 400,
  productId: ['0x0043'],
  protocol: 'stk500v1'
};" > my-board.js

# Use custom board configuration
avrgirl-arduino flash -f sketch.hex -a my-board.js

Boards Command

List all supported Arduino board types.

avrgirl-arduino boards

Usage Examples:

# List all supported boards
avrgirl-arduino boards

# Output:
# Supported Boards:
#  - adk
#  - arduboy
#  - bqZum
#  - circuit-playground-classic
#  - duemilanove168
#  - esplora
#  - feather
#  - imuduino
#  - leonardo
#  - lilypad-usb
#  - mega
#  - micro
#  - nano
#  - pinoccio
#  - pro-mini
#  - qduino
#  - sparkfun-pro-micro
#  - tinyduino
#  - uno
#  - xprov4
#  - yun
#  - zumcore2
#  - zumjunior

# Filter boards (using grep on Unix systems)
avrgirl-arduino boards | grep nano
# Output: - nano

# Count supported boards
avrgirl-arduino boards | grep -c " - "
# Output: 27

List Command

Display all available serial ports on the system.

avrgirl-arduino list

Usage Examples:

# List all serial ports
avrgirl-arduino list

# Example output on Linux:
# [
#   {
#     "path": "/dev/ttyUSB0",
#     "manufacturer": "Arduino (www.arduino.cc)",
#     "serialNumber": "55432333038351F03170",
#     "vendorId": "0x2341",
#     "productId": "0x0043"
#   },
#   {
#     "path": "/dev/ttyS0",
#     "manufacturer": "",
#     "serialNumber": "",
#     "vendorId": "",
#     "productId": ""
#   }
# ]

# Parse output with jq (if available)
avrgirl-arduino list | jq '.[].path'
# Output:
# "/dev/ttyUSB0"
# "/dev/ttyS0"

# Filter for Arduino devices
avrgirl-arduino list | jq '.[] | select(.manufacturer | contains("Arduino"))'

Test Pilot Command

Run the hardware test pilot program to verify Arduino connectivity and functionality.

avrgirl-arduino test-pilot

Usage Examples:

# Run test pilot
avrgirl-arduino test-pilot

# Output (if not installed):
# running preflight check...
# installing test pilot, won't be long...
# [installation progress for avrga-tester package]

# Output (if already installed):
# running preflight check...
# [comprehensive hardware connectivity tests]

The test pilot program:

Checks for existing avrga-tester dependency installation
Automatically installs test pilot if not present (requires npm permissions)
Runs comprehensive hardware connectivity tests
Provides detailed feedback on Arduino board detection and communication capabilities
Tests serial port communication and protocol verification

Help Command

Display usage information and command help.

avrgirl-arduino help

Usage Examples:

# Show help
avrgirl-arduino help

# Output:
# Usage:
#   avrgirl-arduino flash -f <file> -a <arduino spec> [-p <port>] [-v]
#   avrgirl-arduino boards
#   avrgirl-arduino list
#   avrgirl-arduino test-pilot

# Show help for invalid command
avrgirl-arduino invalid-command
# Shows help and exits with error code 9

Error Handling

The CLI provides specific error messages and appropriate exit codes:

Exit Codes

# Success
echo $?  # 0

# Flash failure
avrgirl-arduino flash -f missing.hex -a uno
echo $?  # 1

# Invalid command or missing arguments
avrgirl-arduino flash
echo $?  # 1

# Invalid command
avrgirl-arduino invalid-command
echo $?  # 9

Common Error Scenarios

Missing Required Arguments:

$ avrgirl-arduino flash -f sketch.hex
# Shows help and exits with code 1

$ avrgirl-arduino flash -a uno
# Shows help and exits with code 1

Invalid Board Type:

$ avrgirl-arduino flash -f sketch.hex -a invalid-board
# Output: Error: Oops! That board is not supported, sorry.
# Exit code: 1

Missing Hex File:

$ avrgirl-arduino flash -f missing.hex -a uno
# Output: Error: ENOENT: no such file or directory, open 'missing.hex'
# Exit code: 1

Invalid Custom Board File:

$ avrgirl-arduino flash -f sketch.hex -a missing-board.js
# Output: Error: Oops! We could not read the custom board file.
# Exit code: 1

Permission Issues (Test Pilot):

$ avrgirl-arduino test-pilot
# If permission denied:
# Output: Error: Oops! We ran into a permissions issue...
# you might want to check out this resource
# https://docs.npmjs.com/getting-started/fixing-npm-permissions

Global Installation

Install globally to use the CLI from anywhere:

# Install globally
npm install -g avrgirl-arduino

# Verify installation
which avrgirl-arduino
# Output: /usr/local/bin/avrgirl-arduino

# Check version (via npm)
npm list -g avrgirl-arduino --depth=0

Integration Examples

Shell Scripts

#!/bin/bash
# flash-sketch.sh

SKETCH_FILE="$1"
BOARD_TYPE="$2"
PORT="$3"

if [ -z "$SKETCH_FILE" ] || [ -z "$BOARD_TYPE" ]; then
    echo "Usage: $0 <sketch.hex> <board_type> [port]"
    exit 1
fi

echo "Flashing $SKETCH_FILE to $BOARD_TYPE..."

if [ -n "$PORT" ]; then
    avrgirl-arduino flash -f "$SKETCH_FILE" -a "$BOARD_TYPE" -p "$PORT" -v
else
    avrgirl-arduino flash -f "$SKETCH_FILE" -a "$BOARD_TYPE" -v
fi

if [ $? -eq 0 ]; then
    echo "Flash completed successfully!"
else
    echo "Flash failed!"
    exit 1
fi

Makefile Integration

# Makefile for Arduino project

BOARD_TYPE = uno
SKETCH_HEX = build/sketch.hex
PORT = /dev/ttyUSB0

.PHONY: flash flash-auto list-ports boards

flash:
	avrgirl-arduino flash -f $(SKETCH_HEX) -a $(BOARD_TYPE) -p $(PORT) -v

flash-auto:
	avrgirl-arduino flash -f $(SKETCH_HEX) -a $(BOARD_TYPE) -v

list-ports:
	avrgirl-arduino list

boards:
	avrgirl-arduino boards

test-connection:
	avrgirl-arduino test-pilot

CI/CD Integration

# .github/workflows/arduino-flash.yml
name: Arduino Flash Test

on: [push, pull_request]

jobs:
  flash-test:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2

    - name: Setup Node.js
      uses: actions/setup-node@v2
      with:
        node-version: '16'

    - name: Install avrgirl-arduino
      run: npm install -g avrgirl-arduino

    - name: List supported boards
      run: avrgirl-arduino boards

    - name: Validate hex file exists
      run: test -f firmware.hex

    - name: Dry run (no actual hardware)
      run: |
        # Would flash if hardware was connected:
        # avrgirl-arduino flash -f firmware.hex -a uno
        echo "Would flash firmware.hex to Arduino Uno"

Install with Tessl CLI