0
# Port Management
1

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

4
## Capabilities
5

6
### List Ports (Instance Method)
7

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

10
```javascript { .api }
11
/**
12
 * List available serial ports with Arduino detection
13
 * @param {function} callback - Callback function with error and ports array
14
 */
15
listPorts(callback: (error?: Error, ports?: SerialPort[]) => void): void;
16

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

24
**Usage Examples:**
25

26
```javascript
27
const Avrgirl = require('avrgirl-arduino');
28

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

31
// List ports using instance method
32
avrgirl.listPorts(function(error, ports) {
33
  if (error) {
34
    console.error('Error listing ports:', error);
35
    return;
36
  }
37

38
  console.log('Available ports:');
39
  ports.forEach(port => {
40
    console.log(`- ${port.path} (${port.manufacturer || 'Unknown'})`);
41
    if (port.productId) {
42
      console.log(`  Product ID: ${port.productId}`);
43
    }
44
  });
45
});
46

47
// Using the alias method
48
avrgirl.list(function(error, ports) {
49
  if (error) {
50
    console.error('Error listing ports:', error);
51
    return;
52
  }
53

54
  // Filter for Arduino boards
55
  const arduinoPorts = ports.filter(port =>
56
    port.manufacturer &&
57
    port.manufacturer.toLowerCase().includes('arduino')
58
  );
59

60
  console.log(`Found ${arduinoPorts.length} Arduino boards`);
61
});
62
```
63

64
### List Ports (Static Method)
65

66
Static methods for listing ports without creating an Avrgirl instance.
67

68
```javascript { .api }
69
/**
70
 * Static method to list all available serial ports
71
 * @param {function} callback - Callback function with error and ports array
72
 */
73
AvrgirlArduino.listPorts(callback: (error?: Error, ports?: SerialPort[]) => void): void;
74

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

82
**Usage Examples:**
83

84
```javascript
85
const Avrgirl = require('avrgirl-arduino');
86

87
// Static method - no instance needed
88
Avrgirl.listPorts(function(error, ports) {
89
  if (error) {
90
    console.error('Error listing ports:', error);
91
    return;
92
  }
93

94
  console.log('All serial ports:');
95
  ports.forEach((port, index) => {
96
    console.log(`${index + 1}. ${port.path}`);
97
    console.log(`   Manufacturer: ${port.manufacturer || 'Unknown'}`);
98
    console.log(`   Serial Number: ${port.serialNumber || 'N/A'}`);
99
    console.log(`   Vendor ID: ${port.vendorId || 'N/A'}`);
100
    console.log(`   Product ID: ${port.productId || 'N/A'}`);
101
    console.log('');
102
  });
103
});
104

105
// Static method with Arduino filtering
106
Avrgirl.list(function(error, ports) {
107
  if (error) {
108
    console.error('Error:', error);
109
    return;
110
  }
111

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

119
  if (arduinoPorts.length === 0) {
120
    console.log('No Arduino boards detected');
121
  } else {
122
    console.log(`Detected ${arduinoPorts.length} Arduino board(s):`);
123
    arduinoPorts.forEach(port => {
124
      console.log(`- ${port.path} (Product ID: ${port.productId})`);
125
    });
126
  }
127
});
128
```
129

130
### List Known Boards
131

132
Returns an array of all supported Arduino board names.
133

134
```javascript { .api }
135
/**
136
 * Get list of all supported Arduino board names
137
 * @returns {string[]} Array of board name strings
138
 */
139
AvrgirlArduino.listKnownBoards(): string[];
140
```
141

142
**Usage Examples:**
143

144
```javascript
145
const Avrgirl = require('avrgirl-arduino');
146

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

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

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

157
// Check if a specific board is supported
158
const boardToCheck = 'leonardo';
159
if (supportedBoards.includes(boardToCheck)) {
160
  console.log(`✓ ${boardToCheck} is supported`);
161
} else {
162
  console.log(`✗ ${boardToCheck} is not supported`);
163
}
164

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

172
## Port Auto-Detection
173

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

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

181
**Auto-Detection Example:**
182

183
```javascript
184
const Avrgirl = require('avrgirl-arduino');
185

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

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

