Networked Embedded Systems. Development Guide

Networked Embedded Systems Development Guide Robert Leidenfrost Martin Biely Vienna, May, 2008

Contents 1 The ZigBee Protocol 1 1.1 ZigBee Architecture.............................. 1 1.2 ZigBee Components.............................. 1 1.3 Network Topologies.............................. 3 1.4 IEEE 802.15.4 PHY.............................. 4 1.5 IEEE 802.15.4 MAC............................. 5 2 Build Environment 11 2.1 Tool Chain.................................. 11 2.1.1 Avr-gcc................................ 11 2.1.2 Avrdude................................ 11 3 Workspace Setup 13 3.1 Directory Structure.............................. 13 3.1.1 lib................................... 13 3.1.2 doc................................... 15 3.1.3 urb template............................. 16 3.1.4 packet capture............................ 16 3.1.5 simul urb template.......................... 16 3.2 Setup your Workspace............................ 17 3.3 Makefile Targets................................ 18 4 The Simulator 19 5 Programming Guidelines 20 List of Figures 21 List of Tables 22 i

List of Acronyms 23 Bibliography 25 ii

1 The ZigBee Protocol ZigBee [All06] is a standard for Low-rate Wireless Personal Area Network (LR-WPAN)s and has been ratified in late 2004 under IEEE 802.15.4 Wireless Networking Standard. The reason for this development was, that other wireless standards were not suitable for building automation and industrial control, because they needed lower cost, better latency, and lower power consumption [EP03]. The ZigBee protocol is similar to Bluetooth but simpler, has a lower data rate and a very low power consumption. Thus, these characteristics make it possible that a node on a ZigBee network should be able to run several months to two years on just two AA batteries and therefore is best suited for embedded applications in consumer electronics, home and building automation, industrial control, sensor networks, and many others. 1.1 ZigBee Architecture The ZigBee architecture is based on the standard Open System Interconnection (OSI) seven-layer model, but defines only the relevant layers. ZigBee specifies the application and Network (NWK) layer and builds on the Physical (PHY) layer containing the radio frequency (RF) transceiver and the Media Access Control (MAC) layer from the IEEE 802.15.4-2003 [IEE03] standard. The purpose is, that devices from different vendors based on this standard will enable interoperable, low-cost, and highly usable products. The application layer is comprised of the Application Support (APS) sublayer, the Application Framework (AF) profile, the ZigBee Device Object (ZDO)s, and the manufacturer-defined application objects. A simplified relation between these layers is depicted in the Figure 1.1. 1.2 ZigBee Components A ZigBee System is composed of a number of components which have different features. Because of different constraints regarding implementation costs, memory requirements, and other hardware resources, the ZigBee Physical Device type based on IEEE 802.15.4 is distinguished in three Logical Device types. Generally, IEEE 802.15.4 provides the implementation of two different Physical Device types. The first one is the Full-function Device (FFD) and the second type is the Reduced-function Device (RFD). Every IEEE 802.15.4 network requires at least one FFD, which acts as a network coordinator. As listed in the Table 1.1 below, an RFD is implemented with minimum resources and therefore improves power consumption and reduces implementation size and costs [Kin03]. In contrast to FFDs which can also serve as a link coordinator and is generally line powered, an RFD component is usually 1

1.2. ZIGBEE COMPONENTS CHAPTER 1. THE ZIGBEE PROTOCOL Figure 1.1: ZigBee architecture. battery-powered and can only talk to an FFD. Reduced Function Device Limited to star topology Can only talk to an FFD Can not become a network coordinator Very simple implementation Full Function Device Can function in any topology Can talk to RFDs and FFDs Can become a network coordinator Can become a coordinator. Table 1.1: ZigBee physical device types. As mentioned above, ZigBee distinguishes the Physical Device types (RFD or FFD) into three different Logical Device types, which are described in the following paragraphs: ZigBee Coordinator (ZC). Every network must contain exactly one ZC which is responsible for starting the network and therefore for initiating and maintaining the devices. The coordinator selects the frequency to be used by the network and associates the devices with a logical address. It also provides message routing, security management, and other services. Only an FFD can be a Personal Area Network (PAN) coordinator. ZigBee Router (ZR). ZigBee Router (ZR)s are used for moving data and control messages through the network using a hierarchical routing strategy and thus can act as an intermediate router. They are used to extend a network or to combine several ZigBee clusters. Only an FFD can be a ZR. ZigBee End Device (ZED). The end devices directly communicate with a ZigBee coordinator and are used for applications which do not need to send large amounts of 2

