µracoli Manual  Version foo
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 μ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 μ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