Writing and Compiling Firmware

Here's a quick overview of writing and compiling firmware for the TekPet boards. There's some example firmware in SVN at source:trunk/electrical/firmware/example you can/should use as a template for your firmware.

Compiling Firmware

These instructions are written for and tested on Linux. However, you should be able make these work with Windows as well without too much trouble.

Setting up Your Build Environment

You need to download and install an AVR compiler, avr-libc (library for basic functions), and flip (to upload your firmware onto the TekPet).

avr-gcc/avr-libc

Most Linux distros already have avr-gcc and avr-libc packaged. On Ubuntu, the packages are avr-gcc and avr-libc. Search your favorite package manager for details. If your distro does not have a precompiled package, you can compile and install them yourself. Read the avr-libc installation instructions for step-by-step instructions.

On Windows, install WinAVR. That should be all you need.

Flip

Flip is the program you use to upload firmware from your computer to the TekPet. You can download it from AVR. There're versions for both Windows and Linux.

On some Linux distros, it will "just work" (Red Hat/Fedora). On Ubuntu and some others, you need to do some special hacking. Download the file libatlibusbdfu.so into flip.3.2.1/bin directory. (Here's an explanation of the problem from Atmel).

Also, I've had to run Flip as root (through sudo) on my machine (Kubuntu 8.04). If Flip isn't seeing your TekPet, try running it as root.

Compiling The Example

Once you've got your buildtools setup, download a copy of the example firmware in SVN. Check the page on wiki:Subversion for more information if you haven't used Subversion before.

Once you the firmware downloaded, run "make" in the electrical/firmware/example directory. When it's done, you should have a file called "main.hex" which you can upload using Flip. If you get errors, make sure you have avr-gcc in your $PATH. If you still have errors, please post them to the discussion board (along with your operating system/distro/other helpful info).

---

Writing Firmware

The most interesting part of the example firmware is probably source:trunk/electrical/firmware/example/hid_task.c. This file shows reading USB input, making decisions based on that input, and how to write data out. Especially look at the functions hid_report_out() (get data from host) and hid_report_in() (send data to host).

Reading and Writing Data

Before reading or writing any data over USB, you have to select your endpoint so the tekpet knows where to read or write from or to. Endpoints in the firmware we're using are always named from the host's (computer's) point of view. The endpoint we read data from is named EP_HID_OUT, and the one we write to is named EP_HID_IN. To select an endpoint, use the Usb_select_endpoint() function. After selecting an endpoint, use the Usb_read_byte() and Usb_write_byte() functions.

unsigned char data[2].
Usb_select_endpoint(EP_HID_OUT);
data[0] = Usb_read_byte();
data[1] = Usb_read_byte();
Usb_ack_receive_out(); /* Tell host we've read in data */

Usb_select_endpoint(EP_HID_IN);
Usb_write_byte(0xFF);
Usb_write_byte(0x3A);
Usb_ack_in_ready(); /* Notify host that we're ready to be read */

If you just want your firmware to respond to commands sent to it by the host, then you can put both your read code and your write code into one function. One way to do this is modify the hid_report_out() function. See the servo firmware's hid_report_out() function for an example of this.

If you have data that needs to be sent the host without responding to a command, put your Usb_write_byte() functions in the hid_report_in() function. This function is called repeatedly (after hid_report_out() is called). See the example firmware for a demo.

Changing Endpoints

Depending on what kind of data your firmware receives or sends to the host, you may need to change your endpoints' settings. The default firmware's two endpoints both are defined at interrupt endpoints with 8 byte long packets. If you are reading or writing a lot of data, (rule of thumb; more than 8 bytes at a time), you'll probably want to change to using a bulk endpoint and/or a bigger packet size. To make these changes, there are two files you need to edit.

• usb_descriptors.h:98: Change the EP_ATTRIBUTES_n define to change the endpoint type. To change packet size, change the EP_xxx_LENGTH and LENGTH_OF_REPORT_xxx defines.
• usb_specific_request.c:181 Change the usb_user_endpoint_init() function to have the right SIZE_xx definition in the calls to usb_configure_endpoint().

Valid sizes for endpoints in full-speed devices are 8, 16, 32, and 64 bytes.

---

USB on Host

To send USB commands from your computer to the TekPet, use libusb on Linux or libraries fro Atmel on Windows. The led-computer.c attachment has some very basic example code for sending/receiving USB data on Linux through libusb. Atmel has some libraries on their website that should do a similar thing for Windows.