µracoli Manual Version foo

- µracoli
- User Guide
- Reference Guide

Getting Started

# Overview

- Quick Start
  Jumpstart using µracoli with your hardware.
- Architecture
  Some words about the concepts of µracoli.
- Package Contents
  Contents of the source package.
- The Source Code Package (todo: split to existing pages)
  Overview of the package contents.
- Prerequisites
  What is needed to start with µracoli?
- Compiling the Library
  How the Library is built for specific boards.
- Using Examples and Applications
  Compiling and using the provided applications.
- Creating Own Projects
  Creating own applicationw with liburacoli

# Quick Start

- Install a toolchain (see Prerequisites)
- Select your board from Boards and Modules, rember the target name.
- have avr-gcc and make in your PATH.
- execute `"make -C src/wuart <target>"`
- Flash @ "src/bin/wuart_radiofaro.hex"
- connect a terminal to your board
- press reset and see in the terminal the boot message
- Flash the second board and connect it to a terminal too
- the letters typed in one window should be displayed in the second terminal window the second terminal window
- todo add pictures
- todo add links to Howto sections.

# Architecture

Software modules

# Package Contents

uracoli-<version>
|-- doc
| `-- search
|-- scripts
`-- src
|-- as6
| `-- halimbawa
|-- examples
|-- inc
| |-- boards
| `-- sensors
|-- rsensor
|-- sniffer
|-- uracoli
|-- wibo
| |-- wibo
| |-- wibohost
| `-- wibotest
`-- wuart

# Prerequisites

- Two or more of the supported transceiver boards (see Boards and Modules) are needed.
- In order to flash the compiled firmware into the micro controller, an hardware programmer like AVRISP, JTAGICE mkII, AVR-Dragon or a similiar tool is needed.
- A working AVR toolchain is required. The GNU AVR tools (or WinAVR on Windows) are used for compiling the firmware. The programs avrdude, avarice, avr-gdb (or AVR-Studio on Windows) are used to flash and debug the compiled applications.
- Additionally you probably want to install the python programming language with a version before .0 with the module pyserial in order to easily run and create PC applications that interact over the serial port with a radio module.
- If you want to build all libraries and applications from scratch, scons is needed. Building the documentation requires doxygen and graphviz.

Todo: clean / remove the link, add Toolchain description in HowTo. Some more detailed information about installing the software can be found at http://uracoli.nongnu.org/gettingstarted.html.

# Compiling the Library

cd uracoli-<version>/src/uracoli
make [help|list|all|<board>]

- `"make help"` : display the usage message
- `"make list"` : display all supported boards.
- `"make all"` : compile all libraries ``lib/liburacoli_*`.a`
- `"make <board>"` : compile the library ``lib/liburacoli_<board>`.a`

# Using Examples and Applications

The examples are minimal C-Programms, that illustrate the usage of the `liburacoli` functions. For more details refer to section Compiling the Examples.

The applications implement more complex functions and can be thought as tools, like a wireless UART or a sniffer. For more details refer to section Applications. For some of the applications a supplementary PC-software is required, e.g. `sniffer.py` for the firmware `sniffer_<board>.hex`. In order to be platform independent, the PC-software is written in Python.

# Creating Own Projects

The library is used by the

- examples and
- applications or it can be used in
- own applications.

The Library Reference documents the functions seperately.

As a starting point for an own application, one of the examples can be used.

Make a directory, e.g. `myproject` in `"uracoli-<version>/src"`

Start with writing an initial C-File and store it as `myproject.c:`

#include <stdio.h>
#include "board.h"
#include "transceiver.h"
#include "radio.h"
uint8_t RxFrame[MAX_FRAME_SIZE];
int main(void)
{
radio_init(RxFrame, sizeof(RxFrame));
while(1)
{
}
return 0;
}

Now the C-File can be compiled and linked against `liburacoli`. In order to get the compiler and linker flags, execute the compiling of one of the examples and copy the command line from there:

make -C ../examples/ -n -f xmpl_hif.mk rdk230
...
avr-gcc -Wall -Wundef -Os -g -ffunction-sections -fdata-sections -std=c99 -mmcu=atmega1281 -Wa,-adhlns=../build/xmpl_hif_rdk230.lst -Drdk230 -DF_CPU=8000000UL -DAPP_NAME="\"xmpl_hif\"" -I../inc -I. -c -o ../build/xmpl_hif_rdk230.o xmpl_hif.c
avr-gcc -o ../bin/xmpl_hif_rdk230.elf -Wall -Wundef -Os -g -ffunction-sections -fdata-sections -std=c99 -mmcu=atmega1281 -Wa,-adhlns=../build/xmpl_hif_rdk230.o -Drdk230 -DF_CPU=8000000UL -DAPP_NAME="\"xmpl_hif\"" -I../inc -I. ../build/xmpl_hif_rdk230.o -L../lib -Wl,--gc-sections -luracoli_rdk230
avr-objcopy -O ihex ../bin/xmpl_hif_rdk230.elf ../bin/xmpl_hif_rdk230.hex
...

The own project can then be build with the command line

avr-gcc -Os -g \
-std=c99 -mmcu=atmega1281 \
-Drdk230 -DF_CPU=8000000UL \
-I../inc -I. \
-o myproject.elf \ myproject.c \
-L../lib -Wl,--gc-sections \
-luracoli_rdk230

The file `myproject.elf` contains the firmware and can be flashed on the tartet board.