= The µracoli Source Package =

:author: Axel Wachtler
:mail: axel@uracoli.de
:url: http://www.uracoli.de
:version: 0.2.0

== Overview ==

This package contains the uracoli-source code.

- +src+
  Source code of radio and ioutil library.
- +wuart+
  The wireless UART application.
- +xmpl+
  Some example applications, that illustrate how to use
  the µracoli functions.
- +wibo+
  The wireless bootloader source code, host application and
  examples.
- +inc+
  The header files used by the source code.

In order to build the libraries and applications you
need an installed AVR toolchain.

[horizontal]
avr-gcc ::
    AVR GCC C-compiler which we need to compile the libraries
    and the test examples
avr-binutils ::
    Linker, Object File Converter, ..
avr-libc ::
    Standard C library which provides a good set of C
    standard functions
avrdude ::
    Tool to transfer the machine code (.hex files) via ISP
    or JTAG AVR interface
    to the internal Flash memory and/or EEPROM.
avr-gdb ::
    GNU debugger to debug AVR programs
AVaRICE ::
    This tool interfaces the AVR GNU debugger with the AVR
    JTAG interface which allows real in-circuit debugging

A detailed installation description is available at
http://uracoli.nongnu.org/avrtools.html.


== Compiling the Libraries ==

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 libraries for radiofaro.

------
$ls -1sh  lib/
216K lib/libio_radiofaro.a
324K lib/libradio_radiofaro.a
 36K lib/libwibohost_radiofaro.a
------

== The Wireless UART ==

The wireless UART can be used to communicate between two PCs via a RF
link, or to communicate between a PC and an autnomous sensor/actor
node. The WUART application starts on a fixed channel and is automatically
in the transparent data mode.


["ditaa"]
--------------------------------------------------------


 +------------------+            +------------------+
 |   Terminal PC#1  |            |   Terminal PC#2  |
 |------------------|            |------------------|
 |    Wuart 0.2 ... |            |    Wuart 0.2 ... |
 |#2: howdy #1      |            |#1: hiho #2       |
 |#3: t=24          |            |#3: t=24          |
 |#2: yyyyy         |            |#1: xxxxx         |
 |#3: t=25          |            |#3: t=25          |
 |                  |            |                  |
 +-------*----------+            +--------*---------+
         |                                |
         |serial IF                       |serial IF
         |                                |
         |       ^                 ^      |
     +---*----+  |                 |  +---*----+
     | WUART  |  |                 |  | WUART  |
     | Node#1 +--+                 +--+ Node#2 |
     |        |                       |        |
     +--------+       ^               +--------+
                      | +--------+
                      +-+ Sensor |
                        | Node#3 |
                        +--------+

--------------------------------------------------------

The wireless UART for the radiofaro board is build with the following
commands:

------
make -C src radiofaro
make -C wuart radiofaro
------

The firmware file +wuart_radiofaro.hex+ will be now available in the directoy
+bin/+. It can be flashed in the microcontroller e.g. using an AVR Dragon
programmer with the command:

------
avrdude -Pusb -cdragon_jtag -pm128rfa1 -U bin/wuart
------

Now open a serial terminal programm, adjust the baudrate, set the
hardware handshake to _none_ and after a reset of WUART node you will
see a boot message, similiar to this:

------
Wuart 0.2 chan=17 radio 02.01

------

Do the same steps for a second board an try to chat between the terminal
windows. Alternatively you can compile the example programm +xmpl_linbuf_tx.hex+
and watch the text that appears in the terminal window of the PC.

------
 make -C src anotherboard
 make -C xmpl -f xmpl_linbuf_tx.mk anotherboard
------

== The Examples ==

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


[horizontal]
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 xmpl -f xmpl**.mk list
 make -C src myboard
 make -C xmpl -f xmpl**.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.

== The Wireless Bootloader ==

How to use the wirless booloader is described in the file wino/README.txt
or doc/wibo.pdf.
