A NodeJS library for flashing compiled sketch files to Arduino microcontroller boards.
🆕Alpha release of web serial support for some Arduino boards 🆕
Want to contribute?
Own a supported Arduino and want to be a test pilot for this project with two minutes of your time?
- Run
npm install -g avrgirl-arduino@latestin your terminal. - Type
avrgirl-arduino test-pilot, hit enter / return key and follow the prompts. - Thank you, friend ❤️
avrgirl-arduino is a NodeJS library written to present a convenient way to upload precompiled sketches to an Arduino. avrgirl-arduino supports a selection of Arduino boards.
The current supported list:
- Arduino Uno
- Arduino Mega
- Arduino ADK
- Arduino Leonardo
- Arduino Micro
- Arduino Nano
- Arduino Duemilanove (168)
- Arduino Pro Mini
- Arduino Lilypad USB
- Arduino Yun
- Arduino Esplora
- Femtoduino IMUduino
- RedBearLab Blend Micro
- Tinyduino
- Sparkfun Pro Micro
- Qtechknow Qduino
- Pinoccio Scout
- Adafruit Feather 32u4 Basic Proto
- Arduboy
- Adafruit Circuit Playground
- BQ Zum
- BQ ZUM Core 2
- BQ ZUM Core 2
This library is designed to ultimately be rolled into the avrgirl project (in development), however it still works perfectly well as a stand-alone package to be used outside of avrgirl if you wish.
- Install NodeJS from nodejs.org
- Run
npm install avrgirl-arduinoin your shell of choice
Before using your Arduino with avrgirl-arduino on Windows XP, 7, and 8, you may need to install the Arduino drivers included with the Arduino IDE. You can follow steps 1-4 on this guide to install the Arduino IDE and activate the relevant drivers. After step 4 of the guide (drivers) you will be ready to use your Arduino with avrgirl!
Your first task is to source a pre-compiled .hex file of the sketch you're interested in uploading to your Arduino. It needs to be compiled for your specific Arduino. You'll find some example hex files for each board within the junk/hex folder of this repo, however if you'd like to use your own, see this guide if you're unsure of how to go about this.
Already have a .hex file in a Buffer object ready to go? No problem! Pass this Buffer object in instead of the file path string, and avrgirl-arduino will take care of the rest. Hooray!
Don't forget to plug your supported Arduino of choice into an available USB port on your computer!
Wanna use this in the CLI? See this section.
The following example code should get you up and running with an Arduino Uno:
var Avrgirl = require('avrgirl-arduino');
var avrgirl = new Avrgirl({
board: 'uno'
});
avrgirl.flash('Blink.cpp.hex', function (error) {
if (error) {
console.error(error);
} else {
console.info('done.');
}
});When creating new Avrgirl(), only the board property is required. The board names to use are detailed in the table below:
| Programmer | Board Option String |
|---|---|
| Arduino Uno | uno |
| Arduino Mega | mega |
| Arduino ADK | adk |
| Arduino Leonardo | leonardo |
| Arduino Micro | micro |
| Arduino Nano | nano |
| Arduino Nano (with new bootloader) | nano (new bootloader) |
| Arduino Lilypad USB | lilypad-usb |
| Arduino Duemilanove | duemilanove168 |
| Arduino Yun | yun |
| Arduino Esplora | esplora |
| RedBearLab Blend Micro | blend-micro |
| Tiny Circuits Tinyduino | tinyduino |
| SparkFun Pro Micro | sf-pro-micro |
| Qtechknow Qduino | qduino |
| Pinoccio Scout | pinoccio |
| Femtoduino IMUduino | imuduino |
| Adafruit Feather 32u4 Basic Proto | feather |
| Arduboy | arduboy |
| Adafruit Circuit Playground | circuit-playground-classic |
| BQ ZUM | bqZum |
| BQ ZUM Core 2 | zumcore2 |
| BQ ZUM Junior | zumjunior |
You can optionally specify a port to connect to the Arduino, but if you omit this property avrgirl-arduino will do a pretty good job of finding it for you. The exception to this is if you're using the Arduino Pro Mini - please specify your port in this case as avrgirl-arduino cannot auto detect it for you.
Specifying the port would look something like this:
var avrgirl = new Avrgirl({
board: 'uno',
port: '/dev/cu.usbmodem1412'
});You can list available USB ports programmatically using the the list method:
Avrgirl.list(function(err, ports) {
console.log(ports);
/*
[ { comName: '/dev/cu.usbmodem1421',
manufacturer: 'Arduino (www.arduino.cc)',
serialNumber: '55432333038351F03170',
pnpId: '',
locationId: '0x14200000',
vendorId: '0x2341',
productId: '0x0043',
_standardPid: '0x0043' } ]
*/
});Alternatively, you can use the CLI to list active ports:
$ avrgirl-arduino list
[ { comName: '/dev/cu.usbmodem1421',
manufacturer: 'Arduino (www.arduino.cc)',
serialNumber: '55432333038351F03170',
pnpId: '',
locationId: '0x14200000',
vendorId: '0x2341',
productId: '0x0043',
_standardPid: '0x0043' } ]
Like logs? Turn on debug mode to see simple flashing progress logs in the console:
var avrgirl = new Avrgirl({
board: 'uno',
// turn on debug mode!
debug: true
});A sample:
found uno on port /dev/cu.usbmodem14141
connected
flashing, please wait...
flash complete.
Prefer your own custom debug behaviour? No Problem!
You can pass in your own debug function instead of a boolean, and avrgirl-arduino will run that instead.
Example:
var myCustomDebug = function(debugLogString) {
// do your own debug stuff in here
}
var avrgirl = new Avrgirl({
board: 'uno',
// turn on debug with your own function
debug: myCustomDebug
});Have a device that requires a manual reset?
You can pass in a manualReset property as a boolean, in either your custom board object or in the general Avrgirl options. This will skip the reset flow when flashing the board. Please note that this is only available for use with boards that speak the AVR109 protocol (most ATMega32U4 powered boards).
Example without custom board:
var avrgirl = new Avrgirl({
board: 'leonardo',
// you can put it here:
manualReset: true
});Example with custom board:
var board = {
name: 'micro',
baud: 57600,
signature: new Buffer([0x43, 0x41, 0x54, 0x45, 0x52, 0x49, 0x4e]),
productId: ['0x0037', '0x8037', '0x0036'],
protocol: 'avr109',
// or you can put it here:
manualReset: true
};
var avrgirl = new Avrgirl({
board: board
});Want to Disable Code Verification?
You can pass in a disableVerify property as a boolean, in either your custom board object or in the general Avrgirl options. This will skip the Verification after flashing the board. Please note that this is only available for use with boards that speak the AVR109 protocol (most ATMega32U4 powered boards).
Example without custom board:
var avrgirl = new Avrgirl({
board: 'leonardo',
// you can put it here:
disableVerify: true
});Example with custom board:
var board = {
name: 'micro',
baud: 57600,
signature: new Buffer([0x43, 0x41, 0x54, 0x45, 0x52, 0x49, 0x4e]),
productId: ['0x0037', '0x8037', '0x0036'],
protocol: 'avr109',
// or you can put it here:
disableVerify: true
};
var avrgirl = new Avrgirl({
board: board
});Run npm install -g avrgirl-arduino in a shell session to install globally for easy CLI use.
The same example above would look like the following as a CLI call in your shell:
avrgirl-arduino flash -f Blink.cpp.hex -a uno
Required flags:
- -f specify the location of the hex file to flash
- -a specify the spcification of the Arduino. It can be:
- the name of the Arduino (
uno,mega,leonardo,micro,nano,"nano (new bootloader)",pro-mini,duemilanove168,yun,esplora,blend-micro,tinyduino,sf-pro-micro,qduino,pinoccio,feather, orimuduino) - a JavaScript file describing a custom board
- the name of the Arduino (
When using a custom board, the JavaScript file must export the board specification:
var board = {
name: 'micro',
baud: 57600,
signature: new Buffer([0x43, 0x41, 0x54, 0x45, 0x52, 0x49, 0x4e]),
productId: ['0x0037', '0x8037', '0x0036'],
protocol: 'avr109',
};
module.exports = board;Optional flags:
- -p will allow you to specify the port where your Arduino is plugged in. Remember to specify your port if using an Arduino Pro Mini.
- -v will turn on debug/verbose mode, which will print a log of things when you run the command.
You can also list the supported boards:
avrgirl-arduino boards
As well as listing all available USB devices on your computer:
avrgirl-arduino list
The output will be presented in JSON format, very similar to the output of the Serialport.list() method (if you've used node-serialport before).
When specifying a custom board object, a number of properties must be provided:
name: the name of the board, used in debug and error messagesbaud: the data rate for data transmissionsignature: aBuffercontaining the device signatureproductId: an array of valid USB product IDs for the boardprotocol: the board communication protocol (avr109,stk500v1andstk500v2are currently supported)
If using the stk500v2 protocol, you also need to specify:
pageSize: the size of the page used to load programs
The other board specification properties are optional. You may look at boards.js for more details.
A .hex file is the compiled end result of an Arduino sketch file. I have provided some example hex files for each board within the junk/hex folder of this repo. Feel free to use these, or if you're after something specific not provided, see the directions below.
The most common way to compile a sketch for your Arduino of choice is to download and install the Arduino IDE. Ensure you install version 1.6.5 or greater for the following steps.
- Open the sketch file you'd like to export, or write a new one if you need to.
- Choose the correct target Arduino board you want to compile the hex file for, from the Tools -> Board menu.
- Export your hex file by navigating to Sketch -> Export compiled binary
- You can find the exported hex file in the same directory your sketch file is located in.
Credit to Jacob Rosenthal, Ryan Day, and Elijah Insua for a lot of the heavy lifting going on underneath in this library.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
![greenkeeper[bot] avatar](https://avatars.githubusercontent.com/in/505?v=4 "greenkeeper[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent