Atmel AVR2060 User manual

APPLICATION NOTE
Atmel AVR2060: BitCloud ZigBee Light Link Quick Start
Guide
8-bit Atmel Microcontrollers
Features
•BitCloud®ZigBee®Light Link package overview
•Instructions for getting started with the package
•Description of the Light Link demo application
•Color light and color scene controller interactions
•Source code overview
Introduction
This document describes the contents of the BitCloud ZigBee Light Link software
development kit (SDK), a software package for developing ZigBee Light Link profile
applications.
Chapter 1gives an overview of the software package and supported hardware
configuration. A getting started guide including hardware configuration, installation
and programming instructions is given in Chapter 2. Chapter 3describes how to
launch, and use the demo application.
This document is intended to be the starting point of exploring the SDK. More details
on programming for ZigBee Light Link profile are contained in [6].
42004B
−
AVR
−
08/2012

Atmel AVR2060: BitCloud ZigBee Light Link Quick Start Guide [APPLICATION NOTE]
42004B−AVR−08/2012
2
Table of Contents
1.Overview ..............................................................................................3
1.1SDK’s contents.................................................................................................. 3
1.2Supported platforms and tools .......................................................................... 3
2.Installation and getting started .............................................................4
2.1Tool chain installation........................................................................................ 4
2.2Hardware configuration ..................................................................................... 4
2.2.1Assembling devices ............................................................................ 4
2.2.2Fuse bits settings................................................................................ 5
2.3Programming..................................................................................................... 6
2.3.1Programming with IAR Embedded Workbench................................... 6
2.3.1.1Precompiled images ......................................................... 6
2.3.1.2Application workspace ...................................................... 6
2.3.2Programming with Atmel AVR Studio ................................................. 6
3.Demo application .................................................................................7
3.1Launching the demo.......................................................................................... 7
3.2Color light’s functions ........................................................................................ 7
3.2.1Touch link with a controller device ...................................................... 8
3.2.2Reset to the factory new state ............................................................ 8
3.3Color scene controller’s functions ..................................................................... 9
3.3.1Main commands ................................................................................. 9
3.3.2Reset to factory new state .................................................................. 9
3.3.3Touch link/forming a network .............................................................. 9
3.3.3.1Several color scene controllers in a network................... 10
3.3.4Controlling a light device – all commands......................................... 10
3.4Supported clusters .......................................................................................... 12
3.5Source code organization ............................................................................... 12
3.5.1IAR projects ...................................................................................... 12
4.Reference ..........................................................................................13

Atmel AVR2060: BitCloud ZigBee Light Link Quick Start Guide [APPLICATION NOTE]
42004B−AVR−08/2012
3
1. Overview
1.1 SDK’s contents
The SDK includes the BitCloud implementation of ZigBee Pro protocol and ZigBee Cluster Library, the Light Link demo
application and a set of pre-built firmware images and development tools.
The BitCloud stack included in this package contains the ZigBee Cluster Library implementation, and is very similar to
the BitCloud Profile Suite stack. However, a few enhancements are made to adjust to the behavior needed for ZigBee
Light Link profile.
Table 1-1 describes the file structure of the software package supplied with the SDK.
Table 1-1. BitCloud ZigBee Light Link SDK’s structure.
Name Location
/BitCloud/Components Header files and source code for some components (HAL,
BSP, and drivers)
/BitCloud/Components/ZCL/ZLL Header files with definitions of clusters used by Light Link
applications, and ZLL’s specific API definitions
/BitCloud/lib BitCloud compiled libraries
/Applications/ZLLDemo Demo application’s sources and projects
/Evaluation Tools/ZLLDemo Demo application’s pre-compiled images
/Documentation Documentation for this package
In addition to this document, the documentation includes the API Reference, which contains specification of functions
and times available for the user, and the developer guides.
1.2 Supported platforms and tools
Supported platforms and development tools are described in Table 1-2.
Table 1-2. System requirements for BitCloud ZigBee Light Link SDK.
Parameter Value Note
MCU/RF Atmel®ATmega128RFA1 SoC
Atmel ATmega256RFR2 SoC
Evaluation Board RCB128RFA1 for a color lightc;
RCB128RFA1 hosted on a Key
Remote Control board for a color
scene controller
Boards are available with
Atmel RF4CE-EK Evaluation Kit
JTAG emulator Atmel AVR®JTAGICE mkII or
Atmel JTAGICE 3
Required to upload firmware onto the
boards and debug through JTAG
IDE IAR Embedded Workbench®for AVR
6.11 (with IAR™ C/C++ Compiler for
AVR v6.11.1.50453)
Required to develop applications using
API and to upload firmware images
through JTAG

