rpi-usb
TypeScript icon, indicating that this package has built-in type declarations

1.3.1 • Public • Published

RPi USB Monitor

A TypeScript library for monitoring USB devices on Linux systems, particularly optimized for Raspberry Pi. This package provides robust functionality to list and monitor USB devices using built-in Node.js packages and udev.

Section Description
Features Key features and capabilities
Installation Setup and installation instructions
Usage Detailed usage examples
API Reference Complete API documentation
Error Handling Error handling and logging
Requirements System requirements and dependencies

Features

  • Real-time USB device monitoring using udev
  • Automatic device detection and tracking
  • Graceful shutdown handling
  • TypeScript support with comprehensive types
  • Event-based architecture
  • Platform-specific checks (Linux only)
  • Automatic cleanup on process termination

Installation

npm install rpi-usb

Usage

Basic Setup

import { USBDeviceMonitor } from 'rpi-usb';

// Create a monitor instance
const monitor = new USBDeviceMonitor();

// Start monitoring device changes
monitor.onDeviceChange((event) => {
    console.log(`Device ${event.type}ed:`, event.device);
});

Device Listing

import { listDevices } from 'rpi-usb';

// List all connected USB devices
const devices = listDevices();
console.log('Connected devices:', devices);

Advanced Monitoring

import { USBDeviceMonitor } from 'rpi-usb';

const monitor = new USBDeviceMonitor();

// Add multiple callbacks
monitor.onDeviceChange((event) => {
    if (event.type === 'attach') {
        console.log('New device attached:', event.device);
    } else {
        console.log('Device detached:', event.device);
    }
});

// Remove a callback when no longer needed
const callback = (event) => {
    console.log('Device change:', event);
};
monitor.onDeviceChange(callback);
monitor.removeDeviceChangeListener(callback);

API Reference

USBDeviceMonitor Class

Method Description Parameters Returns
onDeviceChange Register callback for device changes callback: (event: DeviceChangeEvent) => void void
removeDeviceChangeListener Remove a registered callback callback: (event: DeviceChangeEvent) => void void

Types

interface USBDevice {
    DEVPATH: string;
    DEVNAME: string;
    ID_VENDOR?: string;
    ID_MODEL?: string;
    ID_SERIAL?: string;
    ID_VENDOR_ID?: string;
    ID_MODEL_ID?: string;
}

interface DeviceChangeEvent {
    type: 'attach' | 'detach';
    device: USBDevice;
}

Device Properties

The following table describes all available device properties that can be accessed from a USBDevice:

Property Description
DEVPATH Device path in the system
DEVNAME Device name (e.g., /dev/ttyUSB0)
MAJOR Major device number
MINOR Minor device number
SUBSYSTEM Device subsystem (e.g., tty, usb)
USEC_INITIALIZED Time when device was initialized
ID_BUS Bus type (e.g., usb)
ID_MODEL Device model name
ID_MODEL_ENC Encoded device model name
ID_MODEL_ID Device model ID
ID_SERIAL Device serial number
ID_SERIAL_SHORT Shortened device serial number
ID_VENDOR Device vendor name
ID_VENDOR_ENC Encoded device vendor name
ID_VENDOR_ID Device vendor ID
ID_REVISION Device revision number
ID_TYPE Device type
ID_USB_MODEL USB-specific model name
ID_USB_MODEL_ENC Encoded USB-specific model name
ID_USB_MODEL_ID USB-specific model ID
ID_USB_SERIAL USB-specific serial number
ID_USB_SERIAL_SHORT Shortened USB-specific serial number
ID_USB_VENDOR USB-specific vendor name
ID_USB_VENDOR_ENC Encoded USB-specific vendor name
ID_USB_VENDOR_ID USB-specific vendor ID
ID_USB_REVISION USB-specific revision number
ID_USB_TYPE USB-specific device type
ID_USB_INTERFACES USB interface information
ID_USB_INTERFACE_NUM USB interface number
ID_USB_DRIVER USB driver name
ID_VENDOR_FROM_DATABASE Vendor name from USB database
ID_MODEL_FROM_DATABASE Model name from USB database
ID_PATH Device path identifier
ID_PATH_TAG Device path tag
ID_MM_CANDIDATE ModemManager candidate flag
SYSTEMD_WANTS Systemd service dependencies
DEVLINKS Device symbolic links
TAGS Device tags
CURRENT_TAGS Current device tags

Error Handling

The library implements comprehensive error handling and logging. All errors are logged with timestamps and context information.

Error Codes and Descriptions

Error Code Description Solution Level
MONITOR_START_FAILED Failed to start USB monitoring Check system permissions and udev configuration Error
MONITOR_STOP_FAILED Failed to stop USB monitoring Check process permissions Warning
DEVICE_READ_ERROR Failed to read device information Verify device permissions and connection Warning
CALLBACK_ERROR Error in device change callback Review callback implementation Warning

Requirements

  • Node.js 14 or higher
  • Linux system (Raspberry Pi recommended)
  • Root/sudo access for USB monitoring
  • udev installed and configured

Package Sidebar

Install

npm i rpi-usb

Weekly Downloads

11

Version

1.3.1

License

ISC

Unpacked Size

22 kB

Total Files

12

Last publish

Collaborators

  • nickspinelli85