 |
|
| If you can't view the Datasheet, Please click here to try to view without PDF Reader . |
|
|
|
| If you can't view the Datasheet, Please click here to try to view without PDF Reader . |
|
|
| Datasheet File OCR Text: |
| 802.15.4 mac/phy software user?s guide 802154MPSUG/d rev. 0.0, 11/2004
information in this document is prov ided solely to enable system and software implementers to use freescale semiconduc tor products. there are no express or implied copyright licenses granted hereunder to design or fabricate any integrated circuits or integrated ci rcuits based on the inform ation in this document. freescale semiconductor reserves the right to make changes without further notice to any products herein. freescale semic onductor makes no warranty, representation or guarantee regarding the suitability of its products for any particular purpose, nor does freescale semiconductor assume any li ability arising out of the application or use of any product or circuit, and specifically disclaims any and all liability, including without limitation consequential or incidental damages. ?typical? parameters that may be provided in freescale semiconductor dat a sheets and/or specifications can and do vary in different applications and act ual performance may vary over time. all operating parameters, including ?typicals? , must be validated for each customer application by customer?s technical ex perts. freescale semiconductor does not convey any license under its patent rights nor the rights of others. freescale semiconductor products are not designed, intended, or authorized for use as components in systems intended for surgical implant into the body, or other applications intended to support or sustain lif e, or for any other application in which the failure of the freescale semiconducto r product could create a situation where personal injury or death may occur. should buyer purchase or use freescale semiconductor products for any such uni ntended or unauthorized application, buyer shall indemnify and hold freescale semi conductor and its officers, employees, subsidiaries, affiliates, and distributors harmless against all claims, costs, damages, and expenses, and reasonable attorney fees arisi ng out of, directly or indirectly, any claim of personal injury or death associated with such unintended or unauthorized use, even if such claim alleges that freescale semiconductor was negligent regarding the design or manufacture of the part. learn more: for more information about fr eescale products, please visit www.freescale.com. freescale? and the freescale logo are tradem arks of freescale semiconductor, inc. all other product or service names are the property of their respective owners. ? freescale semiconductor, inc. 2004. all rights reserved. zigbee? is a trademark of the zigbee alliance. how to reach us: usa/europe/locations not listed: freescale semiconductor litera ture distribution center p.o. box 5405 denver, colorado 80217 1-800-521-6274 or 480-768-2130 japan: freescale semiconductor japan ltd. technical information center 3-20-1, minami-azabu, minato-ku tokyo 106-8573, japan 81-3-3440-3569 asia/pacific: freescale semiconductor hong kong ltd. 2 dai king street tai po industrial estate tai po, n.t., hong kong 852-26668334 home page: www.fr eescale.com contents freescale semiconductor 802.15.4 mac/phy software user?s guide, rev. 0.0 iii about this book ................................................................................................................ .........v organization................................................................................................................... ............................... v conventions .................................................................................................................... .............................. v definitions, acronyms, and abbreviations....................................................................................... ...........vi references..................................................................................................................... ..............................vii revision history ............................................................................................................... ..........................vii chapter 1 overview ............................................................................................................. ....1-1 1.1 ieee 802.15.4 background ....................................................................................................... ...1-1 1.2 device types ................................................................................................................... .............1-4 1.3 system overview ................................................................................................................ ..........1-5 chapter 2 interfacing to the 802.15.4 mac software ............................................................2-1 2.1 interface ov erview............................................................................................................. ...........2-1 2.2 include files.................................................................................................................. ................2-3 2.3 mac api........................................................................................................................ ..............2-3 2.4 mac main task .................................................................................................................. .........2-6 2.5 mlme and mcps interface........................................................................................................ .2-7 2.5.1 resetting ...................................................................................................................... .................2-7 2.5.2 accessing pib a ttributes....................................................................................................... .......2-8 2.5.3 mlme primitives ................................................................................................................ .........2-8 2.5.4 mcps primitives ................................................................................................................ ........2-11 2.6 asp interface .................................................................................................................. ............2-12 chapter 3 creating an application .........................................................................................3-1 3.1 basic setup .................................................................................................................... ...............3-2 3.1.1 initialization ................................................................................................................. .................3-2 3.1.2 resetting ...................................................................................................................... .................3-2 3.1.3 implementing sap?s............................................................................................................. ........3-3 3.2 starting a new pan............................................................................................................. .........3-3 3.2.1 energy detection scan.......................................................................................................... ........3-4 3.2.2 choosing short address ......................................................................................................... ......3-7 3.2.3 choosing pan id ................................................................................................................ .........3-8 iv 802.15.4 mac/phy software user?s guide, rev. 0.0 freescale semiconductor 3.2.4 starting a pan ................................................................................................................. .............3-9 3.3 joining a pan.................................................................................................................. ...........3-11 3.3.1 active scan .................................................................................................................... .............3-11 3.3.2 associating to a pan........................................................................................................... .......3-14 3.4 adding a device to the pan ..................................................................................................... .3-17 3.5 data tr ansfer .................................................................................................................. ............3-19 3.5.1 direct data .................................................................................................................... ..............3-19 3.5.2 indirect data .................................................................................................................. .............3-22 3.6 summary ........................................................................................................................ .............3-24 freescale semiconductor 802.15.4 mac/phy software user?s guide, rev. 0.0 v about this book this user?s guide describes how to use the freescal e 802.15.4 mac/phy software. it describes how to access and use the medium access control/physical layer (mac/phy) and provides detailed programming descriptions which will allow users to de velop upper layer or application code for this product. this manual is best used together with the 802.15.4 mac/phy software reference manual, 802154mpsrm/d, so that any detailed and specific qu estions can be answered while reading this manual. the freescale 802.15.4 software is designed for use with the freescale mc13192 802.15.4 transceiver as described in the mc13192/93 data sheet, mc13192ds/d. the software package, the mc13192, and the hc08 mcu, form the freescale 802.15.4 platform solution. organization this document is organized into three chapters: chapter 1 overview ? this chapter presents a brief overview of the freescale 802.15.4 software. chapter 2 interfacing to the 802.15.4 mac software ? this chapter describes how to interface a user application to the mac and how to use the mac interface functions. chapter 3 creating an application ? this chapter guides users through the steps required to create a basic, non-beacon ne twork with one coordinator and one device. conventions this document uses the following notational conventions: ? courier monospaced type indicates commands, command parameters, code examples, expressions, data types, and directives e.g. ret = msg_send(nwk_mlme, msg); ? all source code examples are written in c. vi 802.15.4 mac/phy software user?s guide, rev. 0.0 freescale semiconductor definitions, acronyms, and abbreviations the following list defines the abbrev iations used in this document. api application programming interface asp application support package cap contention access period csma-ca carrier sense multiple access with collision avoidance ed energy detection ffd full function device gts guaranteed time slot isr interrupt service routine lqi link quality indication mac medium access control mcps mac common part sublayer mcu micro control unit mlme mac sublayer management entity nwk network pan personal area network panid pan identification phy physical layer pib pan information base ram random access memory rfd reduced function device sap service access point sw software wpan wireless personal area network freescale semiconductor 802.15.4 mac/phy software user?s guide, rev. 0.0 vii references the following documents are referenced in this document. [1] ieee? 802.15.4 standard -2003, part 14.5: wireless medium access control (mac) and physical layer (phy) specifications for low-rate wireless personal area networks (lr-wpans) , the institute of electrical and electronics engineers, inc., 1 october 2003 [2] mc13192 data sheet, mc13192ds/d, freescale semiconductor, 2004 [3] 802.15.4 mac/phy software reference manual, 802154mpsum/d, freescale semiconductors, 2004 [4] hcs08 family reference manual , motorola inc., 2003 revision history the following table summarizes revisions to this manual since the previous release (rev. 0.0). revision history location revision entire document new document. 0.0 viii 802.15.4 mac/phy software user?s guide, rev. 0.0 freescale semiconductor freescale semoconductor 802.15.4 mac/phy software users guide, rev. 0.0 1-1 chapter 1 overview this chapter presents a brief overview of the freescale 802.15.4 software. in section 1.1 , the main concept of the ieee 802.15.4 standard is explained. section 1.2 provides a brief introduction to the full function device and the reduced function device and the use cases associated with each one. section 1.3 provides a system overview. in this section, pay special attention to the concepts presented regarding the three interfaces present in this implementation: 1. mlme 2. mcps 3. asp these three interfaces comprise the applicati on programming interface (api) and are described in detail in chapter 2 . chapter 3 guides users through the making of an application using the ieee 802.15.4 software and the api as described in chapter 2 . 1.1 ieee 802.15.4 background the ieee 802.15.4 is a standard developed for wireless personal area networks (wpans). wpans convey information over short distances among their participants in the network. they enable small, power efficient, inexpensive solutions to be implemented for a wide range of applications and types of devices. some ke y characteristics of an ieee 802.15.4 network are: ? an over the air data rate of 250 kbit/s in the 2.4ghz band. ? 16 independent communication channels in the 2.4ghz band. ? large networks (up to 65534 devices). ? devices use carrier sense multiple access with collision avoidance (csma-ca) to access the medium. ? devices use energy detection (ed) for channel selection. ? devices inform the application about the quality of the wireless link - link quality indication (lqi). 1-2 802.15.4 mac/phy software user?s guide, rev. 0.0 freescale semiconductor the ieee 802.15.4 standard defines two network t opologies in which both topologies use one and only one central device (the pan coordina tor). the pan coordinator is the principal controller of the network: the star network topology in a star network all communication in the network is either to the pan coordinator or from the pan coordinator. that is, communication between non-pan coordinator devices is not possible. the peer-to-peer network topology in a peer-to-peer network communication can occur between any two devices in the network as long as they are within range of one another. figure 1. peer-to- peer and star network (no pan coordinator) if a device wants to join an ieee 802.15.4 network it will have to associate with a device that is already part of the network. that allows other de vices to associate with it. a device can only be associated with one other device but multiple devices can be associated with the same device as shown in figure 1 . a device that has other devices associated with it is a coordinator to those devices. a coordinator can provide synchronization services to the devices that are associated with it through the transmission of beacon frames as shown in figure 2 . in a star network there will be only one pan coordinator, but in a peer-to-peer network there can be multiple coordinators plus the pan coordinator. device pan coordinator communication line (within range) star network peer-to-peer network freescale semiconductor 802.15.4 mac/phy software user?s guide, rev. 0.0 1-3 figure 2. peer and star network (with pan coordinator) a network (both star and peer-to-peer) can operate in either beacon mode or non-beacon mode. in beacon mode, all coordinators within the network transmit synchronization frames (beacon frames) to its associated devices and all data transmissions between the coordinator and its associated devices occur in the active period following the beacon frame as shown in figure 3. beacon frame timing in non-beacon mode data transmissions data transmission can take place at any time. for both non-beacon and beacon networks, the application can choose to transmit data in two ways. ? direct data transfer - data exchanged between a device and a coordinator in a non- beacon network using direct data transfer takes place as soon as the channel is free using csma-ca. ? indirect data transfer - data from a device to a coordinator in a beacon network using indirect data transfer is sent in the cap as soon as the channel is free using csma-ca. coordinator pan coordinator association lines star network peer-to-peer network device beacon frames contention access period time active period inactive period 1-4 802.15.4 mac/phy software user?s guide, rev. 0.0 freescale semiconductor 1.2 device types the basic device types for the freescale 802.15.4 software are as follows: ? reduced function device (rfd) - this device contains a subset of the ieee 802.15.4 features. the rfd can only act as a device in a network. normally the rfd would be used for battery powered devices, since a device with a pure device capability is very power efficient. examples of rfds could be light switches and temperature sensors. ? full function device (ffd) - this device contains all of the ieee 802.15.4 features. the ffd can act as device or coordinator in a network. the ffd is targeted to be used for backbone powered devices. an ffd that take on the role as coordinator uses significantly more power than an rfd in the device role and is more complex and therefore requires more code and memory space than the rfd. examples of ffds could be light controllers with router capability (light bulbs) and pan coordinators (main network controller). to allow users to select the best memory solution, freescale provides both the rfd and the ffd as precompiled libraries. in addition, freescale provides a small number of derivatives of both the ffd and the rfd devices to further reduce memory requirements. for example, if users want to implement an ffd device that does not require beacon capability, they can save almost 9 kb of code space by selecting the ffd library that does not contain this feature. table 1 shows the mac device types as provided by freescale. table 1. mac device types device type description code size ffd full-blown ffd. contains all 802.15. 4 features including security. 37k ffdngts same as ffd but no gts capability. 33k ffdnb same as ffd but no beacon capability. 28k ffdnbns same as ffd but no beacon and no security capability. 21k rfd reduced function device. cont ains 802.15.4 rfd features. 29k rfdnb same as rfd but no beacon capability. 25k rfdnbns same as rfd but no beac on and no security capability. 18k table 1 shows that a significant code reduction is achieved by proper device type library selection. note most low cost, low power applications fit into a standalone embedded device model where the application and mac/phy reside on the same processor. freescale semiconductor 802.15.4 mac/phy software user?s guide, rev. 0.0 1-5 1.3 system overview figure 4 shows a block diagram of the system. the application is using the lower layers to implement a wireless application based on the freescale 802.15.4 software. figure 4. system block diagram the application can theoretically be anything and is entirely up to the user. some examples are: ? dedicated mac application ? zigbee network layer ? proprietary stack the layer below the application as shown in figure 4 , is the 802.15.4 mac (or just mac). the mac provides three interfaces to the application. 1. mlme interface - this interface is used for all 802.15.4 mac commands. for example, the application must use this interface to send the mlme-associate.request primitive and it will also receive the mlme-associate. confirm primitive on this interface. this interface is defined in the ieee 802.15.4 specification. 2. mcps interface - this interface is used for all 802.15.4 data related primitives. the application must use this interface in order to send and receive data. this interface is defined in the ieee 802.15.4 specification. 3. asp interface - this interface is used for various application support features. for example, the application can request that the hardware must enter a low power mode. this interface is proprietary to freescale. 802.15.4 phy 802.15.4 mac mcps mlme asp rf modem transceiver application 1-6 802.15.4 mac/phy software user?s guide, rev. 0.0 freescale semiconductor as shown in figure 4, the two layers at the bottom are the phy and the actual radio (including hardware driver). the application does not access the phy and hardware layer directly. note the application must use the thr ee mac interfaces to implement the desired functionality. chapter 3 describes in detail how to implement a simple application. chapter 2 describes the interfaces in complete detail. freescale semoconductor 802.15.4 mac/phy software users guide, rev. 0.0 2-1 chapter 2 interfacing to the 802.15.4 mac software this chapter describes how to interface an a pplication to the mac and how to use the mac interface functions. the examples shown in this chapter explain the api functions and are often simplified for this purpose. refer to the example application described in chapter 3 for a detailed walk-through of how to create a more advanced application. for a more detailed description of all mac primitives refer to the 802.15.4 mac/phy software reference manual, 802154mpsrm/d . freescale recommends having the reference manual at hand when reding this guide because subtle details (for reasons of readability) are not included in this guide. a brief overview of the mac interfaces are given in section 2.3 before each interface is explained in more detail. throughout this chapter, the term ?application? refers to the next higher layer and all layers above the mac layer. this could be the zigbee network, an application, or another network layer written directly on top of the mac. 2.1 interface overview the interface between the application layer and the mac layer is based on service primitives passed as messages from one layer to another. these service primitives are implemented as a number of c-structures with fields for command opcodes/identifiers and command parameters. this chapter does not describe the primitives in detail but focuses on the functions used for passing, receiving, and processing the message primitives. for a description of all available message primitives see the 802.15.4 mac/phy software reference manual, 802154mpsrm/d . figure 5 shows the three interfaces to the mac. figure 5. mac interfaces 2-2 802.15.4 mac/phy software user?s guide, rev. 0.0 freescale semiconductor messages are sent to a service access point (sap) function which is responsible for handling the message. six saps exists, three for the communication stream to the mac and three for the communication to the application layer. the following list shows the three service access points as provided by the mac layer: 1. nwk_mlme_saphandler() - used for command related primitives sent from the application (or network) layer to the mac layer. this sap receives all mlme request and response primitives. see section 2.5 for a detailed description. 2. nwk_mcps_saphandler() - used for data related primitives sent from the application layer to the mac layer. this sap receives all mcps request and response primitives. see section 2.5 for a detailed description. 3. app_asp_saphandler() - the application support package (asp) interface is provided in order to support freescale specific functionality such as enabling the low- power modes of the mac. this sap is used for all asp request from the application layer to the mac. see section 2.6 for a detailed description. the following list shows the three service access points which must be implemented in the application layer by the mac user. 1. mlme_nwk_saphandler() - used for command related primitives sent from the mac layer to the application/network layer. the access point receives all mlme confirm and indication primitives. see section 2.5 for a detailed description. 2. mcps_nwk_saphandler() - used for data related primitives sent from the application layer to the mac layer. this sap receives all mcps confirm and indication primitives. see section 2.5 for a detailed description. 3. asp_app_saphandler()- used for receiving all asp indications from the mac. see section 2.6 for a detailed description. the application and mac saps typically store the received messages in message queues. a message queue decouples the execution context which ensures that the call stack does not build up between modules when communicating. the decoupling also ensures that timing critical modules can queue a message to less timing critical modules and move on which ensures that the receiving module does process the message immediately. parts of the mac are executed through a synchronous, interrupt driven part. this part is referred to as the mc13192 isr because the controlling interrupts are generated by the mc13192 radio. mc13192 interrupts typically indicate events such as rx data received, rx timeouts, tx done indications, and others. the most timing critical parts of the mac are serviced through this interrupt. the following timing constraint must be kept by the application in order to meet mac interrupt latency demands: ? within a peiod of 64 s the application must disable the mc13192 interrupts for a duration of maximum 10 s . freescale semiconductor 802.15.4 mac/phy software users guide, rev. 0.0 2-3 2.2 include files table 2 shows which mac files must be included in the application c-files in order to have access to the entire mac api. table 2. required mac files in application c-files include file name description digitype.h provides freescale specific type defines for creating fixed sized variables. for example an uint8_t defines the type of an 8 bit uns igned integer. also defines the true and false constants. phymacmsg.h provides access to message handling functions and to allocation/deallocation of data and command buffers to/from the mac/phy. nwkmacinterface.h defines structures and c onstants for all mlme and mcps primitives. appaspinterface.h defines structures and constants for all asp primitives. publicconst.h contains the 802.15. 4 specific status/return codes. 2.3 mac api the mac api provides a simple and consistent way of interfacing to the freescale ieee 802.15.4 mac software. the number of api functions that the freescale mac software exposes to the application, are limited in order to keep the interfaces as simple and consistent as possible. the api functions available are used for initiali zation of the mac, running the mac, allocating, deallocating, and sending messages, and queueing and dequeueing of messages. table 3 shows the available api functions for initializing and running the mac. table 3. available api functions function description init_802_15_4() this function initializes inter nal variables of the mac/phy modules, resets state machines etc. once the function has been called the mac layer services are available and the mac and phy layers are in a known and ready state for further access. the function is only available if the preprocessor definition include_802_15_4 has been setup in the compiler settings of the mcp project. status = mlme_main() as the mac has been designed to be independent of an operating system, part of the mac must be ex ecuted through regular calls to a mac ?main task? implemented as a simple function. the function basically processes data/command me ssages that are pending in any of the mac input queues. the function returns true if it has more messages to process (that is, it should be called again immediately) and false otherwise. see section 2.4 for an in-depth description of the mlme_main() function. 2-4 802.15.4 mac/phy software user?s guide, rev. 0.0 freescale semiconductor for allocating and deallocating messages to and from the mac and sending messages to the mac, the mac exposes the following message handling functions as shown in table 4 . table 4. exposed message handling functions function description *pmsg = msg_alloctype(type) allocate a message of a certain type. this must only be used to allocate messages for one of the mac access points. the type parameter can be set to mlmemessage_t, mcpsmessage_t, and aspmessage_t. msg_free(*pmsg) frees a message that wa s allocated using msg_alloctype(). status = msg_send(sap, *pmsg) sending a mess age is equal to calling a service access point function. the sap argument can be either nwk_mlme, nwk_mcps or app_asp. the argument is translated into the corresponding sap handler function, e.g. nwk_mlme_saphandler(). the mac implements a few functions for queueing and dequeuing messages from the mac to the application. these functions are shown in table 5 . table 5. queueing and dequeuing functions function description msg_initqueue(*panchor) initializes a queue. this function must be called before queuing or dequeueing from the queue. status = msg_pending(*panchor) checks if a message is pending in a queue given a queue anchor. returns true if any pending messages, and false otherwise. msg_queue(*panchor, *pmsg) queues a message given a queue anchor and a pointer to the message. *pmsg = msg_dequeue(*panchor) gets a message from a queue. returns null if there are no messages in the queue. freescale semiconductor 802.15.4 mac/phy software users guide, rev. 0.0 2-5 also, a few data types are available on the mlme, mcps, and asp interfaces. a common element of the data structures is that a member variable must be set to indicate which message is being sent. the rest of the data structure is a union that must be accessed and set up accordingly. table 6. data structures passed from the application data type description mlmemessage_t the data structure of t he messages passed from the application to the mlme sap handler. mcpsmessage_t the data stru cture of the messages pa ssed from the application to the mcps sap handler. aspmessage_t the data stru cture of the messages pa ssed from the application to the asp sap handler. similar data structures are used when the mac sends messages to the application. again, a member variable contains the message type and the rest of the data structure is a union that must be decoded accordingly. table 7. data structures passed from the mac data type description nwkmessage_t the data structure of the m essages passed from the mlme to the applications mlme sap handler. mcpstonwkmessage_t the data structure of the messages passed from the mcps to the applications mcps sap handler. asptoappmsg_t the data structure of the messages passed from the asp to the applications asp sap handler. additionally, a helper structure for managing message queues is also defined. table 8. helper structures for managing message queues data type description anchor_t a container for any type of mac message. before queuing or dequeuing messages into the stru cture the anchor must be initialized using msg_initqueue() . messages are queued and dequeued using msg_queue() and msg_dequeue() . 2-6 802.15.4 mac/phy software user?s guide, rev. 0.0 freescale semiconductor 2.4 mac main task because the mac is designed to be independent of an operating system, part of the mac must be executed through regular calls to a mac ?main task? implemented as a simple function. the mac main task mlme_main() is responsible for the following functions. ? restructuring data and command frames from the application to the 802.15.4 mac packet format and vice versa. this includes processing all primitives sent to the mlme, mcps, and asp saps. ? matching data requests received from remote devices against the packets queued for indirect transfer. matched packets are passed on to an interrupt driven part of the mac that takes care of the actual transmission. ? processing the gts fields, pending address fi elds, and the beacon payload of received beacon frames. ? automatically generating data requests packets to extract pending data from remote devices (only if in beacon mode and the pib attribute macautorequest is set to true ). ? applying encryption/decryption to the mac frames if sequrity is enabled. even though these activities are not highly time critical in nature, the application program must execute this function in a timely manner. the specific requirements for this execution are as follows. ? the function must be executed at least once for every rx packet the application wishes to receive . if the mac is in a state where the receiver is enabled either continously or with a regular interval, packets can be expected ?any time? and the worst-case packet receive latency is increased with the interval, with which the application executes the mlme_main() function. the mac will not crash if all receive buffers fill up due to slow mlme_main() polling, but instead the receiver will be switched off even though it should actually have been enabled. ? the function must be executed at least once for every mcps, mlme or asp primitive the application has sent to one of the mac access points. ? in addition to the already stated requirements, the function must be executed at least once between two beacon receptions in order to ensure basic beacon operation. if this requirement is not met, beacon packets are not processed in a timely manner, which could lead to unexpected behaviour. for optimal beacon operation it is recommended that the mlme_main() function is polled at least twice during every superframe . freescale semiconductor 802.15.4 mac/phy software users guide, rev. 0.0 2-7 2.5 mlme and mcps interface the mlme and mcps interfaces are quite similar in the way that they are used and both of them are specified in the ieee? 802.15.4 standard. the asp interface is freescale proprietary. the mlme interface manages all commands, responses, indications, and confirmations used for managing a pan and an ieee 802.15.4 compliant unit. the mcps interface carries data related messages (data requests, data indications, data confirmations) and the number of available messages are much smaller than on the mlme interface. common for the mcps and mlme interface is that messages are sent to the interfaces using the msg_send(sap, *pmsg) function (see section 2.3 ). if sending to the mlme the sap parameter must be set to nwk_mlme and sending to the mcps the sap parameter must be set to nwk_mcps. 2.5.1 resetting before the freescale ieee 802.15.4 mac layer can be accessed after power-on, it must be initialized by calling the init_802_15_4() function. see section 2.3 and the 802.15.4 mac/phy software reference manual , 802154mpsrm/d, for a more detailed explanation. at any point after this, it is always safe to reset the mac (and also the phy) layer by using the service mlme-reset.request as shown in the following example code: void app_resetmac_example(void) { mlmemessage_t mlmereset; /* create and execute the reset request */ mlmereset.msgtype = gmlmeresetreq_c; mlmereset.msgdata.resetreq.setdefaultpib = true; (void) msg_send(nwk_mlme, &mlmereset); } by calling this service, the mac layer is reset and brought into the same state, as it was right after having called init_802_15_4() . the setdefaultpib parameter tells the mac layer whether its pib attributes should be set to their default value or if they are to stay unchanged after the reset. this is specified in the ieee 802.15.4 standard. notice that the reset is processed immediately (in the nwk_mlme_saphandler()) and that the freescale mac does not generate the confirmation message, mlme-reset.confirm. furthermore there is no need to check for the return value of msg_send() as it always returns gsuccess_c on an mlme-reset.request. since the call is processed immediately, the message structure need not be allocated through msg_alloctype() , but can be allocated on the stack. in all circumstances, it is the responsibility of the calling entity to de-allocate the message for mlme-reset.request. 2-8 802.15.4 mac/phy software user?s guide, rev. 0.0 freescale semiconductor 2.5.2 accessing pib attributes the mac pib holds all the mac attributes/variables that are accessible for the application. according to ieee 802.15.4 standard, the primitives mlme-set.request and mlme- get.request, provide access to the pib. similar to the freescale implementation of mlme-reset, these primitives are processed immediately and therefore the corresponding confirm messages mlme-set.confirm and mlme-get.confirm are not generated. instead, the return code from msg_send() must be used to check the status. the mlme-set.request message contains a pointer to the data to be written to the mac pib, which must be supplied by the application. the following code is an example of how to use mlme-set.request. uint8_t app_setmacpib_example(uint8_t attribute, uint8_t *pvalue) { mlmemessage_t mlmeset; /* create and execute the set request */ mlmeset.msgtype = gmlmesetreq_c; mlmeset.msgdata.setreq.pibattribute = attribute; mlmeset.msgdata.setreq.pibattributevalue = pvalue; return msg_send(nwk_mlme, &mlmeset); } this usage is very similar to mlme-reset.request, because the call is processed immediately. therefore the message structure need not be allocated through msg_alloctype() , but can be allocated. for example, it can allocated on the stack. it is the responsibility of the calling entity to de-allocate the message (and potentially the pib attribute value data buffer) for mlme- set.request. the return value of msg_send() is gsuccess_c if the set request was processed correctly or ginvalidparameter_c if parameter verification failed. in the latter case, the pib attribute was not set to the new value. the use of mlme-get.request is very similar and only differs in that the pibattributevalue parameter in the message is a return value and in the value of msgtype . see the 802.15.4 mac/phy software reference manual , 802154mpsrm/d, for a description of how to access all available pib attributes including freescale specific pib attributes. 2.5.3 mlme primitives the mlme-set.request, mlme-get.request, and mlme-reset.requests are the only messages that are completed synchronously all other messages from the application to the mlme interface are completed asynchronously i.e. a confirmation message will be generated in the mlme and sent to the mlme sap handler of the application ( mlme_nwk_saphandler() ). for example, in order to request an energy detection scan (for a further explanation of energy detection scan see section 3.2.1 ) the application must allocate a mlme message using msg_alloctype(mlmemessage_t) and fill out the parameters of the message (mlme- scan.request) and send the message to the mlme sap handler as shown in the following code example. freescale semiconductor 802.15.4 mac/phy software users guide, rev. 0.0 2-9 uint8_t app_startedscan_example(void) { mlmemessage_t *pmsg; /* allocate a message for the mlme. */ pmsg = msg_alloctype(mlmemessage_t); if(pmsg != null) { /* allocation succeeded. fill out the message */ pmsg->msgtype = gmlmescanreq_c; pscanreq->msgdata.scanreq.scantype = gscanmodeed_c; pscanreq->msgdata.scanreq.scanchannels[0] = 0x00; pscanreq->msgdata.scanreq.scanchannels[1] = 0xf8; pscanreq->msgdata.scanreq.scanchannels[2] = 0xff; pscanreq->msgdata.scanreq.scanchannels[3] = 0x07; pscanreq->msgdata.scanreq.scanduration = 5; /* send the scan request to the mlme. */ if(msg_send(nwk_mlme, pmsg) == gsuccess_c) return errornoerror; else return errorinvalidparameter; } else { /* allocation of a message buffer failed. */ return errorallocfailed; } } when requesting a service that is completed asynchronously, it is the responsibility of the mlme to deallocate the message. in order for the application to be able to receive the mlme- scan.confirm message from the mlme (and for the application to be able to link without any errors) the application must implement the mlme sap handler. this sap handler will typically only queue the message (which is of type nwkmessage_t ) and return as soon as possible. to tell the mlme that the message was received successfully the sap handler must return a status code of gsuccess_c (any other return codes indicates a failure) as shown in the following code example. uint8_t mlme_nwk_saphandler(nwkmessage_t * pmsg) { msg_queue(&mmlmenwkinputqueue, pmsg); return gsuccess_c; } 2-10 802.15.4 mac/phy software user?s guide, rev. 0.0 freescale semiconductor as shown in the following code example, dequeuing the messages that were received from either the mcps, mlme, or asp interface is done using msg_dequeue() . before dequeuing, it makes sense to have called mlme_main() and then check if there are any messages from the mlme that need to be processed. void main(void) { nwkmessage_t *pmsg; uint8_t *pedlist; while(1) { /* execute the mac main task function. */ mlme_main(); /* try to get a message from the mlme. */ if(msg_pending(&mmlmenwkinputqueue)) { pmsg = msg_dequeue(&mmlmenwkinputqueue); switch (pmsg->msgtype) { /* check for a scan confirm message. */ case gnwkscancnf_c: /* find the pointer to the list of detected energies */ pedlist = pmsg->msgdata.scancnf.reslist.penergydetectlist; /* do app. specific operation on the detected energies */ ? no code is shown for that ? /* the list of detected energies must be freed. */ /* note: this is a special exception for scan. */ msg_free(pedlist); break; default: break; } /* ensure to always free the message */ msg_free(pmsg); } } } notice that the application must free the mlme message after having processed it and that some messages contain pointers to data structures that must be freed before freeing the message itself (as in the case shown in the previous example code). neglecting to free such data structures (and the messages themselves) will cause memory leaks. see the 802.15.4 mac/phy software reference manual , 802154mpsrm/d for more details. the mlme interface only allows for one request pending at a time. that is, after having sent a scan request message to the mlme, users must wait for a scan confirmation message on the mlme sap handler until they are allowed to send another mlme request to the mlme. not complying with this rule may result in unwanted and/or unpredictable behaviour. freescale semiconductor 802.15.4 mac/phy software users guide, rev. 0.0 2-11 2.5.4 mcps primitives alongside the mlme interface, the mcps interface processes data related messages (see the figure in section 2.1 ). the mcsp interface is used just like the mlme interface. the main difference is the message types are sent back and forth on the interface. on the mcps, users must use msg_alloctype(nwktomcpsmessage_t) to allocate a mcps message as shown in the following code example. void app_transmituartdata_example(void) { nwktomcpsmessage_t* ppacket = msg_alloctype(nwktomcpsmessage_t); if(ppacket != null) { /* if we have a buffer, then get data from the uart. */ uint8_t msdulength = uart_poll(ppacket->msgdata.datareq.msdu); if(msdulength) { /* data was available in the uart receive buffer. now create an mcps-data request message containing the uart data. */ ppacket->msgtype = gmcpsdatareq_c; /* create the header using coordinator information gained during the scan procedure. also use the short address we were assigned by the coordinator during association. */ memcpy(ppacket->msgdata.datareq.dstaddr, coordinfo.coordaddress, 8); memcpy(ppacket->msgdata.datareq.srcaddr, myaddress, 8); memcpy(ppacket->msgdata.datareq.dstpanid, coordinfo.coordpanid, 2); memcpy(ppacket->msgdata.datareq.srcpanid, coordinfo.coordpanid, 2); ppacket->msgdata.datareq.dstaddrmode = coordinfo.coordaddrmode; ppacket->msgdata.datareq.srcaddrmode = myaddrmode; ppacket->msgdata.datareq.msdulength = msdulength; /* request mac level acknowledgement of the data packet */ ppacket->msgdata.datareq.txoptions = gtxoptsack_c; /* give the data packet a handle. the handle is returned in the mcps-data confirm message. */ ppacket->msgdata.datareq.msduhandle = msduhandle++; /* send the data request to the mcps */ msg_send(nwk_mcps, ppacket); } } } the application is allowed to allocate multiple data messages using msg_alloctype(mcpsmessage_t, ?) until this returns null. unless the mac is running in non-beacon mode as a device, it reserves a buffer for general receive and for transmitting beacons. because the mcps interface can manage multiple outstanding data requests, it is possible to use double (or multiple) buffering for maximum throughput. that is, it is possible to send a data request to the mcps and then, before receiving a data confirmation on that request, send another data request which keeps a constant data flow between the application and the mcps interface. even though it is not supported by the ieee 802.15.4 standard, double buffering can also be used for polling. see section 3.5.1 for a description of how to optimize data throughput using double buffering. 2-12 802.15.4 mac/phy software user?s guide, rev. 0.0 freescale semiconductor when the application receives messages from the mcps, the messages are received as a type mcpstonwkmessage_t in the mcps_nwk_saphandler() function as shown in the following code example. uint8_t mcps_nwk_saphandler(mcpstonwkmessage_t *pmsg) { /* put the incoming mcps message in the applications input queue. */ msg_queue(&mmcpsnwkinputqueue, pmsg); return gsuccess_c; } the mcps sap handler in the application is similar to that of the mlme. however, separate queues are used for the mcps and mlme messages because the messages cannot be differentiated once the sap handler has finished and the messages have been queued. mcps message processing is performed similar to the processing of mlme messages (typically in the main() function) and the application is responsible of deallocating the mcps messages. 2.6 asp interface the asp interface is a freescale proprietary in terface that can perform several functions including power management, access non-volatile (nv) ram and others. as with the mlme interface, the asp interface contains both asynchronous and synchronous messages. in the asp interface, a request never results in a confirmation message received on the applications asp sap handler. it is completed synchronously and the result of the command is checked using the return value of msg_send() . asp messages must be allocated using msg_alloctype(apptoaspmessage_t) as shown in the following example code. void app_enterhibernation_example(void) { apptoaspmessage_t packet; /* create an asp-hibernate request message. */ packet.msgtype = gappasphibernatereq_c; /* no further parameters to fill out */ /* send the hibernate request to the asp */ msg_send(nwk_asp, &packet); } notice that the application is responsible for de-allocating the messages that it sends to the asp. however, as a consequence of the asp receiving a command (for example, an asp- doze.request to send the mc 13192 into doze mode), the asp may at some point send an indication message to the application (for example, an asp-wake.indication when the mc13192 wakes up from doze mode). as was the case for the mlme and mcps interfaces, the asp sends back indication messages (of type asptoappmsg_t ) to the application using the applications asp sap handler asp_app_saphandler() as shown in the following example code. freescale semiconductor 802.15.4 mac/phy software users guide, rev. 0.0 2-13 uint8_t asp_app_saphandler(asptoappmsg_t *pmsg) { /* put the incoming asp message in the applications input queue. */ msg_queue(&maspappinputqueue, pmsg); return gsuccess_c; } again, the asp messages are typically processed in the main() function of the application, just like the mlme and mcps messages. it is the responsibility of the application to de-allocate the asp message. 2-14 802.15.4 mac/phy software user?s guide, rev. 0.0 freescale semiconductor freescale semoconductor 802.15.4 mac/phy software users guide, rev. 0.0 3-1 chapter 3 creating an application this chapter guides users through the steps required to create a basic, non-beacon network with one coordinator and one device. throughout this guide there are references to the source code example applications contained in the my_wireless_app_demo application example. this example can be downloaded from the freescale zigbee web-site at www.freescale.com/zigbee . each source file is a step towards a full wireless uart application. clear references will be made to the appropriate source file. the guide focuses on the ieee 802.15.4 standard and the freescale specific issues and does not in detail explain the state machine that the code contains. the following source files are available with each new file adding additional functionality until a fully functional application has been developed for both a coordinator and a device. files with names ending in ?a? are demonstrating coordinator behaviour and files with names ending in ?b? demonstrate device behavior. ? myapp_ex01.c : proper initialization of the mac is demonstrated and the mlme main function is called in the main loop. this application does not yet have any real functionality. ? myapp_ex02.c : the energy detection scan is used for scanning a range of channels in order to select a specific channel to operate a pan on. ? myapp_ex03a.c : this demo application builds on myapp_ex02.c. the primary purpose of this application is to demonstrate how to use the start feature of the mac in order to configure a pan coordinator. ? myapp_ex03b.c : this demo application builds upon myapp_ex01.c. the primary purpose of this application is to demonstrate how to use the active scan feature of the mac in order to locate a coordinator that we will associate to later. ? myapp_ex04a.c : this demo application builds on myapp_ex03a.c. in the example we will enable the coordinator to respond to associate requests from devices. ? myapp_ex04b.c : this demo application builds upon myapp_ex03b.c. now that we have the capability of finding a coordinator, we will associate to one in this demo application. ? myapp_ex05a.c : this demo application builds on myapp_ex04a.c. now that we have the 802.15.4 features available for building a network, its time to send data. ? myapp_ex05b.c : this demo application builds upon myapp_ex04b.c. in this demo application we will send data to the coordinator that we have previously associated to. it is recommended that users download the application example and open the my_wireless_app_demo.mcp file. this file is the guide that shows key points in the source code. however, not all code is explained and th e code shown here may be stripped of code that may not be relevant for the given context. it is assumed that users are familiar with metrowerks 3-2 802.15.4 mac/phy software user?s guide, rev. 0.0 freescale semiconductor codewarrior and know how to build the project for either the freescale 13191/92 developer?s starter kit mc13192dsk or the freescale evaluation kit mc13193evk. 3.1 basic setup this section describes the basic setup procedure for any type of device. refer to the demonstration application in the source file called myapp_ex01.c for full source code. 3.1.1 initialization before the freescale ieee 802.15.4 mac layer can be accessed, it must be initialized by calling the init_802_15_4() function which will initialize both the mac and phy layers as shown in the following example code. init_802_15_4(); the function call initializes internal variables of the modules, resets state machines among other things. once this function is called, the mac layer services are available and the mac and phy layers are in a known and ready state for further access. 3.1.2 resetting after this point, it is always safe to reset the mac (and thereby also the phy) layer by using the service mlme-reset.request as shown in the following code. mlmemessage_t mlmereset; /* create and execute the reset request */ mlmereset.msgtype = gmlmeresetreq_c; mlmereset.msgdata.resetreq.setdefaultpib = true; (void) msg_send(nwk_mlme, &mlmereset); by calling this service, the mac layer is reset and brought into the same state as it was right after having called init_802_15_4() . the setdefaultpib parameter tells the mac layer whether its pib attributes should be set to their default value (as specified in the ieee 802,15,4 standard) or if they are to stay unchanged after the reset. notice that when requesting the reset primitive, the reset call is synchronous. that is, there is no confirmation message on the reset request and the function msg_send() simply returns gsuccess_c if the reset was successful (it always will be). because the call is synchronous, the message structure need not be allocated through msg_alloctype() but can be allocated on the stack. in all circumstances, it is the responsibility of the calling entity to de-allocate the message. notice that it is not necessary to reset the mac right after having called init_802_15_4() . myapp_ex01.c does not contain any example of code for resetting a device using the mlme- reset.request. however, it is a well-defined way of bringing back the mac and phy layers to a known state. freescale semiconductor 802.15.4 mac/phy software users guide, rev. 0.0 3-3 3.1.3 implementing sap?s before being able to compile the project, it is necessary to create the sap handlers that process the messages from the mac layer to the next higher layer. for now, just create empty functions and implement the functionality later as shown in this code. /* the following functions are called by the mac to put messages into the application's queue. they need to be defined even if they are not used in order to avoid linker errors. */ uint8_t mlme_nwk_saphandler(nwkmessage_t *pmsg) { /* this only serves as a temporary way of avoiding a compiler warning. later this will be changed so that we return gsuccess_c instead. */ return pmsg->msgtype; } uint8_t mcps_nwk_saphandler(mcpstonwkmessage_t *pmsg) { /* this only serves as a temporary way of avoiding a compiler warning. later this will be changed so that we return gsuccess_c instead. */ return pmsg->msgtype; } uint8_t asp_app_saphandler(asptoappmsg_t *pmsg) { /* this only serves as a temporary way of avoiding a compiler warning. later this will be changed so that we return gsuccess_c instead. */ return pmsg->msgtype; } typically, the sap handlers buffer the messages in a queue and then process the messages at regular intervals or whenever appropriate. section 3.2.1 describes how to process the messages in the sap handler. 3.2 starting a new pan once the mac and phy layers are initialized (see section 3.1.1 ) it is now safe to access the mcps, asp, and mlme services of the mac layer. start by accessing the mlme. the example code for this is found in the myapp_ex02.c source file. the units are now ready to start up a pan. first, set up a pan coordinator because all ieee 802.15.4 standard pans must have a pan coordinator. 3-4 802.15.4 mac/phy software user?s guide, rev. 0.0 freescale semiconductor 3.2.1 energy detection scan the first task that a pan coordinator must perform is to choose which radio frequency to use for its pan. this is called the logical channel. this can be a hard-coded value, but a better method is to choose a channel that is not used by other units. for that purpose, there are primitives that the pan coordinator can use for scanning all (or selected) channels. this is called the energy detection scan (ed scan). the following code shows this task. uint8_t app_startscan(uint8_t scantype) { mlmemessage_t *pmsg; mlmescanreq_t *pscanreq; uart_print("sending the mlme-scan request message to the mac..."); /* allocate a message for the mlme (we should check for null). */ pmsg = msg_alloctype(mlmemessage_t); if(pmsg != null) { /* this is a mlme-start.req command */ pmsg->msgtype = gmlmescanreq_c; /* create the start request message data. */ pscanreq = &pmsg->msgdata.scanreq; /* gscanmodeed_c, gscanmodeactive_c, gscanmodepassive_c, or gscanmodeorphan_c */ pscanreq->scantype = scantype; /* channelstoscan & 0xff - lsb, always 0x00 */ pscanreq->scanchannels[0] = (uint8_t)((scan_channels) & 0xff); /* channelstoscan>>8 & 0xff */ pscanreq->scanchannels[1] = (uint8_t)((scan_channels>>8) & 0xff); /* channelstoscan>>16 & 0xff */ pscanreq->scanchannels[2] = (uint8_t)((scan_channels>>16) & 0xff); /* channelstoscan>>24 & 0xff - msb */ pscanreq->scanchannels[3] = (uint8_t)((scan_channels>>24) & 0xff); /* duration per channel 0-14 (dc). t[sec] = (16*960*((2^dc)+1))/1000000. a scan duration of 5 on 16 channels approximately takes 8 secs. */ pscanreq->scanduration = 5; /* send the scan request to the mlme. */ if(msg_send(nwk_mlme, pmsg) == gsuccess_c) { uart_print("done\n"); return errornoerror; } else { uart_print("invalid parameter!\n"); return errorinvalidparameter; } } else { /* allocation of a message buffer failed. */ uart_print("message allocation failed!\n"); return errorallocfailed; } } freescale semiconductor 802.15.4 mac/phy software users guide, rev. 0.0 3-5 in this case, the scantype parameter for app_startscan() must be set to gscanmodeed_c. other types of scanning are explained later in this chapter. if there is any activity on a channel at the time the pan coordinator scans the channel, this shows up in the result of the scan. a channel that showed no sign of activity at the time of the scan, shows an energy level of approximately 0x00. the higher the number, the more activity that was detected on the channel or the closer the other pan coordinator is to the scanning pan coordinator. the previous code example scans all the 16 available channels in the 2.4 ghz band. the parameter scanchannels is a bit mask where each bit that is set indicates that this channel must be scanned. because the 2.4 ghz band contains channel numbers 11 to 26, bits 11 to 26 are set in the scanchannels bit mask. lower channel numbers are for other frequency bands and are ignored if set in the bit bask. also, the scanduration parameter tells the mac how long to scan on each channel. the numbers 0 to 14 are valid entries for this parameter. the higher the number, the longer the time spent scanning. the exact scan duration for each channel can be calculated using this equation: scan duration = 15.36 ms * (2 scanduration + 1) the scanduration parameter in the example requests scanning for approximately 0.5 seconds on each of the 16 channels. once the scan request message has successfully been sent to the mlme, the scanning commences and a scan confirmation (a nwkmessage_t struct with msgtype == gnwkscancnf_c ) is received asynchronously in the sap handler for the messages from the mlme to the nwk. the following code processes the scan confirmation message. void app_handlescanedconfirm(nwkmessage_t *pmsg) { uint8_t n, minenergy; uint8_t *pedlist; uart_print("recevied the mlme-scan confirm message from the mac\n"); /* get a pointer to the energy detect results */ pedlist = pmsg->msgdata.scancnf.reslist.penergydetectlist; /* set the minimum energy to a large value */ minenergy = 0xff; /* select default channel */ logicalchannel = 11; /* search for the channel with least energy */ for(n=0; n<16; n++) { if(pedlist[n] < minenergy) { minenergy = pedlist[n]; /* channel numbering is 11 to 26 both inclusive */ logicalchannel = n + 11; } } /* print out the result of the ed scan */ uart_print("ed scan returned the following results:\n ["); uart_printhex(pedlist, 16, gprthexbigendian_c | gprthexcommas_c); uart_print("]\n\n"); 3-6 802.15.4 mac/phy software user?s guide, rev. 0.0 freescale semiconductor /* print out the selected logical channel */ uart_print("based on the ed scan the logical channel 0x"); uart_printhex(&logicalchannel, 1, 0); uart_print(" was selected\n"); /* the list of detected energies must be freed. */ msg_free(pedlist); } assuming that the scanning was successful, ( status == gsuccess_c) and that the nwkmessage_t struct is pointed to by a pointer pmsg the pedlist = pmsg- >msgdata.scancnf.reslist.penergydetectlist points to a byte array of 16 bytes. one byte for each channel. pedlist[0] contains the result for channel 11, pedlist[1] contains the result for channel 12 and so on. there will only be a valid result for the channels that were requested to scan for, so a 0x00 result means that either the channel is probably available or the channel was not scanned. it is important to remember the channels that the scan was requested for. once the results of the energy detection scan are received, look at the results from all the channels. remember, a request was made to scan all the channels and to pick the channel with the lowest energy level. store this channel number in a global variable called logicalchannel . do not forget to free not only the scan confirm message (this is done in main() in myapp_ex02.c ) but also the data structures pointed to by pedlist ? and free pedlist first (unless you have a local copy of pedlist that you can use for freeing the list of energy levels) . note just because the ed scan returned a result that showed no activity on a channel it does not mean that another pan coordinator is not using this channel. it only means that no transaction(s) took place between this pan coordinator and any of its devices while performing the ed scan. scanning for a longer time increases the possibility that another pan coordinator is on the channel and is detected, but it is not guaranteed! notice that in myapp_ex02.c there has been added code, as shown in the following code example, for queuing incoming mlme messages and decoupling the mlme from the application. /* application input queues */ anchor_t mmlmenwkinputqueue; uint8_t mlme_nwk_saphandler(nwkmessage_t * pmsg) { /* put the incoming mlme message in the applications input queue. */ msg_queue(&mmlmenwkinputqueue, pmsg); return gsuccess_c; } freescale semiconductor 802.15.4 mac/phy software users guide, rev. 0.0 3-7 also, in the main loop of the application there is added code for processing incoming messages from that queue as shown in this code example. /* try to get a message from mlme */ if(msg_pending(&mmlmenwkinputqueue)) pmsgin = msg_dequeue(&mmlmenwkinputqueue); else pmsgin = null; ? /* process message if pmsgin!=null */ if(pmsgin) { /* messages from the mlme must always be freed. */ msg_free(pmsgin); } by implementing the mlme to nwk sap handler this way, the mlme and nwk/app are completely decoupled. that is, the sap handler only queues the message but does not do any processing of the message. in this way, the mlme returns from the call as fast as possible and the call stack of the mcu is excercised as little as possible reducing the risk of getting a call stack overflow. 3.2.2 choosing short address now the coordinator must assign itself a short address. all units come with a pre-assigned long address, but a short address must be assigned before starting the pan. otherwise, the start request will fail. because the pan coordinator is the first unit to participate in its own pan, it can chose any short address for itself. once the short address is chosen, it is usually hard-coded, it must be set by setting the macshortaddress pib attribute. this is done in app_startcoordinator() in myapp_ex03a.c as shown in the following example code. uint8_t app_startcoordinator(void) { /* message for the mlme will be allocated and attached to this pointer */ mlmemessage_t *pmsg; uart_print("sending the mlme-start request message to the mac..."); /* allocate a message for the mlme (we should check for null). */ pmsg = msg_alloctype(mlmemessage_t); if(pmsg != null) { /* pointer which is used for easy access inside the allocated message */ mlmestartreq_t *pstartreq; /* return value from msg_send - used for avoiding compiler warnings */ uint8_t ret; /* boolean value that will be written to the mac pib */ uint8_t boolflag; /* set-up mac pib attributes. please note that set, get, and reset messages are not freed by the mlme. */ /* we must always set the short address to something else than 0xffff before starting a pan. */ pmsg->msgtype = gmlmesetreq_c; pmsg->msgdata.setreq.pibattribute = gmacpibshortaddress_c; 3-8 802.15.4 mac/phy software user?s guide, rev. 0.0 freescale semiconductor pmsg->msgdata.setreq.pibattributevalue = (uint8_t *)shortaddress; ret = msg_send(nwk_mlme, pmsg); ? /lot of other stuff going on here */ } else { /* allocation of a message buffer failed. */ uart_print("message allocation failed!\n"); return errorallocfailed; } } in the previous code example, the short address of the pan coordinator is set to the value of shortaddress which is elsewhere set to 0xcafe . as with the reset request, the mlme- set.request is also completed synchronously. so, if ret == gsuccess_c after calling msg_send() , the pib attribute was set successfully. the pibattributevalue parameter is not freed by the mlme. the short address must be different from 0xffff. a short address of 0xfffe tells the coordinator to use its long address in all transactions. if the short address is set to anything different from 0xffff and 0xfffe, the pan coordina tor uses this address instead of its long address and thus sends shorter packets. a long a ddress is 8 bytes long, a short address is 2 bytes long. 3.2.3 choosing pan id after selecting the logical channel, the last th ing required before a pan coordinator can start a pan, is for the coordinator to select an identification number for the pan which is called the panid. trusting that there really is no other p an using the same logical channel, the new pan coordinator can freely choose a panid. however, users may want to perform an active scan (see section 3.3.1 ) of the channel to see if there really are no other pan coordinators using the same logical channel. if so, the panid used must be different from the one used by the other pan coordinator on the same logical channel. in the source example file myapp_ex03a.c it is assumed that no other ieee 802.15.4 pan is present and it sets the global variable panid = 0xbeef . freescale semiconductor 802.15.4 mac/phy software users guide, rev. 0.0 3-9 3.2.4 starting a pan after choosing a logical channel, panid, and short address, it is time to start up the pan using the mlme_start.request primitive. the pancoordinator parameter indicates whether the start request is to start up a pan for a pan coordinator or for a coordinator without p an coordinator capability. for an explanation of the difference, see the ieee 802.15.4 standard. because this example is starting up a pan coordinator, this parameter is set to 0x01, where 0x01 means yes, and 0x00 means no. the beaconorder and superframeorder parameters are set to 0x0f because users want to start a non-beacon network. see the 802.15.4 standard about how to start a beacon network. any combination of beaconorder and superframeorder where beaconorder is set to 0x0f creates a non-beacon network. the batterylifeext parameter is ignored for now and is set to 0x00. the coordrealignment parameter tells the mlme whether it should send out a coordinator realignment command prior to starting up the pan. for now, users should set this to 0x00 (no coordinator realignment command) because it is not relevant for this example. finally, the securityenable parameter tells the mlme if it should apply any security to the transactions taking place over the air. for now, users should leave this set to 0x00 (no security). app_startcoordinator() in myapp_ex03a.c contains the code for starting a pan. /* message for the mlme will be allocated and attached to this pointer */ mlmemessage_t *pmsg; uart_print("sending the mlme-start request message to the mac..."); /* allocate a message for the mlme (we should check for null). */ pmsg = msg_alloctype(mlmemessage_t); if(pmsg != null) { /* pointer which is used for easy access inside the allocated message */ mlmestartreq_t *pstartreq; /* return value from msg_send - used for avoiding compiler warnings */ uint8_t ret; /* boolean value that will be written to the mac pib */ uint8_t boolflag; ? /* various mac pib attributes are set up. */ /* this is a mlme-start.req command */ pmsg->msgtype = gmlmestartreq_c; /* create the start request message data. */ pstartreq = &pmsg->msgdata.startreq; /* pan id - lsb, msb. the example shows a pan id of 0xbeef. */ memcpy(pstartreq->panid, (void *)panid, 2); /* logical channel - the default of 11 will be overridden */ pstartreq->logicalchannel = logicalchannel; /* beacon order - 0xf = turn off beacons */ pstartreq->beaconorder = 0x0f; /* superframe order - 0xf = turn off beacons */ pstartreq->superframeorder = 0x0f; /* be a pan coordinator */ pstartreq->pancoordinator = true; /* dont use battery life extension */ pstartreq->batterylifeext = false; 3-10 802.15.4 mac/phy software user?s guide, rev. 0.0 freescale semiconductor /* this is not a realignment command */ pstartreq->coordrealignment = false; /* dont use security */ pstartreq->securityenable = false; /* send the start request to the mlme. */ if(msg_send(nwk_mlme, pmsg) == gsuccess_c) { uart_print("done\n"); return errornoerror; } else { /* one or more parameters in the start request message were invalid. */ uart_print("invalid parameter!\n"); return errorinvalidparameter; } a start confirmation is received asynchronously on the sap that handles the messages from the mlme to the nwk. if the pan was started successfully, a status code of gsuccess_c is returned. the mlme-start.confirm message is processed in myapp_ex03a.c in the state statestartcoordinatorwaitconfirm. as shown in the following code. case statestartcoordinatorwaitconfirm: /* stay in this state until the start confirm message arrives, and then goto the listen state. */ ret = app_waitmsg(pmsgin, gnwkstartcnf_c); if(ret == errornoerror) { uart_print("started the coordinator with pan id 0x"); uart_printhex((uint8_t *)panid, 2, 0); uart_print(", and short address 0x"); uart_printhex((uint8_t *)shortaddress, 2, 0); uart_print(".\n"); state = statelisten; } break; after successfully starting a pan, the macrxonwhenidle pib has been set to 0x01. this means that whenever the pan coordinator is not transmitting a packet, it is listening for incoming packets. this behavior is freescale proprietary and is implemented this way because it is not logical to start a pan and then not start liste ning for incoming association requests or beacon requests from devices performing active scans. however, if this behavior is unwanted, the macrxonwhenidle pib can be set back to its default value of 0x00. all that needs to be done on the pan coordinator is that the pib attribute macassociationpermit must be set to 0x01 in order to ensure that devices are allowed to associate to the pan coordinator. if this pib is left untouched, or at any time set to 0x00, any incoming association requests from a device will be ignored by the mac (see app_startcoordinator()) as shown in the following code. /* we must set the association permit flag to true in order to allow devices to associate to us. */ pmsg->msgtype = gmlmesetreq_c; pmsg->msgdata.setreq.pibattribute = gmacpibassociationpermit_c; boolflag = true; pmsg->msgdata.setreq.pibattributevalue = &boolflag; ret = msg_send(nwk_mlme, pmsg); freescale semiconductor 802.15.4 mac/phy software users guide, rev. 0.0 3-11 as was the case when setting the macshortaddress pib, the ret variable contains gsuccess_c if the pib was successfully set. in the source code example in myapp_ex03a.c, the allocated message pmsg was used repeatedly for setting pib attributes and for st arting the pan. when setting pib attributes the message is not freed by the mlme so it can be used again for things like setting another pib attribute or starting the pan. but as soon as pmsg is used for requesting the startup of a pan, the message is no longer valid in the application context. now the message is owned by the mlme and is freed by the mlme. so, in app_startcoordinator(), pmsg is never freed because this is eventually done by the mlme. 3.3 joining a pan the next step in creating a pan is to associate a device with the pan coordinator that was just started up. the association between the device and the pan coordinator is necessary because the pan coordinator is the only device type that is allowed to assign short addresses to devices and coordinators and a device must have a short address assigned. also, during the (successful) association procedure, the logical channel and panid that the device is going to use when transmitting data is set. the following code examples are taken from myapp_ex03b.c . 3.3.1 active scan before associating to a pan coordinator, the devi ce first needs to find a pan coordinator that is accepting incoming association requests. for that purpose, the device must use the active scan feature. this feature is initiated much the same way as the energy detection (ed) scan and users can reuse the function app_startscan() as described in section 3.2.1 . the only difference is that the scantype parameter must now be set to gscanmodeactive_c . the device could also do an ed scan prior to doing the active scan in order to estimate which logical channels would be worth doing active scan on. however, because the pan that was set up by the pan coordinator is non-beacon and thus no air-traffic is available to detect in the ed scan because there is also no other data on the air, users should not do an ed scan on the device. after receiving the active scan request, the mlme starts sending out beacon requests on the requested channels (in the scanchannels parameter) and starts listening for beacons from (pan) coordinators for as long as indicated in the scanduration parameter. basically, sending a beacon request is like asking, ?are there any pan coordinators out there that have a pan on this channel?? and a pan coordinator sending back a beacon means, ? yes, i have a pan, here is my pan information? . because the device does not know which channel the pan coordinator chose after performing the ed scan, the device will be scanning all channels. assuming that only the pan coordinator that was just started is in the vicinity of our device and it did see the beacon request, a scan confirm with the status == gsuccess_c and resu ltlistsize == 1 is returned. if no answer was received, then status == gnobeacon_c. after receiving the scan confirmation, now look at the ppandescriptor pointer in the scan confirmation message and the data it is pointing to. the ppandescriptor pointer points to an 3-12 802.15.4 mac/phy software user?s guide, rev. 0.0 freescale semiconductor array of structures of type pandescriptor_t as many as are indicated in the resultlistsize parameter as shown in the following code example. typedef struct pandescriptor_tag { uint8_t coordaddress[8]; uint8_t coordpanid[2]; uint8_t coordaddrmode; uint8_t logicalchannel; bool_t securityuse; uint8_t aclentry; bool_t securityfailure; uint8_t superframespec[2]; bool_t gtspermit; uint8_t linkquality; uint8_t timestamp[3]; } pandescriptor_t; using the list of pandescriptor_t structure pointed to by ppandescriptor, the device can decide which coordinator to associate to. for now, skip the parameters that are irrelevant for this example because this example does not run a beacon pan and does not use security. the securityuse , aclentry , securityfailure , gtspermit , and timestamp parameters are not used in this example. the coordaddrmode denotes whether the coordinator is using its long address or is using a short address. if set to gaddrmodeshort_c the pan, the coordinator uses a 16 bit short address and only the first two bytes in coordaddress are valid and contains (in little endian mode) the short address of the pan coordinator. if coordaddrmode is set to gaddrmodelong_c all 8 bytes of the coordaddress parameter are valid and contains (in little endian mode) the full address of the pan coordinator. in this example, coordaddrmode equals gaddrmodeshort_c and coordaddress equals 0xcafe . the logicalchannel denotes the logical channel where the pan coordinator can be found. this value can vary in this example, but it is probably set to 0x0b. see section 3.2.1 for more details. the coordpanid contains the panid of the pan that the pan coordinator has set up. in this example, it is 0xbeef. see section 3.2.4 . the linkquality contains a value in the range of 0x00 to 0xff ? the larger the value, the better the signal strength from the pan coordinator. in most cases this means the closer the pan coordinator is to the device. the last parameter that the device must look at is the superframespec parameter. this parameter contains the information as shown in table 9. table 9. superframespec parameter contents bits: 0-3 4-7 8-11 12 13 14 15 beacon order superframe order final cap slot battery life extension reserved pan coordinator association permit freescale semiconductor 802.15.4 mac/phy software users guide, rev. 0.0 3-13 the bit definition is covered later in this chapter. however, beacon order bit and superframe order bit must correspond to the beacon order and superframe order used when starting the pan coordinator. see section 3.2.4 . in this non-beacon example, they are both 0xf. the pan coordinator bit must also be set as this bit is set as shown in section 3.2.4 . the last bit that is required to look at is the association permit bit. this bit indicates if the pan coordinator will process any incoming association requests. if set, it will process the requests, if not set, the association requests are ignored. this bit follows the macassociatepermit pib attribute of the coordinator as shown in section 3.2.4 . the following code example from myapp_ex03b.c shows how an incoming scan confirmation on an active scan is handled. uint8_t app_handlescanactiveconfirm(nwkmessage_t *pmsg) { uint8_t pandesclistsize = pmsg->msgdata.scancnf.resultlistsize; pandescriptor_t *ppandesc = pmsg- >msgdata.scancnf.reslist.ppandescriptorlist; uint8_t rc = errornoscanresults; /* check if the scan resulted in any coordinator responses. */ if(pandesclistsize != 0) { /* initialize link quality to very poor. */ uint8_t i, bestlinkquality = 0; /* check all pan descriptors. */ for(i=0; i 3-14 802.15.4 mac/phy software user?s guide, rev. 0.0 freescale semiconductor >msgdata.scancnf.reslist.ppandescriptorlist first. that is, unless users have a local copy that they can use for freeing the list of pan descriptors. 3.3.2 associating to a pan from the pan descriptor that was returned by the pan coordinator, users can see that the pan coordinator does accept incoming association requests and there is also a short address and a panid of its pan. next, users can associate the device to the pan coordinator. use the association request message (see myapp_ex04b.c ) to accomplish this as shown in the following code example. uint8_t app_sendassociaterequest(void) { mlmemessage_t *pmsg; mlmeassociatereq_t *passocreq; uart_print("sending the mlme-associate request message to the mac..."); /* allocate a message for the mlme message. */ pmsg = msg_alloctype(mlmemessage_t); if(pmsg != null) { /* this is a mlme-associate.req command. */ pmsg->msgtype = gmlmeassociatereq_c; /* create the associate request message data. */ passocreq = &pmsg->msgdata.associatereq; /* use the coordinator info we got from the active scan. */ memcpy(passocreq->coordaddress, coordinfo.coordaddress, 8); memcpy(passocreq->coordpanid, coordinfo.coordpanid, 2); passocreq->coordaddrmode = coordinfo.coordaddrmode; passocreq->logicalchannel = coordinfo.logicalchannel; passocreq->securityenable = false; /* we want the coordinator to assign a short address to us. */ passocreq->capabilityinfo = gcapinfoallocaddr_c; /* send the associate request to the mlme. */ if(msg_send(nwk_mlme, pmsg) == gsuccess_c) { uart_print("done\n"); return errornoerror; } else { /* one or more parameters in the message were invalid. */ uart_print("invalid parameter!\n"); return errorinvalidparameter; } } freescale semiconductor 802.15.4 mac/phy software users guide, rev. 0.0 3-15 else { /* allocation of a message buffer failed. */ uart_print("message allocation failed!\n"); return errorallocfailed; } } most of the parameters in the association request message are recognizable from previous sections. one parameter that is new is the capabilityinfo parameter. this bit mask is described in table 10 . table 10. capabilityinfo parameter bit 0 bit 1 bit 2 bit 3 bit 4-5 bit 6 bit 7 alternate pan coordinator device type power source receiver on when idle reserved security capability allocate address table 11. capabilityinfo field definitions field name setting alternate pan coordinator 1 = if device is capable of being a pan coordinator 0 = if device is not capable of being a pan coordinator device type 1 = if device is an radio frequency device (rfd) 0 = if device is not an radio frequency device (rfd) power source 1 = if device is receiving power from ac power 0 = if device is not receiving power from ac power receiver on when idle 1= if device does not disable its receiver during idle periods 0 = if device does disable its receiver during idle periods reserved secure capability 1 = if device is capable of sending and receiving mac frames using the security suite. 0 = if device is not capable of sendi ng and receiving mac frames using the security suite. field is one bit in length. allocate address 1 = if device wants the coor dinator to allocate a short address as a result of the asso ciation procedure. 0 = the special short address (0xfffe) is allocated to the device and returned through the association response command. in this case, the device communicates on the pan using only its 64 bit extended address. field is one bit in length. in this example, the device that users are trying to associate will only have the allocate address subfield set to 1, all others are set to 0. the capabilityinfo parameter is set to gcapinfoallocaddr_c (0x80). after sending the association request message to the mlme, an association request is sent from the device to the pan coordinator. assuming that the pan coordinator receives, accepts, and 3-16 802.15.4 mac/phy software user?s guide, rev. 0.0 freescale semiconductor responds positively to the association request by sending an association response as described in section 3.4, the application on the device receives an association confirmation with status gsuccess_c and the assocshortaddress parameter set to the short address that the pan coordinator has assigned to the device. in this case the device short address has been set to 0x0001 ( assocshortaddress[0] = 0x00, assocshortaddress[1] = 0x01 ) as shown in the following example code. void app_handleassociateconfirm(nwkmessage_t *pmsg) { /* this is our own extended address (mac address). it cannot be modified. */ extern const uint8_t aextendedaddress[8]; /* if the coordinator assigns a short address of 0xfffe then, that means we must use our own extended address in all communications with the coordinator. otherwise, we use the short address assigned to us. */ if( (pmsg->msgdata.associatecnf.assocshortaddress[0] >= 0xfe) && (pmsg->msgdata.associatecnf.assocshortaddress[1] == 0xff) ) { myaddrmode = 3; memcpy(myaddress, (void *)aextendedaddress, 8); } else { myaddrmode = 2; memcpy(myaddress, pmsg->msgdata.associatecnf.assocshortaddress, 2); } } as the example code shows, the address assigned to the device by the coordinator is stored in myaddress and the addressing mode that is used is stored in myaddrmode . if the coordinator assigns the short address 0xfffe to the device, the device must always use its long (8 byte) address. in this particular scenario there is no checking the pmsg->msgdata.associatecnf.status parameter because the coordinator always accepts incoming association requests. however, in a more extensive application it would be necessary to check on this parameter. freescale semiconductor 802.15.4 mac/phy software users guide, rev. 0.0 3-17 3.4 adding a device to the pan until now this example has ignored what happens on the pan coordinator when the association request from the device is received by the pan coordinator and passed up to the application as an association indication. the association indicati on contains the extended device address (in the deviceaddress parameter) of the associating device and a copy of the capability information that the device passed to the mlme in the association request message. the capability information is stored in the capabilityinfo parameter as described in section 3.3.2 . as the allocate address bit is set in the capabilityinfo parameter, the pan coordinator must assign a short address to the device. because the pan coordinator is the only unit in the pan that is allowed to assign short addresses to a device it can freely choose anything in the 0x0000-0xfffd range. 0xffff is an invalid short address and 0xfffe is the short address that must be assigned to devices that do not request a short address or that always must use a long address. in this example the incoming association indication is accepted and the short address 0x0001 is chosen for the device. as shown in the following code, this message must be sent to the mlme. uint8_t app_sendassociateresponse(nwkmessage_t *pmsgin) { mlmemessage_t *pmsg; mlmeassociateres_t *passocres; uart_print("sending the mlme-associate response message to the mac..."); /* allocate a message for the mlme */ pmsg = msg_alloctype(mlmemessage_t); if(pmsg != null) { /* this is a mlme-associate.res command */ pmsg->msgtype = gmlmeassociateres_c; /* create the associate response message data. */ passocres = &pmsg->msgdata.associateres; /* assign a short address to the device. in this example we simply choose 0x0001. though, all devices and coordinators in a pan must have different short addresses. however, if a device do not want to use short addresses at all in the pan, a short address of 0xfffe must be assigned to it. */ if(pmsgin->msgdata.associateind.capabilityinfo & gcapinfoallocaddr_c) { /* assign a unique short address less than 0xfffe if the device requests so. */ passocres->assocshortaddress[0] = 0x01; passocres->assocshortaddress[1] = 0x00; } else { /* a short address of 0xfffe means that the device is granted access to the pan (associate successful) but that long addressing is used.*/ passocres->assocshortaddress[0] = 0xfe; passocres->assocshortaddress[1] = 0xff; } /* get the 64 bit address of the device requesting association. */ 3-18 802.15.4 mac/phy software user?s guide, rev. 0.0 freescale semiconductor memcpy(passocres->deviceaddress, pmsgin- >msgdata.associateind.deviceaddress, 8); /* association granted. may also be gpanatcapacity_c or gpanaccessdenied_c. */ passocres->status = gsuccess_c; /* do not use security */ passocres->securityenable = false; /* save device info. */ memcpy(deviceshortaddress, passocres->assocshortaddress, 2); memcpy(devicelongaddress, passocres->deviceaddress, 8); /* send the associate response to the mlme. */ if(msg_send(nwk_mlme, pmsg) == gsuccess_c) ? this concludes the association procedure for the pan coordinator and completes the association procedure. had users not accepted the association request, the status parameter would have been set to gpanaccessdenied_c . if the pan coordinator does not want to see any incoming association requests, it can set the pib attribute macassociatepermit to 0x00 (false). see section 3.2.4 for details. as was the case for the device, the pan coordinator must store the extended 8 byte address of the device contained in the deviceaddress parameter so that it can later disassociate from the device if it needs to. as an indication of a successful association procedure the coordinator receives a mlme- comm-status.indication message which must be managed as shown in the following code example. uint8_t app_handlemlmeinput(nwkmessage_t *pmsg) { if(pmsg == null) return errornomessage; /* handle the incoming message. the type determines the sort of processing.*/ switch(pmsg->msgtype) { case gnwkassociateind_c: uart_print("received an mlme-associate indication from the mac\n"); /* a device sent us an associate request. we must send back a response. */ return app_sendassociateresponse(pmsg); break; case gnwkcommstatusind_c: /* sent by the mlme after the association response has been transmitted. */ freescale semiconductor 802.15.4 mac/phy software users guide, rev. 0.0 3-19 uart_print("received an mlme-comm-status indication from the mac\n"); break; } return errornoerror; } the example code does not expect that the association procedure fails and does not check on the status code of the mlme-comm-stat us.indication. however, the mlme-comm- status.indication also contains other parameters such as the addresses of the coordinator and the device, their addressing modes, and the panid used by the association procedure. see the 802.15.4 mac/phy software reference manual , 802154mpsrm/d for more information. 3.5 data transfer now that the pan coordinator and the device are associated, data must be transferred between the units. in ieee 802.15.4 standard pans, most communications are driven by the devices in a network. the devices are typically battery powered and must be able to control the data flow in order to optimize battery life. this is accomplished by the device polling for data from the coordinator and transmitting the data directly to the coordinator. the coordinator only sends data to a device when it knows it is listening, for example, when a device has requested data. 3.5.1 direct data in many user scenarios, there will be one pan coordinator with several devices associated to it and the pan coordinator will be powered with ac power, where the devices will be powered by a battery. also, the devices will decide when to transfer data. therefore, the normal set up is to have the pan coordinator listen for data all the time (except when it is transmitting) and have the devices initiate all data transfers. this behavior is implemented in the pan coordinator by setting the macrxonwhenidle pib attribute to 0x01 (true - the default value is 0x00 (false) which corresponds to not listening). this pib is automatically set to 0x01 when the coordinator starts the pan. see section 3.2.4 for details. sending data using the mcps interface is achieved similar to sending commands on the mlme interface. however, there is one major difference. the data may be required to be sent using high bandwidth. on the mlme interface, there can only be one outstanding command packet at a time. only when a confirmation message has been received is the application allowed to send a new command. however, on the mcps interface, there can be multiple outstanding data packets (as many as can be allocated by the application) at a time, keeping the throughput at a maximum. in non-beacon mode, direct data, as opposed to indi rect data, is sent immediately and is sent from the device to the coordinator. the device can send any time because the coordinator is always listening. the coordinator is ac powered and does not need to conserve battery power. as shown in the following code example, myapp_ex05b.c shows how to send data from the device to the coordinator and achieve maximum throughput while sending data. 3-20 802.15.4 mac/phy software user?s guide, rev. 0.0 freescale semiconductor void app_transmituartdata(void) { /* use multi buffering for increased tx performance. it does not really have any effect at a uart baud rate of 19200bps but serves as an example of how the throughput may be improved in a real-world application where the data rate is of concern. */ if( (numpendingpackets < max_pending_data_packets) && (ppacket == null) ) { /* if the maximum number of pending data buffes is below maximum limit and we do not have a data buffer already then allocate one. */ ppacket = msg_alloctype(nwktomcpsmessage_t); } if(ppacket != null) { /* if we have a buffer, then get data from the uart. */ uint8_t msdulength = uart_poll(ppacket->msgdata.datareq.msdu); if(msdulength) { /* data was available in the uart receive buffer. now create an mcps-data request message containing the uart data. */ ppacket->msgtype = gmcpsdatareq_c; /* create the header using coordinator information gained during the scan procedure. also use the short address we were assigned by the coordinator during association. */ memcpy(ppacket->msgdata.datareq.dstaddr, coordinfo.coordaddress, 8); memcpy(ppacket->msgdata.datareq.srcaddr, myaddress, 8); memcpy(ppacket->msgdata.datareq.dstpanid, coordinfo.coordpanid, 2); memcpy(ppacket->msgdata.datareq.srcpanid, coordinfo.coordpanid, 2); ppacket->msgdata.datareq.dstaddrmode = coordinfo.coordaddrmode; ppacket->msgdata.datareq.srcaddrmode = myaddrmode; ppacket->msgdata.datareq.msdulength = msdulength; /* request mac level acknowledgement of the data packet */ ppacket->msgdata.datareq.txoptions = gtxoptsack_c; /* give the data packet a handle. the handle is returned in the mcps-data confirm message. */ ppacket->msgdata.datareq.msduhandle = msduhandle++; /* send the data request to the mcps */ nr msg_send(nwk_mcps, ppacket); /* prepare for another data buffer */ ppacket = null; numpendingpackets++; } } } as this code example shows, the function transmituartdata() must be called at regular intervals (typically when also calling mlme_main() ) in order to keep the throughput at a maximum. also, the number of outstanding data packets in the example has been limited by a constant max_pending_data_packets . to make this limitation is a matter of design and may influence the throughput if it is set too low depending on the data transfer scenario. most of the parameters in the data request message have already been explained in previous sections and basically just contain addresses and addressing modes. however, the txoptions , msduhandle, and msdulength require some explanation. ? the msduhandle parameter is a unique identifier for the data packet. this identifier can be used when receiving the mcps-data.confirm message to identify which data freescale semiconductor 802.15.4 mac/phy software users guide, rev. 0.0 3-21 packet the mcps-data.message refers to. the msduhandle parameter must be chosen so that it can uniquely identify the outstanding data packets. the value is only typically increased between each data packet that is sent as shown throughout this example. ? the msdulength parameter indicates how many valid data bytes the data buffer ppacket->msgdata.datareq.msdu contains. the ppacket- >msgdata.datareq.msdu contains the data that must be transferred, up to 102 bytes. ? the txoptions parameter is a bit mask that tells the mcps how to transfer the data. in this example, only the data packet was required to be acknowledged along with no gts, no indirect transmission, and no security options enabled. the txoptions bit mask is encoded as shown in table 12 . table 12. txoptions parameter encoding bit 0 bit 1 bit 2 bit 3 bits 4-7 acknowledge required gts transmission indirect transmission security enabled 0 the data sent by the device to the coordinator is sent as soon as possible because direct transmission is used. the coordinator is always listening and must acknowledge the reception of the data packet if it was received successfully. if the coordinator was not listening, the device will get a mcps-data.confirm message indicating that no acknowledge was received. however, in the demo application it is assumed that the data was transferred successfully and a counter that keeps track of the number of outstanding data packets is decreased. void app_handlemcpsinput(mcpstonwkmessage_t *pmsgin) { switch(pmsgin->msgtype) { /* the mcps-data confirm is sent by the mac to the network or application layer when data has been sent. */ case gmcpsdatacnf_c: if(numpendingpackets) numpendingpackets--; break; } } on the coordinator side (see myapp_ex05a.c ) the data that the device sent is received much the same way, only it is receiving mcps-data. i ndications instead of mcps-data.confirms. the coordinator just passes the received data on to the uart. void app_handlemcpsinput(mcpstonwkmessage_t *pmsgin) { switch(pmsgin->msgtype) { case gmcpsdataind_c: /* the mcps-data indication is sent by the mac to the network or application layer when data has been received. we simply copy the received data to the uart. */ uart_tx(pmsgin->msgdata.dataind.msdu, pmsgin->msgdata.dataind.msdulength); 3-22 802.15.4 mac/phy software user?s guide, rev. 0.0 freescale semiconductor break; } } for data transfer to actually take place, the sap handler for the mcps interface on both the coordinator and the device must now be implemented just like the mlme sap handler did. uint8_t mcps_nwk_saphandler(mcpstonwkmessage_t *pmsg) { /* put the incoming mcps message in the applications input queue. */ msg_queue(&mmcpsnwkinputqueue, pmsg); return gsuccess_c; } the mcps sap handler uses its own queue and does not share queue with the mlme sap handler because the message formats are differe nt and cannot easily be distinguished by looking at the message. the processing of the messages in the mcps queue starts in the main loop of the application and on both the coordinator and device it follows the pattern as shown in the following example code. if(msg_pending(&mmcpsnwkinputqueue)) { pmsgin = msg_dequeue(&mmcpsnwkinputqueue); ? /* process the mcps packet appripriately */ /* always free messages from mcps */ msg_free(pmsgin); } note the mcps message must be freed by the application. 3.5.2 indirect data sending data from the coordinator to the device is different than sending data from the device to the coordinator because the device is not necessarily listening. the device is usually battery powered and may shut down its transceiver at any time. this requires that the coordinator send its data indirectly. that is, the coordinator sends its data and the data is buffered until the device polls for it. the data is not sent immediately. the data message is created and set as was shown in section 3.5.1 except from the txoptions parameter (see myapp_ex06a.c ) as shown in the following example code. /* request mac level acknowledgement, and indirect transmission of the data packet */ ppacket->msgdata.datareq.txoptions = gtxoptsack_c | gtxoptsindirect_c; the coordinator needs to set the gtxoptsindirect_c bit in the txoptions parameter. if this bit is not set, the data is transmitted directly and immediately. this means that the data would probably be lost as the device is probably not listening. in non-beacon mode, the coordinator typically uses indirect data transmission. by using the gtxoptsack_c bit, the coordinator (and the device) will not only get a mcps- data.confirm message stating that the packet was sent successfully, but they will also get a freescale semiconductor 802.15.4 mac/phy software users guide, rev. 0.0 3-23 message if the data packet was not acknowledged and hence not received by the intended receiver. this allows for an opportunity to retransmit the data packet. because the coordinator sends its data indirectly, the device must poll the data out of the coordinator when the device decides that it is in a state where is it ready to receive and process a message from the coordinator. this is done using the mlme-poll.request message (see myapp_ex06b.c) as shown in the following example code. /* this is an mlme-poll.req command. */ mlmemessage_t *pmlmemsg = msg_alloctype(mlmemessage_t); if(pmlmemsg) { /* create the poll request message data. */ pmlmemsg->msgtype = gmlmepollreq_c; /* use the coordinator information we got from the active scan. */ memcpy(pmlmemsg->msgdata.pollreq.coordaddress, coordinfo.coordaddress, 8); memcpy(pmlmemsg->msgdata.pollreq.coordpanid, coordinfo.coordpanid, 2); pmlmemsg->msgdata.pollreq.coordaddrmode = coordinfo.coordaddrmode; pmlmemsg->msgdata.pollreq.securityenable = false; /* send the poll request to the mlme. */ if(msg_send(nwk_mlme, pmlmemsg) == gsuccess_c) { /* do not allow another poll request before the confirm is received. */ waitpollconfirm = true; /* restart timer. */ timer_reset(); } } sending this request means that the device is asking the coordinator if there is any data avilable in the coordinator for the device. the coordinator sends back an answer in a mlme- poll.response, resulting in a mlme-poll.confirm on the device as shown in the following example code. uint8_t app_handlemlmeinput(nwkmessage_t *pmsg) { if(pmsg == null) return errornomessage; /* handle the incoming message. the type determines the sort of processing.*/ switch(pmsg->msgtype) { case gnwkpollcnf_c: if(pmsg->msgdata.pollcnf.status != gsuccess_c) { /* the poll confirm status was not successful. usually this happens if no data was available at the coordinator. in this case we start polling at a lower rate to conserve power. */ pollinterval = poll_interval_slow; /* if we get to this point, then no data was available, and we allow a new poll request. otherwise, we wait for the data indication before allowing the next poll request. */ waitpollconfirm = false; } break; } 3-24 802.15.4 mac/phy software user?s guide, rev. 0.0 freescale semiconductor return errornoerror; } as this code example shows, a status parameter different from gsuccess_c indicates that there is no data available for the device on the coordinator. in this example, the device uses a timer for polling the coordinator at regular intervals. if the coordinator does not have any data, the polling rate is decreased until the coordinator starts transmitting data again and then the polling interval is again increased. using this polling scheme conserves power in the device (the transceiver is on less often) but other applications may want to use another polling scheme and may choose to poll differently. should the coordinator send back a mlme-poll.response that indicates that it has data queued for the device, the coordinator will, immediatel y after the mlme-poll.response, send its data to the device, which in turn will receive the data packet on the mcps interface. the application does not need to take any action on a mlme-poll.confirm message with status==gsuccess_c ). this extends the app_handlemcpsinput() function on the device that as shown earlier in this chapter. see the myapp_ex06b.c file for more details. void app_handlemcpsinput(mcpstonwkmessage_t *pmsgin) { switch(pmsgin->msgtype) { /* the mcps-data confirm is sent by the mac to the network or application layer when data has been sent. */ case gmcpsdatacnf_c: if(numpendingpackets) numpendingpackets--; break; case gmcpsdataind_c: /* copy the received data to the uart. */ uart_tx(pmsgin->msgdata.dataind.msdu, pmsgin->msgdata.dataind.msdulength); /* since we received data, the coordinator might have more to send. we reduce the polling interval to raise the throughput while data is available. */ pollinterval = poll_interval_fast; /* allow another mlme-poll request. */ waitpollconfirm = false; break; } } as was the case for the coordinator, the device simply passes the data to the uart and completes the transparent uart example. 3.6 summary users should now be able to understand the basic steps in creating and managing a simple, non-beacon ieee 802.15.4 pan. 1. starting and initializing the freescale ieee 802.15.4 mac software. 2. performing and energy detection (ed) scan. freescale semiconductor 802.15.4 mac/phy software users guide, rev. 0.0 3-25 3. starting a non-beacon pan. 4. performaing an active scan. 5. associating a device and a coordinator. 6. performing a direct and indirect data transfer. when writing their own application, users may choose to employ a less complex data transfer model. that is, only one outstanding data request at a time or use a different polling scheme. the design depends upon what the application is supposed to do and the performance criteria imposed on the application. items to consider are code size, power consumption, throughput, among others. this example is intended to introduce just the basic concepts of a non-beacon ieee 802.15.4 pan though there are many other ways of achieving the same functionality, the basic concepts remain the same. 3-26 802.15.4 mac/phy software user?s guide, rev. 0.0 freescale semiconductor |
Price & Availability of 802154MPSUG
 |
|
|
|
|
All Rights Reserved © IC-ON-LINE 2003 - 2022 |
| [Add Bookmark] [Contact Us] [Link exchange] [Privacy policy] |
|
Mirror Sites : [www.datasheet.hk]
[www.maxim4u.com] [www.ic-on-line.cn]
[www.ic-on-line.com] [www.ic-on-line.net]
[www.alldatasheet.com.cn]
[www.gdcy.com]
[www.gdcy.net] |