µracoli Manual Version foo

- µracoli
- User Guide
- Reference Guide

Arduino IDE support

# Overview

µracoli provides a support package for the Arduino-IDE. The UASP (µracoli-arduino-support-package) includes a Arduino-Serial-like library for the radio transceiver and board definitions for some selected boards.

Arduino is a Microcontroller Development plattform that consists of a Java-IDE which supports various microcontroller boards. Most of the supported boards are equipped mit 8-bit-AVR microcontrollers.

Basically the Arduino-IDE provides a simple code editor and the firmware (denoted as "sketches") can be compiled and flashed with a button click. A serial terminal completes the IDE. This high level of abstration makes it very easy for none technicians and first-time users to start with embedded programming.

A sketch basically implements two functions `setup()` and `loop()` that are called from the main function of the core library. A simple API is provided, that is described at http://arduino.cc/en/Reference/HomePage.

µracoli provides a support package package for the Arduino-IDE with versions above 1.5.x.

The following boards are supported in the package:

- radiofaro - Radiofaro w/ ATmega128rfa1
- pinoccio - Pinoccio Scout
- atzb256rfr2xpro - Atmel ATmega256RFR2 Xplained Pro Evaluation Kit
- wdba1281 - Zigbit 2400MHz, w/ ATmega1281
- mnb900 - Zigbit 900MHz, w/ ATmega1281

The Arduino project did fork in 2014, see http://hackaday.com/2015/04/06/arduino-ide-forked/ for details. Since this time there are two versions of the IDE avaiable.

- IDE from arduino.cc
  https://www.arduino.cc/en/Main/Software
- IDE from arduio.org
  http://www.arduino.org/downloads

Note
  In version arduino.cc-v1.6.5/arduino.org-v1.7.3 the arduino.org IDE comes with a complete arm-none-eabi GNU toolchain and a CMSIS for Atmel Cortex-M0/M0+/M4 controllers. The arduino.cc IDE is the SAM and SAMD board variants are missing too. The rest of both IDE-packages seems to be identical.

# Installation

Download and install one of the Arduino IDEs.

Select one of the forked IDEs

- IDE from arduino.cc
  https://www.arduino.cc/en/Main/Software
- IDE from arduio.org
  http://www.arduino.org/downloads

and install it on your computer according to the instructions for your OS (Linux, Windows, MAC-OS).

Download the µracoli-Arduino-Support-Package (UASP)

Download the UASP-zipfile `uracoli-arduino-15x-` <version>.zip from http://uracoli.nongnu.org/download.html

Option A: Install UASP in the IDE directory

With this method the package is installed centrally for all users. The UASP example sketches are located in `"File / Examples / Radio"`

- Change to the Arduino-IDE directory (e.g. `"cd /opt/arduino-1.6.5/"`)
- Unpack the UASP (e.g. `"unzip uracoli-arduino-15x-<version>.zip"`)
  The UASP has three top level directories, `hardware`, `examples`, `doc`) the fell directly in the existing Arduino-IDE directories.
- Open the Arduino-IDE (e.g. `"./arduino"`).
- If you see in the menu `"Tools / Board"` the boards Radiofaro, Zigbit2400 and Zigbit900, the installation was successful.

Option B: Install UASP in the Sketchbook folder

This method installs the UASP locally in the sketchbook folder of the current user. The UASP example sketches are located in `"File / Sketchbook / Radio"`

- Open the Arduino IDE (e.g. `"/opt/arduino-1.6.5/arduino"`)
- Open the menu item `"Files / Preferences"`)
  a dialogue window pops up. Here you find the location of the "Sketchbook location" in the first entry.
- Change to the `"Sketchbook location"`, e.g. `"cd /home/axel/Arduino"`.
- Unpack the UASP (e.g. `"unzip uracoli-arduino-15x-<version>.zip"`)
  The UASP has three top level directories, `hardware`, `examples`, `doc`) the fell directly in the existing Arduino-IDE directories.
- Reopen the Arduino-IDE (e.g. `"/opt/arduino-1.6.5/arduino"`) to load the UASP boards and examples into the IDE.
- If you see in the menu `"Tools / Board"` the boards Radiofaro, Zigbit2400 and Zigbit900, the installation was successful.

# Usage

Using the HelloRadio sketch

Restart the Arduino-IDE after unpacking `uracoli-arduino-` <version>.zip and check if you see the new boards at the end of the list that opens if you click the menu entry `"Tools/Board"` and select your radio board, e.g. "Radiofaro", "Zigbit 2400MHz", etc.

In the next step select the in the menu `"Tools / Serial Port"` the serial port to which your radio board is connected.

Now open the `HelloRadio` sketch. It can be found either in `"File / Examples / Radio"` or `"File / Sketchbook / Radio"`, depending on the installation option you did choose (see Installation).

Now select the menu entry `"File / Upload"`. The sketch will compiled and flashed to the choosen radio board.

Note
  If the upload fails, mark the options `"compile verbose"` and `"upload verbose"` in the dialogue that opens when clicking `"File / Preferences"` and check in the lower window pane of the Arduino-IDE what goes wrong.

The sketch "HelloRadio", that you have currently uploaded, sends a short frame every 500ms on channel 17 and reports the transmission also on its serial port. You can open a terminal with `"Tools / SerialMonitor"` and you should see in the terminal window:

HelloRadio
TX: 0
TX: 1
TX: 2
...

Each printed number shows, that a frame was successfully transmitted. If you see this output, that means that you are now "on air".

