avr-multibootloader

Node AVR Multi-Bootloader

Program many devices at once over a multidrop bus, like RS485. This was written with AVR devices in mind, via the AVR Multidrop Bootloader, but it can be usable for other devices that have adapted that bootloader.

• Install
• CLI Interface
  • Examples
• API
  • MultiBootloader(serial, options)
  • readSignalLine()
• Example using the API

Install

sudo npm install avr-multibootloader -g

CLI Interface

  Usage: multibootloader [options] <file ...>

  Send a file to all devices on a serial bus.

  Options:

    -h, --help                    output usage information
    -V, --version                 output the version number
    -l, --list                    List all serial devices
    -b, --baud <number>           Baud rate to the serial device
    -d, --device <name>           The serial device to connect to
    -s, --page-size <number>      The programming page size for your device.
    -c, --command <number>        The Disco Bus message command that puts the devices into the bootloader.
    -p, --prog-version <maj.min>  The major.minor version of your program (for example 1.5)
    <file ...>                    The file to program to your devices

Examples

Basic Programming

multibootloader --baud 115200 --device /dev/cu.usbDevice0 --page-size 128

This is the most basic usage, which passes the device, baud speed and the device page size.

IMPORTANT Page size will be different for all devices. Check your device's datasheet and look for "page size" and enter this value in bytes, not words. In the Atmega328 datasheet it's listed in section 31.5 as 64 words, which would be 128 bytes.

Triggering Program Mode

You can pass a pre-command that will be sent as a disco bus message to trigger the device into programming mode.

multibootloader --baud 115200 --device /dev/cu.usbDevice0 --page-size 128 --command 0xF0

In this example, the programmer will first send the disco bus message 0xF0 to all devices. Then, normal programming will continue after a 1 second delay.

The main program in these devices will need to watch for this message, and then swtich to the bootloader programming mode. You can see an example of a program that does this here.

API

MultiBootloader(serial, options)

The main constructor that creates a programmer instance.

Parameters

• serial: An open SerialPort
• options: Programmer options
  • pageSize: (required) The number of BYTES per page (not words)
  • maxTries: The maximum number of programming retries to make when there are errors.
  • timeBetweenPages: The number of milliseconds to pause between sending each page.
  • signalTimeout: Maximum time to wait for signal line to change to acknoledge nodes are ready.
  • version.major: The new program's version major number
  • version.minor: The new program's version minor number

readSignalLine()

Detects the signal line, which is used to detect if there are errors in programming. By defualt this looks at the DSR line on the serial connection, but this method can be overriden to detect the state another way.

Currently the SerialPort library does not support reading the DSR value. Until that support is added, you can use my fork of their library.

program(filepath)

Program all devices with this HEX program file. NOTE: This must be in Intel Hex format (generally the default hex format).

Parameters:

• filepath: The path to the hex file to progrm the devices with.

Example using the API

const Multibootloader = require('avr-multibootloader');
 
// NOTE: this needs to use, my fork of the library to support the signal line reading (until v5.0.0 is stable):
// npm install https://github.com/jgillick/node-serialport/
const Serialport = require('serialport');
 
const PORT_NAME = '/dev/cu.usbDevice0'
const PORT_BAUD = 115200
const PAGE_SIZE = 128; // 64 words - atmega328
 
const programFile = './test_program.hex';
 
// Open serial port
const port = new SerialPort(PORT_NAME, { baudRate: PORT_BAUD },
  (portErr) => {
    if (portErr) {
      console.error('Error:', portErr);
      return;
    }
 
    // Create programmer
    const bootloader = new MultiBootloader(port, {
      pageSize: PAGE_SIZE
    });
 
    // Listen to programming events
    bootloader.on('status', (status) => {
      console.log(status.message);
    });
    bootloader.on('error', (err) => {
      console.log(err.message);
    });
 
    // Program
    bootloader.program(config.args[0])
    .then(() => {
      console.log('Programming complete!');
    })
    .catch((err) => {
      console.error(`FATAL ERROR: ${err}`);
    });
});