LocoNet IPL Bootloader

About

This piece of software supports a software update of an Atmel AVR processor over LocoNet. The protocol itself is not part of the public LocoNet "personal use" specification (yet?). But the PC side is already implemented in the JMRI LocoNet Tools. Note that the described bootloader is free software, but if you are going to sell a device that includes LocoNet functionality, you have to contact Digitrax for a license agreement.

Memory organization

The bootloader has a size of 512 bytes (256 words) and has to be located at the end of the address space.

0x1FFF = address of bootloader version (end of memory) 0x1FFE = address of hardware version IPL Bootloader 0x1E00 = reset vector configured by fuses 0x1DFF = end of unused space unused, filled with zeros X = begin of unused space X-1 = address of checksum high byte X-2 = address of checksum low byte X-3 = end of application Application 0x0000 entry point of application

The table shows the memory layout of an ATMega8 as an example. All addresses are byte addresses! The application is built as a normal application that starts at the default reset vector 0. The start address of the bootloader (equal to the reset vector) is 512 Bytes before the end of flash memory. The unused space between checksum and bootloader is zero filled. At the very last word of the flash memory, the bootloader incorporates version information of the bootloader and the underlaying hardware. When installing the bootloader, it has to be ensured that this hardware version matches the actual hardware.

The minimum bootloader size in some of the larger AVR's is larger than 512 bytes, so the smallest possible bootloader size will have to be selected by the available fuse settings. This bootloader start address has to be known for different purposes:

The fuses of the AVR processors have to be adjusted to move the reset vector.

The bootloader code begins at that address and has its entry point at this address

The bootloader verifies the checksum over the space that is available for the application (in the example 0x0000 through 0x1DFF) to decide if a healthy application is present. This is a 16 bit negative sum - the location of the checksum is not important for the verification.

The application can detect the start of a software download and jumps directly to the start of the bootloader.

How does it work?

There is a UML activity diagram to illustrate the internal working of the bootloader. The nominal sequence of operation is:

1. The old application is running
2. A user initiates a software update, possibly using JMRI
3. The old application receives the setup packet and checks if the incoming software update matches the manufacturer, developer and device IDs of the running software and optionally checks if the transmitted software version number is higher than the currently running application anch optionally checks for a matching hardware version.
4. The application performs a jump instruction to the start address of the bootloader
5. The bootloader start-up code determines that it was not entered by a reset and therefore assumes that a setup packet was accepted by the application
6. Several data packets are received and transferred to the application space of the flash memory. The flash is erased and burned whenever a complete page has been transferred.
7. Finally an end packet gets received. The bootloader fills the remaining flash space that is available for application with zeros and resets the chip.
8. The starting bootloader recognizes the reset and checks the checksum. If it is correct, it jumps to the absolute address zero, which is the start of the application.

Application checksum

Behind the end of the application space a 16 bit check sum is located. The sum of the application plus check sum must be zero. As the unused space between application and bootloader is filled with zeros, it does not interfere with the checksum. The checksum is used by the bootloader to determine if a complete application exists. If it exists, it is started. If it does not exist, the bootloader reverts to an update only mode and waits for the start packet of the software update. In this mode the software version number of the downloaded software is not checked - there is nothing to check it against.

Use the bootloader in your project

For a device to be updateable via IPL by this bootloader, it has to be identifiable. Many different devices can be connected to the same LocoNet, you only want to update one device type at a time! A device is identified by:

• manufacturer ID, developer ID, product ID: identifies the type of device that this software may be loaded into.
• software version, hardware version: identifies the software and on what hardware version it wants to run.

To clone the bootloader for your project, read the manual for bootloader creation
To make your application ready for a software update, read the manual for updateable application

Author of this website: Stefan Bormann.