What you need to install

• tuxup
• dfu-programmer
  
• firmware hex files
  

Tuxup will be able to update the firmware of all AVR CPU's, which means all CPU's inside Tux and the RF CPU of the dongle.

To reprogram the USB firmware,  dfu-programmer is used. As dfu-programmer is not that easy to use, tuxup will be used and do the calls to dfu-programmer for you.

Installing tuxup

You need to download Tuxup, build it and eventually copy the executable to a directory in your path as there's still no install directive in the Makefile. So that's 3 steps:

• download the latest version of tuxup from the Developer Corner;
  
• build it with 'make'
• copy the 'tuxup' file to /usr/local/bin to be able to launch it from anywhere (optional but recommended)

Getting the hex files

You can get the hex files from the Developer corner (Official firmware files).

If you want to test the development firmware, you can also get the hex files from svn at http://svn.tuxisalive.com/firmware/hex

Testing tuxup

To be sure everything works fine, don't try to bootload all CPU's simultaneously the first time. These few steps will check that dfu-programmer and tuxup are setup correctly.

First go to the folder containing your hex files.

If you never used your Tux Droid and don't know if you need to be root or not to use tuxdaemon, then login as root. See this FAQ for more information.

Then follow this procedure:

1. Checking your hex files
   
   • be sure you are in your hex folder, then type
     

     $ tuxup --all --pretend .
     Programming ./fuxusb.hex in USB CPU
     
     Programming ./tuxcore.hex in core CPU
     Version 0.3.0
     
     Programming ./tuxcore.eep in core CPU
     
     Programming ./tuxaudio.hex in audio CPU
     Version 0.3.0
     
     Programming ./tuxaudio.eep in audio CPU
     
     Programming ./tuxrf.hex in tux RF CPU
     Version 0.1.1
     
     Programming ./fuxrf.hex in fux (dongle) RF CPU
     Version 0.1.1

   • you should see the version of some of your hex files
     
2. Checking dfu-programmer
   
   • use a pen to push on the button located inside the hole on the belly of the dongle
   • while pushing on that button, connect the USB cable to your computer (yeah, that requires some skills ;-)
     
   • the blue eyes of the dongle should not light up, otherwise try again
   • type
     

     $ tuxup fuxusb.hex
     Programming fuxusb.hex in USB CPU
     Bootloader Version: 0x03 (3)
     Validating...
     6507 bytes used (39.72%)
     [OK]
     
     Time elapsed:  6 seconds.
     

   • if you get [OK], you just updated the dongle firmware correctly and you can continue, otherwise try again or look at the common problems
     
3. Checking the I2C programming
   
   • connect the dongle normally (without pressing on the button and don't add the programming cable to tux for now)
   • try to reprogram the RF radio by typing
     

     $ tuxup fuxrf.hex
     Programming fuxrf.hex in fux (dongle) RF CPU
     Version 0.1.1
     ............................................................ [OK]
     
     Time elapsed:  2 seconds.

   • if you get [OK], you just reprogrammed the rf module of the dongle, you're ready to reprogram your tux now.
     

Setting Tux Droid in bootloader mode

There is a special mode that needs to be enabled to upgrade the firmware: the bootloader mode.

Follow this sequence to get in the bootloader mode:

• A clean start: disconnect the dongle, turn off Tux Droid and close any audio applications that might be running.
• Unscrew the battery door on the back of Tux (above the power switch).
  
• Plug the dongle again into the USB port.
• Keep the head button pushed on Tux Droid while switching him back on.
• The left eye LED will be lit, indicating Tux Droid is in the bootloader mode.
• Connect the provided white programming cable between Tux Droid and the USB dongle.
• You're ready to bootload!
  

Reprogramming your tux with tuxup

Important information

The 2 RF CPU's (tuxrf and fuxrf) don't have a bootloader section, this means that the firmware reprograms itself without the use of adequate bootloader facilities and protections. No protections! This means that you should NOT reprogram the RF CPU's if you don't have to.

If you program a wrong hex file in the dongle, tuxcore or tuxaudio, there's no problem as you can always re-enter the bootloader mode and reprogram. But if you program the wrong firmware in the tuxrf and fuxrf, you may not enter the bootloader anymore and your rf modules will be unusable unless you buy or build a programmer for the AVR CPU's. See this FAQ for more information (XXX add the FAQ ;-)

Reprogramming important firmware

Usually, tuxcore and tuxaudio will be the only updated firmwares as that's where we'll add new functionalities and that's also the 2 firmwares people will be able to play with and customize. So if what you want is only reprogram those 2, you can use

tuxup --main path/to/hex/folder/

Reprogramming all firmware

When we fix bugs in different firmware, you better download the latest hex files and reprogram everything so you're sure to have an up to date Tux Droid. Just use

tuxup --all path/to/hex/folder/

Reprogramming only some firmware

To reprogram only one hex file, you can simply give it to tuxup like this:

tuxup hex_file

Advanced usage

To get some command line help, type 'tuxup --help'
You should also get more detailed information in the README file of tuxup until we have a real manpage :-)

$ tuxup --help
Usage: tuxup options [path|file ...]
 -m --main                Reprogram tuxcore and tuxaudio (flash and eeprom) with hex files located in path.
 -a --all                 Reprogram all cpu's with hex files located in path.
 -p --pretend             Don't do the programming, just simulates.
 -h --help                Display this usage information.
 -v --verbose             Print verbose messages.
 -V --version             Print the version number.


Connection: connect the dongle alone, then press on tux's head
  button while switching it on, finally connect the white cable
  between tux and the dongle

Notes: '-a' and -'m' options can't be used simultaneously.
  Inputfiles can be specified only if the -a or -m options are
  not selected.
  Any .hex or .eep files compiled for Tux Droid can be used.
  The eeprom file names should contain 'tuxcore' or 'tuxaudio'
  in order to be identified, the usb hex file should contain
  'fuxusb'.

Common problems

Tux not found on USB

It seems you don't have the permissions to access the usb device. Try to log as root, that should work, then you can fix the permissions like indicated in this FAQ.

Another reason is when you took the binary version of dfu-programmer while your system has another glibc version. Try to run dfu-programmer. If it says

/lib/tls/i686/cmov/libc.so.6: version `GLIBC_2.4' not found (required by ./dfu-programmer)

then download the sources of dfu-programmer and compile it by yourself.

usb_bulk_write error: status = -22

Do you get the following error?

Programming fuxusb.hex in USB CPU
usb_bulk_write error: status = -22 :: error submitting URB: Invalid argument 
Switching to bootloader mode failed.
dfu-programmer: no device present.
[FAIL] Erasing the USB CPU failed.

Time elapsed:  0 seconds.

Then you probably still have the original/old firmware which uses bulk instead of interrupt and are using the new version of tuxup which uses interrupts. You have to enter bootloader mode manually in this case by using a pen to push on the button located inside the hole on the belly of the dongle, and while keeping that button pushed, connect the USB cable to your computer. No leds should light up, you can now reprogram the usb firmware by typing

$ tuxup fuxusb.hex