Atmel AVR2060: BitCloud ZigBee Light Link Quick Start Guide [APPLICATION NOTE]
42004B−AVR−08/2012
4
2. Installation and getting started
2.1 Tool chain installation
•Install IAR Embedded Workbench for AVR [7], if not already installed on your PC
•Add a Windows®environment variable named IAR_AVR_HOME, and set its value to the IAR Embedded
Workbench installation directory (for a default installation, it is C:\Program Files\IAR
Systems\Embedded Workbench 6.11). To do this:
•Go to Control Panel > System > Advanced > Environment Variables
•Click New below the System variables list, and enter Variable Name and Variable Value
This step is required if you plan to build embedded images using IAR Embedded Workbench from the command
line.
More details on tool chains used with BitCloud may be found in [3] or [4].
2.2 Hardware configuration
2.2.1 Assembling devices
Both color scene controller and color light use RCB128RFA1 (RCB) as a base board. For a color scene controller an
RCB board shall be attached to a Key Remote Control board. A color light may either use an RCB board with a Key
Remote Control board (in this case its LCD screen is used to project the color light’s state) or use an RCB board alone
(in this case its LEDs are used to indicate the color light’s state).
To assemble a device:
1. Attach an antenna to the SMA connector on the RCB board.
2. Insert two AAA batteries into the RCB board.
3. For a color scene controller and for a color light to project its state to the LCD screen, attach an RCB board on
top of a Key Remote Control board.
4. Power on the device by shifting the red button at the right side of the RCB board (see Figure 2-1).
Figure 2-1. Assembled RCB hosted on a Key Remote Control board.

Atmel AVR2060: BitCloud ZigBee Light Link Quick Start Guide [APPLICATION NOTE]
42004B−AVR−08/2012
5
5. To use UART output, attach the serial cable, connected to a PC, to the port marked EXT on a Key Remote
Control board as shown on Figure 2-2.
Terminal program configuration should be BAUD RATE: 38400; PARITY: None; DATA BITS: 8; STOP BITS: 1;
FLOW CONTROL: Off.
Figure 2-2. Serial cable attached to a Key Remote Control board.
For more details on using RCB and Key Remote Control boards refer to [5].
2.2.2 Fuse bits settings
The recommended fuse bits settings are shown in Table 2-1.
Table 2-1. Fuse bits for Atmel ATmega128RFA1.
Option Required value (for 8MHz) Required value (for 16MHz)
BODLEVEL 1V8 1V8
OCDEN Enabled Enabled
JTAGEN Enabled Enabled
SPIEN Enabled Enabled
WDTON Disabled Disabled
EESAVE Disabled Disabled
BOOTSZ Boot Flash size=2048 words
start address=$F800
Boot Flash size=2048 words
start address=$F800
BOOTRST Disabled Disabled
CKDIV8 Enabled Enabled
CKOUT Disabled Disabled
SUT_CKSEL Int. RC osc.;
Startup time: 6 CK + 65ms
Transceiver Oscillator;
Starup time 16K CK + 65ms
Resulting bytes
Ext 0xFE 0xFE
High 0x1B 0x1B
Low 0x62 0x77
To quickly test the demo application you may use pre-built application images located in the Evaluation Tools
directory.

