0
# Connection and Device Management
1

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

4
## Capabilities
5

6
### ArduinoFirmata Constructor
7

8
Creates a new Arduino Firmata instance ready for connection.
9

10
```javascript { .api }
11
/**
12
 * Creates a new Arduino Firmata instance
13
 * Initializes internal state and sets up connection variables
14
 * @returns ArduinoFirmata instance
15
 */
16
constructor(): ArduinoFirmata;
17
```
18

19
**Usage Example:**
20

21
```javascript
22
const ArduinoFirmata = require('arduino-firmata');
23
const arduino = new ArduinoFirmata();
24
```
25

26
### Device Discovery
27

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

30
```javascript { .api }
31
/**
32
 * Lists available serial ports for Arduino devices
33
 * Filters ports to show only USB, COM, ACM, and similar Arduino-compatible devices
34
 * @param callback - Callback function receiving (error, devices)
35
 */
36
ArduinoFirmata.list(callback: (error: Error|null, devices: string[]) => void): void;
37
```
38

39
**Usage Example:**
40

41
```javascript
42
ArduinoFirmata.list(function(err, devices) {
43
  if (err) {
44
    console.error('Error listing devices:', err);
45
    return;
46
  }
47
  console.log('Available Arduino devices:', devices);
48
  // Example output: ['/dev/tty.usbmodem1421', '/dev/tty.usbserial-A1234']
49
});
50
```
51

52
### Connection
53

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

56
```javascript { .api }
57
/**
58
 * Connect to Arduino board
59
 * If no port specified, automatically detects the first available Arduino device
60
 * @param serialport_name - Optional serial port name (e.g., '/dev/tty.usbmodem1421')
61
 * @param opts - Optional connection options
62
 * @returns ArduinoFirmata instance for method chaining
63
 */
64
connect(serialport_name?: string, opts?: ConnectionOptions): ArduinoFirmata;
65

66
interface ConnectionOptions {
67
  baudrate?: number; // Communication baud rate, default: 57600
68
}
69
```
70

71
**Usage Examples:**
72

73
```javascript
74
// Auto-detect Arduino port
75
arduino.connect();
76

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

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

83
// Chaining
84
const arduino = new ArduinoFirmata().connect();
85
```
86

87
### Connection Status
88

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

91
```javascript { .api }
92
/**
93
 * Check if connection to Arduino is open
94
 * @returns true if connected and ready, false otherwise
95
 */
96
isOpen(): boolean;
97
```
98

99
**Usage Example:**
100

101
```javascript
102
if (arduino.isOpen()) {
103
  console.log('Arduino is connected and ready');
104
  arduino.digitalWrite(13, true);
105
} else {
106
  console.log('Arduino is not connected');
107
}
108
```
109

110
### Connection Termination
111

112
Properly close the connection to the Arduino board.
113

114
```javascript { .api }
115
/**
116
 * Close connection to Arduino board
117
 * Properly terminates the serial connection
118
 * @param callback - Optional callback function called when connection is closed
119
 */
120
close(callback?: Function): void;
121
```
122

123
**Usage Example:**
124

125
```javascript
126
arduino.close(function() {
127
  console.log('Arduino connection closed');
128
});
129

130
// Or without callback
131
arduino.close();
132
```
133

134
### Board Reset
135

136
Reset the Arduino board to its initial state.
137

138
```javascript { .api }
139
/**
140
 * Reset the Arduino board
141
 * Sends a system reset command to restart the Arduino
142
 * @param callback - Optional callback function called after reset command is sent
143
 */
144
reset(callback?: Function): void;
145
```
146

147
**Usage Example:**
148

149
```javascript
150
arduino.reset(function() {
151
  console.log('Arduino reset command sent');
152
});
153
```
154

155
### Device Type Detection
156

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

159
```javascript { .api }
160
/**
161
 * Check if connected device is an older Arduino model
162
 * Used internally to adjust connection timing
163
 * @returns true if device is older Arduino model, false for newer models
164
 */
165
isOldArduinoDevice(): boolean;
166
```
167

168
**Usage Example:**
169

170
```javascript
171
arduino.on('connect', function() {
172
  if (arduino.isOldArduinoDevice()) {
173
    console.log('Connected to older Arduino device');
174
  } else {
175
    console.log('Connected to newer Arduino device');
176
  }
177
});
178
```
179

180
### Low-level Communication
181

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

184
```javascript { .api }
185
/**
186
 * Write raw bytes to the serial port
187
 * Used internally by other methods, but available for advanced usage
188
 * @param bytes - Array of byte values (0-255)
189
 * @param callback - Optional callback function called after bytes are sent
190
 */
191
write(bytes: number[], callback?: Function): void;
192
```
193

194
**Usage Example:**
195

196
```javascript
197
// Send raw Firmata protocol bytes
198
arduino.write([0xF9], function() {
199
  console.log('Version request sent');
200
});
201
```
202

203
## Connection Events
204

205
Connection-related events are covered in the [Event System](./events.md) documentation, including:
206

207
- `connect` - Fired when Arduino connection is fully established
208
- `boardReady` - Fired when board is detected and initialized
209
- `boardVersion` - Fired when board firmware version is received
210

211
## Constants
212

213
```javascript { .api }
214
// Connection status values
215
ArduinoFirmata.Status = {
216
  CLOSE: 0,  // Connection is closed
217
  OPEN: 1    // Connection is open and ready
218
};
219
```
220

221
## Supported Arduino Boards
222

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

225
- Arduino Diecimila
226
- Arduino Duemilanove
227
- Arduino UNO
228
- Arduino Leonardo
229
- Arduino Micro
230
- Seeduino v2
231
- Any board running StandardFirmata v2.2 or later
232

233
## Connection Timing
234

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

237
- **Newer Arduino devices**: 100ms initialization delay
238
- **Older Arduino devices**: 3000ms initialization delay (detected via USB identifier patterns)
239

240
This ensures reliable connection establishment across different Arduino hardware revisions.