µracoli Manual Version foo

- µracoli
- User Guide
- Reference Guide

The Source Code Package (todo: split to existing pages)

## Overview

This package contains the uracoli-source code. It consists of the library, various example programms that illustrate the usage of the library functions and some end user applications.

Directory | Content
--- | ---
`src/` | source code of the μracoli library .
`inc/` | The library header file.
`wuart/` | The wireless UART application xxx .
`sniffer/` | The source code of the sniffer firmware.
`wibo/` | Wireless bootloader source code, host application and examples.
`xmpl/` | Some example applications, that illustrate how to use the µracoli functions.
`as6/` | Atmel Studio 6 project template.

## Prerequisites

In order to use the libraries and applications you need GNU-make and the GNU-AVR toolchain, consisting of compiler, linker, avr-libc and a hardware programming tool.

### AVR toolchain

Under Windows install Atmel Studio 6. For older Atmel MCUs (up to Atmega128RFA1) the last version of WinAVR is fine too.

On Linux install the following packages with the packet manager of the distribution. In Ubuntu or Debian this can be achieved with the following command line:

    sudo apt-get install avr-libc binutils-avr gcc-avr avrdude avarice gdb-avr

- avr-gcc - The AVR GCC C-compiler
- avr-binutils - Linker, Object File Converter, ...
- avr-libc - Standard C library which provides a good set of C standard functions
- avrdude - Tool for programming to the internal Flash memory and/or EEPROM.
- avr-gdb - GNU debugger to debug AVR programs
- AVaRICE - Tool to interfaces avr-gdb with the Atmel JTAG ICE hardware debugger.

A detailed installation description is available here.

### Python

Python version 2.7.x is required to run the μracoli tools like sterm or the sniffer interface.

Under Windows intstall the MSI package for Python 2.7.9 from http://www.python.org. This package has pip already included, so the installation of further packages is rather simple.

Now run `pip install serial` with administrator privilres.

Under Linux install Python and Python-pip with the package manager of your distribution.

Additionally run `pip install serial` as super user.

The libraries can be build with make. In order to get an overview, if your board is supported, type

    make -C src/ list

The libraries for e.g. the "radiofaro" board, are build with the command:

    make -C src radiofaro

This will create the directory +lib+ and the uracoli-library for radiofaro.

    $ls lib/
    liburacoli_radiofaro.a

## Scritable Terminal Program

This python script +wuart/sterm.py+ is a usefull addon for debugging wireless applications. How to use the script is described in section sterm

## Sniffer Firmware

With the sniffer firmware the frames exchanged in an IEEE 802.15.4 network can be captured and transmitted over the serial interface to the PC. This firmware is intended for use with a the Python script +sniffer.py+ and http:www.wireshark.org[wireshark]. The script together with the documentation, which explains the sniffer setup, can be found in the package uracoli-sniffer-<version>.zip on http://uracoli.nongnu.org/download.html[].

The sniffer firmware can be compiled with the commands

    make -C src mysnifferboard
    make -C sniffer mysnifferboard

For which boards the sniffer application is available, you can find out with the command: make -C sniffer list

## Wireless Bootloader

The wireless bootloader (WiBo) is an application that resides in the bootloader section of the AVR and therefore it can erase and rewrite the programm flash memory. In Difference to a regular bootloader, WiBo receives its data over the RF link. WiBo modifies the flash directly, therefore no special backup flash memory, like in other over the air upgrade (OTA) solutions, is required on the transceiver board.

A detailed description how WiBo is used can be found in section wibo.

## Examples

The example source code can be found in the directory +xmpl/+. This simple example programms are thought as starters for your application.

- `xmpl_leds.c` Example use of the LED macros
- `xmpl_key_events.c` Example for key event processing with a single key
- `xmpl_keys.c` Example use of the KEY macros
- `xmpl_hif.c` Example for use of the HIF functions
- `xmpl_hif_echo.c` Example that implements HIF echo, usefull to test the HIF troughput
- `xmpl_timer.c` Example for using the timer macros
- `xmpl_dbg.c` Example for use of the DBG_XXX macros
- `xmpl_linbuf_tx.c` Example use of the buffer functions
- `xmpl_trx_base.c` Example for accessing the transceiver
- `xmpl_trx_echo.c` Example for echoing received frames
- `xmpl_trx_rxaack.c` Example for receiving frames in rx_aack mode
- `xmpl_trx_rx.c` Example for receiving frames
- `xmpl_trx_txaret.c` Example for transmitting frames in tx_aret mode
- `xmpl_trx_tx.c` Example for transmitting frames
- `xmpl_radio_range.c` Example use of the radio and ioutil functions for a simple range test
- `xmpl_radio_stream.c` Example use of the radio stream functions

The example firmware can be build with the following commands:

    make -C src myboard
    make -C xmpl -f xmpl_<myexample>.mk myboard

Note: Some of the examples are not available on all boards, due to the lack of some hardware features, e.g. if the LEDs, the KEYs or/and the HIF is absent. A list of supported boards of the example can be obtained by:

make -C xmpl -f xmpl_<myexample>.mk list