Athena is an Ethernet- and Serial-capable bootloader for Arduino. Using an Arduino Ethernet board or Wiznet W5x00 shield, you can upload programs to your Arduino over Ethernet. Athena starts a TFTP server on the Arduino board, and files can be transferred using any TFTP client.
Embedded Artistry has forked this bootloader version from the original project, which seems to be no longer actively maintained. We are making many improvements and enhancements to the previous implementation.
Athena is implemented for AVR chips. ARM chips cannot use this bootloader.
Bootloader binary files for different versions can be found on the Releases page.
Table of Contents:
- Getting the Bootloader
- Dependencies
- Supported Boards
- Repository Structure
- Quickstart Checklist
- Related Documents
- Downloading and Building the Bootloader
- Installing the Bootloader Project
- Flashing the Bootloader
- Flashing Applications via Serial
- Flashing Applications via TFTP
- Enabling Remote Reset and Reprogram Capabilities
- Changing the Ethernet CS Pin
- Enabling Ethernet Reset Behavior
- Troubleshooting
- EEPROM Requirements
- Test Binaries
- Supporting Libraries
- Useful References
- Acknowledgments
- License
To download this repository for local development, we recommend cloning with the --recursive flag to ensure submodules (e.g., supporting libraries) are automatically downloaded.
$ git clone https://github.com/embeddedartistry/athena-bootloader.git --recursive
You can also download submodules after cloning with:
$ git submodule update --init --recursive
You can also access .zip archives from latest release page. Download the latest ProjectFile .zip archive for the latest release, which contains the full source tree (including submodules) and populated binary files. This is what you should use for populating the Arduino hardware folder.
This project requires you to use git-lfs. Images and documentation are stored within git-lfs. If you have git-lfs installed, these files will downloaded correctly when cloning the repository.
If you do not have this installed, please visit the git-lfs web page for installation instructions.
If you cloned this repository before installing git-lfs, please run git lfs pull. If you have git-lfs installed before cloning the repository, git will automatically perform a git lfs pull for you.
When you don't have git-lfs installed, you will see all of the files in the repository. However, files stored with git-lfs will show up as small placeholders. Trying to use these files will result in errors.
This project requires Arduino SDK 1.15 or later due to the project's source layout.
The following dependencies are required to compile and use this bootloader:
If you have the Arduino IDE or Atmel Studio installed on your system, you already have avr-gcc.
For manual installation on Linux/WSL:
$ sudo apt-get install gcc-avr binutils-avr avr-libc gdb-avr
For manual installation on OS X using Homebrew:
brew tap osx-cross/avr
brew install avr-libc
brew install avrdude --with-usb
For manual download of the command line tools, see the compiler page.
If you have the Arduino IDE installed on your system, you already have avr-gcc.
For manual installation on Linux/WSL:
sudo apt-get install avrdude
For manual installation on OS X using Homebrew:
brew install avrdude --with-usb
Files can be manually downloaded from the AVRDUDE project here.
For information on integrating avrdude with Atmel Studio, see these links:
- Integrate avrdude with Atmel Studio
- Arduino to Atmel Studio 7 external programmers, ISP and serial programming
- How to Load Programs to an Arduino UNO from Atmel Studio 7
Officially supported MCUs:
- ATmega328
- ATmega2560
- ATmega1284
- ATmega32U4 (see notes)
Officially supported Ethernet controllers (see notes):
- WizNet W5100
- WizNet W5200
- WizNet W5500
Officially supported Arduino Boards:
The ATmega32U4 is supported, but the chip cannot support uploads over USB serial. It should be possible to upload sketches over the serial port (non-USB), but this has not been tested. The Caterina bootloader requires the majority of bootloader space to implement USB support. It is unclear whether both USB and Ethernet support can be implemented for this chip.
On WIZnet shields pins 11,12, and 13 are tied up (by default) with the corresponding pins on the ICSP header. For more information on handling these pins, see this document.
These boards have been reported to work with the Athena bootloader:
If you think another board can be added to this list, please contact us.
This repository is structured to follow the latest Arduino IDE standard for 3rd-party hardware. Here is an overview of the structure:
avr/: This is where the bootloader code, pre-built binaries, and helper libraries livebootloaders/athena/contains the pre-built bootloader.hexfiles, as well as source code for the bootloaderlibraries/contains helper libraries that are used to interact with the bootloader from an Arduino applicationvariants/contains additional board definitions
docs/contains additional reference documentation, images, and GitHub templatesextras/contains miscellaneous useful utilities
This is the abbreviated checklist for installing and using the bootloader:
- Download the bootloader and install it to the proper location
- Just need the bootloader binaries? Check the releases page.
- Flash the bootloader to the device
- DO NOT SKIP: Program network settings for the device using the
AthenaEEPROMlibrary or example sketches- More information available in docs/network_configuration.md
- Include the
AthenaEthernetResetlibrary in your application (or use theResetServerexample sketch- Create a reset server and specify a port
- Call
.begin()on the server object insetup() - Call
.check()on the server object inloop()
- When your application is running, trigger a reprogramming mode using curl or a web browser
- URL Format:
http://{ip}:{port}/{reset_path}/reprogram- Example using default settings:
curl 192.168.1.128:8080/athena/reprogram
- Example using default settings:
- The device will respond with:
- "Arduino will reset for reprogramming in 2 seconds"
- You must use the "password" programmed via the AthenaEEPROM library to successfully enter the programming mode. The default password is
athena
- URL Format:
- Follow the TFTP Upload instructions to send a new binary to the device
Not able to connect to the device? Check out the debugging guide.
Need to use a custom board file for compiling and uploading sketches? Once you've flashed the bootloader, you can do that safely. You will need to install the AthenaEthernetReset and AthenaEEPROM libraries separately, however, because the IDE only picks them up in the bootloader folder if you've selected an Ariadne configuration.
- Compiling Instructions for anyone looking to modify the bootloader
- AVRDUDE Instructions for manually flashing outside of the Arduino IDE or Atmel Studio using AVRDUDE
- Debugging Guide provides pointers for debugging failures to connect to the device
- Network Configuration provides pointers on configuring the network settings for your device
- Converting Binaries for TFTP Upload provides more detailed instructions on the conversion process, with example locations for each OS when using the Arduino IDE
You can clone the repository from GitHub:
$ git clone https://github.com/embeddedartistry/athena-bootloader --recursive
If you have configured your GitHub account with SSH keys, you can also use the SSH checkout:
$ git clone git@github.com:embeddedartistry/athena-bootloader.git --recursive
Note that you must use the --recursive flag because the project contains submodules. If you cloned without the --recursive flag, perform:
$ git submodule update --init
To build binaries within the repository, run make.
You can also download a zip archive of the repository from the GitHub repository page.
You have two options for installing the bootloader:
- Use the board manager
- Manual installation
Follow these Arduino IDE instructions for Third Party Boards, and add this custom URL: https://raw.githubusercontent.com/embeddedartistry/athena-bootloader/master/package_athena-bootloader_index.json .
Once that URL is added, navigate to Tools -> Boards submenu -> Board manager. You will be able to search for "Athena" and then install the board package.
In order for the Arduino IDE to access the information, you need to place the athena-bootloader repository within the hardware/ folder of your "Sketchbook Location". You can find this location by viewing the Arduino IDE settings. The default location is often the Arduino/ folder in your home directory or in Documents/.
For our system, which is OS X, the Sketchbook location is:
/Users/embeddedartistry/Documents/Arduino
On Windows, it should be in My Documents\Arduino\.
Our Sketchbook folder does not have a hardware directory by default. We created the folder ourselves:
$ mkdir -p /Users/embeddedartistry/Documents/Arduino/hardware
You can go to the releases page and download the athena_bootloaders-VERSION.zip file for a given release, unzipping that in the target directory.
You can also clone the repository within that directory, or you can use a symbolic link within the hardware/ folder:
$ cd /Users/embeddedartistry/Documents/Arduino/hardware
$ ln -s ~/src/athena-bootloader/ ./athena
If you cloned the repository, you will need to build the bootloader files.
$ make
In either case, once the athena-bootloader folder is placed in the hardware/ folder, Arduino will detect it. Restart the IDE if it is already open. You should now see the Athena bootloader show up in the board list.
If you are using Atmel Studio, our recommendation is to use the Visual Micro extension. When you are using the Visual Micro add-on, the standard installation instructions will apply. Then, use the Visual Micro board manager to select the proper Athena board definition for your target.
For more information, see this link:
- Programming Hardware Requirements
- Connecting Pins
- Programming with Arduino IDE
- Programming with AVRDUDE
To flash the bootloader to a device, you will need an in-system programmer (ISP). You can purchase an AVR-ISP or USBtinyISP, which work for most Arduino devices.
Some devices do not work reliably with the ATMega2560 due to page size requirements. For the ATMega2560, you will need a ISP such as Atmel's AVRISP mkII, Atmel's AVRISP STK500 USB ISP Programmer, Olimex's AVR-ISP-MK2, or any similarly-capable programmer.
If you have a spare Arduino, you can build a ParallelProgrammer or an ArduinoISP. Nick Gammon has published a guide for using one Arduino to program another, and his method is reported to work with the ATMega2560.
The programmers should be connected to the ICSP pins. On Arduino boards, the ISCP pins are a 2x3 header located near the processor. The board must be powered by an external power supply, by the programmer, or by the USB port. If you are using an ArduinoISP, consult this link for additional instructions.
After you have connected the Arduino board and the programmer to your computer launch the Arduino IDE.
First, navigate to the Tools > Board menu and select your target board from the Athena Bootloader list (at the bottom in our view).
Next, navigate to the Tools > Version menu and select Wiznet chip from the list, as well as "Standard" or "Debug" mode. Debug binaries are larger, but contain helpful Serial output for seeing what the bootloader is doing. The only difference between Standard and Debug mode is the serial output.
By default, bootloader updates will erase the contents of the EEPROM. Because the Athena EEPROM layout is different from the default layout, this approach is advisable. If you're simply upgrading Athena bootloader versions, you probably want to keep your previously configured device to a new version.
Navigate to the Tools > Erase EEPROM? menu and select Save to prevent the EEPROM from being erased.
Note: If you are manually flashing the application or need to specify fuse settings, use a high_fuse setting of
0xD8to erase, and0xD0to preserve.
Next, go to the Tools > Programmer menu and select the programmer you are using.
In case you are using ArduinoISP, make sure that the selected port in the Tools > Serial Port menu refers to the ArduinoISP. You should not select the board that you want to burn the bootloader on. This requirement applies to other serial-based programmers, such as the AVR-ISP 2.0 ("Atmel STK500 Development Board").
To flash the bootloader, select the Tools > Burn Bootloader menu option.
Check the Arduino console output to confirm that the bootloader was flashed successfully.
If you have configured the Visual Micro board manager, you can configure your programmer and burn in the bootloader in the visual micro menu similarly to the Arduino IDE.
You can also manually flash the bootloader in Atmel Studio. For this, you will need to manually supply fuse settings for your configuration. These settings can be found in boards.txt.
Instructions on manually programming the bootloader with AVRDUDE are described in docs/avrdude.md
Athena is built off of the standard Arduino AVR bootloaders. Serial upload capabilities are preserved. Serial uploads work even when an Ethernet shield is not installed.
To flash an application over USB/Serial:
- Plug in the USB cable
- Select the serial port for the device and the appropriate board from the Tools > Board menu.
- Program the device
If your device has auto-reset capabilities, such that a Serial connection resets the device, programming will work with a sketch is running.
If your device does not have auto-reset capabilities, then you will need to press the reset button on the device to enter the bootloader mode. In this case, if there is a valid program already flashed on the Arduino, you have to reprogram the device in the next 5 seconds. If you don't, the bootloader will initiate the program that is already flashed onto the Arduino. In case there is no program flashed or the program has been marked as invalid, the bootloader will never time out and you can reprogram it at any time.
Note: For boards other than the Arduino Mega, the primary LED will start blinking rapidly when the bootloader is running.
After a successful flashing in either case, the bootloader will automatically start the application.
Flashing applications via TFTP requires multiple moving parts. This README references the default network settings and assumes that your network is configured so these settings will work.
* IP Address: 192.168.1.128
* Subnet Mask: 255.255.255.0
* Gateway: 192.168.1.1
* MAC Address: 0xDE.0xAD.0xBE.0xEF.0xFE.0xED
* TFTP Negotiation Port: 69
* TFTP Data Port: 46969
For more information on network configuration, see docs/network_configuration.md
If the default values will not work, you MUST configure the network settings for the TFTP server in the bootloader and the AthenaEthernetReset server to work correctly with your network configuration.
The process flow is:
- Reset into TFTP mode in the bootloader
- Connect to the device
- Upload a binary image
- After upload completes, the new application auto-boots
While Arduino serial flashing uses HEX files, the bootloader TFTP server only works with binary files. You must manually convert your programs the .bin file format using avr-objcopy.
For detailed instructions, see docs/converting_binaries.md. Only brief notes are shown here.
The first step is to find the .hex file you want to flash to your device. If you're using the Arduino IDE, look for a line in the build output referencing a .hex file. It is placed in a temporary folder, such as this:
/var/folders/0h/_66m4dqj3p1b3j1xqg10r08w0000gn/T/arduino_build_678002/WebServer.ino.hex
Copy that path and use it in with the following command structure:
Windows:
"C:\Program Files\Arduino\hardware\tools\avr\bin\avr-objcopy.exe" -I ihex "C:\path\to\your\program.hex" -O binary program.bin
Linux, WSL, and OS X:
avr-objcopy -I ihex /path/to/sketch.hex -O binary sketch.bin
To upload the binary over Ethernet, you will need a TFTP client. All three major OSes have tools that you can use through the command line.
No matter the OS, the following flow must be used:
- Put the device into bootloader mode, either via the reset button or the Ethernet Reset Server library.
- Connect to the device using TFTP and the configured port (69 by default)
- Enable "octet mode" or "binary mode"
- Send the binary file to the device using the
PUTcommand
After the binary is uploaded, the bootloader will automatically run the application.
If the upload fails, wait for the upload process on the bootloader to timeout. That takes about 10 seconds. For this period you should witness the indication led doing some random blinking. Note that the LED on an Arduino Mega will not blink due to contention with the SCK pin.
After the timeout the TFTP server should restart itself and wait for a new upload.
Windows provides a tftp command that can be used:
Microsoft Windows XP [Version 5.1.2600]
(C) Copyright 1985-2001 Microsoft Corp.
C:\Documents and Settings\Administrator>tftp
Transfers files to and from a remote computer running the TFTP service.
TFTP [-i] host [GET | PUT] source [destination]
-i Specifies binary image transfer mode (also called
octet). In binary image mode the file is moved literally, byte by byte. Use this mode when transferring binary files.
host Specifies the local or remote host.
GET Transfers the file destination on the remote host to
the file source on the local host.
PUT Transfers the file source on the local host to
the file destination on the remote host.
source Specifies the file to transfer.
destination Specifies where to transfer the file.
Here is an example upload command:
C:\Documents and Settings\Administrator>tftp -i 192.168.1.128 PUT sketch.bin
Linux and OS X both have a tftp command:
$ tftp [ip] [port]
For the default bootloader, the command would be:
$ tftp 192.168.1.128 69
Or, because 69 is the default TFTP port, you could simply say:
$ tftp 192.168.1.128
You should be greeted by the TFTP prompt:
tftp>
Enable binary/octet mode to tell TFTP to send binary data:
tftp> mode octet
You can optionally enable verbose output settings:
tftp> trace
tftp> verbose
To send the sketch to the board, issue a PUT command:
tftp> put [sketch].bin
You should see your TFTP client sending packets. A correct output sample of the TFTP client uploading the blink sketch is below:
tftp> mode octet
tftp> trace
Trace mode on.
tftp> verbose
Verbose mode on.
tftp> put blink.bin
sent WRQ <file: blink.bin, mode: octet <>>
received ACK <block: 0>
sent DATA <block: 1, size: 512>
received ACK <block: 1>
sent DATA <block: 2, size: 512>
received ACK <block: 2>
sent DATA <block: 3, size: 512>
received ACK <block: 3>
sent DATA <block: 4, size: 512>
received ACK <block: 4>
sent DATA <block: 5, size: 42>
received ACK <block: 5>
tftp>
Some Linux distributions, like Fedora/RedHat, require you to load the ip_conntrack_tftp module. If you don't, the TFTP client won't be able to acknowledge (ACK) the incoming packets. Other distributions, such as Arch, don't require this step.
To load ip_conntrack_tftp, run the following:
$ sudo modprobe ip_conntrack_tftp
The AthenaEthernetReset library is a requirement for your program if you want to support remotely enabling binary uploads. A README is provided and there is an example sketch showing the usage of the library.
The following steps must be used to implement a remote upload capability for your device:
- Flash the bootloader to the device
- Program network settings for the device using the AthenaEEPROM library or examples
- Include the AthenaEthernetReset library in your application
- Create a reset server and specify a port
- Call
.begin()on the server object insetup() - Call
.check()on the server object inloop()
- Trigger a reset using curl or a web browser
- URL Format:
http://{ip}:{port}/{password}/reprogram- Example:
curl 192.168.1.128:8080/athena/reprogram - Note that the
resetendpoint does not provide a reprogramming opportunity.
- Example:
- The device will respond with:
- "Arduino will reset for reprogramming in 2 seconds"
- You must use the "password" programmed via the AthenaEEPROM library to successfully enter the programming mode. The default value is
athena.
- URL Format:
- Follow the TFTP Upload instructions to send a new binary to the device
If you don't want to use the EthernetReset server (because you have your own web server), you can trigger update mode manually with the following function calls:
EEPROM.enableUpdateMode(); // in AthenaEEPROM library
watchdogReset(); // from avr/wdt.h
After the device resets, it will wait for a firmware update over TFTP or Serial. This mode will not time out. If the device is manually reset, it will boot once more into the image currently installed on the board.
The bootloader is programmed to use the default CS pin to talk to the Ethernet controller. If your board is using a custom pin, you can change the pin that the bootloader will use by programming the EEPROM:
EEPROM.setEthernetCSPin(53); // Uses Arduino pin number
By default, the bootloader does not know about a reset pin. If your hardware requires the bootloader to perform a reset during system boot, you can specify a reset pin using the EEPROM:
EEPROM.setEthernetResetPin(53); // Uses Arduino pin number
If you're having problems connecting to the device, check out docs/Debugging.md for troubleshooting tips.
If you see an error like the one below, you only have placeholder git-lfs files. Please see the git-lfs section above for instructions.
avrdude: ERROR: No valid record found in Intel Hex file "C:\Users\XXX\Documents\Arduino\hardware\athena-bootloader-11.1.8\avr/bootloaders/athena/athena_debug2560_w5500.hex"
avrdude: read from file 'C:\Users\XXX\Documents\Arduino\hardware\athena-bootloader-11.1.8\avr/bootloaders/athena/athena_debug2560_w5500.hex' failed
Error while burning bootloader.
If you see an error like the one below, your submodules are not populated. Please see the instructions on Getting the Bootloader.
Invalid library found in C:\Users\XXX\Documents\Arduino\hardware\athena-bootloader-11.1.8\avr\libraries\AthenaEEPROM: no headers files (.h) found in C:\Users\XXX\Documents\Arduino\hardware\athena-bootloader-11.1.8\avr\libraries\AthenaEEPROM
Invalid library found in C:\Users\XXX\Documents\Arduino\hardware\athena-bootloader-11.1.8\avr\libraries\AthenaEthernetReset: no headers files (.h) found in C:\Users\XXX\Documents\Arduino\hardware\athena-bootloader-11.1.8\avr\libraries\AthenaEthernetReset
Invalid library found in C:\Users\XXX\Documents\Arduino\libraries\Archive: no headers files (.h) found in C:\Users\XXX\Documents\Arduino\libraries\Archive
Athena uses the Arduino EEPROM to store values needed by the bootloader and AthenaEthernetReset server. If you are using the default EEPROM library for our own purposes, please make sure to start writing after NETEEPROM_END, available in AthenaEEPROM_defs.h:
#define NETEEPROM_START 0
#define NETEEPROM_END (NETEEPROM_START + 70)
For more information, see the AthenaEEPROM library.
If you use the AthenaEEPROM library included with the Athena bootloader, then offsets will be handled for you automatically and you will not need to adjust your code. Note, however, that the full EEPROM space is not available.
For testing purposes, you can find a blink sketch in binary form inside the extras/tests/blink folder.
The fade sketch in the extras/tests/fade folder will also give you a view of what a failed upload looks like. This sketch fails because it is written in plain C and not in Arduino. That way it lacks some "signatures" the bootloader uses to validate Arduino sketches.
Supporting libraries are included with the bootloader. These libraries are meant to facilitate interacting with the Athena bootloader from Arduino applications.
These libraries are packaged with the bootloader and will automatically detected by the Arduino IDE when an Athena board configuration is used. If you are using a custom board configuration, you may also want to install these libraries separately so that they are available even when an Athena board configuration is not selected.
- AthenaEEPROM (found at
avr/libraries/AthenaEEPROM) is a patched EEPROM library that protect the memory space used by the Athena bootloader. This library also enables you to read/write the bootloader network settings.- Use this library in place of the default EEPROM library to prevent settings from being overwritten
- AthenaEthernetReset (found at
avr/libraries/AthenaEthernetReset) is a library that can be used to create an HTTP server in an application that enables you to:- Remotely restart the Arduino application
- Restart into the bootloader in programming mode, which waits for the a binary over TFTP
The AthenaEthernetReset library is a requirement for your program if you want to support remotely enabling binary uploads. A README is provided and there is an example sketch showing the usage of the library.
- AVR Beginners is an excellent resource for anyone working on this bootloader who is new to the AVR architecture
The Embedded Artistry version of the Athena bootloader is derived from loathingkernel/ariadne-bootloader. Credit goes to its maintainer, Stelios Tsampas.
The Ariadne bootloader was built upon these open source projects:
- TFTP-Bootloader (The original base for this project)
- Optiboot (Bootloader for the ATmega328)
- Arduino-stk500v2-bootloader (Bootloader for the ATmega2560)
The following contributors were listed in the original project README:
- mharizanov (Commenting some of the initial Arduino code, enabling Stelios to take on the project)
- follower (Sketches served as a starting point for the included AthenaEEPROM and AthenaEthernetReset libraries)
- Arjen Hiemstra (Provided support for W5200 and W5500)
- per1234 (Testing and tech support in Arduino Forums)
The following donors were listed in the original project README:
- Hachi Manzur (AVRISP mkII programmer, testing)
Athena is released under the GPLv2, GNU General Public License.