Customizing Brainlink's Firmware

Table of Contents

  1. Why Customize?
  2. What you Need to Know: C for Microcontrollers
  3. Setting up a Development Environment
    1. Windows
    2. Mac
    3. Linux
  4. Writing new Firmware: Where to Begin
  5. Compile and Download new Firmware to Brainlink

Why Customize?

Customizing Brainlink's firmware can be done entirely with free software tools, and does not require any additional hardware. There are a number of reasons why you might want to customize the firmware:  

  • You may need a mode in which the Brainlink is controlled through it's auxiliary serial port instead of over bluetooth, so that another microcontroller can control Brainlink's capabilities.
  • You may wish to create a stand-alone mode where Brainlink controls IR devices without needing to be connected to a Computer/smartphone host.
  • You'd like to change or add to the Brainlink's capabilities - perhaps changing the ADC or DAC resolution, or adding software control of RC servos.
  • You'd like to change the default communications protocol to operate more easily with host software you've created.

What you Need to Know: C for Xmega Microcontrollers

This tutorial assumes you have some familiarity with the process of writing firmware in C for 8-bit microcontrollers. If you do not, there are a number of excellent getting started guides online, herehere, and here.

If you're familiar with 8-bit C programming generally, but not with the Xmega product line, check out Atmel's extensive listing of app notes and software drivers. They have provided example C code for many applications, as well as drivers that make it easy to write code for the various modules of the controller.

Setting up a Software Development Environment

Brainlink's core controller is the Atmel ATxmega16A4. Atmel's AVR microcontrollers are backed by an excellent suite of open-source software tools for compiling, editing, and burning firmware. The primary tools are:

AVR-GCC.  avr-gcc is the open source compiler that allows programs written for the AVR-series microcontroller to be turned into machine code (.hex files) that can be downloaded to an AVR.  The language of AVR-GCC is C.  You can read more about avr-gcc at:

http://www.avrfreaks.net/wiki/index.php/Documentation:AVR_GCC

AVR-LIBC.  avr-libc provides the definitions for all of the address locations for the many registers on every current AVR device, and also provides a library of functions specific to AVR devices that are generally useful (things like delay program execution).  Without avr-libc, programming for AVRs would be much more difficult as you would need to look up in the datasheet and write into your code things like the specific hex address location of the analog to digital converter’s register just to read a sensor input.  More at:

http://www.nongnu.org/avr-libc/

AVR-DUDE.  avr-dude is an open source downloader tool.  It allows you to take the compiled code of your program and download it through a built-in bootloader or hardware device to your microcontroller.  It also allows you to set up the microcontrollers’ fuses, or general settings.  More at:

http://savannah.nongnu.org/projects/avrdude/

Windows and Mac both have open-source development environments that combine all of these tools as well as additional useful utilities (like editors) into a single installation.

Windows Setup

WinAVR combines everything necessary to begin writing and compiling programs for AVR microcontrollers. Download and install the most recent build of WinAVR from: http://sourceforge.net/projects/winavr/files/WinAVR/

WinAVR comes with a handy code editor called Programmer's Notepad (or pn.exe). Launch it from the WinAVR folder of the Start Menu.

Mac Setup

The best development environment for the Mac is Crosspack, available at:

http://www.obdev.at/products/crosspack/index.html

Some instructions for installing and testing are available at:

http://mightyohm.com/blog/tutorials/avr-toolchain-installation/mac-os-x

Linux Setup

For Linux, you will need to install the low-level avr-gcc, avr-libc, and avr-dude tools separately.  Here’s two step by step guides to installing these tools:

http://mightyohm.com/blog/tutorials/avr-toolchain-installation/linux

http://www.ladyada.net/learn/avr/setup-unix.html

Writing new Firmware: Where to Begin

The default firmware running on Brainlink is open sourced and downloadable here. The firmware is structured around a file containing the main function (imaginatively named mainFirmware.c), and files containing helper functions. These files are typically named after the capabilities of the Brainlink which they control. This structure allows you to radically change the main firmware's operation without needing to rewrite subroutines controlling things you don't want to modify. Or, you can keep the main firmware code intact and re-write a subroutine to make that module behave differently (for example, you may change the ADC or DAC resolution, or the default baud rate).

We recommend you begin exploring the source code by looking at mainFirmware.c, and then move on to the helper functions. The source code is heavily commented, but if anything is unclear, please post a question to the forum or email us.

In addition to the firmware, you will likely want to refer to the atXmega16a4 datasheet and user manual, as well as the Brainlink's schematic and hardware specifications.

Compile and Download new Firmware to Brainlink

To compile and download code for the Brainlink, you will first need to edit a few variables in the Makefile included with the Brainlink release firmware.

The Makefile

The makefile is a big, scary file that configures how the low level tools will operate.  Fortunately, you will likely only need to modify two of the variables:

TARGET.  Set this to the name of the file with the “main” function that you would like to compile.  Leave off the .c extension.  Like TARGET = mainFirmware

AVRDUDE_PORT.  Tells avr-dude what port on the computer you’re using to bootload over. This is your Brainlink's serial port identifier (on Windows, COMXXX, on Mac/Linux, it's /dev/yourdevicename). Like AVRDUDE_PORT=COM3.

Compiling

Once the Makefile is configured, all you need to do to compile your file is to type "make all" at the command prompt in the project directory. If successful, you should see a printout characterizing the memory usage of your code. If not, you have one or more errors in your code that must be addressed first. If you use WinAVR's programmer's notepad, you can also compile with Tools->Make All; the compiler output will be displayed in the editor.

Successful compilation will generate a number of files, including the machine code .hex file, which is the file that is downloaded to the microcontroller during bootloading.

Placing Brainlink in Bootloader Mode

Ground wire 2 of the 8 pin connector by connecting it to wire 8 of the connector. While the wire is grounded, turn on Brainlink. Brainlink's LED should be blue, indicating it is in bootloader mode.

Once in bootloader mode, there are two ways to trigger avr-dude, the tool used to download your compiled program (the .hex file). 

Use the Makefile

If you've correctly set up your Makefile with the serial port and target name, you can download your file by typing Make Program at the command line in the directory containing your code and Makefile. If using Windows, you can also trigger avr-dude by selecting Tools->Program in Programmer's Notepad.

Command Line Incantation

The Makefile simply links "Make Program" with a command line incantation that it constructs based on how you set the variables in the Makefile. This incantation is along the lines of:

avrdude -p atxmega16a4 -P serialPort -c avr109  -b 115200 -U flash:w:yourProgramName.hex

You need to change serialPort to the serial port identifier for the Brainlink on your machine (COMXXX on Windows, /dev/yourdevicename on Mac/Linux), and yourProgramName to your newly compiled .hex file.

Example Output

The following screenshot shows expected output from a successful firmware download. Note that the last line indicates an error, this is harmless so long as the text "nnnn bytes of flash verified" shows up on the second to last line.

Occasionally, the bootloader will fail to connect, and something like the following output may be observed. If this occurs, simply try the download command again.