Example Sketches

A good starting point for using the radio functions are the example sketches.

- IoCheck.ino
- RadioUart.ino
- HelloRadio.ino
- IoRadio.ino
- Gateway.ino
- Remote.ino

Function Reference

The regular Arduino core functions are documented at http://arduino.cc/en/Reference/HomePage.

The radio specific functions are described in section Arduino Radio Functions.

Building Sketches from Command Line

Beside several thirdparty CLI tools, e.g. Arscons, Inotool, since version 1.5 the Arduino IDE supports its own CLI, see https://github.com/arduino/Arduino/blob/ide-1.5.x/build/shared/manpage.adoc

arduino --verify \
--board uracoli:avr:radiofaro \
examples/Radio/RadioUart/RadioUart.ino

Note
  - In order to explicitely set the Arduino build path add `–pref` build.path=<your_build_dir> to the command.
  - With option -v, a more verbose output of the build process is generated and the current Arduino build directory is shown.

# Bootloader

If the Arduino Bootloader in your board is accidently erased, you can restore it with the following procedure.

In order to flash the bootloader, use a flash programmer and a programming tool of your choice (avrdude, atprogram, Atmel-Studio) and flash the file to the board.

The source code and a precompiled Intel-Hex file of the bootloader is located in the directory `hardware/uracoli/avr/bootloaders/radiofaro`.

Check also if the fuses are set correctly:

LF = 0xe7
HF = 0x90
EF = 0xf6

Examples

The preferred flashing program is avrdude since it comes with the Arduino distribution.

Note
  : If you use avrdude from the arduino package, an error message about the missing config file may occur.
  avrdude: can't open config file "...avrdude.conf": No such file or directory
  avrdude: error reading system wide configuration file
  So you have to give the path to the config file explicitely.

Examples

# Connection AVR dragon via isp
PROG=avrdragon_isp
# Connection AVR dragon via jtag
PROG=avrdragon_jtag
avrdude -C $ARDUIONDIR/hardware/tools/avr/etc/avrdude.conf \
-P usb -c $PROG -p m128rfa1 \
-U lf:w:0xe7:m -U hf:w:0x90:m -U ef:w:0xf7:m \
-U fl:w:ATmegaBOOT_radiofaro.hex

If the bootloader is flashed correctly, it can be checked with

avrdude -C $ARDUIONDIR/hardware/tools/avr/etc/avrdude.conf \
-P <MYSERIALPORT> \
-b 57600 -c arduino -p m128rfa1 -U <MYHEXFILE>

# Licenses

This package incorporates source code from different license models, which has an influence on the usae of the code in proprieatary projects and environments.

GPL version 2.0

According to the file header, the bootloader is licensed under GNU General Public License version 2.0. See http://www.gnu.org/licenses/gpl-2.0.txt or file link:license_gpl_2v0.txt[].

hardware/uracoli/bootloaders/radiofaro/ATmegaBOOT.c

LGPL version 2.1

The files copied from the original Arduino core are licensed under the GNU Lesser General Public License version 2.1. This code is linked to each sketch. See http://www.gnu.org/licensesUold-licenses/lgpl-2.1.txt or file link:license_lgpl_2v1.txt[].

hardware/uracoli/variants/zigbit900/pins_arduino.h
hardware/uracoli/variants/zigbit2400/pins_arduino.h
hardware/uracoli/variants/radiofaro/pins_arduino.h

Modified BSD license

The sources of the µracoli radio functions are licensed under the modified 3 clause BSD license. See file link:license_uracoli.txt[].

hardware/uracoli/cores/uracoli/trx_rf230_param.c
hardware/uracoli/cores/uracoli/const.h
hardware/uracoli/cores/uracoli/boards/base_zdma1281.h
hardware/uracoli/cores/uracoli/boards/board_derfa.h
hardware/uracoli/cores/uracoli/boards/board_wdba1281.h
hardware/uracoli/cores/uracoli/trx_rf230_sram.c
hardware/uracoli/cores/uracoli/trx_datarate_str.c
hardware/uracoli/cores/uracoli/board.h
hardware/uracoli/cores/uracoli/at86rf230b.h
hardware/uracoli/cores/uracoli/trx_rf230.c
hardware/uracoli/cores/uracoli/at86rf212.h
hardware/uracoli/cores/uracoli/atmega_rfa1.h
hardware/uracoli/cores/uracoli/trx_datarate.c
hardware/uracoli/cores/uracoli/trx_rf230_frame.c
hardware/uracoli/cores/uracoli/trx_rfa.c
hardware/uracoli/cores/uracoli/trx_rf230_irq.c
hardware/uracoli/cores/uracoli/trx_rf230_bitwr.c
hardware/uracoli/cores/uracoli/trx_rf230_bitrd.c
hardware/uracoli/cores/uracoli/radio_rf230.c
hardware/uracoli/cores/uracoli/at86rf230a.h
hardware/uracoli/cores/uracoli/radio_rfa.c
hardware/uracoli/cores/uracoli/radio.h
hardware/uracoli/cores/uracoli/trx_rf230_crc.c
hardware/uracoli/cores/uracoli/transceiver.h
hardware/uracoli/cores/uracoli/usr_radio_irq.c
hardware/uracoli/cores/uracoli/trx_rf230_misc.c
examples/Radio/RadioUart/RadioUart.ino
examples/Radio/IoCheck/IoCheck.ino
examples/Radio/HelloRadio/HelloRadio.ino
examples/Radio/IoRadio/IoRadio.ino