CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-arduino-firmata

Node.js implementation of the Arduino Firmata protocol for controlling Arduino boards from JavaScript applications

Overview
Eval results
Files

connection.mddocs/

Connection and Device Management

Core connection functionality for detecting and communicating with Arduino boards over serial ports with automatic device detection and connection management.

Capabilities

ArduinoFirmata Constructor

Creates a new Arduino Firmata instance ready for connection.

/**
 * Creates a new Arduino Firmata instance
 * Initializes internal state and sets up connection variables
 * @returns ArduinoFirmata instance
 */
constructor(): ArduinoFirmata;

Usage Example:

const ArduinoFirmata = require('arduino-firmata');
const arduino = new ArduinoFirmata();

Device Discovery

Lists available serial ports that can be used to connect to Arduino devices.

/**
 * Lists available serial ports for Arduino devices
 * Filters ports to show only USB, COM, ACM, and similar Arduino-compatible devices
 * @param callback - Callback function receiving (error, devices)
 */
ArduinoFirmata.list(callback: (error: Error|null, devices: string[]) => void): void;

Usage Example:

ArduinoFirmata.list(function(err, devices) {
  if (err) {
    console.error('Error listing devices:', err);
    return;
  }
  console.log('Available Arduino devices:', devices);
  // Example output: ['/dev/tty.usbmodem1421', '/dev/tty.usbserial-A1234']
});

Connection

Establishes connection to an Arduino board with automatic port detection and initialization.

/**
 * Connect to Arduino board
 * If no port specified, automatically detects the first available Arduino device
 * @param serialport_name - Optional serial port name (e.g., '/dev/tty.usbmodem1421')
 * @param opts - Optional connection options
 * @returns ArduinoFirmata instance for method chaining
 */
connect(serialport_name?: string, opts?: ConnectionOptions): ArduinoFirmata;

interface ConnectionOptions {
  baudrate?: number; // Communication baud rate, default: 57600
}

Usage Examples:

// Auto-detect Arduino port
arduino.connect();

// Specify port explicitly
arduino.connect('/dev/tty.usbmodem1421');

// Custom baud rate
arduino.connect('/dev/tty.usbmodem1421', { baudrate: 115200 });

// Chaining
const arduino = new ArduinoFirmata().connect();

Connection Status

Check if the Arduino connection is currently open and ready for communication.

/**
 * Check if connection to Arduino is open
 * @returns true if connected and ready, false otherwise
 */
isOpen(): boolean;

Usage Example:

if (arduino.isOpen()) {
  console.log('Arduino is connected and ready');
  arduino.digitalWrite(13, true);
} else {
  console.log('Arduino is not connected');
}

Connection Termination

Properly close the connection to the Arduino board.

/**
 * Close connection to Arduino board
 * Properly terminates the serial connection
 * @param callback - Optional callback function called when connection is closed
 */
close(callback?: Function): void;

Usage Example:

arduino.close(function() {
  console.log('Arduino connection closed');
});

// Or without callback
arduino.close();

Board Reset

Reset the Arduino board to its initial state.

/**
 * Reset the Arduino board
 * Sends a system reset command to restart the Arduino
 * @param callback - Optional callback function called after reset command is sent
 */
reset(callback?: Function): void;

Usage Example:

arduino.reset(function() {
  console.log('Arduino reset command sent');
});

Device Type Detection

Determine if the connected Arduino is an older model that requires different timing.

/**
 * Check if connected device is an older Arduino model
 * Used internally to adjust connection timing
 * @returns true if device is older Arduino model, false for newer models
 */
isOldArduinoDevice(): boolean;

Usage Example:

arduino.on('connect', function() {
  if (arduino.isOldArduinoDevice()) {
    console.log('Connected to older Arduino device');
  } else {
    console.log('Connected to newer Arduino device');
  }
});

Low-level Communication

Direct byte-level communication with the Arduino for advanced use cases.

/**
 * Write raw bytes to the serial port
 * Used internally by other methods, but available for advanced usage
 * @param bytes - Array of byte values (0-255)
 * @param callback - Optional callback function called after bytes are sent
 */
write(bytes: number[], callback?: Function): void;

Usage Example:

// Send raw Firmata protocol bytes
arduino.write([0xF9], function() {
  console.log('Version request sent');
});

Connection Events

Connection-related events are covered in the Event System documentation, including:

  • connect - Fired when Arduino connection is fully established
  • boardReady - Fired when board is detected and initialized
  • boardVersion - Fired when board firmware version is received

Constants

// Connection status values
ArduinoFirmata.Status = {
  CLOSE: 0,  // Connection is closed
  OPEN: 1    // Connection is open and ready
};

Supported Arduino Boards

Arduino Firmata supports a wide range of Arduino-compatible boards:

  • Arduino Diecimila
  • Arduino Duemilanove
  • Arduino UNO
  • Arduino Leonardo
  • Arduino Micro
  • Seeduino v2
  • Any board running StandardFirmata v2.2 or later

Connection Timing

The library automatically adjusts initialization timing based on the Arduino model:

  • Newer Arduino devices: 100ms initialization delay
  • Older Arduino devices: 3000ms initialization delay (detected via USB identifier patterns)

This ensures reliable connection establishment across different Arduino hardware revisions.

Install with Tessl CLI

npx tessl i tessl/npm-arduino-firmata

docs

analog-io.md

connection.md

digital-io.md

events.md

index.md

servo.md

sysex.md

tile.json