View 802154MPSRM_3403440.PDF datasheet online --- IC-ON-LINE

Datasheet File OCR Text:

802.15.4 mac/phy software reference manual 802154MPSRM/d rev. 1.1, 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 reference manual, rev. 1.1 iii about this book......................................................................................................... viii important related do cumentatio n............................................................................ viii organization................................................................................................................... .............. viii conventions .................................................................................................................... ............. viii definitions, acronyms, and abbreviations ................................................................................... ix references..................................................................................................................... .................. x revision history ............................................................................................................... .............. x chapter 1 freescale 802.15.4 mac/ phy software ov erview.................................. 1-1 1.1 freescale 802.15.4 mac/phy software de vice types and libraries ........................... 1-1 1.1.1 full function device (ffd) type ....................................................................... 1-2 1.1.2 full function device with no gts (ffdngts) type ..................................... 1-2 1.1.3 full function device no beacon (ffdnb) type............................................... 1-2 1.1.4 full function device no beacon no security (ffdnbns) type ..................... 1-2 1.1.5 reduced function device (rfd) type ............................................................... 1-2 1.1.6 reduced function device no beacon (rfdnb) type....................................... 1-3 1.1.7 reduced function device no beacon no security (rfdnbns) type.............. 1-3 1.1.8 802.15.4_phy_rd01.lib ................................................................................... 1-3 1.1.9 802.15.4_phy_axm_0308_c.lib ..................................................................... 1-3 1.2 the freescale 802.15.4 mac/phy software build environment.................................. 1-3 1.2.1 adding user applications to the build environment.......................................... 1-4 1.3 freescale 802.15.4 mac/phy software source file structure...................................... 1-4 1.4 configuring the freescale 802.15.4 mac/phy soft ware (users hardware platform).. 1-6 1.4.1 redefining the hcs08 clock speed.................................................................... 1-6 1.4.2 changing the interconnection between the hcs08 mcu and the mc13192..... 1-7 chapter 2 mac/network laye r interface descr iption ............................................. 2-1 2.1 general mac/network interface information ................................................................ 2-1 2.2 data types ................................................................................................................. ...... 2-4 chapter 3 feature descripti ons ................................................................................ 3-1
iv 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor 3.1 configuration .............................................................................................................. ..... 3-1 3.1.1 pib attributes ...................................................................................................... 3-1 3.1.2 configuration primitives...................................................................................... 3-3 3.1.2.1 reset request....................................................................................................... 3-3 3.1.2.2 reset confirm (n/a)............................................................................................ 3-3 3.1.2.3 set request .......................................................................................................... 3- 3 3.1.2.4 set confirm.......................................................................................................... 3- 4 3.1.2.5 get request.......................................................................................................... 3- 4 3.1.2.6 get confirm ......................................................................................................... 3-4 3.1.3 configuration examples ...................................................................................... 3-5 3.2 scan feature............................................................................................................... ...... 3-6 3.2.1 common parts...................................................................................................... 3-6 3.2.2 energy detection scan......................................................................................... 3-6 3.2.3 active and passive scan ...................................................................................... 3-6 3.2.4 orphan scan......................................................................................................... 3-6 3.2.5 scan primitives .................................................................................................... 3-7 3.2.5.1 scan request........................................................................................................ 3-7 3.2.5.2 scan-confirm....................................................................................................... 3-7 3.2.5.3 orphan indication ................................................................................................ 3-8 3.2.5.4 orphan response ................................................................................................. 3-8 3.2.5.5 beacon notify indication..................................................................................... 3-8 3.2.5.6 pan descriptor.................................................................................................... 3-9 3.3 start feature .............................................................................................................. ....... 3-9 3.3.1 start primitives .................................................................................................... 3-9 3.3.1.1 start request ........................................................................................................ 3- 9 3.3.1.2 start confirm ..................................................................................................... 3-10 3.4 sync feature ............................................................................................................... ... 3-10 3.4.1 synchronization primitives................................................................................ 3-10 3.4.1.1 sync request...................................................................................................... 3-10 3.4.1.2 sync loss indication.......................................................................................... 3-10 3.5 association feature........................................................................................................ 3-10 3.5.1 association primitives ....................................................................................... 3-13
freescale semiconductor 802.15.4 mac/phy software reference manual, rev. 1.1 v 3.5.1.1 associate request .............................................................................................. 3-13 3.5.1.2 associate response............................................................................................ 3-13 3.5.1.3 associate indication........................................................................................... 3-13 3.5.1.4 associate confirm ............................................................................................. 3-13 3.5.2 associate example............................................................................................. 3-14 3.6 disassociation feature ................................................................................................... 3- 15 3.6.1 disassociation primitives................................................................................... 3-15 3.6.1.1 disassociate request.......................................................................................... 3-15 3.6.1.2 disassociate indication ...................................................................................... 3-16 3.6.1.3 disassociate confirm ......................................................................................... 3-16 3.7 data feature ............................................................................................................... .... 3-16 3.7.1 data primitives .................................................................................................. 3-16 3.7.1.1 data request ...................................................................................................... 3-17 3.7.1.2 data confirm ..................................................................................................... 3-17 3.7.1.3 data indication................................................................................................... 3-17 3.7.1.4 poll request ....................................................................................................... 3-18 3.7.1.5 poll confirm....................................................................................................... 3-18 3.7.1.6 communications status indication .................................................................... 3-18 3.7.2 data example..................................................................................................... 3-19 3.8 purge feature .............................................................................................................. ... 3-19 3.8.1 purge primitives................................................................................................. 3-20 3.8.1.1 purge request .................................................................................................... 3-20 3.8.1.2 purge confirm.................................................................................................... 3-20 3.9 rx enable feature.......................................................................................................... 3-20 3.9.1.1 rx enable request ............................................................................................ 3-20 3.9.1.2 rx enable confirm ........................................................................................... 3-21 3.10 guaranteed time slots (gts) feature .......................................................................... 3-21 3.10.1 gts as device ................................................................................................... 3-21 3.10.2 gts as pan coordinator .................................................................................. 3-23 3.10.3 miscellaneous items .......................................................................................... 3-24 3.10.4 gts primitives................................................................................................... 3-24 3.10.4.1 gts request ................................................................................................. 3-24
vi 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor 3.10.4.2 gts confirm ................................................................................................ 3-24 3.10.4.3 gts indication.............................................................................................. 3-25 3.11 security .................................................................................................................. ........ 3-25 3.11.1 security pib attributes...................................................................................... 3-26 chapter 4 app/asp layer interface descr iption ..................................................... 4-1 4.1 general app/asp interface information......................................................................... 4-1 4.2 asp to app interface....................................................................................................... 4-2 4.2.1 get time confirm................................................................................................ 4-2 4.2.2 get inactive time confirm.................................................................................. 4-3 4.2.3 doze confirm....................................................................................................... 4-3 4.2.4 auto doze confirm.............................................................................................. 4-3 4.2.5 hibernate confirm ............................................................................................... 4-3 4.2.6 wake confirm...................................................................................................... 4-4 4.2.7 event confirm...................................................................................................... 4-4 4.2.8 trim confirm ....................................................................................................... 4-4 4.2.9 ddr confirm....................................................................................................... 4-4 4.2.10 port confirm ........................................................................................................ 4-4 4.2.11 clko confirm .................................................................................................... 4-5 4.2.12 set notify confirm .............................................................................................. 4-5 4.2.13 set min doze time confirm ............................................................................... 4-5 4.2.14 wake indication ................................................................................................... 4-5 4.2.15 idle indication ...................................................................................................... 4-6 4.2.16 inactive indication ............................................................................................... 4-6 4.2.17 event indication................................................................................................... 4-6 4.2.18 asp to app message union ................................................................................. 4-7 4.2.19 examples of asp to app messages..................................................................... 4-7 4.3 app to asp interface....................................................................................................... 4-8 4.3.1 get time request ................................................................................................ 4-8 4.3.2 get inactive time request .................................................................................. 4-8 4.3.3 doze request ....................................................................................................... 4-9 4.3.4 auto doze request .............................................................................................. 4-9 4.3.5 hibernate request................................................................................................ 4-9
freescale semiconductor 802.15.4 mac/phy software reference manual, rev. 1.1 vii 4.3.6 wake request .................................................................................................... 4-10 4.3.7 event request .................................................................................................... 4-10 4.3.8 trim request...................................................................................................... 4-10 4.3.9 ddr request ..................................................................................................... 4-10 4.3.10 port request ....................................................................................................... 4-11 4.3.11 clko request................................................................................................... 4-11 4.3.12 set notify request ............................................................................................. 4-11 4.3.13 set min doze time request .............................................................................. 4-12 4.3.14 app to asp message union ............................................................................... 4-12 4.3.15 examples of app to asp messages................................................................... 4-13 chapter 5 parametric information ............................................................................ 5-1
freescale semiconductor 802.15.4 mac/phy software reference manual, rev. 1.1 viii about this book this document is the reference manual for the freescale ieeetm 802.15.4 standard, mac/phy software. the software is designe d for the freescale mc13192 transceiver. the software package, the mc13192, and the hcs08 mcu forms the freescale 802.15.4 solution. important related documentation it is highly recommended that this reference manual is used together with the freescale 802.15.4 mac/phy software user?s guide. users can dow nload this guide from the freescale zigbee home page www.freescale.com/zigbee . organization this document is organized into five chapters. chapter 1 freescale 802.15.4 mac/phy software overview ? this chapter presents the freescale 802.15.4 mac/phy software device types and libraries, build environment, source file structure, and hardware setup. chapter 2 mac/network layer interface description ? this chapter describes the mac/phy interface for fdd, rfd and their derivatives. chapter 3 feature descriptions ? the chapter contains descriptions of the freescale 802.15.4 mac/phy software features, focusing on the implementation specific details of the ieee 802.15.4 standard. chapter 4 app/asp layer interface description ? this section describes the application (app) / application support package (asp) interface. chapter 5 parametric information ? this chapter lists the main parametric information for the freescale 802.15.4 mac/phy software. conventions this document uses the following notational conventions: ? courier monospaced type indicates commands, command parameters, code examples, expressions, data types, and directives. ? italic type indicates replaceable command parameters. ? all source code examples are in c.
freescale semiconductor 802.15.4 mac/phy software reference manual, rev. 1.1 ix definitions, acronyms, and abbreviations the following list defines the abbreviations used in this document. ack acknowledgement frame api application programming interface ffd full function device as specified in the ieee 802.15.4 standard. ffdngts an ffd without gts support. ffdnb an ffd without beacon support. ffdnbns an ffd without beacon or security support. gpio general purpose input output gts guaranteed time slot hw hardware irq interrupt request isr interrupt service routine mac medium access control mcps mac common part sublayer- service access point mcu micro controllers mlme mac sublayer management entity msdu mac service data unit nwk network layer pan personal area network pan id pan identification pcb printed circuit board phy physical layer pib pan information base psdu phy service data unit rf radio frequencies rfd reduced function device as specified in the ieee 802.15.4 standard. rfdnb an rfd without beacon support. rfdnbns an rfd without beacon or security support. sap service access point sw software
x 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor references the following documents were referenced to build 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. october 2003 [2] zigbee security services specification v.092 revision history the following table summarizes revisions to this manual since the previous release (rev. 1.0). revision history location revision entire document multiple updates.
freescale semiconductor 802.15.4 mac/phy software reference manual, rev. 1.1 1-1 chapter 1 freescale 802.15.4 mac/phy software overview this chapter describes the freescale 802.15.4 mac/phy device types and libraries, build environment, source file structure, and hardware setup. 1.1 freescale 802.15.4 mac/phy software device types and libraries this section describes the suite of freescal e 802.15.4 mac/phy software device types and their related libraries. the different 802.15.4 mac/phy so ftware device types offer various degrees of code sizes by reducing functionality. table 1 shows the relationship between each library and excluded functionalities. table 1. mc/phy software device type functionality device type description mac library file name code size ffd full-blown ffd. contains all 802.15.4 features including security. 802.15.4_mac_ffd_vx.yz.lib 37kb ffdngt s same as ffd but no gts capability. 802.15.4_mac_ffdngts_vx.yz.lib 33kb ffdnb same as ffd but no beacon capability. 802.15.4_mac_ffdnb_vx.yz.lib 28kb ffdnbns same as ffd but no beacon and no security capability. 802.15.4_mac_ffdnbns_vx.yz.lib 21kb rfd reduced function device. contains 802.15.4 rfd features. 802.15.4_mac_rfd_vx.yz.lib 29kb rfdnb same as rfd but no beacon capability. 802.15.4_mac_rfdnb_vx.yz.lib 25kb rfnbns same as rfd but no beacon and no security capability. 802.15.4_mac_rfdnbns_vx.yz.lib 18kb the code size, as shown in table 1, is for the complete freescale 802.15.4 mac/phy software device type (mac, phy, mc13192 driver). x.yz is the version number of the freescale 802.15.4 mac/phy software. the mac is available in library format only because it is independent of the hardware platform for your 802.15.4 application. the phy is available in source code format because it is dependent of the hardware platform for your 802.15.4 application. for example, if user s want to run the freescale 802.15.4 mac/phy software on their own hardware platform, they may need to change the definition of the connections between the hcs08 mcu and the mc13192. see section 1.4 for a detailed description of how to make the freescale 802.15.4 mac/phy software run on the user?s own
1-2 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor hardware platform. the freescale 802.15.4 mac/p hy software includes two phy libraries targeted for the freescale evaluation boards (see section 1.1.8 and section 1.1.9 ). note the phy is independent of the device type. 1.1.1 full function device (ffd) type the freescale 802.15.4 mac/phy software ffd t ype is an ieee 802.15.4 standard compliant full functional device with all mac features included. it can be used in applications that require both device and coordinator functionality such as zigbee routers. users should compile their application with the 802.15.4_mac_ffd_vx.yz.lib library to create a device with ffd capabilities. 1.1.2 full function device with no gts (ffdngts) type the freescale 802.15.4 mac/phy software ffdngts device type is an ieee 802.15.4 standard compliant ffd with the gts functionality excluded. it can be used in applications that require both device and coordinator functionality such as zigbee routers. this library cannot be used for applications demanding gts data transmissions. users should compile their application with the 802.15.4_mac_ffdngts_vx.yz.lib library to create a device with ffdngts capabilities. 1.1.3 full function device no beacon (ffdnb) type the freescale 802.15.4 mac/phy software ffdnb device type is an ieee 802.15.4 compliant full functional device with the beacon functionality excluded. it can be used in applications that require both device and coordinator functionality such as zigbee routers. this library cannot be used for creating beaconed networks. users should compile their application with the 802.15.4_mac_ffdnb_vx.yz.lib library to create a device with ffdnb capabilities. 1.1.4 full function device no beacon no security (ffdnbns) type the freescale 802.15.4 mac/phy software ff dnbns device type is an ieee 802.15.4 compliant full functional device with the beacon and security functionalities excluded. it can be used in applications that require both device and coordinator functionality such as zigbee routers. this library cannot be used for creating beaconed networks or for applications demanding encrypted or otherwise secured transactions. users should link their application with the 802.15.4_mac_ffdnbns_vx.yz.lib library to create a device with ffdnbns capabilities. 1.1.5 reduced function device (rfd) type the freescale 802.15.4 mac/phy software rfd device type is an ieee 802.15.4 compliant reduced functional device. it can be used in applications that require device functionality only.
freescale semiconductor 802.15.4 mac/phy software reference manual, rev. 1.1 1-3 users should compile their application with the 802.15.4_mac_rfd_vx.yz.lib library to create a device with rfd capabilities. 1.1.6 reduced function device no beacon (rfdnb) type the freescale 802.15.4 mac/phy software rfdnb device type is an ieee 802.15.4 compliant reduced functional device with the beacon functionality excluded. it can be used in applications that require device functionality only su ch as leaf devices. that is, end-devices with no child devices. this library cannot be used for applications that need to participate in beaconed networks. users should compile their application w ith the 802.15.4_mac_rfdnb_vx.yz.lib library to create a device with ffdnb capabilities. 1.1.7 reduced function device no beacon no security (rfdnbns) type the freescale 802.15.4 mac/phy software rf dnbns device type is an ieee 802.15.4 compliant reduced functional device with the beacon and security functionality excluded. it can be used in applications that require device functionality only, such as leaf devices. that is, end-devices with no child devices. this library cannot be used for applications that need to participate in beaconed networks or for applications that require encrypted or otherwise secured transactions. users should compile their application with the 802.15.4_mac_rfdnbns_vx.yz.lib library to create a device with ffdnbns capabilities. 1.1.8 802.15.4_phy_rd01.lib this freescale 802.15.4 phy library is targeted for the freescale 13192-sard and 13192-evb evaluation boards. users can find more information about these evaluation boards on the freescale zigbee homepage www.freescale.com/zigbee . the freescale 802.15.4 phy library must be linked with one of the freescale 802.15.4 mac libraries and the user application software to form an 802.15.4 compliant product. 1.1.9 802.15.4_phy_axm_0308_c.lib this freescale 802.15.4 phy library is targeted for the axiom axm-0308, hcs08 development board. the freescale 802.15.4 phy library must be linked with one of the freescale 802.15.4 mac libraries and the user application software to form an 802.15.4 compliant product. 1.2 the freescale 802.15.4 mac/phy software build environment this section describes the freescale 802.15.4 mac/phy software build environment. the freescale 802.15.4 mac/phy software is built using the metrowerks ide codewarrior development studio for freescale hc08 3.0, build 030506. freescale recommends using this
1-4 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor version or 3.1, build 4210 of the codewarrior tool to build user applications. both of these versions support the hcs08 variant used in the freescale 802.15.4 mac/phy software package. two metrowerks ide codewarrior development studio project files are included in this release. 1. freescale_802.15.4_phy_sw_vx.yz_mc_v30.mcp . use this .mcp file if you base your development on the metrowerks ide codewarrior development studio for freescale hc08 3.0, build 030506. 2. freescale_802.15.4_phy_sw_vx.yz_mc_v31.mcp . use this .mcp file if you base your development on the metrowerks ide codewarrior development studio for freescale hc08 3.1, build 4210. 1.2.1 adding user applications to the build environment this freescale 802.15.4 mac/phy software includes the freescale 802.15.4 mac libraries, the freescale 802.15.4 phy library/source code, and metrowerks codewarrier project files (.mcp) only. no application library, code, or documentation is included in this release. adding a user application directly on top of the build envir onment is possible but it requires both in depth 802.15.4 knowledge and wireless application experi ence. freescale strongly recommends that users base their application development on the freescale 802.15.4 mac/phy my_wireless_app_demo application example software. this software is described in detail in the freescale 802.15.4 mac/phy software user?s guide , 802154mpsug/d. users can download both the freescale 802.15.4 my_wireless_ app_demo application example software and the freescale 802.15.4 mac/phy software user?s guide on the freescale zigbee home page www.freescale.com/zigbee . 1.3 freescale 802.15.4 mac/phy software source file structure this section describes the source file stru cture of the freescale 802.15.4 mac/phy software. the freescale 802.15.4 mac/phy software uses the following file extensions: source code *.c *.h libraries *.lib elf format targets *.elf s19 record format targets *.s19 memory maps *.map note all targets are drive and main directory independent. the .mcp- project file and the mac/phy libraries will, in a released version,
freescale semiconductor 802.15.4 mac/phy software reference manual, rev. 1.1 1-5 have a version number added to the end of the file name for easy tracking of versions. the freescale 802.15.4 mac/phy software is arranged in the following file structure: |???mcp metrowerks project file |???bin empty output directory |???freescale_reference_libs freescale library files | |???mac | | |???802.15.4_mac_ffd_vx.yz.lib mac ffd device type library | | |???802.15.4_mac_ffdngts_vx.yz.lib mac ffdngts device type library | | |???802.15.4_mac_ffdnb_vx.yz.lib mac ffdnb device type library | | |???802.15.4_mac_ffdnbns_vx.yz.lib mac ffdnbns device type library | | |???802.15.4_mac_rfd_vx.yz.lib mac rfd device type library | | |???802.15.4_mac_rfdnb_vx.yz.lib mac rfdnb device type library | | |???802.15.4_mac_rfdnbns_vx.yz.lib mac rfdnbns device type library | | | |???phy | |???802.15.4_phy_axm_0308_c_vx.yz.lib phy library for axiom axm-0308 board | |???802.15.4_phy_rd01_vx.yz.lib phy library for mc13192sard and mc13192evbs | |???src |???code main directory for source code | |???phy freescale 802.15.2 phy source and header files | |???ghdr global header files and target configuration
1-6 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor 1.4 configuring the freescale 802.15.4 mac/phy software (users hardware platform) this section describes how to redefine the hcs08 clock speed and how to change the interconnection between the hcs08 mcu and the mc13192. this enables users to run thery 802.15.4 application on their own hardware platform. 1.4.1 redefining the hcs08 clock speed by properly configuring the freescale 802.15.4 mac/ phy software, it is possible to run the hsc08 mcu at various clock speeds. freescale recommends adding a compiler define ? type_xxxx ?, where xxxx corresponds to the selected mac library, when the mac/phy libraries are linked with the application software. that is to specify ? type_ffd ? for mac ffd library, ? type_rfd ? for mac rfd library, etc. the mac libraries were also built using this #define to enable the functionality required for a specific device type. however, the system clock is not directly controlled by the libraries but by the application. in the freescale 802.15.4 example application my_wireless_app_demo described in the freescale 802.15.4 mac/phy software user?s guide , the system clock is controlled from the files in the sys directory. freescale recommends copying and reusing the files from these examples. users can download both the freescale 802.15.4 example application my_wireless_app_demo and the freescale 802.15.4 mac/phy software user?s guide from the freescale zigbee web-site at http.//www.freescale.com/zigbee . the define ? type_xxxx ? selects a minimum system bus frequency in the app_target.h header file in the sys directory for each device type. the application can chose to use a higher system bus frequency, but it is not advised to use a lower one. if users want to use a higher frequency than necessary then they need to define one of the following settings on their project: #define system_clock_16mhz #define system_clock_16_78mhz the above defines are used in the nv_data.c file to setup the correct system bus frequency. note that some mcu baud rates are only available at certain system clock frequencies.
freescale semiconductor 802.15.4 mac/phy software reference manual, rev. 1.1 1-7 1.4.2 changing the interconnection between the hcs08 mcu and the mc13192 the phy library is compiled with standard interconnections. there is one each for the freescale 13192-sard and 13192-evb evaluation boards and one for the axiom axm-0308, hcs08 development board. see section 1.1.8 and 1.1.9 for a description of these libraries. if users require a different interconnection for their own hardware platform, the phy library must be recompiled. for this reason the phy library is delivered as source code. in the target.h header file (in the ghdr directory) a set of macros is defined which are used directly by the phy layer for antenna control, etc. in addition to the macros used directly by the phy layer, the gpio ports on the mcu must be set correctly. the port settings are controlled by an additional set of macros which are also configured in the target.h file. the phy function phy_hw_setup() uses these macros to set up the ports. therefore phy_hw_setup() must be called before calling the initializephy() function. the macros in target.h can easily be changed for a new hardware configuration. all macros use the following definition which must be redefi ned if other port and pin mappings are used. in the following example code, the settings are for the freescale 13192-sard and 13192-evb evaluation boards. // define hw pin mappings #define abel_port1 ptcd #define abel_att_pin (1<<2) #define abel_rxtx_pin (1<<3) #define abel_reset_pin (1<<4) #define abel_port2 ptbd #define abel_gpio1_pin (1<<4) #define abel_gpio2_pin (1<<5) #define abel_ant_switch_pin (1<<6)
1-8 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor
freescale semiconductor 802.15.4 mac/phy software reference manual, rev. 1.1 2-1 chapter 2 mac/network layer interface description this chapter describes the mac/phy interface for fdd, rfd and their derivatives. 2.1 general mac/network interface information the interface between the network layer (nwk ) and the mac logical management entity layer (mlme) is based on service primitives passed from one layer to the other through a layer service access point (sap). two saps must be implemented as functions in the application: 1. zberrorcode_t mlme_nwk_saphandler(void *msg) ; mlme to nwk sap mlme_nwk_saphandler() function passes primitives from the mlme to the nwk) 2. zberrorcode_t mcps_nwk_saphandler(void *msg) ; mcps to nwk sap mcps_nwk_saphandler() function passes primitives from the mcps to the nwk) two sap handlers are likewise implemented in the mac. they accept messages in the opposite direction from the nwk to the mlme, and mcps. the sap handler functions should not be calle d directly, but through the available macro msg_send(sap, msg) . the identifier ?sap? will be concatenated with _saphandler . thus, msg_send(nwk_mlme, msg) will be translated to nwk_mlme_saphandler(msg) where msg is some message that must be sent from the nwk to the mlme. both mlme and mcps service primitives use the same type of messages as defined in the interface header file called nwkmacinterface.h . the macros are defined in the header file called phymacmsg.h . the nwk_mlme_saphandler() and nwk_mcps_saphandler() functions may place a message in a queue. in order to process queued messages, the mlme main function mlme_main() must be polled from the nwk or from your application. bool _tmlme_main(void); the function returns true if it has more to process (that is, it must be called again) and returns false if it does not have more to process. the cpu sleep mode can be entered by the nwk or application. because the nwk and mlme/mcps interfaces are based on messages being passed to a few sap?s, each message needs to have an identifie r. these identifiers are shown in the following four tables. some of the identifiers are unsupporte d for some of the device types. for example, the mlme-gts.request primitive is available for the ffdngts but the functionality is not supported.
2-2 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor table 2 provides a list of all the message identifiers in the direction from the mlme to the nwk. they cover all the mlme confirm and indication primitives. table 2. primitives in the mlme to nwk direction. message identifier (primmlmetonwk_t) 802.15.4 mlme to nwk primitives gnwkassociateind_c mlme-associate.indication gnwkassociatecnf_c mlme-associate.confirm gnwkdisassociateind_c mlme-disassociate.indication gnwkdisassociatecnf_c mlme-disassociate.confirm gnwkbeaconnotifyind_c mlme-beacon-notify.indication gnwkgetcnf_c n/a gnwkgtsind_c mlme-gts.indication gnwkgtscnf_c mlme-gts.confirm gnwkorphanind_c mlme-reset.confirm gnwkresetcnf_c n/a gnwkrxenablecnf_c mlme-rx-enable.confirm gnwkscancnf_c mlme-scan.confirm gnwkcommstatusind_c mlme-comm-status.indication gnwksetcnf_c n/a gnwkstartcnf_c mlme-start.confirm gnwksynclossind_c mlme-sync-loss.indication gnwkpollcnf_c mlme-poll.confirm table 3 provides a list of all the message identifiers in the direction from the mcps to the nwk. they cover all the mcps confirm and indication primitives. table 3. primitives in the mcps to nwk direction. message identifier (primmcpstonwk_t) 802.15.4 mcps to nwk primitives gmcpsdatacnf_c mcps-data.confirm gmcpsdataind_c mcps-data.confirm gmcpspurgecnf_c mcps-purge.confirm
freescale semiconductor 802.15.4 mac/phy software reference manual, rev. 1.1 2-3 table 4 provides a list of all the message identifiers in the direction from the nwk to the mlme. they cover all the mlme request and response primitives. table 4. primitives in the nwk to mlme direction. message identifier (primnwktomlme_t) 802.15.4 nwk to mlme primitives gmlmeassociatereq_c mlme-associate.request gmlmeassociateres_c mlme-associate.response gmlmedisassociatereq_c mlme-disassociate.request gmlmegetreq_c mlme-get.request gmlmegtsreq_c mlme-gts.request gmlmeorphanres_c mlme-orphan.response gmlmeresetreq_c mlme-reset.request gmlmerxenablereq_c mlme-rx-enable.request gmlmescanreq_c mlme-scan.request gmlmesetreq_c mlme-set.request gmlmestartreq_c mlme-start.request gmlmesyncreq_c mlme-sync.request gmlmepollreq_c mlme-poll.request table 5 provides a list of all the message identifiers in the direction from the nwk to the mcps. they cover all the mcps request and response primitives. table 5. primitives in the nwk to mcps direction. message identifier (primnwktomcps_t) 802.15.4 nwk to mcps primitives gmcpsdatareq_c mcps-data.request gmcpspurgereq_c mcps-purge.request
2-4 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor 2.2 data types this section describes the main c-structures, and data types used by the mac/nwk interface. a common feature of all the interface structures is that all elements of a size greater than 1 byte are little endian, and declared as byte arrays. that is, a 16 bit short must be stored as shown in the following code example: short panid = 0x1234; associatereq->coordpanid[0] = panid & 0xff; // 0x34 associatereq->coordpanid[1] = panid >> 8; // 0x12 the exception from the little endian notation is the pointer type which may be aligned to a suitable boundary and have the endianess of the cpu in question. values for the various structure elements are defined by the 802.15.4 standard. for example, address mode can take on values 0, 2, and 3 meaning no, short, and extended address respectively. in a later release, the definitions for the various values and bit fields will be provided in the nwkmacinterface.h header file. the structures described in section 3.1.2.1 through section 3.10.4.3 have been collected in single message type as unions plus a message type that corresponds to the enumeration of the primitives. these are the structures which transport messages across the interface. for messages from the mlme to the nwk the following structure/union is used. // mlme to nwk message typedef struct nwkmessage_tag { primmlmetonwk_t msgtype; union { nwkassociateind_t associateind; nwkassociatecnf_t associatecnf; nwkdisassociateind_t disassociateind; nwkdisassociatecnf_t disassociatecnf; nwkbeaconnotifyind_t beaconnotifyind; nwkgetcnf_t getcnf; // not used nwkgtsind_t gtsind; nwkgtscnf_t gtscnf; nwkorphanind_t orphanind; nwkresetcnf_t resetcnf; // not used nwkrxenablecnf_t rxenablecnf; nwkscancnf_t scancnf; nwkcommstatusind_t commstatusind; nwksetcnf_t setcnf; // not used nwkstartcnf_t startcnf; nwksynclossind_t synclossind; nwkpollcnf_t pollcnf; } msgdata; } nwkmessage_t;
freescale semiconductor 802.15.4 mac/phy software reference manual, rev. 1.1 2-5 for messages from the mcps to the nwk the following structure/union is used: // mcps to nwk message typedef struct mcpstonwkmessage_tag { primmcpstonwk_t msgtype; union { mcpsdatacnf_t datacnf; mcpsdataind_t dataind; mcpspurgecnf_t purgecnf; } msgdata; } mcpstonwkmessage_t; the following structure/union is used for messages that must be sent from the nwk to the mlme. an mlme message must be allocated using msg_alloctype(mlmemessage_t) . the macro returns a pointer to a memory location with a sufficient number of bytes, or null if the memory pools are exhausted. the null pointer should be handled in the same way as a confirm message with a status code of transaction_overflow . an allocated message that is sent to the mlme will be freed automatically. pay attention to the comments regarding allocation for the set, get, and reset requests described in section 3.1.2 . // nwk to mlme message typedef struct mlmemessage_tag { primnwktomlme_t msgtype; union { mlmeassociatereq_t associatereq; mlmeassociateres_t associateres; mlmedisassociatereq_t disassociatereq; mlmegetreq_t getreq; mlmegtsreq_t gtsreq; mlmeorphanres_t orphanres; mlmeresetreq_t resetreq; mlmerxenablereq_t rxenablereq; mlmescanreq_t scanreq; mlmesetreq_t setreq; mlmestartreq_t startreq; mlmesyncreq_t syncreq; mlmepollreq_t pollreq; } msgdata; } mlmemessage_t; the following structure/union is used for messages that must be sent from the nwk to the mcps. an mcps-purge.request must be allocated using msg_alloctype(nwktomcpsmessage_t) , while an mcps-data.request message must be allocated using msg_alloc((sizeof( nwktomcpsmessage_t)-1)+size) . both allocation macros return a pointer to a memory location with a sufficient number of bytes, or null if the memory pools are exhausted. the null pointer should be handled in the same way as a confirm message with a status code of transaction_overflow . an allocated message that is sent to the mcps will be freed automatically. // nwk to mcps message typedef struct nwktomcpsmessage_tag { primnwktomcps_t msgtype; union { mcpsdatareq_t datareq; mcpspurgereq_t purgereq; } msgdata; } nwktomcpsmessage_t;
2-6 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor
freescale semiconductor 802.15.4 mac/phy software reference manual, rev. 1.1 3-1 chapter 3 feature descriptions the chapter contains descriptions of th e freescale 802.15.4 mac/phy software features, focusing on the implementation specific details of the ieee 802.15.4 standard. refer to the ieee 802.15.4 standard for more details on these features. 3.1 configuration the mac contains a programmable pan information base (pib). it consists of variables controlling the operation of the mac. some of the variables are updated by the mac while others must be configured by the upper layer. the mac pib attributes, and the three primitives which are available for configuring the mac pib are described in the following sections. 3.1.1 pib attributes table 6 shows all the mac pib attributes available including freescale specific additions to the 802.15.4 specific attributes. table 6. available pib attributes. pib attribute description freescale specific attributes 0x20 gmacrole_c . contains the current role of the dev ice: 0x00 = device, 0x01 = coordinator, 0x02 = pan coordinator. 0x21 gmaclogicalchannel_c . contains the current logical channel (11 to 26). 0x22 gmacpancoordinator_c . true if the device is a pan coordinator. 802.15.4 specific attributes (see error! reference source not found. for descriptions) 0x40 gmacackwaitduration_c 0x41 gmacassociationpermit_c 0x42 gmacautorequest_c 0x43 gmacbattlifeext_c 0x44 gmacbattlifeextperiods_c 0x45 gmacbeaconpayload_c 0x46 gmacbeaconpayloadlength_c 0x47 gmacbeaconorder_c 0x48 gmacbeacontxtime_c 0x49 gmacbsn_c 0x4a gmaccoordextendedaddress_c 0x4b gmaccoordshortaddress_c 0x4c gmacdsn_c 0x4d gmacgtspermit_c
3-2 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor 0x4e gmacmaxcsmabackoffs_c 0x4f gmacminbe_c 0x50 gmacpanid_c 0x51 gmacpromiscuousmode_c 0x52 gmacrxonwhenidle_c 0x53 gmacshortaddress_c 0x54 gmacsuperframeorder_c 0x55 gmactransactionpersistencetime_c security specific attributes 0x70 gmacaclentrydescriptorset_c. a set of acl entries each containing information to be used to protect frames between the mac layer and the specified destinat ion device. size is 30*n, where n is the number of acl entry descriptors. 0x71 gmacaclentrydescriptorsetsize_c. the number of entries in the acl descriptor set. size is 1 byte. 0x72 gmacdefaultsecurity_c . if true, then the device is able to send/receive secured frames to/from devices not listed in the acl descriptor set. size is 1 byte. 0x73 gmacdefaultsecuritymateriallength_c . the number of bytes in the acl security material. size is 1 byte. 0x74 gmacdefaultsecuritymaterial_c . the specific security material to be used to protect frames between the mac and devices not in t he acl descriptor set. size is 16 bytes. 0x75 gmacdefaultsecuritysuite_c . the unique identifier of the security suite to be used to protect frames between the mac and devices not in the acl descriptor set. size is 1 byte. 0x76 gmacsecuritymode_c . the identifier of the security m ode in use. 0x00 = unsecured mode, 0x01 = acl mode, 0x02 is secured mode. size is 1 byte. freescale specific security attributes 0x77 gmacaclentrycurrent_c . sets which acl entry is active for access (0 indicates first entry, 1 second entry and so on). size is 1 byte. 0x78 gmacaclentryextaddress_c. 64 bit addr of the device in this acl entry. size is 8 bytes. 0x79 gmacaclentryshortaddress_c. 16 bit addr of the device in this acl entry. size is 2 bytes. 0x7a gmacaclentrypanid_c. pan id of the device in this acl entry. size is 2 bytes. 0x7b gmacaclentrysecuritymateriallength_c . number of bytes in 'aclsecuritymaterial' (<=16). size is 1 byte. 0x7c gmacaclentrysecuritymaterial_c . key for protecting frames. size is 16 bytes. 0x7d gmacaclentrysecuritysuite_c . security suite used for the device in this acl entry. size is 1 byte.
freescale semiconductor 802.15.4 mac/phy software reference manual, rev. 1.1 3-3 3.1.2 configuration primitives this section describes the implementation of the configuration related primitives. 3.1.2.1 reset request the internal state of the mac including the message/data buffer system is always reset by the mlme-reset.request. however, the upper layer can choose whether the mac pib attributes must be set to default values. this is accomplished through the setdefaultpib parameter of the mlme-reset.request . if the parameter is true the mac pib will be reset to default values, otherwise the contents are left untouched. the reset-request message is processed immediately, and can be allocated on the stack. if the message is allocated by msg_alloc(), it will not be freed by the mlme. no confirm message is generated. instead the return code from the msg_send() macro is used as the status code. // type: gmlmeresetreq_c, typedef struct mlmeresetreq_tag { bool_t setdefaultpib; } mlmeresetreq_t; 3.1.2.2 reset confirm (n/a) the reset-confirm is not used because the reset is carried out immediately. the confirmation status code is returned by the sap function that sends the reset-request message to the mlme. // type: gnwkresetcnf_c, typedef struct nwkresetcnf_tag { uint8_t status; } nwkresetcnf_t; 3.1.2.3 set request the mlme-set.request is used for modifying parameters in the mac pib. see section 3.1 for a list of available pib attributes. the set request message structure contains a point er to the data to be written to the mac pib. the pointer must be supplied by the nwk or app. attributes with a size of more than one byte must be little endian, and given as byte arrays. because the set-request message is processed immediately, it can be allocated on the stack. if the message is allocated by msg_alloc() , it will not be freed by the mlme. no confirm message is generated. instead the return code from the msg_send() macro is used as the status code. when the set-request is used for setting the beacon payload, the beacon payload length attribute must be set first. otherwise, the mlme has no way to tell how many bytes to copy. // type: gmlmesetreq_c, typedef struct mlmesetreq_tag { uint8_t pibattribute; uint8_t *pibattributevalue; // pointer supplied by nwk } mlmesetreq_t;
3-4 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor 3.1.2.4 set confirm the set-confirm is not used because the set-request is carried out synchronously. see the set- request structure for more information. // type: gnwksetcnf_c, typedef struct nwksetcnf_tag { uint8_t status; uint8_t pibattribute; } nwksetcnf_t; 3.1.2.5 get request the mlme-get.request reads parameters in the mac pib. see table 6 for a list of available pib attributes. the get-request message contains a pointer to a buffer where data from the mac pib will be copied to. the pointer must be supplied by the nwk or app. attributes with a size of more than one byte are little endian, and given as byte arrays. because the get-request message is processed immediately, it can be allocated on the stack. if the message is allocated by msg_alloc(), it will not be freed by the mlme. no confirm message is generated. instead the return code from the msg_send() macro is used as the status code. // type: gmlmegetreq_c, typedef struct mlmegetreq_tag { uint8_t pibattribute; uint8_t *pibattributevalue; // pointer supplied by nwk } mlmegetreq_t; 3.1.2.6 get confirm the get-confirm is not used because the get-request is carried out synchronously. see the get- request structure for more information. // type: gnwkgetcnf_c, typedef struct nwkgetcnf_tag { uint8_t status; uint8_t pibattribute; uint8_t *pibattributevalue; } nwkgetcnf_t;
freescale semiconductor 802.15.4 mac/phy software reference manual, rev. 1.1 3-5 3.1.3 configuration examples the following are examples of sending a configuration messages to the mlme. send a set-request with macpanid=0x1234 . uint8_t confirmstatus; uint8_t bpanid[2] = {0x34, 0x12}; // little endian pan id mlmemessage_t *msg = msg_alloctype(mlmemessage_t); msg->msgdata.setreq.attribute = 0x50; msg->msgdata.setreq.attributevalue = bpanid; msg->msgtype = gmlmesetreq_c; // calls uint8_t nwk_mlme_saphandler(void *msg) confirmstatus = msg_send(nwk_mlme, msg) // msg is not deallocated by get/set/reset-requests. msg_free(msg); another way is to use the stack instead of using msg_alloctype() for getting the message buffer ( only for get/set/reset requests). mlmemessage_t msg; uint8_t autorequestflag = true; // set message identifer to mlme-set.request msg.msgtype = gmlmesetreq; // we want to set the pan id attribute of the mac pib. msg.msgdata.setreq.attribute = 0x50; msg.msgdata.setreq.attributevalue = bpanid; // calls uint8_t nwk_mlme_saphandler(void*msg) confirmstatus = msg_send(nwk_mlme, &msg) // set the mac pib auto request flag to true. no need to set // message identifier again since the msg is not modified by // the msg_send(nwk_mlme, &msg) call. msg.msgdata.setreq.attribute = 0x42; msg.msgdata.setreq.attributevalue = &autorequestflag; msg_send(nwk_mlme, &msg); example of getting macbeacontxtime using the get request. uint8_t txtime[3]; msg.msgdata.getreq.attribute = 0x48; msg.msgdata.getreq.attributevalue = txtime; msg.msgtype = gmlmegetreq_c; // calls uint8_t nwk_mlme_saphandler(void*msg) confirmstatus = msg_send(nwk_mlme, &msg) // now txtime contains the value of macbeacontxtime // (24 bit integer in little endian format).
3-6 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor 3.2 scan feature in general, this feature is implemented as described in the ieee 802.15.4 standard (parts 7.1.11, 7.5.2), so only the differences and additional details are included in this document. 3.2.1 common parts requesting any of the scan types (using the mlme-scan.request primitive) will interrupt all other system activity at the mlme layer and below, in accordance with the ieee 802.15.4 standard. it is the responsibility of the nwk layer to only initiate scanning, when this behavior is acceptable. the nwk layer is responsible for correct system behavior, particularly by ensuring that only supported scan types (see below) are attempted, and that at least one channel is always indicated in the scanchannels parameter. 3.2.2 energy detection scan energy detection scan is not supported on rfd devices and derivatives. when energy detection scan is requested, the device will measure the energy level on each requested channel until the scan time has elapsed. the mlme-scan.confirm primitive will always hold energy detection results from all requested channels, that is, partial responses will never be returned. the energy levels are measured in ?dbm steps, with 0 corresponding to ?80dbm (theoretical minimal value) and 0xa0 (decimal 160) corresponding to 0dbm (theoretical maximal value). practical tests on the mc13192 development board (v ersion 2.0) indicate the practical theoretical minimal value to be 0x0a (-75dbm) and the maximal value to be 0x82 (-15dbm). 3.2.3 active and passive scan when active or passive scan is requested, the device will wait for beacons to arrive until the scan time has elapsed. if during this time a valid unique beacon is received, the device will store the result. in this case, or if any other package was received from the air, the device will re-enter rx mode, as long as there is time for the shortest possible rx cycle to complete before the complete scan time has elapsed. active and passive scan is capable of returning up to five (5) results in a single mlme- scan.confirm primitive. thus, when five (5) unique (see the 802.15.4 standard) beacons have been received, the scan is terminated in accordance with the ieee 802.15.4 standard, even if all channels have not been scanned to completion. 3.2.4 orphan scan when orphan scan is requested, the device will wait for a coordinator realignment command to arrive until the scan time has elapsed. if during this time any other command is received from the air, the device will ignore the command and re-enter rx mode, as long as there is time for the shortest possible rx cycle to complete before the complete scan time has elapsed. if a valid coordinator realignment response is received while performing the orphan scan, scanning is immediately terminated in accordance with the ieee 802.15.4 standard error!
freescale semiconductor 802.15.4 mac/phy software reference manual, rev. 1.1 3-7 reference source not found. , even if all channels have not been scanned to completion. in this case, the resulting status parameter is success (otherwise no_beacon ), and mac pib attribute values received in the coordinator realignment frame ( macpanid , maccoordshortaddress , maclogicalchannel and macshortaddress ) are automatically used to update the mac pib. 3.2.5 scan primitives this section describes the implementation of the scan related primitives. 3.2.5.1 scan request the scan-request message parameters map straightforwardly to the message parameters listed and described in error! reference source not found. . it must be ensured that scanchannels always indicates at least one valid channel, and that channels outside the valid range [11;26] are not indicated. the value 0x07fff800 corresponds to ? all valid channels ?. the valid range for scantype is [0;3]. the valid range for scanduration is [0;14]. // type: gmlmescanreq_c, typedef struct mlmescanreq_tag { uint8_t scantype; uint8_t scanchannels[4]; uint8_t scanduration; } mlmescanreq_t; 3.2.5.2 scan-confirm the scan-confirm structure contains a pointer to an array of pan descriptors or energy levels. see the definition in section 3.2.5.6. the array must be freed by a call to mm_free() after energy detection, passive or active scan. all other parameters map exactly as shown to the parameters listed and described in the 802.15.4 standard. // type: gnwkscancnf_c, typedef struct nwkscancnf_tag { uint8_t status; uint8_t scantype; uint8_t resultlistsize; uint8_t unscannedchannels[4]; union { // byte array [16]. must be freed by mm_free(); uint8_t *penergydetectlist; // array of pan descriptors [5]. must be freed by mm_free(); pandescriptor_t *ppandescriptorlist; } reslist; } nwkscancnf_t;
3-8 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor 3.2.5.3 orphan indication // type: gnwkorphanind_c, typedef struct nwkorphanind_tag { uint8_t orphanaddress[8]; bool_t securityuse; uint8_t aclentry; } nwkorphanind_t; 3.2.5.4 orphan response // type: gmlmeorphanres_c, typedef struct mlmeorphanres_tag { uint8_t orphanaddress[8]; uint8_t shortaddress[2]; bool_t securityenable; bool_t associatedmember; } mlmeorphanres_t; 3.2.5.5 beacon notify indication the mlme-beacon-notify.indication message is not only received during scan, but may also be received when the device is tracking a beaconing coordinator. the mlme-beacon-notify.indication message is special since it contains pointers. paddrlist points to the address list which is formatted according to the 802.15.4 standard, section 7.2.2.1.6/7. ppandescriptor points to the pan descriptor of the indication message. see the definition in section 3.2.5.6 . psdu is the beacon payload buffer. the pbufferroot pointer is containing the data fields pointed to by the other pointers, and is used for freeing only. warning the pbufferroot must be freed before freeing the indication message. as shown in this example, msg_free(pbeaconind- >pbufferroot); msg_free(pbeaconind); otherwise, the mac memory pools will be exhausted after just a few beacons. // type: gnwkbeaconnotifyind_c typedef struct nwkbeaconnotifyind_tag { uint8_t bsn; uint8_t pendaddrspec; uint8_t sdulength; uint8_t *paddrlist; pandescriptor_t *ppandescriptor; uint8_t *psdu; uint8_t *pbufferroot; } nwkbeaconnotifyind_t;
freescale semiconductor 802.15.4 mac/phy software reference manual, rev. 1.1 3-9 3.2.5.6 pan descriptor the pan descriptor structure is a common data type used by both the active/passive scan, and beacon notification messages. 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; 3.3 start feature the start feature is not supported on rfd type devices and derivatives. according to the ieee 802.15.4 standard error! reference source not found. it is necessary to set the macshortaddress pib attribute to any value different from 0xffff before using the start feature, otherwise an error code gnoshortaddress_c will be returned. it has been chosen to enable rxonwhenidle when successfully calling the mlme- start.request primitive. hence the new (pan) coordinator will start receiving right away. also, if any additional mlme-start.request primitives are issued in order to change superframe configuration after previously having enabled a beaconed network using mlme- start.request , all information regarding gts (if gts is being used) will be cleared and gts must be set up again by the nwk layer. 3.3.1 start primitives this section describes the implementation of the start related primitives. 3.3.1.1 start request before sending a start-request, the macshortaddress must be set to something different from 0xffff. // type: gmlmestartreq_c, typedef struct mlmestartreq_tag { uint8_t panid[2]; uint8_t logicalchannel; uint8_t beaconorder; uint8_t superframeorder; bool_t pancoordinator; bool_t batterylifeext; bool_t coordrealignment; bool_t securityenable; } mlmestartreq_t;
3-10 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor 3.3.1.2 start confirm // type: gnwkstartcnf_c, typedef struct nwkstartcnf_tag { uint8_t status; } nwkstartcnf_t; 3.4 sync feature when executing an mlme-sync.request , the device tries to synchronize with the coordinator beacons. because there is no mlme-sync.confirm primitive, the way to detect when the synchronization occurs is to set the macautorequest pib attribute to false prior to executing the mlme-sync.request . this forces the mac to send an mlme-beacon- notify.indication every time a beacon is received. after the first beacon has been received, the macautorequest pib attribute can be set to true again. if amaxlostbeacons consecutive beacons are lost, the mac will send an mlme-sync-loss.indication . it is very important to set the macpanid pib attribute to a value different from 0xffff prior to executing mlme-sync.request . if this is not done, the command is ignored by the mac. if the trackbeacon parameter is true , the mac attempts to synchronize with the beacon and track all future beacons. if trackbeacon is false the mac attempts to synchronize with only the next beacon and then goes back to idle state. notice that this also works in combination with the macautorequest pib attribute. for example, if macautorequest is set to true and mlme-sync .request is issued with t rackbeacon equal to false , the mac attempts to acquire synchronization and poll out any pending data. 3.4.1 synchronization primitives this section describes the implementation of the synchronization related primitives. 3.4.1.1 sync request // type: gmlmesyncreq_c, typedef struct mlmesyncreq_tag { uint8_t logicalchannel; bool_t trackbeacon; } mlmesyncreq_t; 3.4.1.2 sync loss indication // type: gnwksynclossind_c, typedef struct nwksynclossind_tag { uint8_t lossreason; } nwksynclossind_t; 3.5 association feature association is implemented according to the ieee 802.15.4 standard but the standard is not explicit on how and when various mac pib attributes are updated. issuing the mlme-
freescale semiconductor 802.15.4 mac/phy software reference manual, rev. 1.1 3- 11 associate.request primitive actually results in two mac command frames being sent to the coordinator. the first is the association request itself. the second is the data request that is sent after aresponsewaittime symbols. refer to the ieee 802.15.4 standard for a description of the association procedure. the following attributes are updated when mlme- associate.request is called. ? macpanid : this attribute is updated as required by the ieee 802.15.4 standard. ? phylogicalchannel : this attribute is updated as required by the ieee 802.15.4 standard. ? maccoordextendedaddress : this attribute is updated if the extended address of the coordinator is passed as argument. otherwise it is not affected. ? maccoordshortaddress : this attribute is updated with the value passed as argument if short addressing mode is used. this is stated in the ieee 802.15.4 standard. if the extended coordinator address is used in the call it is not possible to update this attribute ? the short address of the coordinator is unknown. the ieee 802.15.4 standard does not mention this possibility. the implementation will force maccoordshortaddress to 0xfffe if an extended address is used in the call. ? macshortaddress : the implementation will force this attribute to 0xffff before sending the request to the coordinator. this is the default value following a reset. the attribute is updated because it will ensure that the data request is sent using a long source address. this is the only way to guarantee that the association response can be successfully extracted from the coordinator. setting macshortaddress to 0xffff can be considered as a safeguard mechanism. although this update is not listed in the ieee 802.15.4 standard, it should not violate the intention of the ieee 802.15.4 standard. once these attributes have been updated, a mac command frame containing the association request is then sent to the coordinator. a timer is started upon successful reception. the timer expires after aresponsewaittime symbols. note that the timeout value has a different meaning given the scenario used. ? non-beacon enabled pan network ( macbeaconorder = 15). the timeout value just a simple wait (corresponds to approximately 0.5 sec). ? beacon-enabled pan network ( macbeaconorder < 15). the same interpretation as above is used if the beacon is not being tracked. if the beacon is being tracked it implies that the timeout value corresponds to cap symbols. the timeout may in this case extend over several superframes. the last scenario has some implications that may not be evident. consider a superframe configuration with macbeaconorder = 14 and macsuperframeorder = 0. the cap will in this example be approximately 900 symbols (depends on the length of the beacon frame). beacons will be transmitted approximately every 4 minutes. aresponsewaittime is equal to 30.720 symbols. this implies that the timeout will occur after approximately 34 superframes which in the example is more than two hours!
3-12 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor the data request is sent when the timer expires in order to get the association response from the coordinator unless the following occurs. ? the association response has been ?auto requested? (beacon enabled pan with beacon tracking enabled and macautorequest set to true ). the timer is cancelled if the response arrives before the timer expires. note that the implementation discards all other types of incoming mac command frames while waiting for the association response. ? beacon synchronization may be lost on a beacon enabled pan. loss of beacon synchronization implies that the beacon was being tracked when the association procedure was initiated. if this should happen the association attempt is aborted with a status error of beacon lost (indicated in the mlme-associate.confirm message). this error code is not listed in the ieee 802.15.4 standard error! reference source not found. . note that an mlme-sync-loss.indication message will also be generated (as expected when synchronization is lost). once the data request has been sent (if any) the code is ready to process any incoming mac command frame (the expected being the mlme-associate.response packet of course). the following attributes are updated if the associate response frame is received and the status indicates a successful association as shown in the following list. ? macshortaddress : this attribute is updated with the allocated short address. ? maccoordextendedaddress : the source address is extracted from the mac command frame header and stored in this attribute. ? maccoordshortaddress : this attribute is not updated although this is mentioned in the ieee 802.15.4 standard error! reference source not found. . the short address of the coordinator is not present in the response. notice also that an mlme-comm-status.indication message is generated on the coordinator when the response has been extracted by the device.
freescale semiconductor 802.15.4 mac/phy software reference manual, rev. 1.1 3- 13 3.5.1 association primitives this section describes the implementation of the association related primitives. 3.5.1.1 associate request before sending the associate-request primitive, the ieee 802.15.4 standard error! reference source not found. states that a reset-request must be sent, and an active or passive scan was performed. // type: gmlmeassociatereq_c typedef struct mlmeassociatereq_tag { uint8_t coordaddress[8]; uint8_t coordpanid[2]; uint8_t coordaddrmode; uint8_t logicalchannel; bool_t securityenable; uint8_t capabilityinfo; } mlmeassociatereq_t; 3.5.1.2 associate response // type: gmlmeassociateres_c typedef struct mlmeassociateres_tag { uint8_t deviceaddress[8]; uint8_t assocshortaddress[2]; bool_t securityenable; uint8_t status; } mlmeassociateres_t; 3.5.1.3 associate indication // type: gnwkassociateind_c typedef struct nwkassociateind_tag { uint8_t deviceaddress[8]; bool_t securityuse; uint8_t aclentry; uint8_t capabilityinfo; } nwkassociateind_t; 3.5.1.4 associate confirm // type: gnwkassociatecnf_c typedef struct nwkassociatecnf_tag { uint8_t assocshortaddress[2]; uint8_t status; } nwkassociatecnf_t;
3-14 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor 3.5.2 associate example this section shows an example of sending an associate-request. some pseudo-code has been used (the associatefillinparms(), and handleassocconf() functions does not exist) in order to simplify the example. // need to allocate mlme message for this one. mlmemessage_t *reqmsg = msg_alloctype(mlmemessage_t); nwkmessage_t *cnfmsg; // if reqmsg==null then transaction_overflow // fill in source+destination addresses and capabilities. associatefillinparms(&reqmsg->msgdata.associatereq); reqmsg->msgtype = gmlmeassociatereq_c; // calls uint8_t nwk_mlme_saphandler(void*msg) confirmstatus = msg_send(nwk_mlme, reqmsg) if(confirmstatus == success) { // os call that waits until input arrives in the input queue. waitevent(); // use message system to get the message from the input queue. if(msg_pending(&nwkqueue)) { cnfmsg = msg_dequeue(&nwkqueue); // check if it is the correct message if(cnfmsg->msgtype == gnwkassociatecnf_c) { handleassocconf(&cnfmsg->msgdata.associatecnf); } } else { // not the message we waited for. } // always remember to free incoming messages. msg_free(cnfmsg); } else { // mac failed to initiate association request due to either // wrong parameters or out of buffers. msg was freed by the mac. }
freescale semiconductor 802.15.4 mac/phy software reference manual, rev. 1.1 3- 15 3.6 disassociation feature disassociation is less complex than association but there is an issue in the ieee 802.15.4 standard that makes disassociation from a c oordinator difficult in a non-beacon enabled pan network. ? disassociation from a device: the mlme-disassociate.request is just sent to the remote device where it will result in an mlme-disassociate.indication message. ? disassociation from a coordinator: the mlme-disassociate.request is queued in the indirect queue where it resides until it is polled by the remote device (or the transaction expires). the ieee 802.15.4 standard states that a device with a valid short address will supply this address as a source address in the mac header of the data request. however, the coordinator must queue the packet using the extended address of the device. the result is that the packet cannot be extracted from the coordinator because a short address cannot be matched against the long address. the 802.15.4b task group (see www.ieee802.org/15/pub/tg4b.html ) is currently working on a fix but until this change is published and implemented the following limitation exists. ? it is not possible to disassociate from a coordinator in a non-beacon enabled pan if the device has a valid short address (address < 0xfffe) this limitation does not exist on a beacon enabled pan where macautorequest = true because the auto-request poll packet is sent with a source address equal to the one indicated in the beacon frame pending address list. a workaround is possible for all other scenarios. that is, the device may temporarily set its macshortaddress to 0xfffe or 0xffff if it wishes to poll for packets queued using the device?s extended address. 3.6.1 disassociation primitives this section describes the implementation of the disassociation related primitives. 3.6.1.1 disassociate request // type: gmlmedisassociatereq_c typedef struct mlmedisassociatereq_tag { uint8_t deviceaddress[8]; bool_t securityenable; uint8_t disassociatereason; } mlmedisassociatereq_t;
3-16 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor 3.6.1.2 disassociate indication // type: gnwkdisassociateind_c typedef struct nwkdisassociateind_tag { uint8_t deviceaddress[8]; bool_t securityuse; uint8_t aclentry; uint8_t disassociatereason; } nwkdisassociateind_t; 3.6.1.3 disassociate confirm // type: gnwkdisassociatecnf_c typedef struct nwkdisassociatecnf_tag { uint8_t status; } nwkdisassociatecnf_t; 3.7 data feature the data feature includes the service provi ded by the mcps-data.confirm/indication and mlme-poll.request/confirm primitives. whenever these primitives are in use, so are one or more large data buffers. the large data buffers are buffers mainly used for holding tx or rx packets and they are limited to a specific number for each device type. table 7 shows the number of available large data buffers. the numbers vary because the different device types have more or less functionality. table 7. a vailable large data buffers device type rfd rfdnb rfdnbns ffd ffdngts ffdnb ffdnbns buffers 4 3 3 5 5 4 4 each time an mcps-data.confirm or mlme-poll.request primitive is executed one large buffer is used. even though not directly supported by the ieee 802.15.4 standard, it is possible to execute an mlme-poll.request while another mlme-poll.request is pending in the mac. the mac reserves a buffer for general receive and for transmitting beacons unless it is running in non-beacon mode as device. this means that it is safe for the application to allocate data buffers using the msg_alloctype() function until receiving null, indicating that no buffers are available. 3.7.1 data primitives this section describes the implementation of the data related primitives.
freescale semiconductor 802.15.4 mac/phy software reference manual, rev. 1.1 3- 17 3.7.1.1 data request the data-request message structure has an embedded data field. the total size of the message is (sizeof(mcpsdatareq_t) - 1) + msdulength . the data field is simply addressed with: mcpsdatareq->msdu , and may contain more than one byte even though the array is declared with a size of 1. // type: gmcpsdatareq_c, typedef struct mcpsdatareq_tag { uint8_t dstaddr[8]; //address as defined by dstaddrmode uint8_t dstpanid[2]; uint8_t dstaddrmode; uint8_t srcaddr[8]; //address as defined by srcaddrmode uint8_t srcpanid[2]; uint8_t srcaddrmode; uint8_t msdulength; // 0-102 uint8_t msduhandle; uint8_t txoptions; uint8_t msdu[1]; // data will start at this byte } mcpsdatareq_t; 3.7.1.2 data confirm // type: gmcpsdatacnf_c, typedef struct mcpsdatacnf_tag { uint8_t msduhandle; uint8_t status; } mcpsdatacnf_t; 3.7.1.3 data indication the data-indication structure has an embedded data field. the total size of the message is (sizeof(mcpsdataind_t) - 1) + (mcpsdataind->msdulength) . the data field is simply addressed with: mcpsdataind->msdu , and may contain more than one byte even though the array is declared with a size of 1. // type: gmcpsdataind_c, typedef struct mcpsdataind_tag { uint8_t dstaddr[8]; //address as defined by dstaddrmode uint8_t dstpanid[2]; uint8_t dstaddrmode; uint8_t srcaddr[8]; //address as defined by srcaddrmode uint8_t srcpanid[2]; uint8_t srcaddrmode; uint8_t msdulength; // 0-102 uint8_t mpdulinkquality; bool_t securityuse; uint8_t aclentry; uint8_t msdu[1]; // data will start at this byte } mcpsdataind_t;
3-18 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor 3.7.1.4 poll request // type: gmlmepollreq_c, typedef struct mlmepollreq_tag { uint8_t coordaddress[8]; uint8_t coordpanid[2]; uint8_t coordaddrmode; bool_t securityenable; } mlmepollreq_t; 3.7.1.5 poll confirm // type: gnwkpollcnf_c, typedef struct nwkpollcnf_tag { uint8_t status; } nwkpollcnf_t; 3.7.1.6 communications status indication // type: gnwkcommstatusind_c, typedef struct nwkcommstatusind_tag { uint8_t srcaddress[8]; uint8_t panid[2]; uint8_t srcaddrmode; uint8_t destaddress[8]; uint8_t destaddrmode; uint8_t status; } nwkcommstatusind_t;
freescale semiconductor 802.15.4 mac/phy software reference manual, rev. 1.1 3- 19 3.7.2 data example the following is an example of the nwk sending an mcps-data.request to the mcps. it mainly demonstrates how to properly allocate a message buffer, and adding data to the msdu parameter. // send 10 bytes of data to mcps, security is not // enabled so no need to allocate extra space. nwktomcpsmessage_t pmsg = msg_alloc( (sizeof(nwktomcpsmessage_t)-1) + 10); // we want to send an mcps-data.request: pmsg->msgtype = gmcpsdatareq_c; // fill the msdu part of the message with some data. for(i=0; i<10; i++) pmsg->msgdata.datareq.msdu[i] = i; // set the msdu length pmsg->msgdata.datareq.msdulength = 10; // fill in other fields such as destination+source addresses createdatarequestmessageheader(pmsg); // send message to mcps. the mcps will free the message buffer. msg_send(nwk_mcps, pmsg); the following is an example of the nwk recei ving an mcps-data.indication from the mcps. it shows how the mcps to nwk sap handler may be implemented by the application/nwk programmer. // nwk ? receive data indication with 10 bytes of data uint8_t mcps_nwk_saphandler(mcpstonwkmessage_t *pmsg) { switch(pmsg->msgtype) { case gmcpsdataind_c: // handle the incoming data frame for(i=0; i<10; i++) mybuffer[i] = pmsg->msgdata.dataind.msdu[i]; break; case gmcpsdatacnf_c: // the mcps-data.request has completed. check status // parameter to see if the transmission was successful. break; case gmcpspurgecnf_c: // the mcps-purge.request has completed. break; } msg_free(pmsg); // free message asap. return gsuccess_c; } 3.8 purge feature the purge feature allows the next higher layer to purge a data packet (msdu) stored in the mac until it has been sent. this means that if a mcps-data.request primitive with that
3-20 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor msduhandle has been initiated, it is possible to purge the msdu with the given msduhandle , if it has not been sent. initiating the mcps-purge.request primitive and specifying the msduhandle parameter will accomplish the task. a mcps-purge.confirm primitive is generated in response to the mcps-purge.request primitive with the status of success if an msdu matching the given handle is found, or with the status of invalid_handle if an msdu matching the given handle is not found. 3.8.1 purge primitives this section describes the implementation of the purge related primitives. 3.8.1.1 purge request // type: gmcpspurgereq_c, typedef struct mcpspurgereq_tag { uint8_t msduhandle; } mcpspurgereq_t; 3.8.1.2 purge confirm // type: gmcpspurgecnf_c, typedef struct mcpspurgecnf_tag { uint8_t msduhandle; uint8_t status; } mcpspurgecnf_t; 3.9 rx enable feature the rx enable feature allows the network layer to enable the receiver at a given time. the feature is implemented according to the ieee 802.15.4 standard (section 7.1.10). 3.9.1.1 rx enable request // type: gmlmerxenablereq_c, typedef struct mlmerxenablereq_tag { bool_t deferpermit; uint8_t rxontime[3]; uint8_t rxonduration[3]; } mlmerxenablereq_t;
freescale semiconductor 802.15.4 mac/phy software reference manual, rev. 1.1 3- 21 3.9.1.2 rx enable confirm // type: gnwkrxenablecnf_c, typedef struct nwkrxenablecnf_tag { uint8_t status; } nwkrxenablecnf_t; 3.10 guaranteed time slots (gts) feature the guaranteed time slots (gts) feature is a mechanism that allows a device to reserve a certain bandwidth. a gts slot is always unidirec tional and it is always requested by the device. 3.10.1 gts as device it does not make sense for a device to allocate more than one rx slot and one tx slot (although it is possible to do so) because it is impossible for a device to differentiate two tx slots of the same length. analysis yields the following results. ? the mcps-data.request does not support any me thod for selecting between tx slots. ? if the pan coordinator de-allocates or realigns one of the tx slots it is not possible to tell which of the slots were affected. freescale recommends that a device should never allocate more than one gts slot in each direction. refer to the ieee 802.15.4 standard, section 7.5.7 for more information. allocating a gts slot or de-allocating a gts slot is implemented according to the standard. in either case the mlme- gts.request primitive is used. ? allocating : an allocation attempt is initiated by sending the gts request to the pan coordinator. the device then looks for a gts descriptor that matches the requested characteristics in the beacon frames received. once found it is possible to perform gts transfers. ? deallocating : deallocation is very similar. notice that the local gts ?context? is marked as invalid before the request is actually sent to the pan coordinator. any packets that may have been queued for gts transmission are completed with status invalid_gts at this point. the gts deallocation request is then sent to the pan coordinator. there is no guarantee that the pan coordinator receives the request (it may fail with status no_ack or channel_access_failure). this is not critical because the pan coordinator must implement mechanisms to detect ?stale? gts slots. note gts processing is rather intensive and cannot be completed in irq context. the following steps de scribe the procedure for this software implementation.
3-22 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor 1. a beacon frame is received. 2. time critical beacon frame processing is performed. this includes calculating various superframe timing parameters such as the expected end time of the cap and the expected time of the next beacon frame arrival. 3. the gts field of the beacon frame is pre-pr ocessed. pre-processing consists of only one thing: check if the device?s short address is present in the list! an internal flag ( gmlmegtsaccess ) is raised if this is true. 4. the beacon frame is then queued for further processing by higher layer software (the mlme). 5. this completes the beacon processing in irq context. the mlme will asynchronously perform further processing of the beacon frame. this includes generating mlme-beacon.indications messages to the nwk layer. gts processing is performed if the gmlmegtsaccess flag was raised. this includes processing all gts descriptors that matches the short address of the device. the following actions are performed. 1. a new internal gts context is allocated if a gts allocation request was pending and the current gts descriptor matches the requested characteristics. 2. an existing gts slot may have been realigned by the pan coordinator (that is, a new start slot has been defined). the proper internal gts context is updated. 3. an existing gts slot may have been deallocated by the pan coordinator (indicated by a start slot of 0). the proper internal gts context is deallocated. queued data packets are completed with status invalid_gts if applicable. 4. timing parameters for the entire cfp is then calculated. this includes calculating the start and end times for all allocated gts slots. the times are adjusted according to internal setup requirements and clock drift. 5. the gmlmegtsaccess flag is cleared. note these steps are important because the entire cfp of a superframe will be skipped if the gmlmegtsaccess is detected high at the beginning of the cfp. this is needed because the cfp timing parameters are not yet in place. it is also important that the mlme_main() is called in a timely manner.
freescale semiconductor 802.15.4 mac/phy software reference manual, rev. 1.1 3- 23 3.10.2 gts as pan coordinator the pan coordinator will always accept incoming gts requests and it will always allocate the requested gts slot if the minimum length cap can be maintained. a gts slot can occupy 1 to15 superframe slots (assuming that sufficient superframe slots are free). a gts request is denied if the pan coordinator cannot allocate the requested gts slot. note gts processing is rather intensive and cannot be completed in irq context. the following steps de scribe the procedure for this software implementation. 1. a gts request is received in the cap. 2. gmlmegtsaccess is raised. 3. the mac command frame is then queued for further processing by higher layer software (the mlme). 4. this completes gts processing in irq context. as previously stated, the mlme asynchronously performs further processing of the gts request. this includes the following actions. 1. an internal gts context is allocated (if the gts request specified an allocation request) or an existing context is deallocated (if the gts request specified a deallocation request). 2. all gts slots are realigned if a deallocation created ?gaps? in the cfp. 3. timing parameters for the entire cfp is then calculated. this includes calculating the start and end times for all allocated gts slots. the times are adjusted according to internal setup requirements and clock drift. 4. the gmlmegtsaccess flag is cleared. 5. an mlme-gts.indication message is generated (if applicable). note the entire cfp of a superframe will be skipped if the gmlmegtsaccess is detected high at th e beginning of the cfp. this is needed because the cfp timing parameters are not yet in place. it is therefore important that the mlme_main() is called in a timely manner.
3-24 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor users should also be aware that all existing gts sl ots (if any) will be deallocated immediately if the superframe configuration changes ( macbeaconorder or macsuperframeorder is changed). note issuing the mlme-start.reque st primitive updates these two pib attributes. there is no i ndication in the beacon frame indicating this. that is, a device mu st assume that gts slots have been invalidated if the superframe configuration changes. gts expiration is implemented according to the ieee 802.15.4 standard. the pan coordinator deallocates stale slots automatically. the ieee 802.15.4 standard does not specify how to expire a gts slot where data is sent unacknowledged. this implies that the pan coordinator will not receive any acknowledgement frames. the implementation in this case deallocates the gts slot if no data has been transmitted in the slot for the specified number of superframes. for example, ?counting? is based on tx packets and not rx acknowledgements. 3.10.3 miscellaneous items the following items are valid for both device and pan coordinator. ? although possible to allocate a gts slot with length 1 at macsuperframeorder = 0 it is not recommended. this gts slot will only c ontain 60 symbols (30 bytes). as already stated, setup time and overhead for phy and mac headers are at least 21 bytes, so it will not be possible to send or receive any data. a gts slot should at least have length = 2 at macsuperframeorder = 0 (corresponding to 120 symbols). all other superframe orders support gts slots with length 1. as previously stated, it is possible so skip a cfp due to gts maintenance. although this hazard exists, it should have minimal effects because gts slots are (probably) rarely allocated and deallocated (mostly at feature setup and termination). 3.10.4 gts primitives 3.10.4.1 gts request // type: gmlmegtsreq_c, typedef struct mlmegtsreq_tag { bool_t securityenable; uint8_t gtscharacteristics; } mlmegtsreq_t; 3.10.4.2 gts confirm // type: gnwkgtscnf_c, typedef struct nwkgtscnf_tag { uint8_t status;
freescale semiconductor 802.15.4 mac/phy software reference manual, rev. 1.1 3- 25 uint8_t gtscharacteristics; } nwkgtscnf_t; 3.10.4.3 gts indication // type: gnwkgtsind_c, typedef struct nwkgtsind_tag { uint8_t devaddress[2]; bool_t securityuse; uint8_t aclentry; uint8_t gtscharacteristics; } nwkgtsind_t; 3.11 security the mac security functionality is implemented as described in the 802.15.4 standard and in the zigbee security services specification v.092. where a different approach is used between the two, the zigbee security services specification v.092 is followed here. thus, the ccm* security levels are used in place of the security suites described in the 802.15.4 standard. a limitation of the current implementation is that secured beacons will not be processed. secured packets are longer when transmitted over the air than corresponding non-secured packets. besides the increased power consumption and lower maximum throughput, this results in mcps-data.request delivering a gframetoolong_c error code if the resulting packet gets longer than 127 bytes. the maximum msdulength for secured packets depends on the security level, source, and destination addressing modes and whether the source and destination pan id are the same. table 8 shows the overhead added for each security level. table 8. security levels level name encrypted integrity check (length) packet length overhead 0x00 n/a no 0 (no check) 0 0x01 mic-32 no 4 9 0x02 mic-64 no 8 13 0x03 mic-128 no 16 21 0x04 enc yes 0 (no check) 5 0x05 enc-mic-32 yes 4 9 0x06 enc-mic-64 yes 8 13 0x07 enc-mic-128 yes 16 21
3-26 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor 3.11.1 security pib attributes the acl entries are statically allocated. currently four acl entries can be stored in the pib. it is possible to use the security pib attributes as defined in error! reference source not found. with the variation that the aclsecuritymaterial always takes up the maximum (26 decimal) amount of bytes (defaultsecuritymaterial does the same, but that is always accessed directly). it is also possible to write to the contents of the individual acl entries by use of freescale specific security pib attributes, see section 0 . by setting the freescale specific gmacaclentrycurrent_c security attribute to an acl entry index between 0, and 3, it is possible to read and write the individual attributes of the different acl entries without reading/writing the complete acl entry descriptor set at once.
freescale semiconductor 802.15.4 mac/phy software reference manual, rev. 1.1 4-1 chapter 4 app/asp layer interface description this section describes the application (app) / application support package (asp) interface. 4.1 general app/asp interface information the interface between the app and the asp is based on service primitives passed from one layer to the other through a layer service access point (sap). two saps exists, both implemented as functions. 1. zberrorcode_t app_asp_saphandler(void *msg) ; app to asp sap app_asp_saphandler() passes primitives from the app to the asp) 2. zberrorcode_t asp_app_saphandler(void *msg) ; asp to app sap asp_app_saphandler() passes primitives from the asp to the app) the aps_app_saphandler() must be implemented in the application layer by the application developer. the sap handler functions should not be called directly, but through the available macro msg_send(app_asp, msg) . both app and asp service primitives use the same type of messages as defined in the interface header file called appaspinterface.h. the macros are defined in the header file called phymacmsg.h. because the app and asp interfaces are based on messages being passed to a sap, each message needs to have an identifier. these iden tifiers are shown in the two enumerations in table 9 and table 10 . table 9. primitives in the asp to app direction message identifiers asp primitives gaspappwakeind_c asp-wake.indication gaspappidleind_c asp-idle.indication gaspappinactiveind_c asp-inactive.indication gaspappeventind_c asp-event.indication
4-2 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor table 10. primitives in the app to asp direction message identifiers asp primitives gappaspgettimereq_c asp-gettime.request gappaspgetinactivetimereq_c asp-getinactivetime.request gappaspdozereq_c asp-doze.request gappaspautodozereq_c asp-autodoze.request gappasphibernatereq_c asp-hibernate.request gappaspwakereq_c asp-wake.request gappaspeventreq_c asp-event.request gappasptrimreq_c asp-trim.request gappaspddrreq_c asp-ddr.request gappaspportreq_c asp-port.request gappaspclkoreq_c asp-clko.request gappaspsetnotifyreq_c asp-setnotify.request aspsetmindozetimereq_t asp- set-min-doze-time.request the following two sections describe the c-structures which correspond to the message identifiers shown in this section. a common feature of all structures is that all elements of a size greater than 1 byte are little endian and declared as byte arrays. 4.2 asp to app interface the following structures are used for the messages that go from the asp to the app. see the message identifier enumeration list for implemented primitives. all confirm primitives are returned in the same structure as used for the corresponding request. all indication primitives are sent in messages that must be freed by msg_free() . 4.2.1 get time confirm this structure contains the result of the asp- gettime.request. the result is the current value of the mc13192 24 bit event timer (0x000000 to 0xffffff) as a little endian byte array. the status code is always gsuccess_c . // type: gaspappgettimecfm_c typedef struct appgettimecfm_tag { uint8_t status; uint8_t time[3]; } appgettimecfm_t;
freescale semoconductor 802.15.4 mac/phy software reference manual, rev. 1.1 4-3 4.2.2 get inactive time confirm the get inactive time primitive will only yield valid results when called during the inactive portion of a super frame, and mc13192 is not in doze, or hibernate mode. otherwise, the status parameter will be ginvalidparameter_c . // type: gaspappgetinactivetimecfm_c typedef struct appgetinactivetimecfm_tag { uint8_t status; uint8_t time[3]; } appgetinactivetimecfm_t; 4.2.3 doze confirm the asp-doze.request primitive specifies the duration in symbols that the mc13192 must doze. if the mc13192 is idle, the requested doze duration is granted and the actualdozeduration parameter is the same as the time requested. however, if the mc13192 has a wait action running with a duration shorter than the requested duration, the mc13192 will doze until the wait action completes. the actualdozeduration parameter will be the difference of the requested doze duration and the end time of the timer action. if doze mode is not possible because the mc13192 is busy, the status parameter is ginvalidparameter_c . // type: gaspappdozecfm_c typedef struct appdozecfm_tag { uint8_t status; uint8_t actualdozeduration[3]; } appdozecfm_t; 4.2.4 auto doze confirm the auto-doze confirm status is always gsuccess_c . // type: gaspappautodozecfm_c typedef struct appautodozecfm_tag { uint8_t status; } appautodozecfm_t; 4.2.5 hibernate confirm the hibernate confirm status is gsuccess_c if the mc13192 is in idle mode. otherwise the return code is ginvalidparameter_c . // type: gaspapphibernatecfm_c typedef struct apphibernatecfm_tag { uint8_t status; } apphibernatecfm_t;
4-4 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor 4.2.6 wake confirm the wake confirm status is always gsuccess_c . // type: gaspappwakecfm_c typedef struct appwakecfm_tag { uint8_t status; } appwakecfm_t; 4.2.7 event confirm the event confirm message returns the status of the event request primitive. if the mac was idle the status parameter is gsuccess_c , otherwise it is ginvalidparameter_c . // type: gaspappeventcfm_c typedef struct appeventcfm_tag { uint8_t status; } appeventcfm_t; 4.2.8 trim confirm the trim confirm status is always gsuccess_c . // type: gaspapptrimcfm_c typedef struct apptrimcfm_tag { uint8_t status; } apptrimcfm_t; 4.2.9 ddr confirm the ddr confirm status is always gsuccess_c . // type: gaspappddrcfm_c typedef struct appddrcfm_tag { uint8_t status; } appddrcfm_t; 4.2.10 port confirm the port confirm status is always gsuccess_c . // type: gaspappportcfm_c typedef struct appportcfm_tag { uint8_t status; uint8_t portresult; } appportcfm_t;
freescale semoconductor 802.15.4 mac/phy software reference manual, rev. 1.1 4-5 4.2.11 clko confirm the clko confirm message returns the status of the clko request primitive. if an invalid paramter was passed the status parameter is ginvalidparameter_c , otherwise it is gsuccess_c . // type: gaspappclkocfm_c typedef struct appclkocfm_tag { uint8_t status; } appclkocfm_t; 4.2.12 set notify confirm returns the status of the asp-setnotify.request . if beacons are part of the mac feature set the status is always gsuccess_c . otherwise the return code is ginvalidparameter_c . // type: gaspappsetnotifycfm_c typedef struct appsetnotifycfm_tag { uint8_t status; } appsetnotifycfm_t; 4.2.13 set min doze time confirm the set min doze time confirm status is always gsuccess_c . // type: gaspappsetnotifycfm_c typedef struct appsetnotifycfm_tag { uint8_t status; } appsetnotifycfm_t; 4.2.14 wake indication the asp-wake.indication primitive is sent to the app when the mc13192 comes out of doze or hibernate mode. if auto doze is enabled by issuing the asp-autodoze.request with the enablewakeindication , and the autoenable parameters set to true, then wake indications are sent to the app each time auto doze switches from doze to active mode. auto doze may place the mc13192 in doze mode again after the wake indication has been processed by the asp_app sap. thus, the app has the oppertunity to disable auto doze or change the parameters at this time by sending an asp-autodoze.request with the new set of parameters. remember to free this message by calling msg_free() . // type: gaspappwakeind_c typedef struct appwakeind_tag { uint8_t status; } appwakeind_t;
4-6 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor 4.2.15 idle indication this indication is sent to the app if enabled by the asp-setnotify.request, and the mac is operating in beaconed mode. the indication is sent at the start of the idle portion of the super frame. the timeremaining parameter is the number of symbols left of the cap. if macrxonwhenidle is true the cap idle state does not exist, and no idle indications will be sent. remember to free this message by calling msg_free() . // type: gaspappidleind_c typedef struct appidleind_tag { uint8_t timeremaining[3]; } appidleind_t; 4.2.16 inactive indication this indication is sent to the app if enabled by the asp-setnotify.request, and the mac is operating in beaconed mode. the indication is sent at the start of the inactive portion of the super frame. the timeremaining parameter is the number of symbols left in the inactive period. remember to free this message by calling msg_free() . // type: gaspappinactiveind_c typedef struct appinactiveind_tag { uint8_t timeremaining[3]; } appinactiveind_t; 4.2.17 event indication this indication is sent to the app when the requested event has expired. remember to free this message by calling msg_free() . // type: gaspappeventind_c typedef struct appeventind_tag { uint8_t dummy; // this primitive has no parameters. } appeventind_t;
freescale semoconductor 802.15.4 mac/phy software reference manual, rev. 1.1 4-7 4.2.18 asp to app message union // asp to application message typedef struct asptoappmsg_tag { uint8_t msgtype; union { appgettimecfm_t appgettimecfm; appgetinactivetimecfm_t appgetinactivetimecfm; appdozecfm_t appdozecfm; appautodozecfm_t appautodozecfm; apphibernatecfm_t apphibernatecfm; appwakecfm_t appwakecfm; appeventcfm_t appeventcfm; apptrimcfm_t apptrimcfm; appddrcfm_t appddrcfm; appportcfm_t appportcfm; appclkocfm_t appclkocfm; appsetnotifycfm_t appsetnotifycfm; appwakeind_t appwakeind; appidleind_t appidleind; appinactiveind_t appinactiveind; appeventind_t appeventind; } msgdata; } asptoappmsg_t; 4.2.19 examples of asp to app messages this section shows examples of how the app layer should process incoming messages. the examples are not guaranteed to compile because they may contain pseudo code for clarity. only indications must be handled by the app sap. because asp requests are performed synchronously, the confirm messages are returned in the message buffer used for the requests, and does thus not end up in the app sap. example #1: handle wake indications // app must have its own sap handler: uint8_t asp_app_saphandler(asptoappmsg_t *pmsg) { // declared somewhere else extern bool_t weareautodozing; // check which indication was received. switch(pmsg->msgtype) { case aspappwakeind_t: if(weareautodozing == true) { // awoke while auto doze was active. now do some // processing (put data in queue etc.) before mc13192 // is re-entering doze mode. dosomethingwhileawake(); // when returning from here, mc13192 enters doze mode asap. } else { // mc13192 came out of normal doze or hibernate mode. } break; case aspappidleind_t: // asp-setnotify.request(gaspnotifyidle_c) was issued. break;
4-8 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor case aspappinactiveind_t: // asp-setnotify.request(gaspnotifyinactive_c) was issued. break; case aspappeventind_t: // asp-event.request(time) was issued. break; } // always free incoming messages. msg_free(pmsg); return gsuccess_c; } 4.3 app to asp interface the following structures are used for the messages that go from the app to the asp. see the message identifier enumeration list in table 10 for implemented primitives. none of the requests in this section are freed by the asp layer. thus, the app layer does not need to use msg_alloc() for obtaining a buffer for the asp message. notice that the asp layer will modify the message to contain the confirm-primitive corresponding to the request. 4.3.1 get time request this primitive returns the current value of the mc13192 event timer. see section 4.2.1 for information about the returned value. // type: gappaspgettimereq_c typedef struct aspgettimereq_tag { uint8_t dummy; // this primitive takes no parameters } aspgettimereq_t; 4.3.2 get inactive time request this primitive will request the remaining time in the inactive portion of the super frame. see section 4.2.2 for information about the returned value. // type: gappaspgetinactivetimereq_c typedef struct aspgetinactivetimereq_tag { uint8_t dummy; // this primitive takes no parameters } aspgetinactivetimereq_t;
freescale semoconductor 802.15.4 mac/phy software reference manual, rev. 1.1 4-9 4.3.3 doze request shut down the mc13192 for a given amount of time in symbols. the clko output pin will stop providing a clock signal to the cpu. the dozeduration parameter is the maximum time in number of symbols that the mc13192 will be in doze mode. the mc13192 can be woken up prematurely from doze mode by a signal on the attn pin or if a wait action expires in the mac. clko is automatically started again when mc13192 leaves doze mode. // type: gappaspdoze_c typedef struct aspdozereq_tag { // doze duration in little endian 24 bit symbol time (1symbol=16us) uint8_t dozeduration[3]; } aspdozereq_t; 4.3.4 auto doze request automatically shut down the mc13192 during idle periods or if the mac is in executing a wait action. the clko output pin will stop providing a clock signal to the cpu. the autodozeinterval parameter is a suggested period in symbols in which the mc13192 will be in doze mode. this interval may be overridden if doze mode is interrupted by an external signal (attn pin) or if a wait action expires in the mac. if the enablewakeindication parameter is true then an asp-wake.indication is sent to the app layer each time the doze interval expires. the indication can be used by the app layer to do processing. in order to enable auto doze the autoenable parameter must be true. auto doze can be disabled by sending another asp-autodoze.request with the autoenable parameter set to false. it is recommended to use the asp-wake. indication for simple processing during auto doze since it will occur frequently (if enabled) and the auto doze feature is blocked during the processing of the indication in the asp_app sap. // type: gappaspautodoze_c typedef struct aspautodozereq_tag { bool_t autoenable; bool_t enablewakeindication; uint8_t autodozeinterval[3]; } aspautodozereq_t; 4.3.5 hibernate request the hibernate request shuts down the mc 13192. the clko output pin will stop providing a clock signal to the cpu. only a signal on the attn pin of the mc13192 or a power loss can bring the mc13192 out of hibernate mode. clko is automatically started again when mc13192 leaves hibernate mode. the hibernate mode is not adequate for beaconed operation. doze mode should be used instead when mc13192 timers are required. // type: gappasphibernate_c typedef struct asphibernatereq_tag { uint8_t dummy; // this primitive takes no parameters } asphibernatereq_t;
4-10 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor 4.3.6 wake request wake-up the mc13192 from doze/hibernate mode. // type: gappaspwake_c typedef struct aspwakereq_tag { uint8_t dummy; // this primitive takes no parameters } aspwakereq_t; 4.3.7 event request this primitive can be used to schedule a notification for an application event. the primitive is a single instance event. if there is any c onflict with the mac operation a status of ginvalidparameter_c is returned, otherwise a status of gsuccess_c is returned. the eventtime parameter is a 3-byte little endian integer symbol time. // type: gappaspeventreq_c typedef struct aspeventreq_tag { uint8_t eventtime[3]; } aspeventreq_t; 4.3.8 trim request this primitive sets the trim capacitor value for the mc13192. upon receipt of the request, the trim capacitor value contained in the 8-bit parameter is programmed to the mc13192. // type: gappasptrimreq_c typedef struct asptrimreq_tag { uint8_t trimvalue; } asptrimreq_t; 4.3.9 ddr request this primitive sets the gpio data direction. gpios 3-7 are programmed as outputs if the respective bit in mask is a logical 1, otherwise they are programmed as inputs. bits 0,1 and 2 of mask are ignored. // type: gappaspddrreq_c typedef struct aspddrreq_tag { uint8_t directionmask; } aspddrreq_t;
freescale semoconductor 802.15.4 mac/phy software reference manual, rev. 1.1 4-11 4.3.10 port request this primitive reads or writes the gpio data register. portwrite is a boolean value. if true, the respective bits in portvalue will be programmed to the gpio data register (only bits 3-7 are valid). // type: gappaspportreq_c typedef struct aspportreq_tag { uint8_t portwrite; uint8_t portvalue; } aspportreq_t; 4.3.11 clko request this primitive sets and/or enables the clko output of the mc13192. if clkoenable is true, clko is made active, otherwise it is disabl ed. the clko output frequency is programmed depending upon the value contained in clkorate per the clko frequency selection of the mc13192. if an invalid parameter is passed, a status of ginvalidparameter_c is returned, otherwise a status of gsuccess_c is returned. // type: gappaspclkoreq_c typedef struct aspclkoreq_tag { bool_t clkoenable; uint8_t clkorate; } aspclkoreq_t; 4.3.12 set notify request this primitive controls the indications generated in beaconed operation. the notifications parameter can be any of the following four values: 1. gaspnotifynone_c no indications are sent to the app layer. 2. gaspnotifyidle_c asp-idle indication (see section 4.2.15 ) is sent. 3. gaspnotifyinactive_c asp-inactive indication (see section 4.2.16 ) is sent. 4. gaspnotifyidleinactive_c asp-idle, and asp-inactive indications are sent. if the mac pib attribute macrxonwhenidle is set then no idle indications are sent. // type: gappaspsetnotifyreq_c typedef struct aspsetnotifyreq_tag { uint8_t notifications; } aspsetnotifyreq_t;
4-12 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor 4.3.13 set min doze time request set the default minimum doze time. if the allowed doze duration during a mem wait action is smaller than the minimum doze duration, then the mc13192 will not be put in to doze mode. // type: gappaspsetmindozetimereq_c typedef struct aspsetmindozetimereq_tag { uint8_t mindozetime[3]; // should be > 2ms ((2*1000)/16 = 125) // default is 4ms. } aspsetmindozetimereq_t; 4.3.14 app to asp message union use the aspmsg_t structure for asp requests instead of the following apptoaspmsg_t structure because the request buffer will contain the conf irm message after returning from the app_asp sap function call (msg_send(app_asp, pmsg) ) . see section 4.3.15 for examples of sending asp requests and receiving the corresponding confirm messages. // app to asp message typedef struct apptoaspmsg_tag { uint8_t msgtype; union { aspgettimereq_t aspgettimereq; aspgetinactivetimereq_t aspgetinactivetimereq; aspdozereq_t aspdozereq; aspautodozereq_t aspautodozereq; asphibernatereq_t asphibernatereq; aspwakereq_t aspwakereq; aspeventreq_t aspeventreq; asptrimreq_t asptrimreq; aspddrreq_t aspddrreq; aspportreq_t aspportreq; aspclkoreq_t aspclkoreq; aspsetnotifyreq_t aspsetnotifyreq; aspsetmindozetimereq_t aspsetmindozetimereq; } msgdata; } apptoaspmsg_t; it is recommened to use the following structure for sending requests to the asp layer instead of the apptoaspmsg_t structure above. // app to asp, and asp to app union. typedef union aspmsg_tag { uint8_t msgtype; apptoaspmsg_t apptoaspmsg; asptoappmsg_t asptoappmsg; } aspmsg_t;
freescale semoconductor 802.15.4 mac/phy software reference manual, rev. 1.1 4-13 4.3.15 examples of app to asp messages this section provides examples of how to interact with the asp layer. the examples are not guaranteed to compile because they may contain pseudo code for clarity. example #1: getting the current mc13192 clock. // app layer must allocate a message aspmsg_t aspgettime; uint8_t gettimestat; uint8_t currenttime[3]; // set the type. aspgettime.msgtype = gappaspgettimereq_c; // send the request to the asp sap. the ?gettimestat? // variable can be omitted because the confirm message // contains a copy of the status. gettimestat = msg_send(app_asp, &aspgettime); // now aspgettime contains an appgettimecfm_t structure. // aspgettime.msgtype will be gaspappgettimecfm_c. // aspgettime.asptoappmsg.appgettimecfm.status is equal // to gettimestat; // do something with the received time value. copy(currenttime, aspgettime.asptoappmsg.appgettimecfm.time); example #2: start auto doze. // app layer must allocate a message aspmsg_t aspautodoze; aspautodozereq_t *pautodozereq; bool_t weareautodozing = false; pautodozereq = &aspautodoze.apptoaspmsg.aspautodozereq; // set the type. aspautodoze.msgtype = gappaspautodozereq_c; // in this example asp-wake.indications are enabled, // and doze interval is 5 seconds ((5*1000000)/16 = 125000 // symbols = 0x04c4b4). it is recommended that scans and // network formation has been carried out before entering // auto doze if possible. pautodozereq->autoenable = true; pautodozereq->enablewakeindication = true; // values greater than 1 byte must be little endian byte arrays. pautodozereq->autodozeinterval[0] = 0xb4; pautodozereq->autodozeinterval[1] = 0x4c; pautodozereq->autodozeinterval[2] = 0x04; // send the request to the asp sap. msg_send(app_asp, &aspautodoze); // now aspautodoze contains an appautodozecfm_t structure. // aspautodoze.msgtype will be gaspappautodozecfm_c. if(aspautodoze.asptoappmsg.appautodozecfm.status == gsuccess_c) { weareautodozing = true; }
4-14 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor
freescale semiconductor 802.15.4 mac/phy software reference manual, rev. 1.1 5-1 chapter 5 parametric information the following list shows the main parametric information for the freescale ieee 802.15.4 mac/phy software. 1. the mcu must run at a minimum clock frequency of 16 mhz to fulfill the 802.15.4 standard timing requirement for all 802.15.4 standard features. 2. within a period of 64s, the application must disable the mc13192 interrupts for a maximum duration of 10 s. 3. the frequency of the spi that connects the hcs08 mcu to the mc13192 must be half of the hcs08 clock speed.
5-2 802.15.4 mac/phy software reference manual, rev. 1.1 freescale semiconductor

▲Up To Search▲

Price & Availability of 802154MPSRM

	To Download 802154MPSRM Datasheet File
If you can't view the Datasheet, Please click here to try to view without PDF Reader .