AVR2102: RF4Control User Guide AVR2102 V 2 0 1
AVR2102_User_Guide_v_2_0_1
AVR2102_User_Guide_v_2_0_1
User Manual: Pdf
Open the PDF directly: View PDF .
Page Count: 91
Download | |
Open PDF In Browser | View PDF |
AVR2102: RF4Control - User Guide Features • • • • • • • • • • • • • • • • RF4Control is the Atmel ZigBee RF4CE Certified Platform Architecture overview APIs: Network, ZRC Profile, ZID Profile. ZRC Example application: Button Controller and Single Button Controller ZRC Example application: Terminal Target ZID Example application: ZID Device, USB HID Keyboard, Mice, AVR477 QTouch Remote, Terminal Adaptor, Key Remote Device Example application: RF4CE Network Serial Interface, ZRC Serial Interface, ZID Serial Interface. Transceiver support – 2.4 GHz: Atmel AT86RF231 and AT86RF233 Transceiver support – 900MHz: Atmel AT86RF212, AT86RF212B MCU support: Atmel’s ATxmega256a3 and ATxmega256a3bu, ATxmega256a3u MCU support: AT32UC3A3256S MCU support: Atmel’s ATmega256RFR2,ATSAMR21G18A MCU support: ATSAM4L Bootloader support for ATmega256RFR2 Watchdog support. NVM Multi-write Support for ATmega256RFR2 Atmel MCU Wireless Solutions Application Note 1 Introduction This document is the user guide for the Atmel® RF4Control software stack. The RF4Control stack is a ZigBee® RF4CE Certified Platform implementing the ZigBee RF4CE standard [11]. The RF4Control stack is used with Atmel microcontrollers and IEEE ® 802.15.4 transceivers. Some microcontrollers, such as the Atmel AT xmega56a3 [6], are used for reference implementations. Other Atmel microcontrollers can be used based on the application requirements. The ZigBee RF4CE specification makes use of the 2.4GHz band, and Atmel IEEE 802.15.4 transceivers, such as the Atmel AT86RF231, AT86RF233 [4], support the 2.4GHz band. In addition, the RF4Control stack supports the sub-1GHz bands, as defined in the IEEE 802.15.42006 standard [1], with the Atmel AT86RF212 [3]. For applications requiring the use of a single-chip implementation (transceiver and microcontroller SoC), the Atmel megaRF family provides such a single-chip solution. As a reference, the ATmega256RFR2 [5] is used. This user guide introduces the RF4Control architecture and its implementation in section 2. Based on the stack, several example applications are implemented demonstrating the use of the stack‟s functionality and APIs. Chapter 3 describes the example applications. Remote controlling is the main application area for RF4CE, and the Example applications section introduces a few application examples (Terminal Target and Key Remote Controller). Section 3.1.3 introduces a Single Button Controller example application and walks through its implementation. The Key Remote Controller, Rev. 8357D-AVR-02/13 which uses the ATmega128RFA1 Radio Controller Board (RCB), is a certified ZigBee Remote Control application. The software stack provides an API that is aligned with the RF4CE network primitives, and which can be used directly from an application or firmware. A serial interface API is also provided. The serial interface API can be used for communication where the Atmel RF4CE stack is hosted on a separated communication microcontroller and controlled by an additional microcontroller via, for 2 example, a UART, SPI or I C serial interface. The serial interface approach is described in section 0. An example application demonstrates using the serial interface API with an UART interface (see section 3.3.6). When working with the RF4Control stack, it is highly recommended to use the ZigBee RF4CE specification version 1.01 [12]. Terms used throughout this document are based on the ZigBee RF4CE specification. The ZigBee RF4CE also specified a profile for remote control applications – ZigBee Remote Control Profile (ZRC) [13]. Use this specification also as an additional source of information. The RF4Control-ZID stack is used with Atmel microcontrollers and IEEE®802.15.4 transceivers. The ZigBee RF4CE specification makes use of the 2.4GHz band, and Atmel IEEE 802.15.4 transceivers, such as the Atmel AT86RF231 AT86RF233, support the 2.4GHz band. This user guide also introduces the RF4Control-ZID architecture and its implementation in Section 2.3. Based on the stack, one example application is implemented demonstrating the use of the stack‟s functionality and APIs. Chapter $ describes the example application. The ZigBee RF4CE also specified a profile for HID devices - ZigBee Input Device Profile (ZID). Use this specification also as an additional source of information.[14] 1.1 Remote controlling Remote controlling is the main application scope of the RF4CE standard. The first profile published (ZigBee Remote Control profile, ZRC [13]) addresses the remote controlling of consumer goods. The RF4Control package contains a remote control example application in which one board represents a TV (target node) while the other board represents a remote controller (controller node). The end-user applications on both boards use the ZRC profile, as defined by the RF4CE specification. A typical RF4CE network example is shown in Figure 1-1. 2 AVR2102 8357D-AVR-06/12 AVR2102 Figure 1-1. RF4CE network topology example. Source: ZigBee RF4CE [11] Nodes can be made known to each other using a procedure called pairing. The ZRC profile specification describes an automated/simplified pairing procedure, called push button pairing, between a target node and a controller node. Besides the pairing procedure, the profile points to the HDMI specification [15] for the actual controller command codes (CEC – Consumer Electronics Control). 1.2 HID Class Device The RF4Control Package contains a ZID USB HID Adaptor application in which adaptor act as HID Multimedia Keyboard and Mice, On the other end Key remote controller will act as ZID HID Class Device. Which it sends the key board, mice and mutitouch report to paired adaptor. ZID Profile uses push button pairing procedure. 2 RF4Control – Stack implementation 2.1 Architecture The Atmel RF4Control stack uses the Atmel IEEE 802.15.4 MAC as the underlying layer. For detailed information about the MAC layer, see the AVR2025 MAC Software Package [7]. Figure 2-1 shows the software architecture used for RF4Control implementation.Figure 2-1. RF4Control software stack architecture. stack The end-user application accesses the RF4CE network layer directly for initialization and configuration. If the ZRC profile is part of the configuration, the ZRC profile functions support the initialization and data exchange. If the ZID profile is part of the configuration, ZID Profile functions support the initialization and data exchange. The Atmel MAC software implementation is modular, allowing different hardware to be used for RF4CE applications. The microcontroller and board are interfaced using 3 8357D-AVR-06/12 the Platform Abstraction Layer (PAL). The transceiver is interfaced using the Transceiver Abstraction Layer (TAL). For further information about these layers, see the MAC software package user guide [7]. 2.2 ZigBee Remote Control profile The ZigBee Remote Control (ZRC) profile defines the protocol (structure and sequence of communication messages) between a ZRC-compliant remote control (RC) device and a ZRC-compliant target device, such as a TV, DVD, etc. The ZRC profile is specified by [13]. Compared to the RF4CE network specification [12], the ZRC profile specification does not define primitives as Service Access Points (SAP). Therefore the primitives descriptions cannot be used as RF4Control API descriptions as is done within the network specification. The RF4Control API for the ZRC profile is described within the following sections. For detailed information about the API function, see also the reference manual provided in HTML format in section 2.6. 4 AVR2102 8357D-AVR-06/12 AVR2102 The ZRC profile interfaces to the RF4CE network layer to make use of the network‟s standardized pairing and data transmission mechanisms. The pairing mechanism specified by the ZRC profile is called push button pairing (PBP), and it includes the discovery and pairing mechanisms. Push Button Pairing is described in section 2.2.1. The ZRC profile also defines RC command discovery and RC command handling procedures. These procedures are described in sections 2.2.2 and 2.2.3, respectively. In general, ZRC profile features are included in the firmware build if the ZRC_PROFILE flag is defined within the Makefile or the IAR™ project file. Section 2.7 provides an overview of the build configuration. 2.2.1 Push button pairing The push button pairing procedure uses and combines the discovery and pairing mechanisms of the RF4CE network layer. After getting a user stimulus (Button Press or PBP API call) on the controller, the PBP procedure automatically starts a discovery procedure. The target device enters the auto-discovery response mode if triggered by a Button Press or PBP API call. Once the discovery is successful, it automatically starts the pairing procedure. Dedicated PBP API functions are used by the target and controller nodes. Some PBP API function parameters are used for discovery, and the remaining ones are used for the actual pairing. Table 2-1 lists them for the target and Table 2-2 lists them for the controller as implemented by the RF4Control stack. They are declared in the pb_pairing.h header file. The PBP functionality is included in the firmware build if the PBP_ORG/PBP_REC flag is defined within the Makefile or the IAR project file. If the PBP_ORG/PBP_REC flag is set, the PBP API functions are included and the discovery and pairing API functions are hidden from the higher layers. The discovery and pairing functions are used by the PBP implementation. The discovery and pairing API functions are exposed to the application if PBP_REC/PBP_ORG is not set. Section 2.7 provides an overview of the build configuration. Table 2-1. Push button pairing API – target side. API function pbp_rec_pair_request (RecAppCapabilities, RecDevTypeList, RecProfileIdList, pbp_rec_pair_confirm) Description Push button pairing recipient request: Initiates the push button pairing on the target side. Internally, the target starts the autodiscovery procedure. After successful discovery, it handles the incoming pairing request. RecAppCapabilities: The application capabilities of the target node (the device number and profile type supported by the target node). RecDevTypeList: The list of the supported device types. RecProfileIdList: The list of the supported profile types. pbp_rec_pair_confirm: Confirmation callback for the request 5 8357D-AVR-06/12 API function pbp_allow_pairing (Status, SrcIEEEAddr, OrgVendorId, OrgVendorString, OrgUserString, KeyExTransferCount) Description Push button pairing allow pairing: Provides information to the target application about the incoming pairing request from the controller node. The application placed on the target can decide whether or not to allow pairing based on this information. Status: Status of the pair indication; here NWK_SUCCESS or NWK_DUPLICATE_PAIRING. SrcIEEEAddr: IEEE address of the device (controller) requesting to pair. OrgVendorId: Vendor identifier of the device (controller) requesting to pair. OrgVendorString: Vendor string of the device (controller) requesting to pair. OrgUserString: User string of the device (controller) requesting to pair. pbp_rec_pair_confirm (Status, PairingRef) KeyExTransferCount: Key exchange transfer count of the incoming pair request. Push button pairing confirm: This callback function provides the status of the push button pairing request. Status: Status of the push button pairing procedure. PairingRef: If pairing was successful, it contains the assigned pairing reference. Table 2-2. Push button pairing API – controller side. API Function pbp_org_pair_request (OrgAppCapabilities, OrgDevTypeList, OrgProfileIdList, SearchDevType, DiscProfileIdListSize, DiscProfileIdList, pbp_org_pair_confirm) Description Push button pairing originator pair request: Initiates the push button pairing on the controller side. Internally, the controller starts the discovery procedure. After a successful discovery, it automatically sends the pairing request to the target. OrgAppCapabilities: Application capabilities of the controller node. OrgDevTypeList: The list of the supported device types. OrgProfileIdList: The list of the supported profile types. SearchDevType: The device type that the controller is looking for (i.e., a TV). DiscProfileIdListSize: The size of the DiscProfileIdList (the next parameter). pbp_org_pair_confirm (Status, PairingRef) DiscProfileIdList: The list of profile identifiers against which profile identifiers contained in the received discovery response will be matched. pbp_org_pair_confirm: Confirmation callback for the request Push button pairing pair confirm: This callback function provides the status of the push button pairing request. Status: Status of the push button pairing procedure. PairingRef: If pairing was successful, PairingRef contains the assigned pairing reference. 6 AVR2102 8357D-AVR-06/12 AVR2102 2.2.2 Command discovery The command discovery procedure enables a target or controller to query the CEC commands supported by the other node. The other node can respond by sending a command discovery response frame containing a bitmap of its supported CEC commands. The command discovery API is described in Table 2-3. The command discovery functionality is included in the firmware build if the ZRC_CMD_DISCOVERY flag is defined within the Makefile or the IAR project file. Section 2.7 provides an overview of the build configuration. Table 2-3. ZigBee remote control command discovery APIs. API Function zrc_cmd_disc_request (PairingRef, zrc_cmd_disc_confirm) zrc_cmd_disc_confirm (Status, PairingRef, SupportedCmd zrc_cmd_disc_indication (PairingRef) zrc_cmd_disc_response (PairingRef, SupportedCmd) Description Sends command discovery request command to other node. PairingRef: The pairing reference for the other node obtained during the push button pairing procedure. zrc_cmd_disc_confirm: Confirmation callback for the request This callback function provides the status and supported command information from the other node. Status: Status of the command discovery request. SupportedCmd: The CEC commands that the responding node supports. Indicates to the sending device that a command discovery request is received. PairingRef: The pairing reference of the originator node. Allows a device to respond to an incoming command discovery request frame. PairingRef: The pairing reference of the originator node. SupportedCmd: The CEC commands that this node supports. 2.2.3 RC command handling RC command handling allows a controller node to send the RC command (CEC) to a target node to perform the specified operation. For example, when a user presses a “channel up” button on the remote controller, it sends a command over the air to the target device (such as a TV) to increment the channel. Three types of over-the-air commands are defined in the ZRC specification: 1. PRESSED command – When a user presses an RC button, the PRESSED command is sent to the target 2. REPEATED command – If the user holds down a remote key for some time, multiple REPEATED commands can be sent to the target 3. RELEASED command – To stop the operation of a target device (TV, for example), the user releases the pressed RC button and a RELEASED command is sent The Button Controller application example supports this command types, while the Single Button Controller application example uses only the PRESSED command type. The REPEATED and RELEASED functionality is excluded from the firmware build if the ZRC_BASIC_PRESS_ONLY flag is defined within the Makefile or the IAR project file. If the ZRC_BASIC_PRESS_ONLY compiler switch is set, only the basic PRESSED functionality is supported by the implementation. Section 2.7 provides an overview of the build configuration. 7 8357D-AVR-06/12 The API for sending the commands is shown in Table 2-4. Table 2-4. RC command APIs. API Function Description zrc_cmd_request (PairingRef, VendorId, CmdCode, CmdLength, Cmd, TxOptions, zrc_cmd_confirm) Initiates the RC command request (key code) by the application. PairingRef: The pairing reference for the other node. VendorId: Vendor identifier; only use if vendor data transmit option is set. CmdCode: Specifies a command code. This could be a PRESSED command (device menu, for example) or a REPEATED command (volume up, for example). CmdLength: Length of the command payload. Cmd: Contains the CEC command and payload (if anything). TxOptions: Tx options, as defined in the RF4CE network layer specification. zrc_cmd_confirm: Confirmation callback for the request zrc_cmd_confirm (Status, PairingRef, RcCmd) Provides the confirmation of a command request to application. Status: Status of the RC command request. PairingRef: The pairing reference for the other node. RcCmd: The RC (CEC) command to be sent. zrc_cmd_indication (PairingRef, nsduLength, nsdu, RxLinkQuality, RxFlags) Indicates that an RC command request command has been received. PairingRef: The pairing reference of the originator node. nsduLength: The length of the received RC command. nsdu: RC command payload. RxLinkQuality: Received link quality. RxFlags: Rx flags, as defined in the RF4CE network layer specification. 2.3 ZigBee Input Device profile The RF4CE ZID profile defines the over-air commandsand mechanisms required to allow a Human Interface Device (HID) class device to communicate with a host. The profile defines two types of device: a HID class device and a HID adaptor. The HID class device can be used to support devices such as keyboards, mice or touchpads and the HID adaptor can be used to communicate through a HID class driver to some PC or other embedded host. 8 AVR2102 8357D-AVR-06/12 AVR2102 Figure - ZID class device and Adaptor architecture Compared to the RF4CE network specification, the ZID profile specification does not define primitives as Service Access Points (SAP). Therefore the primitives descriptions cannot be used as RF4Control API descriptions as is done within the network specification. The RF4Control API for the ZID profile is described within the following sections. The ZID profile specification uses the GDP profile for pairing and configuration phase. GDP will use push button pairing protocol between an adaptor node and a class device node In general, ZID profile features are included in the firmware build if the ZID_PROFILE flag is defined within the Makefile or the IAR™ project file. 2.3.1 Push button pairing Refer section 2.2.1 for more information. 2.3.2 Configuration phase Figure – Configuration between adaptor and class device 9 8357D-AVR-06/12 The configuration phase enables the HID class device to get the attributes from HID adaptor to check the compatibility with the adaptor and it also pushes its attributes to the adaptor. Adaptor will use these attributes to populate the required descriptors for the communication with the HID class driver. 2.3.3 ZID Command Handling ZID command handling allows class device & adaptor to send the report to each other. Apart from this, the adaptor can request the class device for the report. Three types of ZID commands are defined in the ZID specification: 1. GET_REPORT command – Adaptor can request the device for the report 2. REPORT_DATA command – Sending the report to the other node 3. SET_REPORT command – Adaptor can set the report at device side. It is also 10 AVR2102 8357D-AVR-06/12 AVR2102 used by the device to set the NULL report during the configuration phase. Report data will be sent out by the class device to the adaptor which is then forwarded to the HID class driver to perform the specified operation. For example, when a mouse (class device) sends the mouse report data to the adaptor and the response can be seen at HID class driver side. The sample ZID device application example demonstrates how the application can send out the report using the ZID profile API. 2.4 Channel agility The RF4CE standard‟s frequency agility mechanism can be used to overcome a jammed RF channel scenario. Although, the standard specification refers to frequency agility, in reality channel agility is meant. In the context of the RF4Control stack, the term “channel agility” is used. The following paragraphs describe the design constraints and the implementation / usage of the channel agility mechanism to supplement the RF4CE standard. To detect a channel compromised by an external source of interference, a mechanism called energy detection (ED) is employed. This functionality is provided by the MAC layer, and is operated via ED scans. During ED scans the device cannot receive any frames. Long or frequent scans result in dead times. To avoid long offline durations, the most recently used channel (Base Channel) is scanned first. If the measured channel energy exceeds the maximum ED threshold, all three channels are scanned in sequence, and the channel with the lowest energy is set as the new Base Channel. The Atmel RF4Control stack provides a set of API functions allowing the user to control the usage and behavior of the ED scans in the context of channel agility. Table 2-5 lists the API functions and their parameters that can be used to control the channel agility mechanism. The channel agility feature needs to be started by the application using the nwk_ch_agility_request() API function, and it is then handled automatically by the stack. The channel agility API functions are included in the build process if the CHANNEL_AGILITY compiler switch is defined within the Makefile or the IAR project file. Section 2.7 provides an overview of the build configuration. Table 2-5. Channel agility API functions. API Function Description nwk_ch_agility_request (AgilityMode, nwk_ch_agility_confirm) Enables or disables the channel agility mode. nwk_ch_agility_confirm (Status, ChannelChanged, LogicalChannel) Confirms the previous call of the above request. AgilityMode: AG_ONE_SHOT - starts single scanning AG_PERIODIC - starts periodic scanning AG_STOP - stops periodic scanning nwk_ch_agility_confirm: Confirmation callback for the request Status: Status of the request. ChannelChanged: True if the channel has changed, else false. LogicalChannel: Current logical channel. 11 8357D-AVR-06/12 API Function Description nwk_ch_agility_indication (LogicalChannel) If the channel is changed during the periodic mode, this indication informs the application about it. LogicalChannel: New/current logical channel. nlme_set_request (NIBAttribute, NIBAttributeIndex, NIBAttributeValue, nlme_set_confirm) Sets the configuration parameters (NIBAttribute), such as nwkPrivateChAgScanInterval: Channel agility scan interval, set to 60s for example applications; nwkPrivateChAgEdThreshold: Channel agility ED threshold value, set to 10 (-80dBm) for example applications; nwkScanDuration: duration of a single scanning operation, set to 6 (~1s) for example applications. nlme_set_confirm : Confirmation callback for the request For more details of the actual API functions, see the HTML-based reference manual; section 2.6. 2.5 Vendor-specific data handling The RF4CE profiles define standard behavior to ensure compatibility between different vendors. But some application requirements are not covered by the profile. These requirements can be handled by application-specific frames. The RF4CE standard allows transmitting application-specific frames using vendor data frames handled in the profile context. The Atmel RF4Control stack supports mechanisms (application hooks) for a dedicated vendor specific data exchange in the ZRC profile context. These mechanisms ensure the correct data handling without any impact on the standard profile-specific data handling. Table 2-6 shows the API functions for vendor data handling. The function prototypes can be found in the vendor_data.h header file located in the RF4CE/Inc directory. The vendor-specific API functions are included in the build process if the VENDOR_DATA compiler switch is defined within the Makefile or the IAR project file. Section 2.7 provides an overview of the build configuration. Table 2-6. Vendor data handling API functions. API Function Description vendor_data_request (uint8_t PairingRef, profile_id_t ProfileId, uint16_t VendorId, uint8_t nsduLength, uint8_t *nsdu, uint8_t TxOptions) Initiates a vendor data specific transmission. PairingRef: The pairing reference for the other node. ProfileId: Profile identifier used for the transmission. VendorId: The vendor identifier. If this parameter is equal to 0x0000, the vendor identifier of the stack is used. nsduLength: The number of octets contained in the payload/nsdu. Nsdu: Payload of the data frame. TxOptions: Transmission options for this command; see ZigBee RF4CE specification version 1.0 [12] for further details. 12 AVR2102 8357D-AVR-06/12 AVR2102 API Function Description vendor_data_ind (uint8_t PairingRef, uint16_t VendorId, uint8_t nsduLength, uint8_t *nsdu, uint8_t RxLinkQuality, uint8_t RxFlags); Indicates an incoming vendor specific data frame PairingRef: The pairing reference of the originator node. VendorId: The vendor identifier used by the originator. nsduLength: The number of octets contained in the payload/nsdu. nsdu: Payload of the data frame. RxLinkQuality: Link quality of the incoming frame. RxFlags: Information about the transmit modes used. vendor_data_confirm (nwk_enum_t Status, uint8_t PairingRef, profile_id_t ProfileId, uint8_t Handle); Provides the status of the last vendor data request. Status: Status of the data transmission. PairingRef: The pairing reference used for the transmission. ProfileId: Profile identifier used for the transmission. Handle: Used for data retry at the application level The application needs to define and handle the semantics of the vendor data payload. Some example applications, such as the Single Button Controller (section 3.1.3.9) in combination with the Terminal Target application, demonstrate the use of the vendor data exchange. The ZRC Target (section 3.1.3 application example reveals the concept of vendor data exchange by implementing a firmware over-the-air (FOTA) upgrade feature. 2.6 RF4Control firmware API The Atmel RF4Control stack API is documented using Doxygen-style comments. 2.7 Stack configuration The RF4Control stack can be configured to match end-user application requirements. The configuration ensures that only functionality that is actually needed by the application is included into the stack and that the footprint meets the desired or minimum values. The configuration is done in the same way as it is within the MAC software package [7]; see its user guide for general information about stack configuration. The RF4Control stack uses as the default CPU clock 16 MHz while be run on a megaRF device. Depending on the application requirements the CPU clock can be reduced (from the default 16 MHz operation) to 4 or 8 MHz by setting the define F_CPU to 4000000 or 8000000 in the pal_config.h file. Reducing the CPU clock has impact to the execution speed of the entire application. The Atmel RF4Control stack can be configured by build/compiler switches. It is defined within the app_config.h file, and is applicable to source code package releases only. 13 8357D-AVR-06/12 Table 2-7. Compiler/build switches. 14 API Function Description RF4CE_PLATFORM If set, stack supports all device types. The actual device type needs to be configured by the application. This compiler switch includes also the build switch RF4CE_SECURITY. RF4CE_TARGET If set, stack supports functionality that is required to operate a target node. If not set, the stack only supports functionality that is required to operate a controller node. RF4CE_SECURITY If set (default), security is supported. If not set, the stack does not support security and the footprint is smaller. If set, the compiler switch STB_ON_SAL is required too. RSSI_TO_LQI_MAPPING If set (default), LQI calculation is based on RSSI value, as defined by [12]. MAC_USER_BUILD_CONFIG If set (default), MAC user build configuration is enforced. Only MAC primitives required by the RF4CE network layer are included in the build process. NWK_USER_BUILD_CONFIG If set, the nwk_user_build_config.h file is included during the firmware build process. The header file contains compiler switches to enable or disable network layer features that are required or not required by the application. The Makefile / IAR project file needs to include the path to the nwk_user_build_config.h file. TFA_BAT_MON If included in the Makefile or IAR project file, the supply voltage measurement feature is available. VENDOR_DATA If included in the Makefile or IAR project file, the hooks to handle vendor specific data are available. FLASH_SUPPORT If included in the Makefile or IAR project file, functionality for self programming the flash are available. ZRC_PROFILE If included in the Makefile or IAR project file, the ZRC profile layer is included in the build process. ZRC_CMD_DISCOVERY If included in the Makefile or IAR project file, the command discovery functionality is available. PBP_ORG If included in the Makefile or IAR project file, the push button pairing originator functionality is available. This build switch needs to be set if ZRC_PROFILE/ ZID_PROFILE is set. PBP_REC If included in the Makefile or IAR project file, the push button pairing receipient functionality is available. This build switch needs to be set if ZRC_PROFILE/ ZID_PROFILE is set. CHANNEL_AGILITY If included in the Makefile or IAR project file, the channel agility feature is included to the build process. ZRC_BASIC_PRESS_ONLY If included in the Makefile or IAR project file, the ZRC profile supports only the PRESSED command code. REPEATED and RELEASED are not available. ENABLE_PWR_SAVE_MODE If included in the Makefile or IAR project file, receiver is set to power save mode. AVR2102 8357D-AVR-06/12 AVR2102 API Function Description NO_32KHZ_CRYSTAL If included in the Makefile or IAR project file, sleep functions are configured to operated without a 32 kHz crystal in place. This is used to demonstrate the implementation w/o 32KHz crystal on Single Button Controller application. If this build switch is used, the WATCHDOG_TIMER switch needs to be set as well. STORE_NIB If included in the Makefile or IAR project file, NIB is stored in the flash memory instead of EEPROM. NVM_MULTI_WRITE If included in the Makefile or IAR project file, frame-counter is stored in the flash memory instead of EEPROM. WATCHDOG If included in the Makefile or IAR project file, watchdog feature is enabled. WATCHDOG_TIMER If included in the Makefile or IAR project file, watchdog is enabled in the interrupt mode. BOOT_FLASH If included in the Makefile or IAR project file, bootloader support will be enabled and functionality for self programming the flash will be available through bootloader. NLDE_HANDLE If included in the Makefile or IAR project file, application/profile will be provided with the handle argument for network data retry handling. RF4CE_CALLBACK_PARAM If included in the Makefile or IAR project file, application/profile will be provided with the callback parameter for the confirmation. ZID_PROFILE If included in the Makefile or IAR project file, the ZID profile layer is included in the build process. GDP_PROFILE If included in the Makefile or IAR project file, the GDP profile functionality will be included in the ZID build process. ZID_DEVICE If included in the Makefile or IAR project file, the ZID HID Class Device functionality is available. ZID _ADAPTOR If included in the Makefile or IAR project file, the ZID adaptor functionality is available. Compiler/build switches others than those listed in Table 2-7 configure the underlying MAC layer and its transceiver and platform abstraction. See [7] for further information on MAC layer configuration. 2.8 Stack porting This user guide describes how to use the Atmel RF4Control stack using a few example boards. For a customer- or application-specific design, the existing stack usually needs to be ported to a new hardware platform. The RF4Control stack is designed in a way that abstracts the hardware-specific characteristics through lower layers (Platform Abstraction Layer – PAL, Figure 2-1). Because the higher layers, such as the MAC, network, and profile layers, are implemented independently from the underlying hardware platform, no changes are usually required to these layers. It is recommended to use an existing hardware platform and software application as a basis for customer development. The application examples provided in chapter 3 are a good starting point for your own application development. 15 8357D-AVR-06/12 The “Platform Porting” section of the AVR2025 user guide [7] describes how to port from one hardware platform to another. 3 Example applications The RF4Control stack package contains some example applications that can be used for demonstration purposes and for getting familiar with the implementation for customer application development. For demonstration purposes, the release package includes pre-compiled firmware binary files (in .hex file format using the GCC compiler or .d90/.a90 file format using the IAR compiler). These can be used out of the box. 3.1 ZRC example application 3.1.1 Button Controller example application 3.1.1.1 Introduction The button controller example application implements a button controller and its target, which represents a TV, DVD, STB or similar device. For the button controller, Atmel uses designated hardware called a Button Controller. The counterpart of the button controller is the Terminal Target or ZRC Target application. See 3.2 for further information about the Terminal Target setup, and section. The Terminal Target‟s user interface is realized by using a standard terminal program, such as Windows ® HyperTerminal. The target is controlled via the Terminal target applications, for information about the ZRC Target application. program, and the received button control commands are printed to the terminal program. The handling of the Button Controller example application is described in section 3.1.2.1. The simpler button controller application, called a Single Button Controller, is described in section 3.1.3 3.1.1.2 Button Controller board setup The button controller setup consists of two boards connected together: (1) XMEGAA3BU-XPLAINED board and (2) the Transceiver board supports 2.4GHz and Sub GHz. The XMEGA-A3BU-XPLAINED board holds buttons, LED, USB Interface and Display. RF Communication handled by the Transceiver Board. Figure 3-1 shows the XMEGA-A3BU-XPLAINED button controller application board. 16 AVR2102 8357D-AVR-06/12 AVR2102 Currently following transceivers are supported for the button controller pre-build image: 1. XMEGA-A3BU-XPLAINED Board with Atmel AT86RF231 2. XMEGA-A3BU-XPLAINED Board with Atmel AT86RF230B If the example application is to be used in the sub-1 GHz band, the following board is supported: 3. XMEGA-A3BU-XPLAINED Board with Atmel AT86RF212 Board Setup Connect the supported Transceiver Board to the XMEGA-A3BU-XPLAINED Board. Insert the micro USB cable to the XMEGA-A3BU-XPLAINED & other end to PC or Laptop. Connect the ISP or JTAG to the XMEGA-A3BU-XPLAINED Board. Button controller application available with Atmel Software Frame Work which is selected from ASF Wizard Example Application in Atmel Studio. For IAR Projects download the ASF standalone zip file from http://www.atmel.com/asf Extract the downloaded files into the director. The IAR workspace files are available from the below path \thirdparty\wireless\avr2102_rf4control\apps\zrc\button_ctr\xmega_a3bu_xplained_rz 600rf231\iar \thirdparty\wireless\avr2102_rf4control\apps\zrc\button_ctr\xmega_a3bu_xplained_rz 600rf212\iar It is recommended to check the MCU fuses: Table 3-1 lists the recommended fuse settings. For further information about fuse settings, see [7] and the device datasheet. Table 3-1. Recommended fuse settings. Parameter Value for RCB BODLEVEL Brown-out detection at VCC = 1.8V OCDEN Disabled JTAGEN Enabled SPIEN Enabled WDTON Disabled EESAVE Enabled BOOTSZ Boot flash size = 4096 words; start address = $F000 BOOTRST Disabled CKDIV8 Disabled CKOUT Disabled SUT_CKSEL Internal RC oscillator start-up time = 6CK + 0ms Fuse settings can also be specified in terms of bytes as given below 17 8357D-AVR-06/12 Extended : 0xFE High : 0x91 Low : 0xC2 3.1.2 Terminal target example application The Terminal Target example application, which represents a TV, DVD, etc., can be operated using several boards. The pre-compiled firmware for the supported boards is located in the directory: \thirdparty\wireless\avr2102_rf4control\apps\zrc\terminal_ \< mcu_tranceiver_board>\GCC or \thirdparty\wireless\avr2102_rf4control\apps\zrc\terminal_tgt\\IAR\Exe where represents the used hardware configuration, such as at32uc3a3256s_rz600_at86rf212. The AVR2025 User Guide ([7], section 7.3) provides further information about firmware programming using AVR Studio. Table 3-1 contains information about the recommended MCU fuse settings. The board used for the Terminal Target application needs to be connected to a PC/laptop via a serial interface; that is, an RS232/UART or USB interface. The required USB drivers can be found here: Atmel CDC USB driver used with XMEGA-A3BU-XPLAINED board: [16] At the PC/laptop, a terminal program (Windows HyperTerminal, for example) is used to control the Terminal Target application. Figure 3-1 shows the configuration of the HyperTerminal program used for the example application. If at32uc3a3256s_rz600_at86rf212 is used as terminal target, then Baudrate needs to be set to 9600 18 AVR2102 8357D-AVR-06/12 AVR2102 Figure 3-1. HyperTerminal settings. 3.1.2.1 Remote controlling operations Terminal target functions Once the Terminal Target application is powered up, open the terminal program and press any key to print the menu to the terminal window. Figure 3-2 shows the terminal window with the application menu. Figure 3-2. Terminal Target example application menu. 19 8357D-AVR-06/12 The following actions can be triggered from the menu by entering a letter in the HyperTerminal window. (R) Perform a cold reset of the target device; NIB will be reset to default values and stored in EEPROM (S) Start the target device (P) Start the pairing procedure on target device (A) All-in-one start-up. Perform all three previous steps; that is, reset, start, and pairing (W) Perform a warm reset of the target device (T) Print the pairing table (U) Unpair a device and remove pairing entry from the pairing table of target (C) Enable channel/frequency agility on the target device (O) Open a sub-menu to configure channel agility (B) Set the base channel on the target device (Y) Toggle the standby mode of the target device. Target will sleep and then wake up for 16.8ms every second. If target receives any data in 16.8ms window, it will come out of standby mode (D) Request the battery status from the controller. The target sends a battery status request to the controller. The controller will send the response. The target sends the request command continuously for one second (multi-channel mode) until the controller wakes up (16.8ms window) to receive the data (V) Request the firmware version from the remote controller. The target sends a battery status request to the controller. The controller replies with the response. The target sends the request command continuously for one second (multichannel mode) until the controller wakes up (16.8ms window) to receive the data (Z) Request the remote controller life status. The target sends an alive request to the controller. The controller replies with the response. The target sends the request command continuously for one second (multi-channel mode) until the controller wakes up (16.8ms window) to receive the data. The LEDs on the controller will blink for some time indicating that an alive request is received (M) Request the remote controller to enable the accelerometer for a defined duration(ON duration) and send the accelerometer position to the target periodically(200 ms).After receiving this request, the controller will blink once for indication and start sending the accelerometer position at regular interval(200 ms) till the ON duration expires. Remote controller clearing The remote controller might have stored any data to the microcontroller EEPROM from previous operations. Therefore, it is recommended to clear any data that is stored in the EEPROM and reset any previously stored pairing information. The pairing table is stored in the MCU EEPROM. The remote controller application including EEPROM is cleared by executing a cold start reset. The cold start reset is initiated by pressing the SEL button first then keeping SEL button pressed, hold down the PWR button. The application indicates that it is ready for clearing when the LEDs next to the SEL & PWR buttons turn on. Releasing the SEL & PWR buttons clears all stored data. The clearing procedure is completed when LED ON. After clearing all previously stored data (expect IEEE address), the remote controller application sets itself to sleep mode for power saving. In some scenarios LED ON indicates that a problem has been detected. For example, the application detects that it is not paired to any other device. 20 AVR2102 8357D-AVR-06/12 AVR2102 Pairing In order to control the Terminal Target by the Button Controller board, it is necessary to pair both boards with one another. The pairing procedure, called push button pairing, is defined by the ZigBee RF4CE Remote Control profile specification. Using the example application, the easiest way to execute push button pairing is as follows: Step 1: Enter „A‟ at the terminal program to execute an “All-in-one start.” This includes the reset of the node, initialization of the ZRC profile, start of the network layer, and the auto-discovery procedure as part of the push pairing sequence. The terminal program indicates that it is ready for the push button pairing procedure by printing “Press SEL key then keeping SEL pressed press any FUNC key This starts the push button pairing at the button controller.” and by flashing all the LEDs. Step 2: Start the push button pairing procedure on the button controller board by pressing the SEL button first then keeping the SEL button pressed, hold down one of Target-1 or Target-2 function key. The output of a successful pairing sequence is shown in Figure 3-3. The information stored into the Terminal Target pairing table can be listed by selecting „T‟ from the target menu. Now the Button Controller can be used to send commands to the target. The button controller board can be used to control different targets. For example, the Target-1 key can be used to control a TV and a Target-2 key can be used to control another target, like a DVD. The function key pressed during the pairing procedure determines the target node to be controlled. If the all-in-one start is not used to establish the pairing, the manual sequence needs to be as follows: Reset, start, and then push button pairing.Figure 3-3. Terminal Target example application output – successful pairing. 21 8357D-AVR-06/12 In order to control another target device by the same button controller, the push button pairing procedure needs to be repeated with another Terminal Target application using a different Target key. The Terminal Target example application is limited to three paired devices/controllers at a time. Operation After successful pairing of the two boards (target and controller), the Button Controller board can be used to control the Terminal Target application. The command code (HDMI CEC [15]) of a key that is pressed at the Button Controller board is sent to the Terminal Target application and printed in the terminal window. If a data frame is received by the target, it flashes the data LED. All LEDs are flashed once if the Remote Controller Board does not get an acknowledgement from the target node. This can be used to check the coverage of the implementation. Pressing two push buttons simultaneously is not supported. The SEL & Target-1 or Target-2 keys can be used to switch between different target devices. In order to do so, press the SEL button first and then press the desired function key that was used during the pairing procedure. If a function key is selected that has not been used for a pairing procedure with a terminal target application, all LEDs will flash to indicate a malfunction. Wait until the LED flashing has stopped before continuing. The button controller boards support all three command types: PRESSED, REPEATED, and RELEASED (section 2.2.3). Table 3-2 shows the button controller board buttons and their corresponding ZRC command codes. Table 3-2. KEY_RC board ZRC command codes. Button Command code PWR PRESSED VOLUME REPEATED If power to the remote controller board is momentarily disconnected, the active function needs to be reselected by pressing the SEL button followed by the function button that was used previously during the pairing procedure. From the terminal output, menu item C, channel agility, can be used to toggle (enable or disable) the periodic channel agility mechanism at the target node. See section 2.2 for further information about channel agility. The current status (enabled or disabled) of the periodic channel agility mode is printed to the terminal program (“Channel agility (periodic mode) enabled,” for example). Channel agility becomes very useful in noisy channel environments. When the noise level on the current operating channel become too great (for demonstration purposes, the noise threshold level was set to -80dBm) and the adjacent channels yield better noise performance, the channel with the lowest noise energy will be selected as the new base channel. The parameters used for the channel agility mechanism can be configured using the menu item O, channel agility configuration. If it is desired to demonstrate channel agility when the noise situation would not ordinarily warrant changing the current channel, menu entry B, base channel change, can be used to force a base channel change. Menu item Y, standby, sets the Terminal Target application‟s transceiver to power save mode. During power save mode, the receiver is set periodically to sleep and wake up again. The transmit mechanisms of RF4CE allow the target to wake up during the power save mode by sending a command from the remote controller. 22 AVR2102 8357D-AVR-06/12 AVR2102 Menu item M provides the user to enable the accelerometer at the controller side. It also takes the input for the accelerometer ON duration. The target will receive the accelerometer position from the remote controller every 200ms till the accelerometer ON duration expires. RF frame capture Over-the-air RF frames that are exchanged between both nodes during startup, pairing, and remote control operation can be captured and displayed on the screen by using an RF sniffer. Figure 3-4 shows an example of the RF frames exchanged during startup, discovery, and pairing between the Terminal Target and the Button Controller applications. The security is enabled at both nodes, and the KeyExTransferCount parameter is set to its minimum value of 3. Figure 3-4. RF sniffer snapshot. Target device: 0x00 04 25 FF FF 17 53 0C Controller device: 0x00 04 25 FF FF 17 53 A5 3.1.3 Single Button Controller example application To understand how to use the RF4Control API (see section 2.2 and section 2.6) in a user-defined application, a simple Single Button Controller is introduced. It is simpler than the Key Remote Controller application. It makes use of only a single button, and can be operated as one module. It needs an adapter board only for programming. The following description uses the Atmel ATmega128RFA1 RCB, called RCB_6_3_PLAIN [19]. Besides the RCB_6_3_PLAIN board, the Atmel ATmega128RFA1-EK1 [18] board, ATMEGA256RFR2_XPLAINED_PRO board used to run this application. 23 8357D-AVR-06/12 3.1.3.1 Hardware Figure 3-5. ATmega128RFA1 – RCB_6_3_PLAIN. The Atmel ATmega128RFA1 RCB_6_3_PLAIN board contains three general purpose LEDs (D1, D2 and D3) and one push button for application control. Status LED D5 to the right of the button displays the Atmel ATmega128RFA1 reset state. LEDs and button are shown on the bottom side of Figure 3-5. For correct operation, the antenna needs to be connected to the RCB‟s SMA connector, and two batteries (AAA) need to be inserted into the RCB‟s battery holder. For further information about the RCB, see [19]. 3.1.3.2 Firmware programming The AVR2102 package contains pre-compiled binaries providing an out-of-the-box experience. The MAC User Guide ([7], section 7.3) provides further information about firmware programming using Atmel Studio. Table 3-1 contains information about the recommended MCU fuse settings. For debugging and programming purposes, a JTAG [10] is required. The JTAG is connected to the RCB via a Breakout Board (BB), Sensor Terminal board 3.1.3.3 Application handling Once the firmware is downloaded to the ATmega128RFA1 device and the JTAG pod and BB are disconnected, the application can be started. The RCB communication peer is the Terminal Target application (see section 0). 3.1.3.4 Cold start The cold-start reset and push button pairing procedure is initiated by pushing the button on the controller and entering 'A‟ on the HyperTerminal menu on the Terminal Target. Either device can start the push button pairing procedure. In order to pair the Single Button Controller with the Terminal Target, the push button pairing procedure is used. At the Terminal Target application, the push button pairing procedure is started by entering „A‟ at the HyperTerminal menu on the Terminal Target. The device is reset and started. Then the Terminal Target application displays the ready message to the terminal window: “Press the push button pairing button at the remote controller now.” 24 AVR2102 8357D-AVR-06/12 AVR2102 To start the push button pairing procedure, the RCB push button needs to be pressed as the board is switched on. The board LEDs show the current status of the pairing procedure: LED 0 (D2): application reset and initialization; or error indication LED 1 (D3): push button pairing (discovery and pairing); or error indication LED 2 (D4): error indication If the push button pairing procedure has been completed successfully, all three LEDs are switched on for about one second. The Single Button Controller has limited error handling capability. Blinking LEDs indicate that an error has occurred during discovery or pairing. After successful pairing, the Atmel ATmega128RFA1 device is set to sleep. Pressing the push button wakes the MCU and sends an RF4CE frame (POWER_TOGGLE_FUNCTION command) to the paired device, that is, to the Terminal Target application. The Terminal Target application toggles its LED 1 and the relay 1 if the POWER_TOGGLE_FUNCTION command is received. If the Terminal Target application does not send an acknowledgement to the Single Button Controller, all three controller LEDs are switched on for about two seconds. 3.1.3.5 Warm start - Reinstating existing pairing table The pairing information is stored to the non-volatile memory (NVM) of the ATmega128RFA1. The RCB can be switched off using the power switch (see left side in Figure 3-5). If the push button is not pressed during power up of the RCB, a warm start is performed. During the warm start, the pairing information is read from the NVM as the Single Button Controller is powered up again. The pairing table used in the last session is reinstated on power-up. All three LEDs are switched on at the same time and switched off in sequence, indicating that the warm start reset has been completed. 3.1.3.6 Development environment Two different development environments are supported by the included project or Makefile files: IAR Embedded Workbench® for AVR; http://www.iar.com Atmel Studio http://www.atmel.com/ 3.1.3.7 Application implementation Using the library release package, the entire implementation of the Single Button Controller application requires only a few files: Project file/Makefile: For IAR: Single Button Controller Project and Single Button Controller workspace For Atmel Studio: Single Button Controller solution & project files and Makefile RF4Control library: For IAR: \thirdparty\wireless\avr2102_rf4control\lib\zrc\ctr\ \iar\librf4ce-zrccontroller.r82 25 8357D-AVR-06/12 For Atmel Studio /GCC: \thirdparty\wireless\avr2102_rf4control\lib\zrc\ctr\ \iar\librf4ce-zrccontroller.a 3.1.3.8 Program flowchart The program flow of the Single Button Controller application is shown by Figure 3-6. Figure 3-6. Single Button Controller program flowchart. Power up Stack init Cold start Warm start YES call reset request (true) node_status = COLD_START Button pressed on power-up RF4Control stack Handle reset request Reset Confirm call start request Start Confirm call PBP request PBP Confirm call Cmd disc request Cmd disc. confirm call RxEnable request RxEnable Confirm issues reset confirm Handle start request issues start confirm Handle PBP request issues PBP confirm No call reset request (false) RF4Control stack node_status = WARM_START Handle reset request issues reset confirm Handle RxEnable issues RxEnable confirm Reset Confirm call RxEn request RxEnable Confirm node_status = IDLE Set MCU to sleep mode Handle Cmd disc request issues Cmd disc confirm Handle RxEnable req issues RxEnable confirm node_status = IDLE Set MCU to sleep mode The following paragraphs describe the source code implementation of the Single Button Controller example application. It is recommended having the HTML-based API documentation handy while walking through the implementation (see section 2.6). 26 AVR2102 8357D-AVR-06/12 AVR2102 3.1.3.9 Vendor-specific data exchange For vendor-specific data exchange, the RF4Control stack provides vendor-specific data handling API functions (see section 2.5). Every application can define the semantics of the vendor-specific data. The Single Button Controller application uses vendor-specific data exchange to implement the following features: Battery status request/response Alive request/response Firmware version request/response Rx Enable request/response Firmware request/response for firmware over-the-air (FOTA) update Firmware swap For this application, the request messages are sent by the target node (Terminal Target or ZRC Target application), and the controller node (Single Button Controller) answers the request with a response message. Example: The user initiates a battery status request by entering option D on the Terminal Target menu. The target node sends the battery status request frame using multi-channel transmission to the controller node. The controller, operating in power save mode, switches its receiver on every second for a short duration. During this window, the controller receives this request frame. The controller stack analyzes the frame and calls the vendor data indication callback function vendor_data_ind(). Within the vendor_data_ind() function, the payload is parsed and a battery status request is identified. The controller measures its voltage level and replies with the battery response message frame. ZID example application The RF4Control-ZID stack package contains example application that can be used for demonstration purposes and for getting familiar with the implementation for consumer application development.. 3.2 ZID Example application 3.2.1 ZID USB HID Adaptor example application 3.2.1.1 Features 1. Compliance with ZigBee RF4CE network layer specification, as a target node 2. Compliance with ZigBee RF4CE ZID specification, as a target node 3. Integrated with USB-HID Stack. 4. HID Compliant Consumer Control device 5. HID Compliant Mouse and Keyboard. 6. ZigBee RF4CE network layer security 3.2.1.2 Application Overview This section demonstrates the use of Zigbit RF233 USB stick as ZID adaptor which receives ZID reports from ZID class device over the air and sends to the PC via USB HID interface. Thus the ZID Remote (class Device) can control the PC. The ZID adaptor communicates with the PC via the USB HID stack that is integrated into the 27 8357D-AVR-06/12 application. So that the ZID adaptor will act as a HID Compliant device connected to the PC. 3.2.1.3 On Power Up/Initialization When the USB adaptor is connected to the PC, it initializes the RF4CE ZID stack and the USB HID stack enumerates as a HID Compliant composite device (as a Keyboard, Consumer control device which controls multimedia keys and Mouse) as shown in the screenshot. Wait for the device to enumerate when it is connected for the first time. After initialization, ZID adaptor, performs all in one start, this includes initialization of the ZID profile, start of the network layer, and the auto-discovery procedure as part of the push pairing sequence. This starts the push button pairing at by flashing the Green LED on the board. After successful pairing of the two boards (adaptor and class device), the key remote Controller board can be used to control the PC applications via ZID USB adaptor. ZID report of a key that is pressed at the Button Controller board is sent to the USB adaptor application and the corresponding HID report is sent to the PC. ZID reports triggered by media player keys( volume up/down/mute keys, * play / pause / stop /next/previous keys are handled by supporting applications (for example, Windows master volume control, media player, etc...)Along with media player remote, the ZID Remote application also demonstrates Power point (PPT) remote and Pointing and clicking functionality as mouse. The Key mapping details are provided in the ZID Remote controller device application. 28 AVR2102 8357D-AVR-06/12 AVR2102 3.2.2 ZID Key Remote Controller Device Application ZID HID Class Device example application is developed on key remote controller board. This key remote controller application will demonstrate the functionality of the Multimedia keyboard, Mice, Key board and Joystick using ZID Profile. During power on cold start procedure is done by pressing the Red Button on the Key Remote controller. Once the push button pairing is completed, release the Red Button press. Key Remote Controller LED Indications: S.No LED No Function Description 1 LED1 Toggle Key Press Status and Adaptor Communication status 2 LED2 LED2 On Mouse Mode. Key press event will only send the mouse reports to the adaptor. LED3, LED4, LED5 in Off state. 3 LED3 LED3 On Keyboard mode, Key Press event will only send the keyboard report to the adaptor. LED2, LED4, LED5 in Off state. 4 LED4 LED4 On Joystick (Gaming Mode). LED2, LED3, LED5 in Off State. 5 LED5 LED5 On Media player Mode. Key Press events will only send the Media player report to the adaptor. The below table explains the key events and corresponding key functionality Key name MEDIA MICE MODE KEYBOAR GAMING MODE PLAYER D MODE MODE PWR RED KEY COLD COLD ESC COLD START(During START(Durin START(During Power On) g Power On) Power On) GREEN MICE MODE MICE MODE MICE MICE MODE KEY MODE YELLOW KEYBOARD KEYBOARD KEYBOARD KEYBOARD KEY MODE MODE MODE MODE BLUE KEY GAMING GAMING GAMING GAMING MODE MODE MODE MODE SEL(BLACK MEDIA MEDIA MEDIA MEDIA PLAYER ) KEY PLAYER PLAYER PLAYER MODE MODE MODE MODE 1 KEY 2 KEY 3 KEY 4 KEY 5 KEY 6 KEY 7 KEY 8 KEY 9 KEY 0 KEY L+ KEY VOLUME + LEFT SINGLE TAB THROTTLE_UP CLICK 29 8357D-AVR-06/12 L- KEY VOLUME - R+ KEY R- KEY STOP MUTE/UNMUT E PLAY PAUSE ˄ (UP)KEY ˅ (DOWN)KE Y ˃ (RIGHT)KE Y ˂ (LEFT)KEY OK KEY RIGHT SINGLE CLICK CURSOR UP CURSOR DOWN DEL THROTTLE_DOW N PAGE UP PAGE DOWN UP KEY DOWN KEY BUTTON_1 BUTTON_4 NEXT CURSOR LEFT RIGHT KEY BUTTON_3 PREVIOUS CURSOR RIGHT LEFT KEY BUTTON_2 MEDIA PLAYER Open F5 Key names are readable from the Key remote controller board (silkscreen). In the above table blanks are left unused keys in corresponding key mode. After the cold start, by default key remote controller will be in Media Player Mode. So that LED5 will be in ON State, LED2, LED3, and LED4 in OFF State. To Change into Mice Mode, the user has to press the Green Button on Key remote controller board, Once the mode changed to mice mode, LED2 will be in ON State, LED3, LED4, LED5 will be in OFF State. To Change into Keyboard Mode, the user has to press the Yellow Button on Key remote controller board, Once the mode changed to Keyboard mode, LED3 will be in ON State, LED2, LED4, LED5 will be in OFF State. To change into Media Player Mode, the user has to press the SEL(BLACK) Button on Key remote controller board, Once the mode changed to media player mode, LED5 will be in ON State, LED2, LED3, LED4 will be OFF State. To change into Gaming Mode, the user has to press the BLUE Button on Key remote controller board, Once the mode changed to gaming mode, LED4 will be in ON State, LED2, LED3, LED45will be OFF State. Gaming Mode: The ZID class device will act as a gaming controller when switched to gaming mode. Accelerometer will be enabled in this mode and Gaming controller X,Y-axis Movements will be controlled according to the accelerometer sensor(Physical movement of the Key RC Board). ZID HID Class Device will support to send multiple reports in single report data frame itself. So the user can send and handle multiple reports in single frame itself, to make it communication more efficient and reduce the power consumption. ZID Class Device can combine Keyboard reports, Mice reports and Multitouch reports in single report data frame itself. 30 AVR2102 8357D-AVR-06/12 AVR2102 3.2.3 ZID QT Remote Controller Device Application This application demonstrates the use of AVR477 remote control as ZID class device, which pairs with the ZID HID PC adaptor and controls the PC applications like Media Player. AVR477 QT Remote is powered on QT Remote application will start the push button pairing procedure. First the Application will start the cold start procedure and it continues the push button pairing procedure and pairs with an adaptor if it is found. AVR477 Remote will function as Media Player control Remote. The below table explains the key events and corresponding key functionality Key Name Functionality SW16 STOP SW9 PREVIOUS SW10 NEXT SW17 MEDIA PLAYER OPEN SW14 VOLUME UP SW11 PLAY SW12 PAUSE SW15 VOLUME DOWN SW13 MUTE/UNMUTE Atmel AVR477 QTouch Remote is based on the reference design of AVR477. Please refer AVR477 application note for more details. 3.2.4 ZID Adaptor and Device ZID Adaptor application developed on ATxMEGA256A3U + AT86RF233 USB Zigbit. The project will be available in the following path, \thirdparty\wireless\avr2102_rf4control\apps\zid\terminal_aptr\GCC or \thirdparty\wireless\avr2102_rf4control\apps\zid\IAR Application can be build with either AVRGCC make file or Atmel Studio Project or IAR Project file. USB HID Class Driver support is available in windows by default. When the flash image downloaded and USB ZID Adaptor plugged into the PC then USB HID class driver will be installed automatically. 3.2.4.1 Fuse setting for adaptor and device Since the boot loader is not supported for ZID profile application, the following fuse settings are recommended. Parameter BODLEVEL OCDEN JTAGEN SPIEN WDTON EESAVE Value for RCB Brown-out detection at VCC = 1.8V Disabled Enabled Enabled Disabled Enabled 31 8357D-AVR-06/12 BOOTSZ BOOTRST CKDIV8 CKOUT SUT_CKSEL Boot flash size = 4096 words; start address = $F000 Disabled Disabled Disabled Internal RC oscillator start-up time = 6CK + 0ms Fuse settings can also be specified in terms of bytes as given below Extended: 0xFE High: 0x91 Low: 0xC2 3.2.5 ZID Terminal Adaptor Application The board used for the Terminal adaptor application needs to be connected to a PC/laptop via a serial interface; in case of uart an RS232/UART interface. At the PC/laptop, a terminal program (Windows HyperTerminal, for example) is used to control the Terminal adaptor application. For the terminal adaptor, then Baudrate needs to be set to 9600. Once the Terminal adaptor application is powered up,open the terminal program and press any key to print the menu to the terminal window. The following figure shows the terminal window with the application menu. Figure. Terminal Adaptor example application menu 32 AVR2102 8357D-AVR-06/12 AVR2102 The following actions can be triggered from the menu by entering a letter in the HyperTerminal window. (R) Perform a cold reset of the target device; netw ork and ZID NIB will be reset to default values and stored in NVM (S) Start the adaptor device (Z) Start the ZID connection procedure on target device (A) All-in-one start-up. Perform all three previoussteps; that is, reset, start, and ZID connection (W) Perform a warm reset of the target device (P) Print the pairing table 3.2.5.1 Cold reset and warm reset The class device & adaptor might have stored any data to the NVM from previous operations. Therefore, it is recommended to clear any data that is stored in the NVM and reset any previously stored pairing information. This is achieved by cold reset. The menu option („R‟) is available for the terminaladaptor to do cold reset. At the class device side, Cold start reset is initiated by pressing the button on power on. If we don‟t press the button on power on, it will do warm reset i.e initialize the network and ZID nib from NVM. 3.2.5.2 Starting the node The menu option („S‟) is available for the terminaladaptor to start the node after the reset. At the class device, this will be triggered automatically after the cold/warm reset. 3.2.5.3 ZID attribute initialization This is not demonstrated in the sample application.Since we are using the default attribute values. Generally this will be done in the custom application to initialize the attributes based on the application/device requirements. 3.2.5.4 ZID connection The menu option („Z‟) is available for the terminal adaptor to start the pairing and configuration. At the class device, this will be triggered automatically after the node start. After pairing and configuration, application will be notified of the status of the pairing and configuration. On terminal adaptor, we can see the following message for the successful connection. 33 8357D-AVR-06/12 Figure. Terminal Adaptor example application output – successful connection. 3.2.6 ZID Adaptor operations Once the USB Zigbit Adaptor is connected to PC, USB HID Adaptor will enumerate the ZID Adaptor as multimedia keyboard and mice. Also it initiates and starts the network functionality. It will toggle the led for other device to pair with this ZID Adaptor. 3.2.7 Cold reset and warm reset The class device & adaptor might have stored any data to the NVM from previous operations. Therefore, it is recommended to clear any data that is stored in the NVM and reset any previously stored pairing information. This is achieved by cold reset. At the class device side, Cold start reset is initiated by application any external event. If we don‟t do the cold start, it will do warm reset i.e initialize the network and ZID nib from NVM. 3.2.8 Starting the node In Class Device side starting the node will be triggered automatically after the cold/warm reset. 3.2.9 ZID Attribute Initialization This is not demonstrated in the sample application. Since we are using the default attribute values. Generally this will be done in the custom application to initialize the attributes based on the application/device requirements. 34 AVR2102 8357D-AVR-06/12 AVR2102 3.2.10 ZID connection HID Adaptor to start the pairing initiation can be done at any time. At the class device, this will triggered automatically after the node start. After pairing and configuration, application will be notified of the status of the pairing and configuration. In ZID Adaptor side we can see the LED blink stopped and LED is On. 3.2.11 ZID Report data from the ZID device After the successful connection, class device will send out all the descriptors once. After that, it will send out the report data on button press. If we keep on pressing the button, it will send the report continuously. It will stop on button release after completing the current loop. Reports which is supported by the ZID Class Device Mouse, Keyboard, Contact Data, Tap gesture, Scroll gesture, Pinch gesture, Rotate gesture, Sync, Touch sensor properties, Tap Support properties. The descriptor is received at ZID adaptor side will be made action on cursors and related keys and its response. This demonstrates how to extract the report from the received descriptor. If anything goes wrong with pairing/configuration, we will get the connection confirmation along with status indicating the reason. 3.2.12 ZID example application flow Figure 3-7.1. Cold Reset Flow Diagram 35 8357D-AVR-06/12 Figure 3-8.2. Warm Reset Flow Diagram 3.3 Serial Interface example application 3.3.1 Introduction The Atmel RF4Control stack provides a Serial Interface example application that can be used for any inter-processor communication between a host controller running the main application and a client controller handling the RF4CE communication over the air. Both controllers use a serial interface to communicate. The host controller can be implemented as a standalone microcontroller, or it can also be a personal computer. Figure 3-9 shows a communication scenario example. The client receives commands from the host, such as data transfer requests. The client indicates received data over the air from its communication peer by returning data indications to its host. Figure 3-9. Communication scenario example. Main application host Serial Interface e.g. UART, I2C RF4CE client (target / controller) The physical interface between the main application controller and the RF4CE client can be manifold, including: UART USB I C (TWI) 2 Proprietary interface The Serial Interface example application uses a UART (RS-232) or USB for the serial interface. The physical interface handling is implemented by the PAL; see AVR2025 MAC Software Package [7] for further information about the PAL. 36 AVR2102 8357D-AVR-06/12 AVR2102 The logical interface is handled by the example application within the file “serial_interface.c”. This file implements the logical protocol used for the communication between the main application host and the RF4CE client application. The same protocol scheme is used for host-to-client and client-to-host communications. 3.3.2 Message structure The message structure of the logical protocol is described by the following table. Table 3-3. Logical protocol message structure (in bytes). Message header SOT 0x01 PROTOCOL Length of Message ID payload code 0x02 LEN Message trailer Message payload 0x… data, byte 0 data, byte 1 0x… 0x… … data, byte LEN -1 EOT 0x… 0x04 The message consists of the message header, message payload, and message trailer. The start-of-text symbol (SOT) and the length of payload field form the message header. The value of the length field indicates how many bytes are contained in the actual message payload; that is, the number of message payload bytes before the message trailer end-of-text (EOT) symbol is expected. The message payload is appended after the message header. The message payload starts with the message code followed by the message data fields. The length and the code of each message are listed in Table 3-4. The order of the payload bytes is aligned to the RF4CE primitive specification [12]. If more than one parameter is used by the primitive, the parameters are concatenated to the end of a byte stream in the message payload. Parameters whose size is longer than 8 bits in length are sent with the least-significant byte first. Parameters with 24bit lengths are encoded as 32-bit values where the most-significant byte contains a dummy value and is ignored by the serial interface. Parameter lists such as DevTypeList and ProfileIdList, which have a variable length based on the primitive specification, consist of a fixed length when using the serial interface protocol. The serial interface protocol sets the maximum length for each list; that is, the size of DevTypeList is set to 3 and size of ProfileIdList is set to 7. List values of unused entries are ignored, but need to be present. The following examples introduce this concept. 3.3.2.1 Message structure example 1: NLME-RESET.request primitive If the main application host wants to reset the network layer of the RF4CE application, it sends the NLME-RESET.request command to the RF4CE client. See [12] for further information about the NLME-RESET.request primitive. This request command requires the SetDefaultNIB parameter. Following this example, the value of the SetDefaultNIB value is set to true (1). Using the Serial Interface application, the NLME-RESET.request is encoded and sent as a byte stream via the serial link as follows: Listing 3-1. NLME-RESET.request command byte stream. 37 8357D-AVR-06/12 Byte stream from application host to RF4CE client via serial interface: 0x01 0x02 0x02 0x2A 0x01 0x04 Data interpretation: 0x01: SOT 0x02: RF4CE Protocol ID 0x02: Length field value 0x2A: Message code for NLME-RESET.request 0x01: Message parameter SetDefaultNIB; here 0x01 = true 0x04: EOT The RF4CE client answers a NLME-RESET.request with a NLME-RESET.confirm primitive. Using the Serial Interface application, the NLME-RESET.confirm message is encoded and sent as a byte stream via the serial link as follows: Listing 3-2. NLME-RESET.confirm command byte stream. Byte stream from RF4CE client to application host via serial interface: 0x01 0x02 0x02 0x3D 0x00 0x04 Data interpretation 0x01: SOT 0x02: RF4CE Protocol ID 0x02: Length field value 0x3D: Message code for NLME-RESET.confirm 0x00: Message parameter status; here 0x00 = SUCCESS 0x04: EOT 3.3.2.2 Message structure example 2: NLME-AUTO-DISCOVERY.confirm primitive The RF4CE client application generates a NLME-AUTO-DISCOVERY.confirm primitive as the result of the NLME-AUTO-DISCOVERY.request. Listing 3-3 shows the NLME-AUTO-DISCOVERY.confirm primitive message that is forwarded from the RF4CE client application to the main application host. Listing 3-3. NLME-AUTO-DISCOVERY.confirm message. Byte stream from RF4CE client to application host via serial interface: 0x01 0x02 0x0A 0x36 0x00 0x08 0x07 0x06 0x05 0x04 0x03 0x02 0x01 0x04 Data interpretation: 0x01: SOT 38 AVR2102 8357D-AVR-06/12 AVR2102 0x02: RF4CE Protocol ID0x0A: Length field value 0x36: Message code for NLME-AUTO-DISCOVERY.confirm 0x00: Message parameter “Status”; here 0x00 = SUCCESS 0x08 … 0x01: Message parameter “SrcIEEEAddr”; here 0x0102030405060708 0x04: EOT 3.3.2.3 Message structure exception As described, the message data payload is aligned to the RF4CE primitive order and size, in general. There are two exceptions to this rule, however: (1) the NLDEDATA.request and (2) the NLDE-DATA.indication primitive messages. The parameter order for these primitives is changed in comparison to the RF4CE specification. Listed below are the primitives with their own parameter order for the Serial Interface application example: NLDE-DATA.request parameter order: PairingRef, ProfileId, VendorId, TxOptions, nsduLength, nsdu NLDE-DATA.indication: PairingRef, ProfileId, vendorId, RxLinkQuality, RxFlags, nsduLength, nsdu 3.3.3 Message codes Table 3-4 lists the message codes and message lengths supported by the Serial Interface protocol. Table 3-4. Message codes and message lengths (bytes). RF4CE Network Primitive Message code Message length NLDE-DATA.request 0x24 ≥7 + data len NLDE-DATA.indication 0x34 ≥8 + data len NLDE-DATA.confirm 0x35 3 NLME-AUTO-DISCOVERY.request 0x25 15 NLME-AUTO-DISCOVERY.confirm 0x36 10 NLME-COMM-STATUS.indication 0x37 14 NLME-DISCOVERY.request 0x26 29 NLME-DISCOVERY.indication 0x38 48 NLME-DISCOVERY.response 0x27 22 NLME-DISCOVERY.confirm 0x39 4 + n * 49 n ≥1 NLME-GET.request 0x2B 3 NLME-GET.confirm 0x3A ≥5 NLME-PAIR.request 0x28 24 NLME-PAIR.indication 0x3B 50 NLME-PAIR.response 0x29 24 NLME-PAIR.confirm 0x3C 38 NLME-RESET.request 0x2A 2 NLME-RESET.confirm 0x3D 2 NLME-RX-ENABLE.request 0x2C 5 NLME-RX-ENABLE.confirm 0x3E 2 39 8357D-AVR-06/12 RF4CE Network Primitive Message code Message length NLME-SET.request 0x2D ≥4 NLME-SET.confirm 0x3F 4 NLME-START.request 0x2E 1 NLME-START.confirm 0x40 2 NLME-UNPAIR.request 0x2F 2 NLME-UNPAIR.indication 0x41 2 NLME-UNPAIR.response 0x30 2 NLME-UNPAIR.confirm 0x42 3 NLME-UPDATE-KEY.request 0x31 18 NLME-UPDATE-KEY.confirm 0x43 3 NWK_CH_AGILITY_REQUEST 0x32 2 NWK_CH_AGILITY_INDICATION 0x44 2 NWK_CH_AGILITY_CONFIRM 0x45 4 For better readability, the Atmel RF4Control stack uses the header file nwk_msg_code.h to assign symbolic names to the message codes. For functional compatibility, enumeration and assigned numbers should not be changed in this header file. 3.3.4 Serial Interface - message structure The message structure of all the supported network primitives is listed out below.. 3.3.4.1 NLDE-DATA.request Message header Length of Msg Pair. Profile Vendor Tx SOT Protocol payload code ref ID id options Id 1 byte 0x01 1 byte 0x02 1 byte Message trailer Message payload 1 byte 2 bytes 1 1 byte byte 1+LEN 0x24 0x… 0x… Byte 0-1 1 byte 0x.. Nsdu length 1byte LEN nsdu EOT LEN * 1 byte 1 byte 0x04 3.3.4.2 NLDE-DATA.indication Message header Message tr … SOT Protocol ID Length of payload Message payload EOT 1 byte 40 1 byte 1 byte 1 byte AVR2102 8357D-AVR-06/12 AVR2102 Message header 0x02 0x01 Message payload Message tr … 8+LEN 0x04 Message payload Msg code Pair. Profile ref ID Vendor ID Rx Link Quality Rx Flags nsdu length Data byte0 1 byte 1 byte 1 byte 2 bytes 1 byte 1 byte 1 byte 1 byte 1 byte 0x.. 0x.. LEN 0x.. 0x.. 0x34 0x.. 0x.. byte0 byte1 Data Byte LEN-1 .. 3.3.4.3 NLDE-Data.confirm Message header SOT Message payload Protocol Length of Message ID payload code Message trailer status Pair. Ref. Profile id EOT 1 byte 1 byte 1 byte 1 byte 1 byte 1 byte 1 byte 1 byte 0x01 0x02 4 0x35 0x… 0x… 0x.. 0x04 3.3.4.4 NLME_AUTO_DISCOVERY.Request Message header Protoc Length ol ID of RecApp payloa Message Capabiliti SOT code d es 1 byte 1 byte 1 byte 0x01 0x02 16 Message trailer Message payload 1 byte 1 byte 0x25 0x… RecDev Type List Rec ProfileIdList DevTypeList Profile list Size Size 3* 1 byte 7 * 1 byte 0x… 0x.. Auto DiscDuration EOT 4 bytes 1 byte Byte Byte Byte Byte 0 1 2 3 41 8357D-AVR-06/12 0x04 3.3.4.5 NLME-AUTO-DISCOVERY.confirm Message header Protoc Length ol ID of payloa Message status SOT code d 1 byte 1 byte 1 byte 0x01 0x02 Message trailer Message payload 10 1 byte 1 byte 0x36 0x… Byte 0 Byte 1 Src IEEE addr EOT 8 bytes 1 byte Byte Byte 2 3 Byte 4 Byte Byte Byte 5 6 7 0x04 3.3.4.6 NLME-COMM-STATUS.indication Message header Message trailer Message payload Protoc Length ol ID of Msg Pair. payloa SOT status code ref d Dst PAN ID Dst Addr Mode Dst addr EOT 1 byte 1 byte 1 byte 1 byte 1 byte 1 byte 2 bytes 1 byte 8 bytes 1 byte 0x01 0x02 14 0x37 0x… 0x… byte 0 Byte 1 0x.. 0x04 Byte 0- 8 3.3.4.7 NLME-DISCOVERY.request Message trailer Message header SOT Protocol ID Length of payload Message pay load 1 byte 1 byte 1 byte 0x01 0x02 29 EOT 1 byte Shown below 0x04 Message payload 42 AVR2102 8357D-AVR-06/12 AVR2102 Devtype list Org Profile ID list 1 byte 2 bytes 2 bytes 1 byte Devtype Size 3 * 1 byte Profile id List size 7* 1 byte 0x26 Byte 0-1 Byte 0-1 0x.. 0x.. Msg code PanID Nwk addr Org App Cap. Search disc devtype Profile Iist size 1 byte 1 byte 0x.. 0x.. disc Profile ID list Disc duration Profile id List size 4 bytes 7* 1 byte Byte0-3 3.3.4.8 NLME-DISCOVERY.indication Message trailer Message header SOT Protocol ID Length of payload 1 byte 1 byte 1 byte 0x01 0x02 48 Message pay load EOT 1 byte Shown below 0x04 Message pay load Src Org Org Org Org Org Org Msg status IEEE Node Vendor Vendor App User Devtype code addr Cap. ID string Cap. string List Org Profile ID list Rx Search Link dev quality type Profile id 2 bytes 1 15 Devtype List size 1 byte 1 byte 8 1 byte 1 byte 1 byte 7 bytes byte bytes bytes Size 7* 1 byte 3 * 1 byte 0x38 0x.. Byte 0-7 0x.. Byte 0-1 Byte 0-14 Byte 0-6 0x.. 0x.. 0x.. 3.3.4.9 NLME-DISCOVERY.response Message header Protoc Length ol ID of payloa Message status SOT code d Message trailer Message pay load Dst IEEE Addr Rec App cap rec Devtype List rec Profile ID list Disc ReqLQI 43 8357D-AVR-06/12 EOT 1 byte 0x01 1 byte 1 byte 1 byte 1 byte 22 0x27 0x… 0x02 8 bytes 1 byte Profile id List size 7* 1 byte Devtype Size 3 * 1 byte 1 byte Byte 0-7 0x.. 0x.. 1 byte 0x04 3.3.4.10 NLME-DISCOVERY.confirm Message trailer Message header SOT Protocol ID 1 byte 0x01 Length of payload 1 byte 1 byte 0x02 4 + 49(node_des_size)* num_of_nodes Message pay load 1 byte Shown below 0x04 Message pay load Msg code status Num nodes Desc. List size 1 byte 1 byte 1 byte 1 byte 0x39 0x.. 0x.. 49(node_des_size)* num_of_nodes Desc. List. 49(node_des_size)* num_of_nodes 3.3.4.11 NLME-GET.request Message header SOT 44 Protocol ID Length of payload EOT Message trailer Message pay load Msg code Nib attribute Attribute index EOT 1 byte 1 byte 1 byte 1 byte 1 byte 1 byte 1 byte 0x01 0x02 3 0x2B 0x… 0x… 0x04 AVR2102 8357D-AVR-06/12 AVR2102 3.3.4.12 NLME-GET.confirm Message header SOT 1 byte 0x01 Protocol ID Length of payload 1 byte 0x02 Mes tra Message pay load Msg code 1 byte 1 byte 5+ attribute len 0x3A status Nib attribute Attribute index 1 byte 1 byte 0x… 0x… 1 byte 0x.. E Attribute len Attribute value 1 byte Attribute Len * 1 byte 1b 0x.. 0x 3.3.4.13 NLME-PAIR.request Message trailer Message header SOT Protocol ID 1 byte Length of payload 1 byte Message pay load 1 byte 1 byte 24 0x01 EOT Shown below 0x04 0x02 Message payload Msg Logical Dst code channel panID Dst IEEEaddr Org App Cap. 1 byte 1 byte 2 bytes 8 bytes 1 byte 0x28 0x.. Byte0-1 Byte0-7 0x.. Org Org Devtype Profile ID list list DEV TYPE LIST SIZE 3*1 byte Key ExTransfer count EOT 1 byte PROFILE ID LIST SIZE 7 * 1 byte 1 byte 0x… 0x04 3.3.4.14 NLME-PAIR.indication Message trailer Message header SOT Protocol ID 1 byte 0x01 Length of payload 1 byte 1 byte 0x02 50 Message pay load EOT 1 byte Shown below 0x04 45 8357D-AVR-06/12 Message pay load src Msg statu pan code s ID src IEEE addr Org Org Org Org Org Org Org Devtype node Vendo Vend. App user Profile list r Cap. String Cap. String ID list id 1 1 2 8 1 byte byte bytes bytes byte 0x3B 0x.. Byte 0-1 Byte 0-7 0x.. 2 7 bytes bytes Byte 0-1 Byte 0-6 DEV 15 TYPE bytes LIST 1 byte SIZE 3*1 byte 0x.. Key Prov Ex Pair. Trans. Ref. cnt PROFILE ID 1 LIST byte SIZE 1 byte 7*1 byte Byte 0-14 0x … 0x.. 3.3.4.15 NLME-PAIR.response Message header Protocol Length ID of Msg status SOT payload code 1 byte 1 byte 0x01 0x02 1 byte 1 byte 24 Message trailer Message pay load 0x3A 1 byte 0x.. Dst panID Dst IEEE addr Rec App Cap. Rec Devtype list Rec Profile ID list Prov. Pair. ref EOT DEV PROFILE TYPE ID LIST 2 bytes 8 bytes LIST SIZE SIZE 1 byte 1 byte 3 * 1 byte 7 * 1 byte 1 byte Byte0-1 Byte0-7 0x04 0x.. 0x.. 3.3.4.16 NLME-PAIR.confirm Message header 46 Mess ge traile Message pay load AVR2102 8357D-AVR-06/12 AVR2102 Length Protocol of Msg status Pair. SOT ID payload code Ref. 1 byte 1 byte 0x01 0x02 Rec. Rec. Vendor Vendor ID string Rec App Cap. Rec Rec Rec. Devtype Profile user list ID string list DEV TYPE 1 byte 1 byte 15 LIST 1 byte 1 byte 1 byte 2 bytes 7 bytes bytes SIZE 3*1 byte 38 0x3C 0x.. 0x.. Byte0-1 Byte0-6 0x.. EOT PROFIL 1 byte E ID LIST SIZE 7*1 byte Byte 0-14 0x04 3.3.4.17 NLME-RESET.request Message header Protocol ID SOT Messa traile Message pay load Length of payload setDefaultNIB Msg code 1 byte 1 byte 1 byte 1 byte 0x01 0x02 2 0x2A EOT 1 byt 1 byte 0x.. 0x04 3.3.4.18 NLME-RESET.confirm Message header SOT 1 byte Messa traile Message pay load Protocol ID Length of payload Msg code EOT 1 byte 1 byte 1 byte status 1 byt 1 byte 47 8357D-AVR-06/12 0x01 0x02 2 0x3D 0x.. 0x04 3.3.4.19 NLME-RX-ENABLE.request Message header Protocol ID SOT Messa traile Message pay load Length of payload Msg code rxonDuration 1 byte 1 byte 1 byte 1 byte 0x01 0x02 2 0x2C EOT 1 byt 4 bytes Byte0-3 0x04 3.3.4.20 NLME-RX-ENABLE.confirm Message header Protocol ID Length of payload Msg code 1 byte 1 byte 1 byte 1 byte 0x01 0x02 2 0x3E SOT Messa traile Message pay load EOT status 1 byt 1 byte 0x.. 0x04 3.3.4.21 NLME-SET.request Message header SOT 48 Protocol ID Length of payload Mess trail Message pay load EO Msg code NIB attribute NIB Attribute index NIB Attribute value AVR2102 8357D-AVR-06/12 AVR2102 1 byte 1 byte 1 byte 1 byte 0x01 0x02 3 + LEN 0x3E 1 by 1 byte 1 byte 0x.. 0x.. LEN 0x0 3.3.4.22 NLME-SET.confirm Message header Protocol ID Length of payload Msg code 1 byte 1 byte 1 byte 1 byte 0x01 0x02 4 0x3F SOT Messag traile Message pay load status NIB attribute NIB Attribute index EOT 1 byte 1 byte 1 byte 1 byte 0x.. 0x.. 0x.. 0x04 3.3.4.23 NLME-START.request Message header Protocol ID Length of payload 1 byte 1 byte 1 byte 1 byte 0x01 0x02 1 0x2E SOT Messag traile Message pay load EOT Msg code 1 byte 0x04 3.3.4.24 NLME-START.confirm Message header Messa traile Message pay load 49 8357D-AVR-06/12 Protocol ID Length of payload Msg code 1 byte 1 byte 1 byte 1 byte 0x01 0x02 2 0x40 SOT EOT status 1 byt 1 byte 0x.. 0x04 3.3.4.25 NLME-UNPAIR.request Message header Protocol ID Length of payload Msg code 1 byte 1 byte 1 byte 1 byte 0x01 0x02 2 0x2F SOT Messa traile Message pay load EOT Pair. Ref. 1 byt 1 byte 0x.. 0x04 3.3.4.26 NLME-UNPAIR.confirm Message header Protocol ID Length of payload Msg code 1 byte 1 byte 1 byte 1 byte 0x01 0x02 3 0x42 SOT Message trailer Message pay load status Pair. Ref/ 1 byte 1 byte 0x.. 0x.. EOT 1 byte 0x04 3.3.4.27 NLME-UPDATE-KEY.request Message header 50 Message pay load Message trailer AVR2102 8357D-AVR-06/12 AVR2102 Protocol ID Length of payload Msg code 1 byte 1 byte 1 byte 1 byte 0x01 0x02 18 0x31 SOT EOT Pair. ref New Link key 1 byte 1 byte 16 bytes 0x.. Byte 0-15 0x04 3.3.4.28 NLME-UPDATE-KEY.confirm Message header Protocol ID Length of payload Msg code 1 byte 1 byte 1 byte 1 byte 0x01 0x02 3 0x43 SOT Message trailer Message pay load status Pair. Ref/ 1 byte 1 byte 0x.. 0x.. EOT 1 byte 0x04 3.3.4.29 NWK_CH_AGILITY_REQUEST Message header Message pay load Protocol ID Length of payload Msg code 1 byte 1 byte 1 byte 1 byte 0x01 0x02 2 0x32 SOT Message trailer EOT Agility mode 1 byte 1 byte 0x.. 0x04 3.3.4.30 NWK_CH_AGILITY_CONFIRM 51 8357D-AVR-06/12 Message header Protocol ID Length of payload Msg code 1 byte 1 byte 1 byte 1 byte 0x01 0x02 4 0x45 SOT Messag traile Message pay load status Channel changed Logical Channel EOT 1 byte 1 byte 1 byte 1 byte 0x.. 0x.. 0x.. 0x04 3.3.5 Protocol adaption The message structure described here is an example implemented by the Serial Interface application. The protocol or message structure can easily be adapted to the end-user‟s application needs. For example, a checksum, such as CRC, can be added to detect and correct errors that might occur over the serial link. 3.3.6 Serial interface usage As introduced in section 3.3.1, the Serial Interface application can be used in a scenario where the Atmel RF4CE stack in hosted on one microcontroller and the main application processor controls it via a serial interface. The following section explains how to use the Serial Interface application to set up a communication link. The following figure shows such a setup. Figure 3-10. Application setup using serial interface. Main application host A Serial Interface RF4CE client A RF4CE client B Serial Interface Main application host B Target node Controller node 0x00 04 25 FF FF 17 4A CE 0x00 04 25 FF FF 17 4A DF The main application microcontroller A hosts an application, such as a TV, controlling the RF4CE client A. The other main application microcontroller B hosts an application, such as a remote controller, controlling the RF4CE client B. The main application microcontrollers use a serial interface to communicate with their RF4CE clients. The application hosts send commands to their RF4CE clients to configure the RF4CE communication. The charts below show a typical scenario of commands that establish an RF4CE link and send a data frame to the target. The data communication between the host and the client serial interface is described in section 3.3.2. A typical RF4CE network application can be realized using the following hypothetical operating scenario: 52 AVR2102 8357D-AVR-06/12 AVR2102 Step1: Node initialization: Each client is configured (reset, set capabilities, set LQI threshold, etc.) Step 2: Discovery and pairing. Each client is directed to start discovery and pairing procedures Step 3: Data transmission. Each client is controlled to transmit and receive RF4CE application data 3.3.6.1 Step 1 – Initialization Host A Client A Over the air Client B Host B Reset request Reset confirm Reset request Reset confirm Set node capabilities Set confirm Set node capabilities Set confirm Set disc. LQI threshold Set confirm Set disc. repetition interval Set confirm Start request Start confirm Set max. disc. repetitions Set confirm Set max. report. node Set confirm Start request Start confirm Command / Message Description Byte stream over serial interface (message payload) Reset request Resets the RF4CE stack and underlying layers 0x2a 0x01 Reset confirm Returns the results of the reset request 0x3d 0x00 Set node capabilities Sets the capabilities of the RF4CE client, such as node type (target or controller) and security support Target node: 0x2d 0x73 0x00 0x01 0x0f Set confirm / node capabilities Returns the result of the previous set confirm 0x3f 0x00 0x73 0x00 Set disc. LQI threshold Sets the LQI threshold for the incoming discovery requests; here: 0x01 0x2d 0x62 0x00 0x01 0x01 Set confirm / disc. LQI threshold Returns the result of the previous set confirm 0x3f 0x00 0x62 0x00 Set disc. repetition interval Sets the duration of the discovery repetition interval; here: 0x00044AA2 symbols or 4.5 second 0x2d 0x63 0x00 0x04 0xa2 0x4a 0x04 0x00 Controller node: 0x2d 0x73 0x00 0x01 0x0c 53 8357D-AVR-06/12 Command / Message Description Byte stream over serial interface (message payload) Set confirm / disc. repetition interval Returns the result of the previous set confirm 0x3f 0x00 0x63 0x00 Set max. disc. repetitions Sets maximum number of discovery repetitions; here: 0x1E 0x2d 0x69 0x00 0x01 0x1e Set confirm / max. disc. repetitions Returns the result of the previous set confirm 0x3f 0x00 0x69 0x00 Set max report nodes Sets the maximum number of node descriptors that should be reported during discovery 0x2d 0x6c 0x00 0x01 0x01 Set confirm / max report nodes Returns the result of the previous set confirm 0x3f 0x00 0x6c 0x00 Start request Starts the RF4CE client 0x2e Start confirm Returns the result of the start confirm 0x40 0x00 There is no specific order required for the commands during configuration, but the start request command should not be issued before setting the node capabilities. 3.3.6.2 Step 2 – Discovery and pairing Host A Client A Over the air Client B Host B Auto disc. request Disc. request Discovery Disc. confirm Auto disc. confirm Pair. request Pair. indication Pair response Comm status indication 54 Pairing Pair confirm Command / Message Description Byte stream over serial interface (message payload) Auto disc. request Starts the auto discovery procedure 0x25 0x12 0x02 0x00 0x00 0x01 0x00 0x00 0x00 0x00 0x00 0x00 0x38 0x9c 0x1c 0x00 Auto disc. confirm Returns the result of the auto discovery procedure 0x36 0x00 0xdf 0x4a 0x17 0xff 0xff 0x25 0x04 0x00 AVR2102 8357D-AVR-06/12 AVR2102 Command / Message Description Byte stream over serial interface (message payload) Disc. request Starts the discovery procedure 0x26 0xff 0xff 0xff 0xff 0x12 0x01 0x00 0x00 0x01 0x00 0x00 0x00 0x00 0x00 0x00 0x02 0x01 0x01 0x00 0x00 0x00 0x00 0x00 0x00 0x12 0x7a 0x00 0x00 Disc. confirm Returns the result of the discovery procedure 0x39 0x00 0x01 0x31 0x00 0x0f 0x20 0x1e 0xce 0x4a 0x17 0xff 0xff 0x25 0x04 0x00 0x0f 0x34 0x12 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x12 0x4b 0x49 0x02 0x18 0x39 0x01 0x21 0x58 0x11 0x5b 0x9f 0xef 0x22 0x91 0x40 0x02 0xa2 0xbd 0x01 0x8c 0xc3 0xe4 0xf6 0xe7 0xe5 0x94 Pair request Starts the pair procedure; parameters are used from the discovery result 0x28 0x0f 0x20 0x1e 0xce 0x4a 0x17 0xff 0xff 0x25 0x04 0x00 0x12 0x01 0x00 0x00 0x01 0x00 0x00 0x00 0x00 0x00 0x00 0x03 Pair indication Indicates a pairing request 0x3b 0x00 0xff 0xff 0xdf 0x4a 0x17 0xff 0xff 0x25 0x04 0x00 0x0c 0x34 0x12 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x12 0x94 0x78 0x60 0xc4 0x35 0xf2 0x16 0x16 0x2a 0x05 0x00 0x00 0x00 0x03 0xfe 0x01 0x0c 0x34 0x01 0x00 0x00 0x00 0x00 0x00 0x00 0x03 0x00 Pair response Responses to the pairing request, such as allowing to pair 0x29 0x00 0xff 0xff 0xdf 0x4a 0x17 0xff 0xff 0x25 0x04 0x00 0x12 0x02 0x00 0x00 0x01 0x00 0x00 0x00 0x00 0x00 0x00 0x00 Pair confirm Returns the result of the pair request 0x3c 0x00 0x00 0x34 0x12 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x12 0x09 0xe9 0xce 0x29 0x1e 0xc9 0xc5 0xf3 0x07 0x47 0x08 0x79 0x72 0x87 0x6f 0x02 0x63 0x9a 0x01 0xbb 0xcb 0x0f 0xf4 0x10 0x9d Comm status indication Returns the result of the last response, here: pair response 0x37 0x00 0x00 0xff 0xff 0x01 0xdf 0x4a 0x17 0xff 0xff 0x25 0x04 0x00 There is no need to synchronize the auto discovery request on the target node and the discovery request on the controller node because the discovery request commands are sent by the RF4CE client several times, depending of the discovery repetition interval and the maximum discovery repetitions. The target node (Client A) is ready for the discovery request from the controller node and it is based on the duration parameter used for the auto discovery request command. 55 8357D-AVR-06/12 3.3.6.3 Step 3 – Data transmission Host A Client A Over the air Client B Data transmission Data indication Host B Data request Data confirm Command / Message Description Byte stream over serial interface (message payload) Data request Requests to send a data frame 0x24 0x00 0x01 0xf1 0xff 0x0c 0x02 0x12 0x34 Data indication Indicates the reception of a data frame 0x34 0x00 0x01 0x1e 0x16 0x94 0x02 0x02 0x12 0x34 Data confirm Returns the result of the data request 0x35 0x00 0x00 3.4 ZigBee Remote Control serial interface The RF4Control stack provides a ZRC Serial Interface application that is similar to Serial Interface application. The major differences are that the ZRC Serial Interface application supports: push button pairing API instead of the normal discovery and pairing mechanism remote control command discovery RC command handling instead of normal data transfer vendor-specific commands a controller and target configuration instead of a generic platform configuration 3.4.1 ZRC Serial Interface message codes The underlying architecture and message structure of the ZRC Serial Interface application remain the same as those of the Serial Interface application described in section 0. Table 3-5 lists the message codes and message lengths supported by ZRC Serial Interface protocol. Table 3-5. Message codes and message lengths for the ZRC API. 56 ZRC API functions Message codes Message lengths pbp_org_pair_request 0x46 21 pbp_rec_pair_request 0x48 12 pbp_pair_org_confirm 0x47 3 pbp_pair_rec_confirm 0x49 3 zrc_cmd_disc_request 0x4D 2 zrc_cmd_disc_indication 0x4E 2 zrc_cmd_disc_confirm 0x4F 34 zrc_cmd_disc_response 0x50 35 AVR2102 8357D-AVR-06/12 AVR2102 ZRC API functions Message codes Message lengths zrc_cmd_request 0x4A 6 + payload_length zrc_cmd_indication 0x4B 5 + payload_length zrc_cmd_confirm 0x4C 4 vendor_data_request 0x51 7 + Payload_length vendor_data_indication 0x52 8 + Payload_length vendor_data_confirm 0x53 3 Unsupported cmd code 0xFF 1 3.4.2 ZRC serial interface message structure The message structure of all the supported ZRC primitives is listed out below. 3.4.2.1 pbp_org_pair_request Message trailer Message header SOT Protocol ID 1 byte 1 byte 0x01 0x02 Message pay load Length of payload EOT 1 byte 1 byte 21 Shown below 0x04 Message pay load Msg code 1 byte 0x46 Org Org Devtype Profile ID list list Search Dev type Disc Profile id List size DEV PROFILE TYPE ID LIST 1 byte LIST SIZE SIZE 7 * 1 byte 3 * 1 byte 1 byte 1 byte Org App Cap. 0x.. Disc Profile id list PROFILE ID LIST SIZE 7 * 1 byte 0x.. 3.4.2.2 pbp_rec_pair_request Message header Messag trailer Message pay load 57 8357D-AVR-06/12 Protocol ID Length of payload Msg code rec App Cap. 1 byte 1 byte 1 byte 1 byte 1 byte 0x01 0x02 12 0x48 0x.. SOT rec Devtype list DEV TYPE LIST SIZE 3 * 1 byte EOT rec Profile ID list PROFILE ID LIST SIZE 7 * 1 byte 1 byte 0x04 3.4.2.3 pbp_pair_org_confirm Message header Protocol ID Length of payload Msg code 1 byte 1 byte 1 byte 1 byte 0x01 0x02 3 0x47 SOT Message trailer Message pay load status Pair. Ref/ EOT 1 byte 1 byte 1 byte 0x.. 0x.. 0x04 3.4.2.4 pbp_pair_rec_confirm Message header Protocol ID Length of payload Msg code 1 byte 1 byte 1 byte 1 byte 0x01 0x02 3 0x49 SOT Message trailer Message pay load status Pair. Ref/ 1 byte 1 byte 0x.. 0x.. EOT 1 byte 0x04 3.4.2.5 zrc_cmd_disc_request 58 AVR2102 8357D-AVR-06/12 AVR2102 Message header Message trailer Message pay load SOT Protocol ID Length of payload Msg code 1 byte 1 byte 1 byte 1 byte 0x01 0x02 2 0x4D Pair. Ref/ EOT 1 byte 1 byte 0x.. 0x04 3.4.2.6 zrc_cmd_disc_indication Message header SOT Protocol ID Message trailer Message pay load Length of payload Msg code Pair. Ref/ 1 byte 1 byte 1 byte 1 byte 0x01 0x02 2 0x4E EOT 1 byte 1 byte 0x.. 0x04 3.4.2.7 zrc_cmd_disc_confirm Message header Message trailer Message pay load SOT Protocol ID Length of payload Msg code 1 byte 1 byte 1 byte 1 byte 0x01 0x02 35 0x4F status Pair. Ref/ Supported cmd 1 byte 1 byte 32 bytes 0x.. 0x.. EOT 1 byte 0x04 3.4.2.8 zrc_cmd_disc_response Message header Message trailer Message pay load 59 8357D-AVR-06/12 Protocol ID SOT Length of payload Msg code 1 byte 1 byte 1 byte 1 byte 0x01 0x02 34 0x50 Supported cmd pair. Ref/ EOT 1 byte 1 byte 32 bytes 0x.. 0x04 3.4.2.9 zrc_cmd_request Message header SOT Protocol ID Mes tra Message pay load Length of payload Msg code 1 byte 1 byte 1 byte 1 byte 0x01 0x02 7+LEN 0x4A pair. Ref/ Vendor id Cmd code Tx options Cmd length Cmd payload 1 byte 2 bytes 1 byte 1 byte 1 byte LEN 0x.. Byte 0-1 0x.. 0x.. LEN E 1b 0x 3.4.2.10 zrc_cmd_indication Message header SOT 60 Protocol ID Length of payload Mes tra Message pay load Msg code 1 byte 1 byte 1 byte 1 byte 0x01 0x02 5+LEN 0x4B pair. Ref/ Rx Link quality RX Flags Nsdu length nsdu 1 byte 1 byte 1 byte 1 byte LEN 0x.. 0x.. 0x.. LEN E 1b 0x AVR2102 8357D-AVR-06/12 AVR2102 3.4.2.11 zrc_cmd_confirm Message header SOT Protocol ID Message trailer Message pay load Length of payload Msg code 1 byte 1 byte 1 byte 1 byte 0x01 0x02 4 0x4C status Pair. Ref/ RC cmd 1 byte 1 byte 1 byte 0x.. 0x.. EOT 1 byte 0x04 3.4.2.12 vendor_data_request Message header SOT Protocol ID Messag traile Message pay load Length of payload Msg code 1 byte 1 byte 1 byte 1 byte 0x01 0x02 7+LEN 0x51 pair. Ref/ Profile Id Vendor Id Tx Nsdu Options length nsdu EOT 1 byte 1 byte 1 byte 2 bytes 1 byte 1 byte 0x.. 0x.. Byte 0-1 LEN LEN LEN 0x04 3.4.2.13 vendor_data_indication Message header SOT Message trailer Message pay load Protocol Length Msg ID of code payload 1 byte 1 byte 1 byte 1 byte 0x01 0x02 8+LEN 0x52 pair. Profile Vendor Ref/ Id Id RX Link quality 1 byte 1 byte 2 bytes 1 byte Rx flags Nsdu length nsdu 1 byte 1 byte LEN 1 byte 0x.. 0x.. Byte 0-1 0x.. LEN LEN 0x04 3.4.2.14 vendor_data_confirm 61 8357D-AVR-06/12 EOT Message header SOT Protocol ID Message trailer Message pay load Length of payload Msg code 1 byte 1 byte 1 byte 1 byte 0x01 0x02 3 0x53 status Pair. Ref/ 1 byte 1 byte 0x.. 0x.. EOT 1 byte 0x04 3.4.2.15 Unsupported cmd Message header SOT Protocol ID Message pay load Message trailer Length of payload Msg code EOT 1 byte 1 byte 1 byte 1 byte 1 byte 0x01 0x02 1 0xFF 0x04 3.4.3 ZRC Serial Interface usage This section describes the usage of the ZRC Serial Interface. The description is divided into five steps. 1. 2. 3. 4. 5. 62 Initialization Push button pairing RC command discovery RC command handling Vendor-specific data handling AVR2102 8357D-AVR-06/12 AVR2102 3.4.3.1 Step 1 – Initialization Host A (Target) Client A (Target) Client B (Controller) Host B (Controller) Reset Request Reset Request Reset Confirm Reset Confirm Set Node Capabilities Set Node Capabilities Set Confirm Set Confirm Set aplKeyRepeatWaitTime Set aplKeyRepeatInterval Set Confirm Set Confirm Start request Start request Start Confirm Start Confirm The initialization step also provides a way to assign values to parameters that need to be set differently than their default values. The table below shows setting the example values. Command / Message Description Byte stream over serial interface (message payload) Reset request Resets the RF4CE stack and underlying layers 0x2a 0x01 Reset confirm Returns the results of the reset request 0x3d 0x00 Set node capabilities Sets the capabilities of the RF4CE client, such as node type (target or controller) and security support Target node: 0x2d 0x73 0x00 0x01 0x0f Set confirm / node capabilities Returns the result of the previous set confirm 0x3f 0x00 0x73 0x00 Set aplKeyRepeatInterval Sets the key repeat interval time on controller 0x2d 0x80 0x00 0x01 0x64 Set Confirm / aplKeyRepeatInterval Returns the result of the previous set request 0x3f 0x00 0x80 0x00 Set aplKeyRepeatWaitTime Sets KeyRepeatWaitTime on target 0x2d 0x81 0x00 0x01 0xc8 Set Confirm / aplKeyRepeatWaitTime Returns the result of the previous set request 0x3f 0x00 0x81 0x00 Controller node: 0x2d 0x73 0x00 0x01 0x0c 63 8357D-AVR-06/12 Command / Message Description Byte stream over serial interface (message payload) Set aplResponseWaitTime Sets aplResponseWaitTime 0x2d 0x6c 0x04 0x00 0x00 0x6a 0x18 Set Confirm / aplResponseWaitTime Returns the result of the previous set request 0x3f 0x00 0x6d 0x00 Start request Starts the RF4CE client 0x2e Start confirm Returns the result of the start confirm 0x40 0x00 There is no specific order required for the commands, but the start request command should not be issued before setting the node capabilities. 3.4.3.2 Step 2 – Push button pairing Command / Message Description Byte stream over serial interface (message payload) pbp_org_pair_request Starts the push button pairing procedure at controller 0x46 0x13 0x01 0x00 0x00 0x01 0x00 0x00 0x00 0x00 0x00 0x00 0x02 0x01 0x01 0x00 0x00 0x00 0x00 0x00 0x00 pbp_rec_pair_request Starts the push button pairing procedure at target 0x48 0x13 0x02 0x00 0x00 0x01 0x00 0x00 0x00 0x00 0x00 0x00 pbp_org_pair_confirm Push button pairing status on controller 0x47 0x00 0x00 pbp_rec_pair_confirm Push button pairing status on target 0x49 0x00 0x00 3.4.3.3 Step 3 – RC command discovery RC command discovery is used to exchange information about the supported commands. After pairing, the target sends the RC command discovery request to the controller. The controller answers back to the target with a response message. After a blackout period, the controller sends the command discovery to the target, and the target sends the response back to controller. Command / Message 64 Description Byte stream over serial interface (message payload) AVR2102 8357D-AVR-06/12 AVR2102 Command / Message Description Byte stream over serial interface (message payload) zrc_cmd_disc_request Sends the RC command discovery request 0x4c 0x00 zrc_cmd_disc_indication Indication on the receiver of the command discovery 0x4d 0x00 zrc_cmd_disc_response Sends back the response to originator 0x4f 0x00 0x1f 0x06 0x00 0xe0 0xff 0x03 0x13 0x00 0x0f 0x00 0x00 0x00 0x00 0x00 0x1e 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 zrc_cmd_disc_confirm The status of the command discovery request 0x4e 0x00 0x00 0x1f 0x06 0x00 0xe0 0xff 0x03 0x13 0x00 0x0f 0x00 0x00 0x00 0x00 0x00 0x1e 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 3.4.3.4 Step 4 – RC command handling Host A (Target) Client A (Target) zrc_cmd_indication Over the air Client B (Controller) Data transmission Host B (Controller) zrc_cmd_request Zrc_cmd_confirm Command / Message Description Byte stream over serial interface (message payload) zrc_cmd_request Sends the RC command from controller to target 0x49 0x00 0xfa 0xff 0x01 0x0c 0x01 0x30 zrc_cmd_indication Indication on the target for the RC command 0x4a 0x00 0x2e 0x02 0x02 0x01 0x30 zrc_cmd_confirm The status of the previous RC command 0x4b 0x00 0x00 0x30 65 8357D-AVR-06/12 4 Serial bootloader support The serial bootloader firmware is capable of programming (flashing) the device program memory with a new program application image without using a device programmer (e.g. JTAGICEII). 4.1 Functionality Overview This feature is supported on all the extension boards of Xmega-a3u and Xmega256RFR2.. Please refer to “Supported boards” section 11.4 in the MAC user guide [7]. The bootloader program is also available at thirdparty\wireless\addons\bootloader. Note: In case, if bootloader firmware needs to be programmed using device programmer, then following fuse settings needs to be used Table 4-1. Recommended fuse settings for applications using serial bootloader Parameter Value for RCB BODLEVEL Brown-out detection at VCC = 1.8V OCDEN Disabled JTAGEN Enabled SPIEN Enabled WDTON Disabled EESAVE Enabled BOOTSZ Boot flash size = 2048 words; start address = $F800 BOOTRST Enabled CKDIV8 Enabled CKOUT Disabled SUT_CKSEL Internal RC oscillator start-up time = 6CK + 0ms Fuse settings can also be specified in terms of bytes as given below Extended : 0xFE High : 0x92 Low : 0x42 Serial bootloader consists of two parts: embedded bootstrap code that should be loaded to the flash memory of ATmega128RFA1 and PC based application that sends data to the embedded bootstrap over serial link. Embedded bootstrap code uses the received data to program the internal flash memory of the MCU. A simple communication protocol is used to ensure proper programming. Motorola S-record (SREC) format files are supported as source images for the serial bootloader PC part. To upload (flash) the new image (.srec extension) into device program application memory (flash), a dedicated serial bootloader PC application (either a GUI or console) is executed on the host. This application is part of BitCloud SDK for megaRF and available at [23]. 66 AVR2102 8357D-AVR-06/12 AVR2102 For more details on serial bootloader programming to flash the image through serial bootloader application, please refer AVR2054 – Serial Bootloader User Guide [23]. To upload the application image using the programmer, we need to merge the boot loader image with the application image (srec_cat tool can be used). Then we have to upload the merged image to the board. For example, To upload the serial interface application image to Atmega256RFR2 zigbit modules, first we need to run the following command to merge the application image with the bootloader image after generating the application image. srec_cat Serial_Interface_Platform.hex Serial_Interface_Platform_BT.hex –intel -intel bootloader.hex -intel -o Then we can use Atmel studio programmer to flash the merged image to the target board. 5 Network and ZRC, ZID APIs This section describes the APIs provided for RF4Control network layer and ZRC profile.Application can access the profile/Network layer using these APIs.These APIs cover the data service and management service primitives as mentioned in the RF4CE specification. 5.1 Network layer APIs This section explains the APIs provided by the network layer to the application/profile. In all the request APIs, the application needs to provide the callback for the confirmation so that the network layer will call the same after processing the request. 5.1.1 nlde_data_request/confirm To initiate the data request from the application, the following API should be called. bool nlde_data_request(uint8_t PairingRef, profile_id_t ProfileId, uint16_t VendorId, uint8_t nsduLength, uint8_t *nsdu, uint8_t TxOptions, uint8_t Handle, FUNC_PTR confirm_cb ); Handle parameter can be used by the application to track the data request for the retry handling The confirmation proto type is shown below. void nlde_data_confirm(nwk_enum_t Status, uint8_t PairingRef, profile_id_t ProfileId, uint8_t Handle ); 5.1.2 nlme_set_request This API allows the application to change the NIB attributes. bool nlme_set_request(nib_attribute_t NIBAttribute, uint8_t NIBAttributeIndex, 67 8357D-AVR-06/12 uint8_t *NIBAttributeValue , FUNC_PTR confirm_cb ); The confirmation proto type is shown below. void nlme_set_confirm(nwk_enum_t Status, nib_attribute_t NIBAttribute, uint8_t NIBAttributeIndex); 5.1.3 nlme_get_request This API allows the application to get the NIB attribute value. bool nlme_get_request(nib_attribute_t NIBAttribute, uint8_t NIBAttributeIndex , FUNC_PTR confirm_cb); The confirmation proto type is shown below. void nlme_get_confirm(nwk_enum_t Status, nib_attribute_t NIBAttribute, uint8_t NIBAttributeIndex, void *NIBAttributeValue); 5.1.4 nlme_reset_request This API allows the application to request a reset of the NWK layer bool nlme_reset_request(bool SetDefaultNIB,FUNC_PTR confirm_cb) ; SetDefaultNIB – true for cold reset False for warm reset The confirmation proto type is shown below. void nlme_reset_confirm(nwk_enum_t Status); 5.1.5 nlme_start_request This API allows the application to request the NLME to start a network bool nlme_start_request(FUNC_PTR confirm_cb); The confirmation proto type is shown below. void nlme_start_confirm(nwk_enum_t Status); 5.1.6 nlme_rx_enable_request This API allows the application to request the network layer to either enable (for a finite period or until further notice) or disable the receiver bool nlme_rx_enable_request(uint32_t RxOnDuration, FUNC_PTR confirm_cb); The confirmation proto type is shown below. 68 AVR2102 8357D-AVR-06/12 AVR2102 void nlme_rx_enable_confirm(nwk_enum_t Status); 5.1.7 nlme_discovery_request This API allows the application to request the network layer to discover other devices of interest operating in the POS of the device bool nlme_discovery_request(uint16_t DstPANId, uint16_t DstNwkAddr, uint8_t OrgAppCapabilities, dev_type_t OrgDevTypeList[DEVICE_TYPE_LIST_SIZE], profile_id_t OrgProfileIdList[PROFILE_ID_LIST_SIZE], dev_type_t SearchDevType, uint8_t DiscProfileIdListSize, profile_id_t DiscProfileIdList[PROFILE_ID_LIST_SIZE], uint32_t DiscDuration, FUNC_PTR confirm_cb) ; The confirmation proto type is shown below. void nlme_discovery_confirm(nwk_enum_t Status, uint8_t NumNodes, node_desc_t *NodeDescList); 5.1.8 nlme_discovery_indication This API allows the application to receive the notification that a discovery request command has been received. void nlme_discovery_indication(nwk_enum_t Status, uint64_t SrcIEEEAddr, uint8_t OrgNodeCapabilities, uint16_t OrgVendorId, uint8_t OrgVendorString[7], uint8_t OrgAppCapabilities, uint8_t OrgUserString[15], dev_type_t OrgDevTypeList[3], profile_id_t OrgProfileIdList[7], dev_type_t SearchDevType, uint8_t RxLinkQuality); 5.1.9 nlme_discovery_response This API allows the application to respond to the discovery indication command received from the network layer bool nlme_discovery_response(nwk_enum_t Status, uint64_t DstIEEEAddr, uint8_t RecAppCapabilities, dev_type_t RecDevTypeList[3], profile_id_t RecProfileIdList[7], uint8_t DiscReqLQI); 5.1.10 nlme_auto_discovery_request This API allows the application to request the network layer to handle the receipt of discovery request command frames automatically. bool nlme_auto_discovery_request(uint8_t RecAppCapabilities, 69 8357D-AVR-06/12 dev_type_t RecDevTypeList[DEVICE_TYPE_LIST_SIZE], profile_id_t RecProfileIdList[PROFILE_ID_LIST_SIZE], uint32_t AutoDiscDuration,FUNC_PTR confirm_cb); 5.1.11 nlme_pair_request This API allows the application to request the network layer to pair with another device. This primitive would normally be issued following a discovery operation. bool nlme_pair_request(uint8_t LogicalChannel, uint16_t DstPANId, uint64_t DstIEEEAddr,uint8_t OrgAppCapabilities, dev_type_t OrgDevTypeList[DEVICE_TYPE_LIST_SIZE], profile_id_t OrgProfileIdList[PROFILE_ID_LIST_SIZE], uint8_t KeyExTransferCount, FUNC_PTR confirm_cb ); The network layer provides the confirmation to the application after receiving the response from the other node.If no response, it provides the corresponding error code in the status parameter. The confirmation proto type is shown below. void nlme_pair_confirm(nwk_enum_t Status, uint8_t PairingRef, uint16_t RecVendorId, uint8_t RecVendorString[7], uint8_t RecAppCapabilities, uint8_t RecUserString[15], dev_type_t RecDevTypeList[3], profile_id_t RecProfileIdList[7] ); 5.1.12 nlme_pair_indication This API allows the application to receive the notification of the reception of a pairing request command void nlme_pair_indication(nwk_enum_t Status, uint16_t SrcPANId, uint64_t SrcIEEEAddr, uint8_t OrgNodeCapabilities, uint16_t OrgVendorId, uint8_t OrgVendorString[7], uint8_t OrgAppCapabilities, uint8_t OrgUserString[15], dev_type_t OrgDevTypeList[3],profile_id_t OrgProfileIdList[7], uint8_t KeyExTransferCount, uint8_t ProvPairingRef); 5.1.13 nlme_pair_response This API allows the application to respond to the pairing request command received via nlme_pair_indication API bool nlme_pair_response(nwk_enum_t Status, uint16_t DstPANId, uint64_t DstIEEEAddr, uint8_t RecAppCapabilities, 70 AVR2102 8357D-AVR-06/12 AVR2102 dev_type_t RecDevTypeList[3],profile_id_t RecProfileIdList[7], uint8_t ProvPairingRef); 5.1.14 nlme_unpair_request This API allows the application to request the network layer to remove a pairing link with another device both in the local and remote pairing tables. bool nlme_unpair_request(uint8_t PairingRef, FUNC_PTR confirm_cb) ; The confirmation proto type is shown below. void nlme_unpair_confirm(uint8_t Status, uint8_t PairingRef); 5.1.15 nlme_unpair_indication This API allows the application to get the notification of the removal of a pairing link by another device void nlme_unpair_indication(uint8_t PairingRef); 5.1.16 nlme_unpair_response This API allows the application to notify the network layer to remove the pairing link indicated via the NLME-UNPAIR.indication primitive from the pairing table bool nlme_unpair_response(uint8_t PairingRef); 5.1.17 nlme_update_key_request This API allows the application to request the network layer to change the security link key of an entry in the pairing table. bool nlme_update_key_request(uint8_t PairingRef, uint8_t NewLinkKey[16] , FUNC_PTR confirm_cb ); The confirmation proto type is shown below. void nlme_update_key_confirm(nwk_enum_t Status, uint8_t PairingRef); 5.1.18 nlme_ch_agility_request This API allows the application to configure the channel agility mode. bool nwk_ch_agility_request(nwk_agility_mode_t AgilityMode , FUNC_PTR confirm_cb ); The confirmation proto type is shown below. void nwk_ch_agility_confirm(nwk_enum_t Status, bool ChannelChanged, uint8_t LogicalChannel); 71 8357D-AVR-06/12 5.1.19 nlme_ch_agility_indication This API allows the application to receive the indications when channel agility event has occured, i.e. the base channel has been changed automatically. The new channel is indicated by the parameter LogicalChannel void nwk_ch_agility_indication(uint8_t LogicalChannel); 5.2 ZRC profile APIs 5.2.1 zrc_cmd_request This API allows the application to send the zrc command.The profile will call the confirmation callback provided in the request after processing the request. bool zrc_cmd_request(uint8_t PairingRef, uint16_t VendorId, zrc_cmd_code_t CmdCode, uint8_t CmdLength, uint8_t *Cmd, uint8_t TxOptions, FUNC_PTR confirm_cb); The confirmation proto type is shown below. void zrc_cmd_confirm(nwk_enum_t Status, uint8_t PairingRef, cec_code_t RcCmd); 5.2.2 zrc_cmd_indication This API allows the application to receive the indication for the zrc command from the other node. void zrc_cmd_indication(uint8_t PairingRef, uint8_t nsduLength, uint8_t *nsdu, uint8_t RxLinkQuality, uint8_t RxFlags); 5.2.3 zrc_cmd_disc_request This API allows the application to send the zrc command discovery request to the other node. bool zrc_cmd_disc_request(uint8_t PairingRef, FUNC_PTR confirm_cb ); The confirmation proto type is shown below. void zrc_cmd_disc_confirm(nwk_enum_t Status, uint8_t PairingRef, uint8_t *SupportedCmd); 5.2.4 zrc_cmd_disc_indication This API allows the application to receive the indication for the command discovery request from the other node. void zrc_cmd_disc_indication(uint8_t PairingRef); 72 AVR2102 8357D-AVR-06/12 AVR2102 5.2.5 zrc_cmd_disc_response This API allows the application to send the response for the the command discovery request from the other node. bool zrc_cmd_disc_response(uint8_t PairingRef, uint8_t *SupportedCmd); 5.3 Registering ZRC indication callbacks The application needs to register the indication callbacks for network layer/ZRC profile at the network startup. The following APIs are provided by Network layer/ZRC profile to the application for registering the indication callbacks. void register_zrc_indication_callback(zrc_indication_callback_t *zrc_ind_callback); void register_nwk_indication_callback(nwk_indication_callback_t *nwk_ind_cb); The application needs to define the structure of the corresponding indication callback (zrc/network) and fill it with the required callbacks. In case of partially filled indication structure, we have to initialize other callbacks to NULL to ignore them. Then it should call the corresponding API passing the structure as an argument. 5.3.1 Indication structure The structure used for registering the network indication callbacks is shown below. typedef struct nwk_indication_callback { nwk_ch_agility_indication_cb_t nwk_ch_agility_indication_cb; nlme_unpair_indication_cb_t nlme_unpair_indication_cb; nlme_pair_indication_cb_t nlme_pair_indication_cb; nlme_discovery_indication_cb_t nlme_discovery_indication_cb; nlme_comm_status_indication_cb_t nlme_comm_status_indication_cb; zrc_data_indication_cb_t zrc_data_indication_cb; nlde_data_indication_cb_t nlde_data_indication_cb; } nwk_indication_callback_t; The structure used for registering the ZRC indication callbacks is shown below. typedef struct zrc_indication_callback { zrc_cmd_indication_cb_t zrc_cmd_indication_cb; zrc_cmd_disc_indication_cb_t zrc_cmd_disc_indication_cb; vendor_data_ind_cb_t vendor_data_ind_cb; } zrc_indication_callback_t; 73 8357D-AVR-06/12 5.4 ZID profile APIs This section describes the APIs provided for RF4Control network layer and ZID profile. Application can access the profile/Network layer using these APIs. These APIs cover the data service and management service primitives as mentioned in the RF4CE specification. This section explains the APIs provided by the network layer to the application/profile. In all the request APIs, the application needs to provide the callback for the confirmation so that the network layer will call the same after processing the request. 5.4.1 ZID APIs Common for Adaptor and Device 5.4.2 zid_report_data_request bool zid_report_data_request(uint8_t PairingRef, uint8_t numReportRecords, zid_report_data_record_t *reportRecord, uint8_t TxOptions , FUNC_PTR zid_report_data_confirm ); This API will be used to send the report data to other node. If ACK is set in the TxOptions then the report data will be sent over control pipe, otherwise API will use the interrupt pipe to send the data for no ACk option. void zid_report_data_confirm(nwk_enum_t Status, uint8_t PairingRef); This API will be used to get status for zid_report_data_request API 5.4.3 zid_report_data_indication void zid_report_data_indication(uint8_t PairingRef, uint8_t num_report_records, zid_report_data_record_t *zid_report_data_record_ptr, uint8_t RxLinkQuality, uint8_t RxFlags); This API will be used to get the indication from the profile when it receives any report data from other node. 5.4.4 zid_get_attribute_request bool zid_get_attribute_request(bool OTA, uint8_t PairingRef, zid_attribute_t ZIDAttribute, uint8_t ZIDAttributeIndex , FUNC_PTR zid_get_attribute_confirm ) This API is used to read the zid attributes from the local node as well as the remote node. For the remote node, OTA should be set to value 1 void zid_get_attribute_confirm(nwk_enum_t Status, uint8_t PairingRef, zid_attribute_t ZIDAttribute, uint8_t ZIDAttributeIndex, uint8_t AttributeSize, uint8_t *ZIDAttributeValue); 74 AVR2102 8357D-AVR-06/12 AVR2102 This API will be the response for the zid_get_attribute_request API. 5.4.5 zid_set_attribute_request bool zid_set_attribute_request(uint8_t PairingRef, zid_attribute_t ZIDAttribute, uint8_t ZIDAttributeIndex, uint8_t *ZIDAttributeValue , FUNC_PTR zid_set_attribute_confirm ) This API will be used for setting the zid Attributevalue of the local node. void zid_set_attribute_confirm(nwk_enum_t Status, uint8_t PairingRef, zid_attribute_t ZIDAttribute, uint8_t ZIDAttributeIndex); This API will be response to the zid_set_attribute_request API 5.4.6 ZID Adaptor APIs 5.4.7 zid_rec_connect_request bool zid_rec_connect_request(uint8_t RecAppCapabilities, dev_type_t RecDevTypeList[3], profile_id_t RecProfileIdList[7] , FUNC_PTR zid_connect_confirm ); This API is used to connect to the device .This takes care of pairing and configuration internally. After the configuration is done, the status will be indicated to the application using the following confirmation function. void zid_connect_confirm(nwk_enum_t Status, uint8_t PairingRef); This API will receive the response for the zid_rec_connect_request. 5.4.8 zid_get_report_data_request bool zid_get_report_data_request(uint8_t PairingRef,zid_report_types_t zid_report_type,zid_report_desc_t zid_report_desc, uint8_t TxOptions , FUNC_PTR zid_get_report_confirm ); The above API will be used to get the descriptor report from the device. void zid_get_report_confirm(nwk_enum_t Status, uint8_t PairingRef); This API is for the response to the zid_get_report_data_request API 5.4.9 zid_heartbeat_indication void zid_heartbeat_indication(uint8_t PairingRef); This API will be used to indicate to the Application Layer on reception of the Heart beat. 75 8357D-AVR-06/12 5.4.10 zid_standby_request bool zid_standby_request(bool standby_request , FUNC_PTR zid_standby_confirm ); This will put the adaptor into the power save mode as defined by the RF4CE spec. void zid_standby_confirm(nwk_enum_t Status, bool StdbyEnabled); The above API will be response to the zid_standby_request 5.4.11 zid_standby_leave_indication void zid_standby_leave_indication(void); This is the indication from the profile layer when the power save mode. adaptor comes out of 5.4.12 zid_set_report_request bool zid_set_report_request(uint8_t PairingRef, uint8_t payloadlength, uint8_t *payload,uint8_t TxOptions , FUNC_PTR confirm_cb ); This API will be used by the adaptor to set the report at device side. void zid_set_report_confirm_cb)(nwk_enum_t Status, uint8_t PairingRef); This is the confirmation API for set_report_request. 5.4.13 ZID Device APIs 5.4.14 zid_org_connect_request This API is used to connect to the adaptor. This internally takes care of pairing and the configuration. bool zid_org_connect_request(uint8_t OrgAppCapabilities, dev_type_t OrgDevTypeList[DEVICE_TYPE_LIST_SIZE], profile_id_t OrgProfileIdList[PROFILE_ID_LIST_SIZE], dev_type_t SearchDevType, uint8_t DiscProfileIdListSize, profile_id_t DiscProfileIdList[PROFILE_ID_LIST_SIZE] , FUNC_PTR zid_connect_confirm ); This API will inform the application about the connection status. void zid_connect_confirm(nwk_enum_t Status, uint8_tPairingRef); This API is called by the profile during the configuration phase.This gives the provision for the application to decided on the compatibility with the adaptor. It will return the if the adaptor is compatible. 76 AVR2102 8357D-AVR-06/12 AVR2102 bool check_zid_adaptor_compatibility(uint8_t PairingRef,uint8_t payload_length,uint8_t *payload); The below API will be used to send heartbeat request to the Adaptor. bool zid_heartbeat_request(uint8_t PairingRef , FUNC_PTR zid_heartbeat_confirm ); The below API is the confirmation for the zid_heartbeat_request. void zid_heartbeat_confirm(nwk_enum_t Status, uint8_t PairingRef); This API is the indication from the profile to the application when it receives the get_report zid command from the adaptor. void zid_get_report_indication(uint8_t PairingRef, zid_report_types_t zid_report_type, zid_report_desc_t zid_report_desc, uint8_t RxLinkQuality, uint8_t RxFlags); This API used to send the NULL report to the Adaptor during the configuration phase. bool zid_set_null_report(uint8_t report_index,null_report_t *null_report_ptr); 5.4.15 ZID Registering indication callbacks The application needs to register the indication callbacks for network layer/ZRC profile at the network startup. The following APIs are provided by Network layer/ZRC profile to the application for registering the indication callbacks. void register_zid_indication_callback(zid_indication_callback_t *zid_ind_callback); void register_nwk_indication_callback(nwk_indication_callback_t *nwk_ind_cb); The application needs to define the structure of the corresponding indication callback (ZRC/Network) and fill it with the required callbacks. In case of partially filled indication structure, we have to initialize other callbacks to NULL to ignore them. Then it should call the corresponding API passing the structure as an argument. 5.5 Indication structure The structure used for registering the network indication callbacks is shown below. typedef struct nwk_indication_callback { nwk_ch_agility_indication_cb_t nwk_ch_agility_indication_cb; nlme_unpair_indication_cb_t nlme_unpair_indication_cb; nlme_pair_indication_cb_t nlme_pair_indication_cb; nlme_discovery_indication_cb_t nlme_discovery_indication_cb; nlme_comm_status_indication_cb_t nlme_comm_status_indication_cb; zrc_data_indication_cb_t zrc_data_indication_cb; nlde_data_indication_cb_t nlde_data_indication_cb; 77 8357D-AVR-06/12 } nwk_indication_callback_t; Generally nwk_ch_agility_indication_cb and nlme_unpair_indication_cb indications will be available to the ZID application. Other indications will be internally handled by the ZID profile layer. The structure used for registering the ZRC indication callbacks is shown below. typedef struct zid_indication_callback_tag { #if (defined ZID_ADAPTOR) || (defined DOXYGEN) zid_heartbeat_indication_cb_t zid_heartbeat_indication_cb; zid_standby_leave_indication_cb_t zid_standby_leave_indication_cb; #endif #if (defined VENDOR_DATA) || (defined DOXYGEN) vendor_data_ind_cb_t vendor_data_ind_cb; #endif zid_report_data_indication_cb_t zid_report_data_indication_cb; #if (defined ZID_DEVICE) || (defined DOXYGEN) zid_get_report_indication_cb_t zid_get_report_indication_cb; #endif } zid_indication_callback_t; For example: static zid_indication_callback_t zid_ind; … main(void) { /* initializing the required ZID indication callbacks */ zid_ind.zid_report_data_indication_cb = zid_report_data_indication; register_zid_indication_callback(&zid_ind); … } Static void zid_report_data_indication (uint8_t PairingRef, uint8_t num_report_records, zid_report_data_record_t *zid_report_data_record_ptr, uint8_t RxLinkQuality, uint8_t RxFlags) { … … } 78 AVR2102 8357D-AVR-06/12 AVR2102 5.6 ZID Report data structure The nodes needs to use the following structure if it wants to send the standard descriptor data to the other node using REPORT_DATAzid command. The following is the master structure which in turnthe void pointer which shoud be initialized with the corresponding report data structure pointer before calling the zid_report_data_request. typedef struct zid_report_data_record_tag { zid_report_types_t report_type; zid_report_desc_t report_desc_identifier; void *report_data; }zid_report_data_record_t; 5.6.1.1 Mouse descriptor typedef struct mouse_desc_tag { uint8_t button0; uint8_t button1; uint8_t button2; uint8_t x_coordinate; uint8_t y_coordinate; }mouse_desc_t; Example: If the Applications want to send mouse report data then the Application must use this structure to fill out members then call the API to send out the mouse report data. Application: mouse_desc_t mouse_desc; zid_report_data_record_t zid_report_data_record; mouse_desc. button0 = 1; mouse_desc. Button1 = 0; mouse_desc. Button2 = 0; mouse_desc. x_coordinate = 0x02; mouse_desc. y_coordinate = 0x45; zid_report_data_record. report_type = INPUT; zid_report_data_record. report_desc_identifier = MOUSE; zid_report_data_record.report_data = & mouse_desc bool zid_report_data_request(uint8_t PairingRef, uint8_t numReportRecords, 79 8357D-AVR-06/12 zid_report_data_record_t *zid_report_record_ptr, uint8_t TxOptions , FUNC_PTR confirm_cb ) 5.6.1.2 Keyboard Input descriptor typedef struct keyboard_input_desc_tag { uint8_t modifier_keys; uint8_t key_code[6]; }keyboard_input_desc_t; 5.6.1.3 Keyboard Output descriptor typedef struct keyboard_output_desc_tag { uint8_t num_lock; uint8_t caps_lock; uint8_t scroll_lock; uint8_t compose; uint8_t kana; }keyboard_output_desc_t; 5.6.1.4 Touch sensor properties typedef struct touch_sensor_properties_tag { uint8_t no_of_additional_contacts; uint8_t origin; uint8_t reliable_index; uint8_t gestures; uint8_t resolution_x; uint8_t resolution_y; uint16_t max_coordinate_x; uint16_t max_coordinate_y; uint8_t shape; }touch_sensor_properties_t; 5.6.1.5 Tap support properties typedef struct tap_support_properties_tag { 80 AVR2102 8357D-AVR-06/12 AVR2102 uint8_t single_tap; uint8_t tap_and_a_half; uint8_t double_tap; uint8_t long_tap; }tap_support_properties_t; 5.6.1.6 Sync report typedef struct sync_report_tag { uint8_t gesture; uint8_t contact_count; }sync_report_t; 5.6.1.7 Contact data report typedef struct contact_data_report_tag { uint8_t contact_type; uint8_t contact_index; uint8_t contact_state; uint8_t major_axis_orientation; uint8_t pressure; uint16_t location_x; uint16_t location_y; uint16_t major_axis_length; uint16_t minor_axis_length; }contact_data_report_t; 5.6.1.8 Tap gesture report typedef struct tap_gesture_report_tag { uint8_t type; uint8_t finger_count; uint16_t location_x; uint16_t location_y; }tap_gesture_report_t; 5.6.1.9 Scroll gesture report typedef struct scroll_gesture_report_tag { 81 8357D-AVR-06/12 uint8_t type; uint8_t finger_count; uint8_t direction; uint16_t distance; }scroll_gesture_report_t; 5.6.1.10 Pinch gesture report typedef struct pinch_gesture_report_tag { uint8_t finger_present; uint8_t direction; uint16_t distance; uint16_t center_x; uint16_t center_y; }pinch_gesture_report_t; 5.6.1.11 Rotation gesture report typedef struct rotation_gesture_report_tag { uint8_t finger_present; uint8_t direction; uint8_t magnitude; }rotation_gesture_report_t; 6 Appendix 6.1 Applications along with the supported platforms S.No Application Supported Platforms 1 NWK – Serial Interface Host – SAM4L_XPLAINED_PRO NCP – AT32UC3A256S_RZ600_AT86RF212 AT32UC3A256S_RZ600_AT86RF231 ATMEGA256RFR2_XPLAINED_PRO ATXMEGA256A3U_RF212_ZIGBIT_EXT ATXMEGA256A3U_RF212_ZIGBIT_USB ATXMEGA256A3U_RF233_ZIGBIT_USB XMEGA_A3BU_XPLAINED_RZ600_RF212 XMEGA_A3BU_XPLAINED_RZ600_RF231 82 AVR2102 8357D-AVR-06/12 AVR2102 SAMR21_XPLAINED_PRO 2 ZRC - Serial Interface – Controller and Target Host – SAM4L_XPLAINED_PRO NCP – AT32UC3A256S_RZ600_AT86RF212 AT32UC3A256S_RZ600_AT86RF231 ATMEGA256RFR2_XPLAINED_PRO ATXMEGA256A3U_RF212_ZIGBIT_EXT ATXMEGA256A3U_RF212_ZIGBIT_USB ATXMEGA256A3U_RF233_ZIGBIT_USB XMEGA_A3BU_XPLAINED_RZ600_RF212 XMEGA_A3BU_XPLAINED_RZ600_RF231 SAMR21_XPLAINED_PRO 3 ZRC - Button Controller XMEGA_A3BU_XPLAINED_RZ600_RF212 XMEGA_A3BU_XPLAINED_RZ600_RF231 4 ZRC - Single button Controller Host – SAM4L_XPLAINED_PRO NCP – ATMEGA256RFR2_XPLAINED_PRO SAMR21_XPLAINED_PRO 5 ZRC - Terminal Target AT32UC3A256S_RZ600_AT86RF212 AT32UC3A256S_RZ600_AT86RF231 ATXMEGA256A3U_RF212B_ZIGBIT_USB ATXMEGA256A3U_RF233_ZIGBIT_USB SAMR21_XPLAINED_PRO 6 ZID – HID Adaptor ATMEGA256RFR2_Xplained_Pro, ATxMEGA256A3U Zigbit 7 ZID – HID Device Key Remote Controller RCB256RFR2 7 Abbreviations API Application Programming Interface BMM Buffer Management Module CRC Cyclic Redundancy Check CEC Consumer Electronics Control CSMA Carrier Sense Multiple Access EOT End Of Text ED Energy Detection EEPROM Electrically Erasable Programmable Read only memory FOTA Firmware Over The Air I2C Inter-Integrated Circuit 83 8357D-AVR-06/12 LED Light-Emitting Diode MCU Micro Controller Unit MAC Medium Access Control NVM Non-Volatile Memory NCP Network Co-processor PBP Push Button Pairing PAL Platform Abstraction Layer QMM Queue Management Module ORG Originator REC Recipient RCB Radio Controller Board RF4CE Radio Frequency For Consumer Electronics RC Remote Control SAL Security Abstraction Layer STB Security Tool Box SPI Serial Programming Interface SBC Single Button Controller SOC System On Chip 8 References [1] IEEE Standard 802.15.4TM-2006: Wireless Medium Access Control (MAC) and Physical Layer (PHY) Specifications for Low-Rate Wireless Personal Area Networks (WPANs) http://standards.ieee.org/getieee802/download/802.15.4-2006.pdf [2] Atmel RF4Control – ZigBee RF4CE Certified Platform http://www.atmel.com/dyn/products/tools_card_mcu.asp?tool_id=4712 [3] Atmel AT86RF212, 700/800/900 MHz transceiver for IEEE 802.15.4 http://www.atmel.com/dyn/products/product_card.asp?part_id=4349 [4] Atmel AT86RF231; Low Power 2.4 GHz Transceiver for IEEE 802.15.4 http://www.atmel.com/dyn/products/product_card.asp?part_id=4338 [5] Atmel Atmega256RFR2; Microcontroller with Low Power 2.4GHz Transceiver for ZigBee™ and IEEE 802.15.4™ http://www.atmel.com/devices/ATMEGA256RFR2.aspx [6] Atmel AVR ATmega1281 http://www.atmel.com/dyn/products/product_card.asp?part_id=3630 [7] AVR2025: IEEE 802.15.4 MAC Software Package under the asf link thirdparty\wireless\avr2025_mac 84 AVR2102 8357D-AVR-06/12 AVR2102 [8] Atmel ATAVRRZ541 AVR Z-Link 2.4 GHz Packet Sniffer Kit http://www.atmel.com/dyn/products/tools_card.asp?tool_id=4187 [9] Atmel AVR Studio 4, IDE for writing and debugging AVR applications http://www.atmel.com/dyn/products/tools_card.asp?tool_id=2725 [10] Atmel AVR JTAGICE mkII http://www.atmel.com/dyn/products/tools_card.asp?tool_id=3353 [11] ZigBee RF4CE http://www.zigbee.org/rf4ce [12] ZigBee RF4CE Specification Version 1.00; http://www.zigbee.org 094945r00ZB_RF4CE-Specification.pdf [13] ZigBee RF4CE ZRC Profile Specification; http://www.zigbee.org 094946r00ZB_RF4CE-CERC-Profile-Specification.pdf [14] ZigBee RF4CE ZID Profile Specification; http://www.zigbee.org/125649r00ZB_MWG- ZigBee _Input _Device_Standard_1.0 [15] High-Definition Multimedia Interface, Specification Version 1.3a http://www.hdmi.org [16] Sensor Terminal Board, Dresden Elektronik GmbH http://www.dresden-elektronik.de/shop/prod75.html [17] RCB Breakout Board, Dresden Elektronik GmbH http://www.dresden-elektronik.de/shop/prod84.html [18] ATmega128RFA1 Evaluation Kit (EK1) http://www.atmel.com/dyn/products/tools_card.asp?tool_id=4677 [19] AVR2044: RCB128RFA1 – Hardware User Manual http://www.atmel.com/dyn/products/app_notes.asp?family_id=676 [20] Minimalist GNU for Windows http://www.mingw.org or http://sourceforge.net/projects/mingw/ [21] Srec cat tool for windows http://www.srecord.sourceforge.net/ [22] RF4CE Evaluation Kit http://www.atmel.com/dyn/products/tools_card.asp?tool_id=4835 [23] BitCloud SDK for megaRF and AVR2054 Serial Bootloader User Guide http://www.atmel.com/bitcloud 85 8357D-AVR-06/12 9 Document revision history Please note that the referring page numbers in this section are referring to this document. The referring revisions in this section are referring to the document revision. 9.1 Rev. 8357F-MCU Wireless-02/14 Released with version AVR2102_RF4Control_v_2_0_1. Section 6.1 – Updated with newly added platforms Section-3.2 – ZID device application updated with gamepad demo. 9.2 Rev. 8357E-MCU Wireless-02/14 Released with version AVR2102_RF4Control_v_2_0_0. Atmel ZID Profile Information added. Section 1.2 – ZID HID Class Device Introduction added. Section 2.3 –ZID Profile Adaptor and HID Class Device functionality added Section 3.2 – ZID Profile Adaptor and HID Class Device example application added. Section 5.4 - ZID Profile APIs Support added. 9.3 Rev. 8357D-MCU Wireless-06/12 Released with version AVR2102_RF4Control_v_1_4_0 Section 5 – Network and ZRC APIs added Section 3.5.2 – ZRC serial interface message structure added 86 AVR2102 8357D-AVR-06/12 AVR2102 Section 3.4.4 – Serial interface message structure added Section 6.1 – Updated with the newly added platforms Table 2.7 – Updated with newly added build switches Section 3.1.4.3 – Procedure to initiate push button pairing updated 9.4 Rev. 8357C-MCU Wireless-08/11 Update section “Omitting 32 kHz crystal” 9.5 Rev. 8357B-MCU Wireless-08/11 Released with version AVR2102_RF4Control_v_1_3_0 Section „serial bootloader support‟ added. Section „special stack configuration‟ added 9.6 Rev. 8357A-MCU Wireless-01/11 Released with version AVR2102_RF4Control_v_1_0_1-1_2.1 Editorial changes of the RF4Control user guide User guide document number changed 9.7 Rev. 2102C-MCU Wireless-11/10 Released with version AVR2102_RF4Control_v_1_0_1-1_2 ZRC profile layer introduced including sections describing ZRC features and handling Push button pairing added as separate layer Vendor data handling added ZRC Target application added ZRC Serial Interface application added ATmega128RFA1-EK1 support added 9.8 Rev. 2102B-MCU Wireless-04/10 Released with version AVR2102_RF4Control_v_1_0_1-1_1_Lib.zip Section “Serial interface usage” added Table “Message codes and message lengths for the ZRC API.” updated ” added Section “Single Button Controller example application” added 9.9 Rev. 2102A-MCU Wireless-12/09 Initial Version: Internal hex file release Released with version AVR2102_RF4Control_v_1_0_1-1_0.zip 87 8357D-AVR-06/12 10 Table of Contents AVR2102: RF4Control - User Guide .................................................. 1 Features ............................................................................................... 1 1 Introduction ...................................................................................... 1 Atmel .................................................................................................... 1 MCU Wireless Solutions ..................................................................... 1 Application Note ................................................................................. 1 1.1 Remote controlling .............................................................................................. 2 1.2 HID Class Device ................................................................................................ 3 2 RF4Control – Stack implementation .............................................. 3 2.1 Architecture ......................................................................................................... 3 2.2 ZigBee Remote Control profile ............................................................................ 4 2.2.1 Push button pairing ................................................................................................... 5 2.2.2 Command discovery .................................................................................................. 7 2.2.3 RC command handling .............................................................................................. 7 2.3 ZigBee Input Device profile ................................................................................. 8 2.3.1 Push button pairing ................................................................................................... 9 2.3.2 Configuration phase .................................................................................................. 9 2.3.3 ZID Command Handling .......................................................................................... 10 2.4 Channel agility ................................................................................................... 11 2.5 Vendor-specific data handling ........................................................................... 12 2.6 RF4Control firmware API .................................................................................. 13 2.7 Stack configuration ............................................................................................ 13 2.7.1 WATCHDOG .............................................................. Error! Bookmark not defined. 2.8 Stack porting...................................................................................................... 15 3 Example applications .................................................................... 16 3.1 ZRC example application .................................................................................. 16 3.1.1 Button Controller example application ..................................................................... 16 3.1.2 Terminal target example application ........................................................................ 18 3.1.3 Single Button Controller example application .......................................................... 23 3.2 ZID example application .................................................................................... 27 3.2.1 Introduction.............................................................................................................. 27 3.2.2 ZID Key Remote Controller Device Application ....................................................... 29 3.2.3 ZID USB Adaptor Application .................................................................................. 31 3.2.4 ZID Terminal Adaptor Application ............................................................................ 32 3.2.5 ZID Adaptor operations ........................................................................................... 34 3.2.6 Cold reset and warm reset ...................................................................................... 34 3.2.7 Starting the node ..................................................................................................... 34 3.2.8 ZID Attribute Initialization......................................................................................... 34 3.2.9 ZID connection ........................................................................................................ 35 3.2.10 ZID Report data from the ZID device ..................................................................... 35 88 AVR2102 8357D-AVR-06/12 AVR2102 3.2.11 ZID example application flow ................................................................................. 35 3.3 Serial Interface example application ................................................................. 36 3.3.1 Introduction.............................................................................................................. 36 3.3.2 Message structure ................................................................................................... 37 3.3.3 Message codes ....................................................................................................... 39 3.3.4 Serial Interface - message structure ........................................................................ 40 3.3.5 Protocol adaption .................................................................................................... 52 3.3.6 Serial interface usage .............................................................................................. 52 3.4 ZigBee Remote Control serial interface ............................................................ 56 3.4.1 ZRC Serial Interface message codes ...................................................................... 56 3.4.2 ZRC serial interface message structure .................................................................. 57 3.4.3 ZRC Serial Interface usage ..................................................................................... 62 4 Serial bootloader support ............................................................. 66 4.1 Functionality Overview ...................................................................................... 66 5 Network and ZRC, ZID APIs .......................................................... 67 5.1 Network layer APIs ............................................................................................ 67 5.1.1 nlde_data_request/confirm ...................................................................................... 67 5.1.2 nlme_set_request .................................................................................................... 67 5.1.3 nlme_get_request .................................................................................................... 68 5.1.4 nlme_reset_request ................................................................................................. 68 5.1.5 nlme_start_request .................................................................................................. 68 5.1.6 nlme_rx_enable_request ......................................................................................... 68 5.1.7 nlme_discovery_request.......................................................................................... 69 5.1.8 nlme_discovery_indication ...................................................................................... 69 5.1.9 nlme_discovery_response ....................................................................................... 69 5.1.10 nlme_auto_discovery_request ............................................................................... 69 5.1.11 nlme_pair_request ................................................................................................. 70 5.1.12 nlme_pair_indication.............................................................................................. 70 5.1.13 nlme_pair_response .............................................................................................. 70 5.1.14 nlme_unpair_request ............................................................................................. 71 5.1.15 nlme_unpair_indication.......................................................................................... 71 5.1.16 nlme_unpair_response .......................................................................................... 71 5.1.17 nlme_update_key_request .................................................................................... 71 5.1.18 nlme_ch_agility_request ........................................................................................ 71 5.1.19 nlme_ch_agility_indication..................................................................................... 72 5.2 ZRC profile APIs ................................................................................................ 72 5.2.1 zrc_cmd_request ..................................................................................................... 72 5.2.2 zrc_cmd_indication .................................................................................................. 72 5.2.3 zrc_cmd_disc_request............................................................................................. 72 5.2.4 zrc_cmd_disc_indication ......................................................................................... 72 5.2.5 zrc_cmd_disc_response .......................................................................................... 73 5.3 Registering ZRC indication callbacks ................................................................ 73 5.3.1 Indication structure .................................................................................................. 73 5.4 ZID profile APIs ................................................................................................. 74 5.4.1 ZID APIs Common for Adaptor and Device ............................................................. 74 5.4.2 zid_report_data_request.......................................................................................... 74 5.4.3 zid_report_data_indication ...................................................................................... 74 5.4.4 zid_get_attribute_request ........................................................................................ 74 5.4.5 zid_set_attribute_request ........................................................................................ 75 5.4.6 ZID Adaptor APIs .................................................................................................... 75 89 8357D-AVR-06/12 5.4.7 zid_rec_connect_request ........................................................................................ 75 5.4.8 zid_get_report_data_request ................................................................................... 75 5.4.9 zid_heartbeat_indication.......................................................................................... 75 5.4.10 zid_standby_request ............................................................................................. 76 5.4.11 zid_standby_leave_indication ................................................................................ 76 5.4.12 zid_set_report_request .......................................................................................... 76 5.4.13 ZID Device APIs .................................................................................................... 76 5.4.14 zid_set_report_request .......................................................................................... 76 5.4.15 ZID Registering indication callbacks ...................................................................... 77 5.5 Indication structure ............................................................................................ 77 5.6 ZID Report data structure .................................................................................. 79 6 Appendix......................................................................................... 82 6.1 Applications along with the supported platforms ............................................... 82 7 Abbreviations ................................................................................. 83 8 References...................................................................................... 84 9 Document revision history ............................................................ 86 9.1 Rev. 8357E-MCU Wireless-02/14 ..................................................................... 86 9.2 Rev. 8357D-MCU Wireless-06/12 ..................................................................... 86 9.3 Rev. 8357C-MCU Wireless-08/11 ..................................................................... 87 9.4 Rev. 8357B-MCU Wireless-08/11 ..................................................................... 87 9.5 Rev. 8357A-MCU Wireless-01/11 ..................................................................... 87 9.6 Rev. 2102C-MCU Wireless-11/10 ..................................................................... 87 9.7 Rev. 2102B-MCU Wireless-04/10 ..................................................................... 87 9.8 Rev. 2102A-MCU Wireless-12/09 ..................................................................... 87 10 Table of Contents ......................................................................... 88 90 AVR2102 8357D-AVR-06/12 Atmel Corporation Atmel Asia Limited Atmel Munich GmbH Atmel Japan G.K. 2325 Orchard Parkway Unit 01-5 & 16, 19F Business Campus 16F Shin-Osaki Kangyo Building San Jose, CA 95131 BEA Tower, Millennium City 5 Parkring 4 1-6-4 Osaki USA 418 Kwun Tong Road D-85748 Garching b. Munich Shinagawa-ku, Tokyo 141-0032 Tel: (+1)(408) 441-0311 Kwun Tong, Kowloon GERMANY JAPAN Fax: (+1)(408) 487-2600 HONG KONG Tel: (+49) 89-31970-0 Tel: (+81)(3) 6417-0300 www.atmel.com Tel: (+852) 2245-6100 Fax: (+49) 89-3194621 Fax: (+81)(3) 6417-0370 Fax: (+852) 2722-1369 © 2012 Atmel Corporation. All rights reserved. / Rev.: Atmel®, logo and combinations thereof, and others are registered trademarks or trademarks of Atmel Corporation or its subsidiaries. Other terms and product names may be trademarks of others. Disclaimer: The information in this document is provided in connection with Atmel products. No license, express or implied, by estoppel or otherwise, to any intellectual property right is granted by this document or in connection with the sale of Atmel products. EXCEPT AS SET FORTH IN THE ATMEL TERMS AND CONDITIONS OF SALES LOCATED ON THE ATMEL WEBSITE, ATMEL ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS AND PROFITS, BUSINESS INTERRUPTION, OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF ATMEL HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Atmel makes no representations or warranties with respect to the accuracy or completeness of the contents of this document and reserves the right to make changes to specifications and products descriptions at any time without notice. Atmel does not make any commitment to update the information contained herein. Unless specifically provided otherwise, Atmel products are not suitable for, and shall not be used in, automotive applications. Atmel products are not intended, authorized, or warranted for use as components in applications intended to support or sustain life.
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.5 Linearized : No Page Count : 91 Language : en-US Tagged PDF : Yes Title : AVR2102: RF4Control - User Guide Author : Atmel Corporation Creator : Microsoft® Office Word 2007 Create Date : 2014:04:25 17:03:13 Modify Date : 2014:04:25 17:03:13 Producer : Microsoft® Office Word 2007EXIF Metadata provided by EXIF.tools