Atmel AVR2060: BitCloud ZigBee Light Link Quick Start Guide [APPLICATION NOTE]
42004B−AVR−08/2012
6
2.3 Programming
2.3.1 Programming with IAR Embedded Workbench
2.3.1.1 Precompiled images
When using IAR Embedded Workbench to program precompiled images provided with the SDK, the user first needs to
create a project containing the precompiled image.
1. Start IAR Embedded Workbench for AVR.
2. Select File > New > Workspace.
3. Select Project > Create New Project…
4. In the Create New Project dialog, select Externally build executable in Project templates:
5. Select a name for the project, and click Save.
6. Follow the instructions in readme.txt.
7. Once the project is set up, select Project > Options.
8. In the General options category, set Processor Configuration to –cpu=xm256a3, ATmega128RFA1.
9. Click OK.
10. Select JTAGICE mkII >Fuse Handler (JTAGICE 3 > Fuse Handler).
11. Click Read Fuses, and make sure that the device fuses are set as specified in Section 2.2.2.
12. If fuses are set incorrectly, select the correct fuse settings, and click Program fuses.
13. Select Project > Download and debug.
14. Once the debugging session has started, click Stop debugging.
The image is now installed on the board.
2.3.1.2 Application workspace
1. Double-click on a workspace (for example, ZLLDemo.eww), and select JTAGICE mkII > Fuse Handler
(JTAGICE 3>Fuse Handler).
2. Click Read Fuses, and make sure that the device fuses are set as specified in Section 2.2.2.
3. If fuses are set incorrectly, select the correct fuse settings, and click Program fuses.
4. Select the desired application configuration from the drop-down box in the Workspace pane.
5. Select Project > Download and debug.
6. Once the debugging session has started, click Stop debugging.
The image is now installed on the board.
Note: Using a JTAG to program the microcontroller will erase the embedded bootloader, if present. As a result, loading of
application images with Serial Bootloader will become inoperable until the embedded bootloader is loaded to Atmel
ATmega128RFA1 again.
2.3.2 Programming with Atmel AVR Studio
1. In AVR Studio®, open the Tools > Program AVR > Connect… dialog.
2. Choose Atmel AVR JTAGICE mkII (JTAGICE 3) for Platform: and USB for Port:, and click Connect…
3. Select the right device in the Device and Signature Bytes field on the Main tab of the programming dialogue.
4. Click on the Fuses tab and make sure that the device fuses are set as specified in Section 2.2.2.
5. If fuses are set incorrectly, select the correct fuse settings, and click Program.
6. Click on the Program tab.
7. In the Flash section of the dialog, select the precompiled .hex file to be programmed.
8. Click Program.
The image is now installed on the board.

Atmel AVR2060: BitCloud ZigBee Light Link Quick Start Guide [APPLICATION NOTE]
42004B−AVR−08/2012
7
3. Demo application
The reference application involves color light devices and color scene controller devices, which are both defined in the
ZigBee Light Link Profile specification [1]. Both types of devices are emulated by Key Remote Control boards.
The application demonstrates controlling color lights by color scene controllers. All main features of the ZigBee Light
Link profile are implemented:
•A ZigBee Light Link network has no coordinator
•Touchlink commissioning – network parameters are transferred to a new light from a scene controller, while
the scene controller is kept close to the light
•Lights are ZigBee routers to propagate messages across the network
•Multiple scene controllers may be used to control same or different sets of lights
•Application data and network parameters are saved to non-volatile memory to restore the state after reset,
power off, etc.
•Light control functionality, including On/Off, Level (brightness), Color (Hue, Saturation), Groups, and Scenes
To use the demo application, at least one device should be programmed with a color light application’s firmware image,
and one device should be programmed with a color scene controller application’s firmware image.
3.1 Launching the demo
To launch the demo one color scene controller and one color light are needed. More devices (lights or controllers) may
be added as required.
•Assemble devices as described in Section 2.2.1
•Program devices with pre-built images of the demo application via JTAG (as described in Section 2.3). The
pre-built images are located in the \Evaluation Tools\ZLLDemo directory. Image files are used in the
following way:
•ZLLDemo_<SoC>_Light_LCD.hex – for a color light based on RCB mounted on a Key Remote
Control board
•ZLLDemo_<SoC>_Light_LED.hex – for a color light based on a sole RCB board
•ZLLDemo_<SoC>_Remote.hex – for a color scene controller
<SoC> is either ATmega128RFA1 or ATmega256RFR2
•Power on the devices
•Perform a touchlink procedure between the color light and the color scene controller by holding the PWR
button on the controller’s Key Remote, to form a network
•Use color scene controller’s buttons to control the color light (see Section 3.3)
Optionally:
•RCBs placed onto Key Remote Control boards may be connected to a PC via UART to observe information
about sent and received commands in a terminal program on the PC. UART set up is described in Step 5 in
Section 2.2.1.In the application’s source code UART is configured in
\Applications\ZLLDemo\common\src\debug.c
•More color light devices and color scene controller devices may be added through touchlink with the controller
device that is already in the network
3.2 Color light’s functions
A color light device indicates its light status via LEDs on the RCB board or via the LCD screen on the Key Remote
Control board if RCB is attached to the Key Remote Control board.

Atmel AVR2060: BitCloud ZigBee Light Link Quick Start Guide [APPLICATION NOTE]
42004B−AVR−08/2012
8
RCB board’s LEDs are turned on when light is on and turned off when light is off. When the color light’s color level
changes LEDs brightness also changes. When a color light receives an identify command from a controller LEDs start
blinking.
Figure 3-1 below describes functions of a color light’s LCD screen:
Figure 3-1. Color light’s screen on a Key Remote Control board.
Once a factory new color light is powered on, it starts standard ZigBee scanning and displays Scanning 1st...
(indicating that the device is doing ZigBee scan over primary ZLL channels), then Scanning 2nd... (indicating
ZigBee scan over secondary ZLL channels) as the current status. When Listening... is output to the screen the
color light is ready for touch link.
3.2.1 Touch link with a controller device
For touch link a color scene controller is brought closely (10-20cm range) to a color light and the PWR button is pressed
on the color scene controller for more than three seconds. The color scene remote sends an identify command to the
color light, which blinks several times with its LEDs or the LCD screen. The touch link procedure may be aborted at this
moment, if the PWR button is released. To complete the procedure the user should wait for three seconds.
If touch link is a success, the color light’s screen shows NFN Running... status (where NFN stands for Non Factory
New).
After that the color light can be controlled by commands sent from the color scene controller.
3.2.2 Reset to the factory new state
There are two ways to reset a color light device to the factory new state: sending a command from a color scene
controller and using the PWR button if the color light is assembled with a Key Remote Control board.
To trigger reset of a color light to factory new:
•Select the target color light using the SEL button on the color scene controller
•Hold R1, R2 and PWR buttons, altogether, on the color scene controller for three seconds
A color light assembled with a Key Remote Control board may be reset to the factory new state in the following way:
•Switch off the device by shifting back the red button at the right side of the RCB board
•While holding the PWR button on the color light device, switch it on by shifting the RCB’s red button. Wait for
three seconds and then release the PWR button

