µracoli Manual Version foo

- µracoli
- User Guide
- Reference Guide

uracoli-src.md
1 # The Source Code Package (todo: split to existing pages) {#md_src}
2
3 ## Overview
4
5 This package contains the uracoli-source code. It consists of the library,
6 various example programms that illustrate the usage of the library functions
7 and some end user applications.
8
9 | Directory | Content |
10 |-----------:|:--------|
11 | `src/` | source code of the &mu;racoli [library](#src) .
12 | `inc/` | The library header file.
13 | `wuart/` | The wireless UART application [xxx](#md_wuart) .
14 | `sniffer/` | The source code of the sniffer firmware.
15 | `wibo/` | Wireless bootloader source code, host application and examples.
16 | `xmpl/` | Some example applications, that illustrate how to use the µracoli functions.
17 | `as6/` | Atmel Studio 6 project template.
18
19 ## Prerequisites
20
21 In order to use the libraries and applications you
22 need GNU-make and the GNU-AVR toolchain, consisting of compiler, linker,
23 avr-libc and a hardware programming tool.
24
25 ### AVR toolchain
26
27 Under *Windows* install [Atmel Studio 6](http://www.atmel.com/microsite/atmel_studio6/).
28 For older Atmel MCUs (up to Atmega128RFA1) the last
29 version of [WinAVR](http://www.atmel.com/microsite/atmel_studio6/) is fine too.
30
31 On *Linux* install the following packages with the packet manager of the
32 distribution. In Ubuntu or Debian this can be achieved with the following
33 command line:
34
35 sudo apt-get install avr-libc binutils-avr gcc-avr avrdude avarice gdb-avr
36
37 - avr-gcc - The AVR GCC C-compiler
38 - avr-binutils - Linker, Object File Converter, ...
39 - avr-libc - Standard C library which provides a good set of C standard functions
40 - avrdude - Tool for programming to the internal Flash memory and/or EEPROM.
41 - avr-gdb - GNU debugger to debug AVR programs
42 - AVaRICE - Tool to interfaces avr-gdb with the Atmel JTAG ICE hardware debugger.
43
44 A detailed installation description is available [here](http://uracoli.nongnu.org/avrtools.html).
45
46 ### Python
47
48 Python version 2.7.x is required to run the &mu;racoli tools like sterm or the
49 sniffer interface.
50
51 Under *Windows* intstall the MSI package for Python 2.7.9 from http://www.python.org.
52 This package has pip already included, so the installation of further
53 packages is rather simple.
54
55 Now run `pip install serial` with administrator privilres.
56
57 Under *Linux* install Python and Python-pip with the package manager of
58 your distribution.
59
60 Additionally run `pip install serial` as super user.
61
62
63 ## Compiling the Libraries ## {#src}
64
65 The libraries can be build with make. In order to get an overview,
66 if your board is supported, type
67
68 make -C src/ list
69
70 The libraries for e.g. the "radiofaro" board, are build with the
71 command:
72
73 make -C src radiofaro
74
75 This will create the directory +lib+ and the uracoli-library for radiofaro.
76
77 $ls lib/
78 liburacoli_radiofaro.a
79
80
81 ## Scritable Terminal Program
82
83 This python script +wuart/sterm.py+ is a usefull addon for debugging wireless
84 applications. How to use the script is described in section @ref sterm
85
86 ## Sniffer Firmware
87
88 With the sniffer firmware the frames exchanged in an IEEE 802.15.4 network
89 can be captured and transmitted over the serial interface to the PC. This
90 firmware is intended for use with a the Python script +sniffer.py+
91 and http:www.wireshark.org[wireshark]. The script together with the
92 documentation, which explains the sniffer setup, can be found in the package
93 uracoli-sniffer-<version>.zip on http://uracoli.nongnu.org/download.html[].
94
95 The sniffer firmware can be compiled with the commands
96
97 make -C src mysnifferboard
98 make -C sniffer mysnifferboard
99
100 For which boards the sniffer application is available, you can find out with
101 the command:
102 make -C sniffer list
103
104 ## Wireless Bootloader
105
106 The wireless bootloader (WiBo) is an application that resides in the
107 bootloader section of the AVR and therefore it can erase and rewrite the
108 programm flash memory. In Difference to a regular bootloader, WiBo receives its
109 data over the RF link. WiBo modifies the flash directly, therefore no special
110 backup flash memory, like in other over the air upgrade (OTA) solutions,
111 is required on the transceiver board.
112
113 A detailed description how WiBo is used can be found in section @ref wibo.
114
115 ## Examples
116
117 The example source code can be found in the directory +xmpl/+.
118 This simple example programms are thought as starters for your application.
119
120 - `xmpl_leds.c`
121 Example use of the LED macros
122 - `xmpl_key_events.c`
123 Example for key event processing with a single key
124 - `xmpl_keys.c`
125 Example use of the KEY macros
126 - `xmpl_hif.c`
127 Example for use of the HIF functions
128 - `xmpl_hif_echo.c`
129 Example that implements HIF echo, usefull to test the HIF troughput
130 - `xmpl_timer.c`
131 Example for using the timer macros
132 - `xmpl_dbg.c`
133 Example for use of the DBG_XXX macros
134 - `xmpl_linbuf_tx.c`
135 Example use of the buffer functions
136 - `xmpl_trx_base.c`
137 Example for accessing the transceiver
138 - `xmpl_trx_echo.c`
139 Example for echoing received frames
140 - `xmpl_trx_rxaack.c`
141 Example for receiving frames in rx_aack mode
142 - `xmpl_trx_rx.c`
143 Example for receiving frames
144 - `xmpl_trx_txaret.c`
145 Example for transmitting frames in tx_aret mode
146 - `xmpl_trx_tx.c`
147 Example for transmitting frames
148 - `xmpl_radio_range.c`
149 Example use of the radio and ioutil functions for a simple range test
150 - `xmpl_radio_stream.c`
151 Example use of the radio stream functions
152
153 The example firmware can be build with the following commands:
154
155 make -C src myboard
156 make -C xmpl -f xmpl_<myexample>.mk myboard
157
158 Note: Some of the examples are not available on all boards, due
159 to the lack of some hardware features, e.g. if the LEDs, the KEYs or/and the
160 HIF is absent.
161 A list of supported boards of the example can be obtained by:
162
163 make -C xmpl -f xmpl_<myexample>.mk list
164