197
      // List available ports to help user choose
198
      Avrgirl.listPorts(function(err, ports) {
199
        if (!err) {
200
          ports.forEach(port => {
201
            console.log(`- ${port.path}: ${port.manufacturer || 'Unknown'}`);
202
          });
203
        }
204
      });
205
    }
206
  }
207
});
208
```
209

210
## Types
211

212
```javascript { .api }
213
interface SerialPort {
214
  path: string;                    // Port path (e.g., '/dev/ttyUSB0', 'COM3')
215
  manufacturer?: string;           // Device manufacturer name
216
  serialNumber?: string;           // Device serial number
217
  pnpId?: string;                 // Plug and Play ID
218
  locationId?: string;            // Physical location ID
219
  vendorId?: string;              // USB vendor ID (hex string)
220
  productId?: string;             // USB product ID (hex string)
221
  _pid?: string;                  // Platform independent product ID
222
}
223
```
224

225
## Platform-Specific Port Naming
226

227
### Linux
228
- **USB Serial**: `/dev/ttyUSB0`, `/dev/ttyUSB1`, etc.
229
- **ACM Devices**: `/dev/ttyACM0`, `/dev/ttyACM1`, etc.
230
- **Arduino Leonardo/Micro**: Typically `/dev/ttyACM0`
231
- **Arduino Uno/Nano**: Typically `/dev/ttyUSB0`
232

233
### macOS
234
- **USB Serial**: `/dev/cu.usbserial-XXXXXXXX`
235
- **Arduino Boards**: `/dev/cu.usbmodem14101`, `/dev/cu.usbmodem14201`, etc.
236
- **Bluetooth**: `/dev/cu.Bluetooth-Incoming-Port` (not Arduino)
237

238
### Windows
239
- **COM Ports**: `COM1`, `COM2`, `COM3`, etc.
240
- **Arduino Boards**: Usually `COM3`, `COM4`, `COM5`, etc.
241
- **Port Assignment**: Dynamic, assigned by Windows Device Manager
242

243
## Board Product IDs
244

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

247
```javascript
248
const boardProductIds = {
249
  'uno': ['0x0043', '0x7523', '0x0001', '0xea60', '0x6015'],
250
  'leonardo': ['0x0036', '0x8036', '0x800c'],
251
  'micro': ['0x0037', '0x8037', '0x0036', '0x0237'],
252
  'mega': ['0x0042', '0x7523', '0x0001'],
253
  'nano': ['0x7523', '0x0001'],
254
  // ... additional boards
255
};
256
```
257

258
## Error Handling
259

260
Common port-related errors and their handling:
261

262
```javascript
263
// Port listing errors
264
"Error listing serial ports"
265
"Access denied to serial port"
266

267
// Connection errors
268
"Port not found: /dev/ttyUSB0"
269
"Port already in use"
270
"Permission denied: /dev/ttyACM0"
271

272
// Auto-detection errors
273
"no Arduino 'uno' found."
274
"Multiple Arduino boards detected, please specify port"
275
```
276

277
**Error Handling Example:**
278

279
```javascript
280
const Avrgirl = require('avrgirl-arduino');
281

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

289
    // List available ports for troubleshooting
290
    Avrgirl.listPorts((err, ports) => {
291
      if (!err && ports.length > 0) {
292
        console.log('\nAvailable serial ports:');
293
        ports.forEach(port => {
294
          console.log(`- ${port.path}: ${port.manufacturer || 'Unknown'}`);
295
        });
296
      }
297
    });
298
  } else if (error.message.includes('Permission denied')) {
299
    console.log('Permission error. On Linux, try:');
300
    console.log('sudo usermod -a -G dialout $USER');
301
    console.log('Then log out and log back in.');
302
  }
303
}
304

305
// Usage
306
const avrgirl = new Avrgirl({ board: 'uno' });
307
avrgirl.flash('sketch.hex', (error) => {
308
  if (error) {
309
    handlePortError(error, 'uno');
310
  }
311
});
312
```