CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-avrgirl-arduino

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

Overview
Eval results
Files

port-management.mddocs/

Port Management

Serial port detection and management functionality for finding, listing, and connecting to Arduino boards across different operating systems.

Capabilities

List Ports (Instance Method)

Lists all available serial ports with additional Arduino-specific information.

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

/**
 * Alias for listPorts method
 * @param {function} callback - Callback function with error and ports array
 */
list(callback: (error?: Error, ports?: SerialPort[]) => void): void;

Usage Examples:

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

const avrgirl = new Avrgirl({ board: 'uno' });

// List ports using instance method
avrgirl.listPorts(function(error, ports) {
  if (error) {
    console.error('Error listing ports:', error);
    return;
  }

  console.log('Available ports:');
  ports.forEach(port => {
    console.log(`- ${port.path} (${port.manufacturer || 'Unknown'})`);
    if (port.productId) {
      console.log(`  Product ID: ${port.productId}`);
    }
  });
});

// Using the alias method
avrgirl.list(function(error, ports) {
  if (error) {
    console.error('Error listing ports:', error);
    return;
  }

  // Filter for Arduino boards
  const arduinoPorts = ports.filter(port =>
    port.manufacturer &&
    port.manufacturer.toLowerCase().includes('arduino')
  );

  console.log(`Found ${arduinoPorts.length} Arduino boards`);
});

List Ports (Static Method)

Static methods for listing ports without creating an Avrgirl instance.

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

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

Usage Examples:

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

// Static method - no instance needed
Avrgirl.listPorts(function(error, ports) {
  if (error) {
    console.error('Error listing ports:', error);
    return;
  }

  console.log('All serial ports:');
  ports.forEach((port, index) => {
    console.log(`${index + 1}. ${port.path}`);
    console.log(`   Manufacturer: ${port.manufacturer || 'Unknown'}`);
    console.log(`   Serial Number: ${port.serialNumber || 'N/A'}`);
    console.log(`   Vendor ID: ${port.vendorId || 'N/A'}`);
    console.log(`   Product ID: ${port.productId || 'N/A'}`);
    console.log('');
  });
});

// Static method with Arduino filtering
Avrgirl.list(function(error, ports) {
  if (error) {
    console.error('Error:', error);
    return;
  }

  // Find ports matching Arduino product IDs
  const arduinoPorts = ports.filter(port => {
    const knownIds = ['0x0043', '0x7523', '0x0001', '0xea60', '0x6015',
                      '0x0037', '0x8037', '0x0036', '0x0237'];
    return knownIds.includes(port.productId);
  });

  if (arduinoPorts.length === 0) {
    console.log('No Arduino boards detected');
  } else {
    console.log(`Detected ${arduinoPorts.length} Arduino board(s):`);
    arduinoPorts.forEach(port => {
      console.log(`- ${port.path} (Product ID: ${port.productId})`);
    });
  }
});

List Known Boards

Returns an array of all supported Arduino board names.

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

Usage Examples:

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

// Get all supported board names
const supportedBoards = Avrgirl.listKnownBoards();

console.log('Supported Arduino boards:');
supportedBoards.forEach((boardName, index) => {
  console.log(`${index + 1}. ${boardName}`);
});

console.log(`\nTotal supported boards: ${supportedBoards.length}`); // Should output: 28

// Check if a specific board is supported
const boardToCheck = 'leonardo';
if (supportedBoards.includes(boardToCheck)) {
  console.log(`✓ ${boardToCheck} is supported`);
} else {
  console.log(`✗ ${boardToCheck} is not supported`);
}

// Create dropdown options for UI
const boardOptions = supportedBoards.map(board => ({
  value: board,
  label: board.charAt(0).toUpperCase() + board.slice(1).replace('-', ' ')
}));

Port Auto-Detection

When no port is specified in the constructor options, Avrgirl Arduino automatically detects the correct port by:

  1. Scanning Available Ports: Lists all serial ports on the system
  2. Product ID Matching: Compares port product IDs against known Arduino board IDs
  3. Manufacturer Detection: Checks for Arduino-related manufacturer strings
  4. Board-Specific Filtering: Matches ports against the specific board type being used

