0
# Avrgirl Arduino
1

2
Avrgirl Arduino is a NodeJS library for flashing compiled sketch files (.hex files) to Arduino microcontroller boards. It provides automatic board detection, supports multiple communication protocols, and works across Node.js and browser environments. The library supports 28 different Arduino board types and handles the complete firmware upload process automatically.
3

4
## Package Information
5

6
- **Package Name**: avrgirl-arduino
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install avrgirl-arduino`
10

11
## Core Imports
12

13
```javascript
14
const Avrgirl = require('avrgirl-arduino');
15
```
16

17
For browser environments:
18
```html
19
<script src="node_modules/avrgirl-arduino/dist/avrgirl-arduino.min.js"></script>
20
```
21

22
## Basic Usage
23

24
```javascript
25
const Avrgirl = require('avrgirl-arduino');
26

27
// Create instance for Arduino Uno
28
const avrgirl = new Avrgirl({
29
  board: 'uno'
30
});
31

32
// Flash a hex file to the Arduino
33
avrgirl.flash('path/to/sketch.hex', function(error) {
34
  if (error) {
35
    console.error('Flash failed:', error);
36
  } else {
37
    console.log('Flash completed successfully!');
38
  }
39
});
40
```
41

42
## Architecture
43

44
Avrgirl Arduino uses a modular architecture with the following key components:
45

46
- **Main Class**: `AvrgirlArduino` provides the primary flashing API and configuration management
47
- **Connection Management**: Handles serial port communication, auto-detection, and port management
48
- **Protocol Handlers**: Implements STK500v1, STK500v2, and AVR109 protocols for different board types
49
- **Board Configuration**: Comprehensive database of Arduino board specifications and communication parameters
50
- **Hex File Processing**: Tools for parsing and processing Intel HEX format firmware files
51

52
## Capabilities
53

54
### Arduino Flashing
55

56
Core functionality for uploading compiled sketch files to Arduino boards with automatic board detection and protocol selection.
57

58
```javascript { .api }
59
/**
60
 * Main Arduino flashing class
61
 * @param {object} options - Configuration options
62
 */
63
function AvrgirlArduino(options);
64

65
interface AvrgirlArduinoOptions {
66
  board: string | BoardConfig;      // Board type name or custom config
67
  port?: string;                    // Serial port (auto-detected if omitted)
68
  debug?: boolean | function;       // Debug logging: true/false or custom function
69
  megaDebug?: boolean;             // Enhanced protocol-level debugging
70
  manualReset?: boolean;           // Manual reset configuration for AVR109 boards
71
  disableVerify?: boolean;         // Skip verification after flash for AVR109 boards
72
}
73

74
/**
75
 * Flash a hex file to the Arduino board
76
 * @param {string|Buffer} file - Path to hex file or Buffer containing hex data
77
 * @param {function} callback - Completion callback
78
 */
79
flash(file: string | Buffer, callback: (error?: Error) => void): void;
80
```
81

82
[Arduino Flashing](./flashing.md)
83

84
### Port Management
85

86
Serial port detection and management functionality for finding and connecting to Arduino boards.
87

88
```javascript { .api }
89
/**
90
 * List available serial ports with Arduino detection
91
 * @param {function} callback - Callback with ports list
92
 */
93
listPorts(callback: (error?: Error, ports?: SerialPort[]) => void): void;
94

95
/**
96
 * Static method to list serial ports
97
 * @param {function} callback - Callback with ports list
98
 */
99
AvrgirlArduino.listPorts(callback: (error?: Error, ports?: SerialPort[]) => void): void;
100

101
/**
102
 * Get list of all supported Arduino board names
103
 * @returns {string[]} Array of board name strings (28 boards total)
104
 */
105
AvrgirlArduino.listKnownBoards(): string[];
106

107
interface SerialPort {
108
  path: string;
109
  manufacturer?: string;
110
  serialNumber?: string;
111
  pnpId?: string;
112
  locationId?: string;
113
  vendorId?: string;
114
  productId?: string;
115
  _pid?: string;  // Platform independent product ID
116
}
117
```
118

119
[Port Management](./port-management.md)
120

121
### Command Line Interface
122

123
CLI tool for flashing Arduino boards directly from the command line with support for custom board configurations.
124

125
```bash { .api }
126
# Flash a hex file to Arduino board
127
avrgirl-arduino flash -f <file> -a <arduino_type> [-p <port>] [-v]
128

129
# List all supported board types
130
avrgirl-arduino boards
131

132
# List available serial ports
133
avrgirl-arduino list
134

135
# Run hardware test pilot
136
avrgirl-arduino test-pilot
137

138
# Show help information
139
avrgirl-arduino help
140
```
141

142
[Command Line Interface](./cli.md)
143

144
## Board Support
145

146
The library supports 28 Arduino board types including:
147

148
**Popular Boards**: uno, mega, leonardo, micro, nano, nano (new bootloader), duemilanove168, duemilanove328, pro-mini, adk, lilypad-usb, yun, esplora
149

150
**Specialty Boards**: imuduino, blend-micro, tinyduino, sf-pro-micro, qduino, pinoccio, feather, arduboy, circuit-playground-classic, little-bits
151

152
**BQ Boards**: zumjunior, zumcore2, bqZum
153

154
**Other Boards**: xprov4 (Spark Concepts xPro V4)
155

156
Each board configuration includes communication parameters, USB product IDs, protocol specifications, and timing requirements.
157

158
**Browser Support Limitation**: AVR109 protocol boards (Leonardo, Micro, etc.) are not supported in browser environments due to WebSerial API limitations.
159

160
## Types
161

162
```javascript { .api }
163
interface BoardConfig {
164
  name: string;                    // Board identifier
165
  baud: number;                   // Serial communication baud rate
166
  signature: Buffer;              // Board signature for identification
167
  pageSize?: number;              // Memory page size (STK500 boards)
168
  numPages?: number;              // Number of memory pages (STK500 boards)
169
  timeout?: number;               // Communication timeout in ms
170
  productId: string[];            // USB product ID values
171
  productPage: string;            // URL to product information
172
  protocol: 'stk500v1' | 'stk500v2' | 'avr109';  // Communication protocol
173
  aliases?: string[];             // Alternative board names
174
  manualReset?: boolean;          // Manual reset configuration
175
  disableVerify?: boolean;        // Verification settings
176
}
177

178
interface AvrgirlArduinoInstance extends EventEmitter {
179
  options: AvrgirlArduinoOptions;
180
  debug: function;
181
  connection: Connection;
182
  protocol: Protocol;
183
  tools: Tools;
184

185
  flash(file: string | Buffer, callback: (error?: Error) => void): void;
186
  listPorts(callback: (error?: Error, ports?: SerialPort[]) => void): void;
187
  list(callback: (error?: Error, ports?: SerialPort[]) => void): void;
188

189
  // EventEmitter methods
190
  on(event: string, listener: Function): this;
191
  emit(event: string, ...args: any[]): boolean;
192
  removeListener(event: string, listener: Function): this;
193
  removeAllListeners(event?: string): this;
194
}
195

196
interface Tools {
197
  _parseHex(file: string | Buffer): Buffer | Error;  // Parse Intel HEX format
198
  _hexStringToByte(str: string): Buffer;             // Convert hex string to Buffer
199
}
200
```