Atmel AVR2060: BitCloud ZigBee Light Link Quick Start Guide [APPLICATION NOTE]
42004B−AVR−08/2012
9
3.3 Color scene controller’s functions
3.3.1 Main commands
Table 3-1 lists buttons for the main color scene controller’s commands. See the scheme of the Key Remote board with
all available commands in Figure 3-2.
Table 3-1. Biuttons for executing most frequent commands.
Button(s) Effect
PWR Press and hold for three seconds to perform touch link
PWR + R Press and hold for three seconds to perform classical ZigBee scanning
PWR + R Press and hold for three seconds to reset device to factory new state
PWR + R+ + R- Reset a color light to the factory new state. The target color light should be selected using the
SEL button; otherwise all color lights present in the network will be reset to the factory new state
L+/L- Color light’s on/off
Up/Down Increase/decrease light level
Left/Right Increase/decrease saturation
Colored buttons
Set the corresponding color using the following values:
Red: hue = 60000 or x = 40000, y = 20000
Green: hue = 30000 or x = 10000, y = 40000
Yellow: hue = 15000 or x = 30000, y = 30000
Blue: hue = 45000 or x = 10000, y = 10000
SEL
Select the next bound device and requests it to identify itself. This allows sending unicast
commands to a single device. Groupcast mode will be entered automatically after five seconds
of inactivity.
1/2/3 Store Scene if pressed for more than three seconds and Recall scene if pressed for less that
three seconds
7/8/9 Set minimum/middle/maximum light level
4
Triggers network update: the color scene controller applies a standard ZigBee mechanism to
select a new operating channel for the network and broadcasts a command to update the
channel on all other devices
The SEL button may be used to select a color light. When this button is pressed and released, the next color light
becomes active, which means that all commands initiated by the user are sent to this color light in a unicast manner,
until no additional commands are sent for a five second period.
3.3.2 Reset to factory new state
To reset a scene controller device to the factory new state, press the PWR button while holding the R- button and wait
for three seconds. The LED located at the bottom of the RCB board will blink once to indicate that the device has been
reset to the factory new state.
3.3.3 Touch link/forming a network
For touch link a color scene controller is brought close to a new color light, which is not in the network yet. By pressing
the PWR button on a color scene controller, the user initiates a commissioning procedure, where the goal is to transfer
network parameters to the color light. At this moment the devices are not yet in the network, but the communication is
possible, because it happens on the MAC level without a need for routing.
The color light receives network parameters and starts the network as a router (the adjustments in the BitCloud stack
allow this). Once the network is started, the color scene controller joins this network as an end device.

Atmel AVR2060: BitCloud ZigBee Light Link Quick Start Guide [APPLICATION NOTE]
42004B−AVR−08/2012
10
After the first color light is commissioned, the color scene controller may be brought to the second color light, where
after, receiving the network parameters, it will not start the network once again, but will join the existing network as
another router. The subsequent color lights are commissioned in the same way.
3.3.3.1 Several color scene controllers in a network
A Light Link network may contain more than one color scene controller. Additional controller devices are added using
touch link, which happens between two color scene controllers:
•Bring a factory new color scene controller to a color scene controller that is already in the network, and press
the PWR button on both devices for more than three seconds
•Perform touch link between the new color scene controller and each of the color lights
•Use any of the controller devices to manipulate color lights
Note: If touch link between controller devices is not performed, pairing a new controller device with a color light that is
already in the network, will cause the color light to leaving this network, and form a new one.
3.3.4 Controlling a light device – all commands
Figure 3-2 on the next page depicts the key remote board’s keyboard and all commands that can be sent with the
buttons from the color scene controller.
Each button may be used to send up to four commands. What command is sent by pressing a button, depends on
whether buttons R+ and R- are also pressed or not as shown in Table 3-2.
Table 3-2. Alternating a command by holding R+ and R- buttons.
Number of command R+ and R- buttons state
First command Both are not pressed
Second command R+ is pressed, R- is not pressed
Third command R+ is not pressed, R- is pressed
Fourth command Both are pressed
For example, to send a Toggle command press the L+ button while holding both the R+ and R- buttons pressed.
For buttons 1, 2, and 3: if a button is pressed for more than three seconds (when both R+ and R- are not pressed) a
Store Scene command is sent; if a button is pressed for less than three seconds a Recall Scene command is sent.