1.3. NETWORK TOPOLOGIES CHAPTER 1. THE ZIGBEE PROTOCOL data. They have a reduced functionality and therefore minimizes memory requirements and simplifies the implementation. Both FFDs and RFDs can act as a ZED. 1.3 Network Topologies ZigBee s network layer supports three network topologies which are pictured in the Figure 1.2. Figure 1.2: Topology models. Star Topology. This network topology contains exactly one ZigBee coordinator, which establishes the connection between several ZEDs. In contrast to the coordinator, the end devices are usually battery-powered. Hence, this topology may be used in applications with constraints on power consumption such as home automation, toys and games, or personal computer peripherals. During each start of the coordinator and therefore of a network, the coordinator scans for other networks and then chooses a PAN identifier which is not currently used by others. Thus, although several star topologies may be in the radio range of each other, they are able to operate independently. Mesh Topology. The mesh topology, also known as peer-to-peer topology, improves reliability and scalability by multi-path routing and therefore can be ad-hoc, self-organizing, and self-healing. It contains again a single ZigBee coordinator and typically allows full peer-to-peer communication. Moreover, messages can also be routed through multiple hops which makes this topology appropriate for wireless sensor networks. Other applications that benefit from this may be industrial control and monitoring, or asset and inventory tracking. In such a topology, the ZigBee coordinator is responsible for starting the network. The network extension is therefore done through the use of ZRs and ZEDs. Cluster Tree Topology A cluster tree topology usually consists a number of FFDs which build up a tree topology wheres a single ZigBee coordinator forms the root of this 3

1.4. IEEE 802.15.4 PHY CHAPTER 1. THE ZIGBEE PROTOCOL tree. Moreover, every FFD may be connected together with several ZRs or ZEDs and thus forms a cluster. In other words, the end devices correspond to the leaves of the cluster tree. In addition to that, every router can provide synchronization service to the neighboring devices. Because the ZigBee coordinator forms the first cluster, it is also named Cluster Head (CLH) and provides a Cluster Identifier (CID), an unused PAN identifier, and the broadcasting of beacon frames. A CLH may add neighboring devices and can instruct a ZigBee router to become the CLH of a new cluster. This enables an increased coverage area at the cost of communication latency. 1.4 IEEE 802.15.4 PHY According to [GNC + 01, CGH + 02], the physical layer of IEEE 802.15.4 offers two PHY options: The 2.4 GHz PHY and the 868/915 MHz PHY. Both are based on direct sequence spread spectrum (DSSS) methods and share the same packet structure. This allows a simpler and cheaper IC implementation. The 2.4 GHz PHY operates in the 2.4 GHz ISM band and therefore offers nearly worldwide availability. However, many other standards have also chosen this band and thus may be affected by the interaction of incompatible services operating in the same band. Because many LR-WPAN applications are not based on mobility, the IEEE 802.15.4 task group has also added a second PHY option which is a combination of the 868 MHz band in Europe, the 902 MHz band in Australia, and the 915 MHz band in the United States. The close frequency relation of these bands makes the use of similar hardware possible and thus lowers the production costs. Other advantages of the second PHY option are lower power consumption and the avoidance of the interference problem in the 2.4 GHz ISM band. Packet structure. As mentioned above, both PHYs share the same packet structure as depicted in Figure 1.3. A packet at the physical layer is named Physical Protocol Data Unit (PPDU) and contains a preamble, a start of packet delimiter, a PHY header and the PHY Service Data Init (PSDU). The preamble together with the delimiter forms a synchronization header and the PHY header indicates the packet length. Because only seven bits are used to specify the payload length in bytes, a PSDU can have a maximum length of 127 bytes. Therefore, the maximum possible packet duration are 53.2 ms for the 868 MHz band, 26.6 ms for the 915 MHz band, and 4.25 ms for the 2.4 GHz band. Sensitivity and range. In order to support low-cost implementation, the IEEE 802.15.4 standard specifies a receiver sensitivity of 85 dbm for 2.4 GHz and 92 dbm for 868/915 MHz PHY. However, the achievable range does not only depend on the receiver s sensitivity, but also on the sender s transmitting power. Therefore, the standard also specifies to transmit at least 1 mw. Another important aspect is the control of the transmitting power, because this could improve reliability and power consumption. For instance, the quality of the transmission is continuously observed and the transmitter 4

1.5. IEEE 802.15.4 MAC CHAPTER 1. THE ZIGBEE PROTOCOL PHY protocol data unit (PPDU) PHY layer Synchronization header Preamble 4 byte Start of packet delimiter PHY header PHY service data unit (PSDU) 1byte 1byte < 128 byte Figure 1.3: IEEE 802.15.4 PHY packet structure. power is reduced as far as possible, so that the receiver can still hear the sender. Thus, this reduces the problem with interfering networks operating in the same frequency channel. Furthermore, a transmitting power of 1 mw allows a radio range of about 10 to 20 metres but can be up to 100 metres. 1.5 IEEE 802.15.4 MAC According to [IEE90], the IEEE 802 group has split the data link layer into two sub layers, the MAC layer and the Logical Link Control (LLC) layer. The data link layer usually provides functionalists to transfer data between several network entities. Furthermore, it is responsible for error detection and correction that may occur in the physical layer. The LLC is standardized in [IEE98] and usually provides flow control, acknowledgement, and error recovery. Compared to LLC, the MAC layer is closer to the hardware and determines who is allowed to access the medium. As shown in [IEE03], the IEEE 802.15.4 MAC sublayer is responsible for the following tasks: ˆ Association and disassociation ˆ Acknowledged frame delivery ˆ Channel access mechanisms ˆ Frame validation ˆ Guaranteed time slot management ˆ Beacon management ˆ Security management The MAC sublayer provides two services to the upper layers, which can be accessed through two Service Access Point (SAP)s: The MAC data service and the MAC management service. The MAC data service is responsible for the reception and transmission of MAC Protocol Data Units (MPDU)s and the MAC management service provides several service primitives to handle the above mentioned tasks. 5

