0
# Arduino Firmata
1
2
Arduino Firmata is a Node.js library that implements the Arduino Firmata protocol, enabling developers to control Arduino boards directly from JavaScript applications. It provides a comprehensive API for digital I/O operations, analog I/O with PWM support, servo motor control, and custom SysEx message handling with real-time event-driven communication.
3
4
## Package Information
5
6
- **Package Name**: arduino-firmata
7
- **Package Type**: npm
8
- **Language**: JavaScript (compiled from CoffeeScript)
9
- **Installation**: `npm install arduino-firmata`
10
11
## Core Imports
12
13
```javascript
14
const ArduinoFirmata = require('arduino-firmata');
15
```
16
17
## Basic Usage
18
19
```javascript
20
const ArduinoFirmata = require('arduino-firmata');
21
const arduino = new ArduinoFirmata();
22
23
// Connect to Arduino (auto-detects port)
24
arduino.connect();
25
26
arduino.on('connect', function(){
27
console.log("Connected to: " + arduino.serialport_name);
28
console.log("Board version: " + arduino.boardVersion);
29
30
// Basic digital I/O
31
arduino.digitalWrite(13, true); // Turn on LED
32
arduino.digitalWrite(13, false); // Turn off LED
33
34
// Analog operations
35
arduino.analogWrite(9, 128); // PWM output (50%)
36
const reading = arduino.analogRead(0); // Read analog pin
37
38
// Servo control
39
arduino.servoWrite(11, 90); // Move servo to 90 degrees
40
});
41
```
42
43
## Architecture
44
45
Arduino Firmata is built around several key components:
46
47
- **Connection Management**: Auto-detection of Arduino devices and connection handling
48
- **Event System**: Real-time pin state change monitoring via EventEmitter2
49
- **Protocol Implementation**: Complete Firmata 2.2 protocol with binary message parsing
50
- **I/O Operations**: Digital/analog read/write operations with pin mode management
51
- **SysEx Support**: Custom message system for extended functionality
52
- **Multi-Process Support**: Ability to share Arduino connections across Node.js processes
53
54
## Capabilities
55
56
### Connection and Device Management
57
58
Core connection functionality for detecting and communicating with Arduino boards over serial ports.
59
60
```javascript { .api }
61
class ArduinoFirmata extends EventEmitter2 {
62
constructor();
63
connect(serialport_name?: string, opts?: ConnectionOptions): ArduinoFirmata;
64
close(callback?: Function): void;
65
reset(callback?: Function): void;
66
write(bytes: number[], callback?: Function): void;
67
isOpen(): boolean;
68
}
69
70
interface ConnectionOptions {
71
baudrate?: number; // default: 57600
72
}
73
74
// Static methods
75
ArduinoFirmata.list(callback: (error: Error|null, devices: string[]) => void): void;
76
```
77
78
[Connection and Device Management](./connection.md)
79
80
### Digital I/O Operations
81
82
Digital pin control for reading and writing binary states, with real-time change monitoring.
83
84
```javascript { .api }
85
// Digital I/O methods
86
pinMode(pin: number, mode: number|boolean, callback?: Function): void;
87
digitalWrite(pin: number, value: boolean|number, callback?: Function): void;
88
digitalRead(pin: number): boolean;
89
90
// Pin mode constants
91
ArduinoFirmata.INPUT = 0;
92
ArduinoFirmata.OUTPUT = 1;
93
ArduinoFirmata.LOW = 0;
94
ArduinoFirmata.HIGH = 1;
95
```
96
97
[Digital I/O Operations](./digital-io.md)
98
99
### Analog I/O and PWM
100
101
Analog input reading and PWM output control for interfacing with sensors and controlling analog devices.
102
103
```javascript { .api }
104
// Analog I/O methods
105
analogWrite(pin: number, value: number, callback?: Function): void;
106
analogRead(pin: number): number;
107
108
// Additional pin mode constants
109
ArduinoFirmata.ANALOG = 2;
110
ArduinoFirmata.PWM = 3;
111
```
112
113
[Analog I/O and PWM](./analog-io.md)
114
115
### Servo Control
116
117
Servo motor control with angle-based positioning for robotics and automation projects.
118
119
```javascript { .api }
120
servoWrite(pin: number, angle: number, callback?: Function): void;
121
122
// Servo mode constant
123
ArduinoFirmata.SERVO = 4;
124
```
125
126
[Servo Control](./servo.md)
127
128
### SysEx Messaging
129
130
Custom system exclusive messaging for extended Arduino functionality beyond standard Firmata operations.
131
132
```javascript { .api }
133
sysex(command: number, data?: number[], callback?: Function): void;
134
135
// SysEx protocol constants
136
ArduinoFirmata.START_SYSEX = 0xF0;
137
ArduinoFirmata.END_SYSEX = 0xF7;
138
```
139
140
[SysEx Messaging](./sysex.md)
141
142
### Event System
143
144
Real-time event monitoring for pin state changes, board connection status, and custom SysEx messages.
145
146
```javascript { .api }
147
// Event types (EventEmitter2 events)
148
// 'connect' - Fired when Arduino connection is established
149
// 'boardReady' - Fired when board is detected and initialized
150
// 'boardVersion' - Fired when board version is received
151
// 'digitalChange' - Fired when digital pin state changes
152
// 'analogChange' - Fired when analog pin value changes
153
// 'sysex' - Fired when SysEx message is received
154
155
interface DigitalChangeEvent {
156
pin: number;
157
value: boolean;
158
old_value: boolean;
159
}
160
161
interface AnalogChangeEvent {
162
pin: number;
163
value: number; // 0-1023
164
old_value: number;
165
}
166
167
interface SysexEvent {
168
command: number;
169
data: number[];
170
}
171
```
172
173
[Event System](./events.md)
174
175
## Constants and Status Values
176
177
```javascript { .api }
178
// Connection status
179
ArduinoFirmata.Status = {
180
CLOSE: 0,
181
OPEN: 1
182
};
183
184
// Pin modes
185
ArduinoFirmata.INPUT = 0;
186
ArduinoFirmata.OUTPUT = 1;
187
ArduinoFirmata.ANALOG = 2;
188
ArduinoFirmata.PWM = 3;
189
ArduinoFirmata.SERVO = 4;
190
ArduinoFirmata.SHIFT = 5;
191
ArduinoFirmata.I2C = 6;
192
193
// Digital values
194
ArduinoFirmata.LOW = 0;
195
ArduinoFirmata.HIGH = 1;
196
197
// Protocol constants
198
ArduinoFirmata.MAX_DATA_BYTES = 32;
199
ArduinoFirmata.DIGITAL_MESSAGE = 0x90;
200
ArduinoFirmata.ANALOG_MESSAGE = 0xE0;
201
ArduinoFirmata.REPORT_ANALOG = 0xC0;
202
ArduinoFirmata.REPORT_DIGITAL = 0xD0;
203
ArduinoFirmata.SET_PIN_MODE = 0xF4;
204
ArduinoFirmata.REPORT_VERSION = 0xF9;
205
ArduinoFirmata.SYSTEM_RESET = 0xFF;
206
ArduinoFirmata.START_SYSEX = 0xF0;
207
ArduinoFirmata.END_SYSEX = 0xF7;
208
```
209
210
## Instance Properties
211
212
```javascript { .api }
213
interface ArduinoFirmataInstance {
214
readonly status: number; // Status.CLOSE (0) or Status.OPEN (1)
215
readonly serialport_name: string; // Name of connected serial port
216
readonly boardVersion: string; // Arduino board firmware version (e.g. "2.3")
217
}
218
```