maniacbug / ZMAC

Makes an Arduino Library from the Atmel 802.15.4 MAC distribution

ZMAC: Makes an Arduino Library from the Atmel 802.15.4 MAC distribution

The Problem

Atmel produces an IEEE 802.15.4 MAC layer for its radios, which works great on Zigduino. Unfortunately, it will not work in the Arduino IDE. We cannot modify it and redistribute it, due to the license.

The Solution

Here's how we solve this. You download the MAC distribution yourself, sign up with Atmel, agree to the license, etc. Then you get ZMAC, and run the fileprep script. This will copy and modify the files as needed to organize them so the Arduino library can pick them up. It will even translate some of the examples into a form that will load and compile and run using the Arduino IDE.

Pre-requisites

Make sure you have these all in place, or this libary won't do you much good.

1. Zigduino hardware.
2. Arduino environment. Obviously, you'll need Arduino. This has been tested with 0022.
3. Zigduino modifications to Arduino environment. Make sure this is all set up properly, and you can upload the 'Blink' sketch successfully.
4. Atmel's IEEE 802.15.4 MAC distribution. This has been tested with 2.6.1.

Installing

1. Unpack this distribution where you put your Arduino libaries, e.g. C:\users\me\Documents\Arduino\libraries\ZMAC
2. Download and install gawk
3. Edit fileprep.cmd on Windows or fileprep.sh on Mac or Linux...
4. ...Update the MAC_INSTALL variable to where you installed the MAC, typically "C:\Atmel\MAC_v_2_6_1"
5. ...Update the GAWK variable to the location of the gawk binary, typically "C:\Program Files\GnuWin32\bin\gawk.exe"
6. Open a command window, cd to the ZMAC directory
7. Type "fileprep.cmd" on Windows or "./fileprep.sh" on Mac or Linux
8. Exit Arduino
9. Start Arduino
10. Select Tools > Board > Zigduino
11. Select File > Examples > ZMAC > Star_NoBeacon
12. Verify
13. Upload
14. Smile!

How you know it's working

To test the Star_NoBeacon example...

1. Upload it to two Zigduinos.
2. Only power up one of them. This will become the coordinator. Leave the other one off.
3. The first unit will search for a network (fast blinking red light), then give up and create its own (solid red light).
4. Then power on the second unit. This will become the end device.
5. The second unit will search for the first one (fast blinking red light), and then find it.
6. They will then transmit data every few seconds, indicated by a slow blinking red light, in sync between the two units.

Now the fun is just beginning

This MAC library is not particularly easy to use for beginners. It expects a crisp understanding of the principles of the IEEE 802.15.4 MAC design. There are two things to study to help understanding this:

1. 802.15.4 guides and documentation. Try This Whitepaper, and anything else you can find searching the web.
2. The user guide in the Atmel MAC. Read through the Doc/User_Guide/AVR2025_User_Guide.pdf. This is a dense guide chock full of stuff you need to know. Start with Chapter 9, which explains the sample applications in great detail.
3. Dig through the Star_Nobeacon example code. I recommend putting in "printf" debugging statements everywhere so you can keep track of what's going on.

A better solution

The next logical step to this is to create an library that's easier to use for mainstream Arduino users (e.g. beginners) that presents a higher-level layer to the user. Currently the app is expected to handle much of the details of scanning and association. This could all be pulled into the higher-level library.

This hypothetical library should enable all the functionality covered in Robert Faludi's excellent Wireless Sensor Networks book.