1.5. IEEE 802.15.4 MAC CHAPTER 1. THE ZIGBEE PROTOCOL The general MAC frame format. The MAC frame is named MPDU and is enclosed in the PSDU. An MPDU frame has a maximum packet size of 127 bytes and is composed of the MAC Header (MHR), the MAC Service Data Unit (MSDU), and the MAC Footer (MFR). Regarding to the Figure 1.4, the MHR contains a frame control field, a sequence number field, and an address information field. The control field indicates the type of MAC frame (e.g. beacon frame, data frame, acknowledgment frame, MAC command frame) and further specifies the format of the address field, i.e., 16 bit short address or 64 bit extended address. Therefore, the size of the address field may vary. The sequence number is used for the acknowledgment to provide a reliable link and the Frame Check Sequence (FCS) field helps verify the integrity of the MAC frame via 16-bit ITU-T Cyclic Redundancy Check (CRC). Consequently, 102 bytes are left for the MSDU and can be used for user data in the upper layers. The 64 bit extended address is long enough to assign every device in the world a unique number. But if the communication is only based on this address type, then this will result in much overhead and is not beneficial. Because a PAN comprises by far fewer devices than can be addressed via 64 bit, the short address type was introduced and enables a maximum amount of 65536 participants. The short address will be assigned from the PAN coordinator through the association process. PHY protocol data unit (PPDU) PHY layer Synchronization header Preamble 4 byte Start of packet delimiter PHY header Frame length PHY service data unit (PSDU) MPDU 1byte 1byte < 128 byte MAC sublayer Frame control MAC header (MHR) MAC service data unit (MSDU) MAC footer Sequence number Address Information Data Payload FCS 2 byte 1 byte 0... 20 byte n byte 2 byte Figure 1.4: The IEEE 802.15.4 MAC frame format. Channel access mechanisms. The MAC standard uses two types of channel access mechanisms which depend on the use of beacons. Both are based on the Carrier Sense Multiple Access with Collision Avoidance (CSMA/CA) medium access mechanism and therefore are contention based. The only difference is that the first mechanism uses an unslotted variant and the second one a slotted variant of CSMA/CA. Networks with beacons use the slotted CSMA/CA mechanism and are usually deployed in low-latency devices, but a device can also choose not to use beacons for normal transfer and thus use the unslotted variant. 6

1.5. IEEE 802.15.4 MAC CHAPTER 1. THE ZIGBEE PROTOCOL Super frame structure. To take advantage of the beacon scheme, IEEE 802.15.4 has the option to use a super frame structure which allows the PAN coordinator to allocate time-slots to devices with time critical data. The super frame structure is bounded by super frame beacons which are transmitted in predetermined intervals by the coordinator. These intervals are divided into 16 equally sized slots, while the first slot of each super frame contains a special beacon frame. This beacon frame describes the structure of the super frame. The interval between two super frame beacons can be 15 ms up to 245 s. A super frame can also have an active and an inactive portion which can be used to save energy. In the active period each device can transmit at any time during a slot, but must finish before the next super frame beacon. The channel access mechanism in each slot is based on the slotted CSMA/CA strategy. For this reason the active period is also called Contention Access Period (CAP). However, some applications may require guaranteed bandwidth for dedicated devices. For this reason, the standard also supports the use of Guaranteed Time Slot (GTS)s at the end of each active super frame. This results in a contention-free channel access mechanism. The portions used for GTSs together form a Contention Free Period (CFP). This mechanism is visualized in Figure 1.5. It should be noted that a contention based transmission should end before the start of a CFP. Beacon Beacon GTS GTS inactive 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 Contention Access Period Contention Free Period Figure 1.5: Super frame structure with GTSs. CSMA/CA. In networks which does not use beacons, IEEE 802.15.4 determines the use of a contention-based channel access mechanism named CSMA/CA. The behaviour of the CSMA/CA algorithm is generally described with three parameters: The Number of Backoff Periods (NB), the Contention Window (CW) length, and the Backoff Exponent (BE). NB is initialized to 0 before a new transmission attempts and is incremented each time a back off was required while attempting this transmission. The CW length is defined in number of back off periods. A transmission will only be started if the channel is clear during the contention window. The CW is only used in the slotted variant of the CSMA/CA algorithm. BE is the back off exponent and defines the number of back off periods a device has to wait before a channel assessment can be started. The MAC layer features different variables for the implemented CSMA/CA mechanism, i.e., the Minimum Backoff Exponent (macminbe) and the Maximum Backoff Exponent (macmaxcsmabackoffs). 7

1.5. IEEE 802.15.4 MAC CHAPTER 1. THE ZIGBEE PROTOCOL macminbe defines the minimum number of back off exponents and macmaxcsmabackoffs declares the maximum value of the back off exponent before the algorithm will terminate with a channel access failure. Furthermore if macminbe is set to 0, no collision avoidance will be performed during the first iteration of the algorithm. Although the receiver is enabled during the channel assessment, the device discards any received frame. If a frame should be sent, the algorithm first waits for a random time determined by a random number of back off periods from 0 to 2 BE 1 and then performs a Clear Channel Assessment (CCA). In the case the channel is free, the transmission will be started. Otherwise if the channel is assessed to be busy, both NB and BE are incremented by one. If the value of NB is less than or equal macmaxcsmabackoffs, then the algorithm waits again for a random time. Otherwise, if NB is greater than macmaxcsmabackoffs, then the algorithm terminates with a channel access failure. Data transfer model. The MAC sublayer from IEEE 802.15.4 distinguishes three types of data transfer: The data transfer to a coordinator, the data transfer from a coordinator, and the peer-to-peer data transfer. In contrast to a star topology, a peer-to-peer topology may use all three transactions whereas a star topology will not make use of the peer-toper data transfer model. It should be noted that the transfer mechanisms also depend on the use of beacons. Data transfer to a coordinator. This scheme is used to transfer data from a device to the coordinator. In case of a network with the use of beacons, the device must first wait for a network beacon. If so, the device transmits its data frame using the slotted version of CSMA/CA. Afterwards, if the coordinator successfully received the frame, it sends an optional acknowledgment. The mechanism for a network without the use of beacons is similar, but with the addition that the device uses slotted CSMA/CA and it does not have to listen for a beacon before transmitting the data. Both principles are shown in Figure 1.6. Data transfer from a coordinator. If a device requests data from the coordinator, then this mechanism will be applied. In a network using beacons, the coordinator must first indicate in a beacon that it is ready to send data to a device. Therefore, the device listens to the medium and if it receives such a beacon, then the device responds with a data request packet. Afterwards, the coordinator is allowed to send the pending message. In addition to that, all transactions are acknowledged. By contrast, a network without beacons uses unslotted CSMA/CA and the coordinator stores all messages and continuously waits for a data request from a device without any beacon messages. The transfer model for both variants is depicted in Figure 1.7. Peer-to-peer data transfer. This model is used if a device in a network wants to communicate with each other and can be either performed by synchronized or an un- 8

1.5. IEEE 802.15.4 MAC CHAPTER 1. THE ZIGBEE PROTOCOL seq: data transfer to a coordinator Coordinator Network Device opt [beacon-enabled network] Beacon Data opt Acknowledgment Figure 1.6: Communication to a coordinator. synchronized scheme. If no synchronization is performed, then the devices continuously receive messages based on unslotted CSMA/CA. The synchronized scheme is not provided in the standard and may be implemented by the upper layers. Robustness. The LR-WPAN standard supports some mechanisms to ensure robustness in communication. Theses mechanisms are the CSMA/CA scheme, frame acknowledgment, and data verification via a CRC strategy. Security. The security mechanism in this standard includes the ability to maintain an Access Control List (ACL) and the use of symmetric cryptography to protect transmitted frames. The ability to use these functions are determined at the upper layers. 9

1.5. IEEE 802.15.4 MAC CHAPTER 1. THE ZIGBEE PROTOCOL seq: data transfer from a coordinator Coordinator Network Device opt [beacon-enabled network] Beacon Data Request Acknowledgment Data Acknowledgment Figure 1.7: Communication from a coordinator. 10

2 Build Environment 2.1 Tool Chain In order to be able to compile and program the Atmel ZigBee nodes, it is advantageously to use the latest libraries of avr-gcc and avrdude. 2.1.1 Avr-gcc The avr-gcc compiler is necessary to compile your program for a specific target, in our case the atmega1281 target. You have to make sure that your avr-gcc, avr-libc and avr-binutils all support atmega1281. 1 Usually, the avr- packages for several Linux distributions (e.g., Ubuntu) are not new enough or not compiled to support atmega128. Thus it might be necessary to compile your own avr-toolchain (if you want to work at home). The steps for compiling your own avr-toolchain can be found on several websites 2. The order in which you build and install the tools is important! 2.1.2 Avrdude Avrdude is the programmer, which supports several interfaces. In our case, we use the standard USB-avrisp programmer. Therefore, make sure that your computer correctly recognizes your programmer. For instance, if you call lsusb in your command line, you should get something similar like this: Bus 005 Device 001: ID 0000:0000 Bus 003 Device 004: ID 046d:c510 Logitech, Inc. Bus 003 Device 001: ID 0000:0000 Bus 004 Device 002: ID 0483:2016 SGS Thomson Microelectronics Fingerprint Reader Bus 004 Device 001: ID 0000:0000 Bus 001 Device 002: ID 03eb:2104 Atmel Corp. Bus 001 Device 001: ID 0000:0000 Bus 002 Device 001: ID 0000:0000 It is important that the Atmel Corp. occurs in the list. Otherwise you will have to check your connection and maybe if you have the latest libusb library installed. You can also debug with the program dmesg if your system has correctly initialized the 1 In the lab the versions are 4.1.2, 1.4.6 and 2.18 respectively. 2 Look at http://www.roboternetz.de/wissen/index.php/avr-gcc und avrdude installieren or http://www.nongnu.org/avr-libc/user-manual/install tools.html. 11

2.1. TOOL CHAIN CHAPTER 2. BUILD ENVIRONMENT programmer. It is also possible that you encounter problems during the programming although your system has recognized the programmer. This may come from the fact that you have no permissions on the USB-port. So check if you have full access. Now assume that you have correctly compiled your source files and you would like to program the target. In our case, this is done via the makefile by the command make program. However, to get some background knowledge, this calls the following command: avrdude -p atmega1281 -P usb -c avrispv2 -e -U flash:w:build/project.hex Note that the -U flash:w:build/project.hex flag tells the programmer on which memory type it should operate. Should uploading your program take extraordinarily long (more than a minute) the reason is probably that the frequency of the SCK signal (the clock signal used for programming) is too low. This can be corrected by executing: avrdude -p m48 -P usb -c avrispmkii -tuf and then entering sck 5 on the command line. After leaving the avrdude s terminal mode your programming speed should have increased. 12

3 Workspace Setup 3.1 Directory Structure If you unpack the provided template project, you will encounter the following directory structure (Figure 3.1): Figure 3.1: The directory structure of the template project. Since we distribute the documentation separately, so your actual setup may look different when you do not unpack the documentation inside the project tree. 3.1.1 lib The lib-directory contains the static libraries, which support the complete 802.15.4 MAC- Stack and some further layers. libl2 rdk230 rel.a This static library is the original MAC-library from Atmel (with some modifications to support the promiscuous mode). In the course, you will not need this library, since it does not support reliable broadcast communication. Note that this implementation needs about 4K of the RAM-Memory. libpptp rdk230.a This library is based upon the Atmel s MAC-Stack. However, it additionally supports a perfect point-to-point layer with loopback mode. Therefore, this layer provides the following functions: bool pptp send(uint16 t panid, uint16 t addr, uint8 t *buffer, uint8 t size) The panid variable identifies the personal area network identifier and should be the same for all devices in your broadcast domain. The addr parameter defines the 16-bit short-address of the target device. The buffer is a pointer to an 8-bit array of the size size, which represents the message to be sent. The function returns a boolean, which is true, if the target correctly received and acknowledged the data packet and false, if problems occurred during the communication. 13

3.1. DIRECTORY STRUCTURE CHAPTER 3. WORKSPACE SETUP extern void usr pptp recv callback(uint16 t addr, uint8 t *buffer, uint8 t size) This is a callback function and should be implemented in the application layer. Otherwise the linker will encounter problems. This function is called from the system function pptp recv task(), which should be called as often as possible in the application layer. Hence, this function is not called in an interrupt context. Note that this layer implements its own buffer and consumes additionally at least 1K to the 4K of the Atmel s MAC-Stack. Sure, the number of supported devices was already limited to 5. So be careful how much devices your application should support. If you need more devices, you can change this in the header file pptp.h with the macro PPTP MAX DEVICECOUNT, but be sure that, after a new compilation, your library does not cause a memory overrun. Similarly to the implementation of the MAC-layer, the PPTP-layer uses its own buffer for sending and receiving messages. In more detail, the PPTP layer implements the interrupt driven receiver-callback function from the MAC-layer. However, the continuous execution of the pptp recv task() decouples the PPTP receiver callback function from the interrupt context by checking this buffer for new messages. If new messages are available, the pptp recv task() calls the pptp-specific callback function, which must be implemented in the next upper layer (or in the case of no further layers, in the application layer). As a result, all received messages are delivered to the next layer which may implement a similar buffer structure. The addr parameter is again a 16-bit short-address, which defines the sender. The buffer and size parameter again define the message to be sent. void pptp recv task(void) This is an important system function and should be periodically called as often as possible, because it processes all the messages in the buffer. libbeb rdk230.a This library is based upon the PPTP-Layer mentioned above. It additionally implements a best-effort broadcast service. Therefore, this layer provides the following functions: bool beb register device(uint16 t panid, uint16 t short address) This function registers a device into the broadcast domain. This is necessary, because the transmission is done over the PPTP-layer and thus the BEB layer must have knowledge of all devices in the broadcast domain. Initially, the PPTP-layer supports at most 5 devices. So be sure, that you do not register more. The panid variable identifies the personal area network identifier and should be the same for all devices in your broadcast domain. The short address parameter defines the 16-bit short-address of the target device. The functions returns a boolean, which is true, if the target was correctly registered and otherwise false if for instance the register-buffer is full. Registered devices can also be unregistered through the beb remove device function. 14

3.1. DIRECTORY STRUCTURE CHAPTER 3. WORKSPACE SETUP void beb send(uint8 t *buffer, uint8 t size) This function triggers a send-call in the PPTP-layer and thus takes the same parameter list. However, since the beb-layer has already knowledge of all devices in the broadcast domain, you do not need to pass the PAN-ID and the 16-bit short-address. The buffer and size variable again define the message to be sent. Since the BEB-layer supports only a best-effort service, you can not check if the message was sent correctly. Thus, no return value exists. extern void usr beb recv callback(uint16 t addr, uint8 t *buffer, uint8 t size) This is a callback function and should be implemented in the application layer or next upper layer. Otherwise the linker will encounter problems. Similarly to the PPTP layer, this function is called from the system function beb recv task(), which should be called as often as possible in the next upper layer or, in the case of no further layers, in the application layer. Hence, this function is not called in an interrupt context. The addr parameter is a 16-bit short-address, which defines the sender. The buffer and size parameter again define the message to be sent. void beb recv task(void) This is an important system function and should be periodically called as often as possible, because it processes all the messages in the buffer of the PPTP-layer. The corresponding header-files for the specific libraries can be found in the lib/include directory. It is obvious that you can only link one of these static libraries, since one is built upon the other one. If you would like to make your own changes to the MAC-, PPTP-, or BEB-layer, you can find the source files in the lib/src directory. The make-targets of the makefile in the same directory are simply make clean and make all. This automatically creates the three static libraries. Note that the lib-directory is a stand-alone project, because usually you do not need to make changes in the source files. 3.1.2 doc This directory contains all necessary documentations, which you may need during your work. Some important ones are the ATMEL1281 data sheet or the demonstrationkit-documentation. It is advisable to browse this directory before starting your work, because it will safe time later on when you know where to find the information you are looking for. The schematics of the boards can be found in the ATAVRRZ200 DemonstrationKit/schematic/ directory. Therein, the most relevant schematics are those from the radio control board V2.1 and maybe the DisplayBoard. In the same directoy, you will also find a readme.html file. You are well advised to browse this document. 15

3.1. DIRECTORY STRUCTURE CHAPTER 3. WORKSPACE SETUP 3.1.3 urb template This directory contains a starting point for your work. In the urb template.c file you will find a few stubs, that will need some work from your side. Once you implement these functions your device 0 will start sending to the other devices (look at main() which can be found in main.c for a more general view). In case you are interested (or want to change something) the all the hardware is initialized in init.c. You will also find some sub directories here which we describe in the following: drivers: This directory contains the implementation of several processor-specific peripherals. The source-files can be found in the src-directory, whereas the header files are directly mapped to this directory. Note that all source files are automatically compiled and linked via the makefile. If you want to add your own driver, you can simply add the source file to the src-directory. In the application you only have to include the necessary header-files. utils: This directory contains implementations of some helpful functions, which are processor-independent. For instance, the random file abstracts a simple lfsrrandomizer. Likewise to the drivers-dir, this directory again contains a src-subdirectory. Therein, all source files are automatically compiled and linked via the makefile. If you want to add your own processor-independent libraries, you should do it here. It is not necessary to modify the makefile. include: This directory contains all project-specific header files. The most important one is the common.h file, which should be included by all other files. It contains several important macros (e.g., MYADDRESS defines the own 16-bit short-address). You should not do modifications here, but if you need to do this, be sure that the simulator still compiles with the new version. 3.1.4 packet capture The packet capture project has a similar directory structure like the template project. However, it is only a first version and can be used as a packet sniffer. In detail, if you program a device with this project, then it is enabled to receive all packets in the panid and display the information on the display and the UART. You can modify this project to meet your needs with respect to a better debugging. 3.1.5 simul urb template This directory contains a simulation environment based on messages-queues. It contains mostly the same files like in the standard urb template directory. The first step should be to simulate your algorithm with this simulator, since this is faster and you will have a better debugging environment. The implementation should be done in the urb template.h and urb template.c files (you can also change the name of the files, you will not have 16

3.2. SETUP YOUR WORKSPACE CHAPTER 3. WORKSPACE SETUP to change the Makefile). If you have successfully tested your implementation in the simulator environment, you can simply copy these files to the template-project for the real ZigBee devices. The compilation should work error-free, because the simulation environment should support the same functions like the real environment. However, notice to remove, put into comments or otherwise avoid compiling any debugging-outputs, which are not necessary in the real environment, especially the printf-functions, because they consume a lot of RAM. Instead use the printf P function in the real environment. 3.2 Setup your Workspace After unpacking the template-project, you will find the directories as listed in the previous section. Of course, you can change the directory name, so that they are more appropriate to the given exercise, or layer you are currently working on. The most important files in the urb template directory are: init.c This file contains all necessary initialization routines, in order to correctly start the device as a coordinator with a predefined 16-bit short-address. Usually, you do not need to edit anything here. main.c This file contains the main routine, which calls the startup-function of the init.c file. You can further implement a state-machine for each device. Simply write an if-block like if (DEVICE==0). The DEVICE-Macro contains a simple number, starting at 0, which indicates the logical device number (not the 16-bit shortaddress!). This number is defined during the compilation via the make target (e.g., make DEVICE=0). For instance, in the template project, we first check if DEVICE==0, and thus implement the program for the sender. Therein, every time a state-change of the button value is recognized, the send-function of the urb-layer is called. In your implementation, you will call here the send-function of you specific layer-implementation (e.g., uniform reliable broadcast layer). screen.c This file contains the implementation in order to visualize received packets on the display of the programmer board (the docking station with the on-board display). You can use and modify this file in order to have a better debugging. Note that this only abstracts the display-driver. Do not use such functions excessive, since the writing on the display consumes a lot of time. urb template.c This file is the starting point for your implementation. It s current state will only allow your project to compile, but it will do nothing useful (unless you consider lots of initializations useful). include/common.h This file is very important, because it contains all communication relevant macros. For instance the DEVICE START ADDRESS defines the 16- bit address of the first device (with make target DEVICE=0). Thus, the DEVICE- Macro is passed via the make target and defines the logical number of the device 17

3.3. MAKEFILE TARGETS CHAPTER 3. WORKSPACE SETUP from 0 to at most 4. The DEVICECOUNT macro is very important and defines the maximum number of devices in the broadcast domain. It is necessary in order to correctly register all devices in the BEB-layer while the lowest device-address is DEVICE START ADDRESS and the maximum device-address is (DEVICE START ADDRESS+DEVICECOUNT-1). So ensure that this macro is set correctly. The MYADDRESS macro defines the real logical 16-bit address of your own device and is (DEVICE START ADDRESS+DEVICE). The PANID Macro defines the personal area network identifier and should be the same for devices in the broadcast domain. If you setup your project, be sure that every group has its own PANID and that there do not exist any conflicts with the 16-bit short-addresses resulting from an incorrect configuration of the DEVICE START ADDRESS and DEVICECOUNT macro. 3.3 Makefile Targets The complete template-project comprises three sub-projects (lib, simulator, and real project). Therefore every sub-project has its own makefile. Usually, only the simulator and standard-project makefile are relevant. However, the makefiles for the lib and simulator project only support an clean and all target and thus are not explained any more. The makefile for the real ZigBee nodes in the urb template directory contains the following important targets: make clean Clean out build project files. make DEVICE=x Makes the software for a specific device. x declares the logical number of the device and is usually a value from 0 to at most 4, since originally the PPTP-Layer does not support more than 5 devices. Note that the maximum logical device number is bounded by thedevicecount macro in the common.h file. make program Only downloads the produced hex-file from the build-directory to the device. Note that the hex file must exist and, in contrast to standard make install, will not be created automatically. So you will have to call make DEVICE=x before. Moreover the makefile will check that your libraries are compiled, and will try to compile them for you if that is not the case (yet). 18

4 The Simulator After compiling the simulator, you will find an executable file which supports the following Options:./simul: -a <device number=0..> [-s] [-c <number of message to send>] The -a option follows the logical device number as mentioned in the previous chapter. The lowest logical number is 0. So if you start the program with -a 0, internally the address defined in the DEVICE START ADDRESS macro of the common.h file will be used. Similarly, if you start with./simul -a 1, internally the address DE- VICE START ADDRESS+1 will be used. The maximum logical device number is bounded through the DEVICECOUNT macro, again specified in the common.h file. The -s option defines if the program should start as the sender and thus will initially send messages. The number of messages the sender should broadcast is defined via the -c. It is important that you first start only all receivers, i.e., without the -s and -c options. Only the last processor should be started as the sender. You can also implement, modify, and improve the simulator. With respect to the template-project for the ZigBee devices, the simulator-directory contains several similar files. The most important ones are the common.h, urb template.h, and urb template.c files, because they should contain the complete layer-implementation of the given exercise and can be renamed to be more meaningful. Additionally, you can also use the URB DEBUG macro, which is only available in the simulator environment. So you can use it with the #ifdef precompiler condition to make code regions available only within the simulator environment. A simple example is shown below: #ifdef URB_DEBUG printf("urb: sending message with message-id %i\n", message_id); #endif 19

5 Programming Guidelines Since the atmega1281 controller has only 8K RAM memory available (which is usually big enough) and the MAC-layer needs more than 4K, you will have to adhere the following guidelines. Otherwise you will encounter several problems during your implementation: ˆ Do not use the onboard-display excessively for debugging outputs, since the write routines are very time consuming. Instead use the printf-functions, where the stdout-pointer is already mapped to the standard put char(...) function of the buffered UART-driver. Alternatively, you can also use the driver for the external led-board or on-board LEDs. ˆ Put constants ALWAYS into flash, especially strings for debugging outputs. For instance, use printf P(PSTR("Hello World!")) instead of printf("hellow Wrold!"). ˆ Use the simulator to ensure your algorithm is correct, because programming the targets can be very time consuming since every device must be programmed individually. ˆ Program conservative and resource-friendly. ˆ If you want to pass parameters, which are longer than 16 bits (e.g., uint64 t), always use pointers, because they only need 16 bits. This is more friendly to the stack. ˆ Use the memory analyzer in order to be aware of the free memory. avr-size for static memory and the mem eval library (which you might remember from the embedded software engineering course) for dynamic memory. ˆ Check that the programmer is connected correctly (at the RCB socket), such that you do not reprogram the display. In case you do so you should be able to restore the original behaviour of the display by installing rz200 display board v1 0.hex which you will find in the documentation package. 20

List of Figures 1.1 ZigBee architecture............................... 2 1.2 Topology models................................ 3 1.3 IEEE 802.15.4 PHY packet structure..................... 5 1.4 The IEEE 802.15.4 MAC frame format.................... 6 1.5 Super frame structure with GTSs....................... 7 1.6 Communication to a coordinator....................... 9 1.7 Communication from a coordinator...................... 10 3.1 The directory structure of the template project............... 13 21

List of Tables 1.1 ZigBee physical device types......................... 2 22

List of Acronyms ACL Access Control List AF Application Framework APS Application Support BE Backoff Exponent CAP Contention Access Period CCA Clear Channel Assessment CID Cluster Identifier CLH Cluster Head CFP Contention Free Period CRC Cyclic Redundancy Check CSMA/CA Carrier Sense Multiple Access with Collision Avoidance CW Contention Window FCS Frame Check Sequence FFD Full-function Device GTS Guaranteed Time Slot LLC Logical Link Control LR-WPAN Low-rate Wireless Personal Area Network MAC Media Access Control macmaxcsmabackoffs Maximum Backoff Exponent macminbe Minimum Backoff Exponent MFR MAC Footer MHR MAC Header MPDU MAC Protocol Data Units MSDU MAC Service Data Unit 23

List of Tables List of Tables NB Number of Backoff Periods NWK Network OSI Open System Interconnection PAN Personal Area Network PHY Physical PPDU Physical Protocol Data Unit PSDU PHY Service Data Init RFD Reduced-function Device SAP Service Access Point ZC ZigBee Coordinator ZDO ZigBee Device Object ZED ZigBee End Device ZR ZigBee Router 24

Bibliography [All06] ZigBee Alliance. ZigBee Specification, December 2006. [CGH + 02] E. Callaway, P. Gorday, L. Hester, J.A. Gutierrez, M. Naeve, B. Heile, and V. Bahl. Home networking with ieee 802.15.4: a developing standard for low-rate wireless personal area networks. IEEE Communications Magazine, 40(8):70 77, August 2002. [EP03] Chris Evans-Pughe. Bzzzz zzz zigbee wireless standard. IEEE Review, 49(3):28 31, March 2003. [GNC + 01] J.A. Gutierrez, M. Naeve, E. Callaway, M. Bourgeois, V. Mitter, and B. Heile. Ieee 802.15.4: a developing standard for low-power low-cost wireless personal area networks. IEEE Network, 15(5):12 19, 2001. [IEE90] [IEE98] IEEE Computer Society. IEEE Standards for local and metropolitan area networks: overview and architecture. Institute of Electrical and Electronics Engineers, November 1990. IEEE Computer Society. Information processing systems Local area networks Part 2:logical link control. Institute of Electrical and Electronics Engineers, December 1998. [IEE03] IEEE Computer Society. IEEE Standard for Information technology Telecommunication and information exchange between systems Local and metropolitan area networks Specific requirements. Part 15.4: Wireless Medium Access Control (MAC) and Physical Layer (PHY) Specifications for Low-Rate Wireless Personal Area Networks (LR-WPANs). Institute of Electrical and Electronics Engineers, September 2003. [Kin03] P. Kinney. Zigbee technology: Wireless control that simply works. www.zigbee.org/resources, October 2003. Whitepaper. 25