Auto-Detection Example:

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

// No port specified - will auto-detect
const avrgirl = new Avrgirl({
  board: 'uno',
  debug: true  // Enable debug to see detection process
});

avrgirl.flash('sketch.hex', function(error) {
  if (error) {
    if (error.message.includes('no Arduino')) {
      console.log('Auto-detection failed. Try specifying port manually:');

      // List available ports to help user choose
      Avrgirl.listPorts(function(err, ports) {
        if (!err) {
          ports.forEach(port => {
            console.log(`- ${port.path}: ${port.manufacturer || 'Unknown'}`);
          });
        }
      });
    }
  }
});

Types

interface SerialPort {
  path: string;                    // Port path (e.g., '/dev/ttyUSB0', 'COM3')
  manufacturer?: string;           // Device manufacturer name
  serialNumber?: string;           // Device serial number
  pnpId?: string;                 // Plug and Play ID
  locationId?: string;            // Physical location ID
  vendorId?: string;              // USB vendor ID (hex string)
  productId?: string;             // USB product ID (hex string)
  _pid?: string;                  // Platform independent product ID
}

Platform-Specific Port Naming

Linux

  • USB Serial: /dev/ttyUSB0, /dev/ttyUSB1, etc.
  • ACM Devices: /dev/ttyACM0, /dev/ttyACM1, etc.
  • Arduino Leonardo/Micro: Typically /dev/ttyACM0
  • Arduino Uno/Nano: Typically /dev/ttyUSB0

macOS

  • USB Serial: /dev/cu.usbserial-XXXXXXXX
  • Arduino Boards: /dev/cu.usbmodem14101, /dev/cu.usbmodem14201, etc.
  • Bluetooth: /dev/cu.Bluetooth-Incoming-Port (not Arduino)

Windows

  • COM Ports: COM1, COM2, COM3, etc.
  • Arduino Boards: Usually COM3, COM4, COM5, etc.
  • Port Assignment: Dynamic, assigned by Windows Device Manager

Board Product IDs

Each Arduino board type has specific USB product IDs for detection:

const boardProductIds = {
  'uno': ['0x0043', '0x7523', '0x0001', '0xea60', '0x6015'],
  'leonardo': ['0x0036', '0x8036', '0x800c'],
  'micro': ['0x0037', '0x8037', '0x0036', '0x0237'],
  'mega': ['0x0042', '0x7523', '0x0001'],
  'nano': ['0x7523', '0x0001'],
  // ... additional boards
};

Error Handling

Common port-related errors and their handling:

// Port listing errors
"Error listing serial ports"
"Access denied to serial port"

// Connection errors
"Port not found: /dev/ttyUSB0"
"Port already in use"
"Permission denied: /dev/ttyACM0"

// Auto-detection errors
"no Arduino 'uno' found."
"Multiple Arduino boards detected, please specify port"

Error Handling Example:

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

function handlePortError(error, boardType) {
  if (error.message.includes('no Arduino')) {
    console.log(`No ${boardType} board detected. Please check:`);
    console.log('1. Arduino is connected via USB');
    console.log('2. Arduino drivers are installed');
    console.log('3. Arduino is not already in use by another program');

    // List available ports for troubleshooting
    Avrgirl.listPorts((err, ports) => {
      if (!err && ports.length > 0) {
        console.log('\nAvailable serial ports:');
        ports.forEach(port => {
          console.log(`- ${port.path}: ${port.manufacturer || 'Unknown'}`);
        });
      }
    });
  } else if (error.message.includes('Permission denied')) {
    console.log('Permission error. On Linux, try:');
    console.log('sudo usermod -a -G dialout $USER');
    console.log('Then log out and log back in.');
  }
}

// Usage
const avrgirl = new Avrgirl({ board: 'uno' });
avrgirl.flash('sketch.hex', (error) => {
  if (error) {
    handlePortError(error, 'uno');
  }
});

Install with Tessl CLI

npx tessl i tessl/npm-avrgirl-arduino

docs

cli.md

flashing.md

index.md

port-management.md

tile.json