or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdflashing.mdindex.mdport-management.md
tile.json

tessl/npm-avrgirl-arduino

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/avrgirl-arduino@5.0.x

To install, run

npx @tessl/cli install tessl/npm-avrgirl-arduino@5.0.0

index.mddocs/

Avrgirl Arduino

Avrgirl Arduino is a NodeJS library for flashing compiled sketch files (.hex files) to Arduino microcontroller boards. It provides automatic board detection, supports multiple communication protocols, and works across Node.js and browser environments. The library supports 28 different Arduino board types and handles the complete firmware upload process automatically.

Package Information

  • Package Name: avrgirl-arduino
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install avrgirl-arduino

Core Imports

const Avrgirl = require('avrgirl-arduino');

For browser environments:

<script src="node_modules/avrgirl-arduino/dist/avrgirl-arduino.min.js"></script>

Basic Usage

const Avrgirl = require('avrgirl-arduino');

// Create instance for Arduino Uno
const avrgirl = new Avrgirl({
  board: 'uno'
});

// Flash a hex file to the Arduino
avrgirl.flash('path/to/sketch.hex', function(error) {
  if (error) {
    console.error('Flash failed:', error);
  } else {
    console.log('Flash completed successfully!');
  }
});

Architecture

Avrgirl Arduino uses a modular architecture with the following key components:

  • Main Class: AvrgirlArduino provides the primary flashing API and configuration management
  • Connection Management: Handles serial port communication, auto-detection, and port management
  • Protocol Handlers: Implements STK500v1, STK500v2, and AVR109 protocols for different board types
  • Board Configuration: Comprehensive database of Arduino board specifications and communication parameters
  • Hex File Processing: Tools for parsing and processing Intel HEX format firmware files

Capabilities

Arduino Flashing

Core functionality for uploading compiled sketch files to Arduino boards with automatic board detection and protocol selection.

/**
 * Main Arduino flashing class
 * @param {object} options - Configuration options
 */
function AvrgirlArduino(options);

interface AvrgirlArduinoOptions {
  board: string | BoardConfig;      // Board type name or custom config
  port?: string;                    // Serial port (auto-detected if omitted)
  debug?: boolean | function;       // Debug logging: true/false or custom function
  megaDebug?: boolean;             // Enhanced protocol-level debugging
  manualReset?: boolean;           // Manual reset configuration for AVR109 boards
  disableVerify?: boolean;         // Skip verification after flash for AVR109 boards
}

/**
 * Flash a hex file to the Arduino board
 * @param {string|Buffer} file - Path to hex file or Buffer containing hex data
 * @param {function} callback - Completion callback
 */
flash(file: string | Buffer, callback: (error?: Error) => void): void;

Arduino Flashing

Port Management

Serial port detection and management functionality for finding and connecting to Arduino boards.

/**
 * List available serial ports with Arduino detection
 * @param {function} callback - Callback with ports list
 */
listPorts(callback: (error?: Error, ports?: SerialPort[]) => void): void;

/**
 * Static method to list serial ports
 * @param {function} callback - Callback with ports list
 */
AvrgirlArduino.listPorts(callback: (error?: Error, ports?: SerialPort[]) => void): void;

/**
 * Get list of all supported Arduino board names
 * @returns {string[]} Array of board name strings (28 boards total)
 */
AvrgirlArduino.listKnownBoards(): string[];

interface SerialPort {
  path: string;
  manufacturer?: string;
  serialNumber?: string;
  pnpId?: string;
  locationId?: string;
  vendorId?: string;
  productId?: string;
  _pid?: string;  // Platform independent product ID
}

Port Management

Command Line Interface

CLI tool for flashing Arduino boards directly from the command line with support for custom board configurations.

# Flash a hex file to Arduino board
avrgirl-arduino flash -f <file> -a <arduino_type> [-p <port>] [-v]

# List all supported board types
avrgirl-arduino boards

# List available serial ports
avrgirl-arduino list

# Run hardware test pilot
avrgirl-arduino test-pilot

# Show help information
avrgirl-arduino help

Command Line Interface

Board Support

The library supports 28 Arduino board types including:

Popular Boards: uno, mega, leonardo, micro, nano, nano (new bootloader), duemilanove168, duemilanove328, pro-mini, adk, lilypad-usb, yun, esplora

Specialty Boards: imuduino, blend-micro, tinyduino, sf-pro-micro, qduino, pinoccio, feather, arduboy, circuit-playground-classic, little-bits

BQ Boards: zumjunior, zumcore2, bqZum

Other Boards: xprov4 (Spark Concepts xPro V4)

Each board configuration includes communication parameters, USB product IDs, protocol specifications, and timing requirements.

Browser Support Limitation: AVR109 protocol boards (Leonardo, Micro, etc.) are not supported in browser environments due to WebSerial API limitations.

Types

interface BoardConfig {
  name: string;                    // Board identifier
  baud: number;                   // Serial communication baud rate
  signature: Buffer;              // Board signature for identification
  pageSize?: number;              // Memory page size (STK500 boards)
  numPages?: number;              // Number of memory pages (STK500 boards)
  timeout?: number;               // Communication timeout in ms
  productId: string[];            // USB product ID values
  productPage: string;            // URL to product information
  protocol: 'stk500v1' | 'stk500v2' | 'avr109';  // Communication protocol
  aliases?: string[];             // Alternative board names
  manualReset?: boolean;          // Manual reset configuration
  disableVerify?: boolean;        // Verification settings
}

interface AvrgirlArduinoInstance extends EventEmitter {
  options: AvrgirlArduinoOptions;
  debug: function;
  connection: Connection;
  protocol: Protocol;
  tools: Tools;

  flash(file: string | Buffer, callback: (error?: Error) => void): void;
  listPorts(callback: (error?: Error, ports?: SerialPort[]) => void): void;
  list(callback: (error?: Error, ports?: SerialPort[]) => void): void;

  // EventEmitter methods
  on(event: string, listener: Function): this;
  emit(event: string, ...args: any[]): boolean;
  removeListener(event: string, listener: Function): this;
  removeAllListeners(event?: string): this;
}

interface Tools {
  _parseHex(file: string | Buffer): Buffer | Error;  // Parse Intel HEX format
  _hexStringToByte(str: string): Buffer;             // Convert hex string to Buffer
}