EmberZNet 4.7.2 API Reference For the EM260 Co-Processor

graphics/FrontCover.jpg

EmberZNet 4.7.2 API Reference:For the EM260 Co-Processor

December 18, 2012120-3020-000-4720

Silicon Laboratories Inc.400 West Cesar ChavezAustin, TX 78701Tel:1+(512) 416-8500Fax:1+(512) 416-9669Toll Free:1+(877) 444-3032www.silabs.com

www.silabs.com

graphics/FrontCover.jpg

Disclaimer

The information in this document is believed to be accurate in all respects at the timeof publication but is subject to change without notice. Silicon Laboratories assumes noresponsibility for errors or omissions, and disclaims responsibility for the functioning ofundescribed features or parameters. Silicon Laboratories makes no warranty, represen-tation, or gaurantee regarding the suitability of its products for any particular purpose,nor does Silicon Laboratories assume any liability arising out of hte application or useor any product or circuit, and specifically disclaims any and all liability, including with-out limitation consequential or incidental damages. Silicon Laboratories products are notdesigned, indended, or authorized for use in applications indended to support or sustainlife, or for any other application in which the failure of the Silicon Laboratories prod-uct could create a situation where personal injury or death may occur. Should Buyerpurchase or use Silicon Laboratories products for any such unintended or unauthorizedapplication, Buyer shall indemnify and hold Silicon Laboratories harmless against allclaims and damages.

Silicon Laboratories, Silicon Labs, and Ember are trademarks of Silicon LaboratoriesInc.

Other products or brandnames mentioned herin are trademarks or registered trademarksof their respective holders.

3

About This Guide

Purpose

This document is a unified collection of API reference documentation covering EmberZNet PRO Stack.

Silicon Labs recommends that you use this document as a searchable reference. It includes all of theinformation contained in the html version of these materials that are provided as an online reference fordevelopers of EmberZNet-based ZigBee wireless applications. There are three key advantages that thisdocument provides over the online html versions:

• Everything is contained in this single document.

• This document is fully searchable using the Adobe Acrobat search engine that is part of the freeAcrobat Reader (available from www.adobe.com).

• This document can be easily printed.

Audience

This document is intended for use by programmers and designers developing ZigBee wireless network-ing products based on the EmberZNet PRO Stack Software. This document assumes that the reader hasa solid understanding of embedded systems design and programming in the C language. Experience withnetworking and radio frequency systems is useful but not expected.

Getting Help

Development kit customers are eligible for training and technical support. You can use the Silicon Labsweb site www.silabs.com/zigbee to obtain information about all Ember products and services.

You can also contact customer support at www.silabs.com/zigbee-support.html.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

www.silabs.com/zigbee

www.silabs.com/zigbee-support.html

4

Chapter 1

Introduction

The EmberZNet API Reference documentation for the EM260 includes the following API sets:

• Ember Common

• Hardware Abstraction Layer (HAL) API Reference

• Application Utilities API Reference

EmberZNet 4.7.2 API EM260 120-3020-000-4720

5

Chapter 2

Deprecated List

File ami-inter-pan-host.hThe ami-inter-pan library is deprecated and will be removed in a future release. Similar functionalityis available in the Inter-PAN plugin in Application Framework.

File ami-inter-pan.hThe ami-inter-pan library is deprecated and will be removed in a future release. Similar functionalityis available in the Inter-PAN plugin in Application Framework.

File command-interpreter.hcommand-interpreter is deprecated and will be removed in a future release. Use command-interpreter2instead.

File fragment-host.hThe fragment library is deprecated and will be removed in a future release. Similar functionality isavailable in the Fragmentation plugin in Application Framework.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

6

Chapter 3

Module Index

3.1 Modules

Here is a list of all modules:

Ember Common . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Ember Common Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Sending and Receiving Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Ember Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Smart Energy Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Debugging Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Hardware Abstraction Layer (HAL) API Reference . . . . . . . . . . . . . . . . . . . . . . . . 98Common Microcontroller Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Sample APIs for Peripheral Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Serial UART Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104Hardware-Specific UART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

ADC Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Button Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119Buzzer Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121LED Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Carrier Board Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129SPI Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

System Timer Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151HAL Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

Cyclic Redundancy Code (CRC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157Random Number Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

Asynchronous Serial Host (ASH) Framework . . . . . . . . . . . . . . . . . . . . . . . . . 160Application Utilities API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

Forming and Joining Networks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172Bootloading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Stand-Alone Bootloader Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179Stand-Alone Bootloader for EZSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184Stand-Alone Bootloader Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

Command Interpreter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194ZigBee Device Object (ZDO) Information . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

ZigBee Device Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

EmberZNet 4.7.2 API EM260 120-3020-000-4720

7

Message Fragmentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213Network Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217Serial Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220ASH Application Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

Commands2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

EmberZNet 4.7.2 API EM260 120-3020-000-4720

8

Chapter 4

Data Structure Index

4.1 Data Structures

Here are the data structures with brief descriptions:

ashBufferBuffer to hold a DATA frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

AshCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258AshFreeList

Simple free list (singly-linked list) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262AshHostConfig

Configuration parameters: values must be defined before calling ashResetNcp() or ash-Start(). Note that all times are in milliseconds . . . . . . . . . . . . . . . . . . . . . . 263

AshQueueSimple queue (singly-linked list) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

EmberAesMmoHashContextThis data structure contains the context data when calculating an AES MMO hash (mes-sage digest) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

EmberApsFrameAn in-memory representation of a ZigBee APS frame of an incoming or outgoing mes-sage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

EmberBindingTableEntryDefines an entry in the binding table . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

EmberCertificateDataThis data structure contains the certificate data that is used for Certificate Based KeyExchange (CBKE) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

EmberCommandEntryCommand entry for a command table . . . . . . . . . . . . . . . . . . . . . . . . . . 270

EmberCommandStateSThe command state structure. Using a structure allows commands to be read frommultiple sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

EmberCurrentSecurityStateThis describes the security features used by the stack for a joined device . . . . . . . . 275

EmberEventControlControl structure for events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

EmberInitialSecurityStateThis describes the Initial Security features and requirements that will be used whenforming or joining the network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

EmberZNet 4.7.2 API EM260 120-3020-000-4720

9

EmberKeyDataThis data structure contains the key data that is passed into various other functions . . 278

EmberKeyStructThis describes a one of several different types of keys and its associated data . . . . . 278

EmberMacFilterMatchStructThis structure indicates a matching raw MAC message has been received by the appli-cation configured MAC filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280

EmberMessageDigestThis data structure contains an AES-MMO Hash (the message digest) . . . . . . . . . 280

EmberMfgSecurityStructThis structure is used to get/set the security config that is stored in manufacturing tokens 281

EmberMulticastTableEntryDefines an entry in the multicast table . . . . . . . . . . . . . . . . . . . . . . . . . . 281

EmberNeighborTableEntryDefines an entry in the neighbor table . . . . . . . . . . . . . . . . . . . . . . . . . . 282

EmberNetworkInitStructDefines the network initialization configuration that should be used when ::ember-NetworkInitExtended() is called by the application . . . . . . . . . . . . . . . . . . . 284

EmberNetworkParametersHolds network parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284

EmberPrivateKeyDataThis data structure contains the private key data that is used for Certificate Based KeyExchange (CBKE) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

EmberPublicKeyDataThis data structure contains the public key data that is used for Certificate Based KeyExchange (CBKE) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

EmberRouteTableEntryDefines an entry in the route table . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

EmberSignatureDataThis data structure contains a DSA signature. It is the bit concatenation of the ’r’ and’s’ components of the signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288

EmberSmacDataThis data structure contains the Shared Message Authentication Code (SMAC) datathat is used for Certificate Based Key Exchange (CBKE) . . . . . . . . . . . . . . . . 289

EmberTaskControlControl structure for tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

EmberVersionVersion struct containing all version information . . . . . . . . . . . . . . . . . . . . 290

EmberZigbeeNetworkDefines a ZigBee network and the associated parameters . . . . . . . . . . . . . . . . 291

InterPanHeaderA struct for keeping track of all of the header info . . . . . . . . . . . . . . . . . . . . 292

EmberZNet 4.7.2 API EM260 120-3020-000-4720

10

Chapter 5

File Index

5.1 File List

Here is a list of all files with brief descriptions:

_EM260_API.topStarting page for the Ember API documentation for the EM260 exclusively for buildingdocumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

adc.hHeader for A/D converter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

avr-atmega/adc.hHeader for Atmel AVR A/D converter . . . . . . . . . . . . . . . . . . . . . . . . . . 296

ami-inter-pan-host.hUtilities for sending and receiving ZigBee AMI InterPAN messages. See Sending andReceiving Messages for documentation . . . . . . . . . . . . . . . . . . . . . . . . . 297

ami-inter-pan.hUtilities for sending and receiving ZigBee AMI InterPAN messages. See Sending andReceiving Messages for documentation . . . . . . . . . . . . . . . . . . . . . . . . . 299

ash-common.hHeader for ASH common functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

ash-host-io.hHeader for ASH host I/O functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

ash-host-priv.hPrivate header for ASH Host functions . . . . . . . . . . . . . . . . . . . . . . . . . 303

ash-host-queues.hHeader for ASH host queue functions . . . . . . . . . . . . . . . . . . . . . . . . . . 305

ash-host-ui.hHeader for ASH Host user interface functions . . . . . . . . . . . . . . . . . . . . . . 306

ash-host.hHeader for ASH Host functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308

ash-protocol.hASH protocol header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

bootload-ezsp-utils.hUtilities used for performing stand-alone bootloading over EZSP. See Bootloading fordocumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

bootload-utils.hUtilities used for performing stand-alone bootloading. See Bootloading for documen-tation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

EmberZNet 4.7.2 API EM260 120-3020-000-4720

11

bootloader-interface-standalone-v1.hDefinition of the interface to the standalone bootloader . . . . . . . . . . . . . . . . . 317

bootloader-interface-standalone.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319bootloader.h

Micro-specific functions used in conjunction with either bootloader . . . . . . . . . . 319button.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321buzzer.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322cbke-crypto-engine.h

EmberZNet Smart Energy security API. See Smart Energy Security for documention . 323command-interpreter.h

Processes commands coming from the serial port. See Command Interpreter for docu-mentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

command-interpreter2.hProcesses commands coming from the serial port. See Commands2 for documentation 331

crc.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333dev0470.h

Functions specific to the dev0470 breakout board . . . . . . . . . . . . . . . . . . . . 336dev0473.h

Functions specific to the dev0473 breakout board (ATmega128L-EM260) . . . . . . . 340ember-configuration-defaults.h

User-configurable stack memory allocation defaults . . . . . . . . . . . . . . . . . . . 344ember-debug.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348ember-types.h

Ember data type definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362error-def.h

Return-code definitions for EmberZNet stack API functions . . . . . . . . . . . . . . 383error.h

Return codes for Ember API functions and module definitions . . . . . . . . . . . . . 394ezsp-host-configuration-defaults.h

User-configurable parameters for host applications . . . . . . . . . . . . . . . . . . . 395form-and-join.h

Utilities for forming and joining networks . . . . . . . . . . . . . . . . . . . . . . . . 396fragment-host.h

Fragmented message support for EZSP Hosts. Splits long messages into smaller blocksfor transmission and reassembles received blocks. See Message Fragmentation for doc-umentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398

hal.hGeneric set of HAL includes for all platforms . . . . . . . . . . . . . . . . . . . . . . 399

host.hSample API functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401

iar.hCompiler/platform-specific definitions and typedefs for the IAR AVR C compiler . . . 409

led.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414linux-serial.h

Ember serial functionality specific to a PC with Unix library support . . . . . . . . . . 415micro.h

Full HAL functions common across all microcontroller-specific files. See CommonMicrocontroller Functions for documentation . . . . . . . . . . . . . . . . . . . . . . 416

avr-atmega/32/micro.hUtility and convenience functions for ATmega32 microcontroller See Common Micro-controller Functions for documentation . . . . . . . . . . . . . . . . . . . . . . . . . 419

avr-atmega/128/micro.hUtility and convenience functions for ATmega128 microcontroller . . . . . . . . . . . 422

EmberZNet 4.7.2 API EM260 120-3020-000-4720

12

network-manager.hUtilities for use by the ZigBee network manager. See Network Manager for documen-tation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424

random.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42432/reserved-ram.h

Memory allocations that allow for data sharing between the normally running applica-tion and bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427

128/reserved-ram.hMemory allocations that allow for data sharing between the normally running applica-tion and bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433

hal/micro/serial.hSerial hardware abstraction layer interfaces. See Serial UART Communication for doc-umentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435

app/util/serial/serial.hHigh-level serial communication functions . . . . . . . . . . . . . . . . . . . . . . . 440

spi-protocol.hExample AVR SPI Protocol implementation for interfacing with EM260 . . . . . . . 442

spi.hGeneric SPI manipulation routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443

system-timer.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444avr-atmega/32/system-timer.h

Functions that provide access to the system clock for ATmega32 microcontroller . . . 445avr-atmega/128/system-timer.h

Functions that provide access to the system clock for ATmega128 microcontroller . . 445uart.h

Prototypes and defines for the hardware-specific UARTs . . . . . . . . . . . . . . . . 446zigbee-device-common.h

ZigBee Device Object (ZDO) functions available on all platforms. See ZigBee DeviceObject (ZDO) Information for documentation . . . . . . . . . . . . . . . . . . . . . . 448

zigbee-device-host.hZigBee Device Object (ZDO) functions not provided by the stack. See ZigBee DeviceObject (ZDO) Information for documentation . . . . . . . . . . . . . . . . . . . . . . 451

zigbee-device-stack.hZigBee Device Object (ZDO) functions included in the stack . . . . . . . . . . . . . . 452

EmberZNet 4.7.2 API EM260 120-3020-000-4720

13

Chapter 6

Module Documentation

6.1 Ember Common

Modules

• Ember Common Data Types• Sending and Receiving Messages• Ember Status Codes• Smart Energy Security• Configuration• Debugging Utilities

6.1.1 Detailed Description

EmberZNet 4.7.2 API EM260 120-3020-000-4720

14

6.2 Ember Common Data Types

Data Structures

• struct EmberVersionVersion struct containing all version information.

• struct EmberZigbeeNetworkDefines a ZigBee network and the associated parameters.

• struct EmberNetworkInitStructDefines the network initialization configuration that should be used when ::emberNetworkInitExtended() iscalled by the application.

• struct EmberNetworkParametersHolds network parameters.

• struct EmberApsFrameAn in-memory representation of a ZigBee APS frame of an incoming or outgoing message.

• struct EmberBindingTableEntryDefines an entry in the binding table.

• struct EmberNeighborTableEntryDefines an entry in the neighbor table.

• struct EmberRouteTableEntryDefines an entry in the route table.

• struct EmberMulticastTableEntryDefines an entry in the multicast table.

• struct EmberEventControlControl structure for events.

• struct EmberTaskControlControl structure for tasks.

• struct EmberKeyDataThis data structure contains the key data that is passed into various other functions.

• struct EmberCertificateDataThis data structure contains the certificate data that is used for Certificate Based Key Exchange (CBKE).

• struct EmberPublicKeyDataThis data structure contains the public key data that is used for Certificate Based Key Exchange (CBKE).

• struct EmberPrivateKeyDataThis data structure contains the private key data that is used for Certificate Based Key Exchange (CBKE).

• struct EmberSmacDataThis data structure contains the Shared Message Authentication Code (SMAC) data that is used for Certifi-cate Based Key Exchange (CBKE).

• struct EmberSignatureDataThis data structure contains a DSA signature. It is the bit concatenation of the ’r’ and ’s’ components of thesignature.

• struct EmberMessageDigestThis data structure contains an AES-MMO Hash (the message digest).

• struct EmberAesMmoHashContextThis data structure contains the context data when calculating an AES MMO hash (message digest).

• struct EmberInitialSecurityStateThis describes the Initial Security features and requirements that will be used when forming or joining thenetwork.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

15

• struct EmberCurrentSecurityStateThis describes the security features used by the stack for a joined device.

• struct EmberKeyStructThis describes a one of several different types of keys and its associated data.

• struct EmberMfgSecurityStructThis structure is used to get/set the security config that is stored in manufacturing tokens.

• struct EmberMacFilterMatchStructThis structure indicates a matching raw MAC message has been received by the application configuredMAC filters.

Macros

• #define EMBER_JOIN_DECISION_STRINGS• #define EMBER_DEVICE_UPDATE_STRINGS• #define emberInitializeNetworkParameters(parameters)• #define EMBER_COUNTER_STRINGS• #define EMBER_STANDARD_SECURITY_MODE• #define EMBER_TRUST_CENTER_NODE_ID• #define EMBER_NO_TRUST_CENTER_MODE• #define EMBER_GLOBAL_LINK_KEY• #define EMBER_MFG_SECURITY_CONFIG_MAGIC_NUMBER• #define EMBER_MAC_FILTER_MATCH_ENABLED_MASK• #define EMBER_MAC_FILTER_MATCH_ON_PAN_DEST_MASK• #define EMBER_MAC_FILTER_MATCH_ON_PAN_SOURCE_MASK• #define EMBER_MAC_FILTER_MATCH_ON_DEST_MASK• #define EMBER_MAC_FILTER_MATCH_ON_SOURCE_MASK• #define EMBER_MAC_FILTER_MATCH_ENABLED• #define EMBER_MAC_FILTER_MATCH_DISABLED• #define EMBER_MAC_FILTER_MATCH_ON_PAN_DEST_NONE• #define EMBER_MAC_FILTER_MATCH_ON_PAN_DEST_LOCAL• #define EMBER_MAC_FILTER_MATCH_ON_PAN_DEST_BROADCAST• #define EMBER_MAC_FILTER_MATCH_ON_PAN_SOURCE_NONE• #define EMBER_MAC_FILTER_MATCH_ON_PAN_SOURCE_NON_LOCAL• #define EMBER_MAC_FILTER_MATCH_ON_PAN_SOURCE_LOCAL• #define EMBER_MAC_FILTER_MATCH_ON_DEST_BROADCAST_SHORT• #define EMBER_MAC_FILTER_MATCH_ON_DEST_UNICAST_SHORT• #define EMBER_MAC_FILTER_MATCH_ON_DEST_UNICAST_LONG• #define EMBER_MAC_FILTER_MATCH_ON_SOURCE_LONG• #define EMBER_MAC_FILTER_MATCH_ON_SOURCE_SHORT• #define EMBER_MAC_FILTER_MATCH_END

Typedefs

• typedef int8u EmberTaskId• struct {

EmberEventControl ∗ controlvoid(∗ handler )(void)

} EmberEventData

• typedef int16u EmberMacFilterMatchData• typedef int8u EmberLibraryStatus

EmberZNet 4.7.2 API EM260 120-3020-000-4720

16

Enumerations

• enum EmberNodeType {EMBER_UNKNOWN_DEVICE, EMBER_COORDINATOR, EMBER_ROUTER, EMBER_EN-D_DEVICE,EMBER_SLEEPY_END_DEVICE, EMBER_MOBILE_END_DEVICE }

• enum EmberNetworkInitBitmask { EMBER_NETWORK_INIT_NO_OPTIONS, EMBER_NETW-ORK_INIT_PARENT_INFO_IN_TOKEN }

• enum EmberApsOption {EMBER_APS_OPTION_NONE, EMBER_APS_OPTION_DSA_SIGN, EMBER_APS_OPTION-_ENCRYPTION, EMBER_APS_OPTION_RETRY,EMBER_APS_OPTION_ENABLE_ROUTE_DISCOVERY, EMBER_APS_OPTION_FORCE_R-OUTE_DISCOVERY, EMBER_APS_OPTION_SOURCE_EUI64, EMBER_APS_OPTION_DE-STINATION_EUI64,EMBER_APS_OPTION_ENABLE_ADDRESS_DISCOVERY, EMBER_APS_OPTION_POLL_-RESPONSE, EMBER_APS_OPTION_ZDO_RESPONSE_REQUIRED, EMBER_APS_OPTION-_FRAGMENT }

• enum EmberIncomingMessageType {EMBER_INCOMING_UNICAST, EMBER_INCOMING_UNICAST_REPLY, EMBER_INCOM-ING_MULTICAST, EMBER_INCOMING_MULTICAST_LOOPBACK,EMBER_INCOMING_BROADCAST, EMBER_INCOMING_BROADCAST_LOOPBACK }

• enum EmberOutgoingMessageType {EMBER_OUTGOING_DIRECT, EMBER_OUTGOING_VIA_ADDRESS_TABLE, EMBER_O-UTGOING_VIA_BINDING, EMBER_OUTGOING_MULTICAST,EMBER_OUTGOING_BROADCAST }

• enum EmberNetworkStatus {EMBER_NO_NETWORK, EMBER_JOINING_NETWORK, EMBER_JOINED_NETWORK, E-MBER_JOINED_NETWORK_NO_PARENT,EMBER_LEAVING_NETWORK }

• enum EmberNetworkScanType { EMBER_ENERGY_SCAN, EMBER_ACTIVE_SCAN }• enum EmberBindingType { EMBER_UNUSED_BINDING, EMBER_UNICAST_BINDING, EM-

BER_MANY_TO_ONE_BINDING, EMBER_MULTICAST_BINDING }• enum EmberJoinDecision { EMBER_USE_PRECONFIGURED_KEY, EMBER_SEND_KEY_IN-

_THE_CLEAR, EMBER_DENY_JOIN, EMBER_NO_ACTION }• enum EmberDeviceUpdate {

EMBER_STANDARD_SECURITY_SECURED_REJOIN, EMBER_STANDARD_SECURITY_-UNSECURED_JOIN, EMBER_DEVICE_LEFT, EMBER_STANDARD_SECURITY_UNSECU-RED_REJOIN,EMBER_HIGH_SECURITY_SECURED_REJOIN, EMBER_HIGH_SECURITY_UNSECURED-_JOIN, EMBER_HIGH_SECURITY_UNSECURED_REJOIN, EMBER_REJOIN_REASON_NO-NE,EMBER_REJOIN_DUE_TO_NWK_KEY_UPDATE, EMBER_REJOIN_DUE_TO_LEAVE_ME-SSAGE, EMBER_REJOIN_DUE_TO_NO_PARENT, EMBER_REJOIN_DUE_TO_ZLL_TOUC-HLINK,EMBER_REJOIN_DUE_TO_APP_EVENT_5, EMBER_REJOIN_DUE_TO_APP_EVENT_4, E-MBER_REJOIN_DUE_TO_APP_EVENT_3, EMBER_REJOIN_DUE_TO_APP_EVENT_2,EMBER_REJOIN_DUE_TO_APP_EVENT_1 }

• enum EmberDeviceUpdate {EMBER_STANDARD_SECURITY_SECURED_REJOIN, EMBER_STANDARD_SECURITY_-UNSECURED_JOIN, EMBER_DEVICE_LEFT, EMBER_STANDARD_SECURITY_UNSECU-RED_REJOIN,EMBER_HIGH_SECURITY_SECURED_REJOIN, EMBER_HIGH_SECURITY_UNSECURED-_JOIN, EMBER_HIGH_SECURITY_UNSECURED_REJOIN, EMBER_REJOIN_REASON_NO-

EmberZNet 4.7.2 API EM260 120-3020-000-4720

17

NE,EMBER_REJOIN_DUE_TO_NWK_KEY_UPDATE, EMBER_REJOIN_DUE_TO_LEAVE_ME-SSAGE, EMBER_REJOIN_DUE_TO_NO_PARENT, EMBER_REJOIN_DUE_TO_ZLL_TOUC-HLINK,EMBER_REJOIN_DUE_TO_APP_EVENT_5, EMBER_REJOIN_DUE_TO_APP_EVENT_4, E-MBER_REJOIN_DUE_TO_APP_EVENT_3, EMBER_REJOIN_DUE_TO_APP_EVENT_2,EMBER_REJOIN_DUE_TO_APP_EVENT_1 }

• enum EmberClusterListId { EMBER_INPUT_CLUSTER_LIST, EMBER_OUTPUT_CLUSTER_-LIST }

• enum EmberEventUnits {EMBER_EVENT_INACTIVE, EMBER_EVENT_MS_TIME, EMBER_EVENT_QS_TIME, EM-BER_EVENT_MINUTE_TIME,EMBER_EVENT_ZERO_DELAY }

• enum EmberJoinMethod { EMBER_USE_MAC_ASSOCIATION, EMBER_USE_NWK_REJOIN,EMBER_USE_NWK_REJOIN_HAVE_NWK_KEY, EMBER_USE_NWK_COMMISSIONING }

• enum EmberCounterType {EMBER_COUNTER_MAC_RX_BROADCAST, EMBER_COUNTER_MAC_TX_BROADCAS-T, EMBER_COUNTER_MAC_RX_UNICAST, EMBER_COUNTER_MAC_TX_UNICAST_SU-CCESS,EMBER_COUNTER_MAC_TX_UNICAST_RETRY, EMBER_COUNTER_MAC_TX_UNICAS-T_FAILED, EMBER_COUNTER_APS_DATA_RX_BROADCAST, EMBER_COUNTER_APS-_DATA_TX_BROADCAST,EMBER_COUNTER_APS_DATA_RX_UNICAST, EMBER_COUNTER_APS_DATA_TX_UN-ICAST_SUCCESS, EMBER_COUNTER_APS_DATA_TX_UNICAST_RETRY, EMBER_COU-NTER_APS_DATA_TX_UNICAST_FAILED,EMBER_COUNTER_ROUTE_DISCOVERY_INITIATED, EMBER_COUNTER_NEIGHBOR_-ADDED, EMBER_COUNTER_NEIGHBOR_REMOVED, EMBER_COUNTER_NEIGHBOR_S-TALE,EMBER_COUNTER_JOIN_INDICATION, EMBER_COUNTER_CHILD_REMOVED, EMBER-_COUNTER_ASH_OVERFLOW_ERROR, EMBER_COUNTER_ASH_FRAMING_ERROR,EMBER_COUNTER_ASH_OVERRUN_ERROR, EMBER_COUNTER_NWK_FRAME_COUN-TER_FAILURE, EMBER_COUNTER_APS_FRAME_COUNTER_FAILURE, EMBER_COUN-TER_ASH_XOFF,EMBER_COUNTER_APS_LINK_KEY_NOT_AUTHORIZED, EMBER_COUNTER_NWK_DE-CRYPTION_FAILURE, EMBER_COUNTER_APS_DECRYPTION_FAILURE, EMBER_COU-NTER_ALLOCATE_PACKET_BUFFER_FAILURE,EMBER_COUNTER_RELAYED_UNICAST, EMBER_COUNTER_PHY_TO_MAC_QUEUE_L-IMIT_REACHED, EMBER_COUNTER_PACKET_VALIDATE_LIBRARY_DROPPED_COUN-T, EMBER_COUNTER_TYPE_COUNT }

• enum EmberInitialSecurityBitmask {EMBER_DISTRIBUTED_TRUST_CENTER_MODE, EMBER_TRUST_CENTER_GLOBAL_L-INK_KEY, EMBER_PRECONFIGURED_NETWORK_KEY_MODE, EMBER_HAVE_TRUST-_CENTER_EUI64,EMBER_TRUST_CENTER_USES_HASHED_LINK_KEY, EMBER_HAVE_PRECONFIGURE-D_KEY, EMBER_HAVE_NETWORK_KEY, EMBER_GET_LINK_KEY_WHEN_JOINING,EMBER_REQUIRE_ENCRYPTED_KEY, EMBER_NO_FRAME_COUNTER_RESET, EMBER-_GET_PRECONFIGURED_KEY_FROM_INSTALL_CODE }

• enum EmberExtendedSecurityBitmask { EMBER_JOINER_GLOBAL_LINK_KEY, EMBER_N-WK_LEAVE_REQUEST_NOT_ALLOWED }

• enum EmberCurrentSecurityBitmask {EMBER_STANDARD_SECURITY_MODE_, EMBER_DISTRIBUTED_TRUST_CENTER_MO-DE_, EMBER_TRUST_CENTER_GLOBAL_LINK_KEY_, EMBER_HAVE_TRUST_CENTER-_LINK_KEY,EMBER_TRUST_CENTER_USES_HASHED_LINK_KEY_ }

EmberZNet 4.7.2 API EM260 120-3020-000-4720

18

• enum EmberKeyStructBitmask {EMBER_KEY_HAS_SEQUENCE_NUMBER, EMBER_KEY_HAS_OUTGOING_FRAME_CO-UNTER, EMBER_KEY_HAS_INCOMING_FRAME_COUNTER, EMBER_KEY_HAS_PARTN-ER_EUI64,EMBER_KEY_IS_AUTHORIZED, EMBER_KEY_PARTNER_IS_SLEEPY }

• enum EmberKeyType {EMBER_TRUST_CENTER_LINK_KEY, EMBER_TRUST_CENTER_MASTER_KEY, EMBE-R_CURRENT_NETWORK_KEY, EMBER_NEXT_NETWORK_KEY,EMBER_APPLICATION_LINK_KEY, EMBER_APPLICATION_MASTER_KEY }

• enum EmberKeyStatus {EMBER_APP_LINK_KEY_ESTABLISHED, EMBER_APP_MASTER_KEY_ESTABLISHED, E-MBER_TRUST_CENTER_LINK_KEY_ESTABLISHED, EMBER_KEY_ESTABLISHMENT_T-IMEOUT,EMBER_KEY_TABLE_FULL, EMBER_TC_RESPONDED_TO_KEY_REQUEST, EMBER_T-C_APP_KEY_SENT_TO_REQUESTER, EMBER_TC_RESPONSE_TO_KEY_REQUEST_FAIL-ED,EMBER_TC_REQUEST_KEY_TYPE_NOT_SUPPORTED, EMBER_TC_NO_LINK_KEY_FO-R_REQUESTER, EMBER_TC_REQUESTER_EUI64_UNKNOWN, EMBER_TC_RECEIVED_-FIRST_APP_KEY_REQUEST,EMBER_TC_TIMEOUT_WAITING_FOR_SECOND_APP_KEY_REQUEST, EMBER_TC_NO-N_MATCHING_APP_KEY_REQUEST_RECEIVED, EMBER_TC_FAILED_TO_SEND_APP_-KEYS, EMBER_TC_FAILED_TO_STORE_APP_KEY_REQUEST,EMBER_TC_REJECTED_APP_KEY_REQUEST }

• enum EmberLinkKeyRequestPolicy { EMBER_DENY_KEY_REQUESTS, EMBER_ALLOW_K-EY_REQUESTS }

• enum EmberKeySettings { EMBER_KEY_PERMISSIONS_NONE, EMBER_KEY_PERMISSIO-NS_READING_ALLOWED, EMBER_KEY_PERMISSIONS_HASHING_ALLOWED }

• enum EmberMacPassthroughType {EMBER_MAC_PASSTHROUGH_NONE, EMBER_MAC_PASSTHROUGH_SE_INTERPAN, E-MBER_MAC_PASSTHROUGH_EMBERNET, EMBER_MAC_PASSTHROUGH_EMBERNET-_SOURCE,EMBER_MAC_PASSTHROUGH_APPLICATION, EMBER_MAC_PASSTHROUGH_CUSTOM}

Functions

• int8u ∗ emberKeyContents (EmberKeyData ∗key)• int8u ∗ emberCertificateContents (EmberCertificateData ∗cert)• int8u ∗ emberPublicKeyContents (EmberPublicKeyData ∗key)• int8u ∗ emberPrivateKeyContents (EmberPrivateKeyData ∗key)• int8u ∗ emberSmacContents (EmberSmacData ∗key)• int8u ∗ emberSignatureContents (EmberSignatureData ∗sig)

Miscellaneous Ember Types

• enum EmberVersionType { EMBER_VERSION_TYPE_PRE_RELEASE, EMBER_VERSION_T-YPE_GA }

• enum EmberLeaveRequestFlags { EMBER_ZIGBEE_LEAVE_AND_REJOIN, EMBER_ZIGBE-E_LEAVE_AND_REMOVE_CHILDREN }

EmberZNet 4.7.2 API EM260 120-3020-000-4720

19

• enum EmberLeaveReason {EMBER_LEAVE_REASON_NONE, EMBER_LEAVE_DUE_TO_NWK_LEAVE_MESSAGE, E-MBER_LEAVE_DUE_TO_APS_REMOVE_MESSAGE, EMBER_LEAVE_DUE_TO_ZDO_LE-AVE_MESSAGE,EMBER_LEAVE_DUE_TO_ZLL_TOUCHLINK, EMBER_LEAVE_DUE_TO_APP_EVENT_1 }

• typedef int8u EmberStatus• typedef int8u EmberEUI64 [EUI64_SIZE]• typedef int8u EmberMessageBuffer• typedef int16u EmberNodeId• typedef int16u EmberMulticastId• typedef int16u EmberPanId• const EmberVersion emberVersion• #define EUI64_SIZE• #define EXTENDED_PAN_ID_SIZE• #define EMBER_ENCRYPTION_KEY_SIZE• #define EMBER_CERTIFICATE_SIZE• #define EMBER_PUBLIC_KEY_SIZE• #define EMBER_PRIVATE_KEY_SIZE• #define EMBER_SMAC_SIZE• #define EMBER_SIGNATURE_SIZE• #define EMBER_AES_HASH_BLOCK_SIZE• #define __EMBERSTATUS_TYPE__• #define EMBER_MAX_802_15_4_CHANNEL_NUMBER• #define EMBER_MIN_802_15_4_CHANNEL_NUMBER• #define EMBER_NUM_802_15_4_CHANNELS• #define EMBER_ALL_802_15_4_CHANNELS_MASK• #define EMBER_ZIGBEE_COORDINATOR_ADDRESS• #define EMBER_NULL_NODE_ID• #define EMBER_NULL_BINDING• #define EMBER_TABLE_ENTRY_UNUSED_NODE_ID• #define EMBER_MULTICAST_NODE_ID• #define EMBER_UNKNOWN_NODE_ID• #define EMBER_DISCOVERY_ACTIVE_NODE_ID• #define EMBER_NULL_ADDRESS_TABLE_INDEX• #define EMBER_ZDO_ENDPOINT• #define EMBER_BROADCAST_ENDPOINT• #define EMBER_ZDO_PROFILE_ID• #define EMBER_WILDCARD_PROFILE_ID• #define EMBER_MAXIMUM_STANDARD_PROFILE_ID• #define EMBER_BROADCAST_TABLE_TIMEOUT_QS

ZigBee Broadcast Addresses

ZigBee specifies three different broadcast addresses that reach different collections of nodes. Broadcastsare normally sent only to routers. Broadcasts can also be forwarded to end devices, either all of them oronly those that do not sleep. Broadcasting to end devices is both significantly more resource-intensive andsignificantly less reliable than broadcasting to routers.

• #define EMBER_BROADCAST_ADDRESS• #define EMBER_RX_ON_WHEN_IDLE_BROADCAST_ADDRESS• #define EMBER_SLEEPY_BROADCAST_ADDRESS

EmberZNet 4.7.2 API EM260 120-3020-000-4720

20

Ember Concentrator Types

• #define EMBER_LOW_RAM_CONCENTRATOR• #define EMBER_HIGH_RAM_CONCENTRATOR

txPowerModes for emberSetTxPowerMode and mfglibSetPower

• #define EMBER_TX_POWER_MODE_DEFAULT• #define EMBER_TX_POWER_MODE_BOOST• #define EMBER_TX_POWER_MODE_ALTERNATE• #define EMBER_TX_POWER_MODE_BOOST_AND_ALTERNATE

Alarm Message and Counters Request Definitions

• #define EMBER_PRIVATE_PROFILE_ID• #define EMBER_BROADCAST_ALARM_CLUSTER• #define EMBER_UNICAST_ALARM_CLUSTER• #define EMBER_CACHED_UNICAST_ALARM_CLUSTER• #define EMBER_REPORT_COUNTERS_REQUEST• #define EMBER_REPORT_COUNTERS_RESPONSE• #define EMBER_REPORT_AND_CLEAR_COUNTERS_REQUEST• #define EMBER_REPORT_AND_CLEAR_COUNTERS_RESPONSE• #define EMBER_OTA_CERTIFICATE_UPGRADE_CLUSTER

ZDO response status.

Most responses to ZDO commands contain a status byte. The meaning of this byte is defined by the ZigBeeDevice Profile.

• enum EmberZdoStatus {EMBER_ZDP_SUCCESS, EMBER_ZDP_INVALID_REQUEST_TYPE, EMBER_ZDP_DEVIC-E_NOT_FOUND, EMBER_ZDP_INVALID_ENDPOINT,EMBER_ZDP_NOT_ACTIVE, EMBER_ZDP_NOT_SUPPORTED, EMBER_ZDP_TIMEOUT, E-MBER_ZDP_NO_MATCH,EMBER_ZDP_NO_ENTRY, EMBER_ZDP_NO_DESCRIPTOR, EMBER_ZDP_INSUFFICIEN-T_SPACE, EMBER_ZDP_NOT_PERMITTED,EMBER_ZDP_TABLE_FULL, EMBER_ZDP_NOT_AUTHORIZED, EMBER_NWK_ALREAD-Y_PRESENT, EMBER_NWK_TABLE_FULL,EMBER_NWK_UNKNOWN_DEVICE }

Network and IEEE Address Request/Response

Defines for ZigBee device profile cluster IDs follow. These include descriptions of the formats of themessages.

Note that each message starts with a 1-byte transaction sequence number. This sequence number is used tomatch a response command frame to the request frame that it is replying to. The application shall maintaina 1-byte counter that is copied into this field and incremented by one for each command sent. When a valueof 0xff is reached, the next command shall re-start the counter with a value of 0x00

EmberZNet 4.7.2 API EM260 120-3020-000-4720

21

Network request: <transaction sequence number: 1><EUI64:8> <type:1> <start index:1>

IEEE request: <transaction sequence number: 1><node ID:2> <type:1> <start index:1><type> = 0x00 single address response, ignore the start index= 0x01 extended response -> sends kid’s IDs as well

Response: <transaction sequence number: 1><status:1> <EUI64:8> <node ID:2><ID count:1> <start index:1> <child ID:2>*

• #define NETWORK_ADDRESS_REQUEST• #define NETWORK_ADDRESS_RESPONSE• #define IEEE_ADDRESS_REQUEST• #define IEEE_ADDRESS_RESPONSE

Node Descriptor Request/Response

<br>

@codeRequest: <transaction sequence number: 1> <node ID:2>Response: <transaction sequence number: 1> <status:1> <node ID:2>

// <node descriptor: 13> // // Node Descriptor field is divided into subfields of bitmasks as follows: //(Note: All lengths below are given in bits rather than bytes.) // Logical Type: 3 // Complex DescriptorAvailable: 1 // User Descriptor Available: 1 // (reserved/unused): 3 // APS Flags: 3 // Frequency Band:5 // MAC capability flags: 8 // Manufacturer Code: 16 // Maximum buffer size: 8 // Maximum incomingtransfer size: 16 // Server mask: 16 // Maximum outgoing transfer size: 16 // Descriptor Capability Flags:8 // See ZigBee document 053474, Section 2.3.2.3 for more details.

• #define NODE_DESCRIPTOR_REQUEST• #define NODE_DESCRIPTOR_RESPONSE

Power Descriptor Request / Response

<br>


<current power mode, available power sources:1><current power source, current power source level:1>

// See ZigBee document 053474, Section 2.3.2.4 for more details.

• #define POWER_DESCRIPTOR_REQUEST• #define POWER_DESCRIPTOR_RESPONSE

Simple Descriptor Request / Response

Request: <transaction sequence number: 1><node ID:2> <endpoint:1>

Response: <transaction sequence number: 1><status:1> <node ID:2> <length:1> <endpoint:1><app profile ID:2> <app device ID:2><app device version, app flags:1><input cluster count:1> <input cluster:2>*<output cluster count:1> <output cluster:2>*

EmberZNet 4.7.2 API EM260 120-3020-000-4720

22

• #define SIMPLE_DESCRIPTOR_REQUEST• #define SIMPLE_DESCRIPTOR_RESPONSE

Active Endpoints Request / Response

Request: <transaction sequence number: 1> <node ID:2>Response: <transaction sequence number: 1>

<status:1> <node ID:2> <endpoint count:1> <endpoint:1>*

• #define ACTIVE_ENDPOINTS_REQUEST• #define ACTIVE_ENDPOINTS_RESPONSE

Match Descriptors Request / Response

Request: <transaction sequence number: 1><node ID:2> <app profile ID:2><input cluster count:1> <input cluster:2>*<output cluster count:1> <output cluster:2>*

Response: <transaction sequence number: 1><status:1> <node ID:2> <endpoint count:1> <endpoint:1>*

• #define MATCH_DESCRIPTORS_REQUEST• #define MATCH_DESCRIPTORS_RESPONSE

Discovery Cache Request / Response

Request: <transaction sequence number: 1><source node ID:2> <source EUI64:8>

Response: <transaction sequence number: 1><status (== EMBER_ZDP_SUCCESS):1>

• #define DISCOVERY_CACHE_REQUEST• #define DISCOVERY_CACHE_RESPONSE

End Device Announce and End Device Announce Response

Request: <transaction sequence number: 1><node ID:2> <EUI64:8> <capabilities:1>

No response is sent.

• #define END_DEVICE_ANNOUNCE• #define END_DEVICE_ANNOUNCE_RESPONSE

System Server Discovery Request / Response

This is broadcast and only servers which have matching services respond. The response contains the requestservices that the recipient provides.

Request: <transaction sequence number: 1> <server mask:2>Response: <transaction sequence number: 1>

<status (== EMBER_ZDP_SUCCESS):1> <server mask:2>

• #define SYSTEM_SERVER_DISCOVERY_REQUEST• #define SYSTEM_SERVER_DISCOVERY_RESPONSE

EmberZNet 4.7.2 API EM260 120-3020-000-4720

23

ZDO server mask bits

These are used in server discovery requests and responses.

• enum EmberZdoServerMask {EMBER_ZDP_PRIMARY_TRUST_CENTER, EMBER_ZDP_SECONDARY_TRUST_CENTER,EMBER_ZDP_PRIMARY_BINDING_TABLE_CACHE, EMBER_ZDP_SECONDARY_BINDI-NG_TABLE_CACHE,EMBER_ZDP_PRIMARY_DISCOVERY_CACHE, EMBER_ZDP_SECONDARY_DISCOVER-Y_CACHE, EMBER_ZDP_NETWORK_MANAGER }

Find Node Cache Request / Response

This is broadcast and only discovery servers which have the information for the device of interest, or thedevice of interest itself, respond. The requesting device can then direct any service discovery requests tothe responder.

Request: <transaction sequence number: 1><device of interest ID:2> <d-of-i EUI64:8>

Response: <transaction sequence number: 1><responder ID:2> <device of interest ID:2> <d-of-i EUI64:8>

• #define FIND_NODE_CACHE_REQUEST• #define FIND_NODE_CACHE_RESPONSE

End Device Bind Request / Response

Request: <transaction sequence number: 1><node ID:2> <EUI64:8> <endpoint:1> <app profile ID:2><input cluster count:1> <input cluster:2>*<output cluster count:1> <output cluster:2>*

Response: <transaction sequence number: 1> <status:1>

• #define END_DEVICE_BIND_REQUEST• #define END_DEVICE_BIND_RESPONSE

Binding types and Request / Response

Bind and unbind have the same formats. There are two possible formats, depending on whether the desti-nation is a group address or a device address. Device addresses include an endpoint, groups don’t.

Request: <transaction sequence number: 1><source EUI64:8> <source endpoint:1><cluster ID:2> <destination address:3 or 10>

Destination address:<0x01:1> <destination group:2>

Or:<0x03:1> <destination EUI64:8> <destination endpoint:1>


• #define UNICAST_BINDING• #define UNICAST_MANY_TO_ONE_BINDING• #define MULTICAST_BINDING• #define BIND_REQUEST• #define BIND_RESPONSE• #define UNBIND_REQUEST• #define UNBIND_RESPONSE

EmberZNet 4.7.2 API EM260 120-3020-000-4720

24

LQI Table Request / Response

Request: <transaction sequence number: 1> <start index:1>Response: <transaction sequence number: 1> <status:1>

<neighbor table entries:1> <start index:1><entry count:1> <entry:22>*

<entry> = <extended PAN ID:8> <EUI64:8> <node ID:2><device type, rx on when idle, relationship:1><permit joining:1> <depth:1> <LQI:1>

The device-type byte has the following fields:

Name Mask Values

device type 0x03 0x00 coordinator0x01 router0x02 end device0x03 unknown

rx mode 0x0C 0x00 off when idle0x04 on when idle0x08 unknown

relationship 0x70 0x00 parent0x10 child0x20 sibling0x30 other0x40 previous child

reserved 0x10

The permit-joining byte has the following fields

Name Mask Values

permit joining 0x03 0x00 not accepting join requests0x01 accepting join requests0x02 unknown

reserved 0xFC

• #define LQI_TABLE_REQUEST• #define LQI_TABLE_RESPONSE

Routing Table Request / Response


<routing table entries:1> <start index:1><entry count:1> <entry:5>*

<entry> = <destination address:2><status:1><next hop:2>

The status byte has the following fields:

Name Mask Values

status 0x07 0x00 active0x01 discovery underway0x02 discovery failed0x03 inactive0x04 validation underway

flags 0x380x08 memory constrained0x10 many-to-one0x20 route record required

reserved 0xC0

EmberZNet 4.7.2 API EM260 120-3020-000-4720

25

• #define ROUTING_TABLE_REQUEST• #define ROUTING_TABLE_RESPONSE

Binding Table Request / Response

Request: <transaction sequence number: 1> <start index:1>Response: <transaction sequence number: 1>

<status:1> <binding table entries:1> <start index:1><entry count:1> <entry:14/21>*

<entry> = <source EUI64:8> <source endpoint:1> <cluster ID:2><dest addr mode:1> <dest:2/8> <dest endpoint:0/1>

Note

If Dest. Address Mode = 0x03, then the Long Dest. Address will be used and Dest. endpoint will beincluded. If Dest. Address Mode = 0x01, then the Short Dest. Address will be used and there will beno Dest. endpoint.

• #define BINDING_TABLE_REQUEST• #define BINDING_TABLE_RESPONSE

Leave Request / Response

Request: <transaction sequence number: 1> <EUI64:8> <flags:1>The flag bits are:0x40 remove children0x80 rejoin


• #define LEAVE_REQUEST• #define LEAVE_RESPONSE• #define LEAVE_REQUEST_REMOVE_CHILDREN_FLAG• #define LEAVE_REQUEST_REJOIN_FLAG

Permit Joining Request / Response

Request: <transaction sequence number: 1><duration:1> <permit authentication:1>


• #define PERMIT_JOINING_REQUEST• #define PERMIT_JOINING_RESPONSE

Network Update Request / Response

Request: <transaction sequence number: 1><scan channels:4> <duration:1> <count:0/1> <manager:0/2>

If the duration is in 0x00 ... 0x05, then ’count’ is present butnot ’manager’. Perform ’count’ scans of the given duration on thegiven channels.

If duration is 0xFE, then ’channels’ should have a single channeland ’count’ and ’manager’ are not present. Switch to the indicatedchannel.

If duration is 0xFF, then ’count’ is not present. Set the activechannels and the network manager ID to the values given.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

26

Unicast requests always get a response, which is INVALID_REQUEST if theduration is not a legal value.

Response: <transaction sequence number: 1> <status:1><scanned channels:4> <transmissions:2> <failures:2><energy count:1> <energy:1>*

• #define NWK_UPDATE_REQUEST• #define NWK_UPDATE_RESPONSE

Unsupported

Not mandatory and not supported.

• #define COMPLEX_DESCRIPTOR_REQUEST• #define COMPLEX_DESCRIPTOR_RESPONSE• #define USER_DESCRIPTOR_REQUEST• #define USER_DESCRIPTOR_RESPONSE• #define DISCOVERY_REGISTER_REQUEST• #define DISCOVERY_REGISTER_RESPONSE• #define USER_DESCRIPTOR_SET• #define USER_DESCRIPTOR_CONFIRM• #define NETWORK_DISCOVERY_REQUEST• #define NETWORK_DISCOVERY_RESPONSE• #define DIRECT_JOIN_REQUEST• #define DIRECT_JOIN_RESPONSE• #define CLUSTER_ID_RESPONSE_MINIMUM

ZDO configuration flags.

For controlling which ZDO requests are passed to the application. These are normally controlled via thefollowing configuration definitions:

EMBER_APPLICATION_RECEIVES_SUPPORTED_ZDO_REQUESTS EMBER_APPLICATION_H-ANDLES_UNSUPPORTED_ZDO_REQUESTS EMBER_APPLICATION_HANDLES_ENDPOINT_Z-DO_REQUESTS EMBER_APPLICATION_HANDLES_BINDING_ZDO_REQUESTS

See ember-configuration.h for more information.

• enum EmberZdoConfigurationFlags { EMBER_APP_RECEIVES_SUPPORTED_ZDO_REQUES-TS, EMBER_APP_HANDLES_UNSUPPORTED_ZDO_REQUESTS, EMBER_APP_HANDLE-S_ZDO_ENDPOINT_REQUESTS, EMBER_APP_HANDLES_ZDO_BINDING_REQUESTS }


See ember-types.h for source code.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

27

6.2.2 Macro Definition Documentation

6.2.2.1 #define EUI64 SIZE

Size of EUI64 (an IEEE address) in bytes (8).

Definition at line 72 of file ember-types.h.

6.2.2.2 #define EXTENDED PAN ID SIZE

Size of an extended PAN identifier in bytes (8).


6.2.2.3 #define EMBER ENCRYPTION KEY SIZE

Size of an encryption key in bytes (16).


6.2.2.4 #define EMBER CERTIFICATE SIZE

Size of Implicit Certificates used for Certificate Based Key Exchange.


6.2.2.5 #define EMBER PUBLIC KEY SIZE

Size of Public Keys used in Elliptical Cryptography ECMQV algorithms.


6.2.2.6 #define EMBER PRIVATE KEY SIZE

Size of Private Keys used in Elliptical Cryptography ECMQV algorithms.


6.2.2.7 #define EMBER SMAC SIZE

Size of the SMAC used in Elliptical Cryptography ECMQV algorithms.


6.2.2.8 #define EMBER SIGNATURE SIZE

Size of the DSA signature used in Elliptical Cryptography Digital Signature Algorithms.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

28

6.2.2.9 #define EMBER AES HASH BLOCK SIZE

The size of AES-128 MMO hash is 16-bytes. This is defined in the core. ZigBee specification.


6.2.2.10 #define EMBERSTATUS TYPE

Return type for Ember functions.


6.2.2.11 #define EMBER MAX 802 15 4 CHANNEL NUMBER

The maximum 802.15.4 channel number is 26.


6.2.2.12 #define EMBER MIN 802 15 4 CHANNEL NUMBER

The minimum 802.15.4 channel number is 11.


6.2.2.13 #define EMBER NUM 802 15 4 CHANNELS

There are sixteen 802.15.4 channels.


6.2.2.14 #define EMBER ALL 802 15 4 CHANNELS MASK

Bitmask to scan all 802.15.4 channels.


6.2.2.15 #define EMBER ZIGBEE COORDINATOR ADDRESS

The network ID of the coordinator in a ZigBee network is 0x0000.


6.2.2.16 #define EMBER NULL NODE ID

A distinguished network ID that will never be assigned to any node. Used to indicate the absence of a nodeID.


6.2.2.17 #define EMBER NULL BINDING

A distinguished binding index used to indicate the absence of a binding.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

29


6.2.2.18 #define EMBER TABLE ENTRY UNUSED NODE ID

A distinguished network ID that will never be assigned to any node.

This value is used when setting or getting the remote node ID in the address table or getting the remotenode ID from the binding table. It indicates that address or binding table entry is not in use.


6.2.2.19 #define EMBER MULTICAST NODE ID

A distinguished network ID that will never be assigned to any node. This value is returned when gettingthe remote node ID from the binding table and the given binding table index refers to a multicast bindingentry.


6.2.2.20 #define EMBER UNKNOWN NODE ID

A distinguished network ID that will never be assigned to any node. This value is used when getting theremote node ID from the address or binding tables. It indicates that the address or binding table entry iscurrently in use but the node ID corresponding to the EUI64 in the table is currently unknown.


6.2.2.21 #define EMBER DISCOVERY ACTIVE NODE ID

A distinguished network ID that will never be assigned to any node. This value is used when getting theremote node ID from the address or binding tables. It indicates that the address or binding table entry iscurrently in use and network address discovery is underway.


6.2.2.22 #define EMBER NULL ADDRESS TABLE INDEX

A distinguished address table index used to indicate the absence of an address table entry.


6.2.2.23 #define EMBER ZDO ENDPOINT

The endpoint where the ZigBee Device Object (ZDO) resides.


6.2.2.24 #define EMBER BROADCAST ENDPOINT

The broadcast endpoint, as defined in the ZigBee spec.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

30

6.2.2.25 #define EMBER ZDO PROFILE ID

The profile ID used by the ZigBee Device Object (ZDO).


6.2.2.26 #define EMBER WILDCARD PROFILE ID

The profile ID used to address all the public profiles.


6.2.2.27 #define EMBER MAXIMUM STANDARD PROFILE ID

The maximum value for a profile ID in the standard profile range.


6.2.2.28 #define EMBER BROADCAST TABLE TIMEOUT QS

The broadcast table timeout. How long a broadcast entry persists in the local device’s broadcast table. Thisis the maximum length it will persist, in quarter seconds.


6.2.2.29 #define EMBER BROADCAST ADDRESS

Broadcast to all routers.


6.2.2.30 #define EMBER RX ON WHEN IDLE BROADCAST ADDRESS

Broadcast to all non-sleepy devices.


6.2.2.31 #define EMBER SLEEPY BROADCAST ADDRESS

Broadcast to all devices, including sleepy end devices.


6.2.2.32 #define EMBER LOW RAM CONCENTRATOR

A concentrator with insufficient memory to store source routes for the entire network. Route records aresent to the concentrator prior to every inbound APS unicast.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

31

6.2.2.33 #define EMBER HIGH RAM CONCENTRATOR

A concentrator with sufficient memory to store source routes for the entire network. Remote nodes stopsending route records once the concentrator has successfully received one.


6.2.2.34 #define EMBER JOIN DECISION STRINGS

@ brief Defines the CLI enumerations for the EmberJoinDecision enum


6.2.2.35 #define EMBER DEVICE UPDATE STRINGS

@ brief Defines the CLI enumerations for the EmberDeviceUpdate enum.


6.2.2.36 #define emberInitializeNetworkParameters( parameters )


6.2.2.37 #define EMBER COUNTER STRINGS

@ brief Defines the CLI enumerations for the EmberCounterType enum.


6.2.2.38 #define EMBER TX POWER MODE DEFAULT

The application should call ::emberSetTxPowerMode() with the txPowerMode parameter set to this valueto disable all power mode options, resulting in normal power mode and bi-directional RF transmitter output.


6.2.2.39 #define EMBER TX POWER MODE BOOST

The application should call ::emberSetTxPowerMode() with the txPowerMode parameter set to this valueto enable boost power mode.


6.2.2.40 #define EMBER TX POWER MODE ALTERNATE

The application should call ::emberSetTxPowerMode() with the txPowerMode parameter set to this valueto enable the alternate transmitter output.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

32

6.2.2.41 #define EMBER TX POWER MODE BOOST AND ALTERNATE

The application should call ::emberSetTxPowerMode() with the txPowerMode parameter set to this valueto enable both boost mode and the alternate transmitter output.


6.2.2.42 #define EMBER PRIVATE PROFILE ID

This is a ZigBee application profile ID that has been assigned to Ember Corporation.

It is used to send for sending messages that have a specific, non-standard interaction with the Ember stack.Its only current use is for alarm messages and stack counters requests.


6.2.2.43 #define EMBER BROADCAST ALARM CLUSTER

Alarm messages provide a reliable means for communicating with sleeping end devices.

A messages sent to a sleeping device is normally buffered on the device’s parent for a short time (the precisetime can be specified using the configuration parameter EMBER_INDIRECT_TRANSMISSION_TIME-OUT). If the child does not poll its parent within that time the message is discarded.

In contrast, alarm messages are buffered by the parent indefinitely. Because of the limited RAM available,alarm messages are necessarily brief. In particular, the parent only stores alarm payloads. The headerinformation in alarm messages is not stored on the parent.

The memory used for buffering alarm messages is allocated statically. The amount of memory set aside foralarms is controlled by two configuration parameters:

• EMBER_BROADCAST_ALARM_DATA_SIZE

• EMBER_UNICAST_ALARM_DATA_SIZE

Alarm messages must use the EMBER_PRIVATE_PROFILE_ID as the application profile ID. The sourceand destination endpoints are ignored.

Broadcast alarms must use EMBER_BROADCAST_ALARM_CLUSTER as the cluster id and messageswith this cluster ID must be sent to EMBER_RX_ON_WHEN_IDLE_BROADCAST_ADDRESS. A broad-cast alarm may not contain more than EMBER_BROADCAST_ALARM_DATA_SIZE bytes of payload.

Broadcast alarm messages arriving at a node are passed to the application via ::emberIncomingMessage-Handler(). If the receiving node has sleepy end device children, the payload of the alarm is saved and thenforwarded to those children when they poll for data. When a sleepy child polls its parent, it receives onlythe most recently arrived broadcast alarm. If the child has already received the most recent broadcast alarmit is not forwarded again.


6.2.2.44 #define EMBER UNICAST ALARM CLUSTER

Unicast alarms must use EMBER_UNICAST_ALARM_CLUSTER as the cluster id and messages withthis cluster ID must be unicast.

The payload of a unicast alarm consists of three one-byte length fields followed by three variable lengthfields.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

33

1. flags length

2. priority length (must be 0 or 1)

3. data length

4. flags

5. priority

6. payload

The three lengths must total EMBER_UNICAST_ALARM_DATA_SIZE or less.

When a unicast alarm message arrives at its destination it is passed to the application via ::emberIncoming-MessageHandler(). When a node receives a unicast alarm message whose destination is a sleepy enddevice child of that node, the payload of the message is saved until the child polls for data. To conservememory, the values of the length fields are not saved. The alarm will be forwarded to the child using theEMBER_CACHED_UNICAST_ALARM_CLUSTER cluster ID.

If a unicast alarm arrives when a previous one is still pending, the two payloads are combined. Thiscombining is controlled by the length fields in the arriving message. The incoming flag bytes are or’ed withthose of the pending message. If the priority field is not present, or if it is present and the incoming priorityvalue is equal or greater than the pending priority value, the pending data is replaced by the incoming data.

Because the length fields are not saved, the application designer must fix on a set of field lengths that willbe used for all unicast alarm message sent to a particular device.


6.2.2.45 #define EMBER CACHED UNICAST ALARM CLUSTER

A unicast alarm that has been cached on the parent of a sleepy end device is delivered to that deviceusing the EMBER_CACHED_UNICAST_ALARM_CLUSTER cluster ID. The payload consists of threevariable length fields.

1. flags

2. priority

3. payload

The parent will pad the payload out to EMBER_UNICAST_ALARM_DATA_SIZE bytes.

The lengths of the these fields must be fixed by the application designer and must be the same for all unicastalarms sent to a particular device.


6.2.2.46 #define EMBER REPORT COUNTERS REQUEST

The cluster id used to request that a node respond with a report of its Ember stack counters. See app/util/counters/counters-ota.h.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

34

6.2.2.47 #define EMBER REPORT COUNTERS RESPONSE

The cluster id used to respond to an EMBER_REPORT_COUNTERS_REQUEST.


6.2.2.48 #define EMBER REPORT AND CLEAR COUNTERS REQUEST

The cluster id used to request that a node respond with a report of its Ember stack counters. The node willalso reset its clusters to zero after a successful response. See app/util/counters/counters-ota.h.


6.2.2.49 #define EMBER REPORT AND CLEAR COUNTERS RESPONSE

The cluster id used to respond to an EMBER_REPORT_AND_CLEAR_COUNTERS_REQUEST.


6.2.2.50 #define EMBER OTA CERTIFICATE UPGRADE CLUSTER

The cluster id used to send and receive Over-the-air certificate messages. This is used to field upgradedevices with Smart Energy Certificates and other security data.


6.2.2.51 #define EMBER STANDARD SECURITY MODE

This is an EmberInitialSecurityBitmask value but it does not actually set anything. It is the default modeused by the ZigBee Pro stack. It is defined here so that no legacy code is broken by referencing it.


6.2.2.52 #define EMBER TRUST CENTER NODE ID

This is the short address of the trust center. It never changes from this value throughout the life of thenetwork.


6.2.2.53 #define EMBER NO TRUST CENTER MODE

This is the legacy name for the Distributed Trust Center Mode.


6.2.2.54 #define EMBER GLOBAL LINK KEY

This is the legacy name for the Trust Center Global Link Key.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

35

6.2.2.55 #define EMBER MFG SECURITY CONFIG MAGIC NUMBER

This magic number prevents accidentally changing the key settings. The ::emberSetMfgSecurityConfig()API will return EMBER_INVALID_CALL unless it is passed in.


6.2.2.56 #define EMBER MAC FILTER MATCH ENABLED MASK


6.2.2.57 #define EMBER MAC FILTER MATCH ON PAN DEST MASK


6.2.2.58 #define EMBER MAC FILTER MATCH ON PAN SOURCE MASK


6.2.2.59 #define EMBER MAC FILTER MATCH ON DEST MASK


6.2.2.60 #define EMBER MAC FILTER MATCH ON SOURCE MASK


6.2.2.61 #define EMBER MAC FILTER MATCH ENABLED


6.2.2.62 #define EMBER MAC FILTER MATCH DISABLED


6.2.2.63 #define EMBER MAC FILTER MATCH ON PAN DEST NONE


6.2.2.64 #define EMBER MAC FILTER MATCH ON PAN DEST LOCAL


6.2.2.65 #define EMBER MAC FILTER MATCH ON PAN DEST BROADCAST


EmberZNet 4.7.2 API EM260 120-3020-000-4720

36

6.2.2.66 #define EMBER MAC FILTER MATCH ON PAN SOURCE NONE


6.2.2.67 #define EMBER MAC FILTER MATCH ON PAN SOURCE NON LOCAL


6.2.2.68 #define EMBER MAC FILTER MATCH ON PAN SOURCE LOCAL


6.2.2.69 #define EMBER MAC FILTER MATCH ON DEST BROADCAST SHORT


6.2.2.70 #define EMBER MAC FILTER MATCH ON DEST UNICAST SHORT


6.2.2.71 #define EMBER MAC FILTER MATCH ON DEST UNICAST LONG


6.2.2.72 #define EMBER MAC FILTER MATCH ON SOURCE LONG


6.2.2.73 #define EMBER MAC FILTER MATCH ON SOURCE SHORT


6.2.2.74 #define EMBER MAC FILTER MATCH END


6.2.2.75 #define NETWORK ADDRESS REQUEST


6.2.2.76 #define NETWORK ADDRESS RESPONSE


EmberZNet 4.7.2 API EM260 120-3020-000-4720

37

6.2.2.77 #define IEEE ADDRESS REQUEST


6.2.2.78 #define IEEE ADDRESS RESPONSE


6.2.2.79 #define NODE DESCRIPTOR REQUEST


6.2.2.80 #define NODE DESCRIPTOR RESPONSE


6.2.2.81 #define POWER DESCRIPTOR REQUEST


6.2.2.82 #define POWER DESCRIPTOR RESPONSE


6.2.2.83 #define SIMPLE DESCRIPTOR REQUEST


6.2.2.84 #define SIMPLE DESCRIPTOR RESPONSE


6.2.2.85 #define ACTIVE ENDPOINTS REQUEST


6.2.2.86 #define ACTIVE ENDPOINTS RESPONSE


6.2.2.87 #define MATCH DESCRIPTORS REQUEST


EmberZNet 4.7.2 API EM260 120-3020-000-4720

38

6.2.2.88 #define MATCH DESCRIPTORS RESPONSE


6.2.2.89 #define DISCOVERY CACHE REQUEST


6.2.2.90 #define DISCOVERY CACHE RESPONSE


6.2.2.91 #define END DEVICE ANNOUNCE


6.2.2.92 #define END DEVICE ANNOUNCE RESPONSE


6.2.2.93 #define SYSTEM SERVER DISCOVERY REQUEST


6.2.2.94 #define SYSTEM SERVER DISCOVERY RESPONSE


6.2.2.95 #define FIND NODE CACHE REQUEST


6.2.2.96 #define FIND NODE CACHE RESPONSE


6.2.2.97 #define END DEVICE BIND REQUEST


6.2.2.98 #define END DEVICE BIND RESPONSE


EmberZNet 4.7.2 API EM260 120-3020-000-4720

39

6.2.2.99 #define UNICAST BINDING


6.2.2.100 #define UNICAST MANY TO ONE BINDING


6.2.2.101 #define MULTICAST BINDING


6.2.2.102 #define BIND REQUEST


6.2.2.103 #define BIND RESPONSE


6.2.2.104 #define UNBIND REQUEST


6.2.2.105 #define UNBIND RESPONSE


6.2.2.106 #define LQI TABLE REQUEST


6.2.2.107 #define LQI TABLE RESPONSE


6.2.2.108 #define ROUTING TABLE REQUEST


6.2.2.109 #define ROUTING TABLE RESPONSE


EmberZNet 4.7.2 API EM260 120-3020-000-4720

40

6.2.2.110 #define BINDING TABLE REQUEST


6.2.2.111 #define BINDING TABLE RESPONSE


6.2.2.112 #define LEAVE REQUEST


6.2.2.113 #define LEAVE RESPONSE


6.2.2.114 #define LEAVE REQUEST REMOVE CHILDREN FLAG


6.2.2.115 #define LEAVE REQUEST REJOIN FLAG


6.2.2.116 #define PERMIT JOINING REQUEST


6.2.2.117 #define PERMIT JOINING RESPONSE


6.2.2.118 #define NWK UPDATE REQUEST


6.2.2.119 #define NWK UPDATE RESPONSE


6.2.2.120 #define COMPLEX DESCRIPTOR REQUEST


EmberZNet 4.7.2 API EM260 120-3020-000-4720

41

6.2.2.121 #define COMPLEX DESCRIPTOR RESPONSE


6.2.2.122 #define USER DESCRIPTOR REQUEST


6.2.2.123 #define USER DESCRIPTOR RESPONSE


6.2.2.124 #define DISCOVERY REGISTER REQUEST


6.2.2.125 #define DISCOVERY REGISTER RESPONSE


6.2.2.126 #define USER DESCRIPTOR SET


6.2.2.127 #define USER DESCRIPTOR CONFIRM


6.2.2.128 #define NETWORK DISCOVERY REQUEST


6.2.2.129 #define NETWORK DISCOVERY RESPONSE


6.2.2.130 #define DIRECT JOIN REQUEST


6.2.2.131 #define DIRECT JOIN RESPONSE


EmberZNet 4.7.2 API EM260 120-3020-000-4720

42

6.2.2.132 #define CLUSTER ID RESPONSE MINIMUM


6.2.3 Typedef Documentation

6.2.3.1 typedef int8u EmberStatus



6.2.3.2 typedef int8u EmberEUI64[EUI64_SIZE]

EUI 64-bit ID (an IEEE address).


6.2.3.3 typedef int8u EmberMessageBuffer

Incoming and outgoing messages are stored in buffers. These buffers are allocated and freed as needed.

Buffers are 32 bytes in length and can be linked together to hold longer messages.

See packet-buffer.h for APIs related to stack and linked buffers.


6.2.3.4 typedef int16u EmberNodeId

16-bit ZigBee network address.


6.2.3.5 typedef int16u EmberMulticastId

16-bit ZigBee multicast group identifier.


6.2.3.6 typedef int16u EmberPanId

802.15.4 PAN ID.


6.2.3.7 typedef int8u EmberTaskId

brief An identifier for a task


EmberZNet 4.7.2 API EM260 120-3020-000-4720

43

6.2.3.8 typedef { ... } EmberEventData

6.2.3.9 typedef int16u EmberMacFilterMatchData

This is a bitmask describing a filter for MAC data messages that the stack should accept and passthroughto the application.


6.2.3.10 typedef int8u EmberLibraryStatus

This indicates the presence, absence, or status of an Ember stack library.


6.2.4 Enumeration Type Documentation

6.2.4.1 enum EmberVersionType

Type of Ember software version.

Enumerator:

EMBER_VERSION_TYPE_PRE_RELEASEEMBER_VERSION_TYPE_GA


6.2.4.2 enum EmberLeaveRequestFlags


Enumerator:

EMBER_ZIGBEE_LEAVE_AND_REJOIN Leave and rejoinEMBER_ZIGBEE_LEAVE_AND_REMOVE_CHILDREN Send all children leave command


6.2.4.3 enum EmberLeaveReason


Enumerator:

EMBER_LEAVE_REASON_NONEEMBER_LEAVE_DUE_TO_NWK_LEAVE_MESSAGEEMBER_LEAVE_DUE_TO_APS_REMOVE_MESSAGEEMBER_LEAVE_DUE_TO_ZDO_LEAVE_MESSAGEEMBER_LEAVE_DUE_TO_ZLL_TOUCHLINKEMBER_LEAVE_DUE_TO_APP_EVENT_1


EmberZNet 4.7.2 API EM260 120-3020-000-4720

44

6.2.4.4 enum EmberNodeType

Defines the possible types of nodes and the roles that a node might play in a network.

Enumerator:

EMBER_UNKNOWN_DEVICE Device is not joined

EMBER_COORDINATOR Will relay messages and can act as a parent to other nodes.

EMBER_ROUTER Will relay messages and can act as a parent to other nodes.

EMBER_END_DEVICE Communicates only with its parent and will not relay messages.

EMBER_SLEEPY_END_DEVICE An end device whose radio can be turned off to save power. Theapplication must call ::emberPollForData() to receive messages.

EMBER_MOBILE_END_DEVICE A sleepy end device that can move through the network.


6.2.4.5 enum EmberNetworkInitBitmask

Defines the options that should be used when initializing the node’s network configuration.

Enumerator:

EMBER_NETWORK_INIT_NO_OPTIONSEMBER_NETWORK_INIT_PARENT_INFO_IN_TOKEN The Parent Node ID and EUI64 are stored

in a token. This prevents the need to perform an Orphan scan on startup.


6.2.4.6 enum EmberApsOption

Options to use when sending a message.

The discover route, APS retry, and APS indirect options may be used together. Poll response cannot becombined with any other options.

Enumerator:

EMBER_APS_OPTION_NONE No options.

EMBER_APS_OPTION_DSA_SIGN This signs the application layer message body (APS Framenot included) and appends the ECDSA signature to the end of the message. Needed by SmartEnergy applications. This requires the CBKE and ECC libraries. The emberDsaSignHandler()function is called after DSA signing is complete but before the message has been sent by the APSlayer. Note that when passing a buffer to the stack for DSA signing, the final byte in the buffer hasspecial significance as an indicator of how many leading bytes should be ignored for signaturepurposes. Refer to API documentation of emberDsaSign() or the dsaSign EZSP command forfurther details about this requirement.

EMBER_APS_OPTION_ENCRYPTION Send the message using APS Encryption, using the LinkKey shared with the destination node to encrypt the data at the APS Level.

EMBER_APS_OPTION_RETRY Resend the message using the APS retry mechanism. In the meshstack, this option and the enable route discovery option must be enabled for an existing route tobe repaired automatically.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

45

EMBER_APS_OPTION_ENABLE_ROUTE_DISCOVERY Send the message with the NWK ’en-able route discovery’ flag, which causes a route discovery to be initiated if no route to the des-tination is known. Note that in the mesh stack, this option and the APS retry option must beenabled an existing route to be repaired automatically.

EMBER_APS_OPTION_FORCE_ROUTE_DISCOVERY Send the message with the NWK ’forceroute discovery’ flag, which causes a route discovery to be initiated even if one is known.

EMBER_APS_OPTION_SOURCE_EUI64 Include the source EUI64 in the network frame.

EMBER_APS_OPTION_DESTINATION_EUI64 Include the destination EUI64 in the network frame.

EMBER_APS_OPTION_ENABLE_ADDRESS_DISCOVERY Send a ZDO request to discover thenode ID of the destination, if it is not already know.

EMBER_APS_OPTION_POLL_RESPONSE This message is being sent in response to a call to -::emberPollHandler(). It causes the message to be sent immediately instead of being queued upuntil the next poll from the (end device) destination.

EMBER_APS_OPTION_ZDO_RESPONSE_REQUIRED This incoming message is a valid ZDOrequest and the application is responsible for sending a ZDO response. This flag is used onlywithin emberIncomingMessageHandler() when EMBER_APPLICATION_RECEIVES_UNSU-PPORTED_ZDO_REQUESTS is defined.

EMBER_APS_OPTION_FRAGMENT This message is part of a fragmented message. This optionmay only be set for unicasts. The groupId field gives the index of this fragment in the low-orderbyte. If the low-order byte is zero this is the first fragment and the high-order byte contains thenumber of fragments in the message.


6.2.4.7 enum EmberIncomingMessageType

Defines the possible incoming message types.

Enumerator:

EMBER_INCOMING_UNICAST Unicast.

EMBER_INCOMING_UNICAST_REPLY Unicast reply.

EMBER_INCOMING_MULTICAST Multicast.

EMBER_INCOMING_MULTICAST_LOOPBACK Multicast sent by the local device.

EMBER_INCOMING_BROADCAST Broadcast.

EMBER_INCOMING_BROADCAST_LOOPBACK Broadcast sent by the local device.


6.2.4.8 enum EmberOutgoingMessageType

Defines the possible outgoing message types.

Enumerator:

EMBER_OUTGOING_DIRECT Unicast sent directly to an EmberNodeId.

EMBER_OUTGOING_VIA_ADDRESS_TABLE Unicast sent using an entry in the address table.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

46

EMBER_OUTGOING_VIA_BINDING Unicast sent using an entry in the binding table.EMBER_OUTGOING_MULTICAST Multicast message. This value is passed to emberMessage-

SentHandler() only. It may not be passed to emberSendUnicast().EMBER_OUTGOING_BROADCAST Broadcast message. This value is passed to emberMessage-

SentHandler() only. It may not be passed to emberSendUnicast().


6.2.4.9 enum EmberNetworkStatus

Defines the possible join states for a node.

Enumerator:

EMBER_NO_NETWORK The node is not associated with a network in any way.EMBER_JOINING_NETWORK The node is currently attempting to join a network.EMBER_JOINED_NETWORK The node is joined to a network.EMBER_JOINED_NETWORK_NO_PARENT The node is an end device joined to a network but

its parent is not responding.EMBER_LEAVING_NETWORK The node is in the process of leaving its current network.


6.2.4.10 enum EmberNetworkScanType

Type for a network scan.

Enumerator:

EMBER_ENERGY_SCAN An energy scan scans each channel for its RSSI value.EMBER_ACTIVE_SCAN An active scan scans each channel for available networks.


6.2.4.11 enum EmberBindingType

Defines binding types.

Enumerator:

EMBER_UNUSED_BINDING A binding that is currently not in use.EMBER_UNICAST_BINDING A unicast binding whose 64-bit identifier is the destination EUI64.

EMBER_MANY_TO_ONE_BINDING A unicast binding whose 64-bit identifier is the many-to-onedestination EUI64. Route discovery should be disabled when sending unicasts via many-to-onebindings.

EMBER_MULTICAST_BINDING A multicast binding whose 64-bit identifier is the group address.A multicast binding can be used to send messages to the group and to receive messages sent tothe group.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

47

6.2.4.12 enum EmberJoinDecision

Decision made by the Trust Center when a node attempts to join.

Enumerator:

EMBER_USE_PRECONFIGURED_KEY Allow the node to join. The node has the key.

EMBER_SEND_KEY_IN_THE_CLEAR Allow the node to join. Send the key to the node.

EMBER_DENY_JOIN Deny join.

EMBER_NO_ACTION Take no action.


6.2.4.13 enum EmberDeviceUpdate

The Status of the Update Device message sent to the Trust Center. The device may have joined or rejoinedinsecurely, rejoined securely, or left. MAC Security has been deprecated and therefore there is no securejoin.

Enumerator:

EMBER_STANDARD_SECURITY_SECURED_REJOINEMBER_STANDARD_SECURITY_UNSECURED_JOINEMBER_DEVICE_LEFTEMBER_STANDARD_SECURITY_UNSECURED_REJOINEMBER_HIGH_SECURITY_SECURED_REJOINEMBER_HIGH_SECURITY_UNSECURED_JOINEMBER_HIGH_SECURITY_UNSECURED_REJOINEMBER_REJOIN_REASON_NONEEMBER_REJOIN_DUE_TO_NWK_KEY_UPDATEEMBER_REJOIN_DUE_TO_LEAVE_MESSAGEEMBER_REJOIN_DUE_TO_NO_PARENTEMBER_REJOIN_DUE_TO_ZLL_TOUCHLINKEMBER_REJOIN_DUE_TO_APP_EVENT_5EMBER_REJOIN_DUE_TO_APP_EVENT_4EMBER_REJOIN_DUE_TO_APP_EVENT_3EMBER_REJOIN_DUE_TO_APP_EVENT_2EMBER_REJOIN_DUE_TO_APP_EVENT_1


6.2.4.14 enum EmberDeviceUpdate

Notes the last rejoin reason.

Enumerator:

EMBER_STANDARD_SECURITY_SECURED_REJOIN

EmberZNet 4.7.2 API EM260 120-3020-000-4720

48

EMBER_STANDARD_SECURITY_UNSECURED_JOINEMBER_DEVICE_LEFTEMBER_STANDARD_SECURITY_UNSECURED_REJOINEMBER_HIGH_SECURITY_SECURED_REJOINEMBER_HIGH_SECURITY_UNSECURED_JOINEMBER_HIGH_SECURITY_UNSECURED_REJOINEMBER_REJOIN_REASON_NONEEMBER_REJOIN_DUE_TO_NWK_KEY_UPDATEEMBER_REJOIN_DUE_TO_LEAVE_MESSAGEEMBER_REJOIN_DUE_TO_NO_PARENTEMBER_REJOIN_DUE_TO_ZLL_TOUCHLINKEMBER_REJOIN_DUE_TO_APP_EVENT_5EMBER_REJOIN_DUE_TO_APP_EVENT_4EMBER_REJOIN_DUE_TO_APP_EVENT_3EMBER_REJOIN_DUE_TO_APP_EVENT_2EMBER_REJOIN_DUE_TO_APP_EVENT_1


6.2.4.15 enum EmberClusterListId

Defines the lists of clusters that must be provided for each endpoint.

Enumerator:

EMBER_INPUT_CLUSTER_LIST Input clusters the endpoint will accept.

EMBER_OUTPUT_CLUSTER_LIST Output clusters the endpoint can send.


6.2.4.16 enum EmberEventUnits

Either marks an event as inactive or specifies the units for the event execution time.

Enumerator:

EMBER_EVENT_INACTIVE The event is not scheduled to run.

EMBER_EVENT_MS_TIME The execution time is in approximate milliseconds.

EMBER_EVENT_QS_TIME The execution time is in ’binary’ quarter seconds (256 approximatemilliseconds each).

EMBER_EVENT_MINUTE_TIME The execution time is in ’binary’ minutes (65536 approximatemilliseconds each).

EMBER_EVENT_ZERO_DELAY The event is scheduled to run at the earliest opportunity.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

49

6.2.4.17 enum EmberJoinMethod

The type of method used for joining.

Enumerator:

EMBER_USE_MAC_ASSOCIATION Normally devices use MAC Association to join a network,which respects the "permit joining" flag in the MAC Beacon. For mobile nodes this value causesthe device to use an Ember Mobile Node Join, which is functionally equivalent to a MAC asso-ciation. This value should be used by default.

EMBER_USE_NWK_REJOIN For those networks where the "permit joining" flag is never turnedon, they will need to use a ZigBee NWK Rejoin. This value causes the rejoin to be sent withOUTNWK security and the Trust Center will be asked to send the NWK key to the device. The NWKkey sent to the device can be encrypted with the device’s corresponding Trust Center link key.That is determined by the EmberJoinDecision on the Trust Center returned by the ::emberTrust-CenterJoinHandler(). For a mobile node this value will cause it to use an Ember Mobile noderejoin, which is functionally equivalent.

EMBER_USE_NWK_REJOIN_HAVE_NWK_KEYEMBER_USE_NWK_COMMISSIONING For those networks where all network and security in-

formation is known ahead of time, a router device may be commissioned such that it does notneed to send any messages to begin communicating on the network.


6.2.4.18 enum EmberCounterType

Defines the events reported to the application by the ::emberCounterHandler().

Enumerator:

EMBER_COUNTER_MAC_RX_BROADCAST The MAC received a broadcast.

EMBER_COUNTER_MAC_TX_BROADCAST The MAC transmitted a broadcast.

EMBER_COUNTER_MAC_RX_UNICAST The MAC received a unicast.

EMBER_COUNTER_MAC_TX_UNICAST_SUCCESS The MAC successfully transmitted a uni-cast.

EMBER_COUNTER_MAC_TX_UNICAST_RETRY The MAC retried a unicast. This is a place-holder and is not used by the ::emberCounterHandler() callback. Instead the number of MACretries are returned in the data parameter of the callback for the EMBER_COUNTER_MAC_TX-_UNICAST_SUCCESS and EMBER_COUNTER_MAC_TX_UNICAST_FAILED types.

EMBER_COUNTER_MAC_TX_UNICAST_FAILED The MAC unsuccessfully transmitted a uni-cast.

EMBER_COUNTER_APS_DATA_RX_BROADCAST The APS layer received a data broadcast.

EMBER_COUNTER_APS_DATA_TX_BROADCAST The APS layer transmitted a data broadcast.

EMBER_COUNTER_APS_DATA_RX_UNICAST The APS layer received a data unicast.

EMBER_COUNTER_APS_DATA_TX_UNICAST_SUCCESS The APS layer successfully trans-mitted a data unicast.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

50

EMBER_COUNTER_APS_DATA_TX_UNICAST_RETRY The APS layer retried a data unicast.This is a placeholder and is not used by the ::emberCounterHandler() callback. Insteadthe number of APS retries are returned in the data parameter of the callback for the EMBER_C-OUNTER_APS_DATA_TX_UNICAST_SUCCESS and EMBER_COUNTER_APS_DATA_TX_-UNICAST_FAILED types.

EMBER_COUNTER_APS_DATA_TX_UNICAST_FAILED The APS layer unsuccessfully trans-mitted a data unicast.

EMBER_COUNTER_ROUTE_DISCOVERY_INITIATED The network layer successfully submit-ted a new route discovery to the MAC.

EMBER_COUNTER_NEIGHBOR_ADDED An entry was added to the neighbor table.

EMBER_COUNTER_NEIGHBOR_REMOVED An entry was removed from the neighbor table.

EMBER_COUNTER_NEIGHBOR_STALE A neighbor table entry became stale because it had notbeen heard from.

EMBER_COUNTER_JOIN_INDICATION A node joined or rejoined to the network via this node.

EMBER_COUNTER_CHILD_REMOVED An entry was removed from the child table.

EMBER_COUNTER_ASH_OVERFLOW_ERROR EZSP-UART only. An overflow error occurredin the UART.

EMBER_COUNTER_ASH_FRAMING_ERROR EZSP-UART only. A framing error occurred inthe UART.

EMBER_COUNTER_ASH_OVERRUN_ERROR EZSP-UART only. An overrun error occurred inthe UART.

EMBER_COUNTER_NWK_FRAME_COUNTER_FAILURE A message was dropped at the Net-work layer because the NWK frame counter was not higher than the last message seen from thatsource.

EMBER_COUNTER_APS_FRAME_COUNTER_FAILURE A message was dropped at the APSlayer because the APS frame counter was not higher than the last message seen from that source.

EMBER_COUNTER_ASH_XOFF EZSP-UART only. An XOFF was transmitted by the UART.

EMBER_COUNTER_APS_LINK_KEY_NOT_AUTHORIZED A message was dropped at the A-PS layer because it had APS encryption but the key associated with the sender has not beenauthenticated, and thus the key is not authorized for use in APS data messages.

EMBER_COUNTER_NWK_DECRYPTION_FAILURE A NWK encrypted message was receivedbut dropped because decryption failed.

EMBER_COUNTER_APS_DECRYPTION_FAILURE An APS encrypted message was receivedbut dropped because decryption failed.

EMBER_COUNTER_ALLOCATE_PACKET_BUFFER_FAILURE The number of times we failedto allocate a set of linked packet buffers. This doesn’t necessarily mean that the packet buffercount was 0 at the time, but that the number requested was greater than the number free.

EMBER_COUNTER_RELAYED_UNICAST The number of relayed unicast packets.

EMBER_COUNTER_PHY_TO_MAC_QUEUE_LIMIT_REACHED The number of times we droppeda packet due to reaching the preset PHY to MAC queue limit (emMaxPhyToMacQueueLength).The limit will determine how many messages are accepted by the PHY between calls to ember-Tick(). After that limit is hit, packets will be dropped. The number of dropped packets will berecorded in this counter.NOTE: For each call to emberCounterHandler() there may be more than 1 packet that wasdropped due to the limit reached. The actual number of packets dropped will be returned inthe ’data’ parameter passed to that function.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

51

EMBER_COUNTER_PACKET_VALIDATE_LIBRARY_DROPPED_COUNT The number of timeswe dropped a packet due to the packet-validate library checking a packet and rejecting it due tolength or other formatting problems.

EMBER_COUNTER_TYPE_COUNT A placeholder giving the number of Ember counter types.


6.2.4.19 enum EmberInitialSecurityBitmask

This is the Initial Security Bitmask that controls the use of various security features.

Enumerator:

EMBER_DISTRIBUTED_TRUST_CENTER_MODE This enables Distributed Trust Center Modefor the device forming the network. (Previously known as EMBER_NO_TRUST_CENTER_M-ODE)

EMBER_TRUST_CENTER_GLOBAL_LINK_KEY This enables a Global Link Key for the TrustCenter. All nodes will share the same Trust Center Link Key.

EMBER_PRECONFIGURED_NETWORK_KEY_MODE This enables devices that perform MACAssociation with a pre-configured Network Key to join the network. It is only set on the TrustCenter.

EMBER_HAVE_TRUST_CENTER_EUI64 This denotes that the EmberInitialSecurityState::preconfigured-TrustCenterEui64 has a value in it containing the trust center EUI64. The device will only joina network and accept commands from a trust center with that EUI64. Normally this bit is NOTset, and the EUI64 of the trust center is learned during the join process. When commission-ing a device to join onto an existing network that is using a trust center, and without sending anymessages, this bit must be set and the field EmberInitialSecurityState::preconfiguredTrustCenter-Eui64 must be populated with the appropriate EUI64.

EMBER_TRUST_CENTER_USES_HASHED_LINK_KEY This denotes that the EmberInitialSecurity-State::preconfiguredKey is not the actual Link Key but a Root Key known only to the Trust Cen-ter. It is hashed with the IEEE Address of the destination device in order to create the actual LinkKey used in encryption. This is bit is only used by the Trust Center. The joining device need notset this.

EMBER_HAVE_PRECONFIGURED_KEY This denotes that the EmberInitialSecurityState::preconfigured-Key element has valid data that should be used to configure the initial security state.

EMBER_HAVE_NETWORK_KEY This denotes that the EmberInitialSecurityState::networkKey el-ement has valid data that should be used to configure the initial security state.

EMBER_GET_LINK_KEY_WHEN_JOINING This denotes to a joining node that it should attemptto acquire a Trust Center Link Key during joining. This is only necessary if the device does nothave a pre-configured key.

EMBER_REQUIRE_ENCRYPTED_KEY This denotes that a joining device should only accept anencrypted network key from the Trust Center (using its pre-configured key). A key sent in-the-clear by the Trust Center will be rejected and the join will fail. This option is only valid whenutilizing a pre-configured key.

EMBER_NO_FRAME_COUNTER_RESET This denotes whether the device should NOT reset itsoutgoing frame counters (both NWK and APS) when ::emberSetInitialSecurityState() is called.Normally it is advised to reset the frame counter before joining a new network. However in caseswhere a device is joining to the same network again (but not using ::emberRejoinNetwork()) itshould keep the NWK and APS frame counters stored in its tokens.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

52

EMBER_GET_PRECONFIGURED_KEY_FROM_INSTALL_CODE This denotes that the deviceshould obtain its preconfigured key from an installation code stored in the manufacturing token.The token contains a value that will be hashed to obtain the actual preconfigured key. If thattoken is not valid than the call to ::emberSetInitialSecurityState() will fail.


6.2.4.20 enum EmberExtendedSecurityBitmask

This is the Extended Security Bitmask that controls the use of various extended security features.

Enumerator:

EMBER_JOINER_GLOBAL_LINK_KEY This denotes whether a joiner node (router or end-device)uses a Global Link Key or a Unique Link Key.

EMBER_NWK_LEAVE_REQUEST_NOT_ALLOWED This denotes whether a router node shoulddiscard or accept network Leave Commands.


6.2.4.21 enum EmberCurrentSecurityBitmask

This is the Current Security Bitmask that details the use of various security features.

Enumerator:

EMBER_STANDARD_SECURITY_MODE_ This denotes that the device is running in a networkwith ZigBee Standard Security.

EMBER_DISTRIBUTED_TRUST_CENTER_MODE_ This denotes that the device is running in anetwork without a centralized Trust Center.

EMBER_TRUST_CENTER_GLOBAL_LINK_KEY_ This denotes that the device has a Global LinkKey. The Trust Center Link Key is the same across multiple nodes.

EMBER_HAVE_TRUST_CENTER_LINK_KEY This denotes that the node has a Trust Center LinkKey.

EMBER_TRUST_CENTER_USES_HASHED_LINK_KEY_ This denotes that the Trust Center isusing a Hashed Link Key.


6.2.4.22 enum EmberKeyStructBitmask

This bitmask describes the presence of fields within the EmberKeyStruct.

Enumerator:

EMBER_KEY_HAS_SEQUENCE_NUMBER This indicates that the key has a sequence numberassociated with it. (i.e. a Network Key).

EMBER_KEY_HAS_OUTGOING_FRAME_COUNTER This indicates that the key has an outgo-ing frame counter and the corresponding value within the EmberKeyStruct has been populatedwith the data.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

53

EMBER_KEY_HAS_INCOMING_FRAME_COUNTER This indicates that the key has an incom-ing frame counter and the corresponding value within the EmberKeyStruct has been populatedwith the data.

EMBER_KEY_HAS_PARTNER_EUI64 This indicates that the key has an associated Partner EU-I64 address and the corresponding value within the EmberKeyStruct has been populated with thedata.

EMBER_KEY_IS_AUTHORIZED This indicates the key is authorized for use in APS data mes-sages. If the key is not authorized for use in APS data messages it has not yet gone through a keyagreement protocol, such as CBKE (i.e. ECC)

EMBER_KEY_PARTNER_IS_SLEEPY This indicates that the partner associated with the link is asleepy end device. This bit is set automatically if the local device hears a device announce fromthe partner indicating it is not an ’RX on when idle’ device.


6.2.4.23 enum EmberKeyType

This denotes the type of security key.

Enumerator:

EMBER_TRUST_CENTER_LINK_KEY This denotes that the key is a Trust Center Link Key.

EMBER_TRUST_CENTER_MASTER_KEY This denotes that the key is a Trust Center MasterKey.

EMBER_CURRENT_NETWORK_KEY This denotes that the key is the Current Network Key.

EMBER_NEXT_NETWORK_KEY This denotes that the key is the Next Network Key.

EMBER_APPLICATION_LINK_KEY This denotes that the key is an Application Link Key

EMBER_APPLICATION_MASTER_KEY This denotes that the key is an Application Master Key


6.2.4.24 enum EmberKeyStatus

This denotes the status of an attempt to establish a key with another device.

Enumerator:

EMBER_APP_LINK_KEY_ESTABLISHEDEMBER_APP_MASTER_KEY_ESTABLISHEDEMBER_TRUST_CENTER_LINK_KEY_ESTABLISHEDEMBER_KEY_ESTABLISHMENT_TIMEOUTEMBER_KEY_TABLE_FULLEMBER_TC_RESPONDED_TO_KEY_REQUESTEMBER_TC_APP_KEY_SENT_TO_REQUESTEREMBER_TC_RESPONSE_TO_KEY_REQUEST_FAILEDEMBER_TC_REQUEST_KEY_TYPE_NOT_SUPPORTEDEMBER_TC_NO_LINK_KEY_FOR_REQUESTER

EmberZNet 4.7.2 API EM260 120-3020-000-4720

54

EMBER_TC_REQUESTER_EUI64_UNKNOWNEMBER_TC_RECEIVED_FIRST_APP_KEY_REQUESTEMBER_TC_TIMEOUT_WAITING_FOR_SECOND_APP_KEY_REQUESTEMBER_TC_NON_MATCHING_APP_KEY_REQUEST_RECEIVEDEMBER_TC_FAILED_TO_SEND_APP_KEYSEMBER_TC_FAILED_TO_STORE_APP_KEY_REQUESTEMBER_TC_REJECTED_APP_KEY_REQUEST


6.2.4.25 enum EmberLinkKeyRequestPolicy

This enumeration determines whether or not a Trust Center answers link key requests.

Enumerator:

EMBER_DENY_KEY_REQUESTSEMBER_ALLOW_KEY_REQUESTS


6.2.4.26 enum EmberKeySettings

Enumerator:

EMBER_KEY_PERMISSIONS_NONEEMBER_KEY_PERMISSIONS_READING_ALLOWEDEMBER_KEY_PERMISSIONS_HASHING_ALLOWED


6.2.4.27 enum EmberMacPassthroughType

The types of MAC passthrough messages that an application may receive. This is a bitmask.

Enumerator:

EMBER_MAC_PASSTHROUGH_NONE No MAC passthrough messages

EMBER_MAC_PASSTHROUGH_SE_INTERPAN SE InterPAN messages

EMBER_MAC_PASSTHROUGH_EMBERNET EmberNet and first generation (v1) standalone boot-loader messages

EMBER_MAC_PASSTHROUGH_EMBERNET_SOURCE EmberNet messages filtered by theirsource address.

EMBER_MAC_PASSTHROUGH_APPLICATION Application-specific passthrough messages.

EMBER_MAC_PASSTHROUGH_CUSTOM Custom inter-pan filter


EmberZNet 4.7.2 API EM260 120-3020-000-4720

55

6.2.4.28 enum EmberZdoStatus

Enumerator:

EMBER_ZDP_SUCCESSEMBER_ZDP_INVALID_REQUEST_TYPEEMBER_ZDP_DEVICE_NOT_FOUNDEMBER_ZDP_INVALID_ENDPOINTEMBER_ZDP_NOT_ACTIVEEMBER_ZDP_NOT_SUPPORTEDEMBER_ZDP_TIMEOUTEMBER_ZDP_NO_MATCHEMBER_ZDP_NO_ENTRYEMBER_ZDP_NO_DESCRIPTOREMBER_ZDP_INSUFFICIENT_SPACEEMBER_ZDP_NOT_PERMITTEDEMBER_ZDP_TABLE_FULLEMBER_ZDP_NOT_AUTHORIZEDEMBER_NWK_ALREADY_PRESENTEMBER_NWK_TABLE_FULLEMBER_NWK_UNKNOWN_DEVICE


6.2.4.29 enum EmberZdoServerMask

Enumerator:

EMBER_ZDP_PRIMARY_TRUST_CENTEREMBER_ZDP_SECONDARY_TRUST_CENTEREMBER_ZDP_PRIMARY_BINDING_TABLE_CACHEEMBER_ZDP_SECONDARY_BINDING_TABLE_CACHEEMBER_ZDP_PRIMARY_DISCOVERY_CACHEEMBER_ZDP_SECONDARY_DISCOVERY_CACHEEMBER_ZDP_NETWORK_MANAGER


6.2.4.30 enum EmberZdoConfigurationFlags

Enumerator:

EMBER_APP_RECEIVES_SUPPORTED_ZDO_REQUESTSEMBER_APP_HANDLES_UNSUPPORTED_ZDO_REQUESTSEMBER_APP_HANDLES_ZDO_ENDPOINT_REQUESTSEMBER_APP_HANDLES_ZDO_BINDING_REQUESTS


EmberZNet 4.7.2 API EM260 120-3020-000-4720

56

6.2.5 Function Documentation

6.2.5.1 int8u∗ emberKeyContents ( EmberKeyData ∗ key )

This function allows the programmer to gain access to the actual key data bytes of the EmberKeyDatastruct.

Parameterskey A Pointer to an EmberKeyData structure.

Returns

int8u∗ Returns a pointer to the first byte of the Key data.

6.2.5.2 int8u∗ emberCertificateContents ( EmberCertificateData ∗ cert )

This function allows the programmer to gain access to the actual certificate data bytes of the Ember-CertificateData struct.

Parameterscert A Pointer to an EmberCertificateData structure.

Returns

int8u∗ Returns a pointer to the first byte of the certificate data.

6.2.5.3 int8u∗ emberPublicKeyContents ( EmberPublicKeyData ∗ key )

This function allows the programmer to gain access to the actual public key data bytes of the EmberPublic-KeyData struct.

Parameterskey A Pointer to an EmberPublicKeyData structure.

Returns

int8u∗ Returns a pointer to the first byte of the public key data.

6.2.5.4 int8u∗ emberPrivateKeyContents ( EmberPrivateKeyData ∗ key )

This function allows the programmer to gain access to the actual private key data bytes of the Ember-PrivateKeyData struct.

Parameterskey A Pointer to an EmberPrivateKeyData structure.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

57

Returns

int8u∗ Returns a pointer to the first byte of the private key data.

6.2.5.5 int8u∗ emberSmacContents ( EmberSmacData ∗ key )

This function allows the programmer to gain access to the actual SMAC (Secured Message AuthenticationCode) data of the EmberSmacData struct.

6.2.5.6 int8u∗ emberSignatureContents ( EmberSignatureData ∗ sig )

This function allows the programmer to gain access to the actual ECDSA signature data of the Ember-SignatureData struct.

6.2.6 Variable Documentation

6.2.6.1 const EmberVersion emberVersion

Struct containing the version info.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

58

6.3 Sending and Receiving Messages

Data Structures

• struct InterPanHeaderA struct for keeping track of all of the header info.

Macros

• #define INTER_PAN_UNICAST• #define INTER_PAN_BROADCAST• #define INTER_PAN_MULTICAST• #define MAX_INTER_PAN_MAC_SIZE• #define STUB_NWK_SIZE• #define STUB_NWK_FRAME_CONTROL• #define MAX_STUB_APS_SIZE• #define MAX_INTER_PAN_HEADER_SIZE• #define INTER_PAN_UNICAST• #define INTER_PAN_BROADCAST• #define INTER_PAN_MULTICAST• #define MAX_INTER_PAN_MAC_SIZE• #define STUB_NWK_SIZE• #define STUB_NWK_FRAME_CONTROL• #define MAX_STUB_APS_SIZE• #define MAX_INTER_PAN_HEADER_SIZE

Functions

• EmberMessageBuffer makeInterPanMessage (InterPanHeader ∗headerData, EmberMessageBufferpayload)

• int8u parseInterPanMessage (EmberMessageBuffer message, int8u startOffset, InterPanHeader ∗header-Data)

• int8u makeInterPanMessage (InterPanHeader ∗headerData, int8u ∗message, int8u maxLength, int8u∗payload, int8u payloadLength)

• int8u parseInterPanMessage (int8u ∗message, int8u messageLength, InterPanHeader ∗headerData)


See also ami-inter-pan.h for source code.

See also ami-inter-pan-host.h for source code.


6.3.2.1 #define INTER PAN UNICAST

Definition at line 29 of file ami-inter-pan.h.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

59

6.3.2.2 #define INTER PAN BROADCAST


6.3.2.3 #define INTER PAN MULTICAST


6.3.2.4 #define MAX INTER PAN MAC SIZE


6.3.2.5 #define STUB NWK SIZE


6.3.2.6 #define STUB NWK FRAME CONTROL


6.3.2.7 #define MAX STUB APS SIZE


6.3.2.8 #define MAX INTER PAN HEADER SIZE


6.3.2.9 #define INTER PAN UNICAST

The three types of inter-PAN messages. The values are actually the corresponding APS frame controls.0x03 is the special interPAN message type. Unicast mode is 0x00, broadcast mode is 0x08, and multicastmode is 0x0C.

Definition at line 28 of file ami-inter-pan-host.h.

6.3.2.10 #define INTER PAN BROADCAST


6.3.2.11 #define INTER PAN MULTICAST


6.3.2.12 #define MAX INTER PAN MAC SIZE


EmberZNet 4.7.2 API EM260 120-3020-000-4720

60

6.3.2.13 #define STUB NWK SIZE


6.3.2.14 #define STUB NWK FRAME CONTROL


6.3.2.15 #define MAX STUB APS SIZE


6.3.2.16 #define MAX INTER PAN HEADER SIZE



6.3.3.1 EmberMessageBuffer makeInterPanMessage ( InterPanHeader ∗ headerData,EmberMessageBuffer payload )

Creates an interpan message suitable for passing to emberSendRawMessage().

6.3.3.2 int8u parseInterPanMessage ( EmberMessageBuffer message, int8u startOffset,InterPanHeader ∗ headerData )

This is meant to be called on the message and offset values passed to emberMacPassthroughMessage-Handler(...). The header is parsed and the various fields are written to the InterPanHeader. The returnedvalue is the offset of the payload in the message, or 0 if the message is not a correctly formed AMI interPANmessage.

6.3.3.3 int8u makeInterPanMessage ( InterPanHeader ∗ headerData, int8u ∗ message, int8umaxLength, int8u ∗ payload, int8u payloadLength )

Create an interpan message. message needs to have enough space for the message contents. Upon return,the return value will be the length of the message, or 0 in case of error.

6.3.3.4 int8u parseInterPanMessage ( int8u ∗ message, int8u messageLength, InterPanHeader ∗headerData )

This is meant to be called on the message passed to emberMacPassthroughMessageHandler(...). The headeris parsed and the various fields are written to the InterPanHeader. The returned value is the offset of thepayload in the message, or 0 if the message is not a correctly formed AMI interPAN message.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

61

6.4 Ember Status Codes

Macros

• #define DEFINE_ERROR(symbol, value)

Enumerations

• enum { EMBER_ERROR_CODE_COUNT }

Generic Messages

These messages are system wide.

• #define EMBER_SUCCESS(x00)• #define EMBER_ERR_FATAL(x01)• #define EMBER_BAD_ARGUMENT(x02)• #define EMBER_EEPROM_MFG_STACK_VERSION_MISMATCH(x04)• #define EMBER_INCOMPATIBLE_STATIC_MEMORY_DEFINITIONS(x05)• #define EMBER_EEPROM_MFG_VERSION_MISMATCH(x06)• #define EMBER_EEPROM_STACK_VERSION_MISMATCH(x07)

Packet Buffer Module Errors

• #define EMBER_NO_BUFFERS(x18)

Serial Manager Errors

• #define EMBER_SERIAL_INVALID_BAUD_RATE(x20)• #define EMBER_SERIAL_INVALID_PORT(x21)• #define EMBER_SERIAL_TX_OVERFLOW(x22)• #define EMBER_SERIAL_RX_OVERFLOW(x23)• #define EMBER_SERIAL_RX_FRAME_ERROR(x24)• #define EMBER_SERIAL_RX_PARITY_ERROR(x25)• #define EMBER_SERIAL_RX_EMPTY(x26)• #define EMBER_SERIAL_RX_OVERRUN_ERROR(x27)

MAC Errors

• #define EMBER_MAC_TRANSMIT_QUEUE_FULL(x39)• #define EMBER_MAC_UNKNOWN_HEADER_TYPE(x3A)• #define EMBER_MAC_ACK_HEADER_TYPE(x3B)• #define EMBER_MAC_SCANNING(x3D)• #define EMBER_MAC_NO_DATA(x31)• #define EMBER_MAC_JOINED_NETWORK(x32)• #define EMBER_MAC_BAD_SCAN_DURATION(x33)• #define EMBER_MAC_INCORRECT_SCAN_TYPE(x34)• #define EMBER_MAC_INVALID_CHANNEL_MASK(x35)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

62

• #define EMBER_MAC_COMMAND_TRANSMIT_FAILURE(x36)• #define EMBER_MAC_NO_ACK_RECEIVED(x40)• #define EMBER_MAC_RADIO_NETWORK_SWITCH_FAILED(x41)• #define EMBER_MAC_INDIRECT_TIMEOUT(x42)

Simulated EEPROM Errors

• #define EMBER_SIM_EEPROM_ERASE_PAGE_GREEN(x43)• #define EMBER_SIM_EEPROM_ERASE_PAGE_RED(x44)• #define EMBER_SIM_EEPROM_FULL(x45)• #define EMBER_SIM_EEPROM_INIT_1_FAILED(x48)• #define EMBER_SIM_EEPROM_INIT_2_FAILED(x49)• #define EMBER_SIM_EEPROM_INIT_3_FAILED(x4A)• #define EMBER_SIM_EEPROM_REPAIRING(x4D)

Flash Errors

• #define EMBER_ERR_FLASH_WRITE_INHIBITED(x46)• #define EMBER_ERR_FLASH_VERIFY_FAILED(x47)• #define EMBER_ERR_FLASH_PROG_FAIL(x4B)• #define EMBER_ERR_FLASH_ERASE_FAIL(x4C)

Bootloader Errors

• #define EMBER_ERR_BOOTLOADER_TRAP_TABLE_BAD(x58)• #define EMBER_ERR_BOOTLOADER_TRAP_UNKNOWN(x59)• #define EMBER_ERR_BOOTLOADER_NO_IMAGE(x05A)

Transport Errors

• #define EMBER_DELIVERY_FAILED(x66)• #define EMBER_BINDING_INDEX_OUT_OF_RANGE(x69)• #define EMBER_ADDRESS_TABLE_INDEX_OUT_OF_RANGE(x6A)• #define EMBER_INVALID_BINDING_INDEX(x6C)• #define EMBER_INVALID_CALL(x70)• #define EMBER_COST_NOT_KNOWN(x71)• #define EMBER_MAX_MESSAGE_LIMIT_REACHED(x72)• #define EMBER_MESSAGE_TOO_LONG(x74)• #define EMBER_BINDING_IS_ACTIVE(x75)• #define EMBER_ADDRESS_TABLE_ENTRY_IS_ACTIVE(x76)

HAL Module Errors

• #define EMBER_ADC_CONVERSION_DONE(x80)• #define EMBER_ADC_CONVERSION_BUSY(x81)• #define EMBER_ADC_CONVERSION_DEFERRED(x82)• #define EMBER_ADC_NO_CONVERSION_PENDING(x84)• #define EMBER_SLEEP_INTERRUPTED(x85)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

63

PHY Errors

• #define EMBER_PHY_TX_UNDERFLOW(x88)• #define EMBER_PHY_TX_INCOMPLETE(x89)• #define EMBER_PHY_INVALID_CHANNEL(x8A)• #define EMBER_PHY_INVALID_POWER(x8B)• #define EMBER_PHY_TX_BUSY(x8C)• #define EMBER_PHY_TX_CCA_FAIL(x8D)• #define EMBER_PHY_OSCILLATOR_CHECK_FAILED(x8E)• #define EMBER_PHY_ACK_RECEIVED(x8F)

Return Codes Passed to emberStackStatusHandler()

See also ::emberStackStatusHandler().

• #define EMBER_NETWORK_UP(x90)• #define EMBER_NETWORK_DOWN(x91)• #define EMBER_JOIN_FAILED(x94)• #define EMBER_MOVE_FAILED(x96)• #define EMBER_CANNOT_JOIN_AS_ROUTER(x98)• #define EMBER_NODE_ID_CHANGED(x99)• #define EMBER_PAN_ID_CHANGED(x9A)• #define EMBER_CHANNEL_CHANGED(x9B)• #define EMBER_NO_BEACONS(xAB)• #define EMBER_RECEIVED_KEY_IN_THE_CLEAR(xAC)• #define EMBER_NO_NETWORK_KEY_RECEIVED(xAD)• #define EMBER_NO_LINK_KEY_RECEIVED(xAE)• #define EMBER_PRECONFIGURED_KEY_REQUIRED(xAF)

Security Errors

• #define EMBER_KEY_INVALID(xB2)• #define EMBER_INVALID_SECURITY_LEVEL(x95)• #define EMBER_APS_ENCRYPTION_ERROR(xA6)• #define EMBER_TRUST_CENTER_MASTER_KEY_NOT_SET(xA7)• #define EMBER_SECURITY_STATE_NOT_SET(xA8)• #define EMBER_KEY_TABLE_INVALID_ADDRESS(xB3)• #define EMBER_SECURITY_CONFIGURATION_INVALID(xB7)• #define EMBER_TOO_SOON_FOR_SWITCH_KEY(xB8)• #define EMBER_SIGNATURE_VERIFY_FAILURE(xB9)• #define EMBER_KEY_NOT_AUTHORIZED(xBB)• #define EMBER_SECURITY_DATA_INVALID(xBD)

Miscellaneous Network Errors

• #define EMBER_NOT_JOINED(x93)• #define EMBER_NETWORK_BUSY(xA1)• #define EMBER_INVALID_ENDPOINT(xA3)• #define EMBER_BINDING_HAS_CHANGED(xA4)• #define EMBER_INSUFFICIENT_RANDOM_DATA(xA5)• #define EMBER_SOURCE_ROUTE_FAILURE(xA9)• #define EMBER_MANY_TO_ONE_ROUTE_FAILURE(xAA)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

64

Miscellaneous Utility Errors

• #define EMBER_STACK_AND_HARDWARE_MISMATCH(xB0)• #define EMBER_INDEX_OUT_OF_RANGE(xB1)• #define EMBER_TABLE_FULL(xB4)• #define EMBER_TABLE_ENTRY_ERASED(xB6)• #define EMBER_LIBRARY_NOT_PRESENT(xB5)• #define EMBER_OPERATION_IN_PROGRESS(xBA)• #define EMBER_TRUST_CENTER_EUI_HAS_CHANGED(xBC)

Application Errors

These error codes are available for application use.

• #define EMBER_APPLICATION_ERROR_0(xF0)• #define EMBER_APPLICATION_ERROR_1(xF1)• #define EMBER_APPLICATION_ERROR_2(xF2)• #define EMBER_APPLICATION_ERROR_3(xF3)• #define EMBER_APPLICATION_ERROR_4(xF4)• #define EMBER_APPLICATION_ERROR_5(xF5)• #define EMBER_APPLICATION_ERROR_6(xF6)• #define EMBER_APPLICATION_ERROR_7(xF7)• #define EMBER_APPLICATION_ERROR_8(xF8)• #define EMBER_APPLICATION_ERROR_9(xF9)• #define EMBER_APPLICATION_ERROR_10(xFA)• #define EMBER_APPLICATION_ERROR_11(xFB)• #define EMBER_APPLICATION_ERROR_12(xFC)• #define EMBER_APPLICATION_ERROR_13(xFD)• #define EMBER_APPLICATION_ERROR_14(xFE)• #define EMBER_APPLICATION_ERROR_15(xFF)


Many EmberZNet API functions return an EmberStatus value to indicate the success or failure of the call.Return codes are one byte long. This page documents the possible status codes and their meanings.

See error-def.h for source code.

See also error.h for information on how the values for the return codes are built up from these definitions.The file error-def.h is separated from error.h because utilities will use this file to parse the return codes.

Note

Do not include error-def.h directly. It is included by error.h inside an enum typedef, which is in turnincluded by ember.h.


6.4.2.1 #define DEFINE ERROR( symbol, value )

Macro used by error-def.h to define all of the return codes.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

65

Parameterssymbol The name of the constant being defined. All Ember returns begin with EMBER_. For

example, ::EMBER_CONNECTION_OPEN.value The value of the return code. For example, 0x61.

Definition at line 35 of file error.h.

6.4.2.2 #define EMBER SUCCESS( x00 )

The generic "no error" message.

Definition at line 43 of file error-def.h.

6.4.2.3 #define EMBER ERR FATAL( x01 )

The generic "fatal error" message.


6.4.2.4 #define EMBER BAD ARGUMENT( x02 )

An invalid value was passed as an argument to a function.


6.4.2.5 #define EMBER EEPROM MFG STACK VERSION MISMATCH( x04 )

The manufacturing and stack token format in non-volatile memory is different than what the stack expects(returned at initialization).


6.4.2.6 #define EMBER INCOMPATIBLE STATIC MEMORY DEFINITIONS( x05 )

The static memory definitions in ember-static-memory.h are incompatible with this stack version.


6.4.2.7 #define EMBER EEPROM MFG VERSION MISMATCH( x06 )

The manufacturing token format in non-volatile memory is different than what the stack expects (returnedat initialization).


6.4.2.8 #define EMBER EEPROM STACK VERSION MISMATCH( x07 )

The stack token format in non-volatile memory is different than what the stack expects (returned at initial-ization).


EmberZNet 4.7.2 API EM260 120-3020-000-4720

66

6.4.2.9 #define EMBER NO BUFFERS( x18 )

There are no more buffers.


6.4.2.10 #define EMBER SERIAL INVALID BAUD RATE( x20 )

Specified an invalid baud rate.


6.4.2.11 #define EMBER SERIAL INVALID PORT( x21 )

Specified an invalid serial port.


6.4.2.12 #define EMBER SERIAL TX OVERFLOW( x22 )

Tried to send too much data.


6.4.2.13 #define EMBER SERIAL RX OVERFLOW( x23 )

There was not enough space to store a received character and the character was dropped.


6.4.2.14 #define EMBER SERIAL RX FRAME ERROR( x24 )

Detected a UART framing error.


6.4.2.15 #define EMBER SERIAL RX PARITY ERROR( x25 )

Detected a UART parity error.


6.4.2.16 #define EMBER SERIAL RX EMPTY( x26 )

There is no received data to process.


6.4.2.17 #define EMBER SERIAL RX OVERRUN ERROR( x27 )

The receive interrupt was not handled in time, and a character was dropped.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

67

6.4.2.18 #define EMBER MAC TRANSMIT QUEUE FULL( x39 )

The MAC transmit queue is full.


6.4.2.19 #define EMBER MAC UNKNOWN HEADER TYPE( x3A )

MAC header FCF error on receive.


6.4.2.20 #define EMBER MAC ACK HEADER TYPE( x3B )

MAC ACK header received.


6.4.2.21 #define EMBER MAC SCANNING( x3D )

The MAC can’t complete this task because it is scanning.


6.4.2.22 #define EMBER MAC NO DATA( x31 )

No pending data exists for device doing a data poll.


6.4.2.23 #define EMBER MAC JOINED NETWORK( x32 )

Attempt to scan when we are joined to a network.


6.4.2.24 #define EMBER MAC BAD SCAN DURATION( x33 )

Scan duration must be 0 to 14 inclusive. Attempt was made to scan with an incorrect duration value.


6.4.2.25 #define EMBER MAC INCORRECT SCAN TYPE( x34 )

emberStartScan was called with an incorrect scan type.


6.4.2.26 #define EMBER MAC INVALID CHANNEL MASK( x35 )

emberStartScan was called with an invalid channel mask.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

68

6.4.2.27 #define EMBER MAC COMMAND TRANSMIT FAILURE( x36 )

Failed to scan current channel because we were unable to transmit the relevent MAC command.


6.4.2.28 #define EMBER MAC NO ACK RECEIVED( x40 )

We expected to receive an ACK following the transmission, but the MAC level ACK was never received.


6.4.2.29 #define EMBER MAC RADIO NETWORK SWITCH FAILED( x41 )

MAC failed to transmit a message because could not successfully perform a radio network switch.


6.4.2.30 #define EMBER MAC INDIRECT TIMEOUT( x42 )

Indirect data message timed out before polled.


6.4.2.31 #define EMBER SIM EEPROM ERASE PAGE GREEN( x43 )

The Simulated EEPROM is telling the application that there is at least one flash page to be erased. TheGREEN status means the current page has not filled above the ::ERASE_CRITICAL_THRESHOLD.

The application should call the function ::halSimEepromErasePage() when it can to erase a page.


6.4.2.32 #define EMBER SIM EEPROM ERASE PAGE RED( x44 )

The Simulated EEPROM is telling the application that there is at least one flash page to be erased. TheRED status means the current page has filled above the ::ERASE_CRITICAL_THRESHOLD.

Due to the shrinking availability of write space, there is a danger of data loss. The application must call thefunction ::halSimEepromErasePage() as soon as possible to erase a page.


6.4.2.33 #define EMBER SIM EEPROM FULL( x45 )

The Simulated EEPROM has run out of room to write any new data and the data trying to be set has beenlost. This error code is the result of ignoring the ::SIM_EEPROM_ERASE_PAGE_RED error code.

The application must call the function ::halSimEepromErasePage() to make room for any further calls toset a token.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

69

6.4.2.34 #define EMBER SIM EEPROM INIT 1 FAILED( x48 )

Attempt 1 to initialize the Simulated EEPROM has failed.

This failure means the information already stored in Flash (or a lack thereof), is fatally incompatible withthe token information compiled into the code image being run.


6.4.2.35 #define EMBER SIM EEPROM INIT 2 FAILED( x49 )


This failure means Attempt 1 failed, and the token system failed to properly reload default tokens and resetthe Simulated EEPROM.


6.4.2.36 #define EMBER SIM EEPROM INIT 3 FAILED( x4A )


This failure means one or both of the tokens ::TOKEN_MFG_NVDATA_VERSION or ::TOKEN_STAC-K_NVDATA_VERSION were incorrect and the token system failed to properly reload default tokens andreset the Simulated EEPROM.


6.4.2.37 #define EMBER SIM EEPROM REPAIRING( x4D )

The Simulated EEPROM is repairing itself.

While there’s nothing for an app to do when the SimEE is going to repair itself (SimEE has to be fullyfunctional for the rest of the system to work), alert the application to the fact that repairing is occurring.There are debugging scenarios where an app might want to know that repairing is happening; such asmonitoring frequency.

Note

Common situations will trigger an expected repair, such as using an erased chip or changing tokendefinitions.


6.4.2.38 #define EMBER ERR FLASH WRITE INHIBITED( x46 )

A fatal error has occurred while trying to write data to the Flash. The target memory attempting to beprogrammed is already programmed. The flash write routines were asked to flip a bit from a 0 to 1, whichis physically impossible and the write was therefore inhibited. The data in the flash cannot be trusted afterthis error.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

70

6.4.2.39 #define EMBER ERR FLASH VERIFY FAILED( x47 )

A fatal error has occurred while trying to write data to the Flash and the write verification has failed. Thedata in the flash cannot be trusted after this error, and it is possible this error is the result of exceeding thelife cycles of the flash.


6.4.2.40 #define EMBER ERR FLASH PROG FAIL( x4B )

Description:

A fatal error has occurred while trying to write data to the flash, possibly due to write protection or aninvalid address. The data in the flash cannot be trusted after this error, and it is possible this error isthe result of exceeding the life cycles of the flash.


6.4.2.41 #define EMBER ERR FLASH ERASE FAIL( x4C )

Description:

A fatal error has occurred while trying to erase flash, possibly due to write protection. The data in theflash cannot be trusted after this error, and it is possible this error is the result of exceeding the lifecycles of the flash.


6.4.2.42 #define EMBER ERR BOOTLOADER TRAP TABLE BAD( x58 )

The bootloader received an invalid message (failed attempt to go into bootloader).


6.4.2.43 #define EMBER ERR BOOTLOADER TRAP UNKNOWN( x59 )

Bootloader received an invalid message (failed attempt to go into bootloader).


6.4.2.44 #define EMBER ERR BOOTLOADER NO IMAGE( x05A )

The bootloader cannot complete the bootload operation because either an image was not found or the imageexceeded memory bounds.


6.4.2.45 #define EMBER DELIVERY FAILED( x66 )

The APS layer attempted to send or deliver a message, but it failed.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

71

6.4.2.46 #define EMBER BINDING INDEX OUT OF RANGE( x69 )

This binding index is out of range for the current binding table.


6.4.2.47 #define EMBER ADDRESS TABLE INDEX OUT OF RANGE( x6A )

This address table index is out of range for the current address table.


6.4.2.48 #define EMBER INVALID BINDING INDEX( x6C )

An invalid binding table index was given to a function.


6.4.2.49 #define EMBER INVALID CALL( x70 )

The API call is not allowed given the current state of the stack.


6.4.2.50 #define EMBER COST NOT KNOWN( x71 )

The link cost to a node is not known.


6.4.2.51 #define EMBER MAX MESSAGE LIMIT REACHED( x72 )

The maximum number of in-flight messages (i.e. EMBER_APS_UNICAST_MESSAGE_COUNT) hasbeen reached.


6.4.2.52 #define EMBER MESSAGE TOO LONG( x74 )

The message to be transmitted is too big to fit into a single over-the-air packet.


6.4.2.53 #define EMBER BINDING IS ACTIVE( x75 )

The application is trying to delete or overwrite a binding that is in use.


6.4.2.54 #define EMBER ADDRESS TABLE ENTRY IS ACTIVE( x76 )

The application is trying to overwrite an address table entry that is in use.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

72


6.4.2.55 #define EMBER ADC CONVERSION DONE( x80 )

Conversion is complete.


6.4.2.56 #define EMBER ADC CONVERSION BUSY( x81 )

Conversion cannot be done because a request is being processed.


6.4.2.57 #define EMBER ADC CONVERSION DEFERRED( x82 )

Conversion is deferred until the current request has been processed.


6.4.2.58 #define EMBER ADC NO CONVERSION PENDING( x84 )

No results are pending.


6.4.2.59 #define EMBER SLEEP INTERRUPTED( x85 )

Sleeping (for a duration) has been abnormally interrupted and exited prematurely.


6.4.2.60 #define EMBER PHY TX UNDERFLOW( x88 )

The transmit hardware buffer underflowed.


6.4.2.61 #define EMBER PHY TX INCOMPLETE( x89 )

The transmit hardware did not finish transmitting a packet.


6.4.2.62 #define EMBER PHY INVALID CHANNEL( x8A )

An unsupported channel setting was specified.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

73

6.4.2.63 #define EMBER PHY INVALID POWER( x8B )

An unsupported power setting was specified.


6.4.2.64 #define EMBER PHY TX BUSY( x8C )

The requested operation cannot be completed because the radio is currently busy, either transmitting apacket or performing calibration.


6.4.2.65 #define EMBER PHY TX CCA FAIL( x8D )

The transmit attempt failed because all CCA attempts indicated that the channel was busy.


6.4.2.66 #define EMBER PHY OSCILLATOR CHECK FAILED( x8E )

The software installed on the hardware doesn’t recognize the hardware radio type.


6.4.2.67 #define EMBER PHY ACK RECEIVED( x8F )

The expected ACK was received after the last transmission.


6.4.2.68 #define EMBER NETWORK UP( x90 )

The stack software has completed initialization and is ready to send and receive packets over the air.


6.4.2.69 #define EMBER NETWORK DOWN( x91 )

The network is not operating.


6.4.2.70 #define EMBER JOIN FAILED( x94 )

An attempt to join a network failed.


6.4.2.71 #define EMBER MOVE FAILED( x96 )

After moving, a mobile node’s attempt to re-establish contact with the network failed.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

74


6.4.2.72 #define EMBER CANNOT JOIN AS ROUTER( x98 )

An attempt to join as a router failed due to a ZigBee versus ZigBee Pro incompatibility. ZigBee devicesjoining ZigBee Pro networks (or vice versa) must join as End Devices, not Routers.


6.4.2.73 #define EMBER NODE ID CHANGED( x99 )

The local node ID has changed. The application can obtain the new node ID by calling ::emberGetNode-Id().


6.4.2.74 #define EMBER PAN ID CHANGED( x9A )

The local PAN ID has changed. The application can obtain the new PAN ID by calling ::emberGetPanId().


6.4.2.75 #define EMBER CHANNEL CHANGED( x9B )

The channel has changed.


6.4.2.76 #define EMBER NO BEACONS( xAB )

An attempt to join or rejoin the network failed because no router beacons could be heard by the joiningnode.


6.4.2.77 #define EMBER RECEIVED KEY IN THE CLEAR( xAC )

An attempt was made to join a Secured Network using a pre-configured key, but the Trust Center sent backa Network Key in-the-clear when an encrypted Network Key was required. (EMBER_REQUIRE_ENCR-YPTED_KEY).


6.4.2.78 #define EMBER NO NETWORK KEY RECEIVED( xAD )

An attempt was made to join a Secured Network, but the device did not receive a Network Key.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

75

6.4.2.79 #define EMBER NO LINK KEY RECEIVED( xAE )

After a device joined a Secured Network, a Link Key was requested (EMBER_GET_LINK_KEY_WHE-N_JOINING) but no response was ever received.


6.4.2.80 #define EMBER PRECONFIGURED KEY REQUIRED( xAF )

An attempt was made to join a Secured Network without a pre-configured key, but the Trust Center sentencrypted data using a pre-configured key.


6.4.2.81 #define EMBER KEY INVALID( xB2 )

The passed key data is not valid. A key of all zeros or all F’s are reserved values and cannot be used.


6.4.2.82 #define EMBER INVALID SECURITY LEVEL( x95 )

The chosen security level (the value of EMBER_SECURITY_LEVEL) is not supported by the stack.


6.4.2.83 #define EMBER APS ENCRYPTION ERROR( xA6 )

There was an error in trying to encrypt at the APS Level.

This could result from either an inability to determine the long address of the recipient from the short ad-dress (no entry in the binding table) or there is no link key entry in the table associated with the destination,or there was a failure to load the correct key into the encryption core.


6.4.2.84 #define EMBER TRUST CENTER MASTER KEY NOT SET( xA7 )

There was an attempt to form a network using High security without setting the Trust Center master keyfirst.


6.4.2.85 #define EMBER SECURITY STATE NOT SET( xA8 )

There was an attempt to form or join a network with security without calling ::emberSetInitialSecurity-State() first.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

76

6.4.2.86 #define EMBER KEY TABLE INVALID ADDRESS( xB3 )

There was an attempt to set an entry in the key table using an invalid long address. An entry cannot be setusing either the local device’s or Trust Center’s IEEE address. Or an entry already exists in the table withthe same IEEE address. An Address of all zeros or all F’s are not valid addresses in 802.15.4.


6.4.2.87 #define EMBER SECURITY CONFIGURATION INVALID( xB7 )

There was an attempt to set a security configuration that is not valid given the other security settings.


6.4.2.88 #define EMBER TOO SOON FOR SWITCH KEY( xB8 )

There was an attempt to broadcast a key switch too quickly after broadcasting the next network key. TheTrust Center must wait at least a period equal to the broadcast timeout so that all routers have a chance toreceive the broadcast of the new network key.


6.4.2.89 #define EMBER SIGNATURE VERIFY FAILURE( xB9 )

The received signature corresponding to the message that was passed to the CBKE Library failed verifica-tion, it is not valid.


6.4.2.90 #define EMBER KEY NOT AUTHORIZED( xBB )

The message could not be sent because the link key corresponding to the destination is not authorized foruse in APS data messages. APS Commands (sent by the stack) are allowed. To use it for encryption ofAPS data messages it must be authorized using a key agreement protocol (such as CBKE).


6.4.2.91 #define EMBER SECURITY DATA INVALID( xBD )

The security data provided was not valid, or an integrity check failed.


6.4.2.92 #define EMBER NOT JOINED( x93 )

The node has not joined a network.


6.4.2.93 #define EMBER NETWORK BUSY( xA1 )

A message cannot be sent because the network is currently overloaded.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

77


6.4.2.94 #define EMBER INVALID ENDPOINT( xA3 )

The application tried to send a message using an endpoint that it has not defined.


6.4.2.95 #define EMBER BINDING HAS CHANGED( xA4 )

The application tried to use a binding that has been remotely modified and the change has not yet beenreported to the application.


6.4.2.96 #define EMBER INSUFFICIENT RANDOM DATA( xA5 )

An attempt to generate random bytes failed because of insufficient random data from the radio.


6.4.2.97 #define EMBER SOURCE ROUTE FAILURE( xA9 )

A ZigBee route error command frame was received indicating that a source routed message from this nodefailed en route.


6.4.2.98 #define EMBER MANY TO ONE ROUTE FAILURE( xAA )

A ZigBee route error command frame was received indicating that a message sent to this node along amany-to-one route failed en route. The route error frame was delivered by an ad-hoc search for a function-ing route.


6.4.2.99 #define EMBER STACK AND HARDWARE MISMATCH( xB0 )

A critical and fatal error indicating that the version of the stack trying to run does not match with the chipit is running on. The software (stack) on the chip must be replaced with software that is compatible withthe chip.


6.4.2.100 #define EMBER INDEX OUT OF RANGE( xB1 )

An index was passed into the function that was larger than the valid range.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

78

6.4.2.101 #define EMBER TABLE FULL( xB4 )

There are no empty entries left in the table.


6.4.2.102 #define EMBER TABLE ENTRY ERASED( xB6 )

The requested table entry has been erased and contains no valid data.


6.4.2.103 #define EMBER LIBRARY NOT PRESENT( xB5 )

The requested function cannot be executed because the library that contains the necessary functionality isnot present.


6.4.2.104 #define EMBER OPERATION IN PROGRESS( xBA )

The stack accepted the command and is currently processing the request. The results will be returned viaan appropriate handler.


6.4.2.105 #define EMBER TRUST CENTER EUI HAS CHANGED( xBC )

The EUI of the Trust center has changed due to a successful rejoin. The device may need to perform otherauthentication to verify the new TC is authorized to take over.


6.4.2.106 #define EMBER APPLICATION ERROR 0( xF0 )

This error is reserved for customer application use. This will never be returned from any portion of thenetwork stack or HAL.








EmberZNet 4.7.2 API EM260 120-3020-000-4720

79






















6.4.2.116 #define EMBER APPLICATION ERROR 10( xFA )


EmberZNet 4.7.2 API EM260 120-3020-000-4720

80


6.4.2.117 #define EMBER APPLICATION ERROR 11( xFB )



6.4.2.118 #define EMBER APPLICATION ERROR 12( xFC )



6.4.2.119 #define EMBER APPLICATION ERROR 13( xFD )



6.4.2.120 #define EMBER APPLICATION ERROR 14( xFE )



6.4.2.121 #define EMBER APPLICATION ERROR 15( xFF )




6.4.3.1 anonymous enum

Enumerator:

EMBER_ERROR_CODE_COUNT Gets defined as a count of all the possible return codes in theEmberZNet stack API.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

81

6.5 Smart Energy Security

Functions

• EmberStatus emberGetCertificate (EmberCertificateData ∗result)• EmberStatus emberGenerateCbkeKeys (void)• EmberStatus emberCalculateSmacs (boolean amInitiator, EmberCertificateData ∗partnerCert, Ember-

PublicKeyData ∗partnerEphemeralPublicKey)• EmberStatus emberClearTemporaryDataMaybeStoreLinkKey (boolean storeLinkKey)• EmberStatus emberDsaSign (EmberMessageBuffer messageToSign)• void emberGenerateCbkeKeysHandler (EmberStatus status, EmberPublicKeyData ∗ephemeralPublic-

Key)• void emberCalculateSmacsHandler (EmberStatus status, EmberSmacData ∗initiatorSmac, Ember-

SmacData ∗responderSmac)• void emberDsaSignHandler (EmberStatus status, EmberMessageBuffer signedMessage)• EmberStatus emberSetPreinstalledCbkeData (EmberPublicKeyData ∗caPublic, EmberCertificateData∗myCert, EmberPrivateKeyData ∗myKey)

• boolean emberGetStackCertificateEui64 (EmberEUI64 certEui64)• EmberStatus emberDsaVerify (EmberMessageDigest ∗digest, EmberCertificateData ∗signerCertificate,

EmberSignatureData ∗receivedSig)• void emberDsaVerifyHandler (EmberStatus status)


This file describes functionality for Certificate Based Key Exchange (CBKE). This is used by Smart Energydevices to generate and store ephemeral ECC keys, derive the SMACs for the Key establishment protocol,and sign messages using their private key for the Demand Response Load Control client cluster.

See cbke-crypto-engine.h for source code.


6.5.2.1 EmberStatus emberGetCertificate ( EmberCertificateData ∗ result )

Retrieves the implicit certificate stored in the MFG tokens of the device.

Parametersresult A pointer to an EmberCertificateData structure where the retrieved certificate will be

stored.

Returns

EMBER_SUCCESS if the certificate was successfully retrieved. EMBER_ERR_FATAL if the tokencontains uninitialized data.

6.5.2.2 EmberStatus emberGenerateCbkeKeys ( void )

This function begins the process of generating an ephemeral public/private ECC key pair.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

82

If no other ECC operation is going on, it will immediately return with EMBER_OPERATION_IN_PRO-GRESS. It will delay a period of time to let APS retries take place, but then it will shutdown the radio andconsume the CPU processing until the key generation is complete. This may take up to 1 second.

The generated results of the key generation is returned via emberGenerateCbkeKeysHandler().

Returns

EMBER_OPERATION_IN_PROGRESS if the stack has queued up the operation for execution.

6.5.2.3 EmberStatus emberCalculateSmacs ( boolean amInitiator, EmberCertificateData ∗partnerCert, EmberPublicKeyData ∗ partnerEphemeralPublicKey )

This function will begin the process of generating the shared secret, the new link key, and the SecuredMessage Authentication Code (SMAC).

If no other ECC operation is going on, it will immediately return with EMBER_OPERATION_IN_PRO-GRESS. It will delay a period of time to let APS retries take place, but then it will shutdown the radio andconsume the CPU processing until SMACs calculations are complete. This may take up to 3.5 seconds.

The calculated SMACS are returned via emberCalculateSmacsHandler().

ParametersamInitiator This boolean indicates whether or not the device is the one that initiated the CBKE with

the remote device, or whether it was the responder to the exchange.partnerCert A pointer to an EmberCertificateData structure that contains the CBKE partner’s im-

plicit certificate.partner-

Ephemeral-PublicKey

A pointer to an EmberPublicKeyData structure that contains the CBKE partner’sephemeral public key.

Returns

EMBER_OPERATION_IN_PROGRESS if the stack has queued up the operation for execution.

6.5.2.4 EmberStatus emberClearTemporaryDataMaybeStoreLinkKey ( boolean storeLinkKey )

This function should be called when all CBKE operations are done. Any temporary data created duringcalls to emberGenerateCbkeKeys() or emberCalculateSmacs() is wiped out. If the local device has val-idated that the partner device has generated the same SMACS as itself, it should set ’storeLinkKey’ toTRUE. Otherwise it should pass in FALSE.

ParametersstoreLinkKey This tells the stack whether to store the newly generated link key, or discard it.

Returns

If storeLinkkey is FALSE, this function returns EMBER_ERR_FATAL always. If storeLinkKey isTRUE, then this function returns the results of whether or not the link key was stored. EMBER_SUC-CESS is returned when key was stored successfully.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

83

6.5.2.5 EmberStatus emberDsaSign ( EmberMessageBuffer messageToSign )

6.5.2.6 void emberGenerateCbkeKeysHandler ( EmberStatus status, EmberPublicKeyData ∗ephemeralPublicKey )

6.5.2.7 void emberCalculateSmacsHandler ( EmberStatus status, EmberSmacData ∗ initiatorSmac,EmberSmacData ∗ responderSmac )

6.5.2.8 void emberDsaSignHandler ( EmberStatus status, EmberMessageBuffer signedMessage )

6.5.2.9 EmberStatus emberSetPreinstalledCbkeData ( EmberPublicKeyData ∗ caPublic,EmberCertificateData ∗ myCert, EmberPrivateKeyData ∗ myKey )

6.5.2.10 boolean emberGetStackCertificateEui64 ( EmberEUI64 certEui64 )

6.5.2.11 EmberStatus emberDsaVerify ( EmberMessageDigest ∗ digest, EmberCertificateData ∗signerCertificate, EmberSignatureData ∗ receivedSig )

6.5.2.12 void emberDsaVerifyHandler ( EmberStatus status )

EmberZNet 4.7.2 API EM260 120-3020-000-4720

84

6.6 Configuration

Macros

• #define EMBER_API_MAJOR_VERSION• #define EMBER_API_MINOR_VERSION• #define EMBER_STACK_PROFILE• #define EMBER_MAX_END_DEVICE_CHILDREN• #define EMBER_SECURITY_LEVEL• #define EMBER_CHILD_TABLE_SIZE• #define EMBER_KEY_TABLE_SIZE• #define EMBER_CERTIFICATE_TABLE_SIZE• #define EMBER_MAX_DEPTH• #define EMBER_MAX_HOPS• #define EMBER_PACKET_BUFFER_COUNT• #define EMBER_MAX_NEIGHBOR_TABLE_SIZE• #define EMBER_NEIGHBOR_TABLE_SIZE• #define EMBER_INDIRECT_TRANSMISSION_TIMEOUT• #define EMBER_MAX_INDIRECT_TRANSMISSION_TIMEOUT• #define EMBER_SEND_MULTICASTS_TO_SLEEPY_ADDRESS• #define EMBER_END_DEVICE_POLL_TIMEOUT• #define EMBER_END_DEVICE_POLL_TIMEOUT_SHIFT• #define EMBER_MOBILE_NODE_POLL_TIMEOUT• #define EMBER_APS_UNICAST_MESSAGE_COUNT• #define EMBER_BINDING_TABLE_SIZE• #define EMBER_ADDRESS_TABLE_SIZE• #define EMBER_RESERVED_MOBILE_CHILD_ENTRIES• #define EMBER_ROUTE_TABLE_SIZE• #define EMBER_DISCOVERY_TABLE_SIZE• #define EMBER_MULTICAST_TABLE_SIZE• #define EMBER_SOURCE_ROUTE_TABLE_SIZE• #define EMBER_DEFAULT_BROADCAST_TABLE_SIZE• #define EMBER_BROADCAST_TABLE_SIZE• #define EMBER_ASSERT_SERIAL_PORT• #define EMBER_MAXIMUM_ALARM_DATA_SIZE• #define EMBER_BROADCAST_ALARM_DATA_SIZE• #define EMBER_UNICAST_ALARM_DATA_SIZE• #define EMBER_FRAGMENT_DELAY_MS• #define EMBER_FRAGMENT_MAX_WINDOW_SIZE• #define EMBER_FRAGMENT_WINDOW_SIZE• #define EMBER_BINDING_TABLE_TOKEN_SIZE• #define EMBER_CHILD_TABLE_TOKEN_SIZE• #define EMBER_KEY_TABLE_TOKEN_SIZE• #define EMBER_REQUEST_KEY_TIMEOUT• #define EMBER_END_DEVICE_BIND_TIMEOUT• #define EMBER_PAN_ID_CONFLICT_REPORT_THRESHOLD• #define EMBER_TASK_COUNT• #define EMBER_SUPPORTED_NETWORKS• #define EZSP_HOST_SOURCE_ROUTE_TABLE_SIZE• #define EZSP_HOST_ASH_RX_POOL_SIZE• #define EZSP_HOST_FORM_AND_JOIN_BUFFER_SIZE

EmberZNet 4.7.2 API EM260 120-3020-000-4720

85


All configurations have defaults, therefore many applications may not need to do anything special. How-ever, you can override these defaults by creating a CONFIGURATION_HEADER and within this header,defining the appropriate macro to a different size. For example, to reduce the number of allocated packetbuffers from 24 (the default) to 8:

#define EMBER_PACKET_BUFFER_COUNT 8

The convenience stubs provided in hal/ember-configuration.c can be overridden by defining theappropriate macro and providing the corresponding callback function. For example, an application withcustom debug channel input must implement emberDebugHandler() to process it. Along with thefunction definition, the application should provide the following line in its CONFIGURATION_HEADE-R:

#define EMBER_APPLICATION_HAS_DEBUG_HANDLER

See ember-configuration-defaults.h for source code.

See ezsp-host-configuration-defaults.h for source code.


6.6.2.1 #define EMBER API MAJOR VERSION

The major version number of the Ember stack release that the application is built against.

Definition at line 58 of file ember-configuration-defaults.h.

6.6.2.2 #define EMBER API MINOR VERSION

The minor version number of the Ember stack release that the application is built against.


6.6.2.3 #define EMBER STACK PROFILE

Specifies the stack profile. The default is Profile 0.

You can set this to Profile 1 (ZigBee) or Profile 2 (ZigBee Pro) in your application’s configuration header(.h) file using:

#define EMBER_STACK_PROFILE 1

or

#define EMBER_STACK_PROFILE 2


EmberZNet 4.7.2 API EM260 120-3020-000-4720

86

6.6.2.4 #define EMBER MAX END DEVICE CHILDREN

The maximum number of end device children that a router will support. For profile 0 the default value is6, for profile 1 the value is 14.


6.6.2.5 #define EMBER SECURITY LEVEL

The security level used for security at the MAC and network layers. The supported values are 0 (nosecurity) and 5 (payload is encrypted and a four-byte MIC is used for authentication).


6.6.2.6 #define EMBER CHILD TABLE SIZE

The maximum number of children that a node may have.

For the tree stack this values defaults to the sum of EMBER_MAX_END_DEVICE_CHILDREN and::EMBER_MAX_ROUTER_CHILDREN. For the mesh stack this defaults to the value of EMBER_MA-X_END_DEVICE_CHILDREN. In the mesh stack router children are not stored in the child table.

Each child table entry requires 4 bytes of RAM and a 10 byte token.

Application definitions for EMBER_CHILD_TABLE_SIZE that are larger than the default value are ig-nored and the default value used instead.


6.6.2.7 #define EMBER KEY TABLE SIZE

The maximum number of link and master keys that a node can store, not including the Trust Center LinkKey. The stack maintains special storage for the Trust Center Link Key.

For the Trust Center, this controls how many totally unique Trust Center Link Keys may be stored. Therest of the devices in the network will use a global or hashed link key.

For normal nodes, this controls the number of Application Link Keys it can store. The Trust Center LinkKey is stored separately from this table.


6.6.2.8 #define EMBER CERTIFICATE TABLE SIZE

The number of entries for the field upgradeable certificate table. Normally certificates (such as SE certs) arestored in the runtime-unmodifiable MFG area. However for those devices wishing to add new certificatesafter manufacturing, they will have to use the normal token space. This defines the size of that table. Formost devices 0 is appropriate since there is no need to change certificates in the field. For those wishingto field upgrade devices with new certificates, 1 is the correct size. Anything more is simply wastingSimEEPROM.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

87

6.6.2.9 #define EMBER MAX DEPTH

The maximum depth of the tree in ZigBee 2006. This implicitly determines the maximum diameter of thenetwork (EMBER_MAX_HOPS) if that value is not overridden.


6.6.2.10 #define EMBER MAX HOPS

The maximum number of hops for a message.

When the radius is not supplied by the Application (i.e. 0) or the stack is sending a message, then thedefault is two times the max depth (EMBER_MAX_DEPTH).


6.6.2.11 #define EMBER PACKET BUFFER COUNT

The number of Packet Buffers available to the Stack. The default is 24.

Each buffer requires 40 bytes of RAM (32 for the buffer itself plus 8 bytes of overhead).


6.6.2.12 #define EMBER MAX NEIGHBOR TABLE SIZE

The maximum number of router neighbors the stack can keep track of.

A neighbor is a node within radio range. The maximum allowed value is 16. End device children are kepttrack of in the child table, not the neighbor table. The default is 16. Setting this value lower than 8 is notrecommended.

Each neighbor table entry consumes 18 bytes of RAM (6 for the table itself and 12 bytes of security data).


6.6.2.13 #define EMBER NEIGHBOR TABLE SIZE


6.6.2.14 #define EMBER INDIRECT TRANSMISSION TIMEOUT

The maximum amount of time (in milliseconds) that the MAC will hold a message for indirect transmissionto a child.

The default is 3000 milliseconds (3 sec). The maximum value is 30 seconds (30000 milliseconds).largervalues will cause rollover confusion.


6.6.2.15 #define EMBER MAX INDIRECT TRANSMISSION TIMEOUT


EmberZNet 4.7.2 API EM260 120-3020-000-4720

88

6.6.2.16 #define EMBER SEND MULTICASTS TO SLEEPY ADDRESS

This defines the behavior for what address multicasts are sent to The normal address is RxOnWhenIdle=T-RUE (0xFFFD). However setting this to true can change locally generated multicasts to be sent to thesleepy broadcast address (0xFFFF). Changing the default is NOT ZigBee Pro compliant and may not beinteroperable.


6.6.2.17 #define EMBER END DEVICE POLL TIMEOUT

The maximum amount of time, in units determined by EMBER_END_DEVICE_POLL_TIMEOUT_SH-IFT, that an EMBER_END_DEVICE or EMBER_SLEEPY_END_DEVICE can wait between polls. Thetimeout value in seconds is EMBER_END_DEVICE_POLL_TIMEOUT << EMBER_END_DEVICE_-POLL_TIMEOUT_SHIFT. If no poll is heard within this time, then the parent removes the end devicefrom its tables. Note: there is a separate EMBER_MOBILE_NODE_POLL_TIMEOUT for mobile enddevices.

Using the default values of both EMBER_END_DEVICE_POLL_TIMEOUT and EMBER_END_DEVI-CE_POLL_TIMEOUT_SHIFT results in a timeout of 320 seconds, or just over five minutes. The maxi-mum value for EMBER_END_DEVICE_POLL_TIMEOUT is 255.


6.6.2.18 #define EMBER END DEVICE POLL TIMEOUT SHIFT

The units used for timing out end devices on their parents. See EMBER_END_DEVICE_POLL_TIMEO-UT for an explanation of how this value is used.

The default value of 6 means gives EMBER_END_DEVICE_POLL_TIMEOUT a default unit of 64 sec-onds, or approximately one minute. The maximum value for EMBER_END_DEVICE_POLL_TIMEOU-T_SHIFT is 14.


6.6.2.19 #define EMBER MOBILE NODE POLL TIMEOUT

The maximum amount of time (in quarter-seconds) that a mobile node can wait between polls. If no pollis heard within this timeout, then the parent removes the mobile node from its tables. The default is 20quarter seconds (5 seconds). The maximum is 255 quarter seconds.


6.6.2.20 #define EMBER APS UNICAST MESSAGE COUNT

The maximum number of APS retried messages that the stack can be transmitting at any time. Here,"transmitting" means the time between the call to ::emberSendUnicast() and the subsequent callback to::emberMessageSentHandler().

Note

A message will typically use one packet buffer for the message header and one or more packet buffersfor the payload. The default is 10 messages.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

89

Each APS retried message consumes 6 bytes of RAM, in addition to two or more packet buffers.


6.6.2.21 #define EMBER BINDING TABLE SIZE

The maximum number of bindings supported by the stack. The default is 0 bindings. Each binding con-sumes 2 bytes of RAM.


6.6.2.22 #define EMBER ADDRESS TABLE SIZE

The maximum number of EUI64<->network address associations that the stack can maintain. The defaultvalue is 8.

Address table entries are 10 bytes in size.


6.6.2.23 #define EMBER RESERVED MOBILE CHILD ENTRIES

The number of child table entries reserved for use only by mobile nodes. The default value is 0.

The maximum number of non-mobile children for a parent is EMBER_CHILD_TABLE_SIZE - EMBER-_RESERVED_MOBILE_CHILD_ENTRIES.


6.6.2.24 #define EMBER ROUTE TABLE SIZE

The maximum number of destinations to which a node can route messages. This include both messagesoriginating at this node and those relayed for others. The default value is 16.

Route table entries are 6 bytes in size.


6.6.2.25 #define EMBER DISCOVERY TABLE SIZE

The number of simultaneous route discoveries that a node will support.

Discovery table entries are 9 bytes in size.


6.6.2.26 #define EMBER MULTICAST TABLE SIZE

The maximum number of multicast groups that the device may be a member of. The default value is 8.

Multicast table entries are 3 bytes in size.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

90

6.6.2.27 #define EMBER SOURCE ROUTE TABLE SIZE

The maximum number of source route table entries supported by the utility code in app/util/source-route.-c. The maximum source route table size is 255 entries, since a one-byte index is used, and the index 0xFFis reserved. The default value is 32.

Source route table entries are 4 bytes in size.


6.6.2.28 #define EMBER DEFAULT BROADCAST TABLE SIZE

The maximum number broadcasts during a single broadcast timeout period. The minimum and defaultvalue is 15 and can only be changed only on compatible Ember stacks. Be very careful when changingthe broadcast table size as it effects timing of the broadcasts as well as number of possible broadcasts.Additionally, this value must be universal for all devices in the network otherwise a single router canoverwhelm all its neighbors with more broadcasts than they can support. In general, this value should beleft alone.

Broadcast table entries are 5 bytes in size.


6.6.2.29 #define EMBER BROADCAST TABLE SIZE


6.6.2.30 #define EMBER ASSERT SERIAL PORT

Settings to control if and where assert information will be printed.

The output can be suppressed by defining EMBER_ASSERT_OUTPUT_DISABLED. The serial port towhich the output is sent can be changed by defining EMBER_ASSERT_SERIAL_PORT as the desiredport.

The default is to have assert output on and sent to serial port 1.


6.6.2.31 #define EMBER MAXIMUM ALARM DATA SIZE

The absolute maximum number of payload bytes in an alarm message.

The three length bytes in EMBER_UNICAST_ALARM_CLUSTER messages do not count towards thislimit.

EMBER_MAXIMUM_ALARM_DATA_SIZE is defined to be 16.

The maximum payload on any particular device is determined by the configuration parameters, EMB-ER_BROADCAST_ALARM_DATA_SIZE and EMBER_UNICAST_ALARM_DATA_SIZE, neither ofwhich may be greater than ::MBER_MAXIMUM_ALARM_DATA_SIZE.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

91

6.6.2.32 #define EMBER BROADCAST ALARM DATA SIZE

The sizes of the broadcast and unicast alarm buffers in bytes.

Devices have a single broadcast alarm buffer. Routers have one unicast alarm buffer for each child tableentry. The total RAM used for alarms is

EMBER_BROADCAST_ALARM_DATA_SIZE+ (EMBER_UNICAST_ALARM_DATA_SIZE *

EMBER_CHILD_TABLE_SIZE)

EMBER_BROADCAST_ALARM_DATA_SIZE is the size of the alarm broadcast buffer. Broadcastalarms whose length is larger will not be buffered or forwarded to sleepy end device children. This pa-rameter must be in the inclusive range 0 ... EMBER_MAXIMUM_ALARM_DATA_SIZE. The defaultvalue is 0.


6.6.2.33 #define EMBER UNICAST ALARM DATA SIZE

The size of the unicast alarm buffers allocated for end device children.

Unicast alarms whose length is larger will not be buffered or forwarded to sleepy end device children. Thisparameter must be in the inclusive range 0 ... EMBER_MAXIMUM_ALARM_DATA_SIZE. The defaultvalue is 0.


6.6.2.34 #define EMBER FRAGMENT DELAY MS

The time the stack will wait (in milliseconds) between sending blocks of a fragmented message. Thedefault value is 0.


6.6.2.35 #define EMBER FRAGMENT MAX WINDOW SIZE

The maximum number of blocks of a fragmented message that can be sent in a single window is defined tobe 8.


6.6.2.36 #define EMBER FRAGMENT WINDOW SIZE

The number of blocks of a fragmented message that can be sent in a single window. The maximum isEMBER_FRAGMENT_MAX_WINDOW_SIZE. The default value is 1.


6.6.2.37 #define EMBER BINDING TABLE TOKEN SIZE


EmberZNet 4.7.2 API EM260 120-3020-000-4720

92

6.6.2.38 #define EMBER CHILD TABLE TOKEN SIZE


6.6.2.39 #define EMBER KEY TABLE TOKEN SIZE


6.6.2.40 #define EMBER REQUEST KEY TIMEOUT

The length of time that the device will wait for an answer to its Application Key Request. For the TrustCenter this is the time it will hold the first request and wait for a second matching request. If both arrivewithin this time period, the Trust Center will reply to both with the new key. If both requests are notreceived then the Trust Center will discard the request. The time is in minutes. The maximum time is 10minutes. A value of 0 minutes indicates that the Trust Center will not buffer the request but instead respondimmediately. Only 1 outstanding request is supported at a time.

The Zigbee Pro Compliant value is 0.


6.6.2.41 #define EMBER END DEVICE BIND TIMEOUT

The time the coordinator will wait (in seconds) for a second end device bind request to arrive. The defaultvalue is 60.


6.6.2.42 #define EMBER PAN ID CONFLICT REPORT THRESHOLD

The number of PAN id conflict reports that must be received by the network manager within one minuteto trigger a PAN id change. Very rarely, a corrupt beacon can pass the CRC check and trigger a falsePAN id conflict. This is more likely to happen in very large dense networks. Setting this value to 2 or 3dramatically reduces the chances of a spurious PAN id change. The maximum value is 63. The defaultvalue is 1.


6.6.2.43 #define EMBER TASK COUNT

The number of event tasks that can be tracked for the purpose of processor idling. The EmberZNet stackrequires 1, an application and associated libraries may use additional tasks, though typically no more than3 are needed for most applications.


6.6.2.44 #define EMBER SUPPORTED NETWORKS

The number of networks supported by the stack.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

93

6.6.2.45 #define EZSP HOST SOURCE ROUTE TABLE SIZE

The size of the source route table on the EZSP host.

Note

This configuration value sets the size of the source route table on the host, not on the node. EMB-ER_SOURCE_ROUTE_TABLE_SIZE sets ::EZSP_CONFIG_SOURCE_ROUTE_TABLE_SIZE ifezsp-utils.c is used, which sets the size of the source route table on the NCP.

Definition at line 32 of file ezsp-host-configuration-defaults.h.

6.6.2.46 #define EZSP HOST ASH RX POOL SIZE

Define the size of the ASH receive buffer pool on the EZSP host.

The number of receive buffers does not need to be greater than the number of packet buffers available on thencp, because this in turn is the maximum number of callbacks that could be received between commands.In reality a value of 20 is a generous allocation.


6.6.2.47 #define EZSP HOST FORM AND JOIN BUFFER SIZE

The size of the buffer for caching data during scans.

The form and join host library uses a flat buffer to store channel energy, pan ids, and matching networks.The underlying data structure is an int16u[], so the true storage size is twice this value. The library requiresthe buffer be at least 32 bytes, so the minimum size here is 16. A matching network requires 16 to 20 bytes,depending on struct padding.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

94

6.7 Debugging Utilities

Macros

• #define NO_DEBUG• #define BASIC_DEBUG• #define FULL_DEBUG• #define emberDebugInit(port)

Functions

• void emberDebugAssert (PGM_P filename, int linenumber)• void emberDebugMemoryDump (int8u ∗start, int8u ∗end)• void emberDebugBinaryPrintf (PGM_P formatString,...)• void emDebugSendVuartMessage (int8u ∗buff, int8u len)• void emberDebugError (EmberStatus code)• boolean emberDebugReportOff (void)• void emberDebugReportRestore (boolean state)• void emberDebugPrintf (PGM_P formatString,...)


EmberZNet debugging utilities. See ember-debug.h for source code.


6.7.2.1 #define NO DEBUG

Definition at line 20 of file ember-debug.h.

6.7.2.2 #define BASIC DEBUG


6.7.2.3 #define FULL DEBUG


6.7.2.4 #define emberDebugInit( port )

This function is obsolete and no longer required to initialize the debug system.

Parametersport Ignored because the port used for debug communication is automatically determined

for each platform.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

95


6.7.3.1 void emberDebugAssert ( PGM_P filename, int linenumber )

Prints the filename and line number to the debug serial port.

Parametersfilename The name of the file where the assert occurred.

linenumber The line number in the file where the assert occurred.

6.7.3.2 void emberDebugMemoryDump ( int8u ∗ start, int8u ∗ end )

Prints the contents of RAM to the debug serial port.

Parametersstart The start address of the block of RAM to dump.end The end address of the block of RAM to dump (address of the last byte).

6.7.3.3 void emberDebugBinaryPrintf ( PGM_P formatString, ... )

Prints binary data to the debug channel.

This function does not use the normal printf format conventions. To print text debug messages, use ember-DebugPrintf(). The format string must contain only these conversion specification characters:

• B - int8u value.

• W - int16u value, printed least significant byte first.

• D - int32u value, printed least significant byte first.

• F - pointer to null terminated string in Flash (PGM_P).

• xxxp - pointer to RAM, length is xxx (max 255).

• lp - pointer to RAM, length is int8u argument.

• xxxf - pointer to Flash (PGM_P), length is xxx (max 255).

• lf - pointer to Flash (PGM_P), length is int8u argument.

• b - EmberMessageBuffer.

Examples:

emberDebugBinaryPrintf("BWD", status, panId, channelMask);

emberDebugBinaryPrintf("F8p", "string example", eui64);emberDebugBinaryPrintf("lp64fb", length, bytes, dataTable

, buffer);

ParametersformatString A string of conversion specification characters describing the arguments to be printed.

... The arguments to be printed.EmberZNet 4.7.2 API EM260 120-3020-000-4720

96

6.7.3.4 void emDebugSendVuartMessage ( int8u ∗ buff, int8u len )

internal debug command used by the HAL to send vuart data out the the debug channel

Parametersbuff pointer to the data to sendlen lenght of the data to send

6.7.3.5 void emberDebugError ( EmberStatus code )

Prints an EmberStatus return code to the serial port.

Parameterscode The EmberStatus code to print.

6.7.3.6 boolean emberDebugReportOff ( void )

Turns off all debug output.

Returns

The current state (TRUE for on, FALSE for off).

6.7.3.7 void emberDebugReportRestore ( boolean state )

Restores the state of the debug output.

Parametersstate The state returned from emberDebugReportOff(). This is done so that debug output is

not blindly turned on.

6.7.3.8 void emberDebugPrintf ( PGM_P formatString, ... )

Prints text debug messages.

ParametersformatString Takes the following:

%% Percent sign%c Single-byte char%s RAM string

EmberZNet 4.7.2 API EM260 120-3020-000-4720

97

%p Flash string (does not follow the printf standard)%u Two-byte unsigned decimal%d Two-byte signed decimal

%x, %%2x, %%4x 1-, 2-, 4-byte hex value (always 0 padded; doesnot follow the printf standard)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

98

6.8 Hardware Abstraction Layer (HAL) API Reference

Modules

• Common Microcontroller Functions• Sample APIs for Peripheral Access• System Timer Control• HAL Utilities• Asynchronous Serial Host (ASH) Framework


<center><h1>Atmel Atmega32 Microprocessors</h1></center>

HAL function names have the following prefix conventions:

halCommon: API that is used by the EmberZNet stack and can also be called from an application. ThisAPI must be implemented. Custom applications can change the implementation of the API but its func-tionality must remain the same.

hal: API that is used by sample applications. Custom applications can remove this API or change itsimplementation as they see fit.

halStack: API used only by the EmberZNet stack. This API must be implemented and should not bedirectly called from any application. Custom applications can change the implementation of the API, butits functionality must remain the same.

halInternal: API that is internal to the HAL. The EmberZNet stack and applications must never call thisAPI directly. Custom applications can change this API as they see fit. However, be careful not to impactthe functionalty of any halStack or halCommon APIs.

See also hal.h.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

99

6.9 Common Microcontroller Functions

Macros

• #define halGetEm2xxResetInfo()• #define MILLISECOND_TICKS_PER_SECOND• #define RESET_UNKNOWN• #define RESET_EXTERNAL• #define RESET_POWERON• #define RESET_WATCHDOG• #define RESET_BROWNOUT• #define RESET_JTAG• #define RESET_ASSERT• #define RESET_RSTACK• #define RESET_CSTACK• #define RESET_BOOTLOADER• #define RESET_PC_ROLLOVER• #define RESET_SOFTWARE• #define RESET_PROTFAULT• #define RESET_FLASH_VERIFY_FAIL• #define RESET_FLASH_WRITE_INHIBIT• #define RESET_BOOTLOADER_IMG_BAD

Functions

• void halStackProcessBootCount (void)• int8u halGetResetInfo (void)• PGM_P halGetResetString (void)• void halInternalAssertFailed (PGM_P filename, int linenumber)• void halStackTriggerDebugTimeSyncCapture (void)


Many of the supplied example applications use these microcontroller functions. See hal/micro/micro.h forsource code.

Note

The term SFD refers to the Start Frame Delimiter.

See also iar.h.

See also 32/micro.h for source code.

See also 32/reserved-ram.h.

See also 128/micro.h.

See also 128/reserved-ram.h.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

100


6.9.2.1 #define halGetEm2xxResetInfo( )

Calls ::halGetExtendedResetInfo() and translates the EM35x reset code to the corresponding value usedby the EM2XX HAL. EM35x reset codes not present in the EM2XX are returned after being OR’ed with0x80.

Application Usage:

Used by the EZSP host as a platform-independent NCP reset code.

Returns

The EM2XX reset code, or a new EM3xx code if B7 is set.

Definition at line 167 of file micro.h.

6.9.2.2 #define MILLISECOND TICKS PER SECOND

Definition at line 50 of file avr-atmega/32/micro.h.

6.9.2.3 #define RESET UNKNOWN

Defines conditions representing possible reasons for a reset.


6.9.2.4 #define RESET EXTERNAL


6.9.2.5 #define RESET POWERON


6.9.2.6 #define RESET WATCHDOG


6.9.2.7 #define RESET BROWNOUT


6.9.2.8 #define RESET JTAG


EmberZNet 4.7.2 API EM260 120-3020-000-4720

101

6.9.2.9 #define RESET ASSERT


6.9.2.10 #define RESET RSTACK


6.9.2.11 #define RESET CSTACK


6.9.2.12 #define RESET BOOTLOADER


6.9.2.13 #define RESET PC ROLLOVER


6.9.2.14 #define RESET SOFTWARE


6.9.2.15 #define RESET PROTFAULT


6.9.2.16 #define RESET FLASH VERIFY FAIL


6.9.2.17 #define RESET FLASH WRITE INHIBIT


6.9.2.18 #define RESET BOOTLOADER IMG BAD



6.9.3.1 void halStackProcessBootCount ( void )

Called from emberInit and provides a means for the HAL to increment a boot counter, most commonly innon-volatile memory.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

102

This is useful while debugging to determine the number of resets that might be seen over a period of time.Exposing this functionality allows the application to disable or alter processing of the boot counter if, forexample, the application is expecting a lot of resets that could wear out non-volatile storage or some

EmberStack Usage:

Called from emberInit only as helpful debugging information. This should be left enabled by default,but this function can also be reduced to a simple return statement if boot counting is not desired.

6.9.3.2 int8u halGetResetInfo ( void )

Gets information about what caused the microcontroller to reset.

Returns

A code identifying the cause of the reset.

6.9.3.3 PGM_P halGetResetString ( void )

Calls halGetResetInfo() and supplies a string describing it.

Application Usage:

Useful for diagnostic printing of text just after program initialization.

Returns

A pointer to a program space string.

6.9.3.4 void halInternalAssertFailed ( PGM_P filename, int linenumber )

Called implicitly through the standard C language assert() macro. An implementation where notificationis, for instance, sent over the serial port can provide meaningful and useful debugging information.

Note

Liberal usage of assert() consumes flash space.

Parametersfilename Name of the file throwing the assert.

linenumber Line number that threw the assert.

6.9.3.5 void halStackTriggerDebugTimeSyncCapture ( void )

Used by the debug stack to trigger the backchannel timer capture circuitry.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

103

6.10 Sample APIs for Peripheral Access

Modules

• Serial UART Communication• ADC Control• Button Control• Buzzer Control• LED Control• Carrier Board Control• SPI Access


These are sample API for accessing peripherals and can be modified as needed for your applications.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

104

6.11 Serial UART Communication

Modules

• Hardware-Specific UART

Enumerations

• enum SerialBaudRate {DEFINE_BAUD, DEFINE_BAUD, DEFINE_BAUD, DEFINE_BAUD,DEFINE_BAUD, DEFINE_BAUD, DEFINE_BAUD, DEFINE_BAUD,DEFINE_BAUD, DEFINE_BAUD, DEFINE_BAUD, DEFINE_BAUD,DEFINE_BAUD, DEFINE_BAUD, DEFINE_BAUD, DEFINE_BAUD,DEFINE_BAUD, DEFINE_BAUD, DEFINE_BAUD }

• enum NameOfType { DEFINE_PARITY, DEFINE_PARITY, DEFINE_PARITY }

Serial Mode Definitions

These are numerical definitions for the possible serial modes so that code can test for the one being used.There may be additional modes defined in the micro-specific micro.h.

• #define EMBER_SERIAL_UNUSED• #define EMBER_SERIAL_FIFO• #define EMBER_SERIAL_BUFFER• #define EMBER_SERIAL_LOWLEVEL

FIFO Utility Macros

These macros manipulate the FIFO queue data structures to add and remove data.

• #define FIFO_ENQUEUE(queue, data, size)• #define FIFO_DEQUEUE(queue, size)

Serial HAL APIs

These functions must be implemented by the HAL in order for the serial code to operate. Only the higher-level serial code uses these functions, so they should not be called directly. The HAL should also implementthe appropriate interrupt handlers to drain the TX queues and fill the RX FIFO queue.

• EmberStatus halInternalUartInit (int8u port, SerialBaudRate rate, SerialParity parity, int8u stopBits)• void halInternalPowerDownUart (void)• void halInternalPowerUpUart (void)• void halInternalStartUartTx (int8u port)• void halInternalStopUartTx (int8u port)• EmberStatus halInternalForceWriteUartData (int8u port, int8u ∗data, int8u length)• EmberStatus halInternalForceReadUartByte (int8u port, int8u ∗dataByte)• void halInternalWaitUartTxComplete (int8u port)• void halInternalRestartUart (void)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

105

• boolean halInternalUart1FlowControlRxIsEnabled (void)• boolean halInternalUart1XonRefreshDone (void)• boolean halInternalUart1TxIsIdle (void)• #define halInternalUartFlowControl(port)• #define halInternalUartRxPump(port)

Buffered Serial Utility APIs

The higher-level serial code implements these APIs, which the HAL uses to deal with buffered serial output.

• void emSerialBufferNextMessageIsr (EmSerialBufferQueue ∗q)• void emSerialBufferNextBlockIsr (EmSerialBufferQueue ∗q, int8u port)

Virtual UART API

API used by the stack in debug builds to receive data arriving over the virtual UART.

• void halStackReceiveVuartMessage (int8u ∗data, int8u length)


This API contains the HAL interfaces that applications must implement for the high-level serial code. Thisheader describes the interface between the high-level serial APIs in app/util/serial/serial.h and the low levelUART implementation.

Some functions in this file return an EmberStatus value. See error-def.h for definitions of all EmberStatusreturn values.

See hal/micro/serial.h for source code.


6.11.2.1 #define EMBER SERIAL UNUSED

A numerical definition for a possible serial mode the code can test for.

Definition at line 55 of file hal/micro/serial.h.

6.11.2.2 #define EMBER SERIAL FIFO



6.11.2.3 #define EMBER SERIAL BUFFER



EmberZNet 4.7.2 API EM260 120-3020-000-4720

106

6.11.2.4 #define EMBER SERIAL LOWLEVEL



6.11.2.5 #define FIFO ENQUEUE( queue, data, size )

Macro that enqueues a byte of data in a FIFO queue.

Parametersqueue Pointer to the FIFO queue.

data Data byte to be enqueued.size Size used to control the wrap-around of the FIFO pointers.


6.11.2.6 #define FIFO DEQUEUE( queue, size )

Macro that de-queues a byte of data from a FIFO queue.

Parametersqueue Pointer to the FIFO queue.

size Size used to control the wrap-around of the FIFO pointers.


6.11.2.7 #define halInternalUartFlowControl( port )

This function is used in FIFO mode when flow control is enabled. It is called from emberSerialReadByte(),and based on the number of bytes used in the uart receive queue, decides when to tell the host it may resumetransmission.

Parametersport Serial port number (0 or 1). (Does nothing for port 0)


6.11.2.8 #define halInternalUartRxPump( port )

This function exists only in Buffer Mode on the EM2xx and in software UART (SOFTUART) mode onthe EM3xx. This function is called by emberSerialReadByte(). It is responsible for maintaining synchro-nization between the emSerialRxQueue and the UART DMA.

Parametersport Serial port number (0 or 1).


EmberZNet 4.7.2 API EM260 120-3020-000-4720

107


6.11.3.1 enum SerialBaudRate

Assign numerical values for variables that hold Baud Rate parameters.

Enumerator:

DEFINE_BAUDDEFINE_BAUDDEFINE_BAUDDEFINE_BAUDDEFINE_BAUDDEFINE_BAUDDEFINE_BAUDDEFINE_BAUDDEFINE_BAUDDEFINE_BAUDDEFINE_BAUDDEFINE_BAUDDEFINE_BAUDDEFINE_BAUDDEFINE_BAUDDEFINE_BAUDDEFINE_BAUDDEFINE_BAUDDEFINE_BAUD


6.11.3.2 enum NameOfType

Assign numerical values for the types of parity. Use for variables that hold Parity parameters.

Enumerator:

DEFINE_PARITYDEFINE_PARITYDEFINE_PARITY


EmberZNet 4.7.2 API EM260 120-3020-000-4720

108


6.11.4.1 EmberStatus halInternalUartInit ( int8u port, SerialBaudRate rate, SerialParity parity, int8ustopBits )

Initializes the UART to the given settings (same parameters as emberSerialInit() ).

Parametersport Serial port number (0 or 1).rate Baud rate (see SerialBaudRate).

parity Parity value (see SerialParity).stopBits Number of stop bits.

Returns

An error code if initialization failed (such as invalid baud rate), otherise EMBER_SUCCESS.

6.11.4.2 void halInternalPowerDownUart ( void )

This function is typically called by ::halPowerDown() and it is responsible for performing all the workinternal to the UART needed to stop the UART before a sleep cycle.

6.11.4.3 void halInternalPowerUpUart ( void )

This function is typically called by ::halPowerUp() and it is responsible for performing all the work internalto the UART needed to restart the UART after a sleep cycle.

6.11.4.4 void halInternalStartUartTx ( int8u port )

Called by serial code whenever anything is queued for transmission to start any interrupt-driven transmis-sion. May be called when transmission is already in progess.


6.11.4.5 void halInternalStopUartTx ( int8u port )

Called by serial code to stop any interrupt-driven serial transmission currently in progress.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

109

6.11.4.6 EmberStatus halInternalForceWriteUartData ( int8u port, int8u ∗ data, int8u length )

Directly writes a byte to the UART for transmission, regardless of anything currently queued for transmis-sion. Should wait for anything currently in the UART hardware registers to finish transmission first, andblock until data is finished being sent.

Parametersport Serial port number (0 or 1).data Pointer to the data to be transmitted.

length The length of data to be transmitted

6.11.4.7 EmberStatus halInternalForceReadUartByte ( int8u port, int8u ∗ dataByte )

Directly reads a byte from the UART for reception, regardless of anything currently queued for reception.Does not block if a data byte has not been received.


dataByte The byte to receive data into.

6.11.4.8 void halInternalWaitUartTxComplete ( int8u port )

Blocks until the UART has finished transmitting any data in its hardware registers.


6.11.4.9 void halInternalRestartUart ( void )

This function is typically called by halInternalPowerUpBoard() and it is responsible for performing all thework internal to the UART needed to restart the UART after a sleep cycle. (For example, resyncing theDMA hardware and the serial FIFO.)

6.11.4.10 boolean halInternalUart1FlowControlRxIsEnabled ( void )

Checks to see if the host is allowed to send serial data to the ncp - i.e., it is not being held off by nCTS oran XOFF. Returns TRUE is the host is able to send.

6.11.4.11 boolean halInternalUart1XonRefreshDone ( void )

When Xon/Xoff flow control is used, returns TRUE if the host is not being held off and XON refreshing iscomplete.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

110

6.11.4.12 boolean halInternalUart1TxIsIdle ( void )

Returns true if the uart transmitter is idle, including the transmit shift register.

6.11.4.13 void emSerialBufferNextMessageIsr ( EmSerialBufferQueue ∗ q )

When new serial transmission is started and bufferQueue->nextByte is equal to NULL, this can becalled to set up nextByte and lastByte for the next message.

Parametersq Pointer to the buffer queue structure for the port.

6.11.4.14 void emSerialBufferNextBlockIsr ( EmSerialBufferQueue ∗ q, int8u port )

When a serial transmission is in progress and bufferQueue->nextByte has been sent and incre-mented leaving it equal to lastByte, this should be called to set up nextByte and lastByte for the nextblock.

Parametersq Pointer to the buffer queue structure for the port.

port Serial port number (0 or 1).

6.11.4.15 void halStackReceiveVuartMessage ( int8u ∗ data, int8u length )

When using a debug build with virtual UART support, this API is called by the stack when virtual UARTdata has been received over the debug channel.

Parametersdata Pointer to the the data received

length Length of the data received

EmberZNet 4.7.2 API EM260 120-3020-000-4720

111

6.12 Hardware-Specific UART

UART0 Tinies

UART I/O tiny implementations for UART0.

• EmberStatus halUart0ReadByteTimeoutTiny (int8u ∗dataByte)• #define halUart0InitTiny()• #define halUart0WriteByteTiny(x)


This contains the prototypes and defines for direct hardware manipulation of UART0. Normally, one wouldgo through Serial UART Communication and the HAL. Use these if you want to break the HAL (that is,save code size) and go straight to the hardware.

Some functions in this file return an EmberStatus value. See stack/include/error-def.h for definitions of allEmberStatus return values.

See uart.h for source code.


6.12.2.1 #define halUart0InitTiny( )

Simple hardware initialization of UART0.

BIT(USBS0) is set for 2 stop bits. Remove it for only 1 stop bit. The 25 is for a 9600 baud rate on a systemrunning at 4MHz. The other hard-coded BIT(#)s are for generating 8-bit packets.

Definition at line 89 of file uart.h.

6.12.2.2 #define halUart0WriteByteTiny( x )

Goes straight to hardware, blocks until the UART is ready, and sets the UART transmit register to thepassed parameter for transmission.

Parametersx The byte to send out on the UART.

Definition at line 119 of file uart.h.


6.12.3.1 EmberStatus halUart0ReadByteTimeoutTiny ( int8u ∗ dataByte )

Goes straight to hardware and reads a byte from UART0.

Waits for the receive flag to become true, copies the received byte to the passed pointer’s location, andreturns with the UART’s error code.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

112

ParametersdataByte Pointer to where the read byte will end up.

Returns

Returns EMBER_SERIAL_RX_EMPTY if the read times out before any activity occurs on the serialline, within about 80 milliseconds. Otherwise the function returns an error code that corresponds tothe error bits for UART0 of an Atmel microcontroller.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

113

6.13 ADC Control

Macros

• #define NUM_ADC_USERS

Typedefs

• typedef int8u ADCChannelType• typedef int8u ADCReferenceType• typedef int8u ADCRateType

Enumerations

• enum ADCUser { ADC_USER_LQI, ADC_USER_APP, ADC_USER_APP2 }• enum { ADC_REF_AREF, ADC_REF_AVCC, ADC_REF_INT }• enum { ADC_CONVERSION_TIME_US_256 }• enum {

ADC_SOURCE_ADC0, ADC_SOURCE_ADC1, ADC_SOURCE_ADC2, ADC_SOURCE_AD-C3,ADC_SOURCE_ADC4, ADC_SOURCE_ADC5, ADC_SOURCE_ADC6, ADC_SOURCE_AD-C7 }

Functions

• void halInternalInitAdc (void)• void halInternalSleepAdc (void)• EmberStatus halStartAdcConversion (ADCUser id, ADCReferenceType reference, ADCChannel-

Type channel, ADCRateType rate)• EmberStatus halRequestAdcData (ADCUser id, int16u ∗value)• EmberStatus halReadAdcBlocking (ADCUser id, int16u ∗value)• EmberStatus halAdcCalibrate (ADCUser id)• int16s halConvertValueToVolts (int16u value)• void emberCalibrateVref (void)


Sample A/D converter driver.

See adc.h for source code.

Note

EM35x ADC driver support is preliminary and essentailly untested - please do not attempt to use thisADC driver on this platform.The EmberZNet stack does use these functions.

To use the ADC system, include this file and ensure that halInternalInitAdc() is called whenever the micro-controller is started. Call halInternalSleepAdc() to sleep the module and halInternalInitAdc() to wake upthe module.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

114

A "user" is a separate thread of execution and usage. That is, internal Ember code is one user and clientsare a different user. But a client that is calling the ADC in two different functions constitutes only one user,as long as the ADC access is not interleaved.

Note

This code does not allow access to the continuous reading mode of the ADC, which some clients mayrequire.

Many functions in this file return an EmberStatus value. See error-def.h for definitions of all EmberStatusreturn values.


6.13.2.1 #define NUM ADC USERS

Be sure to update NUM_ADC_USERS if additional users are added to the ADCUser list.

Definition at line 69 of file adc.h.


6.13.3.1 typedef int8u ADCChannelType

A type for the channel enumeration.


6.13.3.2 typedef int8u ADCReferenceType

A type for the reference voltage enumeration.


6.13.3.3 typedef int8u ADCRateType

A type for the sample rate enumeration.



6.13.4.1 enum ADCUser

ADC functions employ a user ID to keep different users separate.

Avoid many users because each user requires some amount of state storage.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

115

See Also

NUM_ADC_USERS

Enumerator:

ADC_USER_LQI LQI User ID.

ADC_USER_APP Application User ID

ADC_USER_APP2 Application User ID



ADCReferenceType enumeration for the AVR Atmega microcontrollers.

Enumerator:

ADC_REF_AREF AREF pin reference.

ADC_REF_AVCC AVCC pin reference.

ADC_REF_INT Internal reference.

Definition at line 24 of file avr-atmega/adc.h.


ADCRateType enumeration. Note: AVR only supports one rate: ADC_CONVERSION_TIME_US_256.

Enumerator:

ADC_CONVERSION_TIME_US_256 Internal reference.



Atmega single-ended ADC channel values for ADCChannelType.

Enumerator:

ADC_SOURCE_ADC0 Channel 0 : ADC0









EmberZNet 4.7.2 API EM260 120-3020-000-4720

116


6.13.5.1 void halInternalInitAdc ( void )

Initializes and powers-up the ADC. Should also be called to wake from sleep. The ADC is required forEM250 stack operation so this function must be called from halInit.

6.13.5.2 void halInternalSleepAdc ( void )

Shuts down the voltage reference and ADC system to minimize power consumption in sleep.

6.13.5.3 EmberStatus halStartAdcConversion ( ADCUser id, ADCReferenceType reference,ADCChannelType channel, ADCRateType rate )

Starts an ADC conversion for the user specified by id.

Application Usage:

The application must set reference to the voltage reference desired (see the ADC references enum,fixed at ADC_REF_INT for the em250), set channel to the channel number required (see the ADCchannel enum), and set rate to reflect the number of bits of accuracy desired (see the ADC ratesenum, fixed at ADC_CONVERSION_TIME_US_256 for the Atmega).

Parametersid An ADC user.

reference Voltage reference to use, chosen from enum ADCReferenceType (fixed at ADC_REF-_INT for the EM250).

channel Microprocessor channel number. For EM250 channels, see the EM250 ADC channelsenum. For basic, single-ended Atmel channels, see the Atmega single-ended ADCchannels enum. For more complex measurements on Atmels (differential and ampedchannel numbers), see the Atmel datasheet for your micro.

rate EM250 rate number (see the ADC EM250 rate enum). Fixed at ADC_CONVERSIO-N_TIME_US_256 for AVR Atmega.

Returns

One of the following:

• EMBER_ADC_CONVERSION_DEFERRED if the conversion is still waiting to start.

• EMBER_ADC_CONVERSION_BUSY if the conversion is currently taking place.

• EMBER_ERR_FATAL if a passed parameter is invalid.

6.13.5.4 EmberStatus halRequestAdcData ( ADCUser id, int16u ∗ value )

Returns the status of a pending conversion previously started by halStartAdcConversion(). If the conversionis complete, writes the raw register value of the conversion (the unaltered value taken directly from the A-DC’s data register) into value.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

117


value Pointer to an int16u to be loaded with the new value. Take note that the Atmel’s ADConly generates 8-bit values which are loaded into the lower 8 bits of value.

Returns


• EMBER_ADC_CONVERSION_DONE if the conversion is complete.

• EMBER_ADC_CONVERSION_DEFERRED if the conversion is still waiting to start.

• EMBER_ADC_CONVERSION_BUSY if the conversion is currently taking place.

• EMBER_ADC_NO_CONVERSION_PENDING if id does not have a pending conversion.

6.13.5.5 EmberStatus halReadAdcBlocking ( ADCUser id, int16u ∗ value )

Waits for the user’s request to complete and then, if a conversion was done, writes the raw register valueof the conversion (the unaltered value taken directly from the ADC’s data register) into value and returnsEMBER_ADC_CONVERSION_DONE, or immediately returns EMBER_ADC_NO_CONVERSION_P-ENDING.


value Pointer to an int16u to be loaded with the new value. Take note that the Atmel’s ADConly generates 8-bit values which are loaded into the lower 8 bits of value.

Returns


• EMBER_ADC_CONVERSION_DONE if the conversion is complete.

• EMBER_ADC_NO_CONVERSION_PENDING if id does not have a pending conversion.

6.13.5.6 EmberStatus halAdcCalibrate ( ADCUser id )

Calibrates or recalibrates the ADC system.

Application Usage:

Use this function to (re)calibrate as needed. This function is intended for the EM250 microcontroller,which requires proper calibration to calculate a human readible value (a value in volts). If the app doesnot call this function, the first time (and only the first time) the function halConvertValueToVolts() iscalled, this function is invoked. To maintain accurate volt calculations, the application should call thiswhenever it expects the temperature of the micro to change.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

118

Returns


• EMBER_ADC_CONVERSION_DONE if the calibration is complete.

• EMBER_ERR_FATAL if the calibration failed.

6.13.5.7 int16s halConvertValueToVolts ( int16u value )

Convert the raw register value (the unaltered value taken directly from the ADC’s data register) into asigned fixed point value with units 10∧-4 Volts. The returned value will be in the range -12000 to +12000(-1.2000 volts to +1.2000 volts).

Application Usage:

Use this function to get a human useful value.

Parametersvalue An int16u to be converted.

Returns

Volts as signed fixed point with units 10∧-4 Volts.

6.13.5.8 void emberCalibrateVref ( void )

Calibrates Vref to be 1.2V +/-10mV.

Application Usage:

This function must be called from halInternalInitAdc() before making ADC readings. This function isnot intended to be called from any function other than halInternalInitAdc(). This function ensures thatthe master cell voltage and current bias values are calibrated before calibrating Vref.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

119

6.14 Button Control

Functions

• void halInternalInitButton (void)• int8u halButtonState (int8u button)• int8u halButtonPinState (int8u button)• void halButtonIsr (int8u button, int8u state)

Button State Definitions

A set of numerical definitions for use with the button APIs indicating the state of a button.

• #define BUTTON_PRESSED• #define BUTTON_RELEASED


Sample API functions for using push-buttons. See button.h for source code.


6.14.2.1 #define BUTTON PRESSED

Button state is pressed.

Definition at line 24 of file button.h.

6.14.2.2 #define BUTTON RELEASED

Button state is released.

Definition at line 28 of file button.h.


6.14.3.1 void halInternalInitButton ( void )

Initializes the buttons. This function is automatically called by ::halInit().

6.14.3.2 int8u halButtonState ( int8u button )

Returns the current state (pressed or released) of a button.

Note

This function is correlated with halButtonIsr() and so returns the shadow state rather than reading theactual state of the pin.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

120

Parametersbutton The button being queried, either BUTTON0 or BUTTON1 as defined in the appropriate

BOARD_HEADER.

Returns

BUTTON_PRESSED if the button is pressed or BUTTON_RELEASED if the button is not pressed.

6.14.3.3 int8u halButtonPinState ( int8u button )

Returns the current state (pressed or released) of the pin associated with a button.

This reads the actual state of the pin and can be used on startup to determine the initial position of thebuttons.

Parametersbutton The button being queried, either BUTTON0 or BUTTON1 as defined in the appropriate

BOARD_HEADER.

Returns

BUTTON_PRESSED if the button is pressed or BUTTON_RELEASED if the button is not pressed.

6.14.3.4 void halButtonIsr ( int8u button, int8u state )

A callback called in interrupt context whenever a button changes its state.

Application Usage:

Must be implemented by the application. This function should contain the functionality to be executedin response to changes of state in each of the buttons, or callbacks to the appropriate functionality.

Parametersbutton The button which has changed state, either BUTTON0 or BUTTON1 as defined in the

appropriate BOARD_HEADER.state The new state of the button referenced by the button parameter, either BUTTON_PRE-

SSED if the button has been pressed or BUTTON_RELEASED if the button has beenreleased.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

121

6.15 Buzzer Control

Functions

• void halPlayTune_P (int8u PGM ∗tune, boolean bkg)• void halStackIndicatePresence (void)

Note Definitions

Flats are used instead of sharps because # is a special character.

• #define NOTE_C3• #define NOTE_Db3• #define NOTE_D3• #define NOTE_Eb3• #define NOTE_E3• #define NOTE_F3• #define NOTE_Gb3• #define NOTE_G3• #define NOTE_Ab3• #define NOTE_A3• #define NOTE_Bb3• #define NOTE_B3• #define NOTE_C4• #define NOTE_Db4• #define NOTE_D4• #define NOTE_Eb4• #define NOTE_E4• #define NOTE_F4• #define NOTE_Gb4• #define NOTE_G4• #define NOTE_Ab4• #define NOTE_A4• #define NOTE_Bb4• #define NOTE_B4• #define NOTE_C5• #define NOTE_Db5• #define NOTE_D5• #define NOTE_Eb5• #define NOTE_E5• #define NOTE_F5• #define NOTE_Gb5• #define NOTE_G5• #define NOTE_Ab5• #define NOTE_A5• #define NOTE_Bb5• #define NOTE_B5

EmberZNet 4.7.2 API EM260 120-3020-000-4720

122


Sample API functions for playing tunes on a piezo buzzer. See buzzer.h for source code.


6.15.2.1 #define NOTE C3

A note which can be used in tune structure definitions.

Definition at line 23 of file buzzer.h.

6.15.2.2 #define NOTE Db3



6.15.2.3 #define NOTE D3



6.15.2.4 #define NOTE Eb3



6.15.2.5 #define NOTE E3



6.15.2.6 #define NOTE F3



6.15.2.7 #define NOTE Gb3



6.15.2.8 #define NOTE G3


EmberZNet 4.7.2 API EM260 120-3020-000-4720

123


6.15.2.9 #define NOTE Ab3



6.15.2.10 #define NOTE A3



6.15.2.11 #define NOTE Bb3



6.15.2.12 #define NOTE B3















EmberZNet 4.7.2 API EM260 120-3020-000-4720

124




























EmberZNet 4.7.2 API EM260 120-3020-000-4720

125




























EmberZNet 4.7.2 API EM260 120-3020-000-4720

126








6.15.3.1 void halPlayTune P ( int8u PGM ∗ tune, boolean bkg )

Plays a tune on the piezo buzzer.

The tune is played in the background if ::bkg is TRUE. Otherwise, the API blocks until the playback of thetune is complete.

Parameterstune A pointer to tune to play.bkg Determines whether the tune plays in the background. If TRUE, tune plays in back-

ground; if FALSE, tune plays in foreground.

A tune is implemented as follows:

int8u PGM hereIamTune[] = { //All tunes are stored in flash.NOTE_B4, 1, //Plays the note B4 for 100 milliseconds.0, 1, //Pause for 100 milliseconds.NOTE_B5, 5, //Plays the note B5 for 500 milliseconds.0, 0 //NULL terminates the tune.

};

6.15.3.2 void halStackIndicatePresence ( void )

Causes something to happen on a node (such as playing a tune on the buzzer) that can be used to indicatewhere it physically is.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

127

6.16 LED Control

Typedefs

• typedef enum HalBoardLedPins HalBoardLed

Functions

• void halInternalInitLed (void)• void halToggleLed (HalBoardLed led)• void halSetLed (HalBoardLed led)• void halClearLed (HalBoardLed led)• void halStackIndicateActivity (boolean turnOn)


Sample API funtions for controlling LEDs. When specifying an LED to use, always use the BOARDLEDxdefinitions that are defined within the BOARD_HEADER.

See led.h for source code.


6.16.2.1 typedef enum HalBoardLedPins HalBoardLed

Ensures that the definitions from the BOARD_HEADER are always used as parameters to the LED func-tions.

Definition at line 30 of file led.h.


6.16.3.1 void halInternalInitLed ( void )

Configures GPIOs pertaining to the control of LEDs.

6.16.3.2 void halToggleLed ( HalBoardLed led )

Atomically wraps an XOR or similar operation for a single GPIO pin attached to an LED.

Parametersled Identifier (from BOARD_HEADER) for the LED to be toggled.

6.16.3.3 void halSetLed ( HalBoardLed led )

Turns on (sets) a GPIO pin connected to an LED so that the LED turns on.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

128

Parametersled Identifier (from BOARD_HEADER) for the LED to turn on.

6.16.3.4 void halClearLed ( HalBoardLed led )

Turns off (clears) a GPIO pin connected to an LED, which turns off the LED.

Parametersled Identifier (from BOARD_HEADER) for the LED to turn off.

6.16.3.5 void halStackIndicateActivity ( boolean turnOn )

Called by the stack to indicate activity over the radio (for both transmission and reception). It is called oncewith turnOn TRUE and shortly thereafter with turnOn FALSE.

Typically does something interesting, such as change the state of an LED.

ParametersturnOn See Usage.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

129

6.17 Carrier Board Control

Macros

• #define halInternalInitBoard()• #define halInternalPowerDownBoard()• #define halInternalPowerUpBoard()• #define BUTTON0• #define BUTTON1• #define TEMP_SENSOR_ADC_CHANNEL• #define TEMP_SENSOR_SCALE_FACTOR

Enumerations

• enum HalBoardLedPins {BOARDLED0, BOARDLED1, BOARDLED2, BOARDLED3,BOARDLED4, BOARDLED5, BOARD_ACTIVITY_LED, BOARD_HEARTBEAT_LED,BOARDLED0, BOARDLED1, BOARD_ACTIVITY_LED, BOARD_HEARTBEAT_LED,BOARDLED0, BOARDLED1, BOARD_ACTIVITY_LED, BOARD_HEARTBEAT_LED }

SPI Protocol Parameters

The following are used to aid in the abstraction with the SPI Protocol. The HAL uses these definitions soit is able to work across a variety of speeds as well as allow the developer to tweak parameters as desired.

The values used here are based upon an ATmega32L Host operating at 3.6864MHz which generates a17.361us tick.

• #define TCCR1B_CONFIGURATION• #define WAIT_SECTION_TIMEOUT• #define INTER_COMMAND_SPACING• #define WAKE_HANDSHAKE_TIMEOUT• #define STARTUP_TIMEOUT_SINGLE• #define STARTUP_TIMEOUT_COUNT

SPI Protocol Connection Items

The following are used to aid in the abstraction with the SPI Protocol. The HAL uses these definitionsso it is able to work across a variety of boards which could have different connections. The names andports/pins used below are intended to match with a schematic of the system to provide the abstraction.

• #define SPIP_nSSEL_PORT• #define SPIP_nSSEL_DDR• #define SPIP_nSSEL• #define SPIP_MOSI_PORT• #define SPIP_MOSI_DDR• #define SPIP_MOSI• #define SPIP_MISO_PORT• #define SPIP_MISO_DDR• #define SPIP_MISO

EmberZNet 4.7.2 API EM260 120-3020-000-4720

130

• #define SPIP_SCLK_PORT• #define SPIP_SCLK_DDR• #define SPIP_SCLK• #define SPIP_nHOST_INT_PORT• #define SPIP_nHOST_INT_DDR• #define SPIP_nHOST_INT_PIN• #define SPIP_nHOST_INT• #define SPIP_nWAKE_PORT• #define SPIP_nWAKE_DDR• #define SPIP_nWAKE• #define SPIP_nRESET_PORT• #define SPIP_nRESET_DDR• #define SPIP_nRESET

LED Definitions

The following are used to aid in the abstraction with the LED connections. The names and ports/pins usedbelow are intended to match with a schematic of the system to provide the abstraction.

The BOARDLEDn macros should always be used when manipulating the state of LEDs.

BOARDLED_MASK should be set to a mask with a bit set for each pin to an LED is connected


• #define BOARDLED_MASK• #define LED_DDR• #define LED_PORT

Button Definitions

The following are used to aid in the abstraction with the Button connections. The names and ports/pinsused below are intended to match with a schematic of the system to provide the abstraction.

The BUTTONn macros should always be used with manipulating the buttons as they directly refer to thepins to which the buttons are connected.

• #define BUTTON0• #define BUTTON0_PORT• #define BUTTON0_DDR• #define BUTTON0_PIN• #define BUTTON0_INT• #define BUTTON0_INT_VECT• #define BUTTON0_CONFIG_FALLING_EDGE()• #define BUTTON0_CONFIG_RISING_EDGE()• #define BUTTON1• #define BUTTON1_PORT• #define BUTTON1_DDR

EmberZNet 4.7.2 API EM260 120-3020-000-4720

131

• #define BUTTON1_PIN• #define BUTTON1_INT• #define BUTTON1_INT_VECT• #define BUTTON1_CONFIG_FALLING_EDGE()• #define BUTTON1_CONFIG_RISING_EDGE()

Temperature sensor ADC channel

Define the analog input channel connected to the LM-20 temperature sensor. The scale factor compensatesfor different platform input ranges. PA0/ADC0 must be an input. PA1 must be an output and set to a highlevel to power the sensor.

• #define TEMP_SENSOR_ADC_CHANNEL• #define TEMP_SENSOR_SCALE_FACTOR

Board Specific Functions

The following macros exist to aid in the initialization, power up from sleep, and power down to sleepoperations. These macros are responsible for either initializing directly, or calling initialization functionsfor any peripherals that are specific to this board implementation. These macros are called from halInit,halPowerDown, and halPowerUp respectively.

• #define halInternalInitBoard()• #define halInternalPowerDownBoard()• #define halInternalPowerUpBoard()



The values used here are based upon an ATmega128L Host operating at 8MHz which generates a 32ustick.




• #define SPIP_nSSEL_PORT• #define SPIP_nSSEL_DDR

EmberZNet 4.7.2 API EM260 120-3020-000-4720

132

• #define SPIP_nSSEL• #define SPIP_MOSI_PORT• #define SPIP_MOSI_DDR• #define SPIP_MOSI• #define SPIP_MISO_PORT• #define SPIP_MISO_DDR• #define SPIP_MISO• #define SPIP_SCLK_PORT• #define SPIP_SCLK_DDR• #define SPIP_SCLK• #define SPIP_nHOST_INT_PORT• #define SPIP_nHOST_INT_DDR• #define SPIP_nHOST_INT_PIN• #define SPIP_nHOST_INT• #define SPIP_nWAKE_PORT• #define SPIP_nWAKE_DDR• #define SPIP_nWAKE• #define SPIP_nRESET_PORT• #define SPIP_nRESET_DDR• #define SPIP_nRESET

LED Definitions

The following are used to aid in the abstraction with the LED connections. The microcontroller-specificsources use these definitions so they are able to work across a variety of boards which could have differentconnections. The names and ports/pins used below are intended to match with a schematic of the systemto provide the abstraction.

The BOARDLEDn enum values should always be used when manipulating the state of LEDs, as theydirectly refer to the pins to which the LEDs are connected



• #define BOARDLED_MASK• #define LED_DDR• #define LED_PORT

Button Definitions



• #define BUTTON0• #define BUTTON0_PORT

EmberZNet 4.7.2 API EM260 120-3020-000-4720

133

• #define BUTTON0_DDR• #define BUTTON0_PIN• #define BUTTON0_INT• #define BUTTON0_INT_VECT• #define BUTTON0_CONFIG_FALLING_EDGE()• #define BUTTON0_CONFIG_RISING_EDGE()• #define BUTTON1• #define BUTTON1_PORT• #define BUTTON1_DDR• #define BUTTON1_PIN• #define BUTTON1_INT• #define BUTTON1_INT_VECT• #define BUTTON1_CONFIG_FALLING_EDGE()• #define BUTTON1_CONFIG_RISING_EDGE()


Define the analog input channel connected to the LM-20 temperature sensor. The scale factor compensatesfor different platform input ranges. PF1/ADC1 must be an input. PC7 must be an output and set to a highlevel to power the sensor.






See host.h for source code.

See also dev0470.h for the code.

See also dev0473.h for the code.


6.17.2.1 #define halInternalInitBoard( )

Definition at line 16 of file host.h.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

134

6.17.2.2 #define halInternalPowerDownBoard( )


6.17.2.3 #define halInternalPowerUpBoard( )


6.17.2.4 #define BUTTON0




6.17.2.6 #define TEMP SENSOR ADC CHANNEL


6.17.2.7 #define TEMP SENSOR SCALE FACTOR


6.17.2.8 #define TCCR1B CONFIGURATION

Definition at line 38 of file dev0470.h.

6.17.2.9 #define WAIT SECTION TIMEOUT


6.17.2.10 #define INTER COMMAND SPACING


6.17.2.11 #define WAKE HANDSHAKE TIMEOUT


6.17.2.12 #define STARTUP TIMEOUT SINGLE


EmberZNet 4.7.2 API EM260 120-3020-000-4720

135

6.17.2.13 #define STARTUP TIMEOUT COUNT


6.17.2.14 #define SPIP nSSEL PORT


6.17.2.15 #define SPIP nSSEL DDR


6.17.2.16 #define SPIP nSSEL


6.17.2.17 #define SPIP MOSI PORT


6.17.2.18 #define SPIP MOSI DDR


6.17.2.19 #define SPIP MOSI


6.17.2.20 #define SPIP MISO PORT


6.17.2.21 #define SPIP MISO DDR


6.17.2.22 #define SPIP MISO


6.17.2.23 #define SPIP SCLK PORT


EmberZNet 4.7.2 API EM260 120-3020-000-4720

136

6.17.2.24 #define SPIP SCLK DDR


6.17.2.25 #define SPIP SCLK


6.17.2.26 #define SPIP nHOST INT PORT


6.17.2.27 #define SPIP nHOST INT DDR


6.17.2.28 #define SPIP nHOST INT PIN


6.17.2.29 #define SPIP nHOST INT


6.17.2.30 #define SPIP nWAKE PORT


6.17.2.31 #define SPIP nWAKE DDR


6.17.2.32 #define SPIP nWAKE


6.17.2.33 #define SPIP nRESET PORT


6.17.2.34 #define SPIP nRESET DDR


EmberZNet 4.7.2 API EM260 120-3020-000-4720

137

6.17.2.35 #define SPIP nRESET


6.17.2.36 #define BOARDLED MASK


6.17.2.37 #define LED DDR


6.17.2.38 #define LED PORT




6.17.2.40 #define BUTTON0 PORT


6.17.2.41 #define BUTTON0 DDR


6.17.2.42 #define BUTTON0 PIN


6.17.2.43 #define BUTTON0 INT


6.17.2.44 #define BUTTON0 INT VECT


6.17.2.45 #define BUTTON0 CONFIG FALLING EDGE( )


EmberZNet 4.7.2 API EM260 120-3020-000-4720

138

6.17.2.46 #define BUTTON0 CONFIG RISING EDGE( )






















EmberZNet 4.7.2 API EM260 120-3020-000-4720

139







6.17.2.60 #define TCCR1B CONFIGURATION


6.17.2.61 #define WAIT SECTION TIMEOUT


6.17.2.62 #define INTER COMMAND SPACING


6.17.2.63 #define WAKE HANDSHAKE TIMEOUT


6.17.2.64 #define STARTUP TIMEOUT SINGLE


6.17.2.65 #define STARTUP TIMEOUT COUNT


6.17.2.66 #define SPIP nSSEL PORT


6.17.2.67 #define SPIP nSSEL DDR


EmberZNet 4.7.2 API EM260 120-3020-000-4720

140

6.17.2.68 #define SPIP nSSEL


6.17.2.69 #define SPIP MOSI PORT


6.17.2.70 #define SPIP MOSI DDR


6.17.2.71 #define SPIP MOSI


6.17.2.72 #define SPIP MISO PORT


6.17.2.73 #define SPIP MISO DDR


6.17.2.74 #define SPIP MISO


6.17.2.75 #define SPIP SCLK PORT


6.17.2.76 #define SPIP SCLK DDR


6.17.2.77 #define SPIP SCLK


6.17.2.78 #define SPIP nHOST INT PORT


EmberZNet 4.7.2 API EM260 120-3020-000-4720

141

6.17.2.79 #define SPIP nHOST INT DDR


6.17.2.80 #define SPIP nHOST INT PIN


6.17.2.81 #define SPIP nHOST INT


6.17.2.82 #define SPIP nWAKE PORT


6.17.2.83 #define SPIP nWAKE DDR


6.17.2.84 #define SPIP nWAKE


6.17.2.85 #define SPIP nRESET PORT


6.17.2.86 #define SPIP nRESET DDR


6.17.2.87 #define SPIP nRESET


6.17.2.88 #define BOARDLED MASK


6.17.2.89 #define LED DDR


EmberZNet 4.7.2 API EM260 120-3020-000-4720

142

6.17.2.90 #define LED PORT






















EmberZNet 4.7.2 API EM260 120-3020-000-4720

143























EmberZNet 4.7.2 API EM260 120-3020-000-4720

144


6.17.3.1 enum HalBoardLedPins

Enumerator:

BOARDLED0BOARDLED1BOARDLED2BOARDLED3BOARDLED4BOARDLED5BOARD_ACTIVITY_LEDBOARD_HEARTBEAT_LEDBOARDLED0BOARDLED1BOARD_ACTIVITY_LEDBOARD_HEARTBEAT_LEDBOARDLED0BOARDLED1BOARD_ACTIVITY_LEDBOARD_HEARTBEAT_LED



Enumerator:



EmberZNet 4.7.2 API EM260 120-3020-000-4720

145


Enumerator:



EmberZNet 4.7.2 API EM260 120-3020-000-4720

146

6.18 SPI Access

Functions

• void halCommonInitSpi (void)• void halCommonSpiWrite (int8u data)• int8u halCommonSpiRead (void)• int8u halCommonSpiReadWrite (int8u data)

SPI Protocol Interface

• int8u ∗ halNcpFrame• int8u halNcpSpipErrorByte• void halNcpSerialInit (void)• void halNcpSerialPowerup (void)• void halNcpSerialPowerdown (void)• EzspStatus halNcpHardReset (void)• EzspStatus halNcpHardResetReqBootload (boolean requestBootload)• void halNcpWakeUp (void)• void halNcpSendCommand (void)• void halNcpSendRawCommand (void)• EzspStatus halNcpPollForResponse (void)• void halNcpIsAwakeIsr (boolean isAwake)• boolean halNcpHasData (void)• boolean halNcpVerifySpiProtocolVersion (void)• boolean halNcpVerifySpiProtocolActive (void)

SPI Protocol Test Function

• void spipTest (int16u test, int16u params)


This file contains the prototypes and defines for direct SPI access. These functions are generic.

See spi.h for source code.

These functions are suitable for use by any module, but are entirely dependant upon appropriate sharing ofthe SPI bus through chip selects and hold lines.


See also spi-protocol.h for source code.

For complete documentation of the SPI Protocol, refer to the EM260 Datasheet.


6.18.2.1 void halCommonInitSpi ( void )

Configures the relavent pins and initializes the USART0 module for operation at 8-bits, master mode,3-pin, maximum speed (2MHz).

EmberZNet 4.7.2 API EM260 120-3020-000-4720

147

6.18.2.2 void halCommonSpiWrite ( int8u data )

Writes a byte over the SPI.

Parametersdata The byte to be sent out over the SPI.

6.18.2.3 int8u halCommonSpiRead ( void )

Reads a byte over the SPI without changing the mode.

Returns

The byte read.

6.18.2.4 int8u halCommonSpiReadWrite ( int8u data )

Reads and writes a byte over the SPI.

Parametersdata The byte to be sent out over the SPI.

Returns

The byte read.

6.18.2.5 void halNcpSerialInit ( void )

Initializes the SPI Protocol.

6.18.2.6 void halNcpSerialPowerup ( void )

Reinitializes the SPI Protocol when coming out of sleep (powerdown).

6.18.2.7 void halNcpSerialPowerdown ( void )

Shuts down the SPI Protocol when entering sleep (powerdown).

6.18.2.8 EzspStatus halNcpHardReset ( void )

Forcefully resets the EM260 by pulling on the nRESET line; waits for the EM260 to boot; verifies that ishas booted; verifies the EM260 is active; verifies the SPI Protocol version. When this function returns, theEM260 is ready to accept all commands.

This function is the same as halNcpHardResetReqBootload(), except that the EM260 cannot be told toenter bootload mode through the nWAKE signal.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

148

Returns

A EzspStatus value indicating the success or failure of the command.

6.18.2.9 EzspStatus halNcpHardResetReqBootload ( boolean requestBootload )

Forcefully resets the EM260 by pulling on the nRESET line; sets the nWAKE signal based upon the stateof the requestBootload boolean; waits for the EM260 to boot; verifies that is has booted; verifies the E-M260 is active; verifies the SPI Protocol version. When this function returns, the EM260 is ready to acceptall commands.

This function is the same as halNcpHardReset(), except that the ability to request the EM260 enter bootloadmode through the nWAKE signal is made available.

Returns


6.18.2.10 void halNcpWakeUp ( void )

If the Host thinks that the EM260 is sleeping and wants to wake it up, the EZSP calls halNcpWakeUp().

Waking up can take some time (milliseconds) so halNcpWakeUp() returns immediately and the SPI Proto-col calls halNcpIsAwakeIsr() once the wakeup handshaking is complete and the EM260 is ready to acceptcommands.

6.18.2.11 void halNcpSendCommand ( void )

The EZSP writes a command into the command buffer and then calls halNcpSendCommand().

This function assumes the command being sent is an EZSP frame and therefore sets the SPI Byte for anEZSP Frame. If sending a command other than EZSP, use halNcpSendRawCommand(). This functionreturns immediately after transmission of the Command has completed and the transaction has entered theWait section. The EZSP must now call halNcpPollForResponse() until the Response is received.

6.18.2.12 void halNcpSendRawCommand ( void )

The upper layer writes a command into the command buffer and then calls halNcpSendRawCommand().

This function makes no assumption about the data in the SpipBuffer, it will just faithly try to perform thetransaction. This function returns immediately after transmission of the Command has completed and thetransaction has entered the Wait section. The upper layer must now call halNcpPollForResponse() until thethe Response is received.

6.18.2.13 EzspStatus halNcpPollForResponse ( void )

After sending a Command with halNcpSendCommand(), the upper layer repeatedly calls this function untilthe SPI Protocol has finished reception of a Response.

Returns


EmberZNet 4.7.2 API EM260 120-3020-000-4720

149

6.18.2.14 void halNcpIsAwakeIsr ( boolean isAwake )

The SPI Protocol calls halNcpIsAwakeIsr() once the wakeup handshaking is complete and the EM260 isready to accept a command.

ParametersisAwake TRUE if the wake handshake completed and the EM260 is awake. FALSE is the wake

handshake failed and the EM260 is unresponsive.

6.18.2.15 boolean halNcpHasData ( void )

If the Host wants to find out whether the EM260 has a pending callback, the EZSP calls halNcpHasData().If this function returns TRUE then the EZSP will send a callback command.

6.18.2.16 boolean halNcpVerifySpiProtocolVersion ( void )

Transmits the SPI Protocol Version Command and checks the response against a literal value to verify theSPI Protocol version.

Returns

TRUE if the SPI Protocol Version used in this function matches the version returned by the EM260.FALSE is the versions do not match.

6.18.2.17 boolean halNcpVerifySpiProtocolActive ( void )

Transmits the SPI Status Command and checks the response against a literal value to verify the SPI Protocolis active.

Returns

TRUE if the SPI Protocol is active. FALSE if the SPI Protocol is not active.

6.18.2.18 void spipTest ( int16u test, int16u params )

A collection of code for use in testing pieces of the SPI Protocol.

The tests available here undocumented and unused by a formal application. They can be called from anytest application or used as inspiration or a template for further testing. To invoke a test, simply call spip-Test() with the desired parameters. (For example, this function can be accessed through a user driveninterface to provide a convenient method for invoking a test or set of tests.)

Parameterstest The number provided here invokes a specific piece of the test code. For example, ’1’

loads the Command buffer with the SPI Protocol Version Commmand and ’0’ initiatesa transaction with whatever data is in buffer.

params The parameters passed into a given test. For example, test ’A’ simply write a byte onthe SPI. The byte written is provided by params.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

150


6.18.3.1 int8u∗ halNcpFrame

A pointer to the length byte at the start of the Payload. Upper layers will write the command to this locationbefore starting a transaction. The upper layer will read the response from this location after a transactioncompletes. This pointer is the upper layers’ primary access into the command/response buffer.

6.18.3.2 int8u halNcpSpipErrorByte

This error byte is the third byte found in a special SPI Protocol error case. It provides more detail concern-ing the error. Refer to the EM260 Datasheet for a more detailed description of this byte. The applicationdoes not need to work with this byte, but it can be useful information when developing.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

151

6.19 System Timer Control

Macros

• #define halIdleForMilliseconds(duration)

Functions

• int16u halInternalStartSystemTimer (void)• int16u halCommonGetInt16uMillisecondTick (void)• int32u halCommonGetInt32uMillisecondTick (void)• int16u halCommonGetInt16uQuarterSecondTick (void)• EmberStatus halSleepForQuarterSeconds (int32u ∗duration)• EmberStatus halSleepForMilliseconds (int32u ∗duration)• EmberStatus halCommonIdleForMilliseconds (int32u ∗duration)• void halCommonSetSystemTime (int32u time)


Functions that provide access to the system clock. A single system tick (as returned by halCommonGet-Int16uMillisecondTick() and halCommonGetInt32uMillisecondTick() ) is approximately 1 millisecond.

• When used with a 32.768kHz crystal, the system tick is 0.976 milliseconds.

• When used with a 3.6864MHz crystal, the system tick is 1.111 milliseconds.

A single quarter-second tick (as returned by halCommonGetInt16uQuarterSecondTick() ) is approximately0.25 seconds.

The values used by the time support functions will wrap after an interval. The length of the interval dependson the length of the tick and the number of bits in the value. However, there is no issue when comparingtime deltas of less than half this interval with a subtraction, if all data types are the same.

See system-timer.h for source code.

See also 32/system-timer.c for source code.

See also 128/system-timer.c for source code.


6.19.2.1 #define halIdleForMilliseconds( duration )

Definition at line 203 of file system-timer.h.


6.19.3.1 int16u halInternalStartSystemTimer ( void )

Initializes the system tick.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

152

Returns

Time to update the async registers after RTC is started (units of 100 microseconds).

6.19.3.2 int16u halCommonGetInt16uMillisecondTick ( void )

Returns the current system time in system ticks, as a 16-bit value.

Returns

The least significant 16 bits of the current system time, in system ticks.

6.19.3.3 int32u halCommonGetInt32uMillisecondTick ( void )

Returns the current system time in system ticks, as a 32-bit value.

EmberStack Usage:

Unused, implementation optional.

Returns

The least significant 32 bits of the current system time, in system ticks.

6.19.3.4 int16u halCommonGetInt16uQuarterSecondTick ( void )

Returns the current system time in quarter second ticks, as a 16-bit value.

EmberStack Usage:


Returns

The least significant 16 bits of the current system time, in system ticks multiplied by 256.

6.19.3.5 EmberStatus halSleepForQuarterSeconds ( int32u ∗ duration )

Uses the system timer to enter ::SLEEPMODE_WAKETIMER for approximately the specified amount oftime (provided in quarter seconds).

This function returns EMBER_SUCCESS and the duration parameter is decremented to 0 after sleepingfor the specified amount of time. If an interrupt occurs that brings the chip out of sleep, the function returnsEMBER_SLEEP_INTERRUPTED and the duration parameter reports the amount of time remaining outof the original request.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

153

Note

This routine always enables interrupts.The maximum sleep time of the hardware is limited on AVR-based platforms to 8 seconds, on EM2-XX-based platforms to 64 seconds, and on EM35x platforms to 48.5 days. Any sleep duration greaterthan this limit will wake up briefly (e.g. 16 microseconds) to reenable another sleep cycle.

The EM2xx has a 16 bit sleep timer, which normally runs at 1024Hz. In order to support long sleepdurations, the chip will periodically wake up to manage a larger timer in software. This periodic wakeupis normally triggered once every 32 seconds. However, this period can be extended to once every 2.275hours by building with ENABLE_LONG_SLEEP_CYCLES defined. This definition enables the useof a prescaler when sleeping for more than 63 seconds at a time. However, this define also imposes thefollowing limitations:

1. The chip may only wake up from the sleep timer. (External GPIO wake events may not be used)

2. Each time a sleep cycle is performed, a loss of accuracy up to +/-750ms will be observed in thesystem timer.

EmberStack Usage:


Parametersduration The amount of time, expressed in quarter seconds, that the micro should be placed into

::SLEEPMODE_WAKETIMER. When the function returns, this parameter providesthe amount of time remaining out of the original sleep time request (normally the returnvalue will be 0).

Returns

An EmberStatus value indicating the success or failure of the command.

6.19.3.6 EmberStatus halSleepForMilliseconds ( int32u ∗ duration )

Uses the system timer to enter ::SLEEPMODE_WAKETIMER for approximately the specified amount oftime (provided in milliseconds). Note that since the system timer ticks at a rate of 1024Hz, a second iscomprised of 1024 milliseconds in this function.

This function returns EMBER_SUCCESS and the duration parameter is decremented to 0 after sleepingfor the specified amount of time. If an interrupt occurs that brings the chip out of sleep, the function returnsEMBER_SLEEP_INTERRUPTED and the duration parameter reports the amount of time remaining outof the original request.

Note

This routine always enables interrupts.This function is not implemented on AVR-based platforms.Sleep durations less than 3 milliseconds are not allowed on on EM2XX-based platforms. Any attemptto sleep for less than 3 milliseconds on EM2XX-based platforms will cause the function to immediatelyexit without sleeping and return EMBER_SLEEP_INTERRUPTED.The maximum sleep time of the hardware is limited on EM2XX-based platforms to 32 seconds. Anysleep duration greater than this limit will wake up briefly (e.g. 16 microseconds) to reenable another

EmberZNet 4.7.2 API EM260 120-3020-000-4720

154

sleep cycle. Due to this limitation, this function should not be used with durations within 3 millisec-onds of a multiple 32 seconds. The short sleep cycle that results from such durations is not handledreliably by the system timer on EM2XX-based platforms. If a sleep duration within 3 milliseconds ofa multiple of 32 seconds is desired, halSleepForQuarterSeconds should be used.

EmberStack Usage:


Parametersduration The amount of time, expressed in milliseconds (1024 milliseconds = 1 second), that

the micro should be placed into ::SLEEPMODE_WAKETIMER. When the functionreturns, this parameter provides the amount of time remaining out of the original sleeptime request (normally the return value will be 0).

Returns


6.19.3.7 EmberStatus halCommonIdleForMilliseconds ( int32u ∗ duration )

Uses the system timer to enter ::SLEEPMODE_IDLE for approximately the specified amount of time(provided in milliseconds).

This function returns EMBER_SUCCESS and the duration parameter is decremented to 0 after idling forthe specified amount of time. If an interrupt occurs that brings the chip out of idle, the function returnsEMBER_SLEEP_INTERRUPTED and the duration parameter reports the amount of time remaining outof the original request.

Note

This routine always enables interrupts.

EmberStack Usage:


Parametersduration The amount of time, expressed in milliseconds, that the micro should be placed into

::SLEEPMODE_IDLE. When the function returns, this parameter provides the amountof time remaining out of the original idle time request (normally the return value willbe 0).

Returns


EmberZNet 4.7.2 API EM260 120-3020-000-4720

155

6.19.3.8 void halCommonSetSystemTime ( int32u time )

Set the current system time.

Parameterstime A 32 bit value, expressed in milliseconds, that will become the current system time.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

156

6.20 HAL Utilities

Modules

• Cyclic Redundancy Code (CRC)• Random Number Generation


EmberZNet 4.7.2 API EM260 120-3020-000-4720

157

6.21 Cyclic Redundancy Code (CRC)

Macros

• #define INITIAL_CRC• #define CRC32_START• #define CRC32_END

Functions

• int16u halCommonCrc16 (int8u newByte, int16u prevResult)• int32u halCommonCrc32 (int8u newByte, int32u prevResult)


Functions that provide access to cyclic redundancy code (CRC) calculation. See crc.h for source code.


6.21.2.1 #define INITIAL CRC

Definition at line 49 of file crc.h.

6.21.2.2 #define CRC32 START


6.21.2.3 #define CRC32 END



6.21.3.1 int16u halCommonCrc16 ( int8u newByte, int16u prevResult )

Calculates 16-bit cyclic redundancy code (CITT CRC 16).

Applies the standard CITT CRC 16 polynomial to a single byte. It should support being called first withan initial value, then repeatedly until all data is processed.

ParametersnewByte The new byte to be run through CRC.

prevResult The previous CRC result.

Returns

The new CRC result.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

158

6.21.3.2 int32u halCommonCrc32 ( int8u newByte, int32u prevResult )

Calculates 32-bit cyclic redundancy code.

Note

On some radios or micros, the CRC for error detection on packet data is calculated in hardware.

Applies a CRC32 polynomial to a single byte. It should support being called first with an initial value, thenrepeatedly until all data is processed.

ParametersnewByte The new byte to be run through CRC.

prevResult The previous CRC result.

Returns

The new CRC result.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

159

6.22 Random Number Generation

Functions

• void halStackSeedRandom (int32u seed)• int16u halCommonGetRandom (void)


Functions that provide access to random numbers. These functions may be hardware accelerated, thoughoften are not.

See random.h for source code.


6.22.2.1 void halStackSeedRandom ( int32u seed )

Seeds the halCommonGetRandom() pseudorandom number generator.

Called by the stack during initialization with a seed from the radio.

Parametersseed A seed for the pseudorandom number generator.

6.22.2.2 int16u halCommonGetRandom ( void )

Runs a standard LFSR to generate pseudorandom numbers.

Called by the MAC in the stack to choose random backoff slots.

Complicated implementations may improve the MAC’s ability to avoid collisions in large networks, but itis critical to implement this function to return quickly.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

160

6.23 Asynchronous Serial Host (ASH) Framework

Macros

• #define ashStopAckTimer(void)• #define ashAckTimerIsRunning()• #define ashAckTimerIsNotRunning()• #define ashSetAckPeriod(msec)• #define ashGetAckPeriod()• #define ashSetAndStartAckTimer(msec)• #define ASH_NR_TIMER_BIT• #define ashStopNrTimer()• #define ashNrTimerIsNotRunning()• #define ASH_VERSION• #define ASH_FLAG• #define ASH_ESC• #define ASH_XON• #define ASH_XOFF• #define ASH_SUB• #define ASH_CAN• #define ASH_WAKE• #define ASH_FLIP• #define ASH_MIN_DATA_FIELD_LEN• #define ASH_MAX_DATA_FIELD_LEN• #define ASH_MIN_DATA_FRAME_LEN• #define ASH_MIN_FRAME_LEN• #define ASH_MAX_FRAME_LEN• #define ASH_CRC_LEN• #define ASH_MIN_FRAME_WITH_CRC_LEN• #define ASH_MAX_FRAME_WITH_CRC_LEN• #define ASH_NCP_SHFRAME_RX_LEN• #define ASH_NCP_SHFRAME_TX_LEN• #define ASH_HOST_SHFRAME_RX_LEN• #define ASH_HOST_SHFRAME_TX_LEN• #define ASH_DFRAME_MASK• #define ASH_CONTROL_DATA• #define ASH_SHFRAME_MASK• #define ASH_CONTROL_ACK• #define ASH_CONTROL_NAK• #define ASH_CONTROL_RST• #define ASH_CONTROL_RSTACK• #define ASH_CONTROL_ERROR• #define ASH_ACKNUM_MASK• #define ASH_ACKNUM_BIT• #define ASH_RFLAG_MASK• #define ASH_RFLAG_BIT• #define ASH_NFLAG_MASK• #define ASH_NFLAG_BIT• #define ASH_PFLAG_MASK• #define ASH_PFLAG_BIT

EmberZNet 4.7.2 API EM260 120-3020-000-4720

161

• #define ASH_FRMNUM_MASK• #define ASH_FRMNUM_BIT• #define ASH_GET_RFLAG(ctl)• #define ASH_GET_NFLAG(ctl)• #define ASH_GET_FRMNUM(ctl)• #define ASH_GET_ACKNUM(ctl)• #define ASH_FRAME_LEN_DATA_MIN• #define ASH_FRAME_LEN_ACK• #define ASH_FRAME_LEN_NAK• #define ASH_FRAME_LEN_RST• #define ASH_FRAME_LEN_RSTACK• #define ASH_FRAME_LEN_ERROR• #define MOD8(n)• #define INC8(n)• #define WITHIN_RANGE(lo, n, hi)

Functions

• int8u ashEncodeByte (int8u len, int8u byte, int8u ∗offset)• EzspStatus ashDecodeByte (int8u byte, int8u ∗out, int8u ∗outLen)• int8u ashRandomizeArray (int8u seed, int8u ∗buf, int8u len)• void ashStartAckTimer (void)• boolean ashAckTimerHasExpired (void)• void ashAdjustAckPeriod (boolean expired)• void ashStartNrTimer (void)• boolean ashNrTimerHasExpired (void)

Variables

• boolean ashDecodeInProgress• int16u ashAckTimer• int16u ashAckPeriod• int8u ashNrTimer


Use the Asynchronous Serial Host (ASH) Framework interfaces on a host microcontroller when it commu-nicates with an Ember chip via EZSP-UART.

See ash-common.h for source code.

See ash-protocol.h for source code.


6.23.2.1 void ashStopAckTimer( void )

Stops and clears ashAckTimer.

Definition at line 98 of file ash-common.h.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

162

6.23.2.2 #define ashAckTimerIsRunning( )

Indicates whether or not ashAckTimer is currently running. The timer may be running even if expired.


6.23.2.3 #define ashAckTimerIsNotRunning( )

Indicates whether or not ashAckTimer is currently running. The timer may be running even if expired.


6.23.2.4 #define ashSetAckPeriod( msec )

Sets the acknowledgement timer period (in msec) and stops the timer.


6.23.2.5 #define ashGetAckPeriod( )

Returns the acknowledgement timer period (in msec).


6.23.2.6 #define ashSetAndStartAckTimer( msec )

Sets the acknowledgement timer period (in msec), and starts the timer running.


6.23.2.7 #define ASH NR TIMER BIT


6.23.2.8 #define ashStopNrTimer( )

Stops the Not Ready timer.


6.23.2.9 #define ashNrTimerIsNotRunning( )

Indicates whether or not ashNrTimer is currently running.


6.23.2.10 #define ASH VERSION

Definition at line 21 of file ash-protocol.h.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

163

6.23.2.11 #define ASH FLAG

frame delimiter


6.23.2.12 #define ASH ESC

byte stuffing escape byte


6.23.2.13 #define ASH XON

flow control byte - means resume transmission


6.23.2.14 #define ASH XOFF

flow control byte - means suspend transmission


6.23.2.15 #define ASH SUB

replaces bytes w framing, overrun or overflow errors


6.23.2.16 #define ASH CAN

frame cancel byte


6.23.2.17 #define ASH WAKE

wake signal byte (also means NCP data pending)


6.23.2.18 #define ASH FLIP

XOR mask used in byte stuffing


6.23.2.19 #define ASH MIN DATA FIELD LEN


EmberZNet 4.7.2 API EM260 120-3020-000-4720

164

6.23.2.20 #define ASH MAX DATA FIELD LEN


6.23.2.21 #define ASH MIN DATA FRAME LEN


6.23.2.22 #define ASH MIN FRAME LEN


6.23.2.23 #define ASH MAX FRAME LEN


6.23.2.24 #define ASH CRC LEN


6.23.2.25 #define ASH MIN FRAME WITH CRC LEN


6.23.2.26 #define ASH MAX FRAME WITH CRC LEN


6.23.2.27 #define ASH NCP SHFRAME RX LEN

longest non-data frame received


6.23.2.28 #define ASH NCP SHFRAME TX LEN

longest non-data frame sent


6.23.2.29 #define ASH HOST SHFRAME RX LEN

longest non-data frame received


EmberZNet 4.7.2 API EM260 120-3020-000-4720

165

6.23.2.30 #define ASH HOST SHFRAME TX LEN

longest non-data frame sent


6.23.2.31 #define ASH DFRAME MASK


6.23.2.32 #define ASH CONTROL DATA


6.23.2.33 #define ASH SHFRAME MASK


6.23.2.34 #define ASH CONTROL ACK


6.23.2.35 #define ASH CONTROL NAK


6.23.2.36 #define ASH CONTROL RST


6.23.2.37 #define ASH CONTROL RSTACK


6.23.2.38 #define ASH CONTROL ERROR


6.23.2.39 #define ASH ACKNUM MASK

acknowledge frame number


6.23.2.40 #define ASH ACKNUM BIT


EmberZNet 4.7.2 API EM260 120-3020-000-4720

166

6.23.2.41 #define ASH RFLAG MASK

retransmitted frame flag


6.23.2.42 #define ASH RFLAG BIT


6.23.2.43 #define ASH NFLAG MASK

receiver not ready flag


6.23.2.44 #define ASH NFLAG BIT


6.23.2.45 #define ASH PFLAG MASK

flag reserved for future use


6.23.2.46 #define ASH PFLAG BIT


6.23.2.47 #define ASH FRMNUM MASK

DATA frame number


6.23.2.48 #define ASH FRMNUM BIT


6.23.2.49 #define ASH GET RFLAG( ctl )


6.23.2.50 #define ASH GET NFLAG( ctl )


EmberZNet 4.7.2 API EM260 120-3020-000-4720

167

6.23.2.51 #define ASH GET FRMNUM( ctl )


6.23.2.52 #define ASH GET ACKNUM( ctl )


6.23.2.53 #define ASH FRAME LEN DATA MIN


6.23.2.54 #define ASH FRAME LEN ACK


6.23.2.55 #define ASH FRAME LEN NAK


6.23.2.56 #define ASH FRAME LEN RST


6.23.2.57 #define ASH FRAME LEN RSTACK


6.23.2.58 #define ASH FRAME LEN ERROR


6.23.2.59 #define MOD8( n )

mask to frame number modulus


6.23.2.60 #define INC8( n )

increment in frame number modulus


6.23.2.61 #define WITHIN RANGE( lo, n, hi )


EmberZNet 4.7.2 API EM260 120-3020-000-4720

168


6.23.3.1 int8u ashEncodeByte ( int8u len, int8u byte, int8u ∗ offset )

Builds an ASH frame. Byte stuffs the control and data fields as required, computes and appends the CRCand adds the ending flag byte. Called with the next byte to encode, this function may return several outputbytes before it’s ready for the next byte.

Parameterslen new frame flag / length of the frame to be encoded. A non-zero value begins a new

frame, so all subsequent calls must use zero. The length includes control byte and datafield, but not the flag or crc. This function does not validate the length.

byte the next byte of data to add to the frame. Note that in general the same byte of datamay have to be passed more than once as escape bytes, the CRC and the end flag byteare output.

offset pointer to the offset of the next input byte. (If the frame data is the array data[], the nextbyte would be data[offset].) Is set to 0 when starting a new frame (ie, len is non-zero).Is set to 0xFF when the last byte of the frame is returned.

Returns

next encoded output byte in frame.

6.23.3.2 EzspStatus ashDecodeByte ( int8u byte, int8u ∗ out, int8u ∗ outLen )

Decodes and validates an ASH frame. Data is passed to it one byte at a time. Decodes byte stuffing, checkscrc, finds the end flag and (if enabled) terminates the frame early on CAN or SUB bytes. The number ofbytes output will not exceed the max valid frame length, which does not include the flag or the crc.

Parametersbyte the next byte of data to add to the frameout pointer to where to write an output byte

outLen number of bytes output so far

Returns

status of frame decoding

• ::EZSP_SUCCESS

• ::EZSP_ASH_IN_PROGRESS

• ::EZSP_ASH_CANCELLED

• ::EZSP_ASH_BAD_CRC

• ::EZSP_ASH_COMM_ERROR

• ::EZSP_ASH_TOO_SHORT

• ::EZSP_ASH_TOO_LONG

EmberZNet 4.7.2 API EM260 120-3020-000-4720

169

6.23.3.3 int8u ashRandomizeArray ( int8u seed, int8u ∗ buf, int8u len )

Randomizes array contents by XORing with an 8-bit pseudo random sequence. This reduces the likelihoodthat byte-stuffing will greatly increase the size of the payload. (This could happen if a DATA framecontained repeated instances of the same reserved byte value.)

Parametersseed zero initializes the random sequence a non-zero value continues from a previous invo-

cationbuf pointer to the array whose contents will be randomizedlen number of bytes in the array to modify

Returns

last value of the sequence. If a buffer is processed in two or more chunks, as with linked buffers, thisvalue should be passed back as the value of the seed argument

6.23.3.4 void ashStartAckTimer ( void )

Sets ashAckTimer to the specified period and starts it running.

6.23.3.5 boolean ashAckTimerHasExpired ( void )

Indicates whether or not ashAckTimer has expired. If the timer is stopped then it is not expired.

6.23.3.6 void ashAdjustAckPeriod ( boolean expired )

Adapts the acknowledgement timer period to the observed ACK delay. If the timer is not running, it doesnothing. If the timer has expired, the timeourt period is doubled. If the timer has not expired, the elapsedtime is fed into simple IIR filter: T[n+1] = (7∗T[n] + elapsedTime) / 8 The timeout period, ashAckPeriod, islimited such that: ASH_xxx_TIME_DATA_MIN <= ashAckPeriod <= ASH_xxx_TIME_DATA_MAX,where xxx is either HOST or NCP.

The acknowledgement timer is always stopped by this function.

Parametersexpired TRUE if timer has expired

6.23.3.7 void ashStartNrTimer ( void )

Starts the Not Ready timer.

On the host, this times nFlag refreshing when the host doesn’t have room for callbacks for a prolongedperiod.

On the NCP, if this times out the NCP resumes sending callbacks.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

170

6.23.3.8 boolean ashNrTimerHasExpired ( void )

Tests whether the Not Ready timer has expired or has stopped. If expired, it is stopped.

Returns

TRUE if the Not Ready timer has expired or stopped


6.23.4.1 boolean ashDecodeInProgress

6.23.4.2 int16u ashAckTimer

6.23.4.3 int16u ashAckPeriod

6.23.4.4 int8u ashNrTimer

EmberZNet 4.7.2 API EM260 120-3020-000-4720

171

6.24 Application Utilities API Reference

Modules

• Forming and Joining Networks• Bootloading• Command Interpreter• ZigBee Device Object (ZDO) Information• Message Fragmentation• Network Manager• Serial Communication• ASH Application Utility


EmberZNet 4.7.2 API EM260 120-3020-000-4720

172

6.25 Forming and Joining Networks

Macros

• #define NETWORK_STORAGE_SIZE• #define NETWORK_STORAGE_SIZE_SHIFT• #define FORM_AND_JOIN_MAX_NETWORKS

Functions

• EmberStatus emberScanForUnusedPanId (int32u channelMask, int8u duration)• EmberStatus emberScanForJoinableNetwork (int32u channelMask, int8u ∗extendedPanId)• EmberStatus emberScanForNextJoinableNetwork (void)• boolean emberFormAndJoinIsScanning (void)• void emberUnusedPanIdFoundHandler (EmberPanId panId, int8u channel)• void emberJoinableNetworkFoundHandler (EmberZigbeeNetwork ∗networkFound, int8u lqi, int8s

rssi)• void emberScanErrorHandler (EmberStatus status)• boolean emberFormAndJoinScanCompleteHandler (int8u channel, EmberStatus status)• boolean emberFormAndJoinNetworkFoundHandler (EmberZigbeeNetwork ∗networkFound, int8u

lqi, int8s rssi)• boolean emberFormAndJoinEnergyScanResultHandler (int8u channel, int8s maxRssiValue)• void emberFormAndJoinTick (void)• void emberFormAndJoinTaskInit (void)• void emberFormAndJoinRunTask (void)• void emberFormAndJoinCleanup (EmberStatus status)

Variables

• boolean emberEnableDualChannelScan


Functions for finding an existing network to join and for finding an unused PAN id with which to form anetwork.

Summary of application requirements:

For the SOC:

• Define ::EMBER_APPLICATION_HAS_ENERGY_SCAN_RESULT_HANDLER in the configu-ration header.

• Call emberFormAndJoinTick() regularly in the main loop.

• Include form-and-join.c and form-and-join-node-adapter.c in the build.

• Optionally include form-and-join-node-callbacks.c in the build.

• If processor idling is desired: – Call emberFormAndJoinTaskInit() to initialize the form and join task– Call emberFormAndJoinRunTask() regularly in the main loop instead of emberFormAndJoinTick()

EmberZNet 4.7.2 API EM260 120-3020-000-4720

173

For an EZSP Host:

• Define ::EZSP_APPLICATION_HAS_ENERGY_SCAN_RESULT_HANDLER in the configura-tion header.

• Include form-and-join.c and form-and-join-host-adapter.c in the build.

• Optionally include form-and-join-host-callbacks.c in the build.

For either platform, the application can omit the form-and-join-∗-callback.c file from the build and imple-ment the callbacks itself if necessary. In this case the appropriate form-and-join callback function must becalled from within each callback, as is done within the form-and-join-∗-callback.c files.

On either platform, FORM_AND_JOIN_MAX_NETWORKS can be explicitly defined to limit (or expand)the number of joinable networks that the library will save for consideration during the scan process.

The library is able to resume scanning for joinable networks from where it left off, via a call to emberScan-ForNextJoinableNetwork(). Thus if the first joinable network found is not the correct one, the applicationcan continue scanning without starting from the beginning and without finding the same network that it hasalready rejected. The library can also be used on the host processor.


6.25.2.1 #define NETWORK STORAGE SIZE

Number of bytes required to store relevant info for a saved network.

This constant represents the minimum number of bytes required to store all members of the NetworkInfostruct used in the adapter code. Its value should not be changed unless the underlying adapter code isupdated accordingly. Note that this constant’s value may be different than sizeof(NetworkInfo) becausesome compilers pad the structs to align on word boundaries. Thus, the adapter code stores/retrieves thesepieces of data individually (to be platform-agnostic) rather than as a struct.

For efficiency’s sake, this number should be kept to a power of 2 and not and not exceed 32 (PACKET_B-UFFER_SIZE).

Definition at line 68 of file form-and-join.h.

6.25.2.2 #define NETWORK STORAGE SIZE SHIFT

Log_base2 of NETWORK_STORAGE_SIZE.


6.25.2.3 #define FORM AND JOIN MAX NETWORKS

Number of joinable networks that can be remembered during the scan process.

Note for SoC Platforms: This is currently limited to a maximum of 15 due to the size of each network entry(16 bytes) and the EmberMessageBuffer API’s requirement that total buffer storage length be kept to an8-bit quantity (less than 256).

Note for EZSP Host Platforms: In the host implementation of this library, the storage size for the detectednetworks buffer is controlled by EZSP_HOST_FORM_AND_JOIN_BUFFER_SIZE, so that limits thehighest value that the host can set for FORM_AND_JOIN_MAX_NETWORKS.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

174


6.25.3.1 EmberStatus emberScanForUnusedPanId ( int32u channelMask, int8u duration )

Find an unused PAN id.

Does an energy scan on the indicated channels and randomly chooses one from amongst those with theleast average energy. Then picks a short PAN id that does not appear during an active scan on the chosenchannel. The chosen PAN id and channel are returned via the emberUnusedPanIdFoundHandler() callback.If an error occurs, the application is informed via the emberScanErrorHandler().

ParameterschannelMask

duration The duration of the energy scan. See the documentation for ::emberStartScan() instack/include/network-formation.h for information on duration values.

Returns

EMBER_LIBRARY_NOT_PRESENT if the form and join library is not available.

6.25.3.2 EmberStatus emberScanForJoinableNetwork ( int32u channelMask, int8u ∗ extendedPanId )

Finds a joinable network.

Performs an active scan on the specified channels looking for networks that:

1. currently permit joining,

2. match the stack profile of the application,

3. match the extended PAN id argument if it is not NULL.

Upon finding a matching network, the application is notified via the emberJoinableNetworkFoundHandler()callback, and scanning stops. If an error occurs during the scanning process, the application is informedvia the emberScanErrorHandler(), and scanning stops.

If the application determines that the discovered network is not the correct one, it may call emberScanFor-NextJoinableNetwork() to continue the scanning process where it was left off and find a different joinablenetwork. If the next network is not the correct one, the application can continue to call emberScanForNext-JoinableNetwork(). Each call must occur within 30 seconds of the previous one, otherwise the state of thescan process is deleted to free up memory. Calling emberScanForJoinableNetwork() causes any old stateto be forgotten and starts scanning from the beginning.

ParameterschannelMask

extendedPanId

Returns

EMBER_LIBRARY_NOT_PRESENT if the form and join library is not available.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

175

6.25.3.3 EmberStatus emberScanForNextJoinableNetwork ( void )

See emberScanForJoinableNetwork().

6.25.3.4 boolean emberFormAndJoinIsScanning ( void )

Returns true if and only if the form and join library is in the process of scanning and is therefore expectingscan results to be passed to it from the application.

6.25.3.5 void emberUnusedPanIdFoundHandler ( EmberPanId panId, int8u channel )

A callback the application needs to implement.

Notifies the application of the PAN id and channel found following a call to emberScanForUnusedPanId().

ParameterspanId

channel

6.25.3.6 void emberJoinableNetworkFoundHandler ( EmberZigbeeNetwork ∗ networkFound, int8u lqi,int8s rssi )


Notifies the application of the network found after a call to emberScanForJoinableNetwork() or ember-ScanForNextJoinableNetwork().

ParametersnetworkFound

lqi The lqi value of the received beacon.rssi The rssi value of the received beacon.

6.25.3.7 void emberScanErrorHandler ( EmberStatus status )


If an error occurs while scanning, this function is called and the scan effort is aborted.

Possible return status values are:

• EMBER_INVALID_CALL: if emberScanForNextJoinableNetwork() is called more than 30 secondsafter a previous call to emberScanForJoinableNetwork() or emberScanForNextJoinableNetwork().

• EMBER_NO_BUFFERS: if there is not enough memory to start a scan.

• EMBER_NO_BEACONS: if no joinable beacons are found.

• EMBER_MAC_SCANNING: if a scan is already in progress.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

176

Parametersstatus

6.25.3.8 boolean emberFormAndJoinScanCompleteHandler ( int8u channel, EmberStatus status )

The application must call this function from within its emberScanCompleteHandler() (on the node) orezspScanCompleteHandler() (on an EZSP host). Default callback implementations are provided in theform-and-join-∗-callbacks.c files.

Returns

TRUE iff the library made use of the call.

6.25.3.9 boolean emberFormAndJoinNetworkFoundHandler ( EmberZigbeeNetwork ∗ networkFound,int8u lqi, int8s rssi )

The application must call this function from within its emberNetworkFoundHandler() (on the node) orezspNetworkFoundHandler() (on an EZSP host). Default callback implementations are provided in theform-and-join-∗-callbacks.c files.

Returns


6.25.3.10 boolean emberFormAndJoinEnergyScanResultHandler ( int8u channel, int8s maxRssiValue )

The application must call this function from within its emberEnergyScanResultHandler() (on the node) orezspEnergyScanResultHandler() (on an EZSP host). Default callback implementations are provided in theform-and-join-∗-callbacks.c files.

Returns


6.25.3.11 void emberFormAndJoinTick ( void )

Used by the form and join code on the node to time out a joinable scan after 30 seconds of inactivity. Theapplication must call emberFormAndJoinTick() regularly. This function does not exist for the EZSP hostlibrary.

6.25.3.12 void emberFormAndJoinTaskInit ( void )

When processor idling is desired on the SOC, this must be called to properly initialize the form and joinlibrary.

6.25.3.13 void emberFormAndJoinRunTask ( void )

When processor idling is desired on the SOC, this should be called regularly instead of emberFormAnd-JoinTick()

EmberZNet 4.7.2 API EM260 120-3020-000-4720

177

6.25.3.14 void emberFormAndJoinCleanup ( EmberStatus status )

When form-and-join state is no longer needed, the application can call this routine to cleanup and freeresources. On the SOC platforms this will free the allocated message buffer.


6.25.4.1 boolean emberEnableDualChannelScan

With some board layouts, the EM250 and EM260 are susceptible to a dual channel issue in which packetsfrom 12 channels above or below can sometimes be heard faintly. This affects channels 11 - 14 and 23 - 26.Hardware reference designs EM250_REF_DES_LAT, version C0 and EM250_REF_DES_CER, versionB0 solve the problem.

Setting the emberEnableDualChannelScan variable to TRUE enables a software workaround to the dualchannel issue which can be used with vulnerable boards. After emberScanForJoinableNetwork() discoversa network on one of the susceptible channels, the channel number that differs by 12 is also scanned. Ifthe same network can be heard there, the true channel is determined by comparing the link quality ofthe received beacons. The default value of emberEnableDualChannelScan is TRUE for the EM250 andEM260. It is not used on other platforms.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

178

6.26 Bootloading

Modules

• Stand-Alone Bootloader Interface• Stand-Alone Bootloader for EZSP• Stand-Alone Bootloader Library


For a thorough discussion of bootloading, see the Bootloading chapter of the EmberZNet Application De-velopers Guide. There are three forms of the bootloading API.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

179

6.27 Stand-Alone Bootloader Interface

Macros

• #define NO_BOOTLOADER_MODE• #define STANDALONE_BOOTLOADER_NORMAL_MODE• #define STANDALONE_BOOTLOADER_RECOVERY_MODE• #define BOOTLOADER_TYPE_STANDALONE• #define halBootloadAppStart(space, segment, ramPtr)• #define halBootloadAdjustFlash(space, segment, ramPtr)

Enumerations

• enum {BOOTLOADER_MODE_MENU, BOOTLOADER_MODE_PASSTHROUGH, BOOTLOADER-_MODE_CLONE, BOOTLOADER_MODE_CLONE_RECOVERY,BOOTLOADER_MODE_PASSTHROUGH_RECOVERY }

Functions

• int16u halGetStandaloneBootloaderVersion (void)• EmberStatus halLaunchStandaloneBootloader (int8u mode)• EmberStatus halInternalStandaloneBootloaderTrap (int16u assumedBootloaderType, int8u trapNumber,...)• void halInternalAdjustFlashBlock (int16u ∗dst, int16u ∗src, int8u size)• EmberStatus halLaunchStandaloneBootloaderV1 (int8u mode, int8u ∗eui64)


Definition of the standalone bootloader interface. Some functions in this file return an EmberStatus value.See error-def.h for definitions of all EmberStatus return values.

See bootloader-interface-standalone.h for source code.

See bootloader-interface-standalone-v1.h for source code.


6.27.2.1 #define NO BOOTLOADER MODE

Define a numerical value for NO BOOTLOADER mode. In other words, the bootloader should not be run.

Definition at line 33 of file bootloader-interface-standalone.h.

6.27.2.2 #define STANDALONE BOOTLOADER NORMAL MODE

Define a numerical value for the normal bootloader mode.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

180

6.27.2.3 #define STANDALONE BOOTLOADER RECOVERY MODE

Define a numerical value for the recovery bootloader mode.


6.27.2.4 #define BOOTLOADER TYPE STANDALONE

A "signature" to identify the bootloader type and help catch any app/bootloader mismatch.

Definition at line 26 of file bootloader-interface-standalone-v1.h.

6.27.2.5 #define halBootloadAppStart( space, segment, ramPtr )

Trap for accessing bootloadAppStart()

Parametersspace Size of block, in words. Must be 0 to 128.

segment Byte address pointer. Must be an even address and within the first 64k bytes of flashaddress space. Usually use to point to the beginning of a flash block.

ramPtr Byte address pointer. Must be within the first 64k bytes of flash address space.

Returns

EMBER_ERR_BOOTLOADER_TRAP_TABLE_BAD if the trap table is corrupt or if the applicationbootloader API is not installed. EMBER_SUCCESS if the segment is written.


6.27.2.6 #define halBootloadAdjustFlash( space, segment, ramPtr )

Trap for accessing halInternalAdjustFlashBlock()

Parametersspace Size of block, in words. Must be 0 to 128.

segment Byte address pointer. Must be an even address and within the first 64k bytes of flashaddress space. Usually use to point to the beginning of a flash block.

ramPtr Byte address pointer. Must be within the first 64k bytes of flash address space.

Returns

EMBER_ERR_BOOTLOADER_TRAP_TABLE_BAD if the trap table is corrupt or if the applicationbootloader API is not installed. EMBER_SUCCESS if the segment is written.



EmberZNet 4.7.2 API EM260 120-3020-000-4720

181


Enumerator:

BOOTLOADER_MODE_MENUBOOTLOADER_MODE_PASSTHROUGHBOOTLOADER_MODE_CLONEBOOTLOADER_MODE_CLONE_RECOVERYBOOTLOADER_MODE_PASSTHROUGH_RECOVERY



6.27.4.1 int16u halGetStandaloneBootloaderVersion ( void )

Detects if the standalone bootloader is installed, and if so returns the installed version.

A returned version of 0x1234 would indicate version 1.2 build 34

Returns

::BOOTLOADER_INVALID_VERSION if the standalone bootloader is not present, or the version ofthe installed standalone bootloader.

6.27.4.2 EmberStatus halLaunchStandaloneBootloader ( int8u mode )

Quits the current application and launches the standalone bootloader (if installed). The function returns anerror if the standalone bootloader is not present.

Parametersmode Controls the mode in which the standalone bootloader will run. See the bootloader

Application Note for full details. Options are:

• STANDALONE_BOOTLOADER_NORMAL_MODE Will listen for an over-the-air image transfer on the current channel with current power settings.

• STANDALONE_BOOTLOADER_RECOVERY_MODE Will listen for an over-the-air image transfer on the default channel with default power settings.

Both modes also allow an image transfer to begin via serial xmodem.

Returns

An EmberStatus error if the standalone bootloader is not present, or EMBER_SUCCESS.

6.27.4.3 EmberStatus halInternalStandaloneBootloaderTrap ( int16u assumedBootloaderType, int8utrapNumber, ... )

Calls the bootloader trap functions and may be used for either the stand-alone or application bootloader.Each trap function has a wrapper macro in hal/micro/.../.../micro.h. Use the wrapper functions under normalcircumstances because they improve readability and automatically check for bootloader type.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

182

Parametersassumed-

Bootloader-Type

There are different traps for the stand-alone and application bootloaders. This guardsagainst calling a trap from the wrong bootloader type.

trapNumber Trap identifier.... Parameter list corresponding to the trap.

Returns

An error if the trap identifier is invalid, or EMBER_SUCCESS.

6.27.4.4 void halInternalAdjustFlashBlock ( int16u ∗ dst, int16u ∗ src, int8u size )

Modifies a block of flash without losing existing data.

Note

dst and size may be set so that they span multiple pages. Any remaining portion of those pageswill remain unchanged other than having been erased and rewritten.

Parametersdst Byte address pointer. Must be an even address and within the first 64k bytes of flash

address space. Usually use to point to the beginning of a flash block.src Byte address pointer. Must be within the first 64k bytes of flash address space.

size Size of block, in words. Must be 0 to 128.

6.27.4.5 EmberStatus halLaunchStandaloneBootloaderV1 ( int8u mode, int8u ∗ eui64 )

Quits the current application and launches the stand-alone bootloader (if installed) in a non-over-the-airmode (usually the serial port). The function returns an error if the stand-alone bootloader is not present.

Parametersmode Controls the mode in which the standalone bootloader will run. See the app. note for

full details. Options are:

• BOOTLOADER_MODE_MENU: Allow user to upload an image via XMODE-M, either to the current node or via single hop over the air passthrough mode.

• BOOTLOADER_MODE_PASSTHROUGH_RECOVERY: Special mode to al-low uploading an image over the air to a node that has been lost as a result of anunsuccessful bootload.

• BOOTLOADER_MODE_CLONE: Upload the current node image to the newnode.

• BOOTLOADER_MODE_CLONE_RECOVERY: Special mode to allow cloningof the current node’s image to a node that has been lost as a result of an unsuc-cessful bootload.

eui64 For BOOTLOADER_MODE_CLONE and BOOTLOADER_MODE_MENU, this pa-rameter specifies the EUI64 of the other node for single hop over the air bootloading.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

183

Returns

An error if the stand-alone bootloader is not present, or EMBER_SUCCESS.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

184

6.28 Stand-Alone Bootloader for EZSP

Macros

• #define TICKS_PER_QUARTER_SECOND

Functions

• boolean hostBootloadUtilLaunchRequestHandler (int8u lqi, int8s rssi, int16u manufacturerId, int8u∗hardwareTag, EmberEUI64 sourceEui)

• void hostBootloadUtilQueryResponseHandler (int8u lqi, int8s rssi, boolean bootloaderActive, int16umanufacturerId, int8u ∗hardwareTag, EmberEUI64 targetEui, int8u bootloaderCapabilities, int8uplatform, int8u micro, int8u phy, int16u blVersion)

• void hostBootloadReinitHandler (void)• boolean isTheSameEui64 (EmberEUI64 sourceEui, EmberEUI64 targetEui)• void printLittleEndianEui64 (int8u port, EmberEUI64 eui64)• void printBigEndianEui64 (int8u port, EmberEUI64 eui64)• EmberStatus debugPrintf (int8u port, PGM_P formatString,...)

Variables

• int16u nodeBlVersion• int8u nodePlat• int8u nodeMicro• int8u nodePhy• EzspStatus bootloadEzspLastError• EzspStatus ignoreNextEzspError


All functions and variables defined here can be used by applications. See bootload-ezsp-utils.h for sourcecode.


6.28.2.1 #define TICKS PER QUARTER SECOND

Definition at line 23 of file bootload-ezsp-utils.h.


6.28.3.1 boolean hostBootloadUtilLaunchRequestHandler ( int8u lqi, int8s rssi, int16u manufacturerId,int8u ∗ hardwareTag, EmberEUI64 sourceEui )

A callback function invoked by bootload-ezsp-utils when a bootload launch request message is received.

The application may choose whether or not to enter the bootloader by checking the manufacturerId,hardwareTag, and sourceEui. If the application chooses to launch the bootloader, the bootloader willlaunch after successful completion of the bootloader launch authentication protocol.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

185

Parameterslqi The link quality from the node that generated this bootload launch request.

rssi The energy level (in units of dBm) observed during the reception.manufacturerId The manufacturer specification (vendor specific) of the sending node.

hardwareTag The hardware specification (vendor specific) of the sending node.sourceEui The EUI64 of the sending node.

Returns

TRUE if the application wishes to launch the bootloader, FALSE if the application does not wish tolaunch the bootloader.

6.28.3.2 void hostBootloadUtilQueryResponseHandler ( int8u lqi, int8s rssi, boolean bootloaderActive,int16u manufacturerId, int8u ∗ hardwareTag, EmberEUI64 targetEui, int8ubootloaderCapabilities, int8u platform, int8u micro, int8u phy, int16u blVersion )

A callback function invoked by bootload-ezsp-utils when a bootload query response message is received.

This is particularly useful when the application needs to decide which node to bootload. Several attributesof the responding node are provided to the application. The application can use these attributes to decidewhether to bootload or how to bootload a given node.

Parameterslqi The link quality from the node that generated this bootload query response.

rssi The energy level (in units of dBm) observed during the reception.bootloader-

ActiveTRUE if the responding node is running the bootloader, FALSE if not.

manufacturerId The manufacturer specification (vendor specific) of the responding node.hardwareTag The hardware specification (vendor specific) of the responding node.

targetEui The EUI64 of the responding node.bootloader-Capabilities

If the lsb is 1, the bootloader on the responding node supports encrypted bootloadermessage payloads.

platform The type of platform of the responding node. 1 is avr-atmega, 2 is xap2b.micro The type of microcontroller on the responding node. Value depends on platform. 1 is

the avr-atmega 64, 2 is the avr-atmega 128, 1 is the xap2b em250.phy The type of phy of the responding node. 1 is em2420, 2 is em250.

blVersion The version of standalone bootloader of the responding node. This is a 2 byte field.The high byte is the version and the low byte is the build. A value of 0xFFFF meansunknown. For example, a version field of 0x1234 is version 1.2, build 34.

6.28.3.3 void hostBootloadReinitHandler ( void )

A callback function invoked by bootload-ezsp-utils when a NCP has finished being bootloaded.

The application can handle this as simply as calling on halReboot() or as complex as needed.

6.28.3.4 boolean isTheSameEui64 ( EmberEUI64 sourceEui, EmberEUI64 targetEui )

A function to compare EUI64s.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

186

Compare two EUI64s.

ParameterssourceEui The EUI64 of the sending node.targetEui The EUI64 of the responding node.

Returns

TRUE if the EUI64s are the same. FALSE if the EUI64s are different.

6.28.3.5 void printLittleEndianEui64 ( int8u port, EmberEUI64 eui64 )

A function to display an EUI64.

Display an EUI64 in little endian format.

Parametersport The serial port to use. 0 for Mega128 port. 0 or 1 for Linux ports.

eui64 The EUI64 to display.

6.28.3.6 void printBigEndianEui64 ( int8u port, EmberEUI64 eui64 )

A function to display an EUI64.

Display an EUI64 in big endian format.


eui64 The EUI64 to display.

6.28.3.7 EmberStatus debugPrintf ( int8u port, PGM_P formatString, ... )

A function to simular to emberSerialPrintf().

Output to local ports.


formatString The string to print.... Format specifiers.

Returns

One of the following (see the Main Page):

• EMBER_SERIAL_TX_OVERFLOW indicates that data was dropped.• EMBER_NO_BUFFERS indicates that there was an insufficient number of available stack buffers.• EMBER_SUCCESS.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

187


6.28.4.1 int16u nodeBlVersion

6.28.4.2 int8u nodePlat

6.28.4.3 int8u nodeMicro

6.28.4.4 int8u nodePhy

6.28.4.5 EzspStatus bootloadEzspLastError

6.28.4.6 EzspStatus ignoreNextEzspError

EmberZNet 4.7.2 API EM260 120-3020-000-4720

188

6.29 Stand-Alone Bootloader Library

Macros

• #define BOOTLOAD_HARDWARE_TAG_SIZE

Enumerations

• enum bootloadMode { BOOTLOAD_MODE_NONE, BOOTLOAD_MODE_PASSTHRU }• enum bootloadState {

BOOTLOAD_STATE_NORMAL, BOOTLOAD_STATE_QUERY, BOOTLOAD_STATE_WAI-T_FOR_AUTH_CHALLENGE, BOOTLOAD_STATE_WAIT_FOR_AUTH_RESPONSE,BOOTLOAD_STATE_DELAY_BEFORE_START, BOOTLOAD_STATE_START_UNICAST_-BOOTLOAD, BOOTLOAD_STATE_START_BROADCAST_BOOTLOAD, BOOTLOAD_STA-TE_START_SENDING_IMAGE,BOOTLOAD_STATE_SENDING_IMAGE, BOOTLOAD_STATE_WAIT_FOR_IMAGE_ACK, B-OOTLOAD_STATE_WAIT_FOR_COMPLETE_ACK, BOOTLOAD_STATE_DONE }

Functions

• void bootloadUtilInit (int8u appPort, int8u bootloadPort)• EmberStatus bootloadUtilSendRequest (EmberEUI64 targetEui, int16u mfgId, int8u hardwareTag[B-

OOTLOAD_HARDWARE_TAG_SIZE], int8u encryptKey[BOOTLOAD_AUTH_COMMON_SI-ZE], bootloadMode mode)

• void bootloadUtilSendQuery (EmberEUI64 target)• void bootloadUtilStartBootload (EmberEUI64 target, bootloadMode mode)• void bootloadUtilTick (void)• boolean bootloadUtilLaunchRequestHandler (int16u manufacturerId, int8u hardwareTag[BOOTL-

OAD_HARDWARE_TAG_SIZE], EmberEUI64 sourceEui)• void bootloadUtilQueryResponseHandler (boolean bootloaderActive, int16u manufacturerId, int8u

hardwareTag[BOOTLOAD_HARDWARE_TAG_SIZE], EmberEUI64 targetEui, int8u bootloader-Capabilities, int8u platform, int8u micro, int8u phy, int16u blVersion)

• void bootloadUtilSendAuthResponse (EmberEUI64 target)

Authentication Challenge and Response

The authentication challenge and response must be the same size. The size is chosen to be evenly divisibleby the size of a 128-bit AES block.

• #define BOOTLOAD_AUTH_COMMON_SIZE• #define BOOTLOAD_AUTH_CHALLENGE_SIZE• #define BOOTLOAD_AUTH_RESPONSE_SIZE

Bootload State Variables

Used to check whether a bootloading process is currently happening.

• bootloadState blState• #define IS_BOOTLOADING

EmberZNet 4.7.2 API EM260 120-3020-000-4720

189


All functions and variables defined here can be used by applications. See bootload-utils.h for source code.

Applications can use this stand-alone bootload library to:

1. Load a new (application) image on itself via serial bootload through uart port 1 using the xmodemprotocol.

2. Load a new image on a remote node over-the-air (OTA) from a host (PC), also known as a passthrubootload.

3. Recover a node that failed during the bootloading process, also known as a recovery bootload.

Note from the diagrams below that with over-the-air bootloading the source node (node transmitting boot-load packets) and the target node (node being loaded with a new image) need to be one hop away becausebootload packets are IEEE 802.15.4 packets.

In case of recovery, the source (recovery) node does not need to be part of the network since all recoverypackets are 802.15.4 packets.

A diagram for typical serial bootloading:

[host pc] –(RS232 or Ethernet/IP network)– {uart1 or port 4901}[node]

A diagram for typical passthru bootloading:

[host pc] –(RS232 or Ethernet)– [source node]–(OTA)–[target node]

A diagram for typical recovery bootloading:

[source node] –(OTA)–[target node]

Note

Applications that use the bootload utilities need to #define EMBER_APPLICATION_HAS_BOO-TLOAD_HANDLERS within their CONFIGURATION_HEADER .


6.29.2.1 #define BOOTLOAD AUTH COMMON SIZE

Definition at line 66 of file bootload-utils.h.

6.29.2.2 #define BOOTLOAD AUTH CHALLENGE SIZE


6.29.2.3 #define BOOTLOAD AUTH RESPONSE SIZE


6.29.2.4 #define BOOTLOAD HARDWARE TAG SIZE

Size of hardware tag which is an array of int8u.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

190

// End set of defines


6.29.2.5 #define IS BOOTLOADING



6.29.3.1 enum bootloadMode

Bootload modes supported by the bootload utility library.

Enumerator:

BOOTLOAD_MODE_NONE Used when we are not currently doing any bootloading.

BOOTLOAD_MODE_PASSTHRU Used when doing normal and recovery passthru bootload.


6.29.3.2 enum bootloadState

A bootload state is a value that an application can check to see if bootloading is in progress.

This is necessary because we want the application to be aware that bootloading is going on and it needs tolimit its activities. For example, when passthru bootloading is going on, do not print anything to a serialport because it may violate the XModem protocol. Also, try to limit radio activities to a minimum to avoidany interruptions to bootload progress. Used in a bootload state machine.

Enumerator:

BOOTLOAD_STATE_NORMAL Start state

BOOTLOAD_STATE_QUERY After send query message

BOOTLOAD_STATE_WAIT_FOR_AUTH_CHALLENGE Wait for authentication challenge

BOOTLOAD_STATE_WAIT_FOR_AUTH_RESPONSE Wait for authentication response

BOOTLOAD_STATE_DELAY_BEFORE_START Delay state before start new action

BOOTLOAD_STATE_START_UNICAST_BOOTLOAD After start unicast bootloading

BOOTLOAD_STATE_START_BROADCAST_BOOTLOAD After start broadcast bootloading

BOOTLOAD_STATE_START_SENDING_IMAGE Need to start XMODEM code

BOOTLOAD_STATE_SENDING_IMAGE During sending OTA data messages

BOOTLOAD_STATE_WAIT_FOR_IMAGE_ACK Wait for OTA data ack

BOOTLOAD_STATE_WAIT_FOR_COMPLETE_ACK Wait for OTA end transmission ack

BOOTLOAD_STATE_DONE Finish bootloading


EmberZNet 4.7.2 API EM260 120-3020-000-4720

191


6.29.4.1 void bootloadUtilInit ( int8u appPort, int8u bootloadPort )

Bootload library initialization.

The application needs to define the ports to be used for printing information and for a (passthru) bootload.

Note

Generally it’s a good idea to use different ports for the application and for bootloading because whendoing passthru bootloading, we do not want to print any additional data that can cause an XModemtransaction to fail.

ParametersappPort Port used for printing information.

bootloadPort Port used for passthru bootloading.

6.29.4.2 EmberStatus bootloadUtilSendRequest ( EmberEUI64 targetEui, int16umfgId, int8u hardwareTag[BOOTLOAD HARDWARE TAG SIZE], int8uencryptKey[BOOTLOAD AUTH COMMON SIZE], bootloadMode mode )

Start the bootload process on a remote node that is currently running stack/application.

The source node sends a bootload request message to initiate the bootload authentication process. Thesource node then enters a state waiting for the target node to send an authentication challenge, which it willencrypt and send back as a response. MfgId and harwareTag information is sent over the air to the targetnode to verify whether to go into bootload mode. The encryption key is saved on the source node for laterauthentication. The mode indicates the bootload mode that the source will be using.

ParameterstargetEui Node to be bootloaded.

mfgId Manufacturer ID (vendor specific).hardwareTag Hardware ID, such as a board (vendor specific).

encryptKey Key used in the authentication process.mode Bootload mode to be used is passthru (0x01).

Returns

EMBER_SUCESS if successful, or EMBER_NO_BUFFERS, or EMBER_ERR_FATAL if the func-tion was called too soon after a previous call to it.

6.29.4.3 void bootloadUtilSendQuery ( EmberEUI64 target )

A function to send query message to gather basic information about the node(s).

There are two types of query messages: broadcast and unicast. Broadcast query is generally used to gatherinformation regarding a neighboring node, especially the eui64 of the node. Unicast query is used whenwe already know the eui64 of the target node that we needs information from.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

192

Parameterstarget The node we want to gather information from. If the value is NULL, that means we

want to do a broadcast query.

6.29.4.4 void bootloadUtilStartBootload ( EmberEUI64 target, bootloadMode mode )

Start the bootload process on a remote node that is already running in bootload mode.

This is generally to recover a node that failed during bootload. The failure can be caused by the sourcenode resetting, the network being too busy, a software reset, and so on. However, the failure is not causedby a target node losing power. After the failure, the node stays in bootload mode on the same (current)channel.

Parameterstarget remote node to be bootloaded. If the value is NULL, that means we do not know the

eui64 of the target node. A broadcast (start bootload) packet is sent and the first nodethat replies will be bootloaded.

mode bootload mode to be used, such as passthru (0x01).

6.29.4.5 void bootloadUtilTick ( void )

A function in the application’s heartbeat or tick function that contains basic bootloading state machine andalso manages the bootload timer.

6.29.4.6 boolean bootloadUtilLaunchRequestHandler ( int16u manufacturerId, int8uhardwareTag[BOOTLOAD HARDWARE TAG SIZE], EmberEUI64 sourceEui )

A callback function invoked by bootload-utils when a bootload request message is received.

The application may choose whether or not to enter the bootloader by checking the manufacturerId,hardwareTag, and sourceEui. If the application chooses to launch the bootloader, the bootloader willlaunch after successful completion of the bootloader launch authentication protocol.

ParametersmanufacturerId The manufacturer specification (vendor specific) of the sending node.

hardwareTag The hardware specification (vendor specific) of the sending node.sourceEui The EUI64 of the sending node.

Returns

TRUE if the application wishes to launch the bootloader, FALSE if the application does not wish tolaunch the bootloader.

6.29.4.7 void bootloadUtilQueryResponseHandler ( boolean bootloaderActive, int16u manufacturerId,int8u hardwareTag[BOOTLOAD HARDWARE TAG SIZE], EmberEUI64 targetEui, int8ubootloaderCapabilities, int8u platform, int8u micro, int8u phy, int16u blVersion )

A callback function invoked by bootload-utils when a bootload query response message is received.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

193

This is particularly useful when the application needs to decide which node to bootload. Several attributesof the responding node are provided to the application. The application can use these attributes to decidewhether to bootload or how to bootload a given node.

Parametersbootloader-

ActiveTRUE if the responding node is running the bootloader, FALSE if not.

manufacturerId The manufacturer specification (vendor specific) of the responding node.hardwareTag The hardware specification (vendor specific) of the responding node.

targetEui The EUI64 of the responding node.bootloader-Capabilities

If the lsb is 1, the bootloader on the responding node supports encrypted bootloadermessage payloads.

platform The type of platform of the responding node. 1 is avr-atmega, 2 is xap2b.micro The type of microcontroller on the responding node. Value depends on platform. 1 is

the avr-atmega 64, 2 is the avr-atmega 128, 1 is the xap2b em250.phy The type of phy of the responding node. 1 is em2420, 2 is em250.

blVersion The version of standalone bootloader of the responding node. This is a 2 byte field.The high byte is the version and the low byte is the build. A value of 0xFFFF meansunknown. For example, a version field of 0x1234 is version 1.2, build 34.

6.29.4.8 void bootloadUtilSendAuthResponse ( EmberEUI64 target )

A function called by a parent node to send an authentication response message to the sleepy or mobileend-device target node.

The message is sent as a Just-In-Time (JIT) message, hence, the end-device target needs to poll for themessage.

The bootload utility library will call this function automatically if bootloading the router node.

Parameterstarget The end-device target node being bootloaded.


6.29.5.1 bootloadState blState

EmberZNet 4.7.2 API EM260 120-3020-000-4720

194

6.30 Command Interpreter

Data Structures

• struct EmberCommandEntryCommand entry for a command table.

• struct EmberCommandStateSThe command state structure. Using a structure allows commands to be read from multiple sources.

Macros

• #define TEMP_GREATER_THAN_MAX_ARG_SIZE• #define PERFORM_BOUNDS_CHECKING• #define emberProcessCommandInput(state, port)• #define emberCommandName(state)

Typedefs

• typedef int16u ArgTypeU• typedef void(∗ CommandAction )(struct EmberCommandStateS ∗state)• typedef struct EmberCommandStateS EmberCommandState

Enumerations

• enum EmberCommandStatus {EMBER_CMD_SUCCESS, EMBER_CMD_ERR_PORT_PROBLEM, EMBER_CMD_ERR_NO-_BUFFER_AVAILABLE, EMBER_CMD_ERR_NO_SUCH_COMMAND,EMBER_CMD_ERR_WRONG_COMMAND_ARGUMENTS, EMBER_CMD_ERR_TOO_MAN-Y_COMMAND_ARGUMENTS, EMBER_CMD_ERR_ARGUMENT_OUT_OF_RANGE, EMB-ER_CMD_ERR_ARGUMENT_SYNTAX_ERROR,EMBER_CMD_ERR_STRING_TOO_LONG, EMBER_CMD_ERR_NO_BINARY_STRING_TE-RMINATOR, EMBER_CMD_SUCCESS, EMBER_CMD_ERR_PORT_PROBLEM,EMBER_CMD_ERR_NO_SUCH_COMMAND, EMBER_CMD_ERR_WRONG_NUMBER_OF-_ARGUMENTS, EMBER_CMD_ERR_ARGUMENT_OUT_OF_RANGE, EMBER_CMD_ERR-_ARGUMENT_SYNTAX_ERROR,EMBER_CMD_ERR_STRING_TOO_LONG, EMBER_CMD_ERR_INVALID_ARGUMENT_T-YPE }

Functions

• void emberCommandReaderInit (EmberCommandState ∗state)• boolean emberProcessCommandString (EmberCommandState ∗state, int8u ∗input, int8u size)

Variables

• PGM_NO_CONST PGM_P emberCommandErrorNames [ ]

EmberZNet 4.7.2 API EM260 120-3020-000-4720

195

Command Table Settings

• #define EMBER_COMMENT_CHARACTER• #define EMBER_MAX_COMMAND_LENGTH

Macros to Retrieve Arguments

Use the following macros in your functions that process commands to retrieve arguments from the com-mand interpreter state object. These macros pull out unsigned integers, signed integers, and buffers.

• #define emberUnsignedCommandArgument(state, index)• #define emberSignedCommandArgument(state, index)• #define emberBufferCommandArgument(state, index)


Interpret serial port commands. See command-interpreter.h for source code.

See the following application usage example followed by a brief explanation.

static EmberCommandEntry commands[] = {{ "integers", integersCommand, "u1u2s1s2", "integers"},{ "intlist", intListCommand, "u1*", "intlist"},{ "stringlist", stringListCommand, "bb*", "stringlist"},{ NULL, NULL, NULL, NULL}}; // NULL action makes this a terminator

static void commandErrorHandler(EmberCommandState *state){

// ...}

ArgTypeU arguments[4];

EmberCommandState testState ={commands,commandErrorHandler,arguments,4, // maximum command arguments10 // integer base

};

emberCommandReaderInit(&testState);

1. Applications specify the commands that can be interpreted by defining a commands table of typeEmberCommandEntry. The table includes the following information for each command:

(a) The full command name.

(b) Your application’s function name that implements the command.

(c) An EmberCommandEntry::argumentTypes string specifies the number and types of argumentsthe command accepts. See ::argumentTypes for details.

(d) A description string explains the command.

2. Applications also need to define a command error handler to deal with incorrect command input.

3. The command table, the error handler, and other command interpreter state information are bundledinto an EmberCommandState structure. Using a structure allows commands to be read from multiplesources.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

196

4. The application provides an instance of the EmberCommandState structure to the interpreter bycalling emberCommandReaderInit().


6.30.2.1 #define EMBER COMMENT CHARACTER

The command table’s comment indicator. A comment consists of a ’#’ followed by any characters up to anend-of-line.

Definition at line 75 of file command-interpreter.h.

6.30.2.2 #define EMBER MAX COMMAND LENGTH

The maximum number of characters in a command.


6.30.2.3 #define TEMP GREATER THAN MAX ARG SIZE


6.30.2.4 #define PERFORM BOUNDS CHECKING


6.30.2.5 #define emberUnsignedCommandArgument( state, index )


6.30.2.6 #define emberSignedCommandArgument( state, index )


6.30.2.7 #define emberBufferCommandArgument( state, index )


6.30.2.8 #define emberProcessCommandInput( state, port )

A macro that parses any input coming in on the serial port, which returns when no more input is available.This is a wrapper for emberProcessCommandString() with a null string and the port passed in as the stringsize.

void emberProcessCommandInput(EmberCommandState

*state, int8u port);


EmberZNet 4.7.2 API EM260 120-3020-000-4720

197

6.30.2.9 #define emberCommandName( state )

Return a pointer to the command name being executed.

Parametersstate The command state structure.



6.30.3.1 typedef int16u ArgTypeU


6.30.3.2 typedef void(∗ CommandAction)(struct EmberCommandStateS ∗state)


6.30.3.3 typedef struct EmberCommandStateS EmberCommandState

The command state structure. Using a structure allows commands to be read from multiple sources.


6.30.4.1 enum EmberCommandStatus

Command error states.

If you change this list, ensure you also change the strings that describe these errors in the array ember-CommandErrorNames[] in command-interpreter.c.

Enumerator:

EMBER_CMD_SUCCESS no error

EMBER_CMD_ERR_PORT_PROBLEM serial port error

EMBER_CMD_ERR_NO_BUFFER_AVAILABLE command processor busy

EMBER_CMD_ERR_NO_SUCH_COMMAND no such command

EMBER_CMD_ERR_WRONG_COMMAND_ARGUMENTS incorrect command arguments

EMBER_CMD_ERR_TOO_MANY_COMMAND_ARGUMENTS too many command arguments

EMBER_CMD_ERR_ARGUMENT_OUT_OF_RANGE integer argument out of range

EMBER_CMD_ERR_ARGUMENT_SYNTAX_ERROR argument syntax error

EMBER_CMD_ERR_STRING_TOO_LONG message too long

EMBER_CMD_ERR_NO_BINARY_STRING_TERMINATOR missing binary message termina-tor

EMBER_CMD_SUCCESSEMBER_CMD_ERR_PORT_PROBLEM

EmberZNet 4.7.2 API EM260 120-3020-000-4720

198

EMBER_CMD_ERR_NO_SUCH_COMMANDEMBER_CMD_ERR_WRONG_NUMBER_OF_ARGUMENTSEMBER_CMD_ERR_ARGUMENT_OUT_OF_RANGEEMBER_CMD_ERR_ARGUMENT_SYNTAX_ERROREMBER_CMD_ERR_STRING_TOO_LONGEMBER_CMD_ERR_INVALID_ARGUMENT_TYPE



6.30.5.1 void emberCommandReaderInit ( EmberCommandState ∗ state )

Initialize a command state.

Parametersstate The command state structure.

6.30.5.2 boolean emberProcessCommandString ( EmberCommandState ∗ state, int8u ∗ input, int8usize )

Parses ’size’ characters from ’input’.

Returns

TRUE if an end of line character was read. If the application uses a command line prompt, thisindeicates it is time to print the prompt.


6.30.6.1 PGM_NO_CONST PGM_P emberCommandErrorNames[ ]

EmberZNet 4.7.2 API EM260 120-3020-000-4720

199

6.31 ZigBee Device Object (ZDO) Information

Modules

• ZigBee Device Object

Macros

• #define ZDO_MESSAGE_OVERHEAD

Device Discovery Functions

• EmberStatus emberNetworkAddressRequest (EmberEUI64 target, boolean reportKids, int8u child-StartIndex)

• EmberStatus emberIeeeAddressRequest (EmberNodeId target, boolean reportKids, int8u childStart-Index, EmberApsOption options)

Service Discovery Functions

• EmberStatus ezspMatchDescriptorsRequest (EmberNodeId target, int16u profile, int8u inCount, int8uoutCount, int16u ∗inClusters, int16u ∗outClusters, EmberApsOption options)

Binding Manager Functions

• EmberStatus ezspEndDeviceBindRequest (EmberNodeId localNodeId, EmberEUI64 localEui64, int8uendpoint, int16u profile, int8u inCount, int8u outCount, int16u ∗inClusters, int16u ∗outClusters,EmberApsOption options)

Function to Decode Address Response Messages

• EmberNodeId ezspDecodeAddressResponse (int8u ∗response, EmberEUI64 eui64Return)


• EmberStatus emberNodeDescriptorRequest (EmberNodeId target, EmberApsOption options)• EmberStatus emberPowerDescriptorRequest (EmberNodeId target, EmberApsOption options)• EmberStatus emberSimpleDescriptorRequest (EmberNodeId target, int8u targetEndpoint, Ember-

ApsOption options)• EmberStatus emberActiveEndpointsRequest (EmberNodeId target, EmberApsOption options)


• EmberStatus emberBindRequest (EmberNodeId target, EmberEUI64 source, int8u sourceEndpoint,int16u clusterId, int8u type, EmberEUI64 destination, EmberMulticastId groupAddress, int8u destination-Endpoint, EmberApsOption options)

• EmberStatus emberUnbindRequest (EmberNodeId target, EmberEUI64 source, int8u sourceEndpoint,int16u clusterId, int8u type, EmberEUI64 destination, EmberMulticastId groupAddress, int8u destination-Endpoint, EmberApsOption options)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

200

Node Manager Functions

• EmberStatus emberLqiTableRequest (EmberNodeId target, int8u startIndex, EmberApsOption op-tions)

• EmberStatus emberRoutingTableRequest (EmberNodeId target, int8u startIndex, EmberApsOptionoptions)

• EmberStatus emberBindingTableRequest (EmberNodeId target, int8u startIndex, EmberApsOptionoptions)

• EmberStatus emberLeaveRequest (EmberNodeId target, EmberEUI64 deviceAddress, int8u leave-RequestFlags, EmberApsOption options)

• EmberStatus emberPermitJoiningRequest (EmberNodeId target, int8u duration, int8u authentication,EmberApsOption options)

• void emberSetZigDevRequestRadius (int8u radius)• int8u emberGetZigDevRequestRadius (void)• int8u emberGetLastZigDevRequestSequence (void)• int8u emberGetLastAppZigDevRequestSequence (void)


For getting information about nodes of a ZigBee network via a ZigBee Device Object (ZDO). See zigbee-device-host.h and zigbee-device-common.h for source code.

The ZDO library provides functions that construct and send several common ZDO requests. It also providesa function for extracting the two addresses from a ZDO address response. The format of all the ZDOrequests and responses that the stack supports is described in stack/include/zigbee-device-stack.h. Sincethe library doesn’t handle all of these requests and responses, the application must construct any otherrequests it wishes to send and decode any other responses it wishes to receive.

The request sending functions do the following:

1. Construct a correctly formatted payload buffer.

2. Fill in the APS frame with the correct values.

3. Send the message by calling either ::ezspSendBroadcast() or ::ezspSendUnicast().

The result of the send is reported to the application as normal via ::ezspMessageSentHandler().

The following code shows an example of an application’s use of emberSimpleDescriptorRequest(). Thecommand interpreter would call this function and supply the arguments.

void sendSimpleDescriptorRequest(EmberCommandState *state){

EmberNodeId target = emberUnsignedCommandArgument(state, 0);

int8u targetEndpoint = emberUnsignedCommandArgument(state, 1);

if (emberSimpleDescriptorRequest(target,targetEndpoint,EMBER_APS_OPTION_NONE)

!= EMBER_SUCCESS) {emberSerialPrintf(SERIAL_PORT, "

emberSimpleDescriptorRequest failed\r\n");}

}

The following code shows an example of an application’s use of ezspDecodeAddressResponse().

EmberZNet 4.7.2 API EM260 120-3020-000-4720

201

void ezspIncomingMessageHandler(EmberIncomingMessageTypetype,

EmberApsFrame *apsFrame,int8u lastHopLqi,int8s lastHopRssi,EmberNodeId sender,int8u bindingIndex,int8u addressIndex,int8u messageLength,int8u *messageContents)

{if (apsFrame->profileId == EMBER_ZDO_PROFILE_ID)

{switch (apsFrame->clusterId) {case NETWORK_ADDRESS_RESPONSE:case IEEE_ADDRESS_RESPONSE:

{EmberEUI64 eui64;EmberNodeId nodeId = ezspDecodeAddressResponse

(messageContents,eui64);

// Use nodeId and eui64 here.break;

}default:

// Handle other incoming ZDO responses here.}

} else {// Handle incoming application messages here.

}}


6.31.2.1 #define ZDO MESSAGE OVERHEAD

ZDO messages start with a sequence number.

Definition at line 16 of file zigbee-device-common.h.


6.31.3.1 EmberStatus emberNetworkAddressRequest ( EmberEUI64 target, boolean reportKids, int8uchildStartIndex )

Request the 16 bit network address of a node whose EUI64 is known.

Parameterstarget The EUI64 of the node.

reportKids TRUE to request that the target list their children in the response.childStartIndex The index of the first child to list in the response. Ignored if reportKids is FALSE.

Returns

An EmberStatus value.

• EMBER_SUCCESS - The request was transmitted successfully.

• EMBER_NO_BUFFERS - Insuffient message buffers were available to construct the request.

• EMBER_NETWORK_DOWN - The node is not part of a network.

• EMBER_NETWORK_BUSY - Transmission of the request failed.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

202

6.31.3.2 EmberStatus emberIeeeAddressRequest ( EmberNodeId target, boolean reportKids, int8uchildStartIndex, EmberApsOption options )

Request the EUI64 of a node whose 16 bit network address is known.

Parameterstarget The network address of the node.


options The options to use when sending the request. See ::emberSendUnicast() for a descrip-tion.

Returns


• EMBER_SUCCESS

• EMBER_NO_BUFFERS

• EMBER_NETWORK_DOWN

• EMBER_NETWORK_BUSY

6.31.3.3 EmberStatus ezspMatchDescriptorsRequest ( EmberNodeId target, int16u profile, int8uinCount, int8u outCount, int16u ∗ inClusters, int16u ∗ outClusters, EmberApsOption options)

Request the specified node to send a list of its endpoints that match the specified application profile and,optionally, lists of input and/or output clusters.

Parameterstarget The node whose matching endpoints are desired. The request can be sent unicast or

broadcast ONLY to the "RX-on-when-idle-address" (0xFFFD) If sent as a broadcast,any node that has matching endpoints will send a response.

profile The application profile to match.inCount The number of input clusters. To not match any input clusters, set this value to 0.

outCount The number of output clusters. To not match any output clusters, set this value to 0.inClusters The list of input clusters.

outClusters The list of output clusters.options The options to use when sending the unicast request. See emberSendUnicast() for a

description. This parameter is ignored if the target is a broadcast address.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

203

Returns

An EmberStatus value. EMBER_SUCCESS, EMBER_NO_BUFFERS, EMBER_NETWORK_DO-WN or EMBER_NETWORK_BUSY.

6.31.3.4 EmberStatus ezspEndDeviceBindRequest ( EmberNodeId localNodeId, EmberEUI64localEui64, int8u endpoint, int16u profile, int8u inCount, int8u outCount, int16u ∗ inClusters,int16u ∗ outClusters, EmberApsOption options )

An end device bind request to the coordinator. If the coordinator receives a second end device bind requestthen a binding is created for every matching cluster.

ParameterslocalNodeId The node ID of the local device.

localEui64 The EUI64 of the local device.endpoint The endpoint to be bound.

profile The application profile of the endpoint.inCount The number of input clusters.

outCount The number of output clusters.inClusters The list of input clusters.

outClusters The list of output clusters.options The options to use when sending the request. See emberSendUnicast() for a description.

Returns


6.31.3.5 EmberNodeId ezspDecodeAddressResponse ( int8u ∗ response, EmberEUI64 eui64Return )

Extracts the EUI64 and the node ID from an address response message.

Parametersresponse The received ZDO message with cluster ID NETWORK_ADDRESS_RESPONSE or

IEEE_ADDRESS_RESPONSE.eui64Return The EUI64 from the response is copied here.

Returns

Returns the node ID from the response if the response status was EMBER_ZDP_SUCCESS. Other-wise, returns EMBER_NULL_NODE_ID.

6.31.3.6 EmberStatus emberNodeDescriptorRequest ( EmberNodeId target, EmberApsOptionoptions )

Request the specified node to send its node descriptor. The node descriptor contains information about thecapabilities of the ZigBee node. It describes logical type, APS flags, frequency band, MAC capabilities

EmberZNet 4.7.2 API EM260 120-3020-000-4720

204

flags, manufacturer code and maximum buffer size. It is defined in the ZigBee Application FrameworkSpecification.

Parameterstarget The node whose node descriptor is desired.

options The options to use when sending the request. See emberSendUnicast() for a description.

Returns


6.31.3.7 EmberStatus emberPowerDescriptorRequest ( EmberNodeId target, EmberApsOptionoptions )

Request the specified node to send its power descriptor. The power descriptor gives a dynamic indicationof the power status of the node. It describes current power mode, available power sources, current powersource and current power source level. It is defined in the ZigBee Application Framework Specification.

Parameterstarget The node whose power descriptor is desired.


Returns


6.31.3.8 EmberStatus emberSimpleDescriptorRequest ( EmberNodeId target, int8u targetEndpoint,EmberApsOption options )

Request the specified node to send the simple descriptor for the specified endpoint. The simple descriptorcontains information specific to a single endpoint. It describes the application profile identifier, applicationdevice identifier, application device version, application flags, application input clusters and applicationoutput clusters. It is defined in the ZigBee Application Framework Specification.

Parameterstarget The node of interest.

targetEndpoint The endpoint on the target node whose simple descriptor is desired.options The options to use when sending the request. See emberSendUnicast() for a description.

Returns


EmberZNet 4.7.2 API EM260 120-3020-000-4720

205

6.31.3.9 EmberStatus emberActiveEndpointsRequest ( EmberNodeId target, EmberApsOptionoptions )

Request the specified node to send a list of its active endpoints. An active endpoint is one for which asimple descriptor is available.

Parameterstarget The node whose active endpoints are desired.


Returns


6.31.3.10 EmberStatus emberBindRequest ( EmberNodeId target, EmberEUI64 source, int8usourceEndpoint, int16u clusterId, int8u type, EmberEUI64 destination, EmberMulticastIdgroupAddress, int8u destinationEndpoint, EmberApsOption options )

Send a request to create a binding entry with the specified contents on the specified node.

Parameterstarget The node on which the binding will be created.

source The source EUI64 in the binding entry.sourceEndpoint The source endpoint in the binding entry.

clusterId The cluster ID in the binding entry.type The type of binding, either UNICAST_BINDING, MULTICAST_BINDING, or U-

NICAST_MANY_TO_ONE_BINDING. UNICAST_MANY_TO_ONE_BINDING isan Ember-specific extension and should be used only when the target is an Ember de-vice.

destination The destination EUI64 in the binding entry for UNICAST_BINDING or UNICAST_-MANY_TO_ONE_BINDING.

groupAddress The group address for the MULTICAST_BINDING.destination-

EndpointThe destination endpoint in the binding entry for the UNICAST_BINDING or UNIC-AST_MANY_TO_ONE_BINDING.


Returns


6.31.3.11 EmberStatus emberUnbindRequest ( EmberNodeId target, EmberEUI64 source, int8usourceEndpoint, int16u clusterId, int8u type, EmberEUI64 destination, EmberMulticastIdgroupAddress, int8u destinationEndpoint, EmberApsOption options )

Send a request to remove a binding entry with the specified contents from the specified node.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

206

Parameterstarget The node on which the binding will be removed.

source The source EUI64 in the binding entry.sourceEndpoint The source endpoint in the binding entry.

clusterId The cluster ID in the binding entry.type The type of binding, either UNICAST_BINDING, MULTICAST_BINDING, or U-

NICAST_MANY_TO_ONE_BINDING. UNICAST_MANY_TO_ONE_BINDING isan Ember-specific extension and should be used only when the target is an Ember de-vice.

destination The destination EUI64 in the binding entry for the UNICAST_BINDING or UNICA-ST_MANY_TO_ONE_BINDING.

groupAddress The group address for the MULTICAST_BINDING.destination-

EndpointThe destination endpoint in the binding entry for the UNICAST_BINDING or UNIC-AST_MANY_TO_ONE_BINDING.


Returns


• EMBER_SUCCESS

• EMBER_NO_BUFFERS _ EMBER_NETWORK_DOWN


6.31.3.12 EmberStatus emberLqiTableRequest ( EmberNodeId target, int8u startIndex,EmberApsOption options )

Request the specified node to send its LQI (neighbor) table. The response gives PAN ID, EUI64, nodeID and cost for each neighbor. The EUI64 is only available if security is enabled. The other fields in theresponse are set to zero. The response format is defined in the ZigBee Device Profile Specification.

Parameterstarget The node whose LQI table is desired.

startIndex The index of the first neighbor to include in the response.options The options to use when sending the request. See emberSendUnicast() for a description.

Returns


6.31.3.13 EmberStatus emberRoutingTableRequest ( EmberNodeId target, int8u startIndex,EmberApsOption options )

Request the specified node to send its routing table. The response gives destination node ID, status andmany-to-one flags, and the next hop node ID. The response format is defined in the ZigBee Device ProfileSpecification.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

207

Parameterstarget The node whose routing table is desired.

startIndex The index of the first route entry to include in the response.options The options to use when sending the request. See emberSendUnicast() for a description.

Returns


6.31.3.14 EmberStatus emberBindingTableRequest ( EmberNodeId target, int8u startIndex,EmberApsOption options )

Request the specified node to send its nonvolatile bindings. The response gives source address, sourceendpoint, cluster ID, destination address and destination endpoint for each binding entry. The responseformat is defined in the ZigBee Device Profile Specification. Note that bindings that have the Ember-specific UNICAST_MANY_TO_ONE_BINDING type are reported as having the standard UNICAST_B-INDING type.

Parameterstarget The node whose binding table is desired.

startIndex The index of the first binding entry to include in the response.options The options to use when sending the request. See emberSendUnicast() for a description.

Returns


6.31.3.15 EmberStatus emberLeaveRequest ( EmberNodeId target, EmberEUI64 deviceAddress,int8u leaveRequestFlags, EmberApsOption options )

Request the specified node to remove the specified device from the network. The device to be removedmust be the node to which the request is sent or one of its children.

Parameterstarget The node which will remove the device.

deviceAddress All zeros if the target is to remove itself from the network or the EUI64 of a child ofthe target device to remove that child.

leaveRequest-Flags

A bitmask of leave options. Include LEAVE_REQUEST_REMOVE_CHILDREN_F-LAG if the target is to remove their children and/or LEAVE_REQUEST_REJOIN_F-LAG if the target is to rejoin the network immediately after leaving.


Returns


EmberZNet 4.7.2 API EM260 120-3020-000-4720

208

6.31.3.16 EmberStatus emberPermitJoiningRequest ( EmberNodeId target, int8u duration, int8uauthentication, EmberApsOption options )

Request the specified node to allow or disallow association.

Parameterstarget The node which will allow or disallow association. The request can be broadcast by us-

ing a broadcast address (0xFFFC/0xFFFD/0xFFFF). No response is sent if the requestis broadcast.

duration A value of 0x00 disables joining. A value of 0xFF enables joining. Any other valueenables joining for that number of seconds.

authentication Controls Trust Center authentication behavior.options The options to use when sending the request. See emberSendUnicast() for a description.

This parameter is ignored if the target is a broadcast address.

Returns


6.31.3.17 void emberSetZigDevRequestRadius ( int8u radius )

Change the default radius for broadcast ZDO requests.

Parametersradius The radius to be used for future ZDO request broadcasts.

6.31.3.18 int8u emberGetZigDevRequestRadius ( void )

Retrieve the default radius for broadcast ZDO requests.

Returns

The radius to be used for future ZDO request broadcasts.

6.31.3.19 int8u emberGetLastZigDevRequestSequence ( void )

Provide access to the application ZDO transaction sequence number for last request. This function hasbeen deprecated and replaced by emberGetLastAppZigDevRequestSequence().

Returns

Last application ZDO transaction sequence number used

6.31.3.20 int8u emberGetLastAppZigDevRequestSequence ( void )

Provide access to the application ZDO transaction sequence number for last request.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

209

Returns

Last application ZDO transaction sequence number used

EmberZNet 4.7.2 API EM260 120-3020-000-4720

210

6.32 ZigBee Device Object

Functions



• EmberStatus emberEnergyScanRequest (EmberNodeId target, int32u scanChannels, int8u scanDuration,int16u scanCount)

• EmberStatus emberSetNetworkManagerRequest (EmberNodeId networkManager, int32u activeChannels)• EmberStatus emberChannelChangeRequest (int8u channel)• EmberStatus emberSendDeviceAnnouncement (void)• int8u emberGetLastStackZigDevRequestSequence (void)


See zigbee-device-stack.h for source code.


6.32.2.1 EmberStatus emberNetworkAddressRequest ( EmberEUI64 target, boolean reportKids, int8uchildStartIndex )

Request the 16 bit network address of a node whose EUI64 is known.

Parameterstarget The EUI64 of the node.


Returns


• EMBER_SUCCESS - The request was transmitted successfully.

• EMBER_NO_BUFFERS - Insuffient message buffers were available to construct the request.

• EMBER_NETWORK_DOWN - The node is not part of a network.

• EMBER_NETWORK_BUSY - Transmission of the request failed.

6.32.2.2 EmberStatus emberIeeeAddressRequest ( EmberNodeId target, boolean reportKids, int8uchildStartIndex, EmberApsOption options )

Request the EUI64 of a node whose 16 bit network address is known.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

211

Parameterstarget The network address of the node.


options The options to use when sending the request. See ::emberSendUnicast() for a descrip-tion.

Returns


• EMBER_SUCCESS




6.32.2.3 EmberStatus emberEnergyScanRequest ( EmberNodeId target, int32u scanChannels, int8uscanDuration, int16u scanCount )

Request that an energy scan be performed and its results returned. This request may only be sent by thecurrent network manager and must be unicast, not broadcast.

Parameterstarget The network address of the node to perform the scan.

scanChannels A mask of the channels to be scanned.scanDuration How long to scan on each channel. Allowed values are 0..5, with the scan times as

specified by 802.15.4 (0 = 31ms, 1 = 46ms, 2 = 77 ms, 3 = 138ms, 4 = 261ms, 5 =507ms).

scanCount The number of scans to be performed on each channel (1 .. 8).

Returns


• EMBER_SUCCESS




6.32.2.4 EmberStatus emberSetNetworkManagerRequest ( EmberNodeId networkManager, int32uactiveChannels )

Broadcasts a request to set the identity of the network manager and the active channel mask. The mask isused when scanning for the network after missing a channel update.

Parametersnetwork-Manager

The network address of the network manager.

activeChannels The new active channel mask.EmberZNet 4.7.2 API EM260 120-3020-000-4720

212

Returns


• EMBER_SUCCESS




6.32.2.5 EmberStatus emberChannelChangeRequest ( int8u channel )

Broadcasts a request to change the channel. This request may only be sent by the current network manager.There is a delay of several seconds from receipt of the broadcast to changing the channel, to allow time forthe broadcast to propagate.

Parameterschannel The channel to change to.

Returns


• EMBER_SUCCESS




6.32.2.6 EmberStatus emberSendDeviceAnnouncement ( void )

Sends a broadcast for a ZDO Device announcement. Normally it is NOT required to call this as the stackautomatically sends a device announcement during joining or rejoining, as per the spec. However if thedevice wishes to re-send its device announcement they can use this call.

Returns


• EMBER_SUCCESS

• EMBER_INVALID_CALL

6.32.2.7 int8u emberGetLastStackZigDevRequestSequence ( void )

Provide access to the stack ZDO transaction sequence number for last request.

Returns

Last stack ZDO transaction sequence number used

EmberZNet 4.7.2 API EM260 120-3020-000-4720

213

6.33 Message Fragmentation

Initialization

• void ezspFragmentInit (int16u receiveBufferLength, int8u ∗receiveBuffer)

Transmitting

• EmberStatus ezspFragmentSendUnicast (EmberOutgoingMessageType type, int16u indexOrDestination,EmberApsFrame ∗apsFrame, int8u maxFragmentSize, int16u messageLength, int8u ∗messageContents)

• EmberStatus ezspFragmentSourceRouteHandler (void)• boolean ezspFragmentMessageSent (EmberApsFrame ∗apsFrame, EmberStatus status)• void ezspFragmentMessageSentHandler (EmberStatus status)

Receiving

• boolean ezspFragmentIncomingMessage (EmberApsFrame ∗apsFrame, EmberNodeId sender, int16u∗messageLength, int8u ∗∗messageContents)

• void ezspFragmentTick (void)


Fragmented message support for EZSP Hosts. Splits long messages into smaller blocks for transmissionand reassembles received blocks. See fragment-host.c for source code.

::EZSP_CONFIG_FRAGMENT_WINDOW_SIZE controls how many blocks are sent at a time. ::EZSP-_CONFIG_FRAGMENT_DELAY_MS controls the spacing between blocks.

Before calling any of the other functions listed here, the application must call ezspFragmentInit().

To send a long message, the application calls ezspFragmentSendUnicast(). The application must add a callto ezspFragmentMessageSent() at the start of its ezspMessageSentHandler(). If ezspFragmentMessage-Sent() returns TRUE, the fragmentation code has handled the event and the application must not process itfurther. The fragmentation code calls the application-defined ezspFragmentMessageSentHandler() when ithas finished sending the long message.

To receive a long message, the application must add a call to ezspFragmentIncomingMessage() at the startof its ezspIncomingMessageHandler(). If ezspFragmentIncomingMessage() returns TRUE, the fragmen-tation code has handled the message and the application must not process it further. The application mustalso call ezspFragmentTick() regularly.


6.33.2.1 void ezspFragmentInit ( int16u receiveBufferLength, int8u ∗ receiveBuffer )

Initialize variables and buffers used for sending and receiving long messages. This functions reads the val-ues of ::EZSP_CONFIG_MAX_HOPS and ::EZSP_CONFIG_FRAGMENT_WINDOW_SIZE. The ap-plication must set these values before calling this function.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

214

ParametersreceiveBuffer-

LengthThe length of receiveBuffer. Incoming messages longer than this will be dropped.

receiveBuffer The buffer used to reassemble incoming long messages. Once the message is complete,this buffer will be passed back to the application by ezspFragmentIncomingMessage().

6.33.2.2 EmberStatus ezspFragmentSendUnicast ( EmberOutgoingMessageType type, int16uindexOrDestination, EmberApsFrame ∗ apsFrame, int8u maxFragmentSize, int16umessageLength, int8u ∗ messageContents )

Sends a long message by splitting it into blocks. Only one long message can be sent at a time. Calling thisfunction a second time aborts the first message.

Parameterstype Specifies the outgoing message type. Must be one of EMBER_OUTGOING_DIRE-

CT, EMBER_OUTGOING_VIA_ADDRESS_TABLE, or EMBER_OUTGOING_V-IA_BINDING.

indexOr-Destination

Depending on the type of addressing used, this is either the EmberNodeId of the desti-nation, an index into the address table, or an index into the binding table.

apsFrame The APS frame for the message.maxFragment-

SizeThe message will be broken into blocks no larger than this.

messageLength The length of the messageContents parameter in bytes.message-Contents

The long message to be sent.

Returns


• EMBER_SUCCESS

• EMBER_MESSAGE_TOO_LONG



• EMBER_INVALID_CALL is returned if messageLength is zero or if the window size (::EZSP-_CONFIG_FRAGMENT_WINDOW_SIZE) is zero.

6.33.2.3 EmberStatus ezspFragmentSourceRouteHandler ( void )

A callback invoked just before each block of the current long message is sent. If the message is to be sourcerouted, the application must define this callback and call ezspSetSourceRoute() in it.

The application must define EZSP_APPLICATION_HAS_FRAGMENT_SOURCE_ROUTE_HANDLE-R in its configuration header if it defines this callback.

Returns

EMBER_SUCCESS if the source route has been set. Any other value will abort transmission of thecurrent long message.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

215

6.33.2.4 boolean ezspFragmentMessageSent ( EmberApsFrame ∗ apsFrame, EmberStatus status )

The application must call this function at the start of its ezspMessageSentHandler(). If it returns TRUE,the fragmentation code has handled the event and the application must not process it further.

ParametersapsFrame The APS frame passed to ezspMessageSentHandler().

status The status passed to ezspMessageSentHandler().

Returns

TRUE if the sent message was a block of a long message. The fragmentation code has handled theevent so the application must return immediately from its ezspMessageSentHandler(). Returns FAL-SE otherwise. The fragmentation code has not handled the event so the application must continue toprocess it.

6.33.2.5 void ezspFragmentMessageSentHandler ( EmberStatus status )

The fragmentation code calls this application-defined handler when it finishes sending a long message.

Parametersstatus EMBER_SUCCESS if all the blocks of the long message were delivered to the desti-

nation, otherwise EMBER_DELIVERY_FAILED, EMBER_NETWORK_DOWN orEMBER_NETWORK_BUSY.

6.33.2.6 boolean ezspFragmentIncomingMessage ( EmberApsFrame ∗ apsFrame, EmberNodeIdsender, int16u ∗ messageLength, int8u ∗∗ messageContents )

The application must call this function at the start of its ezspIncomingMessageHandler(). If it returns TR-UE, the fragmentation code has handled the message and the application must not process it further. Whenthe final block of a long message is received, this function replaces the message with the reassembled longmessage and returns FALSE so that the application processes it.

ParametersapsFrame The APS frame passed to ezspIncomingMessageHandler().

sender The sender passed to ezspIncomingMessageHandler().messageLength A pointer to the message length passed to ezspIncomingMessageHandler().

message-Contents

A pointer to the message contents passed to ezspIncomingMessageHandler().

Returns

TRUE if the incoming message was a block of an incomplete long message. The fragmentation codehas handled the message so the application must return immediately from its ezspIncomingMessage-Handler(). Returns FALSE if the incoming message was not part of a long message. The fragmentationcode has not handled the message so the application must continue to process it. Returns FALSE ifthe incoming message was a block that completed a long message. The fragmentation code replacesthe message with the reassembled long message so the application must continue to process it.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

216

6.33.2.7 void ezspFragmentTick ( void )

Used by the fragmentation code to time incoming blocks. The application must call this function regularly.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

217

6.34 Network Manager

Macros

• #define NM_WARNING_LIMIT• #define NM_WINDOW_SIZE• #define NM_CHANNEL_MASK• #define NM_WATCHLIST_SIZE

Functions

• void nmUtilWarningHandler (void)• boolean nmUtilProcessIncoming (EmberApsFrame ∗apsFrame, int8u messageLength, int8u ∗message)• EmberStatus nmUtilChangeChannelRequest (void)


The network manager is an optional function of one device in the ZigBee network. Devices on the networksend unsolicited ZDO energy scan reports to the network manager when more than 25% of unicasts failwithin a rolling window, but no more than once every 15 minutes.

See network-manager.h for source code.

The network manager is the coordinator by default but can be changed via emberSetNetworkManager-Request(). It processes the energy scan reports from the devices on the network, and is responsible fordetermining if the network should change channels in an attempt to resolve reliability problems that mightbe caused by RF interference.

Note that EmberZNet networks are quite robust to many interferers such as 802.11 (WiFi), and the presenceof interferers does not necessarily degrade application performance or require a channel change. Becausechanging channels is disruptive to network operation, channel changes should not be done solely becauseof observed higher noise levels, as the noise may not be causing any problem.

Also note that receipt of unsolicited scan reports is only an indication of unicast failures in the network.These might be caused by RF interference, or for some other reason such as a device failure. In addition,only the application can tell whether the delivery failures caused an actual problem for the application. Ingeneral, it is difficult to automatically determine with certainty that network problems are caused by RFinterference. Channel changes should therefore be done sparingly and with careful application design.

The stack provides three APIs in include/zigbee-device-stack.h:

• emberEnergyScanRequest

• emberSetNetworkManagerRequest

• emberChannelChangeRequest

This library provides some additional functions:

• nmUtilProcessIncomingMessage

• nmUtilWarningHandler

• nmUtilChangeChannelRequest

EmberZNet 4.7.2 API EM260 120-3020-000-4720

218

An application implementing network manager functionality using this library should pass all incomingmessages to nmUtilProcessIncomingMessage, which will return TRUE if the message was processed as aZDO energy scan report. The application should not make any calls to emberEnergyScanRequest(), as thelibrary assumes all incoming scan reports are unsolicited and indicate unicast failures.

When NM_WARNING_LIMIT reports have been processed within NM_WINDOW_SIZE minutes, thenmUtilWarningHandler callback, which must be implemented by the application, is invoked. The defaultvalues for these parameters are set in network-manager.h and may be modified using #defines within theapplication configuration header.

The application may use the nmUtilWarningHandler callback, along with other application-specific in-formation, to decide if and when to change the channel by calling nmUtilChangeChannelRequest. Thisfunction chooses a new channel from the NM_CHANNEL_MASK parameter using information gatheredover time.

In the event of a network-wide channel change, it is possible that some devices, especially sleepy enddevices, do not receive the broadcast and remain on the old channel. Devices should use the API ember-FindAndRejoinNetwork to get back to the right channel.

Two implementations of this library are provided: network-manager.c, and network-manager-lite.c. Theformer keeps track of the mean and deviation of the energy on each channel and uses these stats to choosethe channel to change to. This consumes a fair amount of RAM. The latter takes the simpler (and possiblymore effective) approach of just avoiding past bad channels. Application developers are encouraged to useand modify either of these solutions to take into account their own application-specific needs.


6.34.2.1 #define NM WARNING LIMIT

Definition at line 97 of file network-manager.h.

6.34.2.2 #define NM WINDOW SIZE


6.34.2.3 #define NM CHANNEL MASK


6.34.2.4 #define NM WATCHLIST SIZE



6.34.3.1 void nmUtilWarningHandler ( void )

callback called when unsolicited scan reports hit limit. This callback must be implemented by the appli-cation. It is called when the number of unsolicited scan reports received within NM_WINDOW_LIMITminutes reaches NM_WARNING_LIMIT.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

219

6.34.3.2 boolean nmUtilProcessIncoming ( EmberApsFrame ∗ apsFrame, int8u messageLength, int8u∗ message )

Called from the app in emberIncomingMessageHandler. Returns TRUE if and only if the library processedthe message.

ParametersapsFrame

messageLengthmessage

6.34.3.3 EmberStatus nmUtilChangeChannelRequest ( void )

Chooses a new channel and broadcasts a ZDO channel change request.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

220

6.35 Serial Communication

Macros

• #define emberSerialWriteUsed(port)• #define SERIAL_PORT_RAW• #define SERIAL_PORT_CLI

Functions

• EmberStatus emberSerialInit (int8u port, SerialBaudRate rate, SerialParity parity, int8u stopBits)• int16u emberSerialReadAvailable (int8u port)• EmberStatus emberSerialReadByte (int8u port, int8u ∗dataByte)• EmberStatus emberSerialReadData (int8u port, int8u ∗data, int16u length, int16u ∗bytesRead)• EmberStatus emberSerialReadDataTimeout (int8u port, int8u ∗data, int16u length, int16u ∗bytes-

Read, int16u firstByteTimeout, int16u subsequentByteTimeout)• EmberStatus emberSerialReadLine (int8u port, char ∗data, int8u max)• EmberStatus emberSerialReadPartialLine (int8u port, char ∗data, int8u max, int8u ∗index)• int16u emberSerialWriteAvailable (int8u port)• EmberStatus emberSerialWriteByte (int8u port, int8u dataByte)• EmberStatus emberSerialWriteHex (int8u port, int8u dataByte)• EmberStatus emberSerialWriteString (int8u port, PGM_P string)• XAP2B_PAGEZERO_ON EmberStatus emberSerialPrintf (int8u port, PGM_P formatString,...)• XAP2B_PAGEZERO_OFF

XAP2B_PAGEZERO_ON EmberStatus emberSerialPrintfLine (int8u port, PGM_P formatString,...)• XAP2B_PAGEZERO_OFF

XAP2B_PAGEZERO_ON EmberStatus emberSerialPrintCarriageReturn (int8u port)• XAP2B_PAGEZERO_OFF EmberStatus emberSerialPrintfVarArg (int8u port, PGM_P formatString,

va_list ap)• EmberStatus emberSerialWriteData (int8u port, int8u ∗data, int8u length)• EmberStatus emberSerialWriteBuffer (int8u port, EmberMessageBuffer buffer, int8u start, int8u

length)• XAP2B_PAGEZERO_ON EmberStatus emberSerialWaitSend (int8u port)• XAP2B_PAGEZERO_OFF EmberStatus emberSerialGuaranteedPrintf (int8u port, PGM_P format-

String,...)• void emberSerialBufferTick (void)• void emberSerialFlushRx (int8u port)• void emberSerialSetPrompt (const char ∗thePrompt)• void emberSerialCleanup (void)• int emberSerialGetInputFd (int8u port)• void emberSerialCommandCompletionInit (EmberCommandEntry ∗listOfCommands)• void emberSerialCommandCompletionInitCli (cliSerialCmdEntry ∗cliCmdList, int cliCmdListLength)

Printf Prototypes

These prototypes are for the internal printf implementation, in case it is desired to use it elsewhere. See thecode for emberSerialPrintf() for an example of printf usage.

• typedef EmberStatus( emPrintfFlushHandler )(int8u flushVar, int8u ∗contents, int8u length)• int8u emPrintfInternal (emPrintfFlushHandler flushHandler, int8u port, PGM_P string, va_list args)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

221


Unless otherwise noted, the EmberNet stack does not use these functions, and therefore the HAL is notrequired to implement them. However, many of the supplied example applications do use them. On someplatforms, they are also required by DEBUG builds of the stack

Many of these functions return an EmberStatus value. See stack/include/error-defs.h for definitions of allEmberStatus return values. See app/util/serial/serial.h for source code. To use these serial routines, theymust be properly configured.

If the Ember serial library is built using EMBER_SERIAL_USE_STDIO, then the Ember serial code willredirect to stdio.h. EMBER_SERIAL_USE_STDIO will not consume any of the usual Ember serial librarybuffers and does not require use of any of the other EMBER_SERIALx definitions described here. In thismode, the only required lower layers are:

• putchar()

• getchar()

• fflush(stdout)

• halInternalUartInit()

• halInternalPrintfWriteAvailable()

• halInternalPrintfReadAvailable()

• halInternalForcePrintf()

The functions can work in two ways, depending on how messages waiting for transmission arestored:

– Buffered mode: Uses stack linked buffers. This method can be more efficient if many messagesreceived over the air also need to be transmitted over the serial interface.

– FIFO mode: Uses a statically allocated queue of bytes, and data to be transmitted is copied intothe queue.

(These modes deal only with data transmission. Data reception always occurs in a FIFO mode.)

The current version of these sources provides support for as many as two serial ports, but it can be easilyextended. The ports are numbered 0 and 1 and should be accessed using those numbers. The ports can beset up independently of each other.

To enable a port, a Use mode (buffered or FIFO) and a Queue Size must be declared on the port. In FIFOmode, the Queue Size is the size of the FIFO and represents the number of bytes that can be waiting fortransmission at any given time. In buffered mode, the Queue Size represents the number of whole messagesthat can be waiting for transmission at any given time. A single message is created for each call to any ofthe serial APIs.

To specify a Use mode and Queue Size, place declarations in the compiler preprocessor options whenbuilding your application:

• Use Mode:

– ::EMBER_SERIAL0_MODE=EMBER_SERIAL_BUFFER or EMBER_SERIAL_FIFO

– ::EMBER_SERIAL1_MODE=EMBER_SERIAL_BUFFER or EMBER_SERIAL_FIFO

• Queue Size:

– ::EMBER_SERIAL0_TX_QUEUE_SIZE=2

EmberZNet 4.7.2 API EM260 120-3020-000-4720

222

– ::EMBER_SERIAL0_RX_QUEUE_SIZE=4

– ::EMBER_SERIAL1_TX_QUEUE_SIZE=8

– ::EMBER_SERIAL1_RX_QUEUE_SIZE=16

Note the following:

• If buffered mode is declared, emberSerialBufferTick() should be called in the application’s mainevent loop.

• If buffered mode is declared, the Tx queue size MUST be <= 255

• On the AVR platform, Rx & Tx queue sizes are limited to powers of 2 <= 128

• By default, both ports are unused.

You can also use declarations to specify what should be done if an attempt is made to send more data thanthe queue can accommodate:

• ::EMBER_SERIAL0_BLOCKING

• ::EMBER_SERIAL1_BLOCKING

Be aware that since blocking spins in a loop, doing nothing until space is available, it can adversely affectany code that has tight timing requirements.

If ::EMBER_SERIAL0_BLOCKING or ::EMBER_SERIAL1_BLOCKING is defined, then the call to theport will block until space is available, guaranteeing that the entire message is sent. Note that in bufferedmode, even if blocking mode is in effect entire messages may be dropped if insufficient stack buffers areavailable to hold them. When this happens, EMBER_NO_BUFFERS is returned.

If no blocking mode is defined, the serial code defaults to non-blocking mode. In this event, when thequeue is too short, the data that don’t fit are dropped. In FIFO mode, this may result bytes being dropped,starting in the middle of message. In buffered mode, the entire message is dropped. When data is dropped,::EMBER_SERIALTX_OVERFLOW is returned.

To minimize code size, very little error checking is done on the given parameters. Specifying an invalidor unused serial port may result in unexplained behavior. In some cases EMBER_ERR_FATAL may bereturned.


6.35.2.1 #define emberSerialWriteUsed( port )

Returns the number of bytes (in FIFO mode) or messages (in buffered mode) that are currently queued andstill being sent.

Parametersport A serial port number (0 or 1).

Returns

The number of bytes or messages available for queueing.

Definition at line 297 of file app/util/serial/serial.h.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

223

6.35.2.2 #define SERIAL PORT RAW

Definition at line 17 of file linux-serial.h.

6.35.2.3 #define SERIAL PORT CLI

Definition at line 18 of file linux-serial.h.


6.35.3.1 typedef EmberStatus( emPrintfFlushHandler)(int8u flushVar, int8u ∗contents, int8u length)

Typedefine to cast a function into the appropriate format to be used inside the emPrintfInternalfunction below, for performing the actual flushing of a formatted string to a destination such as a serialport.

ParametersflushVar,: The destination of the flush, most commonly a serial port number (0 or 1).contents A pointer to the string to flush.

length The number of bytes to flush.

Returns

The EmberStatus value of the typedefined function.

Definition at line 536 of file app/util/serial/serial.h.


6.35.4.1 EmberStatus emberSerialInit ( int8u port, SerialBaudRate rate, SerialParity parity, int8ustopBits )

Initializes a serial port to a specific baud rate, parity, and number of stop bits. Eight data bits are alwaysused.

Parametersport A serial port number (0 or 1).rate The baud rate (see SerialBaudRate).

parity The parity value (see SerialParity).stopBits The number of stop bits.

Returns

An error code if initialization failed (such as invalid baudrate), or EMBER_SUCCESS.

6.35.4.2 int16u emberSerialReadAvailable ( int8u port )

Returns the number of bytes currently available for reading in the specified RX queue.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

224


Returns

The number of bytes available.

6.35.4.3 EmberStatus emberSerialReadByte ( int8u port, int8u ∗ dataByte )

Reads a byte from the specified RX queue. If an error is returned, the dataByte should be ignored. Forerrors other than EMBER_SERIAL_RX_EMPTY multiple bytes of data may have been lost and serialprotocols should attempt to resynchronize.


dataByte A pointer to storage location for the byte.

Returns


• EMBER_SERIAL_RX_EMPTY if no data is available

• EMBER_SERIAL_RX_OVERFLOW if the serial receive fifo was out of space

• EMBER_SERIAL_RX_FRAME_ERROR if a framing error was received

• EMBER_SERIAL_RX_PARITY_ERROR if a parity error was received

• EMBER_SERIAL_RX_OVERRUN_ERROR if the hardware fifo was out of space

• EMBER_SUCCESS if a data byte is returned

6.35.4.4 EmberStatus emberSerialReadData ( int8u port, int8u ∗ data, int16u length, int16u ∗bytesRead )

Reads bytes from the specified RX queue. Blocks until the full length has been read or an error occurs. Inthe event of an error, some valid data may have already been read before the error occurred, in which casethat data will be in the buffer pointed to by data and the number of bytes successfully read will be placedin bytesRead.

Parametersport A serial port number (0 or 1).data A pointer to storage location for the data. It must be at least length in size.

length The number of bytes to read.bytesRead A pointer to a location that will receive the number of bytes read. If the function returns

early due to an error, this value may be less than length. This parameter may be N-ULL, in which case it is ignored.

Returns


EmberZNet 4.7.2 API EM260 120-3020-000-4720

225





• EMBER_SUCCESS if all the data requested is returned

6.35.4.5 EmberStatus emberSerialReadDataTimeout ( int8u port, int8u ∗ data, int16u length, int16u ∗bytesRead, int16u firstByteTimeout, int16u subsequentByteTimeout )

Reads bytes from the specified RX queue, up to a maximum of length bytes. The function may returnbefore length bytes is read if a timeout is reached or an error occurs. Returns EMBER_SERIAL_RX_-EMPTY if a timeout occurs.

Parametersport A serial port number (0 or 1).data A pointer to storage location for the data. It must be at least length in size.

length The maximum number of bytes to read.bytesRead A pointer to a location that will receive the number of bytes read. If the function returns

early due to an error or timeout, this value may be less than length. This parametermay be NULL, in which case it is ignored.

firstByte-Timeout

The amount of time, in milliseconds, to wait for the first byte to arrive (if the queueis empty when the function is called). This value must be a minimum of 2 due to thetimer resolution.

subsequent-ByteTimeout

The amount of time, in milliseconds, to wait after the previous byte was received forthe next byte to arrive. This value must be a minimum of 2 due to the timer resolution.

Returns


• EMBER_SERIAL_RX_EMPTY if the timeout was exceeded before the requested amount ofdata was read





• EMBER_SUCCESS if all the data requested is returned

6.35.4.6 EmberStatus emberSerialReadLine ( int8u port, char ∗ data, int8u max )

Simulates a terminal interface, reading a line of characters at a time. Supports backspace. Always convertsto uppercase. Blocks until a line has been read or max has been exceeded. Calls on halResetWatchdog().

Parametersport A serial port number (0 or 1).data A pointer to storage location for the read line. There must be max contiguous bytes

available at this location.max The maximum number of bytes to read.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

226

Returns

EMBER_SUCCESS

6.35.4.7 EmberStatus emberSerialReadPartialLine ( int8u port, char ∗ data, int8u max, int8u ∗ index )

Simulates a partial terminal interface, reading a line of characters at a time. Supports backspace. Alwaysconverts to uppercase. returns EMBER_SUCCESS when a line has been read or max has been exceeded.Must initialize the index variable to 0 to start a line.

Parametersport A serial port number (0 or 1).data A pointer to storage location for the read line. There must be max contiguous bytes

available at this location.max The maximum number of bytes to read.

index The address of a variable that holds the place in the data to continue. Set to 0 to starta line read.

Returns


• EMBER_SERIAL_RX_EMPTY if a partial line is in progress.

• EMBER_SERIAL_RX_OVERFLOW if the serial receive fifo was out of space.

• EMBER_SERIAL_RX_FRAME_ERROR if a framing error was received.

• EMBER_SERIAL_RX_PARITY_ERROR if a parity error was received.

• EMBER_SERIAL_RX_OVERRUN_ERROR if the hardware fifo was out of space.

• EMBER_SUCCESS if a full ine is ready.

6.35.4.8 int16u emberSerialWriteAvailable ( int8u port )

Returns the number of bytes (in FIFO mode) or messages (in buffered mode) that can currently be queuedto send without blocking or dropping.


Returns

The number of bytes or messages available for queueing.

6.35.4.9 EmberStatus emberSerialWriteByte ( int8u port, int8u dataByte )

Queues a single byte of data for transmission on the specified port.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

227


dataByte The byte to be queued.

Returns


• EMBER_SERIAL_TX_OVERFLOW indicates that data was dropped.

• EMBER_NO_BUFFERS indicates that there was an insufficient number of available stack buffers.

• EMBER_SUCCESS.

6.35.4.10 EmberStatus emberSerialWriteHex ( int8u port, int8u dataByte )

Converts a given byte of data to its two-character ASCII hex representation and queues it for transmissionon the specified port. Values less than 0xF are always zero padded and queued as "0F".


dataByte The byte to be converted.

Returns




• EMBER_SUCCESS.

6.35.4.11 EmberStatus emberSerialWriteString ( int8u port, PGM_P string )

Queues a string for transmission on the specified port.


string The string to be queued.

Returns




• EMBER_SUCCESS.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

228

6.35.4.12 XAP2B PAGEZERO ON EmberStatus emberSerialPrintf ( int8u port, PGM_P formatString, ...)

Printf for printing on a specified port. Supports the following format specifiers:

• %% percent sign

• c single-byte character

• s RAM string

• p flash string (nonstandard specifier)

• u 2-byte unsigned decimal

• d 2-byte signed decimal

• l 4-byte signed decimal

• x %2x %4x 1-, 2-, 4-byte hex value (always 0 padded) (nonstandard specifier)



Returns




• EMBER_SUCCESS.

6.35.4.13 XAP2B PAGEZERO OFF XAP2B PAGEZERO ON EmberStatus emberSerialPrintfLine ( int8uport, PGM_P formatString, ... )

Printf for printing on a specified port. Same as emberSerialPrintf() except it prints a carriage return at thethe end of the text.



Returns



EmberZNet 4.7.2 API EM260 120-3020-000-4720

229

6.35.4.14 XAP2B PAGEZERO OFF XAP2B PAGEZERO ON EmberStatus emberSerialPrintCarriageReturn( int8u port )

Prints "\r\n" to the specified serial port.


Returns




• EMBER_SUCCESS.

6.35.4.15 XAP2B PAGEZERO OFF EmberStatus emberSerialPrintfVarArg ( int8u port, PGM_PformatString, va list ap )

Prints a format string with a variable argument list.


formatString A printf style format string.ap A variable argument list.

Returns




• EMBER_SUCCESS.

6.35.4.16 EmberStatus emberSerialWriteData ( int8u port, int8u ∗ data, int8u length )

Queues an arbitrary chunk of data for transmission on a specified port.

Parametersport A serial port number (0 or 1).data A pointer to data.

length The number of bytes to queue.

Returns



EmberZNet 4.7.2 API EM260 120-3020-000-4720

230


• EMBER_SUCCESS.

6.35.4.17 EmberStatus emberSerialWriteBuffer ( int8u port, EmberMessageBuffer buffer, int8u start,int8u length )

Queues data contained in linked stack buffers for transmission on a specified port. Can specify an arbitraryinitial offset within the linked buffer chain.


buffer The starting buffer in linked buffer chain.start The offset from first buffer in chain.

length The number of bytes to queue.

Returns




• EMBER_SUCCESS.

6.35.4.18 XAP2B PAGEZERO ON EmberStatus emberSerialWaitSend ( int8u port )

Waits for all data currently queued on the specified port to be transmitted before returning. Note: Call thisfunction before serial reinitialization to ensure that transmission is complete.


Returns



6.35.4.19 XAP2B PAGEZERO OFF EmberStatus emberSerialGuaranteedPrintf ( int8u port, PGM_PformatString, ... )

A printf routine that takes over the specified serial port and immediately transmits the given data regardlessof what is currently queued. Does not return until the transmission is complete.

Application Usage:

Useful for fatal situations (such as asserts) where the node will be reset, but information on the causefor the reset needs to be transmitted first.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

231


formatString The string to print.... Formatting specifiers. See emberSerialPrintf() for arguments.

Returns




• EMBER_SUCCESS.

6.35.4.20 void emberSerialBufferTick ( void )

When a serial port is used in buffered mode, this must be called in an application’s main event loop, similarto emberTick(). It frees buffers that are used to queue messages. Note: This function has no effect if FIFOmode is being used.

6.35.4.21 void emberSerialFlushRx ( int8u port )

Flushes the receive buffer in case none of the incoming serial data is wanted.


6.35.4.22 int8u emPrintfInternal ( emPrintfFlushHandler flushHandler, int8u port, PGM_P string,va list args )

The internal printf function, which scans the string for the format specifiers and appropriately implants thepassed data into the string.

ParametersflushHandler,: The name of an internal function, which has parameters matching the function em-

PrintfFlushHandler above, responsible for flushing a string formatted by thisfunction, emPrintfInternal, to the appropriate buffer or function that performsthe actual transmission.

port The destination of the flush performed above, most commonly serial port number (0 or1).

string The string to print.args The list of arguments for the format specifiers.

Returns

The number of characters written.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

232

6.35.4.23 void emberSerialSetPrompt ( const char ∗ thePrompt )

6.35.4.24 void emberSerialCleanup ( void )

6.35.4.25 int emberSerialGetInputFd ( int8u port )

6.35.4.26 void emberSerialCommandCompletionInit ( EmberCommandEntry ∗ listOfCommands )

6.35.4.27 void emberSerialCommandCompletionInitCli ( cliSerialCmdEntry ∗ cliCmdList, intcliCmdListLength )

EmberZNet 4.7.2 API EM260 120-3020-000-4720

233

6.36 ASH Application Utility

Data Structures

• struct AshHostConfigConfiguration parameters: values must be defined before calling ashResetNcp() or ashStart(). Note that alltimes are in milliseconds.

• struct AshCount• struct ashBuffer

Buffer to hold a DATA frame.• struct AshQueue

Simple queue (singly-linked list)• struct AshFreeList

Simple free list (singly-linked list)

Macros

• #define ASH_MAX_TIMEOUTS• #define ASH_MAX_WAKE_TIME• #define ASH_PORT_LEN• #define TRACE_FRAMES_BASIC• #define TRACE_FRAMES_VERBOSE• #define TRACE_EVENTS• #define TRACE_EZSP• #define TRACE_EZSP_VERBOSE• #define ASH_RESET_METHOD_RST• #define ASH_RESET_METHOD_DTR• #define ASH_RESET_METHOD_CUSTOM• #define ASH_RESET_METHOD_NONE• #define ASH_NCP_TYPE_EM2XX_EM3XX• #define ASH_HOST_CONFIG_EM2XX_EM3XX_115200_RTSCTS• #define ASH_HOST_CONFIG_EM2XX_EM3XX_57600_XONXOFF• #define ashReadConfig(member)• #define ashReadConfigOrDefault(member, defval)• #define ashWriteConfig(member, value)• #define BUMP_HOST_COUNTER(mbr)• #define ADD_HOST_COUNTER(op, mbr)• #define DEBUG_STREAM• #define ashDebugPrintf(...)• #define ashDebugVfprintf(format, argPointer)• #define TX_POOL_BUFFERS• #define RX_FREE_LWM• #define RX_FREE_HWM• #define BUMP_HOST_COUNTER(mbr)• #define ADD_HOST_COUNTER(op, mbr)

Typedefs

• typedef struct ashBuffer AshBuffer

EmberZNet 4.7.2 API EM260 120-3020-000-4720

234

Functions

• EzspStatus ashSelectHostConfig (int8u config)• EzspStatus ashStart (void)• void ashStop (void)• EzspStatus ashSend (int8u len, const int8u ∗inptr)• EzspStatus ashResetNcp (void)• EzspStatus ashWakeUpNcp (boolean init)• boolean ashIsConnected (void)• void ashSendExec (void)• EzspStatus ashReceiveExec (void)• EzspStatus ashReceive (int8u ∗len, int8u ∗buffer)• boolean ashOkToSleep (void)• EzspStatus ashSerialInit (void)• void ashSerialClose (void)• void ashResetDtr (void)• void ashResetCustom (void)• EzspStatus ashSerialWriteAvailable (void)• void ashSerialWriteByte (int8u byte)• void ashSerialWriteFlush (void)• EzspStatus ashSerialReadByte (int8u ∗byte)• EzspStatus ashSerialReadAvailable (int16u ∗count)• void ashSerialReadFlush (void)• void ashDebugFlush (void)• int ashSerialGetFd (void)• boolean ashSerialOutputIsIdle (void)• void ashInitQueues (void)• void ashFreeBuffer (AshFreeList ∗list, AshBuffer ∗buffer)• AshBuffer ∗ ashAllocBuffer (AshFreeList ∗list)• AshBuffer ∗ ashRemoveQueueHead (AshQueue ∗queue)• AshBuffer ∗ ashQueueHead (AshQueue ∗queue)• AshBuffer ∗ ashQueueNthEntry (AshQueue ∗queue, int8u n)• AshBuffer ∗ ashQueuePrecedingEntry (AshQueue ∗queue, AshBuffer ∗buffer)• AshBuffer ∗ ashRemoveQueueEntry (AshQueue ∗queue, AshBuffer ∗buffer)• int8u ashQueueLength (AshQueue ∗queue)• int8u ashFreeListLength (AshFreeList ∗list)• void ashAddQueueTail (AshQueue ∗queue, AshBuffer ∗buffer)• boolean ashQueueIsEmpty (AshQueue ∗queue)• void ashPrintUsage (char ∗name)• boolean ashProcessCommandOptions (int argc, char ∗argv[ ])• void ashTraceEvent (const char ∗string)• void ashPrintCounters (AshCount ∗counters, boolean clear)• void ashClearCounters (AshCount ∗counters)• const int8u ∗ ashErrorString (int8u error)• const int8u ∗ ashEzspErrorString (int8u error)• void ashTraceFrame (boolean sent)• void ashTraceEventRecdFrame (const char ∗string)• void ashTraceEventTime (const char ∗string)• void ashTraceDisconnected (int8u error)• void ashTraceArray (int8u ∗name, int8u len, int8u ∗data)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

235

• void ashTraceEzspFrameId (const char ∗message, int8u ∗ezspFrame)• void ashTraceEzspVerbose (char ∗format,...)• void ashCountFrame (boolean sent)• int8u readTxControl (void)• int8u readRxControl (void)• int8u readAckRx (void)• int8u readAckTx (void)• int8u readFrmTx (void)• int8u readFrmReTx (void)• int8u readFrmRx (void)• int8u readAshTimeouts (void)

Variables

• EzspStatus ashError• EzspStatus ncpError• AshHostConfig ashHostConfig• AshCount ashCount• boolean ncpSleepEnabled• AshQueue txQueue• AshQueue reTxQueue• AshQueue rxQueue• AshFreeList txFree• AshFreeList rxFree


See also Asynchronous Serial Host (ASH) Framework.

See ash-host.h.

See ash-host-io.h.

See ash-host-queues.h.

See ash-host-ui.h.

See ash-host-priv.h.


6.36.2.1 #define ASH MAX TIMEOUTS

timeouts before link is judged down

Definition at line 19 of file ash-host.h.

6.36.2.2 #define ASH MAX WAKE TIME

max time in msecs for ncp to wake


EmberZNet 4.7.2 API EM260 120-3020-000-4720

236

6.36.2.3 #define ASH PORT LEN

length of serial port name string


6.36.2.4 #define TRACE FRAMES BASIC

frames sent and received


6.36.2.5 #define TRACE FRAMES VERBOSE

basic frames + internal variables


6.36.2.6 #define TRACE EVENTS

events


6.36.2.7 #define TRACE EZSP

EZSP commands, responses and callbacks


6.36.2.8 #define TRACE EZSP VERBOSE

additional EZSP information


6.36.2.9 #define ASH RESET METHOD RST

send RST frame


6.36.2.10 #define ASH RESET METHOD DTR

reset using DTR


6.36.2.11 #define ASH RESET METHOD CUSTOM

hook for user-defined reset


EmberZNet 4.7.2 API EM260 120-3020-000-4720

237

6.36.2.12 #define ASH RESET METHOD NONE

no reset - for testing


6.36.2.13 #define ASH NCP TYPE EM2XX EM3XX

EM2XX or EM3XX


6.36.2.14 #define ASH HOST CONFIG EM2XX EM3XX 115200 RTSCTS


6.36.2.15 #define ASH HOST CONFIG EM2XX EM3XX 57600 XONXOFF


6.36.2.16 #define ashReadConfig( member )


6.36.2.17 #define ashReadConfigOrDefault( member, defval )


6.36.2.18 #define ashWriteConfig( member, value )


6.36.2.19 #define BUMP HOST COUNTER( mbr )


6.36.2.20 #define ADD HOST COUNTER( op, mbr )


6.36.2.21 #define DEBUG STREAM

Prints ASH ACSII trace information.

Definition at line 99 of file ash-host-io.h.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

238

6.36.2.22 #define ashDebugPrintf( ... )


6.36.2.23 #define ashDebugVfprintf( format, argPointer )


6.36.2.24 #define TX POOL BUFFERS

The number of transmit buffers must be set to the number of receive buffers – to hold the immediate A-CKs sent for each callabck frame received – plus 3 buffers for the retransmit queue and one each for anautomatic ACK (due to data flow control) and a command.

Definition at line 24 of file ash-host-queues.h.

6.36.2.25 #define RX FREE LWM

Define the limits used to decide if the host will hold off the ncp from sending normal priority frames.


6.36.2.26 #define RX FREE HWM


6.36.2.27 #define BUMP HOST COUNTER( mbr )

Definition at line 75 of file ash-host-ui.h.

6.36.2.28 #define ADD HOST COUNTER( op, mbr )

Definition at line 76 of file ash-host-ui.h.


6.36.3.1 typedef struct ashBuffer AshBuffer

Buffer to hold a DATA frame.


6.36.4.1 EzspStatus ashSelectHostConfig ( int8u config )

Selects a set of host configuration parameters. To select a configuration other than the default, must becalled before ashStart().

EmberZNet 4.7.2 API EM260 120-3020-000-4720

239

Parametersconfig one of the following:

• ASH_HOST_CONFIG_EM2XX_EM3XX_115200_RTSCTS (default)

• ASH_HOST_CONFIG_EM2XX_EM3XX_57600_XONXOFF

Returns

• ::EZSP_SUCCESS _ ::EZSP_ASH_HOST_FATAL_ERROR

6.36.4.2 EzspStatus ashStart ( void )

Initializes the ASH protocol, and waits until the NCP finishes rebooting, or a non-recoverable error occurs.

Returns

• ::EZSP_SUCCESS

• ::EZSP_ASH_HOST_FATAL_ERROR

• ::EZSP_ASH_NCP_FATAL_ERROR

6.36.4.3 void ashStop ( void )

Stops the ASH protocol - flushes and closes the serial port, clears all queues, stops timers, etc. Does notaffect any host configuration parameters.

6.36.4.4 EzspStatus ashSend ( int8u len, const int8u ∗ inptr )

Adds a DATA frame to the transmit queue to send to the NCP. Frames that are too long or too short willnot be sent, and frames will not be added to the queue if the host is not in the Connected state, or the NCPis not ready to receive a DATA frame or if there is no room in the queue;.

Parameterslen length of data field

inptr pointer to array containing the data to be sent

Returns

• ::EZSP_SUCCESS

• ::EZSP_ASH_NO_TX_SPACE

• ::EZSP_ASH_DATA_FRAME_TOO_SHORT

• ::EZSP_ASH_DATA_FRAME_TOO_LONG

• ::EZSP_ASH_NOT_CONNECTED

EmberZNet 4.7.2 API EM260 120-3020-000-4720

240

6.36.4.5 EzspStatus ashResetNcp ( void )

Initializes the ASH serial port and (if enabled) resets the NCP. The method used to do the reset is specifiedby the the host configuration parameter resetMethod.

When the reset method is sending a RST frame, the caller should retry NCP resets a few times if it fails.

Returns

• ::EZSP_SUCCESS



6.36.4.6 EzspStatus ashWakeUpNcp ( boolean init )

Wakes up the NCP by sending two 0xFF bytes. When the NCP wakes, it sends back an 0xFF byte.

Parametersinit set TRUE on the first call to this function, starts timer

Returns

• ::EZSP_ASH_IN_PROGRESS NCP is not yet awake, but has not timed out

• ::EZSP_SUCCESS NCP is swake

• ::EZSP_ASH_HOST_FATAL_ERROR NCP did not wake within ASH_MAX_WAKE_TIME

6.36.4.7 boolean ashIsConnected ( void )

Indicates if the host is in the Connected state. If not, the host and NCP cannot exchange DATA frames.Note that this function does not actively confirm that communication with NCP is healthy, but simplyreturns its last known status.

Returns

• TRUE host and NCP can exchange DATA frames

• FALSE host and NCP cannot now exchange DATA frames

6.36.4.8 void ashSendExec ( void )

Manages outgoing communication to the NCP, including DATA frames as well as the frames used forinitialization and error detection and recovery.

6.36.4.9 EzspStatus ashReceiveExec ( void )

Processes all received frames. Received DATA frames are appended to the receive queue if there is room.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

241

Returns

• ::EZSP_SUCCESS

• ::EZSP_ASH_IN_PROGRESS

• ::EZSP_ASH_NO_RX_DATA

• ::EZSP_ASH_NO_RX_SPACE



6.36.4.10 EzspStatus ashReceive ( int8u ∗ len, int8u ∗ buffer )

Returns the next DATA frame received, if there is one. To be more precise, the head of the receive queueis copied into the specified buffer and then freed.

Parameterslen length of the DATA frame if one was returnnd

buffer array into which the DATA frame should be copied

Returns

• ::EZSP_SUCCESS


• ::EZSP_ASH_NOT_CONNECTED

6.36.4.11 boolean ashOkToSleep ( void )

Returns TRUE if the host can sleep without causing errors in the ASH protocol.

6.36.4.12 EzspStatus ashSerialInit ( void )

Initializes the serial port for use by ASH. The port number, baud rate, stop bits, and flow control methodare specifed by the by the ashHostConfig structure.

Returns

• ::EZSP_SUCCESS


6.36.4.13 void ashSerialClose ( void )

If the serial port is open, discards all I/O data and closes the port.

6.36.4.14 void ashResetDtr ( void )

Resets the ncp by deasserting and asserting DTR. This requires a conenction between DTR and nRESET,as there is on the EM260 breakout board when the on-board USB interface is used.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

242

6.36.4.15 void ashResetCustom ( void )

Custom method for resetting the ncp which must be defined by the user for their specific hardware andinterconect. As shipped, this function does nothing.

6.36.4.16 EzspStatus ashSerialWriteAvailable ( void )

Checks to see if there is space available in the serial write buffer. If the buffer is full, it is output to theserial port and it return a "no space indication".

Returns

• ::EZSP_SUCCESS _ ::EZSP_ASH_NO_TX_SPACE

6.36.4.17 void ashSerialWriteByte ( int8u byte )

Writes a byte to the serial output buffer.

Parametersbyte byte to write

6.36.4.18 void ashSerialWriteFlush ( void )

Writes all data the write output buffer to the serial port and calls fsync(). This is called when a completeframe to be sent to the ncp has been created.

6.36.4.19 EzspStatus ashSerialReadByte ( int8u ∗ byte )

Reads a byte from the serial port, if one is available.

Parametersbyte pointer to a variable where the byte read will be output

Returns

• ::EZSP_SUCCESS


6.36.4.20 EzspStatus ashSerialReadAvailable ( int16u ∗ count )

Returns number of the bytes available to read from the serial port.

Parameterscount pointer to a variable where the byte count will be written

EmberZNet 4.7.2 API EM260 120-3020-000-4720

243

Returns

• ::EZSP_SUCCESS


6.36.4.21 void ashSerialReadFlush ( void )

Discards input data from the serial port until there is none left.

6.36.4.22 void ashDebugFlush ( void )

Flushes the ASH ASCII trace output stream.

6.36.4.23 int ashSerialGetFd ( void )

Returns the file descriptor associated with the serial port.

6.36.4.24 boolean ashSerialOutputIsIdle ( void )

tests to see if all serial transmit data has actually been shifted out the host’s serial port transmit data pin.As shipped this is a stub function that must be edited to match the actual operating system and/or UARThardware.

Returns

TRUE if all data has been shifted out.

6.36.4.25 void ashInitQueues ( void )

Initializes all queues and free lists. All receive buffers are put into rxFree, and rxQueue is empty. Alltransmit buffers are put into txFree, and txQueue and reTxQueue are empty.

6.36.4.26 void ashFreeBuffer ( AshFreeList ∗ list, AshBuffer ∗ buffer )

Add a buffer to the free list.

Parameterslist pointer to the free list

buffer pointer to the buffer

6.36.4.27 AshBuffer∗ ashAllocBuffer ( AshFreeList ∗ list )

Get a buffer from the free list.

Parameters

EmberZNet 4.7.2 API EM260 120-3020-000-4720

244

list pointer to the free list

Returns

pointer to the buffer allocated, NULL if free list was empty

6.36.4.28 AshBuffer∗ ashRemoveQueueHead ( AshQueue ∗ queue )

Remove the buffer at the head of a queue. The queue must not be empty.

Parametersqueue pointer to the queue

Returns

pointer to the buffer that had been the head of the queue

6.36.4.29 AshBuffer∗ ashQueueHead ( AshQueue ∗ queue )

Get a pointer to the buffer at the head of the queue. The queue must not be empty.


Returns

pointer to the buffer at the nead of the queue

6.36.4.30 AshBuffer∗ ashQueueNthEntry ( AshQueue ∗ queue, int8u n )

Get a pointer to the Nth entry in a queue. The tail is entry number 1, and if the queue has N entries, thehead is entry number N. The queue must not be empty.


n number of the entry to which a pointer will be returned

Returns

pointer to the Nth queue entry

6.36.4.31 AshBuffer∗ ashQueuePrecedingEntry ( AshQueue ∗ queue, AshBuffer ∗ buffer )

Get a pointer to the queue entry before (closer to the tail) than the specified entry. If the entry specified isthe tail, NULL is returned. If the entry specifed is NULL, a pointer to the head is returned.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

245

Parametersqueue pointer to the queuebuffer pointer to the buffer whose predecessor is wanted

Returns

pointer to the buffer before that specifed, or NULL if none

6.36.4.32 AshBuffer∗ ashRemoveQueueEntry ( AshQueue ∗ queue, AshBuffer ∗ buffer )

Removes the buffer from the queue, and returns a pointer to its predecssor, if there is one, otherwise itreturns NULL.

Parametersqueue pointer to the queuebuffer pointer to the buffer to be removed

Returns

pointer to the buffer before that removed, or NULL if none

6.36.4.33 int8u ashQueueLength ( AshQueue ∗ queue )

Returns the number of entries in the queue.


Returns

number of entries in the queue

6.36.4.34 int8u ashFreeListLength ( AshFreeList ∗ list )

Returns the number of entries in the free list.

Parameterslist pointer to the free list

EmberZNet 4.7.2 API EM260 120-3020-000-4720

246

Returns

number of entries in the free list

6.36.4.35 void ashAddQueueTail ( AshQueue ∗ queue, AshBuffer ∗ buffer )

Add a buffer to the tail of the queue.

Parametersqueue pointer to the queuebuffer pointer to the buffer

6.36.4.36 boolean ashQueueIsEmpty ( AshQueue ∗ queue )

Returns TRUE if the queue is empty.


Returns

TRUE if the queue is empty

6.36.4.37 void ashPrintUsage ( char ∗ name )

Prints usage instructions to stderr.

Parametersname program name (usually argv[0])

6.36.4.38 boolean ashProcessCommandOptions ( int argc, char ∗ argv[ ] )

Sets host configuration values from command line options.

Parametersargc number of command line tokensargv array of pointer to command line tokens

EmberZNet 4.7.2 API EM260 120-3020-000-4720

247

Returns

TRUE if no errors were detected in the command line

6.36.4.39 void ashTraceEvent ( const char ∗ string )

Writes a debug trace message, if enabled.

Parametersstring pointer to message string

Returns

• ::EZSP_SUCCESS


6.36.4.40 void ashPrintCounters ( AshCount ∗ counters, boolean clear )

Prints host counter data.

Parameterscounters pointer to counters structure

clear if TRUE clears counters

6.36.4.41 void ashClearCounters ( AshCount ∗ counters )

Clears host counter data.

Parameterscounters pointer to counters structure

6.36.4.42 const int8u∗ ashErrorString ( int8u error )

Converts ASH reset/error code to a string.

Parameterserror error or reset code (from ashError or ncpError)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

248

Returns

pointer to the string

6.36.4.43 const int8u∗ ashEzspErrorString ( int8u error )

Converts EZSP-ASH error code to a string.

Parameterserror error code

Returns

pointer to the string

6.36.4.44 void ashTraceFrame ( boolean sent )

6.36.4.45 void ashTraceEventRecdFrame ( const char ∗ string )

6.36.4.46 void ashTraceEventTime ( const char ∗ string )

6.36.4.47 void ashTraceDisconnected ( int8u error )

6.36.4.48 void ashTraceArray ( int8u ∗ name, int8u len, int8u ∗ data )

6.36.4.49 void ashTraceEzspFrameId ( const char ∗ message, int8u ∗ ezspFrame )

6.36.4.50 void ashTraceEzspVerbose ( char ∗ format, ... )

6.36.4.51 void ashCountFrame ( boolean sent )

6.36.4.52 int8u readTxControl ( void )

6.36.4.53 int8u readRxControl ( void )

6.36.4.54 int8u readAckRx ( void )

6.36.4.55 int8u readAckTx ( void )

6.36.4.56 int8u readFrmTx ( void )

6.36.4.57 int8u readFrmReTx ( void )

6.36.4.58 int8u readFrmRx ( void )

6.36.4.59 int8u readAshTimeouts ( void )


EmberZNet 4.7.2 API EM260 120-3020-000-4720

249

6.36.5.1 EzspStatus ashError

6.36.5.2 EzspStatus ncpError

6.36.5.3 AshHostConfig ashHostConfig

6.36.5.4 AshCount ashCount

6.36.5.5 boolean ncpSleepEnabled

6.36.5.6 AshQueue txQueue

6.36.5.7 AshQueue reTxQueue

6.36.5.8 AshQueue rxQueue

6.36.5.9 AshFreeList txFree

6.36.5.10 AshFreeList rxFree

EmberZNet 4.7.2 API EM260 120-3020-000-4720

250

6.37 Commands2

Data Structures


Macros

• #define MAX_TOKEN_COUNT• #define emberCommandEntryAction(name, action, argumentTypes, description)• #define emberCommandEntrySubMenu(name, subMenu, description)• #define emberCommandEntryTerminator()• #define EMBER_COMMAND_INTERPRETER_CONFIGURATION_ECHO• #define emberProcessCommandInput(port)• #define emberCommandInterpreterEchoOn()• #define emberCommandInterpreterEchoOff()• #define emberCommandInterpreterIsEchoOn()

Typedefs

• typedef void(∗ CommandAction )(void)

Enumerations


Functions

• void emberCommandActionHandler (const CommandAction action)• void emberCommandErrorHandler (EmberCommandStatus status)• void emberPrintCommandUsage (EmberCommandEntry ∗entry)• void emberPrintCommandUsageNotes (void)• void emberPrintCommandTable (void)• void emberCommandReaderInit (void)• boolean emberProcessCommandString (int8u ∗input, int8u sizeOrPort)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

251

Variables

• EmberCommandEntry ∗ emberCurrentCommand• EmberCommandEntry emberCommandTable [ ]• int8u emberCommandInterpreter2Configuration


• #define EMBER_MAX_COMMAND_ARGUMENTS• #define EMBER_COMMAND_BUFFER_LENGTH• #define EMBER_COMMAND_INTEPRETER_HAS_DESCRIPTION_FIELD

Functions to Retrieve Arguments

Use the following functions in your functions that process commands to retrieve arguments from the com-mand interpreter. These functions pull out unsigned integers, signed integers, and strings, and hex strings.Index 0 is the first command argument.

• int8u emberCommandArgumentCount (void)• int32u emberUnsignedCommandArgument (int8u argNum)• int16s emberSignedCommandArgument (int8u argNum)• int8u ∗ emberStringCommandArgument (int8s argNum, int8u ∗length)• int8u emberCopyStringArgument (int8s argNum, int8u ∗destination, int8u maxLength, boolean left-

Pad)• #define emberCopyKeyArgument(index, keyDataPointer)• #define emberCopyEui64Argument(index, eui64)


Interpret serial port commands. See command-interpreter2.c for source code.

See the following application usage example followed by a brief explanation.

// Usage: network form 22 0xAB12 -3 { 00 01 02 A3 A4 A5 A6 A7 }void formCommand(void){

int8u channel = emberUnsignedCommandArgument(0);

int16u panId = emberUnsignedCommandArgument(1);

int8s power = emberSignedCommandArgument(2);int8u length;int8u *eui64 = emberStringCommandArgument(3,

&length);...... call emberFormNetwork() etc...

}

// The main command table.EmberCommandEntry emberCommandTable[] = {

emberCommandEntrySubMenu("network", networkCommands,"Network form/join commands"),

emberCommandEntryAction("status", statusCommand,"Prints application status),

...emberCommandEntryTerminator()

};

// The table of network commands.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

252

EmberCommandEntry networkCommands[] = {emberCommandEntryAction("form", formCommand, "uvsh", "Form a network"),emberCommandEntryAction("join", joinCommand, "uvsh", "Join a network"),...emberCommandEntryTerminator()

};

void main(void){

emberCommandReaderInit();while(0) {

...// Process input and print prompt if it returns TRUE.if (emberProcessCommandInput(serialPort)) {

emberSerialPrintf(1, "%p>", PROMPT);}...

}}

1. Applications specify the commands that can be interpreted by defining the emberCommandTable ar-ray of type EmberCommandEntry. The table includes the following information for each command:

(a) The full command name.

(b) Your application’s function name that implements the command.

(c) An EmberCommandEntry::argumentTypes string specifies the number and types of argumentsthe command accepts. See ::argumentTypes for details.

(d) A description string explains the command.

2. A default error handler emberCommandErrorHandler() is provided to deal with incorrect commandinput. Applications may override it.

3. The application calls emberCommandReaderInit() to initalize, and emberProcessCommandInput()in its main loop.

4. Within the application’s command functions, use emberXXXCommandArgument() functions to re-trieve command arguments.

The command interpreter does extensive processing and validation of the command input before calling thefunction that implements the command. It checks that the number, type, syntax, and range of all argumentsare correct. It performs any conversions necessary (for example, converting integers and strings inputin hexadecimal notation into the corresponding bytes), so that no additional parsing is necessary withincommand functions. If there is an error in the command input, emberCommandErrorHandler() is calledrather than a command function.

The command interpreter allows inexact matches of command names. The input command may be eithershorter or longer than the actual command. However, if more than one inexact match is found and thereis no exact match, an error of type EMBER_CMD_ERR_NO_SUCH_COMMAND will be generated. Todisable this feature, define EMBER_REQUIRE_EXACT_COMMAND_NAME in the application config-uration header.


6.37.2.1 #define EMBER MAX COMMAND ARGUMENTS

The maximum number of arguments a command can have. A nested command counts as an argument.

Definition at line 104 of file command-interpreter2.h.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

253

6.37.2.2 #define EMBER COMMAND BUFFER LENGTH

The maximum number of arguments a command can have. A nested command counts as an argument.


6.37.2.3 #define EMBER COMMAND INTEPRETER HAS DESCRIPTION FIELD

Whether or not the command entry structure will include descriptions for the commands. This consumesadditional CONST space, which is expensive on the XAP. By default descriptions are not included.


6.37.2.4 #define MAX TOKEN COUNT


6.37.2.5 #define emberCommandEntryAction( name, action, argumentTypes, description )


6.37.2.6 #define emberCommandEntrySubMenu( name, subMenu, description )


6.37.2.7 #define emberCommandEntryTerminator( )


6.37.2.8 #define EMBER COMMAND INTERPRETER CONFIGURATION ECHO


6.37.2.9 #define emberCopyKeyArgument( index, keyDataPointer )

A convenience macro for copying security key arguments to an EmberKeyData pointer.


6.37.2.10 #define emberCopyEui64Argument( index, eui64 )

A convenience macro for copying eui64 arguments to an EmberEUI64.


6.37.2.11 #define emberProcessCommandInput( port )

Process input coming in on the given serial port.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

254

Returns

TRUE if an end of line character was read. If the application uses a command line prompt, thisindicates it is time to print the prompt.

void emberProcessCommandInput(int8u port);


6.37.2.12 #define emberCommandInterpreterEchoOn( )

Turn echo of command line on.


6.37.2.13 #define emberCommandInterpreterEchoOff( )

Turn echo of command line off.


6.37.2.14 #define emberCommandInterpreterIsEchoOn( )

Returns true if echo is on, false otherwise.



6.37.3.1 typedef void(∗ CommandAction)(void)



6.37.4.1 enum EmberCommandStatus

Command error states.

If you change this list, ensure you also change the strings that describe these errors in the array ember-CommandErrorNames[] in command-interpreter.c.

Enumerator:

EMBER_CMD_SUCCESS no error

EMBER_CMD_ERR_PORT_PROBLEM serial port error

EMBER_CMD_ERR_NO_BUFFER_AVAILABLE command processor busy

EMBER_CMD_ERR_NO_SUCH_COMMAND no such command

EMBER_CMD_ERR_WRONG_COMMAND_ARGUMENTS incorrect command arguments

EMBER_CMD_ERR_TOO_MANY_COMMAND_ARGUMENTS too many command arguments

EMBER_CMD_ERR_ARGUMENT_OUT_OF_RANGE integer argument out of range

EmberZNet 4.7.2 API EM260 120-3020-000-4720

255

EMBER_CMD_ERR_ARGUMENT_SYNTAX_ERROR argument syntax error

EMBER_CMD_ERR_STRING_TOO_LONG message too long

EMBER_CMD_ERR_NO_BINARY_STRING_TERMINATOR missing binary message termina-tor

EMBER_CMD_SUCCESSEMBER_CMD_ERR_PORT_PROBLEMEMBER_CMD_ERR_NO_SUCH_COMMANDEMBER_CMD_ERR_WRONG_NUMBER_OF_ARGUMENTSEMBER_CMD_ERR_ARGUMENT_OUT_OF_RANGEEMBER_CMD_ERR_ARGUMENT_SYNTAX_ERROREMBER_CMD_ERR_STRING_TOO_LONGEMBER_CMD_ERR_INVALID_ARGUMENT_TYPE



6.37.5.1 int8u emberCommandArgumentCount ( void )

Returns the number of arguments for the current command.

6.37.5.2 int32u emberUnsignedCommandArgument ( int8u argNum )

Retrieves unsigned integer arguments.

6.37.5.3 int16s emberSignedCommandArgument ( int8u argNum )

Retrieves signed integer arguments.

6.37.5.4 int8u∗ emberStringCommandArgument ( int8s argNum, int8u ∗ length )

Retrieve quoted string or hex string arguments. Hex strings have already been converted into binary. Toretrieve the name of the command itself, use an argNum of -1. For example, to retrieve the first characterof the command, do: int8u firstChar = emberStringCommandArgument(-1, NULL)[0]. If the command isnested, an index of -2, -3, etc will work to retrieve the higher level command names.

6.37.5.5 int8u emberCopyStringArgument ( int8s argNum, int8u ∗ destination, int8u maxLength,boolean leftPad )

Copies the string argument to the given destination up to maxLength. If the argument length is nonzerobut less than maxLength and leftPad is TRUE, leading zeroes are prepended to bring the total length ofthe target up to maxLength. If the argument is longer than the maxLength, it is truncated to maxLength.Returns the minimum of the argument length and maxLength.

This function is commonly used for reading in hex strings such as EUI64 or key data and left paddingthem with zeroes. See emberCopyKeyArgument and emberCopyEui64Argument for convenience macrosfor this purpose.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

256

6.37.5.6 void emberCommandActionHandler ( const CommandAction action )

The application may implement this handler. To override the default handler, define EMBER_APPLICA-TION_HAS_COMMAND_ACTION_HANDLER in the CONFIGURATION_HEADER.

6.37.5.7 void emberCommandErrorHandler ( EmberCommandStatus status )

The application may implement this handler. To override the default handler, define EMBER_APPLI-CATION_HAS_COMMAND_ERROR_HANDLER in the CONFIGURATION_HEADER. Defining thiswill also remove the help functions emberPrintCommandUsage(), emberPrintCommandUsageNotes(), andemberPrintCommandTable().

6.37.5.8 void emberPrintCommandUsage ( EmberCommandEntry ∗ entry )

6.37.5.9 void emberPrintCommandUsageNotes ( void )

6.37.5.10 void emberPrintCommandTable ( void )

6.37.5.11 void emberCommandReaderInit ( void )

Initialize the command interpreter.

6.37.5.12 boolean emberProcessCommandString ( int8u ∗ input, int8u sizeOrPort )

Process the given string as a command.


6.37.6.1 EmberCommandEntry∗ emberCurrentCommand

A pointer to the currently matching command entry. Only valid from within a command function. If theoriginal command was nested, points to the final (non-nested) command entry.

6.37.6.2 EmberCommandEntry emberCommandTable[ ]

6.37.6.3 int8u emberCommandInterpreter2Configuration

Configuration byte.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

257

Chapter 7

Data Structure Documentation

7.1 ashBuffer Struct Reference

#include <ash-host-queues.h>

Data Fields

• struct ashBuffer ∗ link• int8u len• int8u data [ASH_MAX_DATA_FIELD_LEN]


Buffer to hold a DATA frame.


7.1.2 Field Documentation

7.1.2.1 struct ashBuffer∗ ashBuffer::link


7.1.2.2 int8u ashBuffer::len


7.1.2.3 int8u ashBuffer::data[ASH_MAX_DATA_FIELD_LEN]


The documentation for this struct was generated from the following file:

• ash-host-queues.h

EmberZNet 4.7.2 API EM260 120-3020-000-4720

258

7.2 AshCount Struct Reference

#include <ash-host.h>

Data Fields

• int32u txBytes• int32u txBlocks• int32u txData• int32u txAllFrames• int32u txDataFrames• int32u txAckFrames• int32u txNakFrames• int32u txReDataFrames• int32u txN0Frames• int32u txN1Frames• int32u txCancelled• int32u rxBytes• int32u rxBlocks• int32u rxData• int32u rxAllFrames• int32u rxDataFrames• int32u rxAckFrames• int32u rxNakFrames• int32u rxReDataFrames• int32u rxN0Frames• int32u rxN1Frames• int32u rxCancelled• int32u rxCrcErrors• int32u rxCommErrors• int32u rxTooShort• int32u rxTooLong• int32u rxBadControl• int32u rxBadLength• int32u rxBadAckNumber• int32u rxNoBuffer• int32u rxDuplicates• int32u rxOutOfSequence• int32u rxAckTimeouts




7.2.2.1 int32u AshCount::txBytes

total bytes transmitted


EmberZNet 4.7.2 API EM260 120-3020-000-4720

259

7.2.2.2 int32u AshCount::txBlocks

blocks transmitted


7.2.2.3 int32u AshCount::txData

DATA frame data fields bytes transmitted


7.2.2.4 int32u AshCount::txAllFrames

frames of all types transmitted


7.2.2.5 int32u AshCount::txDataFrames

DATA frames transmitted


7.2.2.6 int32u AshCount::txAckFrames

ACK frames transmitted


7.2.2.7 int32u AshCount::txNakFrames

NAK frames transmitted


7.2.2.8 int32u AshCount::txReDataFrames

DATA frames retransmitted


7.2.2.9 int32u AshCount::txN0Frames

ACK and NAK frames with nFlag 0 transmitted


7.2.2.10 int32u AshCount::txN1Frames

ACK and NAK frames with nFlag 1 transmitted


EmberZNet 4.7.2 API EM260 120-3020-000-4720

260

7.2.2.11 int32u AshCount::txCancelled

frames cancelled (with ASH_CAN byte)


7.2.2.12 int32u AshCount::rxBytes

total bytes received


7.2.2.13 int32u AshCount::rxBlocks

blocks received


7.2.2.14 int32u AshCount::rxData

DATA frame data fields bytes received


7.2.2.15 int32u AshCount::rxAllFrames

frames of all types received


7.2.2.16 int32u AshCount::rxDataFrames

DATA frames received


7.2.2.17 int32u AshCount::rxAckFrames

ACK frames received


7.2.2.18 int32u AshCount::rxNakFrames

NAK frames received


7.2.2.19 int32u AshCount::rxReDataFrames

retransmitted DATA frames received


EmberZNet 4.7.2 API EM260 120-3020-000-4720

261

7.2.2.20 int32u AshCount::rxN0Frames

ACK and NAK frames with nFlag 0 received


7.2.2.21 int32u AshCount::rxN1Frames

ACK and NAK frames with nFlag 1 received


7.2.2.22 int32u AshCount::rxCancelled

frames cancelled (with ASH_CAN byte)


7.2.2.23 int32u AshCount::rxCrcErrors

frames with CRC errors


7.2.2.24 int32u AshCount::rxCommErrors

frames with comm errors (with ASH_SUB byte)


7.2.2.25 int32u AshCount::rxTooShort

frames shorter than minimum


7.2.2.26 int32u AshCount::rxTooLong

frames longer than maximum


7.2.2.27 int32u AshCount::rxBadControl

frames with illegal control byte


7.2.2.28 int32u AshCount::rxBadLength

frames with illegal length for type of frame


EmberZNet 4.7.2 API EM260 120-3020-000-4720

262

7.2.2.29 int32u AshCount::rxBadAckNumber

frames with bad ACK numbers


7.2.2.30 int32u AshCount::rxNoBuffer

DATA frames discarded due to lack of buffers


7.2.2.31 int32u AshCount::rxDuplicates

duplicate retransmitted DATA frames


7.2.2.32 int32u AshCount::rxOutOfSequence

DATA frames received out of sequence


7.2.2.33 int32u AshCount::rxAckTimeouts

received ACK timeouts



• ash-host.h

7.3 AshFreeList Struct Reference


Data Fields

• AshBuffer ∗ link


Simple free list (singly-linked list)


EmberZNet 4.7.2 API EM260 120-3020-000-4720

263


7.3.2.1 AshBuffer∗ AshFreeList::link




7.4 AshHostConfig Struct Reference

#include <ash-host.h>

Data Fields

• char serialPort [ASH_PORT_LEN]• int32u baudRate• int8u stopBits• int8u rtsCts• int16u outBlockLen• int16u inBlockLen• int8u traceFlags• int8u txK• int8u randomize• int16u ackTimeInit• int16u ackTimeMin• int16u ackTimeMax• int16u timeRst• int8u nrLowLimit• int8u nrHighLimit• int16u nrTime• int8u resetMethod• int8u ncpType


Configuration parameters: values must be defined before calling ashResetNcp() or ashStart(). Note that alltimes are in milliseconds.



7.4.2.1 char AshHostConfig::serialPort[ASH_PORT_LEN]

serial port name


EmberZNet 4.7.2 API EM260 120-3020-000-4720

264

7.4.2.2 int32u AshHostConfig::baudRate

baud rate (bits/second)


7.4.2.3 int8u AshHostConfig::stopBits

stop bits


7.4.2.4 int8u AshHostConfig::rtsCts

TRUE enables RTS/CTS flow control, FALSE XON/XOFF


7.4.2.5 int16u AshHostConfig::outBlockLen

max bytes to buffer before writing to serial port


7.4.2.6 int16u AshHostConfig::inBlockLen

max bytes to read ahead from serial port


7.4.2.7 int8u AshHostConfig::traceFlags

trace output control bit flags


7.4.2.8 int8u AshHostConfig::txK

max frames sent without being ACKed (1-7)


7.4.2.9 int8u AshHostConfig::randomize

enables randomizing DATA frame payloads


7.4.2.10 int16u AshHostConfig::ackTimeInit

adaptive rec’d ACK timeout initial value


EmberZNet 4.7.2 API EM260 120-3020-000-4720

265

7.4.2.11 int16u AshHostConfig::ackTimeMin

adaptive rec’d ACK timeout minimum value


7.4.2.12 int16u AshHostConfig::ackTimeMax

adaptive rec’d ACK timeout maximum value


7.4.2.13 int16u AshHostConfig::timeRst

time allowed to receive RSTACK after ncp is reset


7.4.2.14 int8u AshHostConfig::nrLowLimit

if free buffers < limit, host receiver isn’t ready


7.4.2.15 int8u AshHostConfig::nrHighLimit

if free buffers > limit, host receiver is ready


7.4.2.16 int16u AshHostConfig::nrTime

time until a set nFlag must be resent (max 2032)


7.4.2.17 int8u AshHostConfig::resetMethod

method used to reset ncp


7.4.2.18 int8u AshHostConfig::ncpType

type of ncp processor



• ash-host.h

EmberZNet 4.7.2 API EM260 120-3020-000-4720

266

7.5 AshQueue Struct Reference


Data Fields

• AshBuffer ∗ tail


Simple queue (singly-linked list)



7.5.2.1 AshBuffer∗ AshQueue::tail




7.6 EmberAesMmoHashContext Struct Reference

#include <ember-types.h>

Data Fields

• int8u result [EMBER_AES_HASH_BLOCK_SIZE]• int32u length


This data structure contains the context data when calculating an AES MMO hash (message digest).



7.6.2.1 int8u EmberAesMmoHashContext::result[EMBER_AES_HASH_BLOCK_SIZE]


EmberZNet 4.7.2 API EM260 120-3020-000-4720

267

7.6.2.2 int32u EmberAesMmoHashContext::length



• ember-types.h

7.7 EmberApsFrame Struct Reference


Data Fields

• int16u profileId• int16u clusterId• int8u sourceEndpoint• int8u destinationEndpoint• EmberApsOption options• int16u groupId• int8u sequence


An in-memory representation of a ZigBee APS frame of an incoming or outgoing message.



7.7.2.1 int16u EmberApsFrame::profileId

The application profile ID that describes the format of the message.


7.7.2.2 int16u EmberApsFrame::clusterId

The cluster ID for this message.


7.7.2.3 int8u EmberApsFrame::sourceEndpoint

The source endpoint.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

268

7.7.2.4 int8u EmberApsFrame::destinationEndpoint

The destination endpoint.


7.7.2.5 EmberApsOption EmberApsFrame::options

A bitmask of options from the enumeration above.


7.7.2.6 int16u EmberApsFrame::groupId

The group ID for this message, if it is multicast mode.


7.7.2.7 int8u EmberApsFrame::sequence

The sequence number.



• ember-types.h

7.8 EmberBindingTableEntry Struct Reference


Data Fields

• EmberBindingType type• int8u local• int16u clusterId• int8u remote• EmberEUI64 identifier• int8u networkIndex


Defines an entry in the binding table.

A binding entry specifies a local endpoint, a remote endpoint, a cluster ID and either the destination EUI64(for unicast bindings) or the 64-bit group address (for multicast bindings).


EmberZNet 4.7.2 API EM260 120-3020-000-4720

269


7.8.2.1 EmberBindingType EmberBindingTableEntry::type

The type of binding.


7.8.2.2 int8u EmberBindingTableEntry::local

The endpoint on the local node.


7.8.2.3 int16u EmberBindingTableEntry::clusterId

A cluster ID that matches one from the local endpoint’s simple descriptor. This cluster ID is set by theprovisioning application to indicate which part an endpoint’s functionality is bound to this particular remotenode and is used to distinguish between unicast and multicast bindings. Note that a binding can be used toto send messages with any cluster ID, not just that listed in the binding.


7.8.2.4 int8u EmberBindingTableEntry::remote

The endpoint on the remote node (specified by identifier).


7.8.2.5 EmberEUI64 EmberBindingTableEntry::identifier

A 64-bit identifier. This is either:

• The destination EUI64, for unicasts

• A 16-bit multicast group address, for multicasts


7.8.2.6 int8u EmberBindingTableEntry::networkIndex

The index of the network the binding belongs to.



• ember-types.h

7.9 EmberCertificateData Struct Reference


EmberZNet 4.7.2 API EM260 120-3020-000-4720

270

Data Fields

• int8u contents [EMBER_CERTIFICATE_SIZE]


This data structure contains the certificate data that is used for Certificate Based Key Exchange (CBKE).



7.9.2.1 int8u EmberCertificateData::contents[EMBER_CERTIFICATE_SIZE]



• ember-types.h

7.10 EmberCommandEntry Struct Reference

#include <command-interpreter.h>

Data Fields

• PGM_P longName• CommandAction action• PGM_P argumentTypes• PGM_P description• PGM_P name


Command entry for a command table.



7.10.2.1 PGM_P EmberCommandEntry::longName

Use letters, digits, and underscores, ’_’, for the long command name. Command names are case-sensitive.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

271

7.10.2.2 CommandAction EmberCommandEntry::action

A reference to a function in the application that implements the command.

A reference to a function in the application that implements the command. If this entry refers to a nestedcommand, then action field has to be set to NULL.


7.10.2.3 PGM_P EmberCommandEntry::argumentTypes

String that specifies the number and types of arguments the command accepts. The argument specifiersare:

• b: buffer

• u1: one-byte unsigned

• u2: two-byte unsigned

• u4: four-byte unsigned (32 bit platforms only)

• s1: one-byte signed

• s2: two-byte signed

• ∗: zero or more of the previous type. If used, this must be the last specifier.

Buffer arguments are given as a string "...". There is currently no way for including quote characters ’,"",’ inbuffer arguments. Buffer arguments can also be given as a hex digit string using curly braces: {1A2B3C}.The hex digits are converted to bytes in pairs.

Integer arguments can be either decimal or hexidecimal. If the integerBase field of the command state is 16then all integers are read as hexidecimal. If integerBase is 10 then a decimal is the default and a 0x prefixindicates a hexidecimal integer.

In case of normal (non-nested) commands, argumentTypes is a string that specifies the number and typesof arguments the command accepts. The argument specifiers are:

• u: one-byte unsigned integer.

• v: two-byte unsigned integer

• w: four-byte unsigned integer

• s: one-byte signed integer

• b: string. The argument can be entered in ascii by using quotes, for example: "foo". Or it may beentered in hex by using curly braces, for example: { 08 A1 f2 }. There must be an even number ofhex digits, and spaces are ignored.

• ∗: zero or more of the previous type. If used, this must be the last specifier.

• ?: Unknown number of arguments. If used this must be the only character. This means, that com-mand interpreter will not perform any validation of arguments, and will call the action directly,trusting it that it will handle with whatever arguments are passed in. Integer arguments can be eitherdecimal or hexidecimal. A 0x prefix indicates a hexidecimal integer. Example: 0x3ed.

In case of a nested command (action is NULL), then this field contains a pointer to the nested Ember-CommandEntry array.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

272

7.10.2.4 PGM_P EmberCommandEntry::description

A description of the command.


7.10.2.5 PGM_P EmberCommandEntry::name

Use letters, digits, and underscores, ’_’, for the command name. Command names are case-sensitive.


The documentation for this struct was generated from the following files:

• command-interpreter.h• command-interpreter2.h

7.11 EmberCommandStateS Struct Reference

#include <command-interpreter.h>

Data Fields

• EmberCommandEntry ∗ commands• void(∗ errorHandler )(struct EmberCommandStateS ∗state)• ArgTypeU ∗ arguments• int8u maximumArguments• int8u integerBase• int8u argumentCount• int8u state• int8u error• int8u command [EMBER_MAX_COMMAND_LENGTH+1]• int16u commandIndex• PGM_P argumentSpecs• int8u stringLength• int8u binaryLength• EmberMessageBuffer stringBuffer• ArgTypeU integerValue• int8u integerSign• int8u currentIntegerBase• EmberCommandEntry ∗ currentCommands


The command state structure. Using a structure allows commands to be read from multiple sources.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

273


7.11.2.1 EmberCommandEntry∗ EmberCommandStateS::commands

The table of commands created in the application.


7.11.2.2 void(∗ EmberCommandStateS::errorHandler)(struct EmberCommandStateS ∗state)


7.11.2.3 ArgTypeU∗ EmberCommandStateS::arguments

Arguments filled in by the interpreter.


7.11.2.4 int8u EmberCommandStateS::maximumArguments


7.11.2.5 int8u EmberCommandStateS::integerBase

Determines whether integers are parsed using base 10 or base 16. Valid values are only 10 or 16.


7.11.2.6 int8u EmberCommandStateS::argumentCount

Set by the interpreter for use by the command function.


7.11.2.7 int8u EmberCommandStateS::state

Finite-state machine’s current state.


7.11.2.8 int8u EmberCommandStateS::error

First error found in this command.


7.11.2.9 int8u EmberCommandStateS::command[EMBER_MAX_COMMAND_LENGTH+1]

For reading in and remembering the current command. The "+ 1" is for the trailing null.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

274

7.11.2.10 int16u EmberCommandStateS::commandIndex


7.11.2.11 PGM_P EmberCommandStateS::argumentSpecs

Stepped forward as arguments are read.


7.11.2.12 int8u EmberCommandStateS::stringLength

Bytes read in so far.


7.11.2.13 int8u EmberCommandStateS::binaryLength

Remaining bytes in the binary block.


7.11.2.14 EmberMessageBuffer EmberCommandStateS::stringBuffer


7.11.2.15 ArgTypeU EmberCommandStateS::integerValue


7.11.2.16 int8u EmberCommandStateS::integerSign

Valid values are ’+’ or ’-’.


7.11.2.17 int8u EmberCommandStateS::currentIntegerBase


7.11.2.18 EmberCommandEntry∗ EmberCommandStateS::currentCommands

Used for pointing to a table of subcommands.



• command-interpreter.h

EmberZNet 4.7.2 API EM260 120-3020-000-4720

275

7.12 EmberCurrentSecurityState Struct Reference


Data Fields

• EmberCurrentSecurityBitmask bitmask• EmberEUI64 trustCenterLongAddress


This describes the security features used by the stack for a joined device.



7.12.2.1 EmberCurrentSecurityBitmask EmberCurrentSecurityState::bitmask

This bitmask indicates the security features currently in use on this node.


7.12.2.2 EmberEUI64 EmberCurrentSecurityState::trustCenterLongAddress

This indicates the EUI64 of the Trust Center. It will be all zeroes if the Trust Center Address is not known(i.e. the device is in a Distributed Trust Center network).



• ember-types.h

7.13 EmberEventControl Struct Reference


Data Fields

• EmberEventUnits status• EmberTaskId taskid• int32u timeToExecute


Control structure for events.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

276

This structure should not be accessed directly. This holds the event status (one of the EMBER_EVENT_values) and the time left before the event fires.



7.13.2.1 EmberEventUnits EmberEventControl::status

The event’s status, either inactive or the units for timeToExecute.


7.13.2.2 EmberTaskId EmberEventControl::taskid

The id of the task this event belongs to.


7.13.2.3 int32u EmberEventControl::timeToExecute

How long before the event fires. Units are always in milliseconds



• ember-types.h

7.14 EmberInitialSecurityState Struct Reference


Data Fields

• int16u bitmask• EmberKeyData preconfiguredKey• EmberKeyData networkKey• int8u networkKeySequenceNumber• EmberEUI64 preconfiguredTrustCenterEui64


This describes the Initial Security features and requirements that will be used when forming or joining thenetwork.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

277


7.14.2.1 int16u EmberInitialSecurityState::bitmask

This bitmask enumerates which security features should be used, as well as the presence of valid datawithin other elements of the EmberInitialSecurityState data structure. For more details see the Ember-InitialSecurityBitmask.


7.14.2.2 EmberKeyData EmberInitialSecurityState::preconfiguredKey

This is the pre-configured key that can used by devices when joining the network if the Trust Center doesnot send the initial security data in-the-clear. For the Trust Center, it will be the global link key and must beset regardless of whether joining devices are expected to have a pre-configured Link Key. This parameterwill only be used if the EmberInitialSecurityState::bitmask sets the bit indicating EMBER_HAVE_PREC-ONFIGURED_KEY


7.14.2.3 EmberKeyData EmberInitialSecurityState::networkKey

This is the Network Key used when initially forming the network. This must be set on the Trust Center. Itis not needed for devices joining the network. This parameter will only be used if the EmberInitialSecurity-State::bitmask sets the bit indicating EMBER_HAVE_NETWORK_KEY.


7.14.2.4 int8u EmberInitialSecurityState::networkKeySequenceNumber

This is the sequence number associated with the network key. It must be set if the Network Key is set. Itis used to indicate a particular of the network key for updating and switching. This parameter will only beused if the EMBER_HAVE_NETWORK_KEY is set. Generally it should be set to 0 when forming thenetwork; joining devices can ignore this value.


7.14.2.5 EmberEUI64 EmberInitialSecurityState::preconfiguredTrustCenterEui64

This is the long address of the trust center on the network that will be joined. It is usually NOT setprior to joining the network and instead it is learned during the joining message exchange. This fieldis only examined if EMBER_HAVE_TRUST_CENTER_EUI64 is set in the EmberInitialSecurityState-::bitmask. Most devices should clear that bit and leave this field alone. This field must be set when usingcommissioning mode. It is required to be in little-endian format.



• ember-types.h

EmberZNet 4.7.2 API EM260 120-3020-000-4720

278

7.15 EmberKeyData Struct Reference


Data Fields

• int8u contents [EMBER_ENCRYPTION_KEY_SIZE]


This data structure contains the key data that is passed into various other functions.



7.15.2.1 int8u EmberKeyData::contents[EMBER_ENCRYPTION_KEY_SIZE]

This is the key byte data.



• ember-types.h

7.16 EmberKeyStruct Struct Reference


Data Fields

• EmberKeyStructBitmask bitmask• EmberKeyType type• EmberKeyData key• int32u outgoingFrameCounter• int32u incomingFrameCounter• int8u sequenceNumber• EmberEUI64 partnerEUI64


This describes a one of several different types of keys and its associated data.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

279


7.16.2.1 EmberKeyStructBitmask EmberKeyStruct::bitmask

This bitmask indicates whether various fields in the structure contain valid data. It also contains the indexof the network the key belongs to.


7.16.2.2 EmberKeyType EmberKeyStruct::type

This indicates the type of the security key.


7.16.2.3 EmberKeyData EmberKeyStruct::key

This is the actual key data.


7.16.2.4 int32u EmberKeyStruct::outgoingFrameCounter

This is the outgoing frame counter associated with the key. It will contain valid data based on the Ember-KeyStructBitmask.


7.16.2.5 int32u EmberKeyStruct::incomingFrameCounter

This is the incoming frame counter associated with the key. It will contain valid data based on the Ember-KeyStructBitmask.


7.16.2.6 int8u EmberKeyStruct::sequenceNumber

This is the sequence number associated with the key. It will contain valid data based on the EmberKey-StructBitmask.


7.16.2.7 EmberEUI64 EmberKeyStruct::partnerEUI64

This is the Partner EUI64 associated with the key. It will contain valid data based on the EmberKeyStruct-Bitmask.



• ember-types.h

EmberZNet 4.7.2 API EM260 120-3020-000-4720

280

7.17 EmberMacFilterMatchStruct Struct Reference


Data Fields

• int8u filterIndexMatch• EmberMacPassthroughType legacyPassthroughType• EmberMessageBuffer message


This structure indicates a matching raw MAC message has been received by the application configuredMAC filters.



7.17.2.1 int8u EmberMacFilterMatchStruct::filterIndexMatch


7.17.2.2 EmberMacPassthroughType EmberMacFilterMatchStruct::legacyPassthroughType


7.17.2.3 EmberMessageBuffer EmberMacFilterMatchStruct::message



• ember-types.h

7.18 EmberMessageDigest Struct Reference


Data Fields

• int8u contents [EMBER_AES_HASH_BLOCK_SIZE]


This data structure contains an AES-MMO Hash (the message digest).


EmberZNet 4.7.2 API EM260 120-3020-000-4720

281


7.18.2.1 int8u EmberMessageDigest::contents[EMBER_AES_HASH_BLOCK_SIZE]



• ember-types.h

7.19 EmberMfgSecurityStruct Struct Reference


Data Fields

• EmberKeySettings keySettings


This structure is used to get/set the security config that is stored in manufacturing tokens.



7.19.2.1 EmberKeySettings EmberMfgSecurityStruct::keySettings



• ember-types.h

7.20 EmberMulticastTableEntry Struct Reference


Data Fields

• EmberMulticastId multicastId• int8u endpoint• int8u networkIndex

EmberZNet 4.7.2 API EM260 120-3020-000-4720

282


Defines an entry in the multicast table.

A multicast table entry indicates that a particular endpoint is a member of a particular multicast group.Only devices with an endpoint in a multicast group will receive messages sent to that multicast group.



7.20.2.1 EmberMulticastId EmberMulticastTableEntry::multicastId

The multicast group ID.


7.20.2.2 int8u EmberMulticastTableEntry::endpoint

The endpoint that is a member, or 0 if this entry is not in use (the ZDO is not a member of any multicastgroups).


7.20.2.3 int8u EmberMulticastTableEntry::networkIndex

The network index of the network the entry is related to.



• ember-types.h

7.21 EmberNeighborTableEntry Struct Reference


Data Fields

• int16u shortId• int8u averageLqi• int8u inCost• int8u outCost• int8u age• EmberEUI64 longId


Defines an entry in the neighbor table.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

283

A neighbor table entry stores information about the reliability of RF links to and from neighboring nodes.



7.21.2.1 int16u EmberNeighborTableEntry::shortId

The neighbor’s two byte network id.


7.21.2.2 int8u EmberNeighborTableEntry::averageLqi

An exponentially weighted moving average of the link quality values of incoming packets from this neigh-bor as reported by the PHY.


7.21.2.3 int8u EmberNeighborTableEntry::inCost

The incoming cost for this neighbor, computed from the average LQI. Values range from 1 for a good linkto 7 for a bad link.


7.21.2.4 int8u EmberNeighborTableEntry::outCost

The outgoing cost for this neighbor, obtained from the most recently received neighbor exchange messagefrom the neighbor. A value of zero means that a neighbor exchange message from the neighbor has notbeen received recently enough, or that our id was not present in the most recently received one. EmberZNetPro only.


7.21.2.5 int8u EmberNeighborTableEntry::age

In EmberZNet Pro, the number of aging periods elapsed since a neighbor exchange message was lastreceived from this neighbor. In stack profile 1, the number of aging periods since any packet was received.An entry with an age greater than 3 is considered stale and may be reclaimed. The aging period is 16seconds.


7.21.2.6 EmberEUI64 EmberNeighborTableEntry::longId

The 8 byte EUI64 of the neighbor.



• ember-types.h

EmberZNet 4.7.2 API EM260 120-3020-000-4720

284

7.22 EmberNetworkInitStruct Struct Reference


Data Fields

• EmberNetworkInitBitmask bitmask


Defines the network initialization configuration that should be used when ::emberNetworkInitExtended()is called by the application.



7.22.2.1 EmberNetworkInitBitmask EmberNetworkInitStruct::bitmask



• ember-types.h

7.23 EmberNetworkParameters Struct Reference


Data Fields

• int8u extendedPanId [8]• int16u panId• int8s radioTxPower• int8u radioChannel• EmberJoinMethod joinMethod• EmberNodeId nwkManagerId• int8u nwkUpdateId• int32u channels


Holds network parameters.

For information about power settings and radio channels, see the technical specification for the RF com-munication module in your Developer Kit.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

285


7.23.2.1 int8u EmberNetworkParameters::extendedPanId[8]

The network’s extended PAN identifier.


7.23.2.2 int16u EmberNetworkParameters::panId

The network’s PAN identifier.


7.23.2.3 int8s EmberNetworkParameters::radioTxPower

A power setting, in dBm.


7.23.2.4 int8u EmberNetworkParameters::radioChannel

A radio channel. Be sure to specify a channel supported by the radio.


7.23.2.5 EmberJoinMethod EmberNetworkParameters::joinMethod

Join method: The protocol messages used to establish an initial parent. It is ignored when forming a ZigBeenetwork, or when querying the stack for its network parameters.


7.23.2.6 EmberNodeId EmberNetworkParameters::nwkManagerId

NWK Manager ID. The ID of the network manager in the current network. This may only be set at joiningwhen using EMBER_USE_NWK_COMMISSIONING as the join method.


7.23.2.7 int8u EmberNetworkParameters::nwkUpdateId

NWK Update ID. The value of the ZigBee nwkUpdateId known by the stack. This is used to determine thenewest instance of the network after a PAN ID or channel change. This may only be set at joining whenusing EMBER_USE_NWK_COMMISSIONING as the join method.


7.23.2.8 int32u EmberNetworkParameters::channels

NWK channel mask. The list of preferred channels that the NWK manager has told this device to use whensearching for the network. This may only be set at joining when using EMBER_USE_NWK_COMMISS-IONING as the join method.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

286



• ember-types.h

7.24 EmberPrivateKeyData Struct Reference


Data Fields

• int8u contents [EMBER_PRIVATE_KEY_SIZE]


This data structure contains the private key data that is used for Certificate Based Key Exchange (CBKE).



7.24.2.1 int8u EmberPrivateKeyData::contents[EMBER_PRIVATE_KEY_SIZE]



• ember-types.h

7.25 EmberPublicKeyData Struct Reference


Data Fields

• int8u contents [EMBER_PUBLIC_KEY_SIZE]


This data structure contains the public key data that is used for Certificate Based Key Exchange (CBKE).


EmberZNet 4.7.2 API EM260 120-3020-000-4720

287


7.25.2.1 int8u EmberPublicKeyData::contents[EMBER_PUBLIC_KEY_SIZE]



• ember-types.h

7.26 EmberRouteTableEntry Struct Reference


Data Fields

• int16u destination• int16u nextHop• int8u status• int8u age• int8u concentratorType• int8u routeRecordState


Defines an entry in the route table.

A route table entry stores information about the next hop along the route to the destination.



7.26.2.1 int16u EmberRouteTableEntry::destination

The short id of the destination.


7.26.2.2 int16u EmberRouteTableEntry::nextHop

The short id of the next hop to this destination.


7.26.2.3 int8u EmberRouteTableEntry::status

Indicates whether this entry is active (0), being discovered (1), or unused (3).


EmberZNet 4.7.2 API EM260 120-3020-000-4720

288

7.26.2.4 int8u EmberRouteTableEntry::age

The number of seconds since this route entry was last used to send a packet.


7.26.2.5 int8u EmberRouteTableEntry::concentratorType

Indicates whether this destination is a High RAM Concentrator (2), a Low RAM Concentrator (1), or not aconcentrator (0).


7.26.2.6 int8u EmberRouteTableEntry::routeRecordState

For a High RAM Concentrator, indicates whether a route record is needed (2), has been sent (1), or is nolong needed (0) because a source routed message from the concentrator has been received.



• ember-types.h

7.27 EmberSignatureData Struct Reference


Data Fields

• int8u contents [EMBER_SIGNATURE_SIZE]


This data structure contains a DSA signature. It is the bit concatenation of the ’r’ and ’s’ components ofthe signature.



7.27.2.1 int8u EmberSignatureData::contents[EMBER_SIGNATURE_SIZE]



• ember-types.h

EmberZNet 4.7.2 API EM260 120-3020-000-4720

289

7.28 EmberSmacData Struct Reference


Data Fields

• int8u contents [EMBER_SMAC_SIZE]


This data structure contains the Shared Message Authentication Code (SMAC) data that is used for Cer-tificate Based Key Exchange (CBKE).



7.28.2.1 int8u EmberSmacData::contents[EMBER_SMAC_SIZE]



• ember-types.h

7.29 EmberTaskControl Struct Reference


Data Fields

• int32u nextEventTime• EmberEventData ∗ events• boolean busy


Control structure for tasks.

This structure should not be accessed directly.



7.29.2.1 int32u EmberTaskControl::nextEventTime


EmberZNet 4.7.2 API EM260 120-3020-000-4720

290

7.29.2.2 EmberEventData∗ EmberTaskControl::events


7.29.2.3 boolean EmberTaskControl::busy



• ember-types.h

7.30 EmberVersion Struct Reference


Data Fields

• int16u build• int8u major• int8u minor• int8u patch• int8u special• EmberVersionType type


Version struct containing all version information.



7.30.2.1 int16u EmberVersion::build


7.30.2.2 int8u EmberVersion::major


7.30.2.3 int8u EmberVersion::minor


7.30.2.4 int8u EmberVersion::patch


EmberZNet 4.7.2 API EM260 120-3020-000-4720

291

7.30.2.5 int8u EmberVersion::special


7.30.2.6 EmberVersionType EmberVersion::type



• ember-types.h

7.31 EmberZigbeeNetwork Struct Reference


Data Fields

• int16u panId• int8u channel• boolean allowingJoin• int8u extendedPanId [8]• int8u stackProfile• int8u nwkUpdateId


Defines a ZigBee network and the associated parameters.



7.31.2.1 int16u EmberZigbeeNetwork::panId


7.31.2.2 int8u EmberZigbeeNetwork::channel


7.31.2.3 boolean EmberZigbeeNetwork::allowingJoin


7.31.2.4 int8u EmberZigbeeNetwork::extendedPanId[8]


EmberZNet 4.7.2 API EM260 120-3020-000-4720

292

7.31.2.5 int8u EmberZigbeeNetwork::stackProfile


7.31.2.6 int8u EmberZigbeeNetwork::nwkUpdateId



• ember-types.h

7.32 InterPanHeader Struct Reference

#include <ami-inter-pan.h>

Data Fields

• int8u messageType• int16u panId• boolean hasLongAddress• EmberNodeId shortAddress• EmberEUI64 longAddress• int16u profileId• int16u clusterId• int16u groupId


A struct for keeping track of all of the header info.

A struct for keeping track of all of the interpan header info.



7.32.2.1 int8u InterPanHeader::messageType


7.32.2.2 int16u InterPanHeader::panId


7.32.2.3 boolean InterPanHeader::hasLongAddress


EmberZNet 4.7.2 API EM260 120-3020-000-4720

293

7.32.2.4 EmberNodeId InterPanHeader::shortAddress


7.32.2.5 EmberEUI64 InterPanHeader::longAddress


7.32.2.6 int16u InterPanHeader::profileId


7.32.2.7 int16u InterPanHeader::clusterId


7.32.2.8 int16u InterPanHeader::groupId


The documentation for this struct was generated from the following files:

• ami-inter-pan.h• ami-inter-pan-host.h

EmberZNet 4.7.2 API EM260 120-3020-000-4720

294

Chapter 8

File Documentation

8.1 EM260 API.top File Reference


Starting page for the Ember API documentation for the EM260 exclusively for building documentation.This file is used by Doxygen to generate the main page for the Ember API documentation, EM260.

Definition in file _EM260_API.top.

8.2 EM260 API.top

00001

8.3 adc.h File Reference

Macros

• #define NUM_ADC_USERS

Typedefs

• typedef int8u ADCChannelType• typedef int8u ADCReferenceType• typedef int8u ADCRateType

Enumerations

• enum ADCUser { ADC_USER_LQI, ADC_USER_APP, ADC_USER_APP2 }

Functions

• void halInternalInitAdc (void)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

295

• void halInternalSleepAdc (void)• EmberStatus halStartAdcConversion (ADCUser id, ADCReferenceType reference, ADCChannel-

Type channel, ADCRateType rate)• EmberStatus halRequestAdcData (ADCUser id, int16u ∗value)• EmberStatus halReadAdcBlocking (ADCUser id, int16u ∗value)• EmberStatus halAdcCalibrate (ADCUser id)• int16s halConvertValueToVolts (int16u value)• void emberCalibrateVref (void)


Header for A/D converter. See ADC Control for documentation.

Definition in file adc.h.

8.4 adc.h

0000100039 #ifndef __ADC_H__00040 #define __ADC_H__0004100042 #ifdef DOXYGEN_SHOULD_SKIP_THIS0004300051 enum ADCUser00052 #else00053 // A type for the ADC User enumeration.00054 typedef int8u ADCUser;00055 enum00056 #endif //DOXYGEN_SHOULD_SKIP_THIS00057 {00059 ADC_USER_LQI = 0,00061 ADC_USER_APP = 1,00063 ADC_USER_APP2 = 200064 };0006500069 #define NUM_ADC_USERS 3 // make sure to update if the above is adjusted0007000073 typedef int8u ADCChannelType;0007400077 typedef int8u ADCReferenceType;0007800081 typedef int8u ADCRateType;00082000830008400085 #if defined(AVR_ATMEGA) || defined(EMBER_TEST)00086 #include "avr-atmega/adc.h"00087 #elif defined(XAP2B)00088 #include "xap2b/adc.h"00089 #elif defined(CORTEXM3)00090 #include "cortexm3/adc.h"00091 #else00092 // platform that doesn’t have ADC support00093 #endif000940009500100 void halInternalInitAdc(void);001010010200106 void halInternalSleepAdc(void);001070010800139 EmberStatus halStartAdcConversion(ADCUser

id,00140 ADCReferenceType reference,00141 ADCChannelType channel,00142 ADCRateType rate);0014300164 EmberStatus halRequestAdcData(ADCUser id,

EmberZNet 4.7.2 API EM260 120-3020-000-4720

296

int16u *value);001650016600184 EmberStatus halReadAdcBlocking(ADCUser id,

int16u *value);001850018600203 EmberStatus halAdcCalibrate(ADCUser id);002040020500217 int16s halConvertValueToVolts(int16u value);002180021900228 void emberCalibrateVref(void);002290023000231 #endif // __ADC_H__00232

8.5 adc.h File Reference

Enumerations

• enum { ADC_REF_AREF, ADC_REF_AVCC, ADC_REF_INT }• enum { ADC_CONVERSION_TIME_US_256 }• enum {

ADC_SOURCE_ADC0, ADC_SOURCE_ADC1, ADC_SOURCE_ADC2, ADC_SOURCE_AD-C3,ADC_SOURCE_ADC4, ADC_SOURCE_ADC5, ADC_SOURCE_ADC6, ADC_SOURCE_AD-C7 }


Header for Atmel AVR A/D converter. See ADC Control for documentation.

Definition in file avr-atmega/adc.h.

8.6 avr-atmega/adc.h

0000100009 #ifndef __AVR_ADC_H__00010 #define __AVR_ADC_H__0001100012 #ifndef DOXYGEN_SHOULD_SKIP_THIS00013 #ifndef __ADC_H__00014 #error do not include this file directly - include micro/adc.h00015 #endif00016 #endif0001700024 enum {00026 ADC_REF_AREF = 0x00,00028 ADC_REF_AVCC = 0x40,00030 ADC_REF_INT = 0xC000031 };000320003300037 enum {00039 ADC_CONVERSION_TIME_US_256 = 4200040 };000410004200045 enum00046 {00048 ADC_SOURCE_ADC0 = 0x0,

EmberZNet 4.7.2 API EM260 120-3020-000-4720

297

00050 ADC_SOURCE_ADC1 = 0x1,00052 ADC_SOURCE_ADC2 = 0x2,00054 ADC_SOURCE_ADC3 = 0x3,00056 ADC_SOURCE_ADC4 = 0x4,00058 ADC_SOURCE_ADC5 = 0x5,00060 ADC_SOURCE_ADC6 = 0x6,00062 ADC_SOURCE_ADC7 = 0x7,00063 };000640006500069 #endif //__AVR_ADC_H__

8.7 ami-inter-pan-host.h File Reference

Data Structures


Macros

• #define INTER_PAN_UNICAST• #define INTER_PAN_BROADCAST• #define INTER_PAN_MULTICAST• #define MAX_INTER_PAN_MAC_SIZE• #define STUB_NWK_SIZE• #define STUB_NWK_FRAME_CONTROL• #define MAX_STUB_APS_SIZE• #define MAX_INTER_PAN_HEADER_SIZE

Functions

• int8u makeInterPanMessage (InterPanHeader ∗headerData, int8u ∗message, int8u maxLength, int8u∗payload, int8u payloadLength)

• int8u parseInterPanMessage (int8u ∗message, int8u messageLength, InterPanHeader ∗headerData)


Utilities for sending and receiving ZigBee AMI InterPAN messages. See Sending and Receiving Messagesfor documentation.

Deprecated The ami-inter-pan library is deprecated and will be removed in a future release. Similarfunctionality is available in the Inter-PAN plugin in Application Framework.

Definition in file ami-inter-pan-host.h.

8.8 ami-inter-pan-host.h

0000100019 #ifndef AMI_INTER_PAN_HOST_H00020 #define AMI_INTER_PAN_HOST_H00021

EmberZNet 4.7.2 API EM260 120-3020-000-4720

298

00028 #define INTER_PAN_UNICAST 0x0300029 #define INTER_PAN_BROADCAST 0x0B00030 #define INTER_PAN_MULTICAST 0x0F000310003200033 // Frame control, sequence, dest PAN ID, dest, source PAN ID, source.00034 #define MAX_INTER_PAN_MAC_SIZE (2 + 1 + 2 + 8 + 2 + 8)00035 //Short form has a short destination.0003600037 // NWK stub frame has two control bytes.00038 #define STUB_NWK_SIZE 200039 #define STUB_NWK_FRAME_CONTROL 0x000B0004000041 // APS frame control, group ID, cluster ID, profile ID00042 #define MAX_STUB_APS_SIZE (1 + 2 + 2 + 2)0004300044 // Short form has no group ID.00045 #define MAX_INTER_PAN_HEADER_SIZE \00046 (MAX_INTER_PAN_MAC_SIZE + STUB_NWK_SIZE + MAX_STUB_APS_SIZE)0004700052 typedef struct {00053 int8u messageType; // one of the INTER_PAN_...CAST values0005400055 // MAC addressing00056 // For outgoing messages this is the destination. For incoming messages00057 // it is the source, which always has a long address.00058 int16u panId;00059 boolean hasLongAddress; // always TRUE for incoming messages00060 EmberNodeId shortAddress;00061 EmberEUI64 longAddress;0006200063 // APS data00064 int16u profileId;00065 int16u clusterId;00066 int16u groupId; // only used for INTER_PAN_MULTICAST00067 } InterPanHeader;0006800075 int8u makeInterPanMessage(InterPanHeader

*headerData,00076 int8u *message,00077 int8u maxLength,00078 int8u *payload,00079 int8u payloadLength);0008000088 int8u parseInterPanMessage(int8u *message,00089 int8u messageLength,00090 InterPanHeader *headerData);0009100092 #endif // AMI_INTER_PAN_HOST_H00093

8.9 ami-inter-pan.h File Reference

Data Structures


Macros

• #define INTER_PAN_UNICAST• #define INTER_PAN_BROADCAST• #define INTER_PAN_MULTICAST• #define MAX_INTER_PAN_MAC_SIZE• #define STUB_NWK_SIZE• #define STUB_NWK_FRAME_CONTROL• #define MAX_STUB_APS_SIZE

EmberZNet 4.7.2 API EM260 120-3020-000-4720

299

• #define MAX_INTER_PAN_HEADER_SIZE

Functions

• EmberMessageBuffer makeInterPanMessage (InterPanHeader ∗headerData, EmberMessageBufferpayload)

• int8u parseInterPanMessage (EmberMessageBuffer message, int8u startOffset, InterPanHeader ∗header-Data)


Utilities for sending and receiving ZigBee AMI InterPAN messages. See Sending and Receiving Messagesfor documentation.

Deprecated The ami-inter-pan library is deprecated and will be removed in a future release. Similarfunctionality is available in the Inter-PAN plugin in Application Framework.

Definition in file ami-inter-pan.h.

8.10 ami-inter-pan.h

0000100019 #ifndef AMI_INTER_PAN_H00020 #define AMI_INTER_PAN_H0002100022 // The three types of inter-PAN messages. The values are actually the00023 // corresponding APS frame controls.00024 //00025 // 0x03 is the special interPAN message type. Unicast mode is 0x00,00026 // broadcast mode is 0x08, and multicast mode is 0x0C.00027 //0002800029 #define INTER_PAN_UNICAST 0x0300030 #define INTER_PAN_BROADCAST 0x0B00031 #define INTER_PAN_MULTICAST 0x0F0003200033 // Frame control, sequence, dest PAN ID, dest, source PAN ID, source.00034 #define MAX_INTER_PAN_MAC_SIZE (2 + 1 + 2 + 8 + 2 + 8)00035 // Short form has a short destination.0003600037 // NWK stub frame has two control bytes.00038 #define STUB_NWK_SIZE 200039 #define STUB_NWK_FRAME_CONTROL 0x000B0004000041 // APS frame control, group ID, cluster ID, profile ID00042 #define MAX_STUB_APS_SIZE (1 + 2 + 2 + 2)00043 // Short form has no group ID.0004400045 #define MAX_INTER_PAN_HEADER_SIZE \00046 (MAX_INTER_PAN_MAC_SIZE + STUB_NWK_SIZE + MAX_STUB_APS_SIZE)0004700051 typedef struct {00052 int8u messageType; // one of the INTER_PAN_...CAST

values0005300054 // MAC addressing00055 // For outgoing messages this is the destination. For incoming messages00056 // it is the source, which always has a long address.00057 int16u panId;00058 boolean hasLongAddress; // always TRUE for incoming

messages00059 EmberNodeId shortAddress;00060 EmberEUI64 longAddress;0006100062 // APS data

EmberZNet 4.7.2 API EM260 120-3020-000-4720

300

00063 int16u profileId;00064 int16u clusterId;00065 int16u groupId; // only used for

INTER_PAN_MULTICAST00066 } InterPanHeader;000670006800072 EmberMessageBuffer makeInterPanMessage(

InterPanHeader *headerData,00073 EmberMessageBuffer

payload);0007400082 int8u parseInterPanMessage(EmberMessageBuffer

message,00083 int8u startOffset,00084 InterPanHeader *headerData);0008500086 #endif // AMI_INTER_PAN_H00087

8.11 ash-common.h File Reference

Macros

• #define ashStopAckTimer(void)• #define ashAckTimerIsRunning()• #define ashAckTimerIsNotRunning()• #define ashSetAckPeriod(msec)• #define ashGetAckPeriod()• #define ashSetAndStartAckTimer(msec)• #define ASH_NR_TIMER_BIT• #define ashStopNrTimer()• #define ashNrTimerIsNotRunning()

Functions

• int8u ashEncodeByte (int8u len, int8u byte, int8u ∗offset)• EzspStatus ashDecodeByte (int8u byte, int8u ∗out, int8u ∗outLen)• int8u ashRandomizeArray (int8u seed, int8u ∗buf, int8u len)• void ashStartAckTimer (void)• boolean ashAckTimerHasExpired (void)• void ashAdjustAckPeriod (boolean expired)• void ashStartNrTimer (void)• boolean ashNrTimerHasExpired (void)

Variables

• boolean ashDecodeInProgress• int16u ashAckTimer• int16u ashAckPeriod• int8u ashNrTimer

EmberZNet 4.7.2 API EM260 120-3020-000-4720

301


Header for ASH common functions. See Asynchronous Serial Host (ASH) Framework for documentation.

Definition in file ash-common.h.

8.12 ash-common.h

0000100010 #ifndef __ASH_COMMON_H__00011 #define __ASH_COMMON_H__0001200044 int8u ashEncodeByte(int8u len, int8u byte, int8u

*offset);0004500067 EzspStatus ashDecodeByte(int8u byte, int8u *out, int8u

*outLen);0006800086 int8u ashRandomizeArray(int8u seed, int8u *buf,

int8u len);0008700092 void ashStartAckTimer(void);0009300097 void ashStopAckTimer(void);00098 #define ashStopAckTimer() do {ashAckTimer = 0;} while (FALSE)0009900104 #define ashAckTimerIsRunning() (ashAckTimer != 0)0010500110 #define ashAckTimerIsNotRunning() (ashAckTimer == 0)0011100116 boolean ashAckTimerHasExpired(void);0011700134 void ashAdjustAckPeriod(boolean expired);0013500140 #define ashSetAckPeriod(msec) \00141 do {ashAckPeriod = msec; ashAckTimer = 0;} while (FALSE)0014200146 #define ashGetAckPeriod() (ashAckPeriod)0014700151 #define ashSetAndStartAckTimer(msec) \00152 do {ashSetAckPeriod(msec); ashStartAckTimer();} while (FALSE)0015300154 // Define the units used by the Not Ready timer as 2**n msecs00155 #define ASH_NR_TIMER_BIT 4 // log2 of msecs per NR timer unit0015600164 void ashStartNrTimer(void);0016500168 #define ashStopNrTimer() do {ashNrTimer = 0;} while (FALSE)0016900175 boolean ashNrTimerHasExpired(void);0017600180 #define ashNrTimerIsNotRunning() (ashAckTimer == 0)0018100182 extern boolean ashDecodeInProgress; // set FALSE to start

decoding a new frame0018300184 // ASH timers (units)00185 extern int16u ashAckTimer; // rec’d ack timer (msecs)00186 extern int16u ashAckPeriod; // rec’d ack timer period

(msecs)00187 extern int8u ashNrTimer; // not ready timer (16 msec

units)0018800189 #endif //__ASH_COMMON_H__00190

8.13 ash-host-io.h File Reference

EmberZNet 4.7.2 API EM260 120-3020-000-4720

302

Macros

• #define DEBUG_STREAM• #define ashDebugPrintf(...)• #define ashDebugVfprintf(format, argPointer)

Functions

• EzspStatus ashSerialInit (void)• void ashSerialClose (void)• void ashResetDtr (void)• void ashResetCustom (void)• EzspStatus ashSerialWriteAvailable (void)• void ashSerialWriteByte (int8u byte)• void ashSerialWriteFlush (void)• EzspStatus ashSerialReadByte (int8u ∗byte)• EzspStatus ashSerialReadAvailable (int16u ∗count)• void ashSerialReadFlush (void)• void ashDebugFlush (void)• int ashSerialGetFd (void)• boolean ashSerialOutputIsIdle (void)


Header for ASH host I/O functions. See ASH Application Utility for documentation.

Definition in file ash-host-io.h.

8.14 ash-host-io.h

0000100009 #ifndef __ASH_HOST_IO_H__00010 #define __ASH_HOST_IO_H__0001100027 EzspStatus ashSerialInit(void);0002800032 void ashSerialClose(void);0003300038 void ashResetDtr(void);0003900044 void ashResetCustom(void);0004500054 EzspStatus ashSerialWriteAvailable(void);0005500060 void ashSerialWriteByte(int8u byte);0006100066 void ashSerialWriteFlush(void);0006700076 EzspStatus ashSerialReadByte(int8u *byte);0007700086 EzspStatus ashSerialReadAvailable(int16u *count);0008700091 void ashSerialReadFlush(void);0009200095 void ashDebugFlush(void);0009600099 #define DEBUG_STREAM stdout0010000101 #ifdef WIN3200102 #define ashDebugPrintf printf

EmberZNet 4.7.2 API EM260 120-3020-000-4720

303

00103 #else00104 #define ashDebugPrintf(...) fprintf(DEBUG_STREAM, __VA_ARGS__)00105 #endif0010600107 #define ashDebugVfprintf(format, argPointer) \00108 vfprintf(DEBUG_STREAM, format, argPointer)0010900113 int ashSerialGetFd(void);001140011500122 boolean ashSerialOutputIsIdle(void);0012300124 #endif //__ASH_HOST_H___0012500126 #if !defined(DOXYGEN_SHOULD_SKIP_THIS)00127 EzspStatus ashSetupSerialPort(int* serialPortFdReturn,00128 char* errorStringLocation,00129 int maxErrorLength,00130 boolean bootloaderMode);00131 #endif00132

8.15 ash-host-priv.h File Reference

Functions

• void ashTraceFrame (boolean sent)• void ashTraceEventRecdFrame (const char ∗string)• void ashTraceEventTime (const char ∗string)• void ashTraceDisconnected (int8u error)• void ashTraceArray (int8u ∗name, int8u len, int8u ∗data)• void ashTraceEzspFrameId (const char ∗message, int8u ∗ezspFrame)• void ashTraceEzspVerbose (char ∗format,...)• void ashCountFrame (boolean sent)• int8u readTxControl (void)• int8u readRxControl (void)• int8u readAckRx (void)• int8u readAckTx (void)• int8u readFrmTx (void)• int8u readFrmReTx (void)• int8u readFrmRx (void)• int8u readAshTimeouts (void)


Private header for ASH Host functions. This file should be included only by ash-host-ui.c and ash-host.c.

See ASH Application Utility for documentation.

Definition in file ash-host-priv.h.

8.16 ash-host-priv.h

0000100018 #ifndef __ASH_HOST_PRIV_H__00019 #define __ASH_HOST_PRIV_H__0002000021 // Defined in ash-host-ui.c

EmberZNet 4.7.2 API EM260 120-3020-000-4720

304

00022 void ashTraceFrame(boolean sent);00023 void ashTraceEventRecdFrame(const char *string);00024 void ashTraceEventTime(const char *string);00025 void ashTraceDisconnected(int8u error);00026 void ashTraceArray(int8u *name, int8u len, int8u *

data);00027 void ashTraceEzspFrameId(const char *message, int8u *

ezspFrame);00028 void ashTraceEzspVerbose(char *format, ...);00029 void ashCountFrame(boolean sent);0003000031 // Defined in ash-host.c00032 int8u readTxControl(void);00033 int8u readRxControl(void);00034 int8u readAckRx(void);00035 int8u readAckTx(void);00036 int8u readFrmTx(void);00037 int8u readFrmReTx(void);00038 int8u readFrmRx(void);00039 int8u readAshTimeouts(void);0004000041 #endif //__ASH_HOST_PRIV_H___00042

8.17 ash-host-queues.h File Reference

Data Structures

• struct ashBufferBuffer to hold a DATA frame.

• struct AshQueueSimple queue (singly-linked list)

• struct AshFreeListSimple free list (singly-linked list)

Macros

• #define TX_POOL_BUFFERS• #define RX_FREE_LWM• #define RX_FREE_HWM

Typedefs

• typedef struct ashBuffer AshBuffer

Functions

• void ashInitQueues (void)• void ashFreeBuffer (AshFreeList ∗list, AshBuffer ∗buffer)• AshBuffer ∗ ashAllocBuffer (AshFreeList ∗list)• AshBuffer ∗ ashRemoveQueueHead (AshQueue ∗queue)• AshBuffer ∗ ashQueueHead (AshQueue ∗queue)• AshBuffer ∗ ashQueueNthEntry (AshQueue ∗queue, int8u n)• AshBuffer ∗ ashQueuePrecedingEntry (AshQueue ∗queue, AshBuffer ∗buffer)• AshBuffer ∗ ashRemoveQueueEntry (AshQueue ∗queue, AshBuffer ∗buffer)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

305

• int8u ashQueueLength (AshQueue ∗queue)• int8u ashFreeListLength (AshFreeList ∗list)• void ashAddQueueTail (AshQueue ∗queue, AshBuffer ∗buffer)• boolean ashQueueIsEmpty (AshQueue ∗queue)

Variables

• AshQueue txQueue• AshQueue reTxQueue• AshQueue rxQueue• AshFreeList txFree• AshFreeList rxFree


Header for ASH host queue functions. See ASH Application Utility for documentation.

Definition in file ash-host-queues.h.

8.18 ash-host-queues.h

0000100016 #ifndef __ASH_HOST_QUEUE_H__00017 #define __ASH_HOST_QUEUE_H__0001800024 #define TX_POOL_BUFFERS (EZSP_HOST_ASH_RX_POOL_SIZE + 5)0002500029 #define RX_FREE_LWM 800030 #define RX_FREE_HWM 120003100034 typedef struct ashBuffer {00035 struct ashBuffer *link;00036 int8u len;00037 int8u data[ASH_MAX_DATA_FIELD_LEN];00038 } AshBuffer;0003900042 typedef struct {00043 AshBuffer *tail;00044 } AshQueue;0004500048 typedef struct {00049 AshBuffer *link;00050 } AshFreeList;0005100057 void ashInitQueues(void);0005800064 void ashFreeBuffer(AshFreeList *list, AshBuffer

*buffer);0006500072 AshBuffer *ashAllocBuffer(AshFreeList *list);0007300081 AshBuffer *ashRemoveQueueHead(AshQueue *

queue);0008200090 AshBuffer *ashQueueHead(AshQueue *queue);0009100101 AshBuffer *ashQueueNthEntry(AshQueue *queue,

int8u n);0010200113 AshBuffer *ashQueuePrecedingEntry(AshQueue

*queue, AshBuffer *buffer);0011400123 AshBuffer *ashRemoveQueueEntry(AshQueue *

queue, AshBuffer *buffer);00124

EmberZNet 4.7.2 API EM260 120-3020-000-4720

306

00131 int8u ashQueueLength(AshQueue *queue);001320013300140 int8u ashFreeListLength(AshFreeList *list);0014100147 void ashAddQueueTail(AshQueue *queue, AshBuffer

*buffer);0014800155 boolean ashQueueIsEmpty(AshQueue *queue);0015600157 extern AshQueue txQueue;00158 extern AshQueue reTxQueue;00159 extern AshQueue rxQueue;00160 extern AshFreeList txFree;00161 extern AshFreeList rxFree;0016200163 #endif //__ASH_HOST_QUEUE_H___00164

8.19 ash-host-ui.h File Reference

Macros

• #define BUMP_HOST_COUNTER(mbr)• #define ADD_HOST_COUNTER(op, mbr)

Functions

• void ashPrintUsage (char ∗name)• boolean ashProcessCommandOptions (int argc, char ∗argv[ ])• void ashTraceEvent (const char ∗string)• void ashPrintCounters (AshCount ∗counters, boolean clear)• void ashClearCounters (AshCount ∗counters)• const int8u ∗ ashErrorString (int8u error)• const int8u ∗ ashEzspErrorString (int8u error)


Header for ASH Host user interface functions. See ASH Application Utility for documentation.

Definition in file ash-host-ui.h.

8.20 ash-host-ui.h

0000100016 #ifndef __ASH_HOST_UI_H__00017 #define __ASH_HOST_UI_H__0001800023 void ashPrintUsage(char *name);0002400033 boolean ashProcessCommandOptions(int argc, char *argv[]

);0003400043 void ashTraceEvent(const char *string);0004400051 void ashPrintCounters(AshCount *counters, boolean clear

);0005200057 void ashClearCounters(AshCount *counters);00058

EmberZNet 4.7.2 API EM260 120-3020-000-4720

307

00065 const int8u* ashErrorString(int8u error);0006600073 const int8u* ashEzspErrorString(int8u error);0007400075 #define BUMP_HOST_COUNTER(mbr) do {ashCount.mbr++;} while (0)00076 #define ADD_HOST_COUNTER(op, mbr) do {ashCount.mbr += op;} while(0)0007700078 #endif //__ASH_HOST_UI_H___00079

8.21 ash-host.h File Reference

Data Structures

• struct AshHostConfigConfiguration parameters: values must be defined before calling ashResetNcp() or ashStart(). Note that alltimes are in milliseconds.

• struct AshCount

Macros

• #define ASH_MAX_TIMEOUTS• #define ASH_MAX_WAKE_TIME• #define ASH_PORT_LEN• #define TRACE_FRAMES_BASIC• #define TRACE_FRAMES_VERBOSE• #define TRACE_EVENTS• #define TRACE_EZSP• #define TRACE_EZSP_VERBOSE• #define ASH_RESET_METHOD_RST• #define ASH_RESET_METHOD_DTR• #define ASH_RESET_METHOD_CUSTOM• #define ASH_RESET_METHOD_NONE• #define ASH_NCP_TYPE_EM2XX_EM3XX• #define ASH_HOST_CONFIG_EM2XX_EM3XX_115200_RTSCTS• #define ASH_HOST_CONFIG_EM2XX_EM3XX_57600_XONXOFF• #define ashReadConfig(member)• #define ashReadConfigOrDefault(member, defval)• #define ashWriteConfig(member, value)• #define BUMP_HOST_COUNTER(mbr)• #define ADD_HOST_COUNTER(op, mbr)

Functions

• EzspStatus ashSelectHostConfig (int8u config)• EzspStatus ashStart (void)• void ashStop (void)• EzspStatus ashSend (int8u len, const int8u ∗inptr)• EzspStatus ashResetNcp (void)• EzspStatus ashWakeUpNcp (boolean init)• boolean ashIsConnected (void)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

308

• void ashSendExec (void)• EzspStatus ashReceiveExec (void)• EzspStatus ashReceive (int8u ∗len, int8u ∗buffer)• boolean ashOkToSleep (void)

Variables

• EzspStatus ashError• EzspStatus ncpError• AshHostConfig ashHostConfig• AshCount ashCount• boolean ncpSleepEnabled


Header for ASH Host functions. See ASH Application Utility for documentation.

Definition in file ash-host.h.

8.22 ash-host.h

0000100016 #ifndef __ASH_HOST_H__00017 #define __ASH_HOST_H__0001800019 #define ASH_MAX_TIMEOUTS 600020 #define ASH_MAX_WAKE_TIME 15000022 #define ASH_PORT_LEN 4000024 // Bits in traceFlags to enable various host trace outputs00025 #define TRACE_FRAMES_BASIC 100026 #define TRACE_FRAMES_VERBOSE 200027 #define TRACE_EVENTS 400028 #define TRACE_EZSP 800029 #define TRACE_EZSP_VERBOSE 1600031 // resetMethod values00032 #define ASH_RESET_METHOD_RST 000033 #define ASH_RESET_METHOD_DTR 100034 #define ASH_RESET_METHOD_CUSTOM 200035 #define ASH_RESET_METHOD_NONE 300037 // ncpType values00038 #define ASH_NCP_TYPE_EM2XX_EM3XX 000040 // ashSelectHostConfig() values00041 #define ASH_HOST_CONFIG_EM2XX_EM3XX_115200_RTSCTS 000042 #define ASH_HOST_CONFIG_EM2XX_EM3XX_57600_XONXOFF 10004300047 typedef struct00048 {00049 char serialPort[ASH_PORT_LEN];00050 int32u baudRate;00051 int8u stopBits;00052 int8u rtsCts;00053 int16u outBlockLen;00054 int16u inBlockLen;00055 int8u traceFlags;00056 int8u txK;00057 int8u randomize;00058 int16u ackTimeInit;00059 int16u ackTimeMin;00060 int16u ackTimeMax;00061 int16u timeRst;00062 int8u nrLowLimit;00063 int8u nrHighLimit;00064 int16u nrTime;00065 int8u resetMethod;00066 int8u ncpType;

EmberZNet 4.7.2 API EM260 120-3020-000-4720

309

00067 } AshHostConfig;0006800069 #define ashReadConfig(member) \00070 (ashHostConfig.member)0007100072 #define ashReadConfigOrDefault(member, defval) \00073 (ashHostConfig.member)0007400075 #define ashWriteConfig(member, value) \00076 do { ashHostConfig.member = value; } while (0)0007700078 #define BUMP_HOST_COUNTER(mbr) do {ashCount.mbr++;} while (0)00079 #define ADD_HOST_COUNTER(op, mbr) do {ashCount.mbr += op;} while(0)0008000081 typedef struct00082 {00083 int32u txBytes;00084 int32u txBlocks;00085 int32u txData;00086 int32u txAllFrames;00087 int32u txDataFrames;00088 int32u txAckFrames;00089 int32u txNakFrames;00090 int32u txReDataFrames;00091 int32u txN0Frames;00092 int32u txN1Frames;00093 int32u txCancelled;00095 int32u rxBytes;00096 int32u rxBlocks;00097 int32u rxData;00098 int32u rxAllFrames;00099 int32u rxDataFrames;00100 int32u rxAckFrames;00101 int32u rxNakFrames;00102 int32u rxReDataFrames;00103 int32u rxN0Frames;00104 int32u rxN1Frames;00105 int32u rxCancelled;00107 int32u rxCrcErrors;00108 int32u rxCommErrors;00109 int32u rxTooShort;00110 int32u rxTooLong;00111 int32u rxBadControl;00112 int32u rxBadLength;00113 int32u rxBadAckNumber;00114 int32u rxNoBuffer;00115 int32u rxDuplicates;00116 int32u rxOutOfSequence;00117 int32u rxAckTimeouts;00118 } AshCount;0011900120 extern EzspStatus ashError;00121 extern EzspStatus ncpError;00122 extern AshHostConfig ashHostConfig;00123 extern AshCount ashCount;00124 extern boolean ncpSleepEnabled;0012500138 EzspStatus ashSelectHostConfig(int8u config);0013900148 EzspStatus ashStart(void);0014900154 void ashStop(void);0015500173 EzspStatus ashSend(int8u len, const int8u *inptr);0017400187 EzspStatus ashResetNcp(void);0018800199 EzspStatus ashWakeUpNcp(boolean init);0020000210 boolean ashIsConnected(void);0021100216 void ashSendExec(void);0021700229 EzspStatus ashReceiveExec(void);0023000244 EzspStatus ashReceive(int8u *len, int8u *buffer);0024500250 boolean ashOkToSleep(void);0025100252 #endif //__ASH_HOST_H___

EmberZNet 4.7.2 API EM260 120-3020-000-4720

310

00253

8.23 ash-protocol.h File Reference

#include "app/util/ezsp/ezsp-protocol.h"

Macros

• #define ASH_VERSION• #define ASH_FLAG• #define ASH_ESC• #define ASH_XON• #define ASH_XOFF• #define ASH_SUB• #define ASH_CAN• #define ASH_WAKE• #define ASH_FLIP• #define ASH_MIN_DATA_FIELD_LEN• #define ASH_MAX_DATA_FIELD_LEN• #define ASH_MIN_DATA_FRAME_LEN• #define ASH_MIN_FRAME_LEN• #define ASH_MAX_FRAME_LEN• #define ASH_CRC_LEN• #define ASH_MIN_FRAME_WITH_CRC_LEN• #define ASH_MAX_FRAME_WITH_CRC_LEN• #define ASH_NCP_SHFRAME_RX_LEN• #define ASH_NCP_SHFRAME_TX_LEN• #define ASH_HOST_SHFRAME_RX_LEN• #define ASH_HOST_SHFRAME_TX_LEN• #define ASH_DFRAME_MASK• #define ASH_CONTROL_DATA• #define ASH_SHFRAME_MASK• #define ASH_CONTROL_ACK• #define ASH_CONTROL_NAK• #define ASH_CONTROL_RST• #define ASH_CONTROL_RSTACK• #define ASH_CONTROL_ERROR• #define ASH_ACKNUM_MASK• #define ASH_ACKNUM_BIT• #define ASH_RFLAG_MASK• #define ASH_RFLAG_BIT• #define ASH_NFLAG_MASK• #define ASH_NFLAG_BIT• #define ASH_PFLAG_MASK• #define ASH_PFLAG_BIT• #define ASH_FRMNUM_MASK• #define ASH_FRMNUM_BIT

EmberZNet 4.7.2 API EM260 120-3020-000-4720

311

• #define ASH_GET_RFLAG(ctl)• #define ASH_GET_NFLAG(ctl)• #define ASH_GET_FRMNUM(ctl)• #define ASH_GET_ACKNUM(ctl)• #define ASH_FRAME_LEN_DATA_MIN• #define ASH_FRAME_LEN_ACK• #define ASH_FRAME_LEN_NAK• #define ASH_FRAME_LEN_RST• #define ASH_FRAME_LEN_RSTACK• #define ASH_FRAME_LEN_ERROR• #define MOD8(n)• #define INC8(n)• #define WITHIN_RANGE(lo, n, hi)


ASH protocol header. See Asynchronous Serial Host (ASH) Framework for documentation.

Definition in file ash-protocol.h.

8.24 ash-protocol.h

0000100016 #ifndef __ASH_PROTOCOL_H__00017 #define __ASH_PROTOCOL_H__0001800019 #include "app/util/ezsp/ezsp-protocol.h"0002000021 #define ASH_VERSION 2 // protocol version0002200023 // Special byte values for ASH protocol and/or low-level comm00024 // Bytes with these values must be escaped (byte-stuffed) before transmission00025 #define ASH_FLAG 0x7E00026 #define ASH_ESC 0x7D00027 #define ASH_XON 0x1100028 #define ASH_XOFF 0x1300029 #define ASH_SUB 0x1800030 #define ASH_CAN 0x1A00032 // The wake byte special function applies only when in between frames, so it00033 // does not need to be escaped within a frame.00034 #define ASH_WAKE 0xFF00036 // Constant used in byte-stuffing00037 #define ASH_FLIP 0x2000039 // Field and frame lengths, excluding flag byte and any byte stuffing overhead00040 // All limits are inclusive00041 #define ASH_MIN_DATA_FIELD_LEN EZSP_MIN_FRAME_LENGTH00042 #define ASH_MAX_DATA_FIELD_LEN EZSP_MAX_FRAME_LENGTH00043 #define ASH_MIN_DATA_FRAME_LEN (ASH_MIN_DATA_FIELD_LEN + 1) // with control00044 #define ASH_MIN_FRAME_LEN 1 // control plus data field, but not CRC00045 #define ASH_MAX_FRAME_LEN (ASH_MAX_DATA_FIELD_LEN + 1)00046 #define ASH_CRC_LEN 200047 #define ASH_MIN_FRAME_WITH_CRC_LEN (ASH_MIN_FRAME_LEN + ASH_CRC_LEN)00048 #define ASH_MAX_FRAME_WITH_CRC_LEN (ASH_MAX_FRAME_LEN + ASH_CRC_LEN)0004900050 // Define lengths of short frames - includes control byte and data field00051 #define ASH_NCP_SHFRAME_RX_LEN 200052 #define ASH_NCP_SHFRAME_TX_LEN 300053 #define ASH_HOST_SHFRAME_RX_LEN 300054 #define ASH_HOST_SHFRAME_TX_LEN 200056 // Control byte formats00057 // +---------+----+----+----+----+----+----+----+----++---------+00058 // | | B7 | B6 | B5 | B4 | B3 | B2 | B1 | B0 || Range |00059 // +---------+----+----+----+----+----+----+----+----++---------+00060 // | DATA | 0 | frameNum | rF | ackNum ||0x00-0x7F|00061 // +---------+----+----+----+----+----+----+----+----++---------+

EmberZNet 4.7.2 API EM260 120-3020-000-4720

312

00062 // | ACK | 1 | 0 | 0 | pF | nF | ackNum ||0x80-0x9F|00063 // | NAK | 1 | 0 | 1 | pF | nF | ackNum ||0xA0-0xBF|00064 // +---------+----+----+----+----+----+----+----+----++---------+00065 // | RST | 1 | 1 | 0 | 0 | 0 | 0 | 0 | 0 || 0xC0 |00066 // | RSTACK | 1 | 1 | 0 | 0 | 0 | 0 | 0 | 1 || 0xC1 |00067 // | ERROR | 1 | 1 | 0 | 0 | 0 | 0 | 1 | 0 || 0xC2 |00068 // +---------+----+----+----+----+----+----+----+----++---------+00069 // rF = rFlag (retransmission flag)00070 // nF = nFlag (receiver not ready flag)00071 // pF = flag reserved for future use00072 // Control byte values 0xC3-0xFE are unused, 0xFF is reserved.0007300074 // Define frame control byte codes00075 #define ASH_DFRAME_MASK 0x8000076 #define ASH_CONTROL_DATA 0x000007700078 #define ASH_SHFRAME_MASK 0xE000079 #define ASH_CONTROL_ACK 0x8000080 #define ASH_CONTROL_NAK 0xA000081 #define ASH_CONTROL_RST 0xC000082 #define ASH_CONTROL_RSTACK 0xC100083 #define ASH_CONTROL_ERROR 0xC20008400085 #define ASH_ACKNUM_MASK 0x0700086 #define ASH_ACKNUM_BIT 000087 #define ASH_RFLAG_MASK 0x0800088 #define ASH_RFLAG_BIT 300089 #define ASH_NFLAG_MASK 0x0800090 #define ASH_NFLAG_BIT 300091 #define ASH_PFLAG_MASK 0x1000092 #define ASH_PFLAG_BIT 400093 #define ASH_FRMNUM_MASK 0x7000094 #define ASH_FRMNUM_BIT 400095 #define ASH_GET_RFLAG(ctl) ((ctl & ASH_RFLAG_MASK ) >> ASH_RFLAG_BIT )00096 #define ASH_GET_NFLAG(ctl) ((ctl & ASH_NFLAG_MASK ) >> ASH_NFLAG_BIT )00097 #define ASH_GET_FRMNUM(ctl) ((ctl & ASH_FRMNUM_MASK) >> ASH_FRMNUM_BIT)00098 #define ASH_GET_ACKNUM(ctl) ((ctl & ASH_ACKNUM_MASK) >> ASH_ACKNUM_BIT)0009900100 // Lengths for each frame type: includes control and data field (if any),00101 // excludes the CRC and flag bytes00102 #define ASH_FRAME_LEN_DATA_MIN (ASH_MIN_DATA_FIELD_LEN + 1)00103 #define ASH_FRAME_LEN_ACK 1 // control00104 #define ASH_FRAME_LEN_NAK 1 // control00105 #define ASH_FRAME_LEN_RST 1 // control00106 #define ASH_FRAME_LEN_RSTACK 3 // control, version, reset reason00107 #define ASH_FRAME_LEN_ERROR 3 // control, version, error0010800109 // Define macros for handling 3-bit frame numbers modulo 800110 #define MOD8(n) ((n) & 7)00111 #define INC8(n) (n=(MOD8(n+1)))00112 // Return TRUE if n is within the range lo through hi, computed (mod 8)00113 #define WITHIN_RANGE(lo, n, hi) (MOD8(n-lo)<=MOD8(hi-lo))0011400115 #endif //__ASH_PROTOCOL_H__00116

8.25 bootload-ezsp-utils.h File Reference

Macros

• #define TICKS_PER_QUARTER_SECOND

Functions

• boolean hostBootloadUtilLaunchRequestHandler (int8u lqi, int8s rssi, int16u manufacturerId, int8u∗hardwareTag, EmberEUI64 sourceEui)

• void hostBootloadUtilQueryResponseHandler (int8u lqi, int8s rssi, boolean bootloaderActive, int16umanufacturerId, int8u ∗hardwareTag, EmberEUI64 targetEui, int8u bootloaderCapabilities, int8uplatform, int8u micro, int8u phy, int16u blVersion)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

313

• void hostBootloadReinitHandler (void)• boolean isTheSameEui64 (EmberEUI64 sourceEui, EmberEUI64 targetEui)• void printLittleEndianEui64 (int8u port, EmberEUI64 eui64)• void printBigEndianEui64 (int8u port, EmberEUI64 eui64)• EmberStatus debugPrintf (int8u port, PGM_P formatString,...)

Variables

• int16u nodeBlVersion• int8u nodePlat• int8u nodeMicro• int8u nodePhy• EzspStatus bootloadEzspLastError• EzspStatus ignoreNextEzspError


Utilities used for performing stand-alone bootloading over EZSP. See Bootloading for documentation.

Definition in file bootload-ezsp-utils.h.

8.26 bootload-ezsp-utils.h

0000100016 // application timers are based on quarter second intervals, each00017 // quarter second is measured in millisecond ticks. This value defines00018 // the approximate number of millisecond ticks in a quarter second.00019 // Account for variations in system timers.00020 #ifdef AVR_ATMEGA_3200021 #define TICKS_PER_QUARTER_SECOND 22500022 #else00023 #define TICKS_PER_QUARTER_SECOND 25000024 #endif0002500026 // Node build info00027 extern int16u nodeBlVersion;00028 extern int8u nodePlat;00029 extern int8u nodeMicro;00030 extern int8u nodePhy;000310003200033 // Both of these need to be correctly handled in the applications’s00034 // ezspErrorHandler().00035 // ezsp error info00036 extern EzspStatus bootloadEzspLastError;00037 // If this is not EZSP_SUCCESS, the next call to ezspErrorHandler()00038 // will ignore this error.00039 extern EzspStatus ignoreNextEzspError;000400004100042 // *******************************************************************00043 // Callback functions used by the bootload library.0004400072 boolean hostBootloadUtilLaunchRequestHandler

(int8u lqi,00073 int8s rssi,00074 int16u manufacturerId,00075 int8u *hardwareTag,00076 EmberEUI64 sourceEui);0007700121 void hostBootloadUtilQueryResponseHandler(

int8u lqi,00122 int8s rssi,00123 boolean bootloaderActive,

EmberZNet 4.7.2 API EM260 120-3020-000-4720

314

00124 int16u manufacturerId,00125 int8u *hardwareTag,00126 EmberEUI64 targetEui,00127 int8u bootloaderCapabilities,00128 int8u platform,00129 int8u micro,00130 int8u phy,00131 int16u blVersion);0013200140 void hostBootloadReinitHandler(void);001410014200143 // Suppport routines in the bootloader utils library0014400156 boolean isTheSameEui64(EmberEUI64 sourceEui, EmberEUI64

targetEui);0015700168 void printLittleEndianEui64(int8u port, EmberEUI64

eui64);0016900180 void printBigEndianEui64(int8u port, EmberEUI64

eui64);0018100199 EmberStatus debugPrintf(int8u port, PGM_P

formatString, ...);00200

8.27 bootload-utils.h File Reference

Macros

• #define BOOTLOAD_HARDWARE_TAG_SIZE

Enumerations

• enum bootloadMode { BOOTLOAD_MODE_NONE, BOOTLOAD_MODE_PASSTHRU }• enum bootloadState {

BOOTLOAD_STATE_NORMAL, BOOTLOAD_STATE_QUERY, BOOTLOAD_STATE_WAI-T_FOR_AUTH_CHALLENGE, BOOTLOAD_STATE_WAIT_FOR_AUTH_RESPONSE,BOOTLOAD_STATE_DELAY_BEFORE_START, BOOTLOAD_STATE_START_UNICAST_-BOOTLOAD, BOOTLOAD_STATE_START_BROADCAST_BOOTLOAD, BOOTLOAD_STA-TE_START_SENDING_IMAGE,BOOTLOAD_STATE_SENDING_IMAGE, BOOTLOAD_STATE_WAIT_FOR_IMAGE_ACK, B-OOTLOAD_STATE_WAIT_FOR_COMPLETE_ACK, BOOTLOAD_STATE_DONE }

Functions

• void bootloadUtilInit (int8u appPort, int8u bootloadPort)• EmberStatus bootloadUtilSendRequest (EmberEUI64 targetEui, int16u mfgId, int8u hardwareTag[B-

OOTLOAD_HARDWARE_TAG_SIZE], int8u encryptKey[BOOTLOAD_AUTH_COMMON_SI-ZE], bootloadMode mode)

• void bootloadUtilSendQuery (EmberEUI64 target)• void bootloadUtilStartBootload (EmberEUI64 target, bootloadMode mode)• void bootloadUtilTick (void)• boolean bootloadUtilLaunchRequestHandler (int16u manufacturerId, int8u hardwareTag[BOOTL-

OAD_HARDWARE_TAG_SIZE], EmberEUI64 sourceEui)• void bootloadUtilQueryResponseHandler (boolean bootloaderActive, int16u manufacturerId, int8u

hardwareTag[BOOTLOAD_HARDWARE_TAG_SIZE], EmberEUI64 targetEui, int8u bootloader-Capabilities, int8u platform, int8u micro, int8u phy, int16u blVersion)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

315

• void bootloadUtilSendAuthResponse (EmberEUI64 target)

Authentication Challenge and Response

The authentication challenge and response must be the same size. The size is chosen to be evenly divisibleby the size of a 128-bit AES block.

• #define BOOTLOAD_AUTH_COMMON_SIZE• #define BOOTLOAD_AUTH_CHALLENGE_SIZE• #define BOOTLOAD_AUTH_RESPONSE_SIZE

Bootload State Variables

Used to check whether a bootloading process is currently happening.

• #define IS_BOOTLOADING• bootloadState blState


Utilities used for performing stand-alone bootloading. See Bootloading for documentation.

Definition in file bootload-utils.h.

8.28 bootload-utils.h

0000100058 // *******************************************************************00059 // Literals that are needed by the application.0006000066 #define BOOTLOAD_AUTH_COMMON_SIZE 1600067 #define BOOTLOAD_AUTH_CHALLENGE_SIZE BOOTLOAD_AUTH_COMMON_SIZE00068 #define BOOTLOAD_AUTH_RESPONSE_SIZE BOOTLOAD_AUTH_COMMON_SIZE0006900076 #define BOOTLOAD_HARDWARE_TAG_SIZE 160007700078 #ifdef DOXYGEN_SHOULD_SKIP_THIS0007900082 enum bootloadMode00083 #else00084 typedef int8u bootloadMode;00085 enum00086 #endif00087 {00089 BOOTLOAD_MODE_NONE,00091 BOOTLOAD_MODE_PASSTHRU,00092 };0009300094 #ifdef DOXYGEN_SHOULD_SKIP_THIS0009500106 enum bootloadState00107 #else00108 typedef int8u bootloadState;00109 enum00110 #endif00111 {00112 BOOTLOAD_STATE_NORMAL,00113 BOOTLOAD_STATE_QUERY,00114 BOOTLOAD_STATE_WAIT_FOR_AUTH_CHALLENGE,

00115 BOOTLOAD_STATE_WAIT_FOR_AUTH_RESPONSE,

EmberZNet 4.7.2 API EM260 120-3020-000-4720

316

00116 BOOTLOAD_STATE_DELAY_BEFORE_START,00117 BOOTLOAD_STATE_START_UNICAST_BOOTLOAD,00118 BOOTLOAD_STATE_START_BROADCAST_BOOTLOAD

,00119 BOOTLOAD_STATE_START_SENDING_IMAGE,00120 BOOTLOAD_STATE_SENDING_IMAGE,00121 BOOTLOAD_STATE_WAIT_FOR_IMAGE_ACK,00122 BOOTLOAD_STATE_WAIT_FOR_COMPLETE_ACK,00123 BOOTLOAD_STATE_DONE00124 };001250012600127 // *******************************************************************00128 // Public functions that are called by the application.0012900143 void bootloadUtilInit(int8u appPort, int8u

bootloadPort);0014400166 EmberStatus bootloadUtilSendRequest(

EmberEUI64 targetEui,00167 int16u mfgId,00168 int8u hardwareTag[

BOOTLOAD_HARDWARE_TAG_SIZE],00169 int8u encryptKey[

BOOTLOAD_AUTH_COMMON_SIZE],00170 bootloadMode mode);0017100184 void bootloadUtilSendQuery(EmberEUI64 target);0018500203 void bootloadUtilStartBootload(EmberEUI64

target, bootloadMode mode);0020400210 void bootloadUtilTick(void);002110021200213 // *******************************************************************00214 // Callback functions used by the bootload library.0021500234 boolean bootloadUtilLaunchRequestHandler(int16u

manufacturerId,00235 int8u hardwareTag[

BOOTLOAD_HARDWARE_TAG_SIZE],00236 EmberEUI64 sourceEui);0023700267 void bootloadUtilQueryResponseHandler(boolean

bootloaderActive,00268 int16u manufacturerId,00269 int8u hardwareTag[

BOOTLOAD_HARDWARE_TAG_SIZE],00270 EmberEUI64 targetEui,00271 int8u bootloaderCapabilities,00272 int8u platform,00273 int8u micro,00274 int8u phy,00275 int16u blVersion);0027600289 void bootloadUtilSendAuthResponse(EmberEUI64

target);002900029100292 // *******************************************************************00293 // Bootload state variables0029400299 extern bootloadState blState;00300 #define IS_BOOTLOADING ((blState != BOOTLOAD_STATE_NORMAL) && \00301 (blState != BOOTLOAD_STATE_DONE))00302

8.29 bootloader-interface-standalone-v1.h File Reference

Macros

• #define BOOTLOADER_TYPE_STANDALONE• #define halBootloadAppStart(space, segment, ramPtr)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

317

• #define halBootloadAdjustFlash(space, segment, ramPtr)

Enumerations

• enum {BOOTLOADER_MODE_MENU, BOOTLOADER_MODE_PASSTHROUGH, BOOTLOADER-_MODE_CLONE, BOOTLOADER_MODE_CLONE_RECOVERY,BOOTLOADER_MODE_PASSTHROUGH_RECOVERY }

Functions

• EmberStatus halInternalStandaloneBootloaderTrap (int16u assumedBootloaderType, int8u trapNumber,...)• void halInternalAdjustFlashBlock (int16u ∗dst, int16u ∗src, int8u size)• EmberStatus halLaunchStandaloneBootloaderV1 (int8u mode, int8u ∗eui64)


Definition of the interface to the standalone bootloader. See Stand-Alone Bootloader Interface for docu-mentation.


Definition in file bootloader-interface-standalone-v1.h.

8.30 bootloader-interface-standalone-v1.h

0000100019 #ifndef __BOOTLOADER_STANDALONE_V1_H__00020 #define __BOOTLOADER_STANDALONE_V1_H__0002100026 #define BOOTLOADER_TYPE_STANDALONE 0xBEEF00027 // BOOTLOADER_TYPE_APP is defined in bootloader-interface-app.h0002800029 #ifndef DOXYGEN_SHOULD_SKIP_THIS0003000031 // Automatically used by the trap functions for triggering the bootloader00032 #define BOOTLOADER_APP_REQUEST_KEY 0xFA270003300034 // Constants used by the standalone bootloader00035 #define FLASH_TAB_POINTERS 0x00F000036 #define FLASH_TAB_POINTERS_DEFAULT_TOKEN_TAB_PTR 0 //DEPRECATED00037 #define FLASH_TAB_POINTERS_UPPER_TOKEN_TAB_PTR 2 //DEPRECATED00038 #define FLASH_TAB_POINTERS_BOOT_TRAP_TAB_PTR 400039 #define FLASH_TAB_POINTERS_HELPERFUNC_TAB 600040 #define BOOTLOADER_TRAPTAB_SIGNATURE 0xBEEF0004100042 #ifdef __HAS_ELPM__00043 #define LPM_HIGH(x,y) \00044 do { \00045 int8u reg; \00046 reg = RAMPZ; \00047 y = __extended_load_program_memory(x); \00048 RAMPZ = reg; \00049 } while(0)0005000051 // #define LPM_HIGH __extended_load_program_memory00052 #define FLASH_HIGH __farflash00053 #else00054 #define LPM_HIGH(x,y) \00055 do { \00056 y = __load_program_memory(x); \00057 } while(0)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

318

0005800059 #define FLASH_HIGH __flash00060 #endif // __HAS_ELPM__000610006200063000640006700071 #ifdef DOXYGEN_SHOULD_SKIP_THIS00072 enum StandaloneBootloaderTraps00073 #else00074 typedef int8u StandaloneBootloaderTraps;00075 enum00076 #endif00077 {00078 BOOT_TRAP_APP_START = 1,00079 BOOT_TRAP_FLASH_ADJUST = 300080 };00081 #endif // DOXYGEN_SHOULD_SKIP_THIS000820008300101 EmberStatus halInternalStandaloneBootloaderTrap

(int16u assumedBootloaderType,00102 int8u trapNumber, ...);0010300104 #ifndef DOXYGEN_SHOULD_SKIP_THIS0010500108 void bootloadAppStart(void);00109 #endif // DOXYGEN_SHOULD_SKIP_THIS0011000111 #ifdef DOXYGEN_SHOULD_SKIP_THIS0011200127 #define halBootloadAppStart(space, segment, ramPtr);00128 #else00129 #define halBootloadAppStart(space, segment, ramPtr) \00130 halInternalStandaloneBootloaderTrap(BOOTLOADER_TYPE_APP, \00131 BOOT_TRAP_APP_START)00132 #endif // DOXYGEN_SHOULD_SKIP_THIS0013300149 void halInternalAdjustFlashBlock(int16u* dst,

int16u* src, int8u size);0015000151 #ifdef DOXYGEN_SHOULD_SKIP_THIS0015200167 #define halBootloadAdjustFlash(space, segment, ramPtr);00168 #else00169 #define halBootloadAdjustFlash(space, segment, ramPtr) \00170 halInternalStandaloneBootloaderTrap(BOOTLOADER_TYPE_APP, \00171 BOOT_TRAP_FLASH_ADJUST, \00172 (segment), (ramPtr), (space))00173 #endif // DOXYGEN_SHOULD_SKIP_THIS0017400175 // Note: bootloaderMode 0 means go into passive bootloader mode. Note:00176 // this includes single hop pass thru.00177 // bootloaderMode 1 means clone to node in gatewayID00178 // bootloaderMode 2 means look for an errant node and clone to it.00179 // bootloaderMode 3 means look for an errant node and do pass thru.00180 // bootloaderMode 4 (not valid here) is later on used for single hop0018100182 enum {00183 BOOTLOADER_MODE_MENU = 0x00,00184 BOOTLOADER_MODE_PASSTHROUGH = 0x00,00185 BOOTLOADER_MODE_CLONE = 0x01,00186 BOOTLOADER_MODE_CLONE_RECOVERY = 0x02,00187 BOOTLOADER_MODE_PASSTHROUGH_RECOVERY =

0x0300188 };0018900214 EmberStatus halLaunchStandaloneBootloaderV1

(int8u mode, int8u *eui64);002150021700218 #endif //__BOOTLOADER_STANDALONE_V1_H__00219

8.31 bootloader-interface-standalone.h File Reference

EmberZNet 4.7.2 API EM260 120-3020-000-4720

319

Macros

• #define NO_BOOTLOADER_MODE• #define STANDALONE_BOOTLOADER_NORMAL_MODE• #define STANDALONE_BOOTLOADER_RECOVERY_MODE

Functions

• int16u halGetStandaloneBootloaderVersion (void)• EmberStatus halLaunchStandaloneBootloader (int8u mode)


See Stand-Alone Bootloader Interface for documentation.

Definition in file bootloader-interface-standalone.h.

8.32 bootloader-interface-standalone.h

0000100017 #ifndef __BOOTLOADER_STANDALONE_H__00018 #define __BOOTLOADER_STANDALONE_H__0001900028 int16u halGetStandaloneBootloaderVersion

(void);0002900033 #define NO_BOOTLOADER_MODE 0xFF0003400037 #define STANDALONE_BOOTLOADER_NORMAL_MODE 10003800041 #define STANDALONE_BOOTLOADER_RECOVERY_MODE 00004200061 EmberStatus halLaunchStandaloneBootloader

(int8u mode);000620006300064 #endif //__BOOTLOADER_STANDALONE_H__00065

8.33 bootloader.h File Reference


Micro-specific functions used in conjunction with either bootloader. Unless otherwise noted, the EmberNetstack does not use these functions, and therefore the HAL is not required to implement them. However,many of the supplied example applications do use them.


Definition in file bootloader.h.

8.34 bootloader.h

00001

EmberZNet 4.7.2 API EM260 120-3020-000-4720

320

00015 #ifndef __BOOTLOADER_H__00016 #define __BOOTLOADER_H__0001700018 #ifndef DOXYGEN_SHOULD_SKIP_THIS0001900020 // Definitions relevant to the application bootloader.00021 // Defines the starting segment offset for the download segment00022 // within the program space.00023 #define BOOTLOADER_DEFAULT_DOWNLOAD_SEGMENT 000024 // Defines the starting segment offset for the currently executing program00025 // within the program space.00026 #define BOOTLOADER_DEFAULT_PROGRAM_SEGMENT 400027 // Defines the starting segment offset for the recovery image00028 // within the program space.00029 #define BOOTLOADER_RECOVERY_IMAGE_SEGMENT 0x03E0000300003100032 // This points to where the trap table is stored in the internal flash00033 #define APP_TRAPTABLE_POINTER 0x1FFC00003400035 // Definition for the recovery image (a bit not used by UCSR1A for errors).00036 #define NO_SERIAL_DATA 0x80000370004200043 #if __HAS_ELPM__00044 #define halInternalReadFlashByte(addr) __extended_load_program_memory(addr)00045 #define halInternalReadFlashWord(addr) HIGH_LOW_TO_INT(

\00046 __extended_load_program_memory((addr)+1),

\00047 __extended_load_program_memory(addr) )00048 #else // __HAS_ELPM__0004900056 #define halInternalReadFlashByte(addr) __load_program_memory(addr)0005700064 #define halInternalReadFlashWord(addr) HIGH_LOW_TO_INT( \00065 __load_program_memory((addr)+1), \00066 __load_program_memory(addr) )00067 #endif // __HAS_ELPM__000680007000071 #endif // DOXYGEN_SHOULD_SKIP_THIS0007200073 #endif // __BOOTLOADER_H_

8.35 button.h File Reference

Functions

• void halInternalInitButton (void)• int8u halButtonState (int8u button)• int8u halButtonPinState (int8u button)• void halButtonIsr (int8u button, int8u state)

Button State Definitions

A set of numerical definitions for use with the button APIs indicating the state of a button.

• #define BUTTON_PRESSED• #define BUTTON_RELEASED


See Button Control for documentation.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

321

Definition in file button.h.

8.36 button.h

0000100024 #define BUTTON_PRESSED 10002500028 #define BUTTON_RELEASED 00002900036 void halInternalInitButton(void);0003700049 int8u halButtonState(int8u button);0005000063 int8u halButtonPinState(int8u button);0006400079 void halButtonIsr(int8u button, int8u state);00080

8.37 buzzer.h File Reference

Functions

• void halPlayTune_P (int8u PGM ∗tune, boolean bkg)• void halStackIndicatePresence (void)

Note Definitions

Flats are used instead of sharps because # is a special character.

• #define NOTE_C3• #define NOTE_Db3• #define NOTE_D3• #define NOTE_Eb3• #define NOTE_E3• #define NOTE_F3• #define NOTE_Gb3• #define NOTE_G3• #define NOTE_Ab3• #define NOTE_A3• #define NOTE_Bb3• #define NOTE_B3• #define NOTE_C4• #define NOTE_Db4• #define NOTE_D4• #define NOTE_Eb4• #define NOTE_E4• #define NOTE_F4• #define NOTE_Gb4• #define NOTE_G4• #define NOTE_Ab4• #define NOTE_A4• #define NOTE_Bb4

EmberZNet 4.7.2 API EM260 120-3020-000-4720

322

• #define NOTE_B4• #define NOTE_C5• #define NOTE_Db5• #define NOTE_D5• #define NOTE_Eb5• #define NOTE_E5• #define NOTE_F5• #define NOTE_Gb5• #define NOTE_G5• #define NOTE_Ab5• #define NOTE_A5• #define NOTE_Bb5• #define NOTE_B5


See Buzzer Control for documentation.

Definition in file buzzer.h.

8.38 buzzer.h

0000100023 #define NOTE_C3 11900024 #define NOTE_Db3 11200025 #define NOTE_D3 10600026 #define NOTE_Eb3 10000027 #define NOTE_E3 9400028 #define NOTE_F3 8900029 #define NOTE_Gb3 8400030 #define NOTE_G3 7900031 #define NOTE_Ab3 7400032 #define NOTE_A3 7000033 #define NOTE_Bb3 6600034 #define NOTE_B3 6300035 #define NOTE_C4 5900036 #define NOTE_Db4 5500037 #define NOTE_D4 5200038 #define NOTE_Eb4 4900039 #define NOTE_E4 4600040 #define NOTE_F4 4400041 #define NOTE_Gb4 4100042 #define NOTE_G4 3900043 #define NOTE_Ab4 3700044 #define NOTE_A4 3500045 #define NOTE_Bb4 3300046 #define NOTE_B4 3100047 #define NOTE_C5 2900048 #define NOTE_Db5 2700049 #define NOTE_D5 2600050 #define NOTE_Eb5 2400051 #define NOTE_E5 2300052 #define NOTE_F5 2100053 #define NOTE_Gb5 2000054 #define NOTE_G5 1900055 #define NOTE_Ab5 1800056 #define NOTE_A5 1700057 #define NOTE_Bb5 1600058 #define NOTE_B5 150005900082 void halPlayTune_P(int8u PGM *tune, boolean bkg);000830008400089 void halStackIndicatePresence(void);00090

EmberZNet 4.7.2 API EM260 120-3020-000-4720

323

8.39 cbke-crypto-engine.h File Reference

Functions

• EmberStatus emberGetCertificate (EmberCertificateData ∗result)• EmberStatus emberGenerateCbkeKeys (void)• EmberStatus emberCalculateSmacs (boolean amInitiator, EmberCertificateData ∗partnerCert, Ember-

PublicKeyData ∗partnerEphemeralPublicKey)• EmberStatus emberClearTemporaryDataMaybeStoreLinkKey (boolean storeLinkKey)• EmberStatus emberDsaSign (EmberMessageBuffer messageToSign)• void emberGenerateCbkeKeysHandler (EmberStatus status, EmberPublicKeyData ∗ephemeralPublic-

Key)• void emberCalculateSmacsHandler (EmberStatus status, EmberSmacData ∗initiatorSmac, Ember-

SmacData ∗responderSmac)• void emberDsaSignHandler (EmberStatus status, EmberMessageBuffer signedMessage)• EmberStatus emberSetPreinstalledCbkeData (EmberPublicKeyData ∗caPublic, EmberCertificateData∗myCert, EmberPrivateKeyData ∗myKey)

• boolean emberGetStackCertificateEui64 (EmberEUI64 certEui64)• EmberStatus emberDsaVerify (EmberMessageDigest ∗digest, EmberCertificateData ∗signerCertificate,

EmberSignatureData ∗receivedSig)• void emberDsaVerifyHandler (EmberStatus status)


EmberZNet Smart Energy security API. See Smart Energy Security for documention.

Definition in file cbke-crypto-engine.h.

8.40 cbke-crypto-engine.h

0000100030 EmberStatus emberGetCertificate(

EmberCertificateData* result);0003100047 EmberStatus emberGenerateCbkeKeys(void);0004800071 EmberStatus emberCalculateSmacs(boolean

amInitiator,00072 EmberCertificateData*

partnerCert,00073 EmberPublicKeyData*

partnerEphemeralPublicKey);0007400089 EmberStatus emberClearTemporaryDataMaybeStoreLinkKey

(boolean storeLinkKey);0009000091 /* @brief LEGACY FUNCTION: This functionality has been replaced by a single00092 * bit in the ::EmberApsFrame, ::EMBER_APS_OPTION_DSA_SIGN. Devices wishing00093 * to send signed messages should use that as it requires fewer function calls00094 * and message buffering. emberDsaSignHandler() is still called when using00095 * ::EMBER_APS_OPTION_DSA_SIGN. However, this function is still supported.00096 *00097 * This function begins the process of signing the passed message00098 * contained within the buffer. If no other ECC operation is going on,00099 * it will immediately return with ::EMBER_OPERATION_IN_PROGRESS.00100 * It will delay a period of time to let APS retries take place, but then it00101 * will shutdown the radio and consume the CPU processing until the signing00102 * is complete. This may take up to 1 second.00103 *00104 * The signed message will be returned in ::emberDsaSignHandler().00105 *

EmberZNet 4.7.2 API EM260 120-3020-000-4720

324

00106 * Note that the last byte of the buffer contents passed to this function has00107 * special significance. As the typical use case for DSA signing is to sign

the00108 * ZCL payload of a DRLC Report Event Status message in SE 1.0, there is often00109 * both a signed portion (ZCL payload) and an unsigned portion (ZCL header).00110 * The last byte in the content of messageToSign is therefore used as a00111 * special indicator to signify how many bytes of leading data in the buffer00112 * should be excluded from consideration during the signing process. If the00113 * signature needs to cover the entire buffer (all bytes except last one),00114 * the caller should ensure that the last byte of the buffer contents is 0.00115 * When the signature operation is complete, this final byte will be replaced00116 * by the signature type indicator (0x01 for ECDSA signatures), and the00117 * actual signature will be appended to the buffer after this byte.00118 *00119 * @param messageToSign The message buffer containing the complete message,00120 * both the to-be-signed portion as well as any leading data excluded from00121 * the signing operation. See note above regarding special requirements00122 * for this buffer.00123 *00124 * @return ::EMBER_OPERATION_IN_PROGRESS if the stack has queued up the00125 * operation for execution. ::EMBER_INVALID_CALL if the operation can’t be00126 * performed in this context (possibly because another ECC operation is00127 * pending.)00128 */00129 EmberStatus emberDsaSign(EmberMessageBuffer

messageToSign);001300013100132 /* @brief This function is an application callback that must be defined00133 * when using CBKE. It is called when the ephemeral key generation operation00134 * is complete. The newly generated public key is passed back to the00135 * application to be sent to the CBKE partner over-the-air. Internally00136 * the stack saves the public and private key pair until it the function00137 * ::emberClearTemporaryDataMaybeStoreLinkKey() is called by the application.00138 *00139 * @param status This is the ::EmberStatus value indicating the success or00140 * failure of the operation.00141 * @param ephemeralPublicKey A pointer to an ::EmberPublicKeyData structure00142 * containing the newly generated public key.00143 */00144 void emberGenerateCbkeKeysHandler(EmberStatus

status,00145 EmberPublicKeyData*

ephemeralPublicKey);0014600147 /* @brief This function is an application callback that must be defined00148 * when using CBKE. It is called when the shared secret generation is00149 * complete and the link key and SMACs have been derived. The link key is00150 * stored in a temporary location until the application decides to00151 * store or discard the key by calling00152 * ::emberClearTemporaryDataMaybeStoreLinkKey().00153 *00154 * @param status This is the ::EmberStatus value indicating the success or00155 * failure of the operation.00156 * @param initiatorSmac This is a pointer to the ::EmberSmacData structure00157 * to the initiator’s version of the SMAC.00158 * @param responderSmac This is a pointer to the ::EmberSmacData structure00159 * to the responder’s version of the SMAC.00160 */00161 void emberCalculateSmacsHandler(EmberStatus

status,00162 EmberSmacData* initiatorSmac,00163 EmberSmacData* responderSmac);0016400165 /* @brief This function is an application callback that must be defined00166 * when using CBKE. This callback is provided to the application to let00167 * it know that the ECC operations have completed and the radio has been turned00168 * back on. When using the sign-and-send option of the ::EmberApsFrame,00169 * ::EMBER_APS_OPTION_DSA_SIGN, the handler will NOT return the complete00170 * signed message. This callback is merely informative. If ::emberDsaSign()00171 * has been called, the message plus signature will be returned to the caller00172 * and it must be sent separately by one of the message send primitives00173 * (such as ::emberSendUnicast()).00174 *00175 * @param status This is the ::EmberStatus value indicating the success or00176 * failure of the operation.00177 * @param signedMessage This is the ::EmberMessageBuffer indicating the newly00178 * signed message, if ::emberDsaSign() was called. If message was signed00179 * using ::EMBER_APS_OPTION_DSA_SIGN then this will be00180 * ::EMBER_NULL_MESSAGE_BUFFER.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

325

00181 */00182 void emberDsaSignHandler(EmberStatus status,00183 EmberMessageBuffer signedMessage);001840018500186 /* @brief This function is used to update the Smart Energy certificate,00187 * CA public key, and local private key that the device uses for CBKE.00188 * The preferred method for adding certificates is to pre-install them00189 * in MFG tokens when the chip is manufactured. However this function00190 * allows the certificate to be updated at runtime after the device has00191 * been deployed.00192 * The behavior of this function differs based on the hardware platform.00193 *00194 * For the 2xx:00195 * To use this functionality the application must also set00196 * the stack configuration value ::EMBER_CERTIFICATE_TABLE_SIZE to 1.00197 * Attempts to call this function with ::EMBER_CERTIFICATE_TABLE_SIZE of 000198 * will return ::EMBER_SECURITY_CONFIGURATION_INVALID.00199 * The passed security data will be persistently stored in stack tokens.00200 * The certificate contains the EUI64 it is associated with. If that00201 * EUI64 matches the EUI64 currently in use by the device, this00202 * function may be called at any time, even while running in a network.00203 * If the EUI64 does not match, this function may only be called when the00204 * network is in a state of ::EMBER_NO_NETWORK. Attempts to do otherwise00205 * will result in a return value of ::EMBER_INVALID_CALL.00206 *00207 * For the 3xx:00208 * This function allows a one-time write of the MFG token if it has not00209 * already been set. It does NOT utilize the ::EMBER_CERTIFICATE_TABLE_SIZE00210 * so that should remain set at 0. Attempts to write the certificate that00211 * has already been written will return a result of00212 * ::EMBER_ERR_FLASH_WRITE_INHIBITED. If the EUI64 in the certificate is00213 * the same as the current EUI of the device then this function may be called00214 * while the stack is up. If the EUI in the certificate is different than00215 * the current value, this function may only be called when the network is in00216 * a state of ::EMBER_NO_NETWORK. Attempts to do otherwise will result in a00217 * return value of ::EMBER_INVALID_CALL. If the EUI in the certificate is00218 * different than the current value this function will also write the00219 * Custom EUI64 MFG token. If that token has already been written the

operation00220 * will fail and return a result of ::EMBER_BAD_ARGUMENT.00221 * If all the above criteria is met the token will be written and00222 * ::EMBER_SUCCESS will be returned.00223 *00224 * @note The device will immediately and persistently <b>change its EUI6400225 * to match the value in the certificate</b>.00226 *00227 * @param caPublic A pointer to the CA public key data that will be stored00228 * in stack tokens.00229 * @param myCert A pointer to the certificate data that will be stored in00230 * stack tokens.00231 * @param mykey A pointer to the private key data that will be stored in00232 * stack tokens.00233 * @return The ::EmberStatus value indicating success or failure of the00234 * operation.00235 */00236 EmberStatus emberSetPreinstalledCbkeData

(EmberPublicKeyData* caPublic,00237 EmberCertificateData

* myCert,00238 EmberPrivateKeyData

* myKey);0023900240 /* @brief This function retrieves the EUI64 from the stack token00241 * Smart Energy Certificate (it does not examine the MFG token certificate)00242 * and returns the value in the "Subject" field (the EUI64) to the caller.00243 * If no stack token is set, the ::EMBER_CERTIFICATE_TABLE_SIZE is zero00244 * or if the CBKE library is not present, this function returns FALSE00245 * and the EUI64 for the return value is not set.00246 *00247 * @param certEui64 The location of the return value for the EUI64.00248 * @return TRUE if the stack token certificate is set and the EUI6400249 * return value is valid. FALSE otherwise.00250 */00251 boolean emberGetStackCertificateEui64(EmberEUI64

certEui64);0025200253 /* @brief This function verifies the ECDSA signature of the00254 * calculated digest and the associated received signature, using00255 * the signerCertificate passed in. It is expected that the application

EmberZNet 4.7.2 API EM260 120-3020-000-4720

326

00256 * obtains the signerCertificate and performs the message digest calculation00257 * on its own.00258 */00259 EmberStatus emberDsaVerify(EmberMessageDigest

* digest,00260 EmberCertificateData*

signerCertificate,00261 EmberSignatureData* receivedSig);0026200263 /* @brief This callback is executed by the stack when the DSA verification00264 * has completed and has a result. If the result is EMBER_SUCCESS, the00265 * signature is valid. If the result is EMBER_SIGNATURE_VERIFY_FAILURE00266 * then the signature is invalid. If the result is anything else then the00267 * signature verify operation failed and the validity is unknown.00268 */00269 void emberDsaVerifyHandler(EmberStatus status);0027000271

8.41 command-interpreter.h File Reference

Data Structures


• struct EmberCommandStateSThe command state structure. Using a structure allows commands to be read from multiple sources.

Macros

• #define TEMP_GREATER_THAN_MAX_ARG_SIZE• #define PERFORM_BOUNDS_CHECKING• #define emberProcessCommandInput(state, port)• #define emberCommandName(state)

Typedefs

• typedef int16u ArgTypeU• typedef void(∗ CommandAction )(struct EmberCommandStateS ∗state)• typedef struct EmberCommandStateS EmberCommandState

Enumerations


EmberZNet 4.7.2 API EM260 120-3020-000-4720

327

Functions

• void emberCommandReaderInit (EmberCommandState ∗state)• boolean emberProcessCommandString (EmberCommandState ∗state, int8u ∗input, int8u size)

Variables

• PGM_NO_CONST PGM_P emberCommandErrorNames [ ]


• #define EMBER_COMMENT_CHARACTER• #define EMBER_MAX_COMMAND_LENGTH

Macros to Retrieve Arguments

Use the following macros in your functions that process commands to retrieve arguments from the com-mand interpreter state object. These macros pull out unsigned integers, signed integers, and buffers.

• #define emberUnsignedCommandArgument(state, index)• #define emberSignedCommandArgument(state, index)• #define emberBufferCommandArgument(state, index)


Processes commands coming from the serial port. See Command Interpreter for documentation.

Deprecated command-interpreter is deprecated and will be removed in a future release. Use command-interpreter2 instead.

Definition in file command-interpreter.h.

8.42 command-interpreter.h

0000100013 #ifndef __COMMAND_INTERPRETER_H__00014 #define __COMMAND_INTERPRETER_H__0001500071 #ifndef EMBER_COMMENT_CHARACTER0007200075 #define EMBER_COMMENT_CHARACTER ’#’00076 #endif0007700078 #ifndef EMBER_MAX_COMMAND_LENGTH0007900081 #define EMBER_MAX_COMMAND_LENGTH 1200082 #endif0008300087 //Since the Cortex-M3 platform is native 32bit, we enable 32bit unsigned00088 //arguments in the command interpreter. This is useful since any addresses or00089 //similar arguments are best supplied as 32bits. All other platforms are both00090 //not native 32bit and even more resource constrained, so only use 16bit args.00091 #ifdef CORTEXM300092 typedef int32u ArgTypeU;00093 #define TEMP_GREATER_THAN_MAX_ARG_SIZE (0)00094 #define PERFORM_BOUNDS_CHECKING (!((type==’u’)&&(size==’4’)))

EmberZNet 4.7.2 API EM260 120-3020-000-4720

328

00095 #else //everything else needs to save space00096 typedef int16u ArgTypeU;00097 #define TEMP_GREATER_THAN_MAX_ARG_SIZE (0xFFFF < temp)00098 #define PERFORM_BOUNDS_CHECKING (1)00099 #endif0010000101 struct EmberCommandStateS; // To allow forward use of

this type.0010200103 typedef void (*CommandAction)(struct EmberCommandStateS

*state);001040010500106 #ifdef DOXYGEN_SHOULD_SKIP_THIS0010700109 typedef struct {00110 #else00111 typedef PGM struct {00112 #endif0011300116 PGM_P longName;00120 CommandAction action;00142 PGM_P argumentTypes;00145 PGM_P description;00146 } EmberCommandEntry;0014700148 #ifdef DOXYGEN_SHOULD_SKIP_THIS0014900154 enum EmberCommandStatus00155 #else00156 typedef int8u EmberCommandStatus;00157 enum00158 #endif00159 {00160 EMBER_CMD_SUCCESS,00161 EMBER_CMD_ERR_PORT_PROBLEM,00162 EMBER_CMD_ERR_NO_BUFFER_AVAILABLE,00163 EMBER_CMD_ERR_NO_SUCH_COMMAND,00164 EMBER_CMD_ERR_WRONG_COMMAND_ARGUMENTS,

00165 EMBER_CMD_ERR_TOO_MANY_COMMAND_ARGUMENTS,

00166 EMBER_CMD_ERR_ARGUMENT_OUT_OF_RANGE,

00167 EMBER_CMD_ERR_ARGUMENT_SYNTAX_ERROR,

00168 EMBER_CMD_ERR_STRING_TOO_LONG,00169 EMBER_CMD_ERR_NO_BINARY_STRING_TERMINATOR

00170 };0017100172 extern PGM_NO_CONST PGM_P emberCommandErrorNames

[];0017300177 typedef struct EmberCommandStateS {00180 EmberCommandEntry *commands;00181 void (* errorHandler)(struct EmberCommandStateS

*state);00183 ArgTypeU *arguments;0018400185 int8u maximumArguments;00189 int8u integerBase;00191 int8u argumentCount;0019200193 // The rest are internal settings00194 //00196 int8u state;00198 int8u error;00202 int8u command[EMBER_MAX_COMMAND_LENGTH +

1];0020300204 int16u commandIndex;00206 PGM_P argumentSpecs;00208 int8u stringLength;00210 int8u binaryLength;0021100212 EmberMessageBuffer stringBuffer;0021300214 ArgTypeU integerValue;00216 int8u integerSign;

EmberZNet 4.7.2 API EM260 120-3020-000-4720

329

0021700218 int8u currentIntegerBase;0021900221 EmberCommandEntry *currentCommands;0022200223 } EmberCommandState;002240022500232 #define emberUnsignedCommandArgument(state, index) \00233 ((state)->arguments[index])0023400235 #define emberSignedCommandArgument(state, index) \00236 ((int16s) ((state)->arguments[index]))0023700238 #define emberBufferCommandArgument(state, index) \00239 (LOW_BYTE((state)->arguments[index]))0024000247 void emberCommandReaderInit(EmberCommandState

*state);0024800254 boolean emberProcessCommandString(EmberCommandState

*state,00255 int8u *input,00256 int8u size);0025700266 #define emberProcessCommandInput(state, port) \00267 emberProcessCommandString(state, NULL, port)0026800272 #define emberCommandName(state) (state->command)002730027400278 #endif //__COMMAND_INTERPRETER_H__

8.43 command-interpreter2.h File Reference

Data Structures


Macros

• #define MAX_TOKEN_COUNT• #define emberCommandEntryAction(name, action, argumentTypes, description)• #define emberCommandEntrySubMenu(name, subMenu, description)• #define emberCommandEntryTerminator()• #define EMBER_COMMAND_INTERPRETER_CONFIGURATION_ECHO• #define emberProcessCommandInput(port)• #define emberCommandInterpreterEchoOn()• #define emberCommandInterpreterEchoOff()• #define emberCommandInterpreterIsEchoOn()

Typedefs

• typedef void(∗ CommandAction )(void)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

330

Enumerations


Functions

• void emberCommandActionHandler (const CommandAction action)• void emberCommandErrorHandler (EmberCommandStatus status)• void emberPrintCommandUsage (EmberCommandEntry ∗entry)• void emberPrintCommandUsageNotes (void)• void emberPrintCommandTable (void)• void emberCommandReaderInit (void)• boolean emberProcessCommandString (int8u ∗input, int8u sizeOrPort)

Variables

• EmberCommandEntry ∗ emberCurrentCommand• EmberCommandEntry emberCommandTable [ ]• int8u emberCommandInterpreter2Configuration


• #define EMBER_MAX_COMMAND_ARGUMENTS• #define EMBER_COMMAND_BUFFER_LENGTH• #define EMBER_COMMAND_INTEPRETER_HAS_DESCRIPTION_FIELD

Functions to Retrieve Arguments

Use the following functions in your functions that process commands to retrieve arguments from the com-mand interpreter. These functions pull out unsigned integers, signed integers, and strings, and hex strings.Index 0 is the first command argument.

• #define emberCopyKeyArgument(index, keyDataPointer)• #define emberCopyEui64Argument(index, eui64)• int8u emberCommandArgumentCount (void)• int32u emberUnsignedCommandArgument (int8u argNum)• int16s emberSignedCommandArgument (int8u argNum)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

331

• int8u ∗ emberStringCommandArgument (int8s argNum, int8u ∗length)• int8u emberCopyStringArgument (int8s argNum, int8u ∗destination, int8u maxLength, boolean left-

Pad)


Processes commands coming from the serial port. See Commands2 for documentation.

Definition in file command-interpreter2.h.

8.44 command-interpreter2.h

0000100010 #ifndef __COMMAND_INTERPRETER2_H__00011 #define __COMMAND_INTERPRETER2_H__0001200100 #ifndef EMBER_MAX_COMMAND_ARGUMENTS0010100104 #define EMBER_MAX_COMMAND_ARGUMENTS 1000105 #endif0010600107 #ifndef EMBER_COMMAND_BUFFER_LENGTH00108 #define EMBER_COMMAND_BUFFER_LENGTH 10000109 #endif0011000115 #if defined(DOXYGEN_SHOULD_SKIP_THIS)00116 #define EMBER_COMMAND_INTEPRETER_HAS_DESCRIPTION_FIELD00117 #endif001180011900123 // The (+ 1) takes into account the leading command.00124 #define MAX_TOKEN_COUNT (EMBER_MAX_COMMAND_ARGUMENTS + 1)0012500126 typedef void (*CommandAction)(void);0012700128 #ifdef DOXYGEN_SHOULD_SKIP_THIS0012900131 typedef struct {00132 #else00133 typedef PGM struct {00134 #endif0013500138 PGM_P name;00144 CommandAction action;00171 PGM_P argumentTypes;00175 PGM_P description;00176 } EmberCommandEntry;001770017800179 #if defined(EMBER_COMMAND_INTEPRETER_HAS_DESCRIPTION_FIELD)00180 /* @brief Macro to define a CLI action */00181 #define emberCommandEntryAction(name, action, argumentTypes, description) \00182 { (name), (action), (argumentTypes), (description) }0018300184 /* @brief Macro to define a CLI sub-menu (nested command) */00185 #define emberCommandEntrySubMenu(name, subMenu, description) \00186 { (name), NULL, (PGM_P)(subMenu), (description) }0018700188 /* @briefy Macro to define a command entry array terminator.*/00189 #define emberCommandEntryTerminator() \00190 { NULL, NULL, NULL, NULL }0019100192 #else // Don’t include description data in struct00193 /* @brief Macro to define a CLI action */00194 #define emberCommandEntryAction(name, action, argumentTypes, description) \00195 { (name), (action), (argumentTypes), NULL }0019600197 /* @brief Macro to define a CLI sub-menu (nested command) */00198 #define emberCommandEntrySubMenu(name, subMenu, description) \00199 { (name), NULL, (PGM_P)(subMenu), NULL }0020000201 /* @briefy Macro to define a command entry array terminator.*/

EmberZNet 4.7.2 API EM260 120-3020-000-4720

332

00202 #define emberCommandEntryTerminator() \00203 { NULL, NULL, NULL, NULL }0020400205 #endif0020600213 extern EmberCommandEntry *emberCurrentCommand

;0021400215 extern EmberCommandEntry emberCommandTable[];0021600220 extern int8u emberCommandInterpreter2Configuration

;0022100222 #define EMBER_COMMAND_INTERPRETER_CONFIGURATION_ECHO (0x01)0022300224 #ifdef DOXYGEN_SHOULD_SKIP_THIS0022500230 enum EmberCommandStatus00231 #else00232 typedef int8u EmberCommandStatus;00233 enum00234 #endif00235 {00236 EMBER_CMD_SUCCESS,00237 EMBER_CMD_ERR_PORT_PROBLEM,00238 EMBER_CMD_ERR_NO_SUCH_COMMAND,00239 EMBER_CMD_ERR_WRONG_NUMBER_OF_ARGUMENTS

,00240 EMBER_CMD_ERR_ARGUMENT_OUT_OF_RANGE,

00241 EMBER_CMD_ERR_ARGUMENT_SYNTAX_ERROR,

00242 EMBER_CMD_ERR_STRING_TOO_LONG,00243 EMBER_CMD_ERR_INVALID_ARGUMENT_TYPE00244 };0024500255 int8u emberCommandArgumentCount(void);0025600258 int32u emberUnsignedCommandArgument(int8u

argNum);0025900261 int16s emberSignedCommandArgument(int8u

argNum);0026200271 int8u *emberStringCommandArgument(int8s

argNum, int8u *length);0027200285 int8u emberCopyStringArgument(int8s argNum,00286 int8u *destination,00287 int8u maxLength,00288 boolean leftPad);0028900293 #define emberCopyKeyArgument(index, keyDataPointer) \00294 (emberCopyStringArgument((index), \00295 emberKeyContents((keyDataPointer)), \00296 EMBER_ENCRYPTION_KEY_SIZE, \00297 TRUE))0029800300 #define emberCopyEui64Argument(index, eui64) \00301 (emberCopyStringArgument((index), (eui64), EUI64_SIZE, TRUE))0030200310 void emberCommandActionHandler(const CommandAction

action);00317 void emberCommandErrorHandler(EmberCommandStatus

status);00318 void emberPrintCommandUsage(EmberCommandEntry

*entry);00319 void emberPrintCommandUsageNotes(void);00320 void emberPrintCommandTable(void);0032100324 void emberCommandReaderInit(void);0032500328 boolean emberProcessCommandString(int8u *input,

int8u sizeOrPort);0032900338 #define emberProcessCommandInput(port) \00339 emberProcessCommandString(NULL, port)0034000343 #define emberCommandInterpreterEchoOn() \00344 (emberCommandInterpreter2Configuration \

EmberZNet 4.7.2 API EM260 120-3020-000-4720

333

00345 |= EMBER_COMMAND_INTERPRETER_CONFIGURATION_ECHO)0034600349 #define emberCommandInterpreterEchoOff() \00350 (emberCommandInterpreter2Configuration \00351 &= (~EMBER_COMMAND_INTERPRETER_CONFIGURATION_ECHO))0035200355 #define emberCommandInterpreterIsEchoOn() \00356 (emberCommandInterpreter2Configuration \00357 & EMBER_COMMAND_INTERPRETER_CONFIGURATION_ECHO)0035800361 #endif // __COMMAND_INTERPRETER2_H__

8.45 crc.h File Reference

Macros

• #define INITIAL_CRC• #define CRC32_START• #define CRC32_END

Functions

• int16u halCommonCrc16 (int8u newByte, int16u prevResult)• int32u halCommonCrc32 (int8u newByte, int32u prevResult)


See Cyclic Redundancy Code (CRC) for detailed documentation.

Definition in file crc.h.

8.46 crc.h

0000100007 #ifndef __CRC_H__00008 #define __CRC_H__0000900028 int16u halCommonCrc16(int8u newByte, int16u

prevResult);000290003000046 int32u halCommonCrc32(int8u newByte, int32u

prevResult);0004700048 // Commonly used initial and expected final CRC32 values00049 #define INITIAL_CRC 0xFFFFFFFFL00050 #define CRC32_START INITIAL_CRC00051 #define CRC32_END 0xDEBB20E3L // For CRC32 POLYNOMIAL run

LSB-MSB000520005300057 #endif //__CRC_H__00058

8.47 dev0470.h File Reference

EmberZNet 4.7.2 API EM260 120-3020-000-4720

334



The values used here are based upon an ATmega32L Host operating at 3.6864MHz which generates a17.361us tick.




• #define SPIP_nSSEL_PORT• #define SPIP_nSSEL_DDR• #define SPIP_nSSEL• #define SPIP_MOSI_PORT• #define SPIP_MOSI_DDR• #define SPIP_MOSI• #define SPIP_MISO_PORT• #define SPIP_MISO_DDR• #define SPIP_MISO• #define SPIP_SCLK_PORT• #define SPIP_SCLK_DDR• #define SPIP_SCLK• #define SPIP_nHOST_INT_PORT• #define SPIP_nHOST_INT_DDR• #define SPIP_nHOST_INT_PIN• #define SPIP_nHOST_INT• #define SPIP_nWAKE_PORT• #define SPIP_nWAKE_DDR• #define SPIP_nWAKE• #define SPIP_nRESET_PORT• #define SPIP_nRESET_DDR• #define SPIP_nRESET

LED Definitions

The following are used to aid in the abstraction with the LED connections. The names and ports/pins usedbelow are intended to match with a schematic of the system to provide the abstraction.

The BOARDLEDn macros should always be used when manipulating the state of LEDs.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

335

• #define BOARDLED_MASK• #define LED_DDR• #define LED_PORT• enum HalBoardLedPins {

BOARDLED0, BOARDLED1, BOARDLED2, BOARDLED3,BOARDLED4, BOARDLED5, BOARD_ACTIVITY_LED, BOARD_HEARTBEAT_LED,BOARDLED0, BOARDLED1, BOARD_ACTIVITY_LED, BOARD_HEARTBEAT_LED,BOARDLED0, BOARDLED1, BOARD_ACTIVITY_LED, BOARD_HEARTBEAT_LED }

Button Definitions



• #define BUTTON0• #define BUTTON0_PORT• #define BUTTON0_DDR• #define BUTTON0_PIN• #define BUTTON0_INT• #define BUTTON0_INT_VECT• #define BUTTON0_CONFIG_FALLING_EDGE()• #define BUTTON0_CONFIG_RISING_EDGE()• #define BUTTON1• #define BUTTON1_PORT• #define BUTTON1_DDR• #define BUTTON1_PIN• #define BUTTON1_INT• #define BUTTON1_INT_VECT• #define BUTTON1_CONFIG_FALLING_EDGE()• #define BUTTON1_CONFIG_RISING_EDGE()


Define the analog input channel connected to the LM-20 temperature sensor. The scale factor compensatesfor different platform input ranges. PA0/ADC0 must be an input. PA1 must be an output and set to a highlevel to power the sensor.




EmberZNet 4.7.2 API EM260 120-3020-000-4720

336



Functions specific to the dev0470 breakout board. See Carrier Board Control.

Definition in file dev0470.h.

8.48 dev0470.h

0000100017 #ifndef __BOARD_H__00018 #define __BOARD_H__0001900020 //This is the most convenient place to suck in the necessary header file00021 //operating the SPI Protocol.00022 #ifndef DOXYGEN_SHOULD_SKIP_THIS00023 #include "hal/micro/avr-atmega/spi-protocol.h

"00024 #endif //DOXYGEN_SHOULD_SKIP_THIS0002500026 //we operate at 3.6864MHz (17.361us tick) so we need to use the following:00038 #define TCCR1B_CONFIGURATION (BIT(CS11)|BIT(CS10))00039 #define WAIT_SECTION_TIMEOUT 17280 //300ms00040 #define INTER_COMMAND_SPACING 57 //1ms00041 #define WAKE_HANDSHAKE_TIMEOUT 17280 //300ms00042 #define STARTUP_TIMEOUT_SINGLE 42750 //750ms00043 //[[ WBBFIXME-measure exactly how long we need during bootup; set to 10 for ]]00044 //[[ plenty of time until we figure out how long bootloader takes ]]00045 #define STARTUP_TIMEOUT_COUNT 10 // count*750 = 7500ms00046 //actual startup timeout time is (single*count) = 7500ms000480004900059 #define SPIP_nSSEL_PORT PORTB00060 #define SPIP_nSSEL_DDR DDRB00061 #define SPIP_nSSEL 400062 #define SPIP_MOSI_PORT PORTB00063 #define SPIP_MOSI_DDR DDRB00064 #define SPIP_MOSI 500065 #define SPIP_MISO_PORT PORTB00066 #define SPIP_MISO_DDR DDRB00067 #define SPIP_MISO 600068 #define SPIP_SCLK_PORT PORTB00069 #define SPIP_SCLK_DDR DDRB00070 #define SPIP_SCLK 700071 #define SPIP_nHOST_INT_PORT PORTD00072 #define SPIP_nHOST_INT_DDR DDRD00073 #define SPIP_nHOST_INT_PIN PIND00074 #define SPIP_nHOST_INT 200075 #define SPIP_nWAKE_PORT PORTB00076 #define SPIP_nWAKE_DDR DDRB00077 #define SPIP_nWAKE 300078 #define SPIP_nRESET_PORT PORTB00079 #define SPIP_nRESET_DDR DDRB00080 #define SPIP_nRESET 100081000820008300097 enum HalBoardLedPins {00098 BOARDLED0 = 2,00099 BOARDLED1 = 3,00100 BOARD_ACTIVITY_LED = BOARDLED0,00101 BOARD_HEARTBEAT_LED = BOARDLED100102 };00103 #define BOARDLED_MASK 0x0C0010400105 #define LED_DDR DDRA00106 #define LED_PORT PORTA00107

EmberZNet 4.7.2 API EM260 120-3020-000-4720

337

00108001090012000121 // Note that BUTTON0 cannot be used to wake the processor, as INT100122 // does not support wakeup on an edge.00123 #define BUTTON0 300124 #define BUTTON0_PORT PORTD00125 #define BUTTON0_DDR DDRD00126 #define BUTTON0_PIN PIND00127 #define BUTTON0_INT INT100128 #define BUTTON0_INT_VECT INT1_vect00129 #define BUTTON0_CONFIG_FALLING_EDGE() \00130 do { \00131 MCUCR |= BIT(ISC11); \00132 MCUCR &= ~BIT(ISC10); \00133 } while(0)00134 #define BUTTON0_CONFIG_RISING_EDGE() \00135 do { \00136 MCUCR |= BIT(ISC11); \00137 MCUCR |= BIT(ISC10); \00138 } while(0)0013900140 #define BUTTON1 200141 #define BUTTON1_PORT PORTB00142 #define BUTTON1_DDR DDRB00143 #define BUTTON1_PIN PINB00144 #define BUTTON1_INT INT200145 #define BUTTON1_INT_VECT INT2_vect00146 #define BUTTON1_CONFIG_FALLING_EDGE() \00147 do { \00148 MCUCSR &= ~BIT(ISC2); \00149 } while(0)00150 #define BUTTON1_CONFIG_RISING_EDGE() \00151 do { \00152 MCUCSR |= BIT(ISC2); \00153 } while(0)001540015600166 #define TEMP_SENSOR_ADC_CHANNEL ADC_SOURCE_ADC000167 #define TEMP_SENSOR_SCALE_FACTOR 20016800180 #define halInternalInitBoard() \00181 do { \00182 halInternalInitAdc(); \00183 halInternalInitButton(); \00184 halInternalInitLed(); \00185 /* temp sensor */ \00186 DDRA |= BIT(1); \00187 PORTA |= BIT(1); \00188 /* Buzzer */ \00189 DDRD |= 0x80; \00190 PORTD |= 0x80; \00191 /*** Configure SPI Protocol pins ***/ \00192 /*nRESET default input/pullup until used*/ \00193 SPIP_nRESET_DDR &= ~BIT(SPIP_nRESET); \00194 SPIP_nRESET_PORT |= BIT(SPIP_nRESET); \00195 /*Activate nHOST_INT internal pullup*/ \00196 SPIP_nHOST_INT_DDR &= ~BIT(SPIP_nHOST_INT); \00197 SPIP_nHOST_INT_PORT |= BIT(SPIP_nHOST_INT); \00198 /*Falling edge detection on nHOST_INT*/ \00199 EICRA |= BIT(ISC01);EICRA &= ~BIT(ISC00); \00200 SPIP_nWAKE_PORT |= BIT(SPIP_nWAKE); \00201 SPIP_nWAKE_DDR |= BIT(SPIP_nWAKE); \00202 SPIP_nSSEL_PORT |= BIT(SPIP_nSSEL); \00203 SPIP_nSSEL_DDR |= BIT(SPIP_nSSEL); \00204 SPIP_MOSI_PORT |= BIT(SPIP_MOSI); \00205 SPIP_MOSI_DDR |= BIT(SPIP_MOSI); \00206 SPIP_SCLK_PORT |= BIT(SPIP_SCLK); \00207 SPIP_SCLK_DDR |= BIT(SPIP_SCLK); \00208 /* SPI Master, Mode 0 */ \00209 SPCR = BIT(SPE) | BIT(MSTR); \00210 /* Fastest SPI speed = 3.6864Mhz/2 */ \00211 SPSR = BIT(SPI2X); \00212 /*initialize the SPI Protocol*/ \00213 halNcpSerialInit(); \00214 } while(0)0021500216 #define halInternalPowerDownBoard() \00217 do { \00218 halInternalSleepAdc(); \

EmberZNet 4.7.2 API EM260 120-3020-000-4720

338

00219 halInternalInitLed(); \00220 /* Disable Buzzer */ \00221 TCCR2 = BIT(WGM21); /* no clock, no timer override */ \00222 TIMSK &= ~(BIT(OCIE2)); /* disable interrupt */ \00223 /* Disable Temp sensor */ \00224 PORTA &= ~BIT(1); \00225 /* Wait for nHOST_INT to go high so that we don’t */ \00226 /* immediately get interrupted and wake the host */ \00227 /* unnecessarily */ \00228 while (((SPIP_nHOST_INT_PIN&BIT(SPIP_nHOST_INT))== 0) \00229 && ((EIFR&BIT(INTF0)) != BIT(INTF0))) {}; \00230 /* Set nHOST_INT to trigger low */ \00231 /* - edge triggers will not wake the Atmega32 */ \00232 EICRA &= ~(BIT(ISC01) | BIT(ISC00)); \00233 EIFR = BIT(INTF0); /*clear interrupt flag */ \00234 EIMSK |= BIT(INT0);/*enable nHOST_INT interrupt for wake */ \00235 } while(0)0023600237 #define halInternalPowerUpBoard() \00238 do { \00239 halInternalInitAdc(); \00240 /* Enable Temp sensor */ \00241 DDRA |= BIT(1); \00242 PORTA |= BIT(1); \00243 EIMSK &= ~BIT(INT0);/* disable nHOST_INT interrupt */ \00244 EIFR = BIT(INTF0); /* clear interrupt flag */ \00245 /* Set nHOST_INT back to trigger on falling edge... */ \00246 EICRA |= BIT(ISC01);EICRA &= ~BIT(ISC00); \00247 halNcpSerialPowerup(); \00248 } while(0)002490025000251 #endif //__BOARD_H__00252

8.49 dev0473.h File Reference



The values used here are based upon an ATmega128L Host operating at 8MHz which generates a 32ustick.




• #define SPIP_nSSEL_PORT• #define SPIP_nSSEL_DDR• #define SPIP_nSSEL• #define SPIP_MOSI_PORT

EmberZNet 4.7.2 API EM260 120-3020-000-4720

339

• #define SPIP_MOSI_DDR• #define SPIP_MOSI• #define SPIP_MISO_PORT• #define SPIP_MISO_DDR• #define SPIP_MISO• #define SPIP_SCLK_PORT• #define SPIP_SCLK_DDR• #define SPIP_SCLK• #define SPIP_nHOST_INT_PORT• #define SPIP_nHOST_INT_DDR• #define SPIP_nHOST_INT_PIN• #define SPIP_nHOST_INT• #define SPIP_nWAKE_PORT• #define SPIP_nWAKE_DDR• #define SPIP_nWAKE• #define SPIP_nRESET_PORT• #define SPIP_nRESET_DDR• #define SPIP_nRESET

LED Definitions

The following are used to aid in the abstraction with the LED connections. The microcontroller-specificsources use these definitions so they are able to work across a variety of boards which could have differentconnections. The names and ports/pins used below are intended to match with a schematic of the systemto provide the abstraction.

The BOARDLEDn enum values should always be used when manipulating the state of LEDs, as theydirectly refer to the pins to which the LEDs are connected


• #define BOARDLED_MASK• #define LED_DDR• #define LED_PORT• enum HalBoardLedPins {

BOARDLED0, BOARDLED1, BOARDLED2, BOARDLED3,BOARDLED4, BOARDLED5, BOARD_ACTIVITY_LED, BOARD_HEARTBEAT_LED,BOARDLED0, BOARDLED1, BOARD_ACTIVITY_LED, BOARD_HEARTBEAT_LED,BOARDLED0, BOARDLED1, BOARD_ACTIVITY_LED, BOARD_HEARTBEAT_LED }

Button Definitions



• #define BUTTON0• #define BUTTON0_PORT• #define BUTTON0_DDR• #define BUTTON0_PIN

EmberZNet 4.7.2 API EM260 120-3020-000-4720

340

• #define BUTTON0_INT• #define BUTTON0_INT_VECT• #define BUTTON0_CONFIG_FALLING_EDGE()• #define BUTTON0_CONFIG_RISING_EDGE()• #define BUTTON1• #define BUTTON1_PORT• #define BUTTON1_DDR• #define BUTTON1_PIN• #define BUTTON1_INT• #define BUTTON1_INT_VECT• #define BUTTON1_CONFIG_FALLING_EDGE()• #define BUTTON1_CONFIG_RISING_EDGE()


Define the analog input channel connected to the LM-20 temperature sensor. The scale factor compensatesfor different platform input ranges. PF1/ADC1 must be an input. PC7 must be an output and set to a highlevel to power the sensor.






Functions specific to the dev0473 breakout board (ATmega128L-EM260). See Carrier Board Control fordocumentation.

Definition in file dev0473.h.

8.50 dev0473.h

0000100018 #ifndef __BOARD_H__00019 #define __BOARD_H__0002000021 //This is the most convenient place to suck in the necessary header file00022 //operating the SPI Protocol.00023 #ifndef DOXYGEN_SHOULD_SKIP_THIS00024 #include "hal/micro/avr-atmega/spi-protocol.h

"00025 #endif //DOXYGEN_SHOULD_SKIP_THIS

EmberZNet 4.7.2 API EM260 120-3020-000-4720

341

0002600027 //we operate at 8MHz (32us tick) so we need to use the following:00039 #define TCCR1B_CONFIGURATION (BIT(CS12))00040 #define WAIT_SECTION_TIMEOUT 9375 //300ms00041 #define INTER_COMMAND_SPACING 31 //1ms00042 #define WAKE_HANDSHAKE_TIMEOUT 9375 //300ms00043 #define STARTUP_TIMEOUT_SINGLE 23438 //750ms00044 //[[ WBBFIXME-measure exactly how long we need during bootup; set to 10 for ]]00045 //[[ plenty of time until we figure out how long bootloader takes ]]00046 #define STARTUP_TIMEOUT_COUNT 10 // count*750 = 7500ms00047 //actual startup timeout time is (single*count) = 7500ms000490005000060 #define SPIP_nSSEL_PORT PORTB00061 #define SPIP_nSSEL_DDR DDRB00062 #define SPIP_nSSEL 000063 #define SPIP_MOSI_PORT PORTB00064 #define SPIP_MOSI_DDR DDRB00065 #define SPIP_MOSI 200066 #define SPIP_MISO_PORT PORTB00067 #define SPIP_MISO_DDR DDRB00068 #define SPIP_MISO 300069 #define SPIP_SCLK_PORT PORTB00070 #define SPIP_SCLK_DDR DDRB00071 #define SPIP_SCLK 100072 #define SPIP_nHOST_INT_PORT PORTD00073 #define SPIP_nHOST_INT_DDR DDRD00074 #define SPIP_nHOST_INT_PIN PIND00075 #define SPIP_nHOST_INT 000076 #define SPIP_nWAKE_PORT PORTB00077 #define SPIP_nWAKE_DDR DDRB00078 #define SPIP_nWAKE 400079 #define SPIP_nRESET_PORT PORTB00080 #define SPIP_nRESET_DDR DDRB00081 #define SPIP_nRESET 500082000830008400102 enum HalBoardLedPins {00103 BOARDLED0 = 0,00104 BOARDLED1 = 1,00105 BOARD_ACTIVITY_LED = BOARDLED0,00106 BOARD_HEARTBEAT_LED = BOARDLED100107 };00108 #define BOARDLED_MASK 0x030010900110 #define LED_DDR DDRC00111 #define LED_PORT PORTC0011200113001140012500126 // Note that BUTTON1 cannot be used to wake the processor, as INT400127 // does not support wakeup on an edge.00128 #define BUTTON0 100129 #define BUTTON0_PORT PORTD00130 #define BUTTON0_DDR DDRD00131 #define BUTTON0_PIN PIND00132 #define BUTTON0_INT INT100133 #define BUTTON0_INT_VECT INT1_vect00134 #define BUTTON0_CONFIG_FALLING_EDGE() \00135 do { \00136 EICRA |= BIT(ISC11); \00137 EICRA &= ~BIT(ISC10); \00138 } while(0)00139 #define BUTTON0_CONFIG_RISING_EDGE() \00140 do { \00141 EICRA |= BIT(ISC11); \00142 EICRA |= BIT(ISC10); \00143 } while(0)0014400145 #define BUTTON1 400146 #define BUTTON1_PORT PORTE00147 #define BUTTON1_DDR DDRE00148 #define BUTTON1_PIN PINE00149 #define BUTTON1_INT INT400150 #define BUTTON1_INT_VECT INT4_vect00151 #define BUTTON1_CONFIG_FALLING_EDGE() \00152 do { \00153 EICRB |= BIT(ISC41); \

EmberZNet 4.7.2 API EM260 120-3020-000-4720

342

00154 EICRB &= ~BIT(ISC40); \00155 } while(0)00156 #define BUTTON1_CONFIG_RISING_EDGE() \00157 do { \00158 EICRB |= BIT(ISC41); \00159 EICRB |= BIT(ISC40); \00160 } while(0)001610016300173 #define TEMP_SENSOR_ADC_CHANNEL ADC_SOURCE_ADC100174 #define TEMP_SENSOR_SCALE_FACTOR 20017500187 #define halInternalInitBoard() \00188 do { \00189 halInternalInitAdc(); \00190 halInternalInitButton(); \00191 halInternalInitLed(); \00192 /* temp sensor */ \00193 DDRC |= BIT(7); \00194 PORTC |= BIT(7); \00195 /* Buzzer */ \00196 DDRB |= 0x80; \00197 PORTB |= 0x80; \00198 /*** Configure SPI Protocol pins ***/ \00199 /*nRESET default input/pullup until used*/ \00200 SPIP_nRESET_DDR &= ~BIT(SPIP_nRESET); \00201 SPIP_nRESET_PORT |= BIT(SPIP_nRESET); \00202 /*Activate nHOST_INT internal pullup*/ \00203 SPIP_nHOST_INT_DDR &= ~BIT(SPIP_nHOST_INT); \00204 SPIP_nHOST_INT_PORT |= BIT(SPIP_nHOST_INT); \00205 /*Falling edge detection on nHOST_INT*/ \00206 EICRA |= BIT(ISC01);EICRA &= ~BIT(ISC00); \00207 SPIP_nWAKE_PORT |= BIT(SPIP_nWAKE); \00208 SPIP_nWAKE_DDR |= BIT(SPIP_nWAKE); \00209 SPIP_nSSEL_PORT |= BIT(SPIP_nSSEL); \00210 SPIP_nSSEL_DDR |= BIT(SPIP_nSSEL); \00211 SPIP_MOSI_PORT |= BIT(SPIP_MOSI); \00212 SPIP_MOSI_DDR |= BIT(SPIP_MOSI); \00213 SPIP_SCLK_PORT |= BIT(SPIP_SCLK); \00214 SPIP_SCLK_DDR |= BIT(SPIP_SCLK); \00215 /* SPI Master, Mode 0 */ \00216 SPCR = BIT(SPE) | BIT(MSTR); \00217 /* Fastest SPI speed = 3.6864Mhz/2 */ \00218 SPSR = BIT(SPI2X); \00219 /*initialize the SPI Protocol*/ \00220 halNcpSerialInit(); \00221 } while(0)0022200223 #define halInternalPowerDownBoard() \00224 do { \00225 halInternalSleepAdc(); \00226 halInternalInitLed(); \00227 /* Disable Buzzer */ \00228 TCCR2 = BIT(WGM21); /* no clock, no timer override */ \00229 TIMSK &= ~(BIT(OCIE2)); /* disable interrupt */ \00230 /* Disable Temp sensor */ \00231 PORTC &= ~BIT(7); \00232 /* Wait for nHOST_INT to go high so that we don’t */ \00233 /* immediately get interrupted and wake the host */ \00234 /* unnecessarily */ \00235 while (((SPIP_nHOST_INT_PIN&BIT(SPIP_nHOST_INT))== 0) \00236 && ((EIFR&BIT(INTF0)) != BIT(INTF0))) {}; \00237 /* Set nHOST_INT to trigger low */ \00238 /* - edge triggers will not wake the Atmega32 */ \00239 EICRA &= ~(BIT(ISC01) | BIT(ISC00)); \00240 EIFR = BIT(INTF0); /*clear interrupt flag */ \00241 EIMSK |= BIT(INT0);/*enable nHOST_INT interrupt for wake */ \00242 } while(0)0024300244 #define halInternalPowerUpBoard() \00245 do { \00246 halInternalInitAdc(); \00247 /* Enable Temp sensor */ \00248 DDRC |= BIT(7); \00249 PORTC |= BIT(7); \00250 EIMSK &= ~BIT(INT0);/* disable nHOST_INT interrupt */ \00251 EIFR = BIT(INTF0); /* clear interrupt flag */ \00252 /* Set nHOST_INT back to trigger on falling edge... */ \00253 EICRA |= BIT(ISC01);EICRA &= ~BIT(ISC00); \00254 halNcpSerialPowerup(); \

EmberZNet 4.7.2 API EM260 120-3020-000-4720

343

00255 } while(0)002560025700258 #endif //__BOARD_H__00259

8.51 ember-configuration-defaults.h File Reference

Macros

• #define EMBER_API_MAJOR_VERSION• #define EMBER_API_MINOR_VERSION• #define EMBER_STACK_PROFILE• #define EMBER_MAX_END_DEVICE_CHILDREN• #define EMBER_SECURITY_LEVEL• #define EMBER_CHILD_TABLE_SIZE• #define EMBER_KEY_TABLE_SIZE• #define EMBER_CERTIFICATE_TABLE_SIZE• #define EMBER_MAX_DEPTH• #define EMBER_MAX_HOPS• #define EMBER_PACKET_BUFFER_COUNT• #define EMBER_MAX_NEIGHBOR_TABLE_SIZE• #define EMBER_NEIGHBOR_TABLE_SIZE• #define EMBER_INDIRECT_TRANSMISSION_TIMEOUT• #define EMBER_MAX_INDIRECT_TRANSMISSION_TIMEOUT• #define EMBER_SEND_MULTICASTS_TO_SLEEPY_ADDRESS• #define EMBER_END_DEVICE_POLL_TIMEOUT• #define EMBER_END_DEVICE_POLL_TIMEOUT_SHIFT• #define EMBER_MOBILE_NODE_POLL_TIMEOUT• #define EMBER_APS_UNICAST_MESSAGE_COUNT• #define EMBER_BINDING_TABLE_SIZE• #define EMBER_ADDRESS_TABLE_SIZE• #define EMBER_RESERVED_MOBILE_CHILD_ENTRIES• #define EMBER_ROUTE_TABLE_SIZE• #define EMBER_DISCOVERY_TABLE_SIZE• #define EMBER_MULTICAST_TABLE_SIZE• #define EMBER_SOURCE_ROUTE_TABLE_SIZE• #define EMBER_DEFAULT_BROADCAST_TABLE_SIZE• #define EMBER_BROADCAST_TABLE_SIZE• #define EMBER_ASSERT_SERIAL_PORT• #define EMBER_MAXIMUM_ALARM_DATA_SIZE• #define EMBER_BROADCAST_ALARM_DATA_SIZE• #define EMBER_UNICAST_ALARM_DATA_SIZE• #define EMBER_FRAGMENT_DELAY_MS• #define EMBER_FRAGMENT_MAX_WINDOW_SIZE• #define EMBER_FRAGMENT_WINDOW_SIZE• #define EMBER_BINDING_TABLE_TOKEN_SIZE• #define EMBER_CHILD_TABLE_TOKEN_SIZE• #define EMBER_KEY_TABLE_TOKEN_SIZE• #define EMBER_REQUEST_KEY_TIMEOUT

EmberZNet 4.7.2 API EM260 120-3020-000-4720

344

• #define EMBER_END_DEVICE_BIND_TIMEOUT• #define EMBER_PAN_ID_CONFLICT_REPORT_THRESHOLD• #define EMBER_TASK_COUNT• #define EMBER_SUPPORTED_NETWORKS


User-configurable stack memory allocation defaults.

Note

Application developers should not modify any portion of this file. Doing so may cause mysteriousbugs. Allocations should be adjusted only by defining the appropriate macros in the application’sCONFIGURATION_HEADER.

See Configuration for documentation.

Definition in file ember-configuration-defaults.h.

8.52 ember-configuration-defaults.h

0000100014 // Todo:00015 // - explain how to use a configuration header00016 // - the documentation of the custom handlers should00017 // go in hal/ember-configuration.c, not here00018 // - the stack profile documentation is out of date0001900047 #ifndef __EMBER_CONFIGURATION_DEFAULTS_H__00048 #define __EMBER_CONFIGURATION_DEFAULTS_H__0004900050 #ifdef CONFIGURATION_HEADER00051 #include CONFIGURATION_HEADER00052 #endif0005300054 #ifndef EMBER_API_MAJOR_VERSION0005500058 #define EMBER_API_MAJOR_VERSION 200059 #endif0006000061 #ifndef EMBER_API_MINOR_VERSION0006200065 #define EMBER_API_MINOR_VERSION 000066 #endif0006700080 #ifndef EMBER_STACK_PROFILE00081 #define EMBER_STACK_PROFILE 000082 #endif0008300084 #if (EMBER_STACK_PROFILE == 2)00085 #define EMBER_MAX_DEPTH 1500086 #define EMBER_SECURITY_LEVEL 500087 #define EMBER_MIN_ROUTE_TABLE_SIZE 1000088 #define EMBER_MIN_DISCOVERY_TABLE_SIZE 400089 #define EMBER_INDIRECT_TRANSMISSION_TIMEOUT 768000090 #define EMBER_SEND_MULTICASTS_TO_SLEEPY_ADDRESS FALSE00091 #endif0009200093 #ifndef EMBER_MAX_END_DEVICE_CHILDREN0009400098 #define EMBER_MAX_END_DEVICE_CHILDREN 600099 #endif0010000101 #ifndef DOXYGEN_SHOULD_SKIP_THIS00102 /* Need to put in a compile time check to make sure that we aren’t specifying00103 * too many child devices. The NCP may or may not support 64 end devices. But00104 * the host code doesn’t matter.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

345

00105 */00106 #if defined(HAL_HAS_INT64) || defined(EZSP_HOST)00107 #if EMBER_MAX_END_DEVICE_CHILDREN > 6400108 #error "EMBER_MAX_END_DEVICE_CHILDREN can not exceed 64."00109 #endif00110 #else00111 #if EMBER_MAX_END_DEVICE_CHILDREN > 3200112 #error "EMBER_MAX_END_DEVICE_CHILDREN can not exceed 32."00113 #endif00114 #endif0011500116 #endif // DOXYGEN_SHOULD_SKIP_THIS0011700118 #ifndef EMBER_SECURITY_LEVEL0011900123 #define EMBER_SECURITY_LEVEL 500124 #endif0012500126 #if ! (EMBER_SECURITY_LEVEL == 0 \00127 || EMBER_SECURITY_LEVEL == 5)00128 #error "Unsupported security level"00129 #endif0013000131 #ifdef EMBER_CHILD_TABLE_SIZE00132 #if (EMBER_MAX_END_DEVICE_CHILDREN < EMBER_CHILD_TABLE_SIZE)00133 #undef EMBER_CHILD_TABLE_SIZE00134 #endif00135 #endif0013600137 #ifndef EMBER_CHILD_TABLE_SIZE0013800152 #define EMBER_CHILD_TABLE_SIZE EMBER_MAX_END_DEVICE_CHILDREN00153 #endif0015400168 #ifndef EMBER_KEY_TABLE_SIZE00169 #define EMBER_KEY_TABLE_SIZE 000170 #endif0017100181 #ifndef EMBER_CERTIFICATE_TABLE_SIZE00182 #define EMBER_CERTIFICATE_TABLE_SIZE 000183 #else00184 #if EMBER_CERTIFICATE_TABLE_SIZE > 100185 #error "EMBER_CERTIFICATE_TABLE_SIZE > 1 is not supported!"00186 #endif00187 #endif0018800194 #ifndef EMBER_MAX_DEPTH00195 #define EMBER_MAX_DEPTH 1500196 #elif (EMBER_MAX_DEPTH > 15)00197 // Depth is a 4-bit field00198 #error "EMBER_MAX_DEPTH cannot be greater than 15"00199 #endif0020000207 #ifndef EMBER_MAX_HOPS00208 #define EMBER_MAX_HOPS (2 * EMBER_MAX_DEPTH)00209 #endif0021000217 #ifndef EMBER_PACKET_BUFFER_COUNT00218 #define EMBER_PACKET_BUFFER_COUNT 2400219 #endif0022000232 #define EMBER_MAX_NEIGHBOR_TABLE_SIZE 1600233 #ifndef EMBER_NEIGHBOR_TABLE_SIZE00234 #define EMBER_NEIGHBOR_TABLE_SIZE 1600235 #endif0023600243 #ifndef EMBER_INDIRECT_TRANSMISSION_TIMEOUT00244 #define EMBER_INDIRECT_TRANSMISSION_TIMEOUT 300000245 #endif00246 #define EMBER_MAX_INDIRECT_TRANSMISSION_TIMEOUT 3000000247 #if (EMBER_INDIRECT_TRANSMISSION_TIMEOUT

\00248 > EMBER_MAX_INDIRECT_TRANSMISSION_TIMEOUT)00249 #error "Indirect transmission timeout too large."00250 #endif0025100258 #ifndef EMBER_SEND_MULTICASTS_TO_SLEEPY_ADDRESS00259 #define EMBER_SEND_MULTICASTS_TO_SLEEPY_ADDRESS FALSE00260 #endif00261

EmberZNet 4.7.2 API EM260 120-3020-000-4720

346

0026200277 #ifndef EMBER_END_DEVICE_POLL_TIMEOUT00278 #define EMBER_END_DEVICE_POLL_TIMEOUT 500279 #endif0028000288 #ifndef EMBER_END_DEVICE_POLL_TIMEOUT_SHIFT00289 #define EMBER_END_DEVICE_POLL_TIMEOUT_SHIFT 600290 #endif0029100298 #ifndef EMBER_MOBILE_NODE_POLL_TIMEOUT00299 #define EMBER_MOBILE_NODE_POLL_TIMEOUT 2000300 #endif0030100314 #ifndef EMBER_APS_UNICAST_MESSAGE_COUNT00315 #define EMBER_APS_UNICAST_MESSAGE_COUNT 1000316 #endif0031700320 #ifndef EMBER_BINDING_TABLE_SIZE00321 #define EMBER_BINDING_TABLE_SIZE 000322 #endif0032300328 #ifndef EMBER_ADDRESS_TABLE_SIZE00329 #define EMBER_ADDRESS_TABLE_SIZE 800330 #endif0033100338 #ifndef EMBER_RESERVED_MOBILE_CHILD_ENTRIES00339 #define EMBER_RESERVED_MOBILE_CHILD_ENTRIES 000340 #endif0034100348 #ifndef EMBER_ROUTE_TABLE_SIZE00349 #ifdef EMBER_MIN_ROUTE_TABLE_SIZE00350 #define EMBER_ROUTE_TABLE_SIZE EMBER_MIN_ROUTE_TABLE_SIZE00351 #else00352 #define EMBER_ROUTE_TABLE_SIZE 1600353 #endif00354 #elif defined(EMBER_MIN_ROUTE_TABLE_SIZE) \00355 && EMBER_ROUTE_TABLE_SIZE < EMBER_MIN_ROUTE_TABLE_SIZE00356 #error "EMBER_ROUTE_TABLE_SIZE is less than required by stack profile."00357 #endif0035800364 #ifndef EMBER_DISCOVERY_TABLE_SIZE00365 #ifdef EMBER_MIN_DISCOVERY_TABLE_SIZE00366 #define EMBER_DISCOVERY_TABLE_SIZE EMBER_MIN_DISCOVERY_TABLE_SIZE00367 #else00368 #define EMBER_DISCOVERY_TABLE_SIZE 800369 #endif00370 #elif defined(EMBER_MIN_DISCOVERY_TABLE_SIZE) \00371 && EMBER_DISCOVERY_TABLE_SIZE < EMBER_MIN_DISCOVERY_TABLE_SIZE00372 #error "EMBER_DISCOVERY_TABLE_SIZE is less than required by stack profile."00373 #endif0037400380 #ifndef EMBER_MULTICAST_TABLE_SIZE00381 #define EMBER_MULTICAST_TABLE_SIZE 800382 #endif0038300390 #ifndef EMBER_SOURCE_ROUTE_TABLE_SIZE00391 #define EMBER_SOURCE_ROUTE_TABLE_SIZE 3200392 #endif0039300405 #if !defined(EMBER_ZLL_STACK) && (EMBER_STACK_PROFILE == 2) &&

!defined(EMBER_TEST)00406 #if defined(EMBER_BROADCAST_TABLE_SIZE)00407 #error "Cannot override broadcast table size unless (EMBER_STACK_PROFILE !=

2) or EMBER_ZLL_STACK"00408 #endif00409 #endif0041000411 #define EMBER_DEFAULT_BROADCAST_TABLE_SIZE 150041200413 #ifndef EMBER_BROADCAST_TABLE_SIZE00414 #define EMBER_BROADCAST_TABLE_SIZE EMBER_DEFAULT_BROADCAST_TABLE_SIZE00415 #elif EMBER_BROADCAST_TABLE_SIZE < EMBER_DEFAULT_BROADCAST_TABLE_SIZE00416 #error "EMBER_BROADCAST_TABLE_SIZE is less than the minimum value of 15."00417 #elif 254 < EMBER_BROADCAST_TABLE_SIZE00418 #error "EMBER_BROADCAST_TABLE_SIZE is larger than the maximum value of 254."00419 #endif0042000430 #if !defined(EMBER_ASSERT_OUTPUT_DISABLED) \00431 && !defined(EMBER_ASSERT_SERIAL_PORT)00432 #define EMBER_ASSERT_SERIAL_PORT 1

EmberZNet 4.7.2 API EM260 120-3020-000-4720

347

00433 #endif0043400448 #define EMBER_MAXIMUM_ALARM_DATA_SIZE 160044900467 #ifndef EMBER_BROADCAST_ALARM_DATA_SIZE00468 #define EMBER_BROADCAST_ALARM_DATA_SIZE 000469 #elif EMBER_MAXIMUM_ALARM_DATA_SIZE < EMBER_BROADCAST_ALARM_DATA_SIZE00470 #error "EMBER_BROADCAST_ALARM_DATA_SIZE is too large."00471 #endif0047200481 #ifndef EMBER_UNICAST_ALARM_DATA_SIZE00482 #define EMBER_UNICAST_ALARM_DATA_SIZE 000483 #elif EMBER_MAXIMUM_ALARM_DATA_SIZE < EMBER_UNICAST_ALARM_DATA_SIZE00484 #error "EMBER_UNICAST_ALARM_DATA_SIZE is too large."00485 #endif0048600490 #ifndef EMBER_FRAGMENT_DELAY_MS00491 #define EMBER_FRAGMENT_DELAY_MS 000492 #endif0049300497 #define EMBER_FRAGMENT_MAX_WINDOW_SIZE 80049800503 #ifndef EMBER_FRAGMENT_WINDOW_SIZE00504 #define EMBER_FRAGMENT_WINDOW_SIZE 100505 #elif EMBER_FRAGMENT_MAX_WINDOW_SIZE < EMBER_FRAGMENT_WINDOW_SIZE00506 #error "EMBER_FRAGMENT_WINDOW_SIZE is too large."00507 #endif0050800509 #ifndef EMBER_BINDING_TABLE_TOKEN_SIZE00510 #define EMBER_BINDING_TABLE_TOKEN_SIZE EMBER_BINDING_TABLE_SIZE00511 #endif00512 #ifndef EMBER_CHILD_TABLE_TOKEN_SIZE00513 #define EMBER_CHILD_TABLE_TOKEN_SIZE EMBER_CHILD_TABLE_SIZE00514 #endif00515 #ifndef EMBER_KEY_TABLE_TOKEN_SIZE00516 #define EMBER_KEY_TABLE_TOKEN_SIZE EMBER_KEY_TABLE_SIZE00517 #endif0051800531 #ifndef EMBER_REQUEST_KEY_TIMEOUT00532 #define EMBER_REQUEST_KEY_TIMEOUT 000533 #elif EMBER_REQUEST_KEY_TIMEOUT > 1000534 #error "EMBER_REQUEST_KEY_TIMEOUT is too large."00535 #endif0053600540 #ifndef EMBER_END_DEVICE_BIND_TIMEOUT00541 #define EMBER_END_DEVICE_BIND_TIMEOUT 6000542 #endif0054300552 #ifndef EMBER_PAN_ID_CONFLICT_REPORT_THRESHOLD00553 #define EMBER_PAN_ID_CONFLICT_REPORT_THRESHOLD 100554 #endif0055500561 #ifndef EMBER_TASK_COUNT00562 #define EMBER_TASK_COUNT (3)00563 #endif0056400567 #ifndef EMBER_SUPPORTED_NETWORKS00568 #ifdef EMBER_TEST00569 #define EMBER_SUPPORTED_NETWORKS 200570 #else00571 #define EMBER_SUPPORTED_NETWORKS 100572 #endif00573 #endif005740057500576 #if defined(EMBER_ZLL_STACK)0057700578 #ifndef EMBER_ZLL_GROUP_ADDRESSES0057900581 #define EMBER_ZLL_GROUP_ADDRESSES 100582 #endif0058300584 #ifndef EMBER_ZLL_RSSI_THRESHOLD0058500587 #define EMBER_ZLL_RSSI_THRESHOLD -12800588 #endif0058900590 #endif // EMBER_ZLL_STACK0059100592

EmberZNet 4.7.2 API EM260 120-3020-000-4720

348

00597 #endif //__EMBER_CONFIGURATION_DEFAULTS_H__

8.53 ember-debug.h File Reference

Macros

• #define NO_DEBUG• #define BASIC_DEBUG• #define FULL_DEBUG• #define emberDebugInit(port)

Functions

• void emberDebugAssert (PGM_P filename, int linenumber)• void emberDebugMemoryDump (int8u ∗start, int8u ∗end)• void emberDebugBinaryPrintf (PGM_P formatString,...)• void emDebugSendVuartMessage (int8u ∗buff, int8u len)• void emberDebugError (EmberStatus code)• boolean emberDebugReportOff (void)• void emberDebugReportRestore (boolean state)• void emberDebugPrintf (PGM_P formatString,...)


See Debugging Utilities for documentation.

Definition in file ember-debug.h.

8.54 ember-debug.h

0000100008 #ifndef __EMBER_DEBUG_H__00009 #define __EMBER_DEBUG_H__0001000019 // Define the values for DEBUG_LEVEL00020 #define NO_DEBUG 000021 #define BASIC_DEBUG 100022 #define FULL_DEBUG 20002300030 #define emberDebugInit(port) do {} while(FALSE)0003100032 #if (DEBUG_LEVEL >= BASIC_DEBUG) || defined(DOXYGEN_SHOULD_SKIP_THIS)0003300039 void emberDebugAssert(PGM_P filename, int linenumber);000400004100049 void emberDebugMemoryDump(int8u *start, int8u *

end);0005000077 void emberDebugBinaryPrintf(PGM_P formatString, ...)

;0007800086 void emDebugSendVuartMessage(int8u *buff, int8u

len);0008700088 #else // (DEBUG_LEVEL >= BASIC_DEBUG) || defined(DOXYGEN_SHOULD_SKIP_THIS)00089 #define emberDebugAssert(filename, linenumber) do {} while(FALSE)00090 #define emberDebugMemoryDump(start, end) do {} while(FALSE)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

349

00091 #define emberDebugBinaryPrintf(formatstring, ...) do {} while(FALSE)00092 #define emDebugSendVuartMessage(buff, len) do {} while(FALSE)00093 #endif // (DEBUG_LEVEL >= BASIC_DEBUG) || defined(DOXYGEN_SHOULD_SKIP_THIS)0009400095 #if (DEBUG_LEVEL == FULL_DEBUG) || defined(DOXYGEN_SHOULD_SKIP_THIS)0009600100 void emberDebugError(EmberStatus code);0010100106 boolean emberDebugReportOff(void);0010700113 void emberDebugReportRestore(boolean state);0011400115 // Format: Same as emberSerialPrintf00116 // emberDebugPrintf("format string"[, parameters ...])00132 void emberDebugPrintf(PGM_P formatString, ...);0013300134 #else // (DEBUG_LEVEL == FULL_DEBUG) || defined(DOXYGEN_SHOULD_SKIP_THIS)00135 #define emberDebugError(code) do {} while(FALSE)00136 // Note the following doesn’t have a do{}while(FALSE)00137 // because it has a return value00138 #define emberDebugReportOff() (FALSE)00139 #define emberDebugReportRestore(state) do {} while(FALSE)00140 #define emberDebugPrintf(...) do {} while(FALSE)00141 #endif // (DEBUG_LEVEL == FULL_DEBUG) || defined(DOXYGEN_SHOULD_SKIP_THIS)0014200146 #endif // __EMBER_DEBUG_H__00147

8.55 ember-types.h File Reference

Data Structures

• struct EmberVersionVersion struct containing all version information.

• struct EmberZigbeeNetworkDefines a ZigBee network and the associated parameters.

• struct EmberNetworkInitStructDefines the network initialization configuration that should be used when ::emberNetworkInitExtended() iscalled by the application.

• struct EmberNetworkParametersHolds network parameters.

• struct EmberApsFrameAn in-memory representation of a ZigBee APS frame of an incoming or outgoing message.

• struct EmberBindingTableEntryDefines an entry in the binding table.

• struct EmberNeighborTableEntryDefines an entry in the neighbor table.

• struct EmberRouteTableEntryDefines an entry in the route table.

• struct EmberMulticastTableEntryDefines an entry in the multicast table.

• struct EmberEventControlControl structure for events.

• struct EmberTaskControlControl structure for tasks.

• struct EmberKeyDataThis data structure contains the key data that is passed into various other functions.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

350

• struct EmberCertificateDataThis data structure contains the certificate data that is used for Certificate Based Key Exchange (CBKE).

• struct EmberPublicKeyDataThis data structure contains the public key data that is used for Certificate Based Key Exchange (CBKE).

• struct EmberPrivateKeyDataThis data structure contains the private key data that is used for Certificate Based Key Exchange (CBKE).

• struct EmberSmacDataThis data structure contains the Shared Message Authentication Code (SMAC) data that is used for Certifi-cate Based Key Exchange (CBKE).

• struct EmberSignatureDataThis data structure contains a DSA signature. It is the bit concatenation of the ’r’ and ’s’ components of thesignature.

• struct EmberMessageDigestThis data structure contains an AES-MMO Hash (the message digest).

• struct EmberAesMmoHashContextThis data structure contains the context data when calculating an AES MMO hash (message digest).

• struct EmberInitialSecurityStateThis describes the Initial Security features and requirements that will be used when forming or joining thenetwork.

• struct EmberCurrentSecurityStateThis describes the security features used by the stack for a joined device.

• struct EmberKeyStructThis describes a one of several different types of keys and its associated data.

• struct EmberMfgSecurityStructThis structure is used to get/set the security config that is stored in manufacturing tokens.

• struct EmberMacFilterMatchStructThis structure indicates a matching raw MAC message has been received by the application configuredMAC filters.

Macros

• #define EMBER_JOIN_DECISION_STRINGS• #define EMBER_DEVICE_UPDATE_STRINGS• #define emberInitializeNetworkParameters(parameters)• #define EMBER_COUNTER_STRINGS• #define EMBER_STANDARD_SECURITY_MODE• #define EMBER_TRUST_CENTER_NODE_ID• #define EMBER_NO_TRUST_CENTER_MODE• #define EMBER_GLOBAL_LINK_KEY• #define EMBER_MFG_SECURITY_CONFIG_MAGIC_NUMBER• #define EMBER_MAC_FILTER_MATCH_ENABLED_MASK• #define EMBER_MAC_FILTER_MATCH_ON_PAN_DEST_MASK• #define EMBER_MAC_FILTER_MATCH_ON_PAN_SOURCE_MASK• #define EMBER_MAC_FILTER_MATCH_ON_DEST_MASK• #define EMBER_MAC_FILTER_MATCH_ON_SOURCE_MASK• #define EMBER_MAC_FILTER_MATCH_ENABLED• #define EMBER_MAC_FILTER_MATCH_DISABLED• #define EMBER_MAC_FILTER_MATCH_ON_PAN_DEST_NONE

EmberZNet 4.7.2 API EM260 120-3020-000-4720

351

• #define EMBER_MAC_FILTER_MATCH_ON_PAN_DEST_LOCAL• #define EMBER_MAC_FILTER_MATCH_ON_PAN_DEST_BROADCAST• #define EMBER_MAC_FILTER_MATCH_ON_PAN_SOURCE_NONE• #define EMBER_MAC_FILTER_MATCH_ON_PAN_SOURCE_NON_LOCAL• #define EMBER_MAC_FILTER_MATCH_ON_PAN_SOURCE_LOCAL• #define EMBER_MAC_FILTER_MATCH_ON_DEST_BROADCAST_SHORT• #define EMBER_MAC_FILTER_MATCH_ON_DEST_UNICAST_SHORT• #define EMBER_MAC_FILTER_MATCH_ON_DEST_UNICAST_LONG• #define EMBER_MAC_FILTER_MATCH_ON_SOURCE_LONG• #define EMBER_MAC_FILTER_MATCH_ON_SOURCE_SHORT• #define EMBER_MAC_FILTER_MATCH_END

Typedefs

• typedef int8u EmberTaskId• struct {

EmberEventControl ∗ controlvoid(∗ handler )(void)

} EmberEventData

• typedef int16u EmberMacFilterMatchData• typedef int8u EmberLibraryStatus

Enumerations

• enum EmberNodeType {EMBER_UNKNOWN_DEVICE, EMBER_COORDINATOR, EMBER_ROUTER, EMBER_EN-D_DEVICE,EMBER_SLEEPY_END_DEVICE, EMBER_MOBILE_END_DEVICE }

• enum EmberNetworkInitBitmask { EMBER_NETWORK_INIT_NO_OPTIONS, EMBER_NETW-ORK_INIT_PARENT_INFO_IN_TOKEN }

• enum EmberApsOption {EMBER_APS_OPTION_NONE, EMBER_APS_OPTION_DSA_SIGN, EMBER_APS_OPTION-_ENCRYPTION, EMBER_APS_OPTION_RETRY,EMBER_APS_OPTION_ENABLE_ROUTE_DISCOVERY, EMBER_APS_OPTION_FORCE_R-OUTE_DISCOVERY, EMBER_APS_OPTION_SOURCE_EUI64, EMBER_APS_OPTION_DE-STINATION_EUI64,EMBER_APS_OPTION_ENABLE_ADDRESS_DISCOVERY, EMBER_APS_OPTION_POLL_-RESPONSE, EMBER_APS_OPTION_ZDO_RESPONSE_REQUIRED, EMBER_APS_OPTION-_FRAGMENT }

• enum EmberIncomingMessageType {EMBER_INCOMING_UNICAST, EMBER_INCOMING_UNICAST_REPLY, EMBER_INCOM-ING_MULTICAST, EMBER_INCOMING_MULTICAST_LOOPBACK,EMBER_INCOMING_BROADCAST, EMBER_INCOMING_BROADCAST_LOOPBACK }

• enum EmberOutgoingMessageType {EMBER_OUTGOING_DIRECT, EMBER_OUTGOING_VIA_ADDRESS_TABLE, EMBER_O-UTGOING_VIA_BINDING, EMBER_OUTGOING_MULTICAST,EMBER_OUTGOING_BROADCAST }

• enum EmberNetworkStatus {EMBER_NO_NETWORK, EMBER_JOINING_NETWORK, EMBER_JOINED_NETWORK, E-MBER_JOINED_NETWORK_NO_PARENT,EMBER_LEAVING_NETWORK }

EmberZNet 4.7.2 API EM260 120-3020-000-4720

352

• enum EmberNetworkScanType { EMBER_ENERGY_SCAN, EMBER_ACTIVE_SCAN }• enum EmberBindingType { EMBER_UNUSED_BINDING, EMBER_UNICAST_BINDING, EM-

BER_MANY_TO_ONE_BINDING, EMBER_MULTICAST_BINDING }• enum EmberJoinDecision { EMBER_USE_PRECONFIGURED_KEY, EMBER_SEND_KEY_IN-

_THE_CLEAR, EMBER_DENY_JOIN, EMBER_NO_ACTION }• enum EmberDeviceUpdate {

EMBER_STANDARD_SECURITY_SECURED_REJOIN, EMBER_STANDARD_SECURITY_-UNSECURED_JOIN, EMBER_DEVICE_LEFT, EMBER_STANDARD_SECURITY_UNSECU-RED_REJOIN,EMBER_HIGH_SECURITY_SECURED_REJOIN, EMBER_HIGH_SECURITY_UNSECURED-_JOIN, EMBER_HIGH_SECURITY_UNSECURED_REJOIN, EMBER_REJOIN_REASON_NO-NE,EMBER_REJOIN_DUE_TO_NWK_KEY_UPDATE, EMBER_REJOIN_DUE_TO_LEAVE_ME-SSAGE, EMBER_REJOIN_DUE_TO_NO_PARENT, EMBER_REJOIN_DUE_TO_ZLL_TOUC-HLINK,EMBER_REJOIN_DUE_TO_APP_EVENT_5, EMBER_REJOIN_DUE_TO_APP_EVENT_4, E-MBER_REJOIN_DUE_TO_APP_EVENT_3, EMBER_REJOIN_DUE_TO_APP_EVENT_2,EMBER_REJOIN_DUE_TO_APP_EVENT_1 }

• enum EmberDeviceUpdate {EMBER_STANDARD_SECURITY_SECURED_REJOIN, EMBER_STANDARD_SECURITY_-UNSECURED_JOIN, EMBER_DEVICE_LEFT, EMBER_STANDARD_SECURITY_UNSECU-RED_REJOIN,EMBER_HIGH_SECURITY_SECURED_REJOIN, EMBER_HIGH_SECURITY_UNSECURED-_JOIN, EMBER_HIGH_SECURITY_UNSECURED_REJOIN, EMBER_REJOIN_REASON_NO-NE,EMBER_REJOIN_DUE_TO_NWK_KEY_UPDATE, EMBER_REJOIN_DUE_TO_LEAVE_ME-SSAGE, EMBER_REJOIN_DUE_TO_NO_PARENT, EMBER_REJOIN_DUE_TO_ZLL_TOUC-HLINK,EMBER_REJOIN_DUE_TO_APP_EVENT_5, EMBER_REJOIN_DUE_TO_APP_EVENT_4, E-MBER_REJOIN_DUE_TO_APP_EVENT_3, EMBER_REJOIN_DUE_TO_APP_EVENT_2,EMBER_REJOIN_DUE_TO_APP_EVENT_1 }

• enum EmberClusterListId { EMBER_INPUT_CLUSTER_LIST, EMBER_OUTPUT_CLUSTER_-LIST }

• enum EmberEventUnits {EMBER_EVENT_INACTIVE, EMBER_EVENT_MS_TIME, EMBER_EVENT_QS_TIME, EM-BER_EVENT_MINUTE_TIME,EMBER_EVENT_ZERO_DELAY }

• enum EmberJoinMethod { EMBER_USE_MAC_ASSOCIATION, EMBER_USE_NWK_REJOIN,EMBER_USE_NWK_REJOIN_HAVE_NWK_KEY, EMBER_USE_NWK_COMMISSIONING }

• enum EmberCounterType {EMBER_COUNTER_MAC_RX_BROADCAST, EMBER_COUNTER_MAC_TX_BROADCAS-T, EMBER_COUNTER_MAC_RX_UNICAST, EMBER_COUNTER_MAC_TX_UNICAST_SU-CCESS,EMBER_COUNTER_MAC_TX_UNICAST_RETRY, EMBER_COUNTER_MAC_TX_UNICAS-T_FAILED, EMBER_COUNTER_APS_DATA_RX_BROADCAST, EMBER_COUNTER_APS-_DATA_TX_BROADCAST,EMBER_COUNTER_APS_DATA_RX_UNICAST, EMBER_COUNTER_APS_DATA_TX_UN-ICAST_SUCCESS, EMBER_COUNTER_APS_DATA_TX_UNICAST_RETRY, EMBER_COU-NTER_APS_DATA_TX_UNICAST_FAILED,EMBER_COUNTER_ROUTE_DISCOVERY_INITIATED, EMBER_COUNTER_NEIGHBOR_-ADDED, EMBER_COUNTER_NEIGHBOR_REMOVED, EMBER_COUNTER_NEIGHBOR_S-TALE,EMBER_COUNTER_JOIN_INDICATION, EMBER_COUNTER_CHILD_REMOVED, EMBER-

EmberZNet 4.7.2 API EM260 120-3020-000-4720

353

_COUNTER_ASH_OVERFLOW_ERROR, EMBER_COUNTER_ASH_FRAMING_ERROR,EMBER_COUNTER_ASH_OVERRUN_ERROR, EMBER_COUNTER_NWK_FRAME_COUN-TER_FAILURE, EMBER_COUNTER_APS_FRAME_COUNTER_FAILURE, EMBER_COUN-TER_ASH_XOFF,EMBER_COUNTER_APS_LINK_KEY_NOT_AUTHORIZED, EMBER_COUNTER_NWK_DE-CRYPTION_FAILURE, EMBER_COUNTER_APS_DECRYPTION_FAILURE, EMBER_COU-NTER_ALLOCATE_PACKET_BUFFER_FAILURE,EMBER_COUNTER_RELAYED_UNICAST, EMBER_COUNTER_PHY_TO_MAC_QUEUE_L-IMIT_REACHED, EMBER_COUNTER_PACKET_VALIDATE_LIBRARY_DROPPED_COUN-T, EMBER_COUNTER_TYPE_COUNT }

• enum EmberInitialSecurityBitmask {EMBER_DISTRIBUTED_TRUST_CENTER_MODE, EMBER_TRUST_CENTER_GLOBAL_L-INK_KEY, EMBER_PRECONFIGURED_NETWORK_KEY_MODE, EMBER_HAVE_TRUST-_CENTER_EUI64,EMBER_TRUST_CENTER_USES_HASHED_LINK_KEY, EMBER_HAVE_PRECONFIGURE-D_KEY, EMBER_HAVE_NETWORK_KEY, EMBER_GET_LINK_KEY_WHEN_JOINING,EMBER_REQUIRE_ENCRYPTED_KEY, EMBER_NO_FRAME_COUNTER_RESET, EMBER-_GET_PRECONFIGURED_KEY_FROM_INSTALL_CODE }

• enum EmberExtendedSecurityBitmask { EMBER_JOINER_GLOBAL_LINK_KEY, EMBER_N-WK_LEAVE_REQUEST_NOT_ALLOWED }

• enum EmberCurrentSecurityBitmask {EMBER_STANDARD_SECURITY_MODE_, EMBER_DISTRIBUTED_TRUST_CENTER_MO-DE_, EMBER_TRUST_CENTER_GLOBAL_LINK_KEY_, EMBER_HAVE_TRUST_CENTER-_LINK_KEY,EMBER_TRUST_CENTER_USES_HASHED_LINK_KEY_ }

• enum EmberKeyStructBitmask {EMBER_KEY_HAS_SEQUENCE_NUMBER, EMBER_KEY_HAS_OUTGOING_FRAME_CO-UNTER, EMBER_KEY_HAS_INCOMING_FRAME_COUNTER, EMBER_KEY_HAS_PARTN-ER_EUI64,EMBER_KEY_IS_AUTHORIZED, EMBER_KEY_PARTNER_IS_SLEEPY }

• enum EmberKeyType {EMBER_TRUST_CENTER_LINK_KEY, EMBER_TRUST_CENTER_MASTER_KEY, EMBE-R_CURRENT_NETWORK_KEY, EMBER_NEXT_NETWORK_KEY,EMBER_APPLICATION_LINK_KEY, EMBER_APPLICATION_MASTER_KEY }

• enum EmberKeyStatus {EMBER_APP_LINK_KEY_ESTABLISHED, EMBER_APP_MASTER_KEY_ESTABLISHED, E-MBER_TRUST_CENTER_LINK_KEY_ESTABLISHED, EMBER_KEY_ESTABLISHMENT_T-IMEOUT,EMBER_KEY_TABLE_FULL, EMBER_TC_RESPONDED_TO_KEY_REQUEST, EMBER_T-C_APP_KEY_SENT_TO_REQUESTER, EMBER_TC_RESPONSE_TO_KEY_REQUEST_FAIL-ED,EMBER_TC_REQUEST_KEY_TYPE_NOT_SUPPORTED, EMBER_TC_NO_LINK_KEY_FO-R_REQUESTER, EMBER_TC_REQUESTER_EUI64_UNKNOWN, EMBER_TC_RECEIVED_-FIRST_APP_KEY_REQUEST,EMBER_TC_TIMEOUT_WAITING_FOR_SECOND_APP_KEY_REQUEST, EMBER_TC_NO-N_MATCHING_APP_KEY_REQUEST_RECEIVED, EMBER_TC_FAILED_TO_SEND_APP_-KEYS, EMBER_TC_FAILED_TO_STORE_APP_KEY_REQUEST,EMBER_TC_REJECTED_APP_KEY_REQUEST }

• enum EmberLinkKeyRequestPolicy { EMBER_DENY_KEY_REQUESTS, EMBER_ALLOW_K-EY_REQUESTS }

• enum EmberKeySettings { EMBER_KEY_PERMISSIONS_NONE, EMBER_KEY_PERMISSIO-NS_READING_ALLOWED, EMBER_KEY_PERMISSIONS_HASHING_ALLOWED }

EmberZNet 4.7.2 API EM260 120-3020-000-4720

354

• enum EmberMacPassthroughType {EMBER_MAC_PASSTHROUGH_NONE, EMBER_MAC_PASSTHROUGH_SE_INTERPAN, E-MBER_MAC_PASSTHROUGH_EMBERNET, EMBER_MAC_PASSTHROUGH_EMBERNET-_SOURCE,EMBER_MAC_PASSTHROUGH_APPLICATION, EMBER_MAC_PASSTHROUGH_CUSTOM}

Functions

• int8u ∗ emberKeyContents (EmberKeyData ∗key)• int8u ∗ emberCertificateContents (EmberCertificateData ∗cert)• int8u ∗ emberPublicKeyContents (EmberPublicKeyData ∗key)• int8u ∗ emberPrivateKeyContents (EmberPrivateKeyData ∗key)• int8u ∗ emberSmacContents (EmberSmacData ∗key)• int8u ∗ emberSignatureContents (EmberSignatureData ∗sig)

Miscellaneous Ember Types

• #define EUI64_SIZE• #define EXTENDED_PAN_ID_SIZE• #define EMBER_ENCRYPTION_KEY_SIZE• #define EMBER_CERTIFICATE_SIZE• #define EMBER_PUBLIC_KEY_SIZE• #define EMBER_PRIVATE_KEY_SIZE• #define EMBER_SMAC_SIZE• #define EMBER_SIGNATURE_SIZE• #define EMBER_AES_HASH_BLOCK_SIZE• #define __EMBERSTATUS_TYPE__• #define EMBER_MAX_802_15_4_CHANNEL_NUMBER• #define EMBER_MIN_802_15_4_CHANNEL_NUMBER• #define EMBER_NUM_802_15_4_CHANNELS• #define EMBER_ALL_802_15_4_CHANNELS_MASK• #define EMBER_ZIGBEE_COORDINATOR_ADDRESS• #define EMBER_NULL_NODE_ID• #define EMBER_NULL_BINDING• #define EMBER_TABLE_ENTRY_UNUSED_NODE_ID• #define EMBER_MULTICAST_NODE_ID• #define EMBER_UNKNOWN_NODE_ID• #define EMBER_DISCOVERY_ACTIVE_NODE_ID• #define EMBER_NULL_ADDRESS_TABLE_INDEX• #define EMBER_ZDO_ENDPOINT• #define EMBER_BROADCAST_ENDPOINT• #define EMBER_ZDO_PROFILE_ID• #define EMBER_WILDCARD_PROFILE_ID• #define EMBER_MAXIMUM_STANDARD_PROFILE_ID• #define EMBER_BROADCAST_TABLE_TIMEOUT_QS• enum EmberVersionType { EMBER_VERSION_TYPE_PRE_RELEASE, EMBER_VERSION_T-

YPE_GA }• enum EmberLeaveRequestFlags { EMBER_ZIGBEE_LEAVE_AND_REJOIN, EMBER_ZIGBE-

E_LEAVE_AND_REMOVE_CHILDREN }

EmberZNet 4.7.2 API EM260 120-3020-000-4720

355

• enum EmberLeaveReason {EMBER_LEAVE_REASON_NONE, EMBER_LEAVE_DUE_TO_NWK_LEAVE_MESSAGE, E-MBER_LEAVE_DUE_TO_APS_REMOVE_MESSAGE, EMBER_LEAVE_DUE_TO_ZDO_LE-AVE_MESSAGE,EMBER_LEAVE_DUE_TO_ZLL_TOUCHLINK, EMBER_LEAVE_DUE_TO_APP_EVENT_1 }

• typedef int8u EmberStatus• typedef int8u EmberEUI64 [EUI64_SIZE]• typedef int8u EmberMessageBuffer• typedef int16u EmberNodeId• typedef int16u EmberMulticastId• typedef int16u EmberPanId• const EmberVersion emberVersion

ZigBee Broadcast Addresses

ZigBee specifies three different broadcast addresses that reach different collections of nodes. Broadcastsare normally sent only to routers. Broadcasts can also be forwarded to end devices, either all of them oronly those that do not sleep. Broadcasting to end devices is both significantly more resource-intensive andsignificantly less reliable than broadcasting to routers.

• #define EMBER_BROADCAST_ADDRESS• #define EMBER_RX_ON_WHEN_IDLE_BROADCAST_ADDRESS• #define EMBER_SLEEPY_BROADCAST_ADDRESS

Ember Concentrator Types

• #define EMBER_LOW_RAM_CONCENTRATOR• #define EMBER_HIGH_RAM_CONCENTRATOR

txPowerModes for emberSetTxPowerMode and mfglibSetPower

• #define EMBER_TX_POWER_MODE_DEFAULT• #define EMBER_TX_POWER_MODE_BOOST• #define EMBER_TX_POWER_MODE_ALTERNATE• #define EMBER_TX_POWER_MODE_BOOST_AND_ALTERNATE

Alarm Message and Counters Request Definitions

• #define EMBER_PRIVATE_PROFILE_ID• #define EMBER_BROADCAST_ALARM_CLUSTER• #define EMBER_UNICAST_ALARM_CLUSTER• #define EMBER_CACHED_UNICAST_ALARM_CLUSTER• #define EMBER_REPORT_COUNTERS_REQUEST• #define EMBER_REPORT_COUNTERS_RESPONSE• #define EMBER_REPORT_AND_CLEAR_COUNTERS_REQUEST• #define EMBER_REPORT_AND_CLEAR_COUNTERS_RESPONSE• #define EMBER_OTA_CERTIFICATE_UPGRADE_CLUSTER

EmberZNet 4.7.2 API EM260 120-3020-000-4720

356

ZDO response status.

Most responses to ZDO commands contain a status byte. The meaning of this byte is defined by the ZigBeeDevice Profile.

• enum EmberZdoStatus {EMBER_ZDP_SUCCESS, EMBER_ZDP_INVALID_REQUEST_TYPE, EMBER_ZDP_DEVIC-E_NOT_FOUND, EMBER_ZDP_INVALID_ENDPOINT,EMBER_ZDP_NOT_ACTIVE, EMBER_ZDP_NOT_SUPPORTED, EMBER_ZDP_TIMEOUT, E-MBER_ZDP_NO_MATCH,EMBER_ZDP_NO_ENTRY, EMBER_ZDP_NO_DESCRIPTOR, EMBER_ZDP_INSUFFICIEN-T_SPACE, EMBER_ZDP_NOT_PERMITTED,EMBER_ZDP_TABLE_FULL, EMBER_ZDP_NOT_AUTHORIZED, EMBER_NWK_ALREAD-Y_PRESENT, EMBER_NWK_TABLE_FULL,EMBER_NWK_UNKNOWN_DEVICE }

Network and IEEE Address Request/Response

Defines for ZigBee device profile cluster IDs follow. These include descriptions of the formats of themessages.

Note that each message starts with a 1-byte transaction sequence number. This sequence number is used tomatch a response command frame to the request frame that it is replying to. The application shall maintaina 1-byte counter that is copied into this field and incremented by one for each command sent. When a valueof 0xff is reached, the next command shall re-start the counter with a value of 0x00

Network request: <transaction sequence number: 1><EUI64:8> <type:1> <start index:1>

IEEE request: <transaction sequence number: 1><node ID:2> <type:1> <start index:1><type> = 0x00 single address response, ignore the start index= 0x01 extended response -> sends kid’s IDs as well

Response: <transaction sequence number: 1><status:1> <EUI64:8> <node ID:2><ID count:1> <start index:1> <child ID:2>*

• #define NETWORK_ADDRESS_REQUEST• #define NETWORK_ADDRESS_RESPONSE• #define IEEE_ADDRESS_REQUEST• #define IEEE_ADDRESS_RESPONSE

Node Descriptor Request/Response

<br>


// <node descriptor: 13> // // Node Descriptor field is divided into subfields of bitmasks as follows: //(Note: All lengths below are given in bits rather than bytes.) // Logical Type: 3 // Complex DescriptorAvailable: 1 // User Descriptor Available: 1 // (reserved/unused): 3 // APS Flags: 3 // Frequency Band:5 // MAC capability flags: 8 // Manufacturer Code: 16 // Maximum buffer size: 8 // Maximum incomingtransfer size: 16 // Server mask: 16 // Maximum outgoing transfer size: 16 // Descriptor Capability Flags:8 // See ZigBee document 053474, Section 2.3.2.3 for more details.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

357

• #define NODE_DESCRIPTOR_REQUEST• #define NODE_DESCRIPTOR_RESPONSE

Power Descriptor Request / Response

<br>


<current power mode, available power sources:1><current power source, current power source level:1>

// See ZigBee document 053474, Section 2.3.2.4 for more details.

• #define POWER_DESCRIPTOR_REQUEST• #define POWER_DESCRIPTOR_RESPONSE

Simple Descriptor Request / Response

Request: <transaction sequence number: 1><node ID:2> <endpoint:1>

Response: <transaction sequence number: 1><status:1> <node ID:2> <length:1> <endpoint:1><app profile ID:2> <app device ID:2><app device version, app flags:1><input cluster count:1> <input cluster:2>*<output cluster count:1> <output cluster:2>*

• #define SIMPLE_DESCRIPTOR_REQUEST• #define SIMPLE_DESCRIPTOR_RESPONSE

Active Endpoints Request / Response

Request: <transaction sequence number: 1> <node ID:2>Response: <transaction sequence number: 1>

<status:1> <node ID:2> <endpoint count:1> <endpoint:1>*

• #define ACTIVE_ENDPOINTS_REQUEST• #define ACTIVE_ENDPOINTS_RESPONSE

Match Descriptors Request / Response

Request: <transaction sequence number: 1><node ID:2> <app profile ID:2><input cluster count:1> <input cluster:2>*<output cluster count:1> <output cluster:2>*

Response: <transaction sequence number: 1><status:1> <node ID:2> <endpoint count:1> <endpoint:1>*

• #define MATCH_DESCRIPTORS_REQUEST• #define MATCH_DESCRIPTORS_RESPONSE

EmberZNet 4.7.2 API EM260 120-3020-000-4720

358

Discovery Cache Request / Response

Request: <transaction sequence number: 1><source node ID:2> <source EUI64:8>

Response: <transaction sequence number: 1><status (== EMBER_ZDP_SUCCESS):1>

• #define DISCOVERY_CACHE_REQUEST• #define DISCOVERY_CACHE_RESPONSE

End Device Announce and End Device Announce Response

Request: <transaction sequence number: 1><node ID:2> <EUI64:8> <capabilities:1>

No response is sent.

• #define END_DEVICE_ANNOUNCE• #define END_DEVICE_ANNOUNCE_RESPONSE

System Server Discovery Request / Response

This is broadcast and only servers which have matching services respond. The response contains the requestservices that the recipient provides.

Request: <transaction sequence number: 1> <server mask:2>Response: <transaction sequence number: 1>

<status (== EMBER_ZDP_SUCCESS):1> <server mask:2>

• #define SYSTEM_SERVER_DISCOVERY_REQUEST• #define SYSTEM_SERVER_DISCOVERY_RESPONSE

ZDO server mask bits

These are used in server discovery requests and responses.

• enum EmberZdoServerMask {EMBER_ZDP_PRIMARY_TRUST_CENTER, EMBER_ZDP_SECONDARY_TRUST_CENTER,EMBER_ZDP_PRIMARY_BINDING_TABLE_CACHE, EMBER_ZDP_SECONDARY_BINDI-NG_TABLE_CACHE,EMBER_ZDP_PRIMARY_DISCOVERY_CACHE, EMBER_ZDP_SECONDARY_DISCOVER-Y_CACHE, EMBER_ZDP_NETWORK_MANAGER }

Find Node Cache Request / Response

This is broadcast and only discovery servers which have the information for the device of interest, or thedevice of interest itself, respond. The requesting device can then direct any service discovery requests tothe responder.

Request: <transaction sequence number: 1><device of interest ID:2> <d-of-i EUI64:8>

Response: <transaction sequence number: 1><responder ID:2> <device of interest ID:2> <d-of-i EUI64:8>

• #define FIND_NODE_CACHE_REQUEST• #define FIND_NODE_CACHE_RESPONSE

EmberZNet 4.7.2 API EM260 120-3020-000-4720

359

End Device Bind Request / Response

Request: <transaction sequence number: 1><node ID:2> <EUI64:8> <endpoint:1> <app profile ID:2><input cluster count:1> <input cluster:2>*<output cluster count:1> <output cluster:2>*


• #define END_DEVICE_BIND_REQUEST• #define END_DEVICE_BIND_RESPONSE

Binding types and Request / Response

Bind and unbind have the same formats. There are two possible formats, depending on whether the desti-nation is a group address or a device address. Device addresses include an endpoint, groups don’t.

Request: <transaction sequence number: 1><source EUI64:8> <source endpoint:1><cluster ID:2> <destination address:3 or 10>

Destination address:<0x01:1> <destination group:2>

Or:<0x03:1> <destination EUI64:8> <destination endpoint:1>


• #define UNICAST_BINDING• #define UNICAST_MANY_TO_ONE_BINDING• #define MULTICAST_BINDING• #define BIND_REQUEST• #define BIND_RESPONSE• #define UNBIND_REQUEST• #define UNBIND_RESPONSE

LQI Table Request / Response


<neighbor table entries:1> <start index:1><entry count:1> <entry:22>*

<entry> = <extended PAN ID:8> <EUI64:8> <node ID:2><device type, rx on when idle, relationship:1><permit joining:1> <depth:1> <LQI:1>

The device-type byte has the following fields:

Name Mask Values

device type 0x03 0x00 coordinator0x01 router0x02 end device0x03 unknown

rx mode 0x0C 0x00 off when idle0x04 on when idle0x08 unknown

relationship 0x70 0x00 parent0x10 child0x20 sibling0x30 other0x40 previous child

reserved 0x10

EmberZNet 4.7.2 API EM260 120-3020-000-4720

360

The permit-joining byte has the following fields

Name Mask Values

permit joining 0x03 0x00 not accepting join requests0x01 accepting join requests0x02 unknown

reserved 0xFC

• #define LQI_TABLE_REQUEST• #define LQI_TABLE_RESPONSE

Routing Table Request / Response


<routing table entries:1> <start index:1><entry count:1> <entry:5>*

<entry> = <destination address:2><status:1><next hop:2>

The status byte has the following fields:

Name Mask Values

status 0x07 0x00 active0x01 discovery underway0x02 discovery failed0x03 inactive0x04 validation underway

flags 0x380x08 memory constrained0x10 many-to-one0x20 route record required

reserved 0xC0

• #define ROUTING_TABLE_REQUEST• #define ROUTING_TABLE_RESPONSE

Binding Table Request / Response

Request: <transaction sequence number: 1> <start index:1>Response: <transaction sequence number: 1>

<status:1> <binding table entries:1> <start index:1><entry count:1> <entry:14/21>*

<entry> = <source EUI64:8> <source endpoint:1> <cluster ID:2><dest addr mode:1> <dest:2/8> <dest endpoint:0/1>

Note

If Dest. Address Mode = 0x03, then the Long Dest. Address will be used and Dest. endpoint will beincluded. If Dest. Address Mode = 0x01, then the Short Dest. Address will be used and there will beno Dest. endpoint.

• #define BINDING_TABLE_REQUEST• #define BINDING_TABLE_RESPONSE

EmberZNet 4.7.2 API EM260 120-3020-000-4720

361

Leave Request / Response

Request: <transaction sequence number: 1> <EUI64:8> <flags:1>The flag bits are:0x40 remove children0x80 rejoin


• #define LEAVE_REQUEST• #define LEAVE_RESPONSE• #define LEAVE_REQUEST_REMOVE_CHILDREN_FLAG• #define LEAVE_REQUEST_REJOIN_FLAG

Permit Joining Request / Response

Request: <transaction sequence number: 1><duration:1> <permit authentication:1>


• #define PERMIT_JOINING_REQUEST• #define PERMIT_JOINING_RESPONSE

Network Update Request / Response

Request: <transaction sequence number: 1><scan channels:4> <duration:1> <count:0/1> <manager:0/2>

If the duration is in 0x00 ... 0x05, then ’count’ is present butnot ’manager’. Perform ’count’ scans of the given duration on thegiven channels.

If duration is 0xFE, then ’channels’ should have a single channeland ’count’ and ’manager’ are not present. Switch to the indicatedchannel.

If duration is 0xFF, then ’count’ is not present. Set the activechannels and the network manager ID to the values given.

Unicast requests always get a response, which is INVALID_REQUEST if theduration is not a legal value.

Response: <transaction sequence number: 1> <status:1><scanned channels:4> <transmissions:2> <failures:2><energy count:1> <energy:1>*

• #define NWK_UPDATE_REQUEST• #define NWK_UPDATE_RESPONSE

Unsupported

Not mandatory and not supported.

• #define COMPLEX_DESCRIPTOR_REQUEST• #define COMPLEX_DESCRIPTOR_RESPONSE• #define USER_DESCRIPTOR_REQUEST• #define USER_DESCRIPTOR_RESPONSE• #define DISCOVERY_REGISTER_REQUEST• #define DISCOVERY_REGISTER_RESPONSE• #define USER_DESCRIPTOR_SET

EmberZNet 4.7.2 API EM260 120-3020-000-4720

362

• #define USER_DESCRIPTOR_CONFIRM• #define NETWORK_DISCOVERY_REQUEST• #define NETWORK_DISCOVERY_RESPONSE• #define DIRECT_JOIN_REQUEST• #define DIRECT_JOIN_RESPONSE• #define CLUSTER_ID_RESPONSE_MINIMUM

ZDO configuration flags.

For controlling which ZDO requests are passed to the application. These are normally controlled via thefollowing configuration definitions:

EMBER_APPLICATION_RECEIVES_SUPPORTED_ZDO_REQUESTS EMBER_APPLICATION_H-ANDLES_UNSUPPORTED_ZDO_REQUESTS EMBER_APPLICATION_HANDLES_ENDPOINT_Z-DO_REQUESTS EMBER_APPLICATION_HANDLES_BINDING_ZDO_REQUESTS

See ember-configuration.h for more information.

• enum EmberZdoConfigurationFlags { EMBER_APP_RECEIVES_SUPPORTED_ZDO_REQUES-TS, EMBER_APP_HANDLES_UNSUPPORTED_ZDO_REQUESTS, EMBER_APP_HANDLE-S_ZDO_ENDPOINT_REQUESTS, EMBER_APP_HANDLES_ZDO_BINDING_REQUESTS }


Ember data type definitions. See Ember Common Data Types for details.

Definition in file ember-types.h.


8.55.2.1 EmberEventControl∗ control

The control structure for the event.


8.55.2.2 void(∗ handler)(void)

The procedure to call when the event fires.


8.56 ember-types.h

0000100020 #ifndef EMBER_TYPES_H00021 #define EMBER_TYPES_H0002200023 #ifndef DOXYGEN_SHOULD_SKIP_THIS00024 #include "stack/config/ember-configuration-defaults.h

"00025 #include "stack/include/ember-static-struct.h"00026 #endif //DOXYGEN_SHOULD_SKIP_THIS00027

EmberZNet 4.7.2 API EM260 120-3020-000-4720

363

0003200036 #ifdef DOXYGEN_SHOULD_SKIP_THIS00037 enum EmberVersionType00038 #else00039 typedef int8u EmberVersionType;00040 enum00041 #endif00042 {00043 EMBER_VERSION_TYPE_PRE_RELEASE = 0x00,00044 // Anything other than 0xAA is considered pre-release00045 // We may define other types in the future (e.g. beta, alpha)00046 // We chose an arbitrary number (0xAA) to allow for expansion, but00047 // to prevent ambiguity in case 0x00 or 0xFF is accidentally retrieved00048 // as the version type.00049 EMBER_VERSION_TYPE_GA = 0xAA,00050 };0005100055 typedef struct {00056 int16u build;00057 int8u major;00058 int8u minor;00059 int8u patch;00060 int8u special;00061 EmberVersionType type;00062 } EmberVersion;0006300067 extern const EmberVersion emberVersion;0006800072 #define EUI64_SIZE 80007300077 #define EXTENDED_PAN_ID_SIZE 80007800082 #define EMBER_ENCRYPTION_KEY_SIZE 160008300088 #define EMBER_CERTIFICATE_SIZE 480008900093 #define EMBER_PUBLIC_KEY_SIZE 220009400098 #define EMBER_PRIVATE_KEY_SIZE 210009900103 #define EMBER_SMAC_SIZE 160010400109 #define EMBER_SIGNATURE_SIZE 420011000114 #define EMBER_AES_HASH_BLOCK_SIZE 16001150011600120 #ifndef __EMBERSTATUS_TYPE__00121 #define __EMBERSTATUS_TYPE__00122 typedef int8u EmberStatus;00123 #endif //__EMBERSTATUS_TYPE__0012400128 typedef int8u EmberEUI64[EUI64_SIZE];0012900139 typedef int8u EmberMessageBuffer;0014000144 typedef int16u EmberNodeId;0014500147 typedef int16u EmberMulticastId;0014800152 typedef int16u EmberPanId;0015300157 #define EMBER_MAX_802_15_4_CHANNEL_NUMBER 260015800162 #define EMBER_MIN_802_15_4_CHANNEL_NUMBER 110016300167 #define EMBER_NUM_802_15_4_CHANNELS \00168 (EMBER_MAX_802_15_4_CHANNEL_NUMBER - EMBER_MIN_802_15_4_CHANNEL_NUMBER + 1)0016900173 #define EMBER_ALL_802_15_4_CHANNELS_MASK 0x07FFF800UL0017400178 #define EMBER_ZIGBEE_COORDINATOR_ADDRESS 0x00000017900184 #define EMBER_NULL_NODE_ID 0xFFFF0018500190 #define EMBER_NULL_BINDING 0xFF0019100201 #define EMBER_TABLE_ENTRY_UNUSED_NODE_ID 0xFFFF0020200209 #define EMBER_MULTICAST_NODE_ID 0xFFFE

EmberZNet 4.7.2 API EM260 120-3020-000-4720

364

0021000218 #define EMBER_UNKNOWN_NODE_ID 0xFFFD0021900227 #define EMBER_DISCOVERY_ACTIVE_NODE_ID 0xFFFC0022800233 #define EMBER_NULL_ADDRESS_TABLE_INDEX 0xFF0023400238 #define EMBER_ZDO_ENDPOINT 00023900243 #define EMBER_BROADCAST_ENDPOINT 0xFF0024400248 #define EMBER_ZDO_PROFILE_ID 0x00000024900253 #define EMBER_WILDCARD_PROFILE_ID 0xFFFF0025400258 #define EMBER_MAXIMUM_STANDARD_PROFILE_ID 0x7FFF002590026000266 #define EMBER_BROADCAST_TABLE_TIMEOUT_QS (20 * 4)002670026800269 #ifdef DOXYGEN_SHOULD_SKIP_THIS00270 enum EmberLeaveRequestFlags00271 #else00272 typedef int8u EmberLeaveRequestFlags;00273 enum00274 #endif00275 {00277 EMBER_ZIGBEE_LEAVE_AND_REJOIN = 0x20,0027800280 EMBER_ZIGBEE_LEAVE_AND_REMOVE_CHILDREN

= 0x40,00281 };0028200283 #ifdef DOXYGEN_SHOULD_SKIP_THIS00284 enum EmberLeaveReason00285 #else00286 typedef int8u EmberLeaveReason;00287 enum00288 #endif00289 {00290 EMBER_LEAVE_REASON_NONE = 0,00291 EMBER_LEAVE_DUE_TO_NWK_LEAVE_MESSAGE = 1

,00292 EMBER_LEAVE_DUE_TO_APS_REMOVE_MESSAGE =

2,00293 // Currently, the stack does not process the ZDO leave message since it is

optional00294 EMBER_LEAVE_DUE_TO_ZDO_LEAVE_MESSAGE = 3

,00295 EMBER_LEAVE_DUE_TO_ZLL_TOUCHLINK = 4,0029600297 EMBER_LEAVE_DUE_TO_APP_EVENT_1 = 0xFF,00298 };00299003010030200315 #define EMBER_BROADCAST_ADDRESS 0xFFFC0031600317 #define EMBER_RX_ON_WHEN_IDLE_BROADCAST_ADDRESS 0xFFFD0031800319 #define EMBER_SLEEPY_BROADCAST_ADDRESS 0xFFFF0032000328 #ifdef DOXYGEN_SHOULD_SKIP_THIS00329 enum EmberNodeType00330 #else00331 typedef int8u EmberNodeType;00332 enum00333 #endif00334 {00336 EMBER_UNKNOWN_DEVICE = 0,00338 EMBER_COORDINATOR = 1,00340 EMBER_ROUTER = 2,00342 EMBER_END_DEVICE = 3,00346 EMBER_SLEEPY_END_DEVICE = 4,00348 EMBER_MOBILE_END_DEVICE = 500349 };0035000354 typedef struct {00355 int16u panId;

EmberZNet 4.7.2 API EM260 120-3020-000-4720

365

00356 int8u channel;00357 boolean allowingJoin;00358 int8u extendedPanId[8];00359 int8u stackProfile;00360 int8u nwkUpdateId;00361 } EmberZigbeeNetwork;003620036300368 #ifdef DOXYGEN_SHOULD_SKIP_THIS00369 enum EmberNetworkInitBitmask00370 #else00371 typedef int16u EmberNetworkInitBitmask;00372 enum00373 #endif00374 {00375 EMBER_NETWORK_INIT_NO_OPTIONS = 0x0000

,00379 EMBER_NETWORK_INIT_PARENT_INFO_IN_TOKEN

= 0x0001,00380 };003810038200387 typedef struct {00388 EmberNetworkInitBitmask bitmask;00389 } EmberNetworkInitStruct;003900039100398 #ifdef DOXYGEN_SHOULD_SKIP_THIS00399 enum EmberApsOption00400 #else00401 typedef int16u EmberApsOption;00402 enum00403 #endif00404 {00406 EMBER_APS_OPTION_NONE = 0x0000,00418 EMBER_APS_OPTION_DSA_SIGN = 0x0010,00421 EMBER_APS_OPTION_ENCRYPTION = 0x0020

,00425 EMBER_APS_OPTION_RETRY = 0x0040,00431 EMBER_APS_OPTION_ENABLE_ROUTE_DISCOVERY

= 0x0100,00434 EMBER_APS_OPTION_FORCE_ROUTE_DISCOVERY

= 0x0200,00436 EMBER_APS_OPTION_SOURCE_EUI64 =

0x0400,00438 EMBER_APS_OPTION_DESTINATION_EUI64 =

0x0800,00441 EMBER_APS_OPTION_ENABLE_ADDRESS_DISCOVERY

= 0x1000,00446 EMBER_APS_OPTION_POLL_RESPONSE =

0x2000,00451 EMBER_APS_OPTION_ZDO_RESPONSE_REQUIRED

= 0x4000,00457 EMBER_APS_OPTION_FRAGMENT =

SIGNED_ENUM 0x800000458 };00459004600046100465 #ifdef DOXYGEN_SHOULD_SKIP_THIS00466 enum EmberIncomingMessageType00467 #else00468 typedef int8u EmberIncomingMessageType;00469 enum00470 #endif00471 {00473 EMBER_INCOMING_UNICAST,00475 EMBER_INCOMING_UNICAST_REPLY,00477 EMBER_INCOMING_MULTICAST,00479 EMBER_INCOMING_MULTICAST_LOOPBACK,00481 EMBER_INCOMING_BROADCAST,00483 EMBER_INCOMING_BROADCAST_LOOPBACK00484 };004850048600490 #ifdef DOXYGEN_SHOULD_SKIP_THIS00491 enum EmberOutgoingMessageType00492 #else00493 typedef int8u EmberOutgoingMessageType;00494 enum

EmberZNet 4.7.2 API EM260 120-3020-000-4720

366

00495 #endif00496 {00498 EMBER_OUTGOING_DIRECT,00500 EMBER_OUTGOING_VIA_ADDRESS_TABLE,00502 EMBER_OUTGOING_VIA_BINDING,00505 EMBER_OUTGOING_MULTICAST,00508 EMBER_OUTGOING_BROADCAST00509 };005100051100515 #ifdef DOXYGEN_SHOULD_SKIP_THIS00516 enum EmberNetworkStatus00517 #else00518 typedef int8u EmberNetworkStatus;00519 enum00520 #endif00521 {00523 EMBER_NO_NETWORK,00525 EMBER_JOINING_NETWORK,00527 EMBER_JOINED_NETWORK,00530 EMBER_JOINED_NETWORK_NO_PARENT,00532 EMBER_LEAVING_NETWORK00533 };005340053500539 #ifdef DOXYGEN_SHOULD_SKIP_THIS00540 enum EmberNetworkScanType00541 #else00542 typedef int8u EmberNetworkScanType;00543 enum00544 #endif00545 {00547 EMBER_ENERGY_SCAN,00549 EMBER_ACTIVE_SCAN00550 };005510055200556 #ifdef DOXYGEN_SHOULD_SKIP_THIS00557 enum EmberBindingType00558 #else00559 typedef int8u EmberBindingType;00560 enum00561 #endif00562 {00564 EMBER_UNUSED_BINDING = 0,00566 EMBER_UNICAST_BINDING = 1,00570 EMBER_MANY_TO_ONE_BINDING = 2,00574 EMBER_MULTICAST_BINDING = 3,00575 };005760057700586 #define EMBER_LOW_RAM_CONCENTRATOR 0xFFF80058700591 #define EMBER_HIGH_RAM_CONCENTRATOR 0xFFF900592005940059500599 #ifdef DOXYGEN_SHOULD_SKIP_THIS00600 enum EmberJoinDecision00601 #else00602 typedef int8u EmberJoinDecision;00603 enum00604 #endif00605 {00607 EMBER_USE_PRECONFIGURED_KEY = 0,00609 EMBER_SEND_KEY_IN_THE_CLEAR,00611 EMBER_DENY_JOIN,00613 EMBER_NO_ACTION00614 };0061500619 #define EMBER_JOIN_DECISION_STRINGS \00620 "use preconfigured key", \00621 "send key in the clear", \00622 "deny join", \00623 "no action",006240062500631 // These map to the actual values within the APS Command frame so they cannot00632 // be arbitrarily changed.00633 #ifdef DOXYGEN_SHOULD_SKIP_THIS

EmberZNet 4.7.2 API EM260 120-3020-000-4720

367

00634 enum EmberDeviceUpdate00635 #else00636 typedef int8u EmberDeviceUpdate;00637 enum00638 #endif00639 {00640 EMBER_STANDARD_SECURITY_SECURED_REJOIN

= 0,00641 EMBER_STANDARD_SECURITY_UNSECURED_JOIN

= 1,00642 EMBER_DEVICE_LEFT = 2,00643 EMBER_STANDARD_SECURITY_UNSECURED_REJOIN

= 3,00644 EMBER_HIGH_SECURITY_SECURED_REJOIN =

4,00645 EMBER_HIGH_SECURITY_UNSECURED_JOIN =

5,00646 /* 6 Reserved */00647 EMBER_HIGH_SECURITY_UNSECURED_REJOIN

= 7,00648 /* 8 - 15 Reserved */00649 };0065000654 #define EMBER_DEVICE_UPDATE_STRINGS \00655 "secured rejoin", \00656 "UNsecured join", \00657 "device left", \00658 "UNsecured rejoin", \00659 "high secured rejoin", \00660 "high UNsecured join", \00661 "RESERVED", /* reserved status code, per the spec. */ \00662 "high UNsecured rejoin",0066300667 #ifdef DOXYGEN_SHOULD_SKIP_THIS00668 enum EmberDeviceUpdate00669 #else00670 typedef int8u EmberRejoinReason;00671 enum00672 #endif00673 {00674 EMBER_REJOIN_REASON_NONE = 0,00675 EMBER_REJOIN_DUE_TO_NWK_KEY_UPDATE = 1,00676 EMBER_REJOIN_DUE_TO_LEAVE_MESSAGE = 2,00677 EMBER_REJOIN_DUE_TO_NO_PARENT = 3,00678 EMBER_REJOIN_DUE_TO_ZLL_TOUCHLINK = 4,0067900680 // App. Framework events00681 // 0xA0 - 0xE00068200683 // Customer Defined Events00684 // I numbered these backwards in case there is ever request00685 // for more application events. We can expand them00686 // without renumbering the previous ones.00687 EMBER_REJOIN_DUE_TO_APP_EVENT_5 = 0xFB,00688 EMBER_REJOIN_DUE_TO_APP_EVENT_4 = 0xFC,00689 EMBER_REJOIN_DUE_TO_APP_EVENT_3 = 0xFD,00690 EMBER_REJOIN_DUE_TO_APP_EVENT_2 = 0xFE,00691 EMBER_REJOIN_DUE_TO_APP_EVENT_1 = 0xFF,00692 };0069300697 #ifdef DOXYGEN_SHOULD_SKIP_THIS00698 enum EmberClusterListId00699 #else00700 typedef int8u EmberClusterListId;00701 enum00702 #endif00703 {00705 EMBER_INPUT_CLUSTER_LIST = 0,00707 EMBER_OUTPUT_CLUSTER_LIST = 100708 };007090071000715 #ifdef DOXYGEN_SHOULD_SKIP_THIS00716 enum EmberEventUnits00717 #else00718 typedef int8u EmberEventUnits;00719 enum00720 #endif00721 {00723 EMBER_EVENT_INACTIVE = 0,

EmberZNet 4.7.2 API EM260 120-3020-000-4720

368

00725 EMBER_EVENT_MS_TIME,00728 EMBER_EVENT_QS_TIME,00731 EMBER_EVENT_MINUTE_TIME,00733 EMBER_EVENT_ZERO_DELAY00734 };007350073600740 #ifdef DOXYGEN_SHOULD_SKIP_THIS00741 enum EmberJoinMethod00742 #else00743 typedef int8u EmberJoinMethod;00744 enum00745 #endif00746 {00752 EMBER_USE_MAC_ASSOCIATION = 0,0075300764 EMBER_USE_NWK_REJOIN = 1,007650076600767 /* For those networks where the "permit joining" flag is never turned00768 * on, they will need to use a NWK Rejoin. If those devices have been00769 * preconfigured with the NWK key (including sequence number) they can use00770 * a secured rejoin. This is only necessary for end devices since they need00771 * a parent. Routers can simply use the ::EMBER_USE_NWK_COMMISSIONING00772 * join method below.00773 */00774 EMBER_USE_NWK_REJOIN_HAVE_NWK_KEY = 2,0077500780 EMBER_USE_NWK_COMMISSIONING = 3,00781 };007820078300790 typedef struct {00792 int8u extendedPanId[8];00794 int16u panId;00796 int8s radioTxPower;00798 int8u radioChannel;00803 EmberJoinMethod joinMethod;0080400809 EmberNodeId nwkManagerId;00815 int8u nwkUpdateId;00821 int32u channels;00822 } EmberNetworkParameters;008230082400825 #ifdef DOXYGEN_SHOULD_SKIP_THIS00826 #define emberInitializeNetworkParameters(parameters) \00827 (MEMSET(parameters, 0, sizeof(EmberNetworkParameters)))00828 #else00829 void emberInitializeNetworkParameters(

EmberNetworkParameters* parameters);00830 #endif0083100835 typedef struct {00837 int16u profileId;00839 int16u clusterId;00841 int8u sourceEndpoint;00843 int8u destinationEndpoint;00845 EmberApsOption options;00847 int16u groupId;00849 int8u sequence;00850 } EmberApsFrame;008510085200859 typedef struct {00861 EmberBindingType type;00863 int8u local;00871 int16u clusterId;00873 int8u remote;00878 EmberEUI64 identifier;00880 int8u networkIndex;00881 } EmberBindingTableEntry;008820088300889 typedef struct {00891 int16u shortId;00894 int8u averageLqi;00897 int8u inCost;00904 int8u outCost;00910 int8u age;

EmberZNet 4.7.2 API EM260 120-3020-000-4720

369

00912 EmberEUI64 longId;00913 } EmberNeighborTableEntry;0091400920 typedef struct {00922 int16u destination;00924 int16u nextHop;00927 int8u status;00930 int8u age;00933 int8u concentratorType;00938 int8u routeRecordState;00939 } EmberRouteTableEntry;0094000948 typedef struct {00950 EmberMulticastId multicastId;00954 int8u endpoint;00956 int8u networkIndex;00957 } EmberMulticastTableEntry;0095800963 #ifdef DOXYGEN_SHOULD_SKIP_THIS00964 enum EmberCounterType00965 #else00966 typedef int8u EmberCounterType;00967 enum00968 #endif00969 {00971 EMBER_COUNTER_MAC_RX_BROADCAST = 0,00973 EMBER_COUNTER_MAC_TX_BROADCAST = 1,00975 EMBER_COUNTER_MAC_RX_UNICAST = 2,00977 EMBER_COUNTER_MAC_TX_UNICAST_SUCCESS = 3,00983 EMBER_COUNTER_MAC_TX_UNICAST_RETRY = 4,00985 EMBER_COUNTER_MAC_TX_UNICAST_FAILED = 5,0098600988 EMBER_COUNTER_APS_DATA_RX_BROADCAST = 6,00990 EMBER_COUNTER_APS_DATA_TX_BROADCAST = 7,00992 EMBER_COUNTER_APS_DATA_RX_UNICAST = 8,00994 EMBER_COUNTER_APS_DATA_TX_UNICAST_SUCCESS

= 9,01000 EMBER_COUNTER_APS_DATA_TX_UNICAST_RETRY

= 10,01002 EMBER_COUNTER_APS_DATA_TX_UNICAST_FAILED

= 11,0100301006 EMBER_COUNTER_ROUTE_DISCOVERY_INITIATED

= 12,0100701009 EMBER_COUNTER_NEIGHBOR_ADDED = 13,01011 EMBER_COUNTER_NEIGHBOR_REMOVED = 14,01013 EMBER_COUNTER_NEIGHBOR_STALE = 15,0101401016 EMBER_COUNTER_JOIN_INDICATION = 16,01018 EMBER_COUNTER_CHILD_REMOVED = 17,0101901021 EMBER_COUNTER_ASH_OVERFLOW_ERROR = 18,01023 EMBER_COUNTER_ASH_FRAMING_ERROR = 19,01025 EMBER_COUNTER_ASH_OVERRUN_ERROR = 20,0102601029 EMBER_COUNTER_NWK_FRAME_COUNTER_FAILURE

= 21,0103001033 EMBER_COUNTER_APS_FRAME_COUNTER_FAILURE

= 22,0103401036 EMBER_COUNTER_ASH_XOFF = 23,0103701041 EMBER_COUNTER_APS_LINK_KEY_NOT_AUTHORIZED

= 24,0104201045 EMBER_COUNTER_NWK_DECRYPTION_FAILURE = 25

,0104601049 EMBER_COUNTER_APS_DECRYPTION_FAILURE = 26

,0105001055 EMBER_COUNTER_ALLOCATE_PACKET_BUFFER_FAILURE

= 27,0105601058 EMBER_COUNTER_RELAYED_UNICAST = 28,0105901071 EMBER_COUNTER_PHY_TO_MAC_QUEUE_LIMIT_REACHED

= 29,

EmberZNet 4.7.2 API EM260 120-3020-000-4720

370

0107201077 EMBER_COUNTER_PACKET_VALIDATE_LIBRARY_DROPPED_COUNT

= 30,0107801080 EMBER_COUNTER_TYPE_COUNT = 3101081 };0108201086 #define EMBER_COUNTER_STRINGS \01087 "Mac Rx Bcast", \01088 "Mac Tx Bcast", \01089 "Mac Rx Ucast", \01090 "Mac Tx Ucast", \01091 "Mac Tx Ucast Retry", \01092 "Mac Tx Ucast Fail", \01093 "APS Rx Bcast", \01094 "APS Tx Bcast", \01095 "APS Rx Ucast", \01096 "APS Tx Ucast Success", \01097 "APS Tx Ucast Retry", \01098 "APS Tx Ucast Fail", \01099 "Route Disc Initiated", \01100 "Neighbor Added", \01101 "Neighbor Removed", \01102 "Neighbor Stale", \01103 "Join Indication", \01104 "Child Moved", \01105 "ASH Overflow", \01106 "ASH Frame Error", \01107 "ASH Overrun Error", \01108 "NWK FC Failure", \01109 "APS FC Failure", \01110 "ASH XOff", \01111 "APS Unauthorized Key", \01112 "NWK Decrypt Failures", \01113 "APS Decrypt Failures", \01114 "Packet Buffer Allocate Failures", \01115 "Relayed Ucast", \01116 "Phy to MAC queue limit reached", \01117 "Packet Validate drop count", \01118 NULL0111901121 typedef int8u EmberTaskId;0112201123 #ifndef EZSP_HOST0112401130 typedef struct {01132 EmberEventUnits status;01134 EmberTaskId taskid;01138 int32u timeToExecute;01139 } EmberEventControl;01140 #else01141 // host applications use an older, basic form of the event system01148 typedef struct {01150 EmberEventUnits status;01154 int16u timeToExecute;01155 } EmberEventControl;01156 #endif0115701165 typedef PGM struct {01167 EmberEventControl *control;01169 void (*handler)(void);01170 } EmberEventData;0117101176 typedef struct {01177 // The time when the next event associated with this task will fire01178 int32u nextEventTime;01179 // The list of events associated with this task01180 EmberEventData *events;01181 // A flag that indicates the task has something to do other than events01182 boolean busy;01183 } EmberTaskControl;011840118901194 #define EMBER_TX_POWER_MODE_DEFAULT 0x00000119501198 #define EMBER_TX_POWER_MODE_BOOST 0x00010119901203 #define EMBER_TX_POWER_MODE_ALTERNATE 0x00020120401208 #define EMBER_TX_POWER_MODE_BOOST_AND_ALTERNATE (EMBER_TX_POWER_MODE_BOOST

EmberZNet 4.7.2 API EM260 120-3020-000-4720

371

\01209 |EMBER_TX_POWER_MODE_ALTERNATE)01210 #ifndef DOXYGEN_SHOULD_SKIP_THIS01211 // The application does not ever need to call emberSetTxPowerMode() with the01212 // txPowerMode parameter set to this value. This value is used internally by01213 // the stack to indicate that the default token configuration has not been01214 // overridden by a prior call to emberSetTxPowerMode().01215 #define EMBER_TX_POWER_MODE_USE_TOKEN 0x800001216 #endif//DOXYGEN_SHOULD_SKIP_THIS01217012190122401232 #define EMBER_PRIVATE_PROFILE_ID 0xC00E0123301272 #define EMBER_BROADCAST_ALARM_CLUSTER 0x00000127301310 #define EMBER_UNICAST_ALARM_CLUSTER 0x00010131101327 #define EMBER_CACHED_UNICAST_ALARM_CLUSTER 0x00020132801332 #define EMBER_REPORT_COUNTERS_REQUEST 0x00030133301335 #define EMBER_REPORT_COUNTERS_RESPONSE 0x80030133601341 #define EMBER_REPORT_AND_CLEAR_COUNTERS_REQUEST 0x00040134201344 #define EMBER_REPORT_AND_CLEAR_COUNTERS_RESPONSE 0x80040134501350 #define EMBER_OTA_CERTIFICATE_UPGRADE_CLUSTER 0x000501351013530135401357 typedef struct {01359 int8u contents[EMBER_ENCRYPTION_KEY_SIZE];01360 } EmberKeyData;0136101364 typedef struct {01365 /* This is the certificate byte data. */01366 int8u contents[EMBER_CERTIFICATE_SIZE];01367 } EmberCertificateData;0136801371 typedef struct {01372 int8u contents[EMBER_PUBLIC_KEY_SIZE];01373 } EmberPublicKeyData;0137401377 typedef struct {01378 int8u contents[EMBER_PRIVATE_KEY_SIZE];01379 } EmberPrivateKeyData;0138001383 typedef struct {01384 int8u contents[EMBER_SMAC_SIZE];01385 } EmberSmacData;0138601390 typedef struct {01391 int8u contents[EMBER_SIGNATURE_SIZE];01392 } EmberSignatureData;0139301396 typedef struct {01397 int8u contents[EMBER_AES_HASH_BLOCK_SIZE];01398 } EmberMessageDigest;0139901403 typedef struct {01404 int8u result[EMBER_AES_HASH_BLOCK_SIZE];01405 int32u length;01406 } EmberAesMmoHashContext;014070140801414 #define EMBER_STANDARD_SECURITY_MODE 0x00000141501419 #define EMBER_TRUST_CENTER_NODE_ID 0x0000014200142101425 #ifdef DOXYGEN_SHOULD_SKIP_THIS01426 enum EmberInitialSecurityBitmask01427 #else01428 typedef int16u EmberInitialSecurityBitmask;01429 enum01430 #endif01431 {01434 EMBER_DISTRIBUTED_TRUST_CENTER_MODE

EmberZNet 4.7.2 API EM260 120-3020-000-4720

372

= 0x0002,01437 EMBER_TRUST_CENTER_GLOBAL_LINK_KEY =

0x0004,01440 EMBER_PRECONFIGURED_NETWORK_KEY_MODE

= 0x0008,0144101442 #if !defined DOXYGEN_SHOULD_SKIP_THIS01443 // Hidden fields used internally.01444 EMBER_HAVE_TRUST_CENTER_UNKNOWN_KEY_TOKEN = 0x0010,01445 EMBER_HAVE_TRUST_CENTER_LINK_KEY_TOKEN = 0x0020,01446 EMBER_HAVE_TRUST_CENTER_MASTER_KEY_TOKEN = 0x0030,01447 #endif0144801458 EMBER_HAVE_TRUST_CENTER_EUI64 =

0x0040,0145901466 EMBER_TRUST_CENTER_USES_HASHED_LINK_KEY

= 0x0084,0146701471 EMBER_HAVE_PRECONFIGURED_KEY =

0x0100,01475 EMBER_HAVE_NETWORK_KEY = 0x0200,01480 EMBER_GET_LINK_KEY_WHEN_JOINING =

0x0400,01486 EMBER_REQUIRE_ENCRYPTED_KEY = 0x0800

,01494 EMBER_NO_FRAME_COUNTER_RESET =

0x1000,01500 EMBER_GET_PRECONFIGURED_KEY_FROM_INSTALL_CODE

= 0x2000,0150101502 #if !defined DOXYGEN_SHOULD_SKIP_THIS01503 // Internal data01504 EM_SAVED_IN_TOKEN = 0x4000,01505 #define EM_SECURITY_INITIALIZED 0x00008000L0150601507 // This is only used internally. High security is not released or supported01508 // except for golden unit compliance.01509 #define EMBER_HIGH_SECURITY_MODE 0x000101510 #else01511 /* All other bits are reserved and must be zero. */01512 #endif01513 };0151401518 #ifdef DOXYGEN_SHOULD_SKIP_THIS01519 enum EmberExtendedSecurityBitmask01520 #else01521 typedef int16u EmberExtendedSecurityBitmask;01522 enum01523 #endif01524 {01525 #ifndef DOXYGEN_SHOULD_SKIP_THIS01526 // If this bit is set, we set the ’key token data’ field in the Initial01527 // Security Bitmask to 0 (No Preconfig Key token), otherwise we leave the01528 // field as it is.01529 EMBER_PRECONFIG_KEY_NOT_VALID = 0x0001,01530 #endif0153101532 // bits 1-3 are unused.0153301536 EMBER_JOINER_GLOBAL_LINK_KEY = 0x0010,0153701538 // bit 5-7 reserved for future use (stored in TOKEN).0153901542 EMBER_NWK_LEAVE_REQUEST_NOT_ALLOWED =

0x0100,0154301544 #ifndef DOXYGEN_SHOULD_SKIP_THIS0154501549 EMBER_R18_STACK_BEHAVIOR = 0x0200,01550 #endif0155101552 // bits 10-11 are reserved for future use (stored in RAM only).0155301554 // bits 12-15 are unused.01555 };0155601559 #define EMBER_NO_TRUST_CENTER_MODE EMBER_DISTRIBUTED_TRUST_CENTER_MODE0156001563 #define EMBER_GLOBAL_LINK_KEY EMBER_TRUST_CENTER_GLOBAL_LINK_KEY

EmberZNet 4.7.2 API EM260 120-3020-000-4720

373

015640156501566 #if !defined DOXYGEN_SHOULD_SKIP_THIS01567 #define NO_TRUST_CENTER_KEY_TOKEN 0x000001568 #define TRUST_CENTER_KEY_TOKEN_MASK 0x003001569 #define SECURITY_BIT_TOKEN_MASK 0x71FF0157001571 #define SECURITY_LOWER_BIT_MASK 0x000000FF // ""01572 #define SECURITY_UPPER_BIT_MASK 0x00FF0000L // ""01573 #endif0157401577 typedef struct {01582 int16u bitmask;01591 EmberKeyData preconfiguredKey;01597 EmberKeyData networkKey;01604 int8u networkKeySequenceNumber;01612 EmberEUI64 preconfiguredTrustCenterEui64

;01613 } EmberInitialSecurityState;016140161501619 #ifdef DOXYGEN_SHOULD_SKIP_THIS01620 enum EmberCurrentSecurityBitmask01621 #else01622 typedef int16u EmberCurrentSecurityBitmask;01623 enum01624 #endif01625 {01626 #if defined DOXYGEN_SHOULD_SKIP_THIS01627 // These options are the same for Initial and Current Security state0162801631 EMBER_STANDARD_SECURITY_MODE_ =

0x0000,01634 EMBER_DISTRIBUTED_TRUST_CENTER_MODE_

= 0x0002,01637 EMBER_TRUST_CENTER_GLOBAL_LINK_KEY_

= 0x0004,01638 #else01639 // Bit 3 reserved01640 #endif0164101642 EMBER_HAVE_TRUST_CENTER_LINK_KEY =

0x0010,0164301645 EMBER_TRUST_CENTER_USES_HASHED_LINK_KEY_

= 0x0084,0164601647 // Bits 1,5,6, 8-15 reserved01648 };0164901650 #if !defined DOXYGEN_SHOULD_SKIP_THIS01651 #define INITIAL_AND_CURRENT_BITMASK 0x00FF01652 #endif016530165401657 typedef struct {01660 EmberCurrentSecurityBitmask bitmask;01664 EmberEUI64 trustCenterLongAddress;01665 } EmberCurrentSecurityState;016660166701671 #ifdef DOXYGEN_SHOULD_SKIP_THIS01672 enum EmberKeyStructBitmask01673 #else01674 typedef int16u EmberKeyStructBitmask;01675 enum01676 #endif01677 {01680 EMBER_KEY_HAS_SEQUENCE_NUMBER = 0x0001,01684 EMBER_KEY_HAS_OUTGOING_FRAME_COUNTER =

0x0002,01688 EMBER_KEY_HAS_INCOMING_FRAME_COUNTER =

0x0004,01692 EMBER_KEY_HAS_PARTNER_EUI64 = 0x0008,01696 EMBER_KEY_IS_AUTHORIZED = 0x0010,01701 EMBER_KEY_PARTNER_IS_SLEEPY = 0x0020,0170201703 };0170401706 #ifdef DOXYGEN_SHOULD_SKIP_THIS

EmberZNet 4.7.2 API EM260 120-3020-000-4720

374

01707 enum EmberKeyType01708 #else01709 typedef int8u EmberKeyType;01710 enum01711 #endif01712 {01714 EMBER_TRUST_CENTER_LINK_KEY = 1,01716 EMBER_TRUST_CENTER_MASTER_KEY = 2,01718 EMBER_CURRENT_NETWORK_KEY = 3,01720 EMBER_NEXT_NETWORK_KEY = 4,01722 EMBER_APPLICATION_LINK_KEY = 5,01724 EMBER_APPLICATION_MASTER_KEY = 6,01725 };0172601730 typedef struct {01734 EmberKeyStructBitmask bitmask;01736 EmberKeyType type;01738 EmberKeyData key;01741 int32u outgoingFrameCounter;01744 int32u incomingFrameCounter;01747 int8u sequenceNumber;01750 EmberEUI64 partnerEUI64;01751 } EmberKeyStruct;017520175301757 #ifdef DOXYGEN_SHOULD_SKIP_THIS01758 enum EmberKeyStatus01759 #else01760 typedef int8u EmberKeyStatus;01761 enum01762 #endif01763 {01764 EMBER_APP_LINK_KEY_ESTABLISHED = 1,01765 EMBER_APP_MASTER_KEY_ESTABLISHED = 2,01766 EMBER_TRUST_CENTER_LINK_KEY_ESTABLISHED

= 3,01767 EMBER_KEY_ESTABLISHMENT_TIMEOUT = 4,01768 EMBER_KEY_TABLE_FULL = 5,0176901770 // These are success status values applying only to the01771 // Trust Center answering key requests01772 EMBER_TC_RESPONDED_TO_KEY_REQUEST = 6

,01773 EMBER_TC_APP_KEY_SENT_TO_REQUESTER =

7,0177401775 // These are failure status values applying only to the01776 // Trust Center answering key requests01777 EMBER_TC_RESPONSE_TO_KEY_REQUEST_FAILED

= 8,01778 EMBER_TC_REQUEST_KEY_TYPE_NOT_SUPPORTED

= 9,01779 EMBER_TC_NO_LINK_KEY_FOR_REQUESTER =

10,01780 EMBER_TC_REQUESTER_EUI64_UNKNOWN = 11

,01781 EMBER_TC_RECEIVED_FIRST_APP_KEY_REQUEST

= 12,01782 EMBER_TC_TIMEOUT_WAITING_FOR_SECOND_APP_KEY_REQUEST

= 13,01783 EMBER_TC_NON_MATCHING_APP_KEY_REQUEST_RECEIVED

= 14,01784 EMBER_TC_FAILED_TO_SEND_APP_KEYS = 15

,01785 EMBER_TC_FAILED_TO_STORE_APP_KEY_REQUEST

= 16,01786 EMBER_TC_REJECTED_APP_KEY_REQUEST =

17,01787 };0178801792 #ifdef DOXYGEN_SHOULD_SKIP_THIS01793 enum EmberLinkKeyRequestPolicy01794 #else01795 typedef int8u EmberLinkKeyRequestPolicy;01796 enum01797 #endif01798 {01799 EMBER_DENY_KEY_REQUESTS = 0x00,01800 EMBER_ALLOW_KEY_REQUESTS = 0x01,01801 };

EmberZNet 4.7.2 API EM260 120-3020-000-4720

375

018020180301811 #if defined DOXYGEN_SHOULD_SKIP_THIS01812 int8u* emberKeyContents(EmberKeyData* key);01813 #else01814 #define emberKeyContents(key) ((key)->contents)01815 #endif0181601824 #if defined DOXYGEN_SHOULD_SKIP_THIS01825 int8u* emberCertificateContents(

EmberCertificateData* cert);01826 #else01827 #define emberCertificateContents(cert) ((cert)->contents)01828 #endif0182901837 #if defined DOXYGEN_SHOULD_SKIP_THIS01838 int8u* emberPublicKeyContents(EmberPublicKeyData

* key);01839 #else01840 #define emberPublicKeyContents(key) ((key)->contents)01841 #endif0184201850 #if defined DOXYGEN_SHOULD_SKIP_THIS01851 int8u* emberPrivateKeyContents(EmberPrivateKeyData

* key);01852 #else01853 #define emberPrivateKeyContents(key) ((key)->contents)01854 #endif0185501860 #if defined DOXYGEN_SHOULD_SKIP_THIS01861 int8u* emberSmacContents(EmberSmacData* key)

;01862 #else01863 #define emberSmacContents(key) ((key)->contents)01864 #endif0186501869 #if defined DOXYGEN_SHOULD_SKIP_THIS01870 int8u* emberSignatureContents(EmberSignatureData

* sig);01871 #else01872 #define emberSignatureContents(sig) ((sig)->contents)01873 #endif018740187501876 #ifdef DOXYGEN_SHOULD_SKIP_THIS01877 enum EmberKeySettings01878 #else01879 typedef int16u EmberKeySettings;01880 enum01881 #endif01882 {01883 EMBER_KEY_PERMISSIONS_NONE = 0x0000,01884 EMBER_KEY_PERMISSIONS_READING_ALLOWED =

0x0001,01885 EMBER_KEY_PERMISSIONS_HASHING_ALLOWED =

0x0002,01886 };018870188801892 typedef struct {01893 EmberKeySettings keySettings;01894 } EmberMfgSecurityStruct;018950189601901 #define EMBER_MFG_SECURITY_CONFIG_MAGIC_NUMBER 0xCABAD11FUL019020190301908 #ifdef DOXYGEN_SHOULD_SKIP_THIS01909 enum EmberMacPassthroughType01910 #else01911 typedef int8u EmberMacPassthroughType;01912 enum01913 #endif01914 {01916 EMBER_MAC_PASSTHROUGH_NONE = 0x00,01918 EMBER_MAC_PASSTHROUGH_SE_INTERPAN =

0x01,01920 EMBER_MAC_PASSTHROUGH_EMBERNET = 0x02,01922 EMBER_MAC_PASSTHROUGH_EMBERNET_SOURCE =

0x04,

EmberZNet 4.7.2 API EM260 120-3020-000-4720

376

01924 EMBER_MAC_PASSTHROUGH_APPLICATION =0x08,

01926 EMBER_MAC_PASSTHROUGH_CUSTOM = 0x10,0192701928 #if !defined DOXYGEN_SHOULD_SKIP_THIS0192901930 EM_MAC_PASSTHROUGH_INTERNAL = 0x8001931 #endif01932 };0193301938 typedef int16u EmberMacFilterMatchData;0193901940 #define EMBER_MAC_FILTER_MATCH_ENABLED_MASK 0x000101941 #define EMBER_MAC_FILTER_MATCH_ON_PAN_DEST_MASK 0x000301942 #define EMBER_MAC_FILTER_MATCH_ON_PAN_SOURCE_MASK 0x000C01943 #define EMBER_MAC_FILTER_MATCH_ON_DEST_MASK 0x003001944 #define EMBER_MAC_FILTER_MATCH_ON_SOURCE_MASK 0x00800194501946 // Globally turn on/off this filter01947 #define EMBER_MAC_FILTER_MATCH_ENABLED 0x000001948 #define EMBER_MAC_FILTER_MATCH_DISABLED 0x00010194901950 // Pick either one of these01951 #define EMBER_MAC_FILTER_MATCH_ON_PAN_DEST_NONE 0x000001952 #define EMBER_MAC_FILTER_MATCH_ON_PAN_DEST_LOCAL 0x000101953 #define EMBER_MAC_FILTER_MATCH_ON_PAN_DEST_BROADCAST 0x00020195401955 // and one of these01956 #define EMBER_MAC_FILTER_MATCH_ON_PAN_SOURCE_NONE 0x000001957 #define EMBER_MAC_FILTER_MATCH_ON_PAN_SOURCE_NON_LOCAL 0x000401958 #define EMBER_MAC_FILTER_MATCH_ON_PAN_SOURCE_LOCAL 0x00080195901960 // and one of these01961 #define EMBER_MAC_FILTER_MATCH_ON_DEST_BROADCAST_SHORT 0x000001962 #define EMBER_MAC_FILTER_MATCH_ON_DEST_UNICAST_SHORT 0x001001963 #define EMBER_MAC_FILTER_MATCH_ON_DEST_UNICAST_LONG 0x00200196401965 // and one of these01966 #define EMBER_MAC_FILTER_MATCH_ON_SOURCE_LONG 0x000001967 #define EMBER_MAC_FILTER_MATCH_ON_SOURCE_SHORT 0x00800196801969 // Last entry should set this and nothing else. No other bits will be

examined.01970 #define EMBER_MAC_FILTER_MATCH_END 0x80000197101975 typedef struct {01976 int8u filterIndexMatch;01977 EmberMacPassthroughType legacyPassthroughType

;01978 EmberMessageBuffer message;01979 } EmberMacFilterMatchStruct;019800198101985 typedef int8u EmberLibraryStatus;019860199101997 #ifdef DOXYGEN_SHOULD_SKIP_THIS01998 enum EmberZdoStatus01999 #else02000 typedef int8u EmberZdoStatus;02001 enum02002 #endif02003 {02004 // These values are taken from Table 48 of ZDP Errata 043238r003 and Table 202005 // of NWK 02130r10.02006 EMBER_ZDP_SUCCESS = 0x00,02007 // 0x01 to 0x7F are reserved02008 EMBER_ZDP_INVALID_REQUEST_TYPE = 0x80,02009 EMBER_ZDP_DEVICE_NOT_FOUND = 0x81,02010 EMBER_ZDP_INVALID_ENDPOINT = 0x82,02011 EMBER_ZDP_NOT_ACTIVE = 0x83,02012 EMBER_ZDP_NOT_SUPPORTED = 0x84,02013 EMBER_ZDP_TIMEOUT = 0x85,02014 EMBER_ZDP_NO_MATCH = 0x86,02015 // 0x87 is reserved = 0x87,02016 EMBER_ZDP_NO_ENTRY = 0x88,02017 EMBER_ZDP_NO_DESCRIPTOR = 0x89,02018 EMBER_ZDP_INSUFFICIENT_SPACE = 0x8a,02019 EMBER_ZDP_NOT_PERMITTED = 0x8b,02020 EMBER_ZDP_TABLE_FULL = 0x8c,

EmberZNet 4.7.2 API EM260 120-3020-000-4720

377

02021 EMBER_ZDP_NOT_AUTHORIZED = 0x8d,0202202023 EMBER_NWK_ALREADY_PRESENT = 0xC5,02024 EMBER_NWK_TABLE_FULL = 0xC7,02025 EMBER_NWK_UNKNOWN_DEVICE = 0xC802026 };02027020400204102042020430204402045020460204702048020490205002051020520205302054 #define NETWORK_ADDRESS_REQUEST 0x000002055 #define NETWORK_ADDRESS_RESPONSE 0x800002056 #define IEEE_ADDRESS_REQUEST 0x000102057 #define IEEE_ADDRESS_RESPONSE 0x8001020580205902066 // <node descriptor: 13>02067 //02068 // Node Descriptor field is divided into subfields of bitmasks as follows:02069 // (Note: All lengths below are given in bits rather than bytes.)02070 // Logical Type: 302071 // Complex Descriptor Available: 102072 // User Descriptor Available: 102073 // (reserved/unused): 302074 // APS Flags: 302075 // Frequency Band: 502076 // MAC capability flags: 802077 // Manufacturer Code: 1602078 // Maximum buffer size: 802079 // Maximum incoming transfer size: 1602080 // Server mask: 1602081 // Maximum outgoing transfer size: 1602082 // Descriptor Capability Flags: 802083 // See ZigBee document 053474, Section 2.3.2.3 for more details.02085 #define NODE_DESCRIPTOR_REQUEST 0x000202086 #define NODE_DESCRIPTOR_RESPONSE 0x8002020870208802097 // See ZigBee document 053474, Section 2.3.2.4 for more details.02099 #define POWER_DESCRIPTOR_REQUEST 0x000302100 #define POWER_DESCRIPTOR_RESPONSE 0x8003021010210202116 #define SIMPLE_DESCRIPTOR_REQUEST 0x000402117 #define SIMPLE_DESCRIPTOR_RESPONSE 0x8004021180211902128 #define ACTIVE_ENDPOINTS_REQUEST 0x000502129 #define ACTIVE_ENDPOINTS_RESPONSE 0x8005021300213102143 #define MATCH_DESCRIPTORS_REQUEST 0x000602144 #define MATCH_DESCRIPTORS_RESPONSE 0x8006021450214602156 #define DISCOVERY_CACHE_REQUEST 0x001202157 #define DISCOVERY_CACHE_RESPONSE 0x8012021580215902168 #define END_DEVICE_ANNOUNCE 0x001302169 #define END_DEVICE_ANNOUNCE_RESPONSE 0x8013021700217102183 #define SYSTEM_SERVER_DISCOVERY_REQUEST 0x001502184 #define SYSTEM_SERVER_DISCOVERY_RESPONSE 0x8015021850218602191 #ifdef DOXYGEN_SHOULD_SKIP_THIS02192 enum EmberZdoServerMask

EmberZNet 4.7.2 API EM260 120-3020-000-4720

378

02193 #else02194 typedef int16u EmberZdoServerMask;02195 enum02196 #endif02197 {02198 EMBER_ZDP_PRIMARY_TRUST_CENTER =

0x0001,02199 EMBER_ZDP_SECONDARY_TRUST_CENTER =

0x0002,02200 EMBER_ZDP_PRIMARY_BINDING_TABLE_CACHE

= 0x0004,02201 EMBER_ZDP_SECONDARY_BINDING_TABLE_CACHE

= 0x0008,02202 EMBER_ZDP_PRIMARY_DISCOVERY_CACHE =

0x0010,02203 EMBER_ZDP_SECONDARY_DISCOVERY_CACHE =

0x0020,02204 EMBER_ZDP_NETWORK_MANAGER = 0x0040,02205 // Bits 0x0080 to 0x8000 are reserved.02206 };0220702221 #define FIND_NODE_CACHE_REQUEST 0x001C02222 #define FIND_NODE_CACHE_RESPONSE 0x801C022230222402235 #define END_DEVICE_BIND_REQUEST 0x002002236 #define END_DEVICE_BIND_RESPONSE 0x8020022370223802256 #define UNICAST_BINDING 0x0302257 #define UNICAST_MANY_TO_ONE_BINDING 0x8302258 #define MULTICAST_BINDING 0x010225902260 #define BIND_REQUEST 0x002102261 #define BIND_RESPONSE 0x802102262 #define UNBIND_REQUEST 0x002202263 #define UNBIND_RESPONSE 0x8022022640226502313 #define LQI_TABLE_REQUEST 0x003102314 #define LQI_TABLE_RESPONSE 0x8031023150231602349 #define ROUTING_TABLE_REQUEST 0x003202350 #define ROUTING_TABLE_RESPONSE 0x8032023510235202371 #define BINDING_TABLE_REQUEST 0x003302372 #define BINDING_TABLE_RESPONSE 0x8033023730237402385 #define LEAVE_REQUEST 0x003402386 #define LEAVE_RESPONSE 0x80340238702388 #define LEAVE_REQUEST_REMOVE_CHILDREN_FLAG 0x4002389 #define LEAVE_REQUEST_REJOIN_FLAG 0x80023900239102400 #define PERMIT_JOINING_REQUEST 0x003602401 #define PERMIT_JOINING_RESPONSE 0x8036024020240302429 #define NWK_UPDATE_REQUEST 0x003802430 #define NWK_UPDATE_RESPONSE 0x8038024310243202436 #define COMPLEX_DESCRIPTOR_REQUEST 0x001002437 #define COMPLEX_DESCRIPTOR_RESPONSE 0x801002438 #define USER_DESCRIPTOR_REQUEST 0x001102439 #define USER_DESCRIPTOR_RESPONSE 0x801102440 #define DISCOVERY_REGISTER_REQUEST 0x001202441 #define DISCOVERY_REGISTER_RESPONSE 0x801202442 #define USER_DESCRIPTOR_SET 0x001402443 #define USER_DESCRIPTOR_CONFIRM 0x801402444 #define NETWORK_DISCOVERY_REQUEST 0x003002445 #define NETWORK_DISCOVERY_RESPONSE 0x803002446 #define DIRECT_JOIN_REQUEST 0x003502447 #define DIRECT_JOIN_RESPONSE 0x80350244802449

EmberZNet 4.7.2 API EM260 120-3020-000-4720

379

02450 #define CLUSTER_ID_RESPONSE_MINIMUM 0x8000024510245202465 #ifdef DOXYGEN_SHOULD_SKIP_THIS02466 enum EmberZdoConfigurationFlags02467 #else02468 typedef int8u EmberZdoConfigurationFlags;02469 enum02470 #endif0247102472 {02473 EMBER_APP_RECEIVES_SUPPORTED_ZDO_REQUESTS

= 0x01,02474 EMBER_APP_HANDLES_UNSUPPORTED_ZDO_REQUESTS

= 0x02,02475 EMBER_APP_HANDLES_ZDO_ENDPOINT_REQUESTS

= 0x04,02476 EMBER_APP_HANDLES_ZDO_BINDING_REQUESTS

= 0x0802477 };024780248002481 #endif // EMBER_TYPES_H02482

8.57 error-def.h File Reference

Generic Messages

These messages are system wide.

• #define EMBER_SUCCESS(x00)• #define EMBER_ERR_FATAL(x01)• #define EMBER_BAD_ARGUMENT(x02)• #define EMBER_EEPROM_MFG_STACK_VERSION_MISMATCH(x04)• #define EMBER_INCOMPATIBLE_STATIC_MEMORY_DEFINITIONS(x05)• #define EMBER_EEPROM_MFG_VERSION_MISMATCH(x06)• #define EMBER_EEPROM_STACK_VERSION_MISMATCH(x07)

Packet Buffer Module Errors

• #define EMBER_NO_BUFFERS(x18)

Serial Manager Errors

• #define EMBER_SERIAL_INVALID_BAUD_RATE(x20)• #define EMBER_SERIAL_INVALID_PORT(x21)• #define EMBER_SERIAL_TX_OVERFLOW(x22)• #define EMBER_SERIAL_RX_OVERFLOW(x23)• #define EMBER_SERIAL_RX_FRAME_ERROR(x24)• #define EMBER_SERIAL_RX_PARITY_ERROR(x25)• #define EMBER_SERIAL_RX_EMPTY(x26)• #define EMBER_SERIAL_RX_OVERRUN_ERROR(x27)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

380

MAC Errors

• #define EMBER_MAC_TRANSMIT_QUEUE_FULL(x39)• #define EMBER_MAC_UNKNOWN_HEADER_TYPE(x3A)• #define EMBER_MAC_ACK_HEADER_TYPE(x3B)• #define EMBER_MAC_SCANNING(x3D)• #define EMBER_MAC_NO_DATA(x31)• #define EMBER_MAC_JOINED_NETWORK(x32)• #define EMBER_MAC_BAD_SCAN_DURATION(x33)• #define EMBER_MAC_INCORRECT_SCAN_TYPE(x34)• #define EMBER_MAC_INVALID_CHANNEL_MASK(x35)• #define EMBER_MAC_COMMAND_TRANSMIT_FAILURE(x36)• #define EMBER_MAC_NO_ACK_RECEIVED(x40)• #define EMBER_MAC_RADIO_NETWORK_SWITCH_FAILED(x41)• #define EMBER_MAC_INDIRECT_TIMEOUT(x42)

Simulated EEPROM Errors

• #define EMBER_SIM_EEPROM_ERASE_PAGE_GREEN(x43)• #define EMBER_SIM_EEPROM_ERASE_PAGE_RED(x44)• #define EMBER_SIM_EEPROM_FULL(x45)• #define EMBER_SIM_EEPROM_INIT_1_FAILED(x48)• #define EMBER_SIM_EEPROM_INIT_2_FAILED(x49)• #define EMBER_SIM_EEPROM_INIT_3_FAILED(x4A)• #define EMBER_SIM_EEPROM_REPAIRING(x4D)

Flash Errors

• #define EMBER_ERR_FLASH_WRITE_INHIBITED(x46)• #define EMBER_ERR_FLASH_VERIFY_FAILED(x47)• #define EMBER_ERR_FLASH_PROG_FAIL(x4B)• #define EMBER_ERR_FLASH_ERASE_FAIL(x4C)

Bootloader Errors

• #define EMBER_ERR_BOOTLOADER_TRAP_TABLE_BAD(x58)• #define EMBER_ERR_BOOTLOADER_TRAP_UNKNOWN(x59)• #define EMBER_ERR_BOOTLOADER_NO_IMAGE(x05A)

Transport Errors

• #define EMBER_DELIVERY_FAILED(x66)• #define EMBER_BINDING_INDEX_OUT_OF_RANGE(x69)• #define EMBER_ADDRESS_TABLE_INDEX_OUT_OF_RANGE(x6A)• #define EMBER_INVALID_BINDING_INDEX(x6C)• #define EMBER_INVALID_CALL(x70)• #define EMBER_COST_NOT_KNOWN(x71)• #define EMBER_MAX_MESSAGE_LIMIT_REACHED(x72)• #define EMBER_MESSAGE_TOO_LONG(x74)• #define EMBER_BINDING_IS_ACTIVE(x75)• #define EMBER_ADDRESS_TABLE_ENTRY_IS_ACTIVE(x76)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

381

HAL Module Errors

• #define EMBER_ADC_CONVERSION_DONE(x80)• #define EMBER_ADC_CONVERSION_BUSY(x81)• #define EMBER_ADC_CONVERSION_DEFERRED(x82)• #define EMBER_ADC_NO_CONVERSION_PENDING(x84)• #define EMBER_SLEEP_INTERRUPTED(x85)

PHY Errors

• #define EMBER_PHY_TX_UNDERFLOW(x88)• #define EMBER_PHY_TX_INCOMPLETE(x89)• #define EMBER_PHY_INVALID_CHANNEL(x8A)• #define EMBER_PHY_INVALID_POWER(x8B)• #define EMBER_PHY_TX_BUSY(x8C)• #define EMBER_PHY_TX_CCA_FAIL(x8D)• #define EMBER_PHY_OSCILLATOR_CHECK_FAILED(x8E)• #define EMBER_PHY_ACK_RECEIVED(x8F)

Return Codes Passed to emberStackStatusHandler()

See also ::emberStackStatusHandler().

• #define EMBER_NETWORK_UP(x90)• #define EMBER_NETWORK_DOWN(x91)• #define EMBER_JOIN_FAILED(x94)• #define EMBER_MOVE_FAILED(x96)• #define EMBER_CANNOT_JOIN_AS_ROUTER(x98)• #define EMBER_NODE_ID_CHANGED(x99)• #define EMBER_PAN_ID_CHANGED(x9A)• #define EMBER_CHANNEL_CHANGED(x9B)• #define EMBER_NO_BEACONS(xAB)• #define EMBER_RECEIVED_KEY_IN_THE_CLEAR(xAC)• #define EMBER_NO_NETWORK_KEY_RECEIVED(xAD)• #define EMBER_NO_LINK_KEY_RECEIVED(xAE)• #define EMBER_PRECONFIGURED_KEY_REQUIRED(xAF)

Security Errors

• #define EMBER_KEY_INVALID(xB2)• #define EMBER_INVALID_SECURITY_LEVEL(x95)• #define EMBER_APS_ENCRYPTION_ERROR(xA6)• #define EMBER_TRUST_CENTER_MASTER_KEY_NOT_SET(xA7)• #define EMBER_SECURITY_STATE_NOT_SET(xA8)• #define EMBER_KEY_TABLE_INVALID_ADDRESS(xB3)• #define EMBER_SECURITY_CONFIGURATION_INVALID(xB7)• #define EMBER_TOO_SOON_FOR_SWITCH_KEY(xB8)• #define EMBER_SIGNATURE_VERIFY_FAILURE(xB9)• #define EMBER_KEY_NOT_AUTHORIZED(xBB)• #define EMBER_SECURITY_DATA_INVALID(xBD)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

382

Miscellaneous Network Errors

• #define EMBER_NOT_JOINED(x93)• #define EMBER_NETWORK_BUSY(xA1)• #define EMBER_INVALID_ENDPOINT(xA3)• #define EMBER_BINDING_HAS_CHANGED(xA4)• #define EMBER_INSUFFICIENT_RANDOM_DATA(xA5)• #define EMBER_SOURCE_ROUTE_FAILURE(xA9)• #define EMBER_MANY_TO_ONE_ROUTE_FAILURE(xAA)

Miscellaneous Utility Errors

• #define EMBER_STACK_AND_HARDWARE_MISMATCH(xB0)• #define EMBER_INDEX_OUT_OF_RANGE(xB1)• #define EMBER_TABLE_FULL(xB4)• #define EMBER_TABLE_ENTRY_ERASED(xB6)• #define EMBER_LIBRARY_NOT_PRESENT(xB5)• #define EMBER_OPERATION_IN_PROGRESS(xBA)• #define EMBER_TRUST_CENTER_EUI_HAS_CHANGED(xBC)

Application Errors

These error codes are available for application use.

• #define EMBER_APPLICATION_ERROR_0(xF0)• #define EMBER_APPLICATION_ERROR_1(xF1)• #define EMBER_APPLICATION_ERROR_2(xF2)• #define EMBER_APPLICATION_ERROR_3(xF3)• #define EMBER_APPLICATION_ERROR_4(xF4)• #define EMBER_APPLICATION_ERROR_5(xF5)• #define EMBER_APPLICATION_ERROR_6(xF6)• #define EMBER_APPLICATION_ERROR_7(xF7)• #define EMBER_APPLICATION_ERROR_8(xF8)• #define EMBER_APPLICATION_ERROR_9(xF9)• #define EMBER_APPLICATION_ERROR_10(xFA)• #define EMBER_APPLICATION_ERROR_11(xFB)• #define EMBER_APPLICATION_ERROR_12(xFC)• #define EMBER_APPLICATION_ERROR_13(xFD)• #define EMBER_APPLICATION_ERROR_14(xFE)• #define EMBER_APPLICATION_ERROR_15(xFF)


Return-code definitions for EmberZNet stack API functions. See Ember Status Codes for documentation.

Definition in file error-def.h.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

383

8.58 error-def.h

000010003800039 #ifdef DOXYGEN_SHOULD_SKIP_THIS0004000043 #define EMBER_SUCCESS(0x00)00044 #else00045 DEFINE_ERROR(SUCCESS, 0)00046 #endif //DOXYGEN_SHOULD_SKIP_THIS000470004800049 #ifdef DOXYGEN_SHOULD_SKIP_THIS0005000053 #define EMBER_ERR_FATAL(0x01)00054 #else00055 DEFINE_ERROR(ERR_FATAL, 0x01)00056 #endif //DOXYGEN_SHOULD_SKIP_THIS000570005800059 #ifdef DOXYGEN_SHOULD_SKIP_THIS0006000063 #define EMBER_BAD_ARGUMENT(0x02)00064 #else00065 DEFINE_ERROR(BAD_ARGUMENT, 0x02)00066 #endif //DOXYGEN_SHOULD_SKIP_THIS000670006800069 #ifdef DOXYGEN_SHOULD_SKIP_THIS0007000074 #define EMBER_EEPROM_MFG_STACK_VERSION_MISMATCH(0x04)00075 #else00076 DEFINE_ERROR(EEPROM_MFG_STACK_VERSION_MISMATCH, 0x04)00077 #endif //DOXYGEN_SHOULD_SKIP_THIS000780007900080 #ifdef DOXYGEN_SHOULD_SKIP_THIS0008100085 #define EMBER_INCOMPATIBLE_STATIC_MEMORY_DEFINITIONS(0x05)00086 #else00087 DEFINE_ERROR(INCOMPATIBLE_STATIC_MEMORY_DEFINITIONS, 0x05)00088 #endif //DOXYGEN_SHOULD_SKIP_THIS000890009000091 #ifdef DOXYGEN_SHOULD_SKIP_THIS0009200096 #define EMBER_EEPROM_MFG_VERSION_MISMATCH(0x06)00097 #else00098 DEFINE_ERROR(EEPROM_MFG_VERSION_MISMATCH, 0x06)00099 #endif //DOXYGEN_SHOULD_SKIP_THIS001000010100102 #ifdef DOXYGEN_SHOULD_SKIP_THIS0010300107 #define EMBER_EEPROM_STACK_VERSION_MISMATCH(0x07)00108 #else00109 DEFINE_ERROR(EEPROM_STACK_VERSION_MISMATCH, 0x07)00110 #endif //DOXYGEN_SHOULD_SKIP_THIS0011100113001140011900120 #ifdef DOXYGEN_SHOULD_SKIP_THIS0012100124 #define EMBER_NO_BUFFERS(0x18)00125 #else00126 DEFINE_ERROR(NO_BUFFERS, 0x18)00127 #endif //DOXYGEN_SHOULD_SKIP_THIS00128001300013500136 #ifdef DOXYGEN_SHOULD_SKIP_THIS0013700140 #define EMBER_SERIAL_INVALID_BAUD_RATE(0x20)00141 #else00142 DEFINE_ERROR(SERIAL_INVALID_BAUD_RATE, 0x20)00143 #endif //DOXYGEN_SHOULD_SKIP_THIS0014400145

EmberZNet 4.7.2 API EM260 120-3020-000-4720

384

00146 #ifdef DOXYGEN_SHOULD_SKIP_THIS0014700150 #define EMBER_SERIAL_INVALID_PORT(0x21)00151 #else00152 DEFINE_ERROR(SERIAL_INVALID_PORT, 0x21)00153 #endif //DOXYGEN_SHOULD_SKIP_THIS001540015500156 #ifdef DOXYGEN_SHOULD_SKIP_THIS0015700160 #define EMBER_SERIAL_TX_OVERFLOW(0x22)00161 #else00162 DEFINE_ERROR(SERIAL_TX_OVERFLOW, 0x22)00163 #endif //DOXYGEN_SHOULD_SKIP_THIS001640016500166 #ifdef DOXYGEN_SHOULD_SKIP_THIS0016700171 #define EMBER_SERIAL_RX_OVERFLOW(0x23)00172 #else00173 DEFINE_ERROR(SERIAL_RX_OVERFLOW, 0x23)00174 #endif //DOXYGEN_SHOULD_SKIP_THIS001750017600177 #ifdef DOXYGEN_SHOULD_SKIP_THIS0017800181 #define EMBER_SERIAL_RX_FRAME_ERROR(0x24)00182 #else00183 DEFINE_ERROR(SERIAL_RX_FRAME_ERROR, 0x24)00184 #endif //DOXYGEN_SHOULD_SKIP_THIS001850018600187 #ifdef DOXYGEN_SHOULD_SKIP_THIS0018800191 #define EMBER_SERIAL_RX_PARITY_ERROR(0x25)00192 #else00193 DEFINE_ERROR(SERIAL_RX_PARITY_ERROR, 0x25)00194 #endif //DOXYGEN_SHOULD_SKIP_THIS001950019600197 #ifdef DOXYGEN_SHOULD_SKIP_THIS0019800201 #define EMBER_SERIAL_RX_EMPTY(0x26)00202 #else00203 DEFINE_ERROR(SERIAL_RX_EMPTY, 0x26)00204 #endif //DOXYGEN_SHOULD_SKIP_THIS002050020600207 #ifdef DOXYGEN_SHOULD_SKIP_THIS0020800212 #define EMBER_SERIAL_RX_OVERRUN_ERROR(0x27)00213 #else00214 DEFINE_ERROR(SERIAL_RX_OVERRUN_ERROR, 0x27)00215 #endif //DOXYGEN_SHOULD_SKIP_THIS00216002180022300224 #ifdef DOXYGEN_SHOULD_SKIP_THIS0022500228 #define EMBER_MAC_TRANSMIT_QUEUE_FULL(0x39)00229 #else00230 // Internal00231 DEFINE_ERROR(MAC_TRANSMIT_QUEUE_FULL, 0x39)00232 #endif //DOXYGEN_SHOULD_SKIP_THIS002330023400235 #ifdef DOXYGEN_SHOULD_SKIP_THIS0023600239 #define EMBER_MAC_UNKNOWN_HEADER_TYPE(0x3A)00240 #else00241 DEFINE_ERROR(MAC_UNKNOWN_HEADER_TYPE, 0x3A)00242 #endif //DOXYGEN_SHOULD_SKIP_THIS0024300244 #ifdef DOXYGEN_SHOULD_SKIP_THIS0024500248 #define EMBER_MAC_ACK_HEADER_TYPE(0x3B)00249 #else00250 DEFINE_ERROR(MAC_ACK_HEADER_TYPE, 0x3B)00251 #endif //DOXYGEN_SHOULD_SKIP_THIS00252

EmberZNet 4.7.2 API EM260 120-3020-000-4720

385

002530025400255 #ifdef DOXYGEN_SHOULD_SKIP_THIS0025600259 #define EMBER_MAC_SCANNING(0x3D)00260 #else00261 DEFINE_ERROR(MAC_SCANNING, 0x3D)00262 #endif //DOXYGEN_SHOULD_SKIP_THIS002630026400265 #ifdef DOXYGEN_SHOULD_SKIP_THIS0026600269 #define EMBER_MAC_NO_DATA(0x31)00270 #else00271 DEFINE_ERROR(MAC_NO_DATA, 0x31)00272 #endif //DOXYGEN_SHOULD_SKIP_THIS002730027400275 #ifdef DOXYGEN_SHOULD_SKIP_THIS0027600279 #define EMBER_MAC_JOINED_NETWORK(0x32)00280 #else00281 DEFINE_ERROR(MAC_JOINED_NETWORK, 0x32)00282 #endif //DOXYGEN_SHOULD_SKIP_THIS002830028400285 #ifdef DOXYGEN_SHOULD_SKIP_THIS0028600290 #define EMBER_MAC_BAD_SCAN_DURATION(0x33)00291 #else00292 DEFINE_ERROR(MAC_BAD_SCAN_DURATION, 0x33)00293 #endif //DOXYGEN_SHOULD_SKIP_THIS002940029500296 #ifdef DOXYGEN_SHOULD_SKIP_THIS0029700300 #define EMBER_MAC_INCORRECT_SCAN_TYPE(0x34)00301 #else00302 DEFINE_ERROR(MAC_INCORRECT_SCAN_TYPE, 0x34)00303 #endif //DOXYGEN_SHOULD_SKIP_THIS003040030500306 #ifdef DOXYGEN_SHOULD_SKIP_THIS0030700310 #define EMBER_MAC_INVALID_CHANNEL_MASK(0x35)00311 #else00312 DEFINE_ERROR(MAC_INVALID_CHANNEL_MASK, 0x35)00313 #endif //DOXYGEN_SHOULD_SKIP_THIS003140031500316 #ifdef DOXYGEN_SHOULD_SKIP_THIS0031700321 #define EMBER_MAC_COMMAND_TRANSMIT_FAILURE(0x36)00322 #else00323 DEFINE_ERROR(MAC_COMMAND_TRANSMIT_FAILURE, 0x36)00324 #endif //DOXYGEN_SHOULD_SKIP_THIS003250032600327 #ifdef DOXYGEN_SHOULD_SKIP_THIS0032800332 #define EMBER_MAC_NO_ACK_RECEIVED(0x40)00333 #else00334 DEFINE_ERROR(MAC_NO_ACK_RECEIVED, 0x40)00335 #endif //DOXYGEN_SHOULD_SKIP_THIS003360033700338 #ifdef DOXYGEN_SHOULD_SKIP_THIS0033900343 #define EMBER_MAC_RADIO_NETWORK_SWITCH_FAILED(0x41)00344 #else00345 DEFINE_ERROR(MAC_RADIO_NETWORK_SWITCH_FAILED, 0x41)00346 #endif //DOXYGEN_SHOULD_SKIP_THIS003470034800349 #ifdef DOXYGEN_SHOULD_SKIP_THIS0035000353 #define EMBER_MAC_INDIRECT_TIMEOUT(0x42)00354 #else00355 DEFINE_ERROR(MAC_INDIRECT_TIMEOUT, 0x42)00356 #endif //DOXYGEN_SHOULD_SKIP_THIS

EmberZNet 4.7.2 API EM260 120-3020-000-4720

386

003570035900360003650036600367 #ifdef DOXYGEN_SHOULD_SKIP_THIS0036800376 #define EMBER_SIM_EEPROM_ERASE_PAGE_GREEN(0x43)00377 #else00378 DEFINE_ERROR(SIM_EEPROM_ERASE_PAGE_GREEN, 0x43)00379 #endif //DOXYGEN_SHOULD_SKIP_THIS003800038100382 #ifdef DOXYGEN_SHOULD_SKIP_THIS0038300392 #define EMBER_SIM_EEPROM_ERASE_PAGE_RED(0x44)00393 #else00394 DEFINE_ERROR(SIM_EEPROM_ERASE_PAGE_RED, 0x44)00395 #endif //DOXYGEN_SHOULD_SKIP_THIS003960039700398 #ifdef DOXYGEN_SHOULD_SKIP_THIS0039900407 #define EMBER_SIM_EEPROM_FULL(0x45)00408 #else00409 DEFINE_ERROR(SIM_EEPROM_FULL, 0x45)00410 #endif //DOXYGEN_SHOULD_SKIP_THIS004110041200413 // Errors 46 and 47 are now defined below in the00414 // flash error block (was attempting to prevent renumbering)004150041600417 #ifdef DOXYGEN_SHOULD_SKIP_THIS0041800425 #define EMBER_SIM_EEPROM_INIT_1_FAILED(0x48)00426 #else00427 DEFINE_ERROR(SIM_EEPROM_INIT_1_FAILED, 0x48)00428 #endif //DOXYGEN_SHOULD_SKIP_THIS004290043000431 #ifdef DOXYGEN_SHOULD_SKIP_THIS0043200438 #define EMBER_SIM_EEPROM_INIT_2_FAILED(0x49)00439 #else00440 DEFINE_ERROR(SIM_EEPROM_INIT_2_FAILED, 0x49)00441 #endif //DOXYGEN_SHOULD_SKIP_THIS004420044300444 #ifdef DOXYGEN_SHOULD_SKIP_THIS0044500452 #define EMBER_SIM_EEPROM_INIT_3_FAILED(0x4A)00453 #else00454 DEFINE_ERROR(SIM_EEPROM_INIT_3_FAILED, 0x4A)00455 #endif //DOXYGEN_SHOULD_SKIP_THIS004560045700458 #ifdef DOXYGEN_SHOULD_SKIP_THIS0045900470 #define EMBER_SIM_EEPROM_REPAIRING(0x4D)00471 #else00472 DEFINE_ERROR(SIM_EEPROM_REPAIRING, 0x4D)00473 #endif //DOXYGEN_SHOULD_SKIP_THIS0047400476004770048200483 #ifdef DOXYGEN_SHOULD_SKIP_THIS0048400491 #define EMBER_ERR_FLASH_WRITE_INHIBITED(0x46)00492 #else00493 DEFINE_ERROR(ERR_FLASH_WRITE_INHIBITED, 0x46)00494 #endif //DOXYGEN_SHOULD_SKIP_THIS004950049600497 #ifdef DOXYGEN_SHOULD_SKIP_THIS0049800504 #define EMBER_ERR_FLASH_VERIFY_FAILED(0x47)00505 #else00506 DEFINE_ERROR(ERR_FLASH_VERIFY_FAILED, 0x47)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

387

00507 #endif //DOXYGEN_SHOULD_SKIP_THIS005080050900510 #ifdef DOXYGEN_SHOULD_SKIP_THIS0051100517 #define EMBER_ERR_FLASH_PROG_FAIL(0x4B)00518 #else00519 DEFINE_ERROR(ERR_FLASH_PROG_FAIL, 0x4B)00520 #endif //DOXYGEN_SHOULD_SKIP_THIS005210052200523 #ifdef DOXYGEN_SHOULD_SKIP_THIS0052400530 #define EMBER_ERR_FLASH_ERASE_FAIL(0x4C)00531 #else00532 DEFINE_ERROR(ERR_FLASH_ERASE_FAIL, 0x4C)00533 #endif //DOXYGEN_SHOULD_SKIP_THIS005340053600537005420054300544 #ifdef DOXYGEN_SHOULD_SKIP_THIS0054500549 #define EMBER_ERR_BOOTLOADER_TRAP_TABLE_BAD(0x58)00550 #else00551 DEFINE_ERROR(ERR_BOOTLOADER_TRAP_TABLE_BAD, 0x58)00552 #endif //DOXYGEN_SHOULD_SKIP_THIS005530055400555 #ifdef DOXYGEN_SHOULD_SKIP_THIS0055600560 #define EMBER_ERR_BOOTLOADER_TRAP_UNKNOWN(0x59)00561 #else00562 DEFINE_ERROR(ERR_BOOTLOADER_TRAP_UNKNOWN, 0x59)00563 #endif //DOXYGEN_SHOULD_SKIP_THIS005640056500566 #ifdef DOXYGEN_SHOULD_SKIP_THIS0056700571 #define EMBER_ERR_BOOTLOADER_NO_IMAGE(0x05A)00572 #else00573 DEFINE_ERROR(ERR_BOOTLOADER_NO_IMAGE, 0x5A)00574 #endif //DOXYGEN_SHOULD_SKIP_THIS0057500577005780058300584 #ifdef DOXYGEN_SHOULD_SKIP_THIS0058500589 #define EMBER_DELIVERY_FAILED(0x66)00590 #else00591 DEFINE_ERROR(DELIVERY_FAILED, 0x66)00592 #endif //DOXYGEN_SHOULD_SKIP_THIS005930059400595 #ifdef DOXYGEN_SHOULD_SKIP_THIS0059600599 #define EMBER_BINDING_INDEX_OUT_OF_RANGE(0x69)00600 #else00601 DEFINE_ERROR(BINDING_INDEX_OUT_OF_RANGE, 0x69)00602 #endif //DOXYGEN_SHOULD_SKIP_THIS006030060400605 #ifdef DOXYGEN_SHOULD_SKIP_THIS0060600610 #define EMBER_ADDRESS_TABLE_INDEX_OUT_OF_RANGE(0x6A)00611 #else00612 DEFINE_ERROR(ADDRESS_TABLE_INDEX_OUT_OF_RANGE, 0x6A)00613 #endif //DOXYGEN_SHOULD_SKIP_THIS006140061500616 #ifdef DOXYGEN_SHOULD_SKIP_THIS0061700620 #define EMBER_INVALID_BINDING_INDEX(0x6C)00621 #else00622 DEFINE_ERROR(INVALID_BINDING_INDEX, 0x6C)00623 #endif //DOXYGEN_SHOULD_SKIP_THIS0062400625

EmberZNet 4.7.2 API EM260 120-3020-000-4720

388

00626 #ifdef DOXYGEN_SHOULD_SKIP_THIS0062700631 #define EMBER_INVALID_CALL(0x70)00632 #else00633 DEFINE_ERROR(INVALID_CALL, 0x70)00634 #endif //DOXYGEN_SHOULD_SKIP_THIS006350063600637 #ifdef DOXYGEN_SHOULD_SKIP_THIS0063800641 #define EMBER_COST_NOT_KNOWN(0x71)00642 #else00643 DEFINE_ERROR(COST_NOT_KNOWN, 0x71)00644 #endif //DOXYGEN_SHOULD_SKIP_THIS006450064600647 #ifdef DOXYGEN_SHOULD_SKIP_THIS0064800652 #define EMBER_MAX_MESSAGE_LIMIT_REACHED(0x72)00653 #else00654 DEFINE_ERROR(MAX_MESSAGE_LIMIT_REACHED, 0x72)00655 #endif //DOXYGEN_SHOULD_SKIP_THIS0065600657 #ifdef DOXYGEN_SHOULD_SKIP_THIS0065800662 #define EMBER_MESSAGE_TOO_LONG(0x74)00663 #else00664 DEFINE_ERROR(MESSAGE_TOO_LONG, 0x74)00665 #endif //DOXYGEN_SHOULD_SKIP_THIS006660066700668 #ifdef DOXYGEN_SHOULD_SKIP_THIS0066900673 #define EMBER_BINDING_IS_ACTIVE(0x75)00674 #else00675 DEFINE_ERROR(BINDING_IS_ACTIVE, 0x75)00676 #endif //DOXYGEN_SHOULD_SKIP_THIS0067700678 #ifdef DOXYGEN_SHOULD_SKIP_THIS0067900683 #define EMBER_ADDRESS_TABLE_ENTRY_IS_ACTIVE(0x76)00684 #else00685 DEFINE_ERROR(ADDRESS_TABLE_ENTRY_IS_ACTIVE, 0x76)00686 #endif //DOXYGEN_SHOULD_SKIP_THIS0068700689006940069500696 #ifdef DOXYGEN_SHOULD_SKIP_THIS0069700700 #define EMBER_ADC_CONVERSION_DONE(0x80)00701 #else00702 DEFINE_ERROR(ADC_CONVERSION_DONE, 0x80)00703 #endif //DOXYGEN_SHOULD_SKIP_THIS007040070500706 #ifdef DOXYGEN_SHOULD_SKIP_THIS0070700711 #define EMBER_ADC_CONVERSION_BUSY(0x81)00712 #else00713 DEFINE_ERROR(ADC_CONVERSION_BUSY, 0x81)00714 #endif //DOXYGEN_SHOULD_SKIP_THIS007150071600717 #ifdef DOXYGEN_SHOULD_SKIP_THIS0071800722 #define EMBER_ADC_CONVERSION_DEFERRED(0x82)00723 #else00724 DEFINE_ERROR(ADC_CONVERSION_DEFERRED, 0x82)00725 #endif //DOXYGEN_SHOULD_SKIP_THIS007260072700728 #ifdef DOXYGEN_SHOULD_SKIP_THIS0072900732 #define EMBER_ADC_NO_CONVERSION_PENDING(0x84)00733 #else00734 DEFINE_ERROR(ADC_NO_CONVERSION_PENDING, 0x84)00735 #endif //DOXYGEN_SHOULD_SKIP_THIS0073600737

EmberZNet 4.7.2 API EM260 120-3020-000-4720

389

00738 #ifdef DOXYGEN_SHOULD_SKIP_THIS0073900743 #define EMBER_SLEEP_INTERRUPTED(0x85)00744 #else00745 DEFINE_ERROR(SLEEP_INTERRUPTED, 0x85)00746 #endif //DOXYGEN_SHOULD_SKIP_THIS0074700749007540075500756 #ifdef DOXYGEN_SHOULD_SKIP_THIS0075700760 #define EMBER_PHY_TX_UNDERFLOW(0x88)00761 #else00762 DEFINE_ERROR(PHY_TX_UNDERFLOW, 0x88)00763 #endif //DOXYGEN_SHOULD_SKIP_THIS007640076500766 #ifdef DOXYGEN_SHOULD_SKIP_THIS0076700770 #define EMBER_PHY_TX_INCOMPLETE(0x89)00771 #else00772 DEFINE_ERROR(PHY_TX_INCOMPLETE, 0x89)00773 #endif //DOXYGEN_SHOULD_SKIP_THIS007740077500776 #ifdef DOXYGEN_SHOULD_SKIP_THIS0077700780 #define EMBER_PHY_INVALID_CHANNEL(0x8A)00781 #else00782 DEFINE_ERROR(PHY_INVALID_CHANNEL, 0x8A)00783 #endif //DOXYGEN_SHOULD_SKIP_THIS007840078500786 #ifdef DOXYGEN_SHOULD_SKIP_THIS0078700790 #define EMBER_PHY_INVALID_POWER(0x8B)00791 #else00792 DEFINE_ERROR(PHY_INVALID_POWER, 0x8B)00793 #endif //DOXYGEN_SHOULD_SKIP_THIS007940079500796 #ifdef DOXYGEN_SHOULD_SKIP_THIS0079700801 #define EMBER_PHY_TX_BUSY(0x8C)00802 #else00803 DEFINE_ERROR(PHY_TX_BUSY, 0x8C)00804 #endif //DOXYGEN_SHOULD_SKIP_THIS008050080600807 #ifdef DOXYGEN_SHOULD_SKIP_THIS0080800812 #define EMBER_PHY_TX_CCA_FAIL(0x8D)00813 #else00814 DEFINE_ERROR(PHY_TX_CCA_FAIL, 0x8D)00815 #endif //DOXYGEN_SHOULD_SKIP_THIS008160081700818 #ifdef DOXYGEN_SHOULD_SKIP_THIS0081900823 #define EMBER_PHY_OSCILLATOR_CHECK_FAILED(0x8E)00824 #else00825 DEFINE_ERROR(PHY_OSCILLATOR_CHECK_FAILED, 0x8E)00826 #endif //DOXYGEN_SHOULD_SKIP_THIS008270082800829 #ifdef DOXYGEN_SHOULD_SKIP_THIS0083000833 #define EMBER_PHY_ACK_RECEIVED(0x8F)00834 #else00835 DEFINE_ERROR(PHY_ACK_RECEIVED, 0x8F)00836 #endif //DOXYGEN_SHOULD_SKIP_THIS0083700839008450084600847 #ifdef DOXYGEN_SHOULD_SKIP_THIS0084800852 #define EMBER_NETWORK_UP(0x90)00853 #else

EmberZNet 4.7.2 API EM260 120-3020-000-4720

390

00854 DEFINE_ERROR(NETWORK_UP, 0x90)00855 #endif //DOXYGEN_SHOULD_SKIP_THIS008560085700858 #ifdef DOXYGEN_SHOULD_SKIP_THIS0085900862 #define EMBER_NETWORK_DOWN(0x91)00863 #else00864 DEFINE_ERROR(NETWORK_DOWN, 0x91)00865 #endif //DOXYGEN_SHOULD_SKIP_THIS008660086700868 #ifdef DOXYGEN_SHOULD_SKIP_THIS0086900872 #define EMBER_JOIN_FAILED(0x94)00873 #else00874 DEFINE_ERROR(JOIN_FAILED, 0x94)00875 #endif //DOXYGEN_SHOULD_SKIP_THIS008760087700878 #ifdef DOXYGEN_SHOULD_SKIP_THIS0087900883 #define EMBER_MOVE_FAILED(0x96)00884 #else00885 DEFINE_ERROR(MOVE_FAILED, 0x96)00886 #endif //DOXYGEN_SHOULD_SKIP_THIS008870088800889 #ifdef DOXYGEN_SHOULD_SKIP_THIS0089000895 #define EMBER_CANNOT_JOIN_AS_ROUTER(0x98)00896 #else00897 DEFINE_ERROR(CANNOT_JOIN_AS_ROUTER, 0x98)00898 #endif //DOXYGEN_SHOULD_SKIP_THIS008990090000901 #ifdef DOXYGEN_SHOULD_SKIP_THIS0090200905 #define EMBER_NODE_ID_CHANGED(0x99)00906 #else00907 DEFINE_ERROR(NODE_ID_CHANGED, 0x99)00908 #endif009090091000911 #ifdef DOXYGEN_SHOULD_SKIP_THIS0091200915 #define EMBER_PAN_ID_CHANGED(0x9A)00916 #else00917 DEFINE_ERROR(PAN_ID_CHANGED, 0x9A)00918 #endif0091900920 #ifdef DOXYGEN_SHOULD_SKIP_THIS0092100923 #define EMBER_CHANNEL_CHANGED(0x9B)00924 #else00925 DEFINE_ERROR(CHANNEL_CHANGED, 0x9B)00926 #endif0092700928 #ifdef DOXYGEN_SHOULD_SKIP_THIS0092900932 #define EMBER_NO_BEACONS(0xAB)00933 #else00934 DEFINE_ERROR(NO_BEACONS, 0xAB)00935 #endif009360093700938 #ifdef DOXYGEN_SHOULD_SKIP_THIS0093900943 #define EMBER_RECEIVED_KEY_IN_THE_CLEAR(0xAC)00944 #else00945 DEFINE_ERROR(RECEIVED_KEY_IN_THE_CLEAR, 0xAC)00946 #endif009470094800949 #ifdef DOXYGEN_SHOULD_SKIP_THIS0095000953 #define EMBER_NO_NETWORK_KEY_RECEIVED(0xAD)00954 #else00955 DEFINE_ERROR(NO_NETWORK_KEY_RECEIVED, 0xAD)00956 #endif

EmberZNet 4.7.2 API EM260 120-3020-000-4720

391

009570095800959 #ifdef DOXYGEN_SHOULD_SKIP_THIS0096000963 #define EMBER_NO_LINK_KEY_RECEIVED(0xAE)00964 #else00965 DEFINE_ERROR(NO_LINK_KEY_RECEIVED, 0xAE)00966 #endif009670096800969 #ifdef DOXYGEN_SHOULD_SKIP_THIS0097000974 #define EMBER_PRECONFIGURED_KEY_REQUIRED(0xAF)00975 #else00976 DEFINE_ERROR(PRECONFIGURED_KEY_REQUIRED, 0xAF)00977 #endif00978009790098100985 #ifdef DOXYGEN_SHOULD_SKIP_THIS0098600990 #define EMBER_KEY_INVALID(0xB2)00991 #else00992 DEFINE_ERROR(KEY_INVALID, 0xB2)00993 #endif // DOXYGEN_SHOULD_SKIP_THIS0099400995 #ifdef DOXYGEN_SHOULD_SKIP_THIS0099601000 #define EMBER_INVALID_SECURITY_LEVEL(0x95)01001 #else01002 DEFINE_ERROR(INVALID_SECURITY_LEVEL, 0x95)01003 #endif //DOXYGEN_SHOULD_SKIP_THIS0100401005 #ifdef DOXYGEN_SHOULD_SKIP_THIS0100601014 #define EMBER_APS_ENCRYPTION_ERROR(0xA6)01015 #else01016 DEFINE_ERROR(APS_ENCRYPTION_ERROR, 0xA6)01017 #endif //DOXYGEN_SHOULD_SKIP_THIS0101801019 #ifdef DOXYGEN_SHOULD_SKIP_THIS0102001023 #define EMBER_TRUST_CENTER_MASTER_KEY_NOT_SET(0xA7)01024 #else01025 DEFINE_ERROR(TRUST_CENTER_MASTER_KEY_NOT_SET, 0xA7)01026 #endif //DOXYGEN_SHOULD_SKIP_THIS0102701028 #ifdef DOXYGEN_SHOULD_SKIP_THIS0102901032 #define EMBER_SECURITY_STATE_NOT_SET(0xA8)01033 #else01034 DEFINE_ERROR(SECURITY_STATE_NOT_SET, 0xA8)01035 #endif //DOXYGEN_SHOULD_SKIP_THIS0103601037 #ifdef DOXYGEN_SHOULD_SKIP_THIS0103801045 #define EMBER_KEY_TABLE_INVALID_ADDRESS(0xB3)01046 #else01047 DEFINE_ERROR(KEY_TABLE_INVALID_ADDRESS, 0xB3)01048 #endif //DOXYGEN_SHOULD_SKIP_THIS0104901050 #ifdef DOXYGEN_SHOULD_SKIP_THIS0105101054 #define EMBER_SECURITY_CONFIGURATION_INVALID(0xB7)01055 #else01056 DEFINE_ERROR(SECURITY_CONFIGURATION_INVALID, 0xB7)01057 #endif //DOXYGEN_SHOULD_SKIP_THIS0105801059 #ifdef DOXYGEN_SHOULD_SKIP_THIS0106001065 #define EMBER_TOO_SOON_FOR_SWITCH_KEY(0xB8)01066 #else01067 DEFINE_ERROR(TOO_SOON_FOR_SWITCH_KEY, 0xB8)01068 #endif0106901070 #ifdef DOXYGEN_SHOULD_SKIP_THIS0107101074 #define EMBER_SIGNATURE_VERIFY_FAILURE(0xB9)01075 #else01076 DEFINE_ERROR(SIGNATURE_VERIFY_FAILURE, 0xB9)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

392

01077 #endif0107801079 #ifdef DOXYGEN_SHOULD_SKIP_THIS0108001086 #define EMBER_KEY_NOT_AUTHORIZED(0xBB)01087 #else01088 DEFINE_ERROR(KEY_NOT_AUTHORIZED, 0xBB)01089 #endif010900109101092 #ifdef DOXYGEN_SHOULD_SKIP_THIS0109301096 #define EMBER_SECURITY_DATA_INVALID(0xBD)01097 #else01098 DEFINE_ERROR(SECURITY_DATA_INVALID, 0xBD)01099 #endif011000110201103011080110901110 #ifdef DOXYGEN_SHOULD_SKIP_THIS0111101114 #define EMBER_NOT_JOINED(0x93)01115 #else01116 DEFINE_ERROR(NOT_JOINED, 0x93)01117 #endif //DOXYGEN_SHOULD_SKIP_THIS0111801119 #ifdef DOXYGEN_SHOULD_SKIP_THIS0112001124 #define EMBER_NETWORK_BUSY(0xA1)01125 #else01126 DEFINE_ERROR(NETWORK_BUSY, 0xA1)01127 #endif //DOXYGEN_SHOULD_SKIP_THIS011280112901130 #ifdef DOXYGEN_SHOULD_SKIP_THIS0113101135 #define EMBER_INVALID_ENDPOINT(0xA3)01136 #else01137 DEFINE_ERROR(INVALID_ENDPOINT, 0xA3)01138 #endif //DOXYGEN_SHOULD_SKIP_THIS011390114001141 #ifdef DOXYGEN_SHOULD_SKIP_THIS0114201146 #define EMBER_BINDING_HAS_CHANGED(0xA4)01147 #else01148 DEFINE_ERROR(BINDING_HAS_CHANGED, 0xA4)01149 #endif //DOXYGEN_SHOULD_SKIP_THIS0115001151 #ifdef DOXYGEN_SHOULD_SKIP_THIS0115201156 #define EMBER_INSUFFICIENT_RANDOM_DATA(0xA5)01157 #else01158 DEFINE_ERROR(INSUFFICIENT_RANDOM_DATA, 0xA5)01159 #endif //DOXYGEN_SHOULD_SKIP_THIS011600116101162 #ifdef DOXYGEN_SHOULD_SKIP_THIS0116301166 #define EMBER_SOURCE_ROUTE_FAILURE(0xA9)01167 #else01168 DEFINE_ERROR(SOURCE_ROUTE_FAILURE, 0xA9)01169 #endif0117001171 #ifdef DOXYGEN_SHOULD_SKIP_THIS0117201177 #define EMBER_MANY_TO_ONE_ROUTE_FAILURE(0xAA)01178 #else01179 DEFINE_ERROR(MANY_TO_ONE_ROUTE_FAILURE, 0xAA)01180 #endif011810118201184011890119001191 #ifdef DOXYGEN_SHOULD_SKIP_THIS0119201198 #define EMBER_STACK_AND_HARDWARE_MISMATCH(0xB0)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

393

01199 #else01200 DEFINE_ERROR(STACK_AND_HARDWARE_MISMATCH, 0xB0)01201 #endif //DOXYGEN_SHOULD_SKIP_THIS012020120301204 #ifdef DOXYGEN_SHOULD_SKIP_THIS0120501209 #define EMBER_INDEX_OUT_OF_RANGE(0xB1)01210 #else01211 DEFINE_ERROR(INDEX_OUT_OF_RANGE, 0xB1)01212 #endif0121301214 #ifdef DOXYGEN_SHOULD_SKIP_THIS0121501218 #define EMBER_TABLE_FULL(0xB4)01219 #else01220 DEFINE_ERROR(TABLE_FULL, 0xB4)01221 #endif //DOXYGEN_SHOULD_SKIP_THIS0122201223 #ifdef DOXYGEN_SHOULD_SKIP_THIS0122401228 #define EMBER_TABLE_ENTRY_ERASED(0xB6)01229 #else01230 DEFINE_ERROR(TABLE_ENTRY_ERASED, 0xB6)01231 #endif0123201233 #ifdef DOXYGEN_SHOULD_SKIP_THIS0123401238 #define EMBER_LIBRARY_NOT_PRESENT(0xB5)01239 #else01240 DEFINE_ERROR(LIBRARY_NOT_PRESENT, 0xB5)01241 #endif0124201243 #ifdef DOXYGEN_SHOULD_SKIP_THIS0124401248 #define EMBER_OPERATION_IN_PROGRESS(0xBA)01249 #else01250 DEFINE_ERROR(OPERATION_IN_PROGRESS, 0xBA)01251 #endif0125201253 #ifdef DOXYGEN_SHOULD_SKIP_THIS0125401259 #define EMBER_TRUST_CENTER_EUI_HAS_CHANGED(0xBC)01260 #else01261 DEFINE_ERROR(TRUST_CENTER_EUI_HAS_CHANGED, 0xBC)01262 #endif01263012650127101272 #ifdef DOXYGEN_SHOULD_SKIP_THIS0127301277 #define EMBER_APPLICATION_ERROR_0(0xF0)01278 #define EMBER_APPLICATION_ERROR_1(0xF1)01279 #define EMBER_APPLICATION_ERROR_2(0xF2)01280 #define EMBER_APPLICATION_ERROR_3(0xF3)01281 #define EMBER_APPLICATION_ERROR_4(0xF4)01282 #define EMBER_APPLICATION_ERROR_5(0xF5)01283 #define EMBER_APPLICATION_ERROR_6(0xF6)01284 #define EMBER_APPLICATION_ERROR_7(0xF7)01285 #define EMBER_APPLICATION_ERROR_8(0xF8)01286 #define EMBER_APPLICATION_ERROR_9(0xF9)01287 #define EMBER_APPLICATION_ERROR_10(0xFA)01288 #define EMBER_APPLICATION_ERROR_11(0xFB)01289 #define EMBER_APPLICATION_ERROR_12(0xFC)01290 #define EMBER_APPLICATION_ERROR_13(0xFD)01291 #define EMBER_APPLICATION_ERROR_14(0xFE)01292 #define EMBER_APPLICATION_ERROR_15(0xFF)01293 #else01294 DEFINE_ERROR( APPLICATION_ERROR_0, 0xF0)01295 DEFINE_ERROR( APPLICATION_ERROR_1, 0xF1)01296 DEFINE_ERROR( APPLICATION_ERROR_2, 0xF2)01297 DEFINE_ERROR( APPLICATION_ERROR_3, 0xF3)01298 DEFINE_ERROR( APPLICATION_ERROR_4, 0xF4)01299 DEFINE_ERROR( APPLICATION_ERROR_5, 0xF5)01300 DEFINE_ERROR( APPLICATION_ERROR_6, 0xF6)01301 DEFINE_ERROR( APPLICATION_ERROR_7, 0xF7)01302 DEFINE_ERROR( APPLICATION_ERROR_8, 0xF8)01303 DEFINE_ERROR( APPLICATION_ERROR_9, 0xF9)01304 DEFINE_ERROR( APPLICATION_ERROR_10, 0xFA)01305 DEFINE_ERROR( APPLICATION_ERROR_11, 0xFB)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

394

01306 DEFINE_ERROR( APPLICATION_ERROR_12, 0xFC)01307 DEFINE_ERROR( APPLICATION_ERROR_13, 0xFD)01308 DEFINE_ERROR( APPLICATION_ERROR_14, 0xFE)01309 DEFINE_ERROR( APPLICATION_ERROR_15, 0xFF)01310 #endif //DOXYGEN_SHOULD_SKIP_THIS0131101313

8.59 error.h File Reference

Macros

• #define __EMBERSTATUS_TYPE__• #define DEFINE_ERROR(symbol, value)

Typedefs

• typedef int8u EmberStatus

Enumerations

• enum { EMBER_ERROR_CODE_COUNT }


Return codes for Ember API functions and module definitions. See Ember Status Codes for documentation.

Definition in file error.h.


8.59.2.1 #define EMBERSTATUS TYPE

Return type for Ember functions.



8.59.3.1 typedef int8u EmberStatus


8.60 error.h

0000100011 #ifndef __ERRORS_H__00012 #define __ERRORS_H__0001300017 #ifndef __EMBERSTATUS_TYPE__00018 #define __EMBERSTATUS_TYPE__

EmberZNet 4.7.2 API EM260 120-3020-000-4720

395

00019 typedef int8u EmberStatus;00020 #endif //__EMBERSTATUS_TYPE__0002100035 #define DEFINE_ERROR(symbol, value) \00036 EMBER_ ## symbol = value,000370003800039 enum {00040 #ifndef DOXYGEN_SHOULD_SKIP_THIS00041 #include "include/error-def.h"00042 #endif //DOXYGEN_SHOULD_SKIP_THIS0004300046 EMBER_ERROR_CODE_COUNT0004700048 };0004900050 #undef DEFINE_ERROR0005100052 #endif // __ERRORS_H__00053

8.61 ezsp-host-configuration-defaults.h File Reference

Macros

• #define EZSP_HOST_SOURCE_ROUTE_TABLE_SIZE• #define EZSP_HOST_ASH_RX_POOL_SIZE• #define EZSP_HOST_FORM_AND_JOIN_BUFFER_SIZE


User-configurable parameters for host applications. The default values set in this file can be overridden byputting #defines into the host application’s CONFIGURATION_HEADER.

See Configuration for documentation.

Definition in file ezsp-host-configuration-defaults.h.

8.62 ezsp-host-configuration-defaults.h

0000100019 #ifdef CONFIGURATION_HEADER00020 #include CONFIGURATION_HEADER00021 #endif0002200023 #ifndef EZSP_HOST_SOURCE_ROUTE_TABLE_SIZE0002400032 #define EZSP_HOST_SOURCE_ROUTE_TABLE_SIZE 3200033 #endif0003400035 #ifndef EZSP_HOST_ASH_RX_POOL_SIZE0003600043 #define EZSP_HOST_ASH_RX_POOL_SIZE 2000044 #endif0004500046 #ifndef EZSP_HOST_FORM_AND_JOIN_BUFFER_SIZE0004700055 #define EZSP_HOST_FORM_AND_JOIN_BUFFER_SIZE 4000056 #endif00057

EmberZNet 4.7.2 API EM260 120-3020-000-4720

396

8.63 form-and-join.h File Reference

Macros

• #define NETWORK_STORAGE_SIZE• #define NETWORK_STORAGE_SIZE_SHIFT• #define FORM_AND_JOIN_MAX_NETWORKS

Functions

• EmberStatus emberScanForUnusedPanId (int32u channelMask, int8u duration)• EmberStatus emberScanForJoinableNetwork (int32u channelMask, int8u ∗extendedPanId)• EmberStatus emberScanForNextJoinableNetwork (void)• boolean emberFormAndJoinIsScanning (void)• void emberUnusedPanIdFoundHandler (EmberPanId panId, int8u channel)• void emberJoinableNetworkFoundHandler (EmberZigbeeNetwork ∗networkFound, int8u lqi, int8s

rssi)• void emberScanErrorHandler (EmberStatus status)• boolean emberFormAndJoinScanCompleteHandler (int8u channel, EmberStatus status)• boolean emberFormAndJoinNetworkFoundHandler (EmberZigbeeNetwork ∗networkFound, int8u

lqi, int8s rssi)• boolean emberFormAndJoinEnergyScanResultHandler (int8u channel, int8s maxRssiValue)• void emberFormAndJoinTick (void)• void emberFormAndJoinTaskInit (void)• void emberFormAndJoinRunTask (void)• void emberFormAndJoinCleanup (EmberStatus status)

Variables

• boolean emberEnableDualChannelScan


Utilities for forming and joining networks. See Forming and Joining Networks for documentation.

Definition in file form-and-join.h.

8.64 form-and-join.h

0000100068 #define NETWORK_STORAGE_SIZE 160006900072 #define NETWORK_STORAGE_SIZE_SHIFT 40007300087 #ifndef FORM_AND_JOIN_MAX_NETWORKS00088 #ifdef EZSP_HOST00089 // the host’s buffer is 16-bit array, so translate to bytes for comparison00090 #define FORM_AND_JOIN_MAX_NETWORKS \00091 (EZSP_HOST_FORM_AND_JOIN_BUFFER_SIZE * 2 / NETWORK_STORAGE_SIZE)00092 #else00093 // use highest value that won’t exceed max EmberMessageBuffer length00094 #define FORM_AND_JOIN_MAX_NETWORKS 1500095 #endif00096 #endif

EmberZNet 4.7.2 API EM260 120-3020-000-4720

397

0009700098 // Check that this value isn’t too large for the SoC implementation to handle00099 #ifndef EZSP_HOST00100 #if (FORM_AND_JOIN_MAX_NETWORKS > 15)00101 #error "FORM_AND_JOIN_MAX_NETWORKS can’t exceed 15 on SoC platform"00102 #endif00103 #endif0010400121 EmberStatus emberScanForUnusedPanId(int32u

channelMask, int8u duration);0012200149 EmberStatus emberScanForJoinableNetwork(

int32u channelMask, int8u* extendedPanId);0015000152 EmberStatus emberScanForNextJoinableNetwork

(void);0015300169 extern boolean emberEnableDualChannelScan;0017000175 boolean emberFormAndJoinIsScanning(void);0017600177 //

------------------------------------------------------------------------------00178 // Callbacks the application needs to implement.0017900188 void emberUnusedPanIdFoundHandler(EmberPanId

panId, int8u channel);0018900200 void emberJoinableNetworkFoundHandler(

EmberZigbeeNetwork *networkFound,00201 int8u lqi,00202 int8s rssi);0020300221 void emberScanErrorHandler(EmberStatus status);0022200223 //

------------------------------------------------------------------------------00224 // Library functions the application must call from within the00225 // corresponding EmberZNet or EZSP callback.0022600234 boolean emberFormAndJoinScanCompleteHandler(

int8u channel, EmberStatus status);0023500243 boolean emberFormAndJoinNetworkFoundHandler(

EmberZigbeeNetwork *networkFound,00244 int8u lqi,00245 int8s rssi);0024600254 boolean emberFormAndJoinEnergyScanResultHandler

(int8u channel, int8s maxRssiValue);0025500260 void emberFormAndJoinTick(void);0026100265 void emberFormAndJoinTaskInit(void);0026600270 void emberFormAndJoinRunTask(void);0027100276 void emberFormAndJoinCleanup(EmberStatus

status);002770027800279

8.65 fragment-host.h File Reference

Initialization

• void ezspFragmentInit (int16u receiveBufferLength, int8u ∗receiveBuffer)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

398

Transmitting

• EmberStatus ezspFragmentSendUnicast (EmberOutgoingMessageType type, int16u indexOrDestination,EmberApsFrame ∗apsFrame, int8u maxFragmentSize, int16u messageLength, int8u ∗messageContents)

• EmberStatus ezspFragmentSourceRouteHandler (void)• boolean ezspFragmentMessageSent (EmberApsFrame ∗apsFrame, EmberStatus status)• void ezspFragmentMessageSentHandler (EmberStatus status)

Receiving

• boolean ezspFragmentIncomingMessage (EmberApsFrame ∗apsFrame, EmberNodeId sender, int16u∗messageLength, int8u ∗∗messageContents)

• void ezspFragmentTick (void)


Fragmented message support for EZSP Hosts. Splits long messages into smaller blocks for transmissionand reassembles received blocks. See Message Fragmentation for documentation.

Deprecated The fragment library is deprecated and will be removed in a future release. Similar function-ality is available in the Fragmentation plugin in Application Framework.

Definition in file fragment-host.h.

8.66 fragment-host.h

0000100059 void ezspFragmentInit(int16u receiveBufferLength, int8u

*receiveBuffer);0006000095 EmberStatus ezspFragmentSendUnicast(

EmberOutgoingMessageType type,00096 int16u indexOrDestination,00097 EmberApsFrame *apsFrame,00098 int8u maxFragmentSize,00099 int16u messageLength,00100 int8u *messageContents);0010100114 EmberStatus ezspFragmentSourceRouteHandler

(void);0011500130 boolean ezspFragmentMessageSent(EmberApsFrame

*apsFrame, EmberStatus status);0013100140 void ezspFragmentMessageSentHandler(EmberStatus

status);0014100173 boolean ezspFragmentIncomingMessage(EmberApsFrame

*apsFrame,00174 EmberNodeId sender,00175 int16u *messageLength,00176 int8u **messageContents);0017700182 void ezspFragmentTick(void);00183

EmberZNet 4.7.2 API EM260 120-3020-000-4720

399

8.67 hal.h File Reference

#include "micro/micro.h"#include "micro/adc.h"#include "micro/button.h"#include "micro/buzzer.h"#include "micro/crc.h"#include "micro/endian.h"#include "micro/led.h"#include "micro/random.h"#include "micro/serial.h"#include "micro/spi.h"#include "micro/system-timer.h"#include "micro/bootloader-eeprom.h"#include "micro/bootloader-interface.h"#include "micro/diagnostic.h"#include "micro/token.h"


Generic set of HAL includes for all platforms. See also Hardware Abstraction Layer (HAL) API Referencefor more documentation.

Some HAL includes are not used or present in builds intended for the Host processor connected to theEmber Network Coprocessor.

Definition in file hal.h.

8.68 hal.h

0000100063 #ifndef __HAL_H__00064 #define __HAL_H__0006500066 #ifdef HAL_HOST0006700068 #include "host/button-common.h"00069 #include "host/crc.h"00070 #include "host/led-common.h"00071 #include "host/micro-common.h"00072 #include "host/serial.h"00073 #include "host/system-timer.h"00074 #include "host/bootloader-eeprom.h"00075 //Pull in the micro specific ADC, buzzer, and clocks headers. The00076 //specific header is chosen by the build include path pointing at00077 //the appropriate directory.00078 #include "adc.h"00079 #include "buzzer.h"0008000081 #else //HAL_MICRO0008200083 // Keep micro and board first for specifics used by other headers00084 #include "micro/micro.h"00085 #if !defined(STACK) && defined(BOARD_HEADER)00086 #include BOARD_HEADER00087 #endif0008800089 #if (! defined(EMBER_STACK_IP))00090 // Pro Stack00091 #include "micro/adc.h"00092 #include "micro/button.h"

EmberZNet 4.7.2 API EM260 120-3020-000-4720

400

00093 #include "micro/buzzer.h"00094 #include "micro/crc.h"00095 #include "micro/endian.h"00096 #include "micro/led.h"00097 #include "micro/random.h"00098 #include "micro/serial.h"00099 #include "micro/spi.h"00100 #include "micro/system-timer.h"00101 #include "micro/bootloader-eeprom.h"0010200103 //Host processors do not use the following modules, therefore the header00104 //files should be ignored.00105 #ifndef EZSP_HOST00106 #include "micro/bootloader-interface.h"00107 #include "micro/diagnostic.h"00108 #include "micro/token.h"00109 //No public HAL code in release 4.0 uses the symbol timer,00110 //therefore it should not be in doxygen.00111 #ifndef DOXYGEN_SHOULD_SKIP_THIS00112 #include "micro/symbol-timer.h"00113 #endif // DOXYGEN_SHOULD_SKIP_THIS00114 #endif //EZSP_HOST0011500116 #else00117 // IP Stack00118 #include "micro/endian.h"00119 #include "micro/random.h"00120 #include "micro/serial.h"00121 #include "micro/system-timer.h"00122 //Host processors do not use the following modules, therefore the header00123 //files should be ignored.00124 #ifndef UNIX_HOST00125 #include "micro/adc.h"00126 #include "micro/button.h"00127 #include "micro/buzzer.h"00128 #include "micro/crc.h"00129 #include "micro/led.h"00130 #include "micro/spi.h"00131 #include "micro/bootloader-interface.h"00132 #include "micro/diagnostic.h"00133 #include "micro/token.h"00134 //No public HAL code in release 4.0 uses the symbol timer,00135 //therefore it should not be in doxygen.00136 #ifndef DOXYGEN_SHOULD_SKIP_THIS00137 #include "micro/symbol-timer.h"00138 #endif // DOXYGEN_SHOULD_SKIP_THIS00139 #endif //UNIX_HOST0014000141 #endif // !EMBER_STACK_IP0014200143 #endif0014400145 #endif //__HAL_H__00146

8.69 host.h File Reference

Macros

• #define halInternalInitBoard()• #define halInternalPowerDownBoard()• #define halInternalPowerUpBoard()• #define BUTTON0• #define BUTTON1• #define TEMP_SENSOR_ADC_CHANNEL• #define TEMP_SENSOR_SCALE_FACTOR

EmberZNet 4.7.2 API EM260 120-3020-000-4720

401

Enumerations



Sample API functions. See also Carrier Board Control.

Definition in file host.h.

8.70 host.h

0000100016 #define halInternalInitBoard() \00017 do { \00018 /*halInternalInitLed(); not currently simulated */ \00019 } while(0)0002000021 #define halInternalPowerDownBoard() \00022 do { \00023 /*halInternalInitLed(); not currently simulated */ \00024 } while(0)0002500026 #define halInternalPowerUpBoard() \00027 do { \00028 } while(0)0002900030 enum HalBoardLedPins {00031 BOARDLED0 = 0,00032 BOARDLED1 = 1,00033 BOARDLED2 = 2,00034 BOARDLED3 = 3,00035 BOARDLED4 = 4,00036 BOARDLED5 = 5,00037 BOARD_ACTIVITY_LED = BOARDLED0,00038 BOARD_HEARTBEAT_LED = BOARDLED100039 };0004000041 #define BUTTON0 000042 #define BUTTON1 100043 #define TEMP_SENSOR_ADC_CHANNEL 000044 #define TEMP_SENSOR_SCALE_FACTOR 300045

8.71 iar.h File Reference

#include "hal/micro/generic/compiler/platform-common.h"

Macros

• #define _HAL_USE_COMMON_MEMUTILS_• #define _HAL_USE_COMMON_DIVMOD_• #define PLATCOMMONOKTOINCLUDE

EmberZNet 4.7.2 API EM260 120-3020-000-4720

402

Master Variable Types

These are a set of typedefs to make the size of all variable declarations explicitly known.

• typedef unsigned char boolean• typedef unsigned char int8u• typedef signed char int8s• typedef unsigned int int16u• typedef signed int int16s• typedef unsigned long int32u• typedef signed long int32s• typedef unsigned int PointerType

Master Program Memory Declarations

These are a set of defines for simple declarations of program memory.

• #define PGM• #define PGM_P• #define PGM_PU• #define PGM_NO_CONST

Miscellaneous Macros

• #define MAIN_FUNCTION_PARAMETERS• #define MAIN_FUNCTION_ARGUMENTS• #define BIGENDIAN_CPU• #define NO_STRIPPING• #define EEPROM• #define __SOURCEFILE__• #define assert(condition)• #define __delay_cycles(x)• #define DEBUG_LEVEL• #define halResetWatchdog()• #define __attribute__(nothing)• #define UNUSED• #define SIGNED_ENUM• #define simulatedTimePasses()• #define simulatedTimePassesMs(x)• #define simulatedSerialTimePasses()• void halInternalAssertFailed (PGM_P filename, int linenumber)

Global Interrupt Manipulation Macros

• #define START_ATOMIC_CLOCK()• #define STOP_ATOMIC_CLOCK()• #define DECLARE_INTERRUPT_STATE• #define DECLARE_INTERRUPT_STATE_LITE• #define DISABLE_INTERRUPTS()

EmberZNet 4.7.2 API EM260 120-3020-000-4720

403

• #define DISABLE_INTERRUPTS_LITE()• #define RESTORE_INTERRUPTS()• #define RESTORE_INTERRUPTS_LITE()• #define INTERRUPTS_ON()• #define INTERRUPTS_OFF()• #define INTERRUPTS_WERE_ON()• #define INTERRUPTS_ARE_OFF()• #define ATOMIC(code)• #define ATOMIC_LITE(code)• #define HANDLE_PENDING_INTERRUPTS()


Compiler/platform-specific definitions and typedefs for the IAR AVR C compiler. See also CommonMicrocontroller Functions.

This file should be included first in all source files by setting the preprocessor macro PLATFORM_HEA-DER to point to it.

Definition in file iar.h.


8.71.2.1 #define PGM

Standard program memory delcaration.

Definition at line 67 of file iar.h.

8.71.2.2 #define PGM P

Char pointer to program memory declaration.


8.71.2.3 #define PGM PU

Unsigned char pointer to program memory declaration.


8.71.2.4 #define PGM NO CONST

Sometimes a second PGM is needed in a declaration. Having two ’const’ declarations generates a warningso we have a second PGM that turns into nothing under gcc.


8.71.2.5 #define MAIN FUNCTION PARAMETERS

Define the parameters to main(), and for those functions that are passed the arguments from main().


EmberZNet 4.7.2 API EM260 120-3020-000-4720

404

8.71.2.6 #define MAIN FUNCTION ARGUMENTS

Define the parameters to main(), and for those functions that are passed the arguments from main().


8.71.2.7 #define BIGENDIAN CPU

A convenient method for code to know what endiannes processor it is running on. For the AVR, we arelittle endian.


8.71.2.8 #define NO STRIPPING

A friendlier name for the compiler’s intrinsic for not stripping.


8.71.2.9 #define EEPROM

A friendlier name for the compiler’s intrinsic for eeprom reference.


8.71.2.10 #define SOURCEFILE

The SOURCEFILE macro is used by asserts to list the filename if it isn’t otherwise defined, set it to thecompiler intrinsic which specifies the whole filename and path of the sourcefile.


8.71.2.11 #define assert( condition )

A custom implementation of the C language assert macro. This macro implements the conditional evalua-tion and calls the function halInternalAssertFailed(). (see hal/micro/micro.h)


8.71.2.12 #define delay cycles( x )

__delay_cycles() is an intrinsic IAR WB call; however, we have explicity disallowed it since it is toospecific to the system clock.

Note

Please use halCommonDelayMicroseconds() instead, because it correctly accounts for various systemclock speeds.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

405

8.71.2.13 #define DEBUG LEVEL

Set debug level based on whether or the DEBUG is defined. For the AVR, no debugging support is includedif DEBUG is not defined.


8.71.2.14 #define halResetWatchdog( )

Macro to reset the watchdog timer. Note: be very very careful when using this as you can easily get intoan infinite loop if you are not careful.


8.71.2.15 #define attribute ( nothing )

Define attribute to nothing since it isn’t handled by IAR.


8.71.2.16 #define UNUSED

Declare a variable as unused to avoid a warning. Has no effect in IAR builds.


8.71.2.17 #define SIGNED ENUM

Some platforms need to cast enum values that have the high bit set.


8.71.2.18 #define simulatedTimePasses( )

Stub for code not running in simulation.


8.71.2.19 #define simulatedTimePassesMs( x )



8.71.2.20 #define simulatedSerialTimePasses( )



EmberZNet 4.7.2 API EM260 120-3020-000-4720

406

8.71.2.21 #define START ATOMIC CLOCK( )

This macro should be called in the local variable declarations section of any function which calls DISAB-LE_INTERRUPTS() or RESTORE_INTERRUPTS().


8.71.2.22 #define STOP ATOMIC CLOCK( )



8.71.2.23 #define DECLARE INTERRUPT STATE



8.71.2.24 #define DECLARE INTERRUPT STATE LITE



8.71.2.25 #define DISABLE INTERRUPTS( )

Disable interrupts, saving the previous state so it can be later restored with RESTORE_INTERRUPTS().

Note

Do not fail to call RESTORE_INTERRUPTS().It is safe to nest this call.Use the LITE version only if you are certain interrupts will not be disabled for long, and pair withRESTORE_INTERRUPTS_LITE().


8.71.2.26 #define DISABLE INTERRUPTS LITE( )



8.71.2.27 #define RESTORE INTERRUPTS( )

Restore the global interrupt state previously saved by DISABLE_INTERRUPTS()

EmberZNet 4.7.2 API EM260 120-3020-000-4720

407

Note

Do not call without having first called DISABLE_INTERRUPTS() to have saved the state.It is safe to nest this call.Use the LITE version only if you are certain interrupts will not be disabled very long, and pair withDISABLE_INTERRUPTS_LITE().


8.71.2.28 #define RESTORE INTERRUPTS LITE( )



8.71.2.29 #define INTERRUPTS ON( )

Enable global interrupts without regard to the current or previous state.


8.71.2.30 #define INTERRUPTS OFF( )

Disable global interrupts without regard to the current or previous state.


8.71.2.31 #define INTERRUPTS WERE ON( )

Returns

TRUE if global interrupt flag was enabled when DISABLE_INTERRUPTS() was called.


8.71.2.32 #define INTERRUPTS ARE OFF( )

Returns

TRUE if the current global interrupt flag is enabled.


8.71.2.33 #define ATOMIC( code )

A block of code may be made atomic by wrapping it with this macro. Something which is atomic cannotbe interrupted by interrupts.

Note

Use the LITE version only if you are certain interrupts will not be disabled very long.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

408

8.71.2.34 #define ATOMIC LITE( code )



8.71.2.35 #define HANDLE PENDING INTERRUPTS( )

Allows up to two pending interrupts to be executed. Usually this would be called at a safe point whileinterrupts are disabled (such as within an ISR).

Takes no action if interrupts are already enabled.

The implementation accounts for an AVR related oddity, wherein one instruction must be executed (a NOPin this instance) before global interrupts are allowed to occur.


8.71.2.36 #define HAL USE COMMON MEMUTILS


8.71.2.37 #define HAL USE COMMON DIVMOD


8.71.2.38 #define PLATCOMMONOKTOINCLUDE



8.71.3.1 typedef unsigned char boolean

A typedef to make the size of the variable explicitly known.


8.71.3.2 typedef unsigned char int8u



8.71.3.3 typedef signed char int8s



EmberZNet 4.7.2 API EM260 120-3020-000-4720

409

8.71.3.4 typedef unsigned int int16u



8.71.3.5 typedef signed int int16s



8.71.3.6 typedef unsigned long int32u



8.71.3.7 typedef signed long int32s



8.71.3.8 typedef unsigned int PointerType




8.71.4.1 void halInternalAssertFailed ( PGM_P filename, int linenumber )

A prototype definition for use by the assert macro. (see hal/micro/micro.h)

8.72 iar.h

0000100020 #ifndef __IAR_H__00021 #define __IAR_H__0002200023 #ifndef __ICCAVR__00024 #error Improper PLATFORM_HEADER00025 #endif000260002700028 #ifndef DOXYGEN_SHOULD_SKIP_THIS00029 #include <inavr.h>00030 #define ENABLE_BIT_DEFINITIONS00031 #include <ioavr.h>00032 #include <stdarg.h>00033 #endif // DOXYGEN_SHOULD_SKIP_THIS0003400035 // suppress warnings about unknown pragmas00036 // (as they may be pragmas known to other platforms)00037 #pragma diag_suppress = pe161

EmberZNet 4.7.2 API EM260 120-3020-000-4720

410

0003800047 typedef unsigned char boolean;00048 typedef unsigned char int8u;00049 typedef signed char int8s;00050 typedef unsigned int int16u;00051 typedef signed int int16s;00052 typedef unsigned long int32u;00053 typedef signed long int32s;00054 typedef unsigned int PointerType;000560005700058 // AVR uses custom PGM definitions00063 #if defined(__HAS_ELPM__) || defined(DOXYGEN_SHOULD_SKIP_THIS)0006400067 #define PGM __farflash0006800072 #define PGM_P const char __farflash *0007300077 #define PGM_PU const unsigned char __farflash *00078 #else00079 #define PGM __flash00080 #define PGM_P const char __flash *00081 #define PGM_PU const unsigned char __flash *00082 #endif000830008400090 #define PGM_NO_CONST PGM0009100092000930009500097000980009900104 #define MAIN_FUNCTION_PARAMETERS void00105 #define MAIN_FUNCTION_ARGUMENTS001060010700112 #define BIGENDIAN_CPU FALSE001130011400119 #define NO_STRIPPING __root001200012100126 #define EEPROM __eeprom001270012800129 #ifndef __SOURCEFILE__0013000135 #define __SOURCEFILE__ __FILE__00136 #endif001370013800139 #undef assert00140 #if !defined(SIMPLER_ASSERT_REBOOT) || defined(DOXYGEN_SHOULD_SKIP_THIS)0014100145 void halInternalAssertFailed(PGM_P filename, int

linenumber);0014600152 #define assert(condition) \00153 do { if (! (condition)) \00154 halInternalAssertFailed(__SOURCEFILE__, __LINE__); } while(0)00155 #else00156 #define assert(condition) \00157 do { if( !(condition) ) while(1){} } while(0)00158 #endif001590016000161 #ifndef BOOTLOADER00162 #undef __delay_cycles0016300169 #define __delay_cycles(x)

please_use_halCommonDelayMicroseconds_instead_of_delay_cycles00170 #endif0017100176 #ifndef DEBUG_LEVEL00177 #ifdef DEBUG00178 #define DEBUG_LEVEL FULL_DEBUG00179 #else00180 #define DEBUG_LEVEL NO_DEBUG

EmberZNet 4.7.2 API EM260 120-3020-000-4720

411

00181 #endif00182 #endif0018300189 #define halResetWatchdog() __watchdog_reset()001900019100195 #define __attribute__(nothing)001960019700202 #define UNUSED002030020400208 #define SIGNED_ENUM002090021000214 #define simulatedTimePasses()0021500218 #define simulatedTimePassesMs(x)0021900222 #define simulatedSerialTimePasses()002230022500226002270022800230002320023300234 #ifdef BOOTLOADER00235 #ifndef DOXYGEN_SHOULD_SKIP_THIS00236 // The bootloader does not use interrupts00237 #define DECLARE_INTERRUPT_STATE00238 #define DISABLE_INTERRUPTS() do { } while(0)00239 #define RESTORE_INTERRUPTS() do { } while(0)00240 #define INTERRUPTS_ON() do { } while(0)00241 #define INTERRUPTS_OFF() do { } while(0)00242 #define INTERRUPTS_ARE_OFF() (FALSE)00243 #define ATOMIC(blah) { blah }00244 #define ATOMIC_LITE(blah) { blah }00245 #define HANDLE_PENDING_INTERRUPTS() do { } while(0)00246 #endif // DOXYGEN_SHOULD_SKIP_THIS00247 #else // BOOTLOADER0024800249 #ifndef DOXYGEN_SHOULD_SKIP_THIS00250 // A series of macros for the diagnostics of the global interrupt state.00251 // These macros either enable or disable the debugging code in the00252 // Interrupt Manipulation Macros as well as define the two pins used for00253 // indicating the entry and exit of critical sections.0025400255 //UNCOMMENT the below #define to enable interrupt debugging.00256 //#define INTERRUPT_DEBUGGING00257 #ifdef INTERRUPT_DEBUGGING00258 #define INT_DEBUG(x) x00259 #else00260 #define INT_DEBUG(x)00261 #endif0026200263 #ifdef INTERRUPT_DEBUGGING00264 #define CLR_PORT_BIT(p, b) PORT##p &= ~BIT(b)00265 #define SET_PORT_BIT(p, b) PORT##p |= BIT(b)00266 #define BLIP_PORT_BIT(p, b) PORT##p |= BIT(b); PORT##p &= ~BIT(b)00267 #else00268 #define CLR_PORT_BIT(p, b)00269 #define SET_PORT_BIT(p, b)00270 #define BLIP_PORT_BIT(p, b)00271 #endif0027200273 // GPIO outputs for measuring the duration of global interrupt state and00274 // specific interrupt service routines. The comments below give the meaning00275 // of the output when it is HIGH.00276 // Pin assignments refer to the dev0222 board.00277 // LED 2 (PORTC.2): interrupts are disabled (includes ATOMIC blocks)00278 // LED 3 (PORTC.3): radio receive isr00279 // LED 4 (PORTC.4): radio transmit isr (symbol timer compare)00280 // LED 5 (PORTC.5): an isr other than radio, uart or system timer00281 // GPIO 0 (PORTG.0): uart 1 receive isr00282 // GPIO 1 (PORTG.1): uart 1 transmit isr00283 // GPIO 2 (PORTG.2): general purpose time marker00284 // GPIO 3 (PORTE.2): system/sleep timer isr00285 // GPIO 5 (PORTE.7): uart 1 receive isr error

EmberZNet 4.7.2 API EM260 120-3020-000-4720

412

00286 #define INT_DEBUG_INTS_OFF() SET_PORT_BIT(C, 2)00287 #define INT_DEBUG_INTS_ON() CLR_PORT_BIT(C, 2)00288 #define INT_DEBUG_BEG_RADIO_RX() INT_DEBUG_INTS_OFF(); SET_PORT_BIT(C,

3)00289 #define INT_DEBUG_END_RADIO_RX() CLR_PORT_BIT(C, 3); INT_DEBUG_INTS_ON()00290 #define INT_DEBUG_BEG_SYMBOL_CMP() INT_DEBUG_INTS_OFF(); SET_PORT_BIT(C,4)00291 #define INT_DEBUG_END_SYMBOL_CMP() CLR_PORT_BIT(C,4); INT_DEBUG_INTS_ON()00292 #define INT_DEBUG_BEG_MISC_INT() INT_DEBUG_INTS_OFF(); SET_PORT_BIT(C,

5)00293 #define INT_DEBUG_END_MISC_INT() CLR_PORT_BIT(C, 5); INT_DEBUG_INTS_ON()00294 #define INT_DEBUG_BEG_UART1_RX() INT_DEBUG_INTS_OFF(); SET_PORT_BIT(G,

0)00295 #define INT_DEBUG_END_UART1_RX() CLR_PORT_BIT(G, 0); INT_DEBUG_INTS_ON()00296 #define INT_DEBUG_BEG_UART1_TX() INT_DEBUG_INTS_OFF(); SET_PORT_BIT(G,

1)00297 #define INT_DEBUG_END_UART1_TX() CLR_PORT_BIT(G, 1); INT_DEBUG_INTS_ON()00298 #define INT_DEBUG_TIME_MARKER(n) BLIP_PORT_BIT(G, 2)00299 #define INT_DEBUG_BEG_SYSTIME_CMP() INT_DEBUG_INTS_OFF(); SET_PORT_BIT(E,

2)00300 #define INT_DEBUG_END_SYSTIME_CMP() CLR_PORT_BIT(E, 2); INT_DEBUG_INTS_ON()00301 #define INT_DEBUG_BEG_UART1_RXERR() SET_PORT_BIT(E, 7)00302 #define INT_DEBUG_END_UART1_RXERR() CLR_PORT_BIT(E, 7)00303003040030500306 //UNCOMMENT the below #define to enable timing diabled interrupt blocks,00307 // except for "LITE" blocks that are never timed.00308 //#define ENABLE_ATOMIC_CLOCK0030900310 #endif // DOXYGEN_SHOULD_SKIP_THIS0031100312 //The core Global Interrupt Manipulation Macros start here.0031300314 #ifdef ENABLE_ATOMIC_CLOCK00315 #define START_ATOMIC_CLOCK() \00316 do { \00317 if (INTERRUPTS_WERE_ON()) \00318 halStartAtomicClock(); \00319 } \00320 while(0)00321 #define STOP_ATOMIC_CLOCK() \00322 do { \00323 if (INTERRUPTS_WERE_ON()) \00324 halStopAtomicClock(); \00325 } \00326 while(0)00327 #else00328 #define START_ATOMIC_CLOCK()00329 #define STOP_ATOMIC_CLOCK()00330 #endif0033100337 #define DECLARE_INTERRUPT_STATE int8u _emIsrState00338 #define DECLARE_INTERRUPT_STATE_LITE int8u _emIsrState003390034000349 #define DISABLE_INTERRUPTS() \00350 _emIsrState = __save_interrupt(); \00351 do { \00352 INT_DEBUG_INTS_OFF(); \00353 __disable_interrupt(); \00354 START_ATOMIC_CLOCK(); \00355 } while(0)0035600357 #define DISABLE_INTERRUPTS_LITE() \00358 _emIsrState = __save_interrupt(); \00359 do { \00360 INT_DEBUG_INTS_OFF(); \00361 __disable_interrupt(); \00362 } while(0)003630036400374 #define RESTORE_INTERRUPTS() \00375 do { \00376 STOP_ATOMIC_CLOCK(); \00377 INT_DEBUG( \00378 if (INTERRUPTS_WERE_ON()) \00379 INT_DEBUG_INTS_ON(); \00380 ) \00381 __restore_interrupt(_emIsrState); \00382 } while(0)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

413

0038300384 #define RESTORE_INTERRUPTS_LITE() \00385 do { \00386 INT_DEBUG( \00387 if (INTERRUPTS_WERE_ON()) \00388 INT_DEBUG_INTS_ON(); \00389 ) \00390 __restore_interrupt(_emIsrState); \00391 } while(0)003920039300398 #define INTERRUPTS_ON() \00399 do { \00400 INT_DEBUG_INTS_ON(); \00401 __enable_interrupt(); \00402 } while(0)004030040400409 #define INTERRUPTS_OFF() \00410 do { \00411 __disable_interrupt(); \00412 INT_DEBUG_INTS_OFF(); \00413 } while(0)004140041500420 #define INTERRUPTS_WERE_ON() (_emIsrState & BIT(7))004210042200426 #define INTERRUPTS_ARE_OFF() (!(__save_interrupt() & BIT(7)))004270042800436 #define ATOMIC(code) \00437 { \00438 DECLARE_INTERRUPT_STATE; \00439 DISABLE_INTERRUPTS(); \00440 { code } \00441 RESTORE_INTERRUPTS(); \00442 }0044300444 #define ATOMIC_LITE(code) \00445 { \00446 DECLARE_INTERRUPT_STATE_LITE; \00447 DISABLE_INTERRUPTS_LITE(); \00448 { code } \00449 RESTORE_INTERRUPTS_LITE(); \00450 }004510045200464 #define HANDLE_PENDING_INTERRUPTS() \00465 do { \00466 if (INTERRUPTS_ARE_OFF()) { \00467 INTERRUPTS_ON(); \00468 __no_operation(); \00469 __no_operation(); \00470 __no_operation(); \00471 INTERRUPTS_OFF(); \00472 } \00473 } while (0)004740047500476 #endif // BOOTLOADER0047700478004790048000481 #define _HAL_USE_COMMON_MEMUTILS_00482 #define _HAL_USE_COMMON_DIVMOD_0048300484 // Include platform-common last to pick up defaults and common definitions00485 #define PLATCOMMONOKTOINCLUDE00486 #include "hal/micro/generic/compiler/platform-common.h"00487 #undef PLATCOMMONOKTOINCLUDE0048800489 #endif // __IAR_H__

8.73 led.h File Reference

EmberZNet 4.7.2 API EM260 120-3020-000-4720

414

Typedefs

• typedef enum HalBoardLedPins HalBoardLed

Functions

• void halInternalInitLed (void)• void halToggleLed (HalBoardLed led)• void halSetLed (HalBoardLed led)• void halClearLed (HalBoardLed led)• void halStackIndicateActivity (boolean turnOn)


See LED Control for documentation.

Definition in file led.h.

8.74 led.h

0000100022 void halInternalInitLed(void);0002300027 #if defined(STACK) || defined(MINIMAL_HAL)00028 typedef int8u HalBoardLed;00029 #else00030 typedef enum HalBoardLedPins HalBoardLed;00031 #endif00032 // Note: Even though many compilers will use 16 bits for an enum instead of 8,00033 // we choose to use an enum here. The possible compiler inefficiency does not

00034 // affect stack-based parameters and local variables, which is the00035 // general case for led paramters.0003600042 void halToggleLed(HalBoardLed led);0004300049 void halSetLed(HalBoardLed led);0005000056 void halClearLed(HalBoardLed led);0005700067 void halStackIndicateActivity(boolean turnOn);00068

8.75 linux-serial.h File Reference

Macros

• #define SERIAL_PORT_RAW• #define SERIAL_PORT_CLI

Functions

• void emberSerialSetPrompt (const char ∗thePrompt)• void emberSerialCleanup (void)• int emberSerialGetInputFd (int8u port)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

415

• void emberSerialCommandCompletionInit (EmberCommandEntry ∗listOfCommands)• void emberSerialCommandCompletionInitCli (cliSerialCmdEntry ∗cliCmdList, int cliCmdListLength)


Ember serial functionality specific to a PC with Unix library support. See Serial Communication fordocumentation.

Definition in file linux-serial.h.

8.76 linux-serial.h

0000100014 // The normal CLI is accessible via port 0 while port 1 is usable for00015 // raw input. This is often used by applications to receive a 26000016 // image for bootloading.00017 #define SERIAL_PORT_RAW 000018 #define SERIAL_PORT_CLI 10001900020 void emberSerialSetPrompt(const char* thePrompt);00021 void emberSerialCleanup(void);00022 int emberSerialGetInputFd(int8u port);0002300024 // For users of app/util/serial/command-interpreter.h00025 void emberSerialCommandCompletionInit(

EmberCommandEntry* listOfCommands);0002600027 #if !defined(EMBER_AF_PLUGIN_GATEWAY)00028 // For users of app/util/serial/cli.h00029 void emberSerialCommandCompletionInitCli(

cliSerialCmdEntry* cliCmdList,00030 int cliCmdListLength);00031 #endif00032

8.77 micro.h File Reference

#include "hal/micro/generic/em2xx-reset-defs.h"

Macros

• #define halGetEm2xxResetInfo()

Functions

• void halStackProcessBootCount (void)• int8u halGetResetInfo (void)• PGM_P halGetResetString (void)• void halInternalAssertFailed (PGM_P filename, int linenumber)


Full HAL functions common across all microcontroller-specific files. See Common Microcontroller Func-tions for documentation. Some functions in this file return an EmberStatus value. See error-def.h for

EmberZNet 4.7.2 API EM260 120-3020-000-4720

416

definitions of all EmberStatus return values.

Definition in file micro.h.

8.78 micro.h

0000100020 #ifndef __MICRO_H__00021 #define __MICRO_H__0002200023 #include "hal/micro/generic/em2xx-reset-defs.h"0002400025 #ifndef DOXYGEN_SHOULD_SKIP_THIS0002600027 #if ((! defined(EZSP_HOST)) && (! defined(UNIX_HOST)))00028 // If we are not a Host processor, Define distinct literal values for00029 // each platform and micro. The Host processor is not tied to a00030 // specific platform or micro since it uses EZSP. These values are00031 // used in ebl headers and the bootloader query response message.00032 // Some values may reserved for future use.0003300034 // PLAT 1 was the AVR ATMega, no longer supported00035 // for PLAT 1, MICRO 1 is the AVR ATMega 6400036 // for PLAT 1, MICRO 2 is the AVR ATMega 12800037 // for PLAT 1, MICRO 3 is the AVR ATMega 320003800039 // PLAT 2 is the XAP2b00040 // for PLAT 2, MICRO 1 is the em25000041 // for PLAT 2, MICRO 2 is the em2600004200043 // PLAT 4 is the Cortex-M300044 // for PLAT 4, MICRO 1 is the em35000045 // for PLAT 4, MICRO 2 is the em36000046 // for PLAT 4, MICRO 3 is the em35700047 // for PLAT 4, MICRO 4 is the em36700048 // for PLAT 4, MICRO 5 is the em35100049 // for PLAT 4, MICRO 6 is the em35x00050 // for PLAT 4, MICRO 7 is the stm32w1080005100052 #if defined( EMBER_TEST )00053 #define PLAT 100054 #define MICRO 200055 #elif defined (AVR_ATMEGA)00056 #define PLAT 100057 #if defined (AVR_ATMEGA_64)00058 #define MICRO 100059 #elif defined (AVR_ATMEGA_128)00060 #define MICRO 200061 #elif defined (AVR_ATMEGA_32)00062 #define MICRO 300063 #endif00064 #elif defined (XAP2B)00065 #define PLAT 200066 #if defined (XAP2B_EM250)00067 #define MICRO 100068 #elif defined (XAP2B_EM260)00069 #define MICRO 200070 #endif00071 #elif defined (MSP430)00072 #define PLAT 300073 #if defined (MSP430_1612)00074 #define MICRO 100075 #elif defined (MSP430_1471)00076 #define MICRO 200077 #endif00078 #elif defined (CORTEXM3)00079 #define PLAT 400080 #if defined (CORTEXM3_EM350)00081 #define MICRO 100082 #elif defined (CORTEXM3_EM360)00083 #define MICRO 200084 #elif defined (CORTEXM3_EM357)00085 #define MICRO 300086 #elif defined (CORTEXM3_EM367)00087 #define MICRO 400088 #elif defined (CORTEXM3_EM351)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

417

00089 #define MICRO 500090 #elif defined (CORTEXM3_EM35X)00091 #define MICRO 600092 #elif defined (CORTEXM3_STM32W108)00093 #define MICRO 700094 #endif00095 #else00096 #error no platform defined, or unsupported00097 #endif0009800099 #ifndef MICRO00100 #error no micro defined, or unsupported00101 #endif0010200103 #endif // ((! defined(EZSP_HOST)) && (! defined(UNIX_HOST)))0010400105 // Define distinct literal values for each phy.00106 // These values are used in the bootloader query response message.00107 // PHY 0 is a null phy00108 // PHY 1 is the em2420 (no longer supported)00109 // PHY 2 is the em25000110 // PHY 3 is the em3xx0011100112 #if defined (PHY_EM2420) || defined (PHY_EM2420B)00113 #error EM2420 is no longer supported.00114 #elif defined (PHY_EM250) || defined (PHY_EM250B)00115 #define PHY 200116 #elif defined (PHY_EM3XX)00117 #define PHY 300118 #elif defined (PHY_NULL)00119 #define PHY 000120 #else00121 #error no phy defined, or unsupported00122 #endif0012300124 #endif // DOXYGEN_SHOULD_SKIP_THIS0012500139 void halStackProcessBootCount(void);0014000145 int8u halGetResetInfo(void);0014600154 PGM_P halGetResetString(void);0015500164 #ifdef CORTEXM300165 int8u halGetEm2xxResetInfo(void);00166 #else00167 #define halGetEm2xxResetInfo() halGetResetInfo()00168 #endif001690017000180 void halInternalAssertFailed(PGM_P filename, int

linenumber);001810018200183 #ifndef DOXYGEN_SHOULD_SKIP_THIS0018400185 #include "micro-common.h"0018600187 #if defined( EMBER_TEST )00188 #include "hal/micro/unix/simulation/micro.h"00189 #include "hal/micro/unix/simulation/bootloader.h"00190 #elif defined(AVR_ATMEGA)00191 #if defined(AVR_ATMEGA_64) || defined(AVR_ATMEGA_128)00192 #include "avr-atmega/128/micro.h"00193 #include "avr-atmega/128/bootloader.h"00194 #elif defined(AVR_ATMEGA_32)00195 #include "avr-atmega/32/micro.h"00196 #else00197 // default, assume 12800198 #include "avr-atmega/128/micro.h"00199 #include "avr-atmega/128/bootloader.h"00200 #endif00201 #elif defined(MSP430_1612)00202 #include "msp430/1612/micro.h"00203 #include "msp430/1612/bootloader.h"00204 #elif defined(MSP430_1471)00205 #include "msp430/1471/micro.h"00206 #include "msp430/1471/bootloader.h"00207 #elif defined(XAP2B)00208 #include "xap2b/em250/micro.h"

EmberZNet 4.7.2 API EM260 120-3020-000-4720

418

00209 #elif defined(CORTEXM3)00210 #include "cortexm3/micro.h"00211 #elif ((defined(EZSP_HOST) || defined(UNIX_HOST)))00212 #include "hal/micro/unix/host/micro.h"00213 #else00214 #error no platform or micro defined00215 #endif0021600217 // the number of ticks (as returned from halCommonGetInt32uMillisecondTick)00218 // that represent an actual second. This can vary on different platforms.00219 // It must be defined by the host system.00220 #ifndef MILLISECOND_TICKS_PER_SECOND00221 #define MILLISECOND_TICKS_PER_SECOND 1024UL00222 // See bug 1023200223 // #error "MILLISECOND_TICKS_PER_SECOND is not defined in micro.h!"00224 #endif0022500226 #endif // DOXYGEN_SHOULD_SKIP_THIS0022700228 #endif //__MICRO_H__00229


Macros

• #define MILLISECOND_TICKS_PER_SECOND• #define RESET_UNKNOWN• #define RESET_EXTERNAL• #define RESET_POWERON• #define RESET_WATCHDOG• #define RESET_BROWNOUT• #define RESET_JTAG• #define RESET_ASSERT• #define RESET_RSTACK• #define RESET_CSTACK• #define RESET_BOOTLOADER• #define RESET_PC_ROLLOVER• #define RESET_SOFTWARE• #define RESET_PROTFAULT• #define RESET_FLASH_VERIFY_FAIL• #define RESET_FLASH_WRITE_INHIBIT• #define RESET_BOOTLOADER_IMG_BAD

Functions

• void halStackTriggerDebugTimeSyncCapture (void)


Utility and convenience functions for ATmega32 microcontroller See Common Microcontroller Functionsfor documentation.

Definition in file avr-atmega/32/micro.h.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

419

8.80 avr-atmega/32/micro.h

0000100014 #ifndef __32_MICRO_H__00015 #define __32_MICRO_H__0001600017 #ifndef DOXYGEN_SHOULD_SKIP_THIS0001800019 #ifndef __MICRO_H__00020 #error do not include this file directly - include micro/micro.h00021 #endif0002200023 #include "micro/avr-atmega/32/reserved-ram.h"0002400026 // Serial definitions00027 #define EM_NUM_SERIAL_PORTS 10002800029 #endif // DOXYGEN_SHOULD_SKIP_THIS000300003100036 void halStackTriggerDebugTimeSyncCapture(

void);000370003800039 #ifndef DOXYGEN_SHOULD_SKIP_THIS00040 #define ADCSR ADCSRA00041 #define EICRA MCUCR00042 #define EICRB MCUCSR00043 #define EIMSK GICR00044 #define EIFR GIFR00045 #define WDCE WDTOE00046 #endif // DOXYGEN_SHOULD_SKIP_THIS0004700048 // the number of ticks (as returned from halCommonGetInt32uMillisecondTick)00049 // that represent an actual second. This can vary on different platforms.00050 #define MILLISECOND_TICKS_PER_SECOND 900UL0005100056 #define RESET_UNKNOWN 0 // cause not known00057 #define RESET_EXTERNAL 1 // reset pin was asserted00058 #define RESET_POWERON 2 // supply voltage was < power-on

threshold00059 #define RESET_WATCHDOG 3 // watchdog low water mark caused NMI00060 #define RESET_BROWNOUT 4 // n/a (no hardware support)00061 #define RESET_JTAG 5 // reset by debugger00062 #define RESET_ASSERT 6 // a self-check within the code failed00063 #define RESET_RSTACK 7 // n/a (memory fault instead)00064 #define RESET_CSTACK 8 // n/a (memory fault instead)00065 #define RESET_BOOTLOADER 9 // requested by bootloader00066 #define RESET_PC_ROLLOVER 10 // n/a (memor fault instead)00067 #define RESET_SOFTWARE 11 // reset requested by software00068 #define RESET_PROTFAULT 12 // n/a (memoru fault instead)00069 #define RESET_FLASH_VERIFY_FAIL 13 // flash write verify failure00070 #define RESET_FLASH_WRITE_INHIBIT 14 // flash write inhibited: already written00071 #define RESET_BOOTLOADER_IMG_BAD 15 // app BTL: bad EEPROM upgrade image0007200073 #endif //__32_MICRO_H__00074


Macros

• #define MILLISECOND_TICKS_PER_SECOND• #define RESET_UNKNOWN• #define RESET_EXTERNAL• #define RESET_POWERON• #define RESET_WATCHDOG• #define RESET_BROWNOUT• #define RESET_JTAG

EmberZNet 4.7.2 API EM260 120-3020-000-4720

420

• #define RESET_ASSERT• #define RESET_RSTACK• #define RESET_CSTACK• #define RESET_BOOTLOADER• #define RESET_PC_ROLLOVER• #define RESET_SOFTWARE• #define RESET_PROTFAULT• #define RESET_FLASH_VERIFY_FAIL• #define RESET_FLASH_WRITE_INHIBIT• #define RESET_BOOTLOADER_IMG_BAD

Functions

• void halStackTriggerDebugTimeSyncCapture (void)


Utility and convenience functions for ATmega128 microcontroller. See also Common MicrocontrollerFunctions.

Unless otherwise noted, the EmberNet stack does not use these functions, and therefore the HAL is notrequired to implement them. However, many of the supplied example applications do use them.

Note

These HAL files/functions are also used for the ATmega64 microcontroller since the only differencebetween the ATmega128 and ATmega64 is the size of the flash.

Definition in file avr-atmega/128/micro.h.


8.81.2.1 #define MILLISECOND TICKS PER SECOND


8.81.2.2 #define RESET UNKNOWN

Defines conditions representing possible reasons for a reset.


8.81.2.3 #define RESET EXTERNAL


8.81.2.4 #define RESET POWERON


EmberZNet 4.7.2 API EM260 120-3020-000-4720

421

8.81.2.5 #define RESET WATCHDOG


8.81.2.6 #define RESET BROWNOUT


8.81.2.7 #define RESET JTAG


8.81.2.8 #define RESET ASSERT


8.81.2.9 #define RESET RSTACK


8.81.2.10 #define RESET CSTACK


8.81.2.11 #define RESET BOOTLOADER


8.81.2.12 #define RESET PC ROLLOVER


8.81.2.13 #define RESET SOFTWARE


8.81.2.14 #define RESET PROTFAULT


8.81.2.15 #define RESET FLASH VERIFY FAIL


EmberZNet 4.7.2 API EM260 120-3020-000-4720

422

8.81.2.16 #define RESET FLASH WRITE INHIBIT


8.81.2.17 #define RESET BOOTLOADER IMG BAD



8.81.3.1 void halStackTriggerDebugTimeSyncCapture ( void )

Used by the debug stack to trigger the backchannel timer capture circuitry.

8.82 avr-atmega/128/micro.h

0000100024 #ifndef __128_MICRO_H__00025 #define __128_MICRO_H__0002600027 #ifndef DOXYGEN_SHOULD_SKIP_THIS0002800029 #ifndef __MICRO_H__00030 #error do not include this file directly - include micro/micro.h00031 #endif0003200033 #include "micro/avr-atmega/128/reserved-ram.h

"0003400036 // Serial definitions0003700038 // Debug builds use 3 serial ports, one of which is a "virtual" port since the00039 // physical port is actually used for the debug channel itself00040 #if defined(DEBUG) && !defined(STACK)00041 #define EM_NUM_SERIAL_PORTS 300042 // Configures a specified serial port to operate in debug mode00043 #ifdef EMBER_SERIAL2_DEBUG00044 #error serial 2 not valid as a debug port00045 #endif00046 #if (!(defined(EMBER_SERIAL0_DEBUG))) && \00047 (!(defined(EMBER_SERIAL1_DEBUG)))00048 #error No valid EMBER_SERIALn_DEBUG definition present00049 #endif00050 #ifdef EMBER_SERIAL0_DEBUG00051 #define EMBER_SERIAL2_MODE EMBER_SERIAL_BUFFER00052 #define EMBER_SERIAL2_TX_QUEUE_SIZE 1600053 #define EMBER_SERIAL2_RX_QUEUE_SIZE 32 // TBD, what is minimum size?00054 #endif00055 #ifdef EMBER_SERIAL1_DEBUG00056 #define EMBER_SERIAL2_MODE EMBER_SERIAL_BUFFER00057 #define EMBER_SERIAL2_TX_QUEUE_SIZE 1600058 #define EMBER_SERIAL2_RX_QUEUE_SIZE 32 // TBD, what is minimum size?00059 #endif00060 #else00061 #define EM_NUM_SERIAL_PORTS 200062 #endif0006300064 #endif // DOXYGEN_SHOULD_SKIP_THIS000650006600071 void halStackTriggerDebugTimeSyncCapture(

void);000720007300074 #ifndef DOXYGEN_SHOULD_SKIP_THIS0007500076 // note: you must actually reserve the ram in low-level-init.c and00077 // all the linker scripts. this just defines the addresses

EmberZNet 4.7.2 API EM260 120-3020-000-4720

423

00078 //#define NORMAL_RAM_END 0x10E00007900080 // ATMega128 / 64 differences0008100082 #ifdef AVR_ATMEGA_6400083 #define ADCSR ADCSRA // For ATMEGA64, it is called ADCSRA00084 #endif0008500086 #endif // DOXYGEN_SHOULD_SKIP_THIS0008700088 // the number of ticks (as returned from halCommonGetInt32uMillisecondTick)00089 // that represent an actual second. This can vary on different platforms.00090 #define MILLISECOND_TICKS_PER_SECOND 1024UL0009100096 #define RESET_UNKNOWN 0 // cause not known00097 #define RESET_EXTERNAL 1 // reset pin was asserted00098 #define RESET_POWERON 2 // supply voltage was < power-on

threshold00099 #define RESET_WATCHDOG 3 // watchdog low water mark caused NMI00100 #define RESET_BROWNOUT 4 // n/a (no hardware support)00101 #define RESET_JTAG 5 // reset by debugger00102 #define RESET_ASSERT 6 // a self-check within the code failed00103 #define RESET_RSTACK 7 // n/a (memory fault instead)00104 #define RESET_CSTACK 8 // n/a (memory fault instead)00105 #define RESET_BOOTLOADER 9 // requested by bootloader00106 #define RESET_PC_ROLLOVER 10 // n/a (memor fault instead)00107 #define RESET_SOFTWARE 11 // reset requested by software00108 #define RESET_PROTFAULT 12 // n/a (memoru fault instead)00109 #define RESET_FLASH_VERIFY_FAIL 13 // flash write verify failure00110 #define RESET_FLASH_WRITE_INHIBIT 14 // flash write inhibited: already written00111 #define RESET_BOOTLOADER_IMG_BAD 15 // app BTL: bad EEPROM upgrade image0011200113 #endif //__128_MICRO_H__

8.83 network-manager.h File Reference

#include <CONFIGURATION_HEADER>

Macros

• #define NM_WARNING_LIMIT• #define NM_WINDOW_SIZE• #define NM_CHANNEL_MASK• #define NM_WATCHLIST_SIZE

Functions

• void nmUtilWarningHandler (void)• boolean nmUtilProcessIncoming (EmberApsFrame ∗apsFrame, int8u messageLength, int8u ∗message)• EmberStatus nmUtilChangeChannelRequest (void)


Utilities for use by the ZigBee network manager. See Network Manager for documentation.

Definition in file network-manager.h.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

424

8.84 network-manager.h

0000100090 #include CONFIGURATION_HEADER0009100092 // The application is notified via nmUtilWarningHandler00093 // if NM_WARNING_LIMIT unsolicited scan reports are received00094 // within NM_WINDOW_SIZE minutes. To save flash and RAM,00095 // the actual timing is approximate.00096 #ifndef NM_WARNING_LIMIT00097 #define NM_WARNING_LIMIT 1600098 #endif0009900100 #ifndef NM_WINDOW_SIZE00101 #define NM_WINDOW_SIZE 400102 #endif0010300104 // The channels that should be used by the network manager.0010500106 #ifndef NM_CHANNEL_MASK00107 #define NM_CHANNEL_MASK EMBER_ALL_802_15_4_CHANNELS_MASK00108 #endif0010900110 // The number of channels used in the NM_CHANNEL_MASK.0011100112 #ifndef NM_WATCHLIST_SIZE00113 #define NM_WATCHLIST_SIZE 1600114 #endif0011500122 void nmUtilWarningHandler(void);0012300132 boolean nmUtilProcessIncoming(EmberApsFrame *

apsFrame,00133 int8u messageLength,00134 int8u* message);0013500139 EmberStatus nmUtilChangeChannelRequest(

void);00140

8.85 random.h File Reference

Functions

• void halStackSeedRandom (int32u seed)• int16u halCommonGetRandom (void)


See Random Number Generation for detailed documentation.

Definition in file random.h.

8.86 random.h

0000100016 #ifndef __RANDOM_H__00017 #define __RANDOM_H__0001800026 void halStackSeedRandom(int32u seed);0002700036 #if defined( EMBER_TEST )00037 #define halCommonGetRandom() halCommonGetRandomTraced(__FILE__, __LINE__)00038 int16u halCommonGetRandomTraced(char *file, int line);00039 #else00040 int16u halCommonGetRandom(void);

EmberZNet 4.7.2 API EM260 120-3020-000-4720

425

00041 #endif0004200046 #endif //__RANDOM_H__0004700048

8.87 reserved-ram.h File Reference

Macros

• #define SRAM_BASE• #define SRAM_END

Reserved RAM Definitions

These are reserved addresses for storing simple data for exchange between applications.

• #define HAL_RESERVED_RAM_PC_DIAG• #define HAL_RESERVED_RAM_RESET_CAUSE• #define HAL_RESERVED_RAM_RESET_CAUSE_B• #define HAL_RESERVED_RAM_RSTACK_H• #define HAL_RESERVED_RAM_RSTACK_L• #define HAL_RESERVED_RAM_CSTACK_H• #define HAL_RESERVED_RAM_CSTACK_L

Reset Cause Definitions

These are markers of possible reset causes.

• #define RESET_CAUSE_SELF_WDOG• #define RESET_CAUSE_ASSERT_BIT• #define RESET_CAUSE_CSTACK_BIT• #define RESET_CAUSE_RSTACK_BIT• #define RESET_CAUSE_BOOTLOADER_BIT• #define RESET_CAUSE_SOFTWARE_BIT


Memory allocations that allow for data sharing between the normally running application and bootloader.See also Common Microcontroller Functions.

By establishing a common memory "segment" we allow data exchange between applications. for examplethe sample applications and the bootloader share id information for over the air bootloading.

This is done by specifying hard coded ram addresses for key data, and a block or "segment" of ram whichwill not be erased by either application when they boot.

There is a potential here for backwards compatilbity issues, since older applications are likely to "reserve"less ram, this is why it’s a good idea to reserve slightly more room than needed. although, assuming you’reonly applications are "some app" and the bootloader, and it’s only the bootloader that falls behind, and thatit never even approaches the ram use limit - maybe not such an issue.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

426

The actual ram reserved block is specified in the linker scripts.

Definition in file 32/reserved-ram.h.


8.87.2.1 #define HAL RESERVED RAM PC DIAG

A reserved address for storing simple data for exchange between applications.

Definition at line 43 of file 32/reserved-ram.h.

8.87.2.2 #define HAL RESERVED RAM RESET CAUSE



8.87.2.3 #define HAL RESERVED RAM RESET CAUSE B



8.87.2.4 #define HAL RESERVED RAM RSTACK H



8.87.2.5 #define HAL RESERVED RAM RSTACK L



8.87.2.6 #define HAL RESERVED RAM CSTACK H



8.87.2.7 #define HAL RESERVED RAM CSTACK L



8.87.2.8 #define RESET CAUSE SELF WDOG

A marker of a possible reset cause.


EmberZNet 4.7.2 API EM260 120-3020-000-4720

427

8.87.2.9 #define RESET CAUSE ASSERT BIT



8.87.2.10 #define RESET CAUSE CSTACK BIT



8.87.2.11 #define RESET CAUSE RSTACK BIT



8.87.2.12 #define RESET CAUSE BOOTLOADER BIT



8.87.2.13 #define RESET CAUSE SOFTWARE BIT



8.87.2.14 #define SRAM BASE

The start of RAM memory.

There isn’t currently an easy way to share this between the linker scripts and the C code directly (since theyaren’t really segments). With that said... This must match the value in the linker scripts.


8.87.2.15 #define SRAM END

The end of normal RAM memory.



8.88 32/reserved-ram.h

0000100043 #define HAL_RESERVED_RAM_PC_DIAG 0x085E00044 #define HAL_RESERVED_RAM_RESET_CAUSE 0x085D00045 #define HAL_RESERVED_RAM_RESET_CAUSE_B 0x085C

EmberZNet 4.7.2 API EM260 120-3020-000-4720

428

00046 #define HAL_RESERVED_RAM_RSTACK_H 0x085B00047 #define HAL_RESERVED_RAM_RSTACK_L 0x085A00048 #define HAL_RESERVED_RAM_CSTACK_H 0x085900049 #define HAL_RESERVED_RAM_CSTACK_L 0x0858000500005100059 #define RESET_CAUSE_SELF_WDOG 000060 #define RESET_CAUSE_ASSERT_BIT 100061 #define RESET_CAUSE_CSTACK_BIT 200062 #define RESET_CAUSE_RSTACK_BIT 300063 #define RESET_CAUSE_BOOTLOADER_BIT 400064 #define RESET_CAUSE_SOFTWARE_BIT 500065000660006700075 #define SRAM_BASE 0x0060 // Start of ram memory000760007700085 #define SRAM_END 0x0857 // End of normal ram memory (~2k + SFR offset

- reserved ram)000860008700088 #ifndef DOXYGEN_SHOULD_SKIP_THIS00089 #ifndef __IAR_SYSTEMS_ASM__00090 extern __no_init __root volatile int8u emResetCause;00091 extern __no_init __root volatile int8u emResetCauseMarker;00092 extern __no_init __root volatile int16u emResetRStack;00093 extern __no_init __root volatile int16u emResetCStack;00094 #endif00095 #endif //DOXYGEN_SHOULD_SKIP_THIS

8.89 reserved-ram.h File Reference

Macros

• #define SRAM_BASE• #define SRAM_END• #define EXT_SRAM_END

Reserved RAM Definitions

These are reserved addresses for storing simple data for exchange between applications.

• #define HAL_RESERVED_RAM_BOOTLOADER_KEY• #define HAL_RESERVED_RAM_PC_DIAG• #define HAL_RESERVED_RAM_GATEWAY_ID• #define HAL_RESERVED_RAM_EUI64_ID• #define HAL_RESERVED_RAM_PAN_ID• #define HAL_RESERVED_RAM_NODE_ID• #define HAL_RESERVED_RAM_CHANNEL• #define HAL_RESERVED_RAM_POWER• #define HAL_RESERVED_RAM_BANDS• #define HAL_RESERVED_RAM_MODE• #define HAL_RESERVED_RAM_RESET_CAUSE• #define HAL_RESERVED_RAM_RESET_CAUSE_B• #define HAL_RESERVED_RAM_RSTACK_H• #define HAL_RESERVED_RAM_RSTACK_L• #define HAL_RESERVED_RAM_CSTACK_H• #define HAL_RESERVED_RAM_CSTACK_L

EmberZNet 4.7.2 API EM260 120-3020-000-4720

429

Reset Cause Definitions

These are markers of possible reset causes.

• #define RESET_CAUSE_SELF_WDOG• #define RESET_CAUSE_ASSERT_BIT• #define RESET_CAUSE_CSTACK_BIT• #define RESET_CAUSE_RSTACK_BIT• #define RESET_CAUSE_BOOTLOADER_BIT• #define RESET_CAUSE_SOFTWARE_BIT


Memory allocations that allow for data sharing between the normally running application and bootloader.See also Common Microcontroller Functions.

By establishing a common memory "segment" we allow data exchange between applications. for examplethe sample applications and the bootloader share id information for over the air bootloading.

This is done by specifying hard coded ram addresses for key data, and a block or "segment" of ram whichwill not be erased by either application when they boot.

There is a potential here for backwards compatilbity issues, since older applications are likely to "reserve"less ram, this is why it’s a good idea to reserve slightly more room than needed. although, assuming you’reonly applications are "some app" and the bootloader, and it’s only the bootloader that falls behind, and thatit never even approaches the ram use limit - maybe not such an issue.

The actual ram reserved block is specified in the linker scripts.

Definition in file 128/reserved-ram.h.


8.89.2.1 #define HAL RESERVED RAM BOOTLOADER KEY

Description:



8.89.2.2 #define HAL RESERVED RAM PC DIAG

Description:



8.89.2.3 #define HAL RESERVED RAM GATEWAY ID

Description:


EmberZNet 4.7.2 API EM260 120-3020-000-4720

430


8.89.2.4 #define HAL RESERVED RAM EUI64 ID

Description:



8.89.2.5 #define HAL RESERVED RAM PAN ID

Description:



8.89.2.6 #define HAL RESERVED RAM NODE ID

Description:



8.89.2.7 #define HAL RESERVED RAM CHANNEL

Description:



8.89.2.8 #define HAL RESERVED RAM POWER

Description:



8.89.2.9 #define HAL RESERVED RAM BANDS

Description:



EmberZNet 4.7.2 API EM260 120-3020-000-4720

431

8.89.2.10 #define HAL RESERVED RAM MODE

Description:



8.89.2.11 #define HAL RESERVED RAM RESET CAUSE

Description:



8.89.2.12 #define HAL RESERVED RAM RESET CAUSE B

Description:



8.89.2.13 #define HAL RESERVED RAM RSTACK H

Description:



8.89.2.14 #define HAL RESERVED RAM RSTACK L

Description:



8.89.2.15 #define HAL RESERVED RAM CSTACK H

Description:



8.89.2.16 #define HAL RESERVED RAM CSTACK L

Description:



EmberZNet 4.7.2 API EM260 120-3020-000-4720

432

8.89.2.17 #define RESET CAUSE SELF WDOG

Description:



8.89.2.18 #define RESET CAUSE ASSERT BIT

Description:



8.89.2.19 #define RESET CAUSE CSTACK BIT

Description:



8.89.2.20 #define RESET CAUSE RSTACK BIT

Description:



8.89.2.21 #define RESET CAUSE BOOTLOADER BIT

Description:



8.89.2.22 #define RESET CAUSE SOFTWARE BIT

Description:



EmberZNet 4.7.2 API EM260 120-3020-000-4720

433

8.89.2.23 #define SRAM BASE

Description:

The start of RAM memory.



8.89.2.24 #define SRAM END

Description:

The end of normal RAM memory.



8.89.2.25 #define EXT SRAM END

Description:

The end of external RAM memory.



8.90 128/reserved-ram.h

0000100043 #define HAL_RESERVED_RAM_BOOTLOADER_KEY 0x10FE00044 #define HAL_RESERVED_RAM_PC_DIAG 0x10FC00045 #define HAL_RESERVED_RAM_GATEWAY_ID 0x10F400046 #define HAL_RESERVED_RAM_EUI64_ID 0x10EC00047 #define HAL_RESERVED_RAM_PAN_ID 0x10EA00048 #define HAL_RESERVED_RAM_NODE_ID 0x10E800049 #define HAL_RESERVED_RAM_CHANNEL 0x10E700050 #define HAL_RESERVED_RAM_POWER 0x10E600051 #define HAL_RESERVED_RAM_BANDS 0x10E500052 #define HAL_RESERVED_RAM_MODE 0x10E400053 #define HAL_RESERVED_RAM_RESET_CAUSE 0x10E300054 #define HAL_RESERVED_RAM_RESET_CAUSE_B 0x10E200055 #define HAL_RESERVED_RAM_RSTACK_H 0x10E100056 #define HAL_RESERVED_RAM_RSTACK_L 0x10E000057 #define HAL_RESERVED_RAM_CSTACK_H 0x10DF00058 #define HAL_RESERVED_RAM_CSTACK_L 0x10DE000590006000068 #define RESET_CAUSE_SELF_WDOG 000069 #define RESET_CAUSE_ASSERT_BIT 100070 #define RESET_CAUSE_CSTACK_BIT 200071 #define RESET_CAUSE_RSTACK_BIT 300072 #define RESET_CAUSE_BOOTLOADER_BIT 400073 #define RESET_CAUSE_SOFTWARE_BIT 5000740007500076

EmberZNet 4.7.2 API EM260 120-3020-000-4720

434

00084 #define SRAM_BASE 0x0100 // Start of ram memory000850008600094 #define SRAM_END 0x10DD // End of normal ram memory (~4k + SFR offset

- reserved ram)000950009600104 #define EXT_SRAM_END 0x7FFF // Largest possible external sram chip (32k)

001050010600107 #ifndef DOXYGEN_SHOULD_SKIP_THIS00108 #ifndef __IAR_SYSTEMS_ASM__00109 extern __no_init __root volatile int8u emResetCause;00110 extern __no_init __root volatile int8u emResetCauseMarker;00111 extern __no_init __root volatile int16u emResetRStack;00112 extern __no_init __root volatile int16u emResetCStack;00113 #endif00114 #endif //DOXYGEN_SHOULD_SKIP_THIS00115

8.91 serial.h File Reference

Enumerations

• enum SerialBaudRate {DEFINE_BAUD, DEFINE_BAUD, DEFINE_BAUD, DEFINE_BAUD,DEFINE_BAUD, DEFINE_BAUD, DEFINE_BAUD, DEFINE_BAUD,DEFINE_BAUD, DEFINE_BAUD, DEFINE_BAUD, DEFINE_BAUD,DEFINE_BAUD, DEFINE_BAUD, DEFINE_BAUD, DEFINE_BAUD,DEFINE_BAUD, DEFINE_BAUD, DEFINE_BAUD }

• enum NameOfType { DEFINE_PARITY, DEFINE_PARITY, DEFINE_PARITY }

Serial Mode Definitions

These are numerical definitions for the possible serial modes so that code can test for the one being used.There may be additional modes defined in the micro-specific micro.h.

• #define EMBER_SERIAL_UNUSED• #define EMBER_SERIAL_FIFO• #define EMBER_SERIAL_BUFFER• #define EMBER_SERIAL_LOWLEVEL

FIFO Utility Macros

These macros manipulate the FIFO queue data structures to add and remove data.

• #define FIFO_ENQUEUE(queue, data, size)• #define FIFO_DEQUEUE(queue, size)

Serial HAL APIs

These functions must be implemented by the HAL in order for the serial code to operate. Only the higher-level serial code uses these functions, so they should not be called directly. The HAL should also implementthe appropriate interrupt handlers to drain the TX queues and fill the RX FIFO queue.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

435

• #define halInternalUartFlowControl(port)• #define halInternalUartRxPump(port)• EmberStatus halInternalUartInit (int8u port, SerialBaudRate rate, SerialParity parity, int8u stopBits)• void halInternalPowerDownUart (void)• void halInternalPowerUpUart (void)• void halInternalStartUartTx (int8u port)• void halInternalStopUartTx (int8u port)• EmberStatus halInternalForceWriteUartData (int8u port, int8u ∗data, int8u length)• EmberStatus halInternalForceReadUartByte (int8u port, int8u ∗dataByte)• void halInternalWaitUartTxComplete (int8u port)• void halInternalRestartUart (void)• boolean halInternalUart1FlowControlRxIsEnabled (void)• boolean halInternalUart1XonRefreshDone (void)• boolean halInternalUart1TxIsIdle (void)

Buffered Serial Utility APIs

The higher-level serial code implements these APIs, which the HAL uses to deal with buffered serial output.

• void emSerialBufferNextMessageIsr (EmSerialBufferQueue ∗q)• void emSerialBufferNextBlockIsr (EmSerialBufferQueue ∗q, int8u port)

Virtual UART API

API used by the stack in debug builds to receive data arriving over the virtual UART.

• void halStackReceiveVuartMessage (int8u ∗data, int8u length)


Serial hardware abstraction layer interfaces. See Serial UART Communication for documentation.

Definition in file hal/micro/serial.h.

8.92 hal/micro/serial.h

0000100023 #ifndef __HAL_SERIAL_H__00024 #define __HAL_SERIAL_H__0002500026 // EM_NUM_SERIAL_PORTS is inherited from the micro specifc micro.h00027 #if (EM_NUM_SERIAL_PORTS == 1)00028 #define FOR_EACH_PORT(cast,prefix,suffix) \00029 cast(prefix##0##suffix)00030 #elif (EM_NUM_SERIAL_PORTS == 2)00031 #define FOR_EACH_PORT(cast,prefix,suffix) \00032 cast(prefix##0##suffix), \00033 cast(prefix##1##suffix)00034 #elif (EM_NUM_SERIAL_PORTS == 3)00035 #define FOR_EACH_PORT(cast,prefix,suffix) \00036 cast(prefix##0##suffix), \00037 cast(prefix##1##suffix), \00038 cast(prefix##2##suffix)00039 #else00040 #error unsupported number of serial ports

EmberZNet 4.7.2 API EM260 120-3020-000-4720

436

00041 #endif0004200055 #define EMBER_SERIAL_UNUSED 000056 #define EMBER_SERIAL_FIFO 100057 #define EMBER_SERIAL_BUFFER 200058 #define EMBER_SERIAL_LOWLEVEL 30005900061 #ifndef DOXYGEN_SHOULD_SKIP_THIS0006200063 // The following tests for setting of an invalid mode00064 #ifdef EMBER_SERIAL0_MODE00065 #if (EMBER_SERIAL0_MODE != EMBER_SERIAL_FIFO) && \00066 (EMBER_SERIAL0_MODE != EMBER_SERIAL_BUFFER) && \00067 (EMBER_SERIAL0_MODE != EMBER_SERIAL_LOWLEVEL) && \00068 (EMBER_SERIAL0_MODE != EMBER_SERIAL_UNUSED)00069 #error Invalid Serial 0 Mode00070 #endif00071 #else00072 #define EMBER_SERIAL0_MODE EMBER_SERIAL_UNUSED00073 #endif00074 #ifdef EMBER_SERIAL1_MODE00075 #if (EMBER_SERIAL1_MODE != EMBER_SERIAL_FIFO) && \00076 (EMBER_SERIAL1_MODE != EMBER_SERIAL_BUFFER) && \00077 (EMBER_SERIAL1_MODE != EMBER_SERIAL_LOWLEVEL) && \00078 (EMBER_SERIAL1_MODE != EMBER_SERIAL_UNUSED)00079 #error Invalid Serial 1 Mode00080 #endif00081 #else00082 #define EMBER_SERIAL1_MODE EMBER_SERIAL_UNUSED00083 #endif00084 #ifdef EMBER_SERIAL2_MODE00085 #if (EMBER_SERIAL2_MODE != EMBER_SERIAL_FIFO) && \00086 (EMBER_SERIAL2_MODE != EMBER_SERIAL_BUFFER) && \00087 (EMBER_SERIAL2_MODE != EMBER_SERIAL_LOWLEVEL) && \00088 (EMBER_SERIAL2_MODE != EMBER_SERIAL_UNUSED)00089 #error Invalid Serial 2 Mode00090 #endif00091 #else00092 #define EMBER_SERIAL2_MODE EMBER_SERIAL_UNUSED00093 #endif0009400095 // Determine if FIFO and/or Buffer modes are being used, so those sections of00096 // code may be disabled if not00097 #if (EMBER_SERIAL0_MODE == EMBER_SERIAL_FIFO) || \00098 (EMBER_SERIAL1_MODE == EMBER_SERIAL_FIFO) || \00099 (EMBER_SERIAL2_MODE == EMBER_SERIAL_FIFO)00100 #define EM_ENABLE_SERIAL_FIFO00101 #endif00102 #if (EMBER_SERIAL0_MODE == EMBER_SERIAL_BUFFER) || \00103 (EMBER_SERIAL1_MODE == EMBER_SERIAL_BUFFER) || \00104 (EMBER_SERIAL2_MODE == EMBER_SERIAL_BUFFER)00105 #define EM_ENABLE_SERIAL_BUFFER00106 #endif001070010800116 typedef struct {00118 int16u head;00120 int16u tail;00122 volatile int16u used;00124 int8u fifo[];00125 } EmSerialFifoQueue;001260012700131 typedef struct {00133 int8u length;00135 EmberMessageBuffer buffer;00137 int8u startIndex;00138 } EmSerialBufferQueueEntry;0013900143 typedef struct {00145 int8u head;00147 int8u tail;00149 volatile int8u used;00151 volatile int8u dead;00154 EmberMessageBuffer currentBuffer;00156 int8u *nextByte;00158 int8u *lastByte;00160 EmSerialBufferQueueEntry fifo[];00161 } EmSerialBufferQueue;00162

EmberZNet 4.7.2 API EM260 120-3020-000-4720

437

00172 extern void *emSerialTxQueues[EM_NUM_SERIAL_PORTS];00174 extern EmSerialFifoQueue *emSerialRxQueues[EM_NUM_SERIAL_PORTS];00176 extern int16u PGM emSerialTxQueueMasks[EM_NUM_SERIAL_PORTS];00178 extern int16u PGM emSerialTxQueueSizes[EM_NUM_SERIAL_PORTS];00180 extern int16u PGM emSerialRxQueueSizes[EM_NUM_SERIAL_PORTS];00182 extern int8u emSerialRxError[EM_NUM_SERIAL_PORTS];00184 extern int16u emSerialRxErrorIndex[EM_NUM_SERIAL_PORTS];00186 extern int8u PGM emSerialPortModes[EM_NUM_SERIAL_PORTS];0018700188 //Compatibility code for the AVR Atmega00189 #ifdef AVR_ATMEGA00190 extern int8u PGM emSerialTxQueueWraps[EM_NUM_SERIAL_PORTS];00191 extern int8u PGM emSerialRxQueueWraps[EM_NUM_SERIAL_PORTS];00192 #else00193 extern int16u PGM emSerialTxQueueWraps[EM_NUM_SERIAL_PORTS];00194 extern int16u PGM emSerialRxQueueWraps[EM_NUM_SERIAL_PORTS];00195 #endif0019600199 #ifdef EZSP_UART00200 #define HANDLE_ASH_ERROR(type) emberCounterHandler(type, 0)00201 #else00202 #define HANDLE_ASH_ERROR(type)00203 #endif0020400205 #endif //DOXYGEN_SHOULD_SKIP_THIS002060020700224 //Compatibility code for the AVR Atmega00225 #ifdef AVR_ATMEGA00226 #define FIFO_ENQUEUE(queue,data,size) \00227 do { \00228 queue->fifo[queue->head] = data; \00229 queue->head = ((queue->head + 1) & size); \00230 queue->used++; \00231 } while(0)00232 #else00233 #define FIFO_ENQUEUE(queue,data,size) \00234 do { \00235 queue->fifo[queue->head] = data; \00236 queue->head = ((queue->head + 1) % size); \00237 queue->used++; \00238 } while(0)00239 #endif0024000248 //Compatibility code for the AVR Atmega00249 #ifdef AVR_ATMEGA00250 #define FIFO_DEQUEUE(queue,size) \00251 queue->fifo[queue->tail]; \00252 queue->tail = ((queue->tail + 1) & size); \00253 queue->used--00254 #else00255 #define FIFO_DEQUEUE(queue,size) \00256 queue->fifo[queue->tail]; \00257 queue->tail = ((queue->tail + 1) % size); \00258 queue->used--00259 #endif0026000264 #ifdef DOXYGEN_SHOULD_SKIP_THIS0026500269 enum SerialBaudRate00270 #else00271 #ifndef DEFINE_BAUD00272 #define DEFINE_BAUD(num) BAUD_##num00273 #endif00274 typedef int8u SerialBaudRate;00275 enum00276 #endif //DOXYGEN_SHOULD_SKIP_THIS00277 {00278 DEFINE_BAUD(300) = 0, // BAUD_30000279 DEFINE_BAUD(600) = 1, // BAUD_60000280 DEFINE_BAUD(900) = 2, // etc...00281 DEFINE_BAUD(1200) = 3,00282 DEFINE_BAUD(2400) = 4,00283 DEFINE_BAUD(4800) = 5,00284 DEFINE_BAUD(9600) = 6,00285 DEFINE_BAUD(14400) = 7,00286 DEFINE_BAUD(19200) = 8,00287 DEFINE_BAUD(28800) = 9,00288 DEFINE_BAUD(38400) = 10,00289 DEFINE_BAUD(50000) = 11,

EmberZNet 4.7.2 API EM260 120-3020-000-4720

438

00290 DEFINE_BAUD(57600) = 12,00291 DEFINE_BAUD(76800) = 13,00292 DEFINE_BAUD(100000) = 14,00293 DEFINE_BAUD(115200) = 15,00294 #ifdef AVR_ATMEGA00295 DEFINE_BAUD(CUSTOM) = 1600296 #else00297 DEFINE_BAUD(230400) = 16, /*<! define higher baud rates for the

EM2XX and EM3XX */00298 DEFINE_BAUD(460800) = 17, /*<! Note: receiving data at baud

rates > 115200 */00299 DEFINE_BAUD(CUSTOM) = 18 /*<! may not be reliable due to

interrupt latency */00300 #endif00301 };003020030300304 #ifdef DOXYGEN_SHOULD_SKIP_THIS0030500309 enum NameOfType00310 #else00311 #ifndef DEFINE_PARITY00312 #define DEFINE_PARITY(val) PARITY_##val00313 #endif00314 typedef int8u SerialParity;00315 enum00316 #endif //DOXYGEN_SHOULD_SKIP_THIS00317 {00318 DEFINE_PARITY(NONE) = 0, // PARITY_NONE00319 DEFINE_PARITY(ODD) = 1, // PARITY_ODD00320 DEFINE_PARITY(EVEN) = 2 // PARITY_EVEN00321 };0032200348 EmberStatus halInternalUartInit(int8u port,00349 SerialBaudRate rate,00350 SerialParity parity,00351 int8u stopBits);0035200357 void halInternalPowerDownUart(void);0035800363 void halInternalPowerUpUart(void);0036400371 void halInternalStartUartTx(int8u port);003720037300379 void halInternalStopUartTx(int8u port);003800038100393 EmberStatus halInternalForceWriteUartData

(int8u port, int8u *data, int8u length);0039400403 EmberStatus halInternalForceReadUartByte

(int8u port, int8u *dataByte);0040400410 void halInternalWaitUartTxComplete(int8u port

);0041100419 #if (EMBER_SERIAL1_MODE == EMBER_SERIAL_FIFO) && \00420 ( defined(EMBER_SERIAL1_XONXOFF) || \00421 (defined(XAP2B) && defined(EMBER_SERIAL1_RTSCTS) ) )00422 void halInternalUartFlowControl(int8u port);00423 #else00424 #define halInternalUartFlowControl(port) do {} while(FALSE)00425 #endif0042600434 #if (defined(XAP2B)&&(EMBER_SERIAL1_MODE == EMBER_SERIAL_BUFFER)) ||

defined(CORTEXM3)00435 void halInternalUartRxPump(int8u port);00436 #else00437 #define halInternalUartRxPump(port) do {} while(FALSE)00438 #endif0043900445 void halInternalRestartUart(void);0044600452 boolean halInternalUart1FlowControlRxIsEnabled

(void);0045300458 boolean halInternalUart1XonRefreshDone(void);0045900464 boolean halInternalUart1TxIsIdle(void);

EmberZNet 4.7.2 API EM260 120-3020-000-4720

439

0046500481 void emSerialBufferNextMessageIsr(

EmSerialBufferQueue *q);004820048300493 void emSerialBufferNextBlockIsr(EmSerialBufferQueue *

q, int8u port);0049400511 void halStackReceiveVuartMessage(int8u* data,

int8u length);0051200515 #endif //__HAL_SERIAL_H__00516

8.93 serial.h File Reference

Macros

• #define emberSerialWriteUsed(port)

Functions

• EmberStatus emberSerialInit (int8u port, SerialBaudRate rate, SerialParity parity, int8u stopBits)• int16u emberSerialReadAvailable (int8u port)• EmberStatus emberSerialReadByte (int8u port, int8u ∗dataByte)• EmberStatus emberSerialReadData (int8u port, int8u ∗data, int16u length, int16u ∗bytesRead)• EmberStatus emberSerialReadDataTimeout (int8u port, int8u ∗data, int16u length, int16u ∗bytes-

Read, int16u firstByteTimeout, int16u subsequentByteTimeout)• EmberStatus emberSerialReadLine (int8u port, char ∗data, int8u max)• EmberStatus emberSerialReadPartialLine (int8u port, char ∗data, int8u max, int8u ∗index)• int16u emberSerialWriteAvailable (int8u port)• EmberStatus emberSerialWriteByte (int8u port, int8u dataByte)• EmberStatus emberSerialWriteHex (int8u port, int8u dataByte)• EmberStatus emberSerialWriteString (int8u port, PGM_P string)• XAP2B_PAGEZERO_ON EmberStatus emberSerialPrintf (int8u port, PGM_P formatString,...)• XAP2B_PAGEZERO_OFF

XAP2B_PAGEZERO_ON EmberStatus emberSerialPrintfLine (int8u port, PGM_P formatString,...)• XAP2B_PAGEZERO_OFF

XAP2B_PAGEZERO_ON EmberStatus emberSerialPrintCarriageReturn (int8u port)• XAP2B_PAGEZERO_OFF EmberStatus emberSerialPrintfVarArg (int8u port, PGM_P formatString,

va_list ap)• EmberStatus emberSerialWriteData (int8u port, int8u ∗data, int8u length)• EmberStatus emberSerialWriteBuffer (int8u port, EmberMessageBuffer buffer, int8u start, int8u

length)• XAP2B_PAGEZERO_ON EmberStatus emberSerialWaitSend (int8u port)• XAP2B_PAGEZERO_OFF EmberStatus emberSerialGuaranteedPrintf (int8u port, PGM_P format-

String,...)• void emberSerialBufferTick (void)• void emberSerialFlushRx (int8u port)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

440

Printf Prototypes

These prototypes are for the internal printf implementation, in case it is desired to use it elsewhere. See thecode for emberSerialPrintf() for an example of printf usage.

• typedef EmberStatus( emPrintfFlushHandler )(int8u flushVar, int8u ∗contents, int8u length)• int8u emPrintfInternal (emPrintfFlushHandler flushHandler, int8u port, PGM_P string, va_list args)


High-level serial communication functions. See Serial Communication for documentation.

Definition in file app/util/serial/serial.h.

8.94 app/util/serial/serial.h

0000100012 #ifndef __SERIAL_H__00013 #define __SERIAL_H__0001400015 #ifndef __HAL_H__00016 #error hal/hal.h should be included first00017 #endif0001800019 #ifndef DOXYGEN_SHOULD_SKIP_THIS00020 #include <stdarg.h>0002100022 //Rx FIFO Full indicator00023 #define RX_FIFO_FULL (0xFFFF)0002400025 #endif // DOXYGEN_SHOULD_SKIP_THIS0002600136 EmberStatus emberSerialInit(int8u port,00137 SerialBaudRate rate,00138 SerialParity parity,00139 int8u stopBits);0014000148 int16u emberSerialReadAvailable(int8u port);0014900167 EmberStatus emberSerialReadByte(int8u port,

int8u *dataByte);0016800193 EmberStatus emberSerialReadData(int8u port,00194 int8u *data,00195 int16u length,00196 int16u *bytesRead);0019700232 EmberStatus emberSerialReadDataTimeout(

int8u port,00233 int8u *data,00234 int16u length,00235 int16u *bytesRead,00236 int16u firstByteTimeout,00237 int16u subsequentByteTimeout);0023800253 EmberStatus emberSerialReadLine(int8u port,

char *data, int8u max);0025400278 EmberStatus emberSerialReadPartialLine(

int8u port, char *data, int8u max, int8u *index);0027900288 int16u emberSerialWriteAvailable(int8u port

);0028900297 #define emberSerialWriteUsed(port) \00298 (emSerialTxQueueSizes[port] - emberSerialWriteAvailable(port))0029900313 EmberStatus emberSerialWriteByte(int8u port

, int8u dataByte);

EmberZNet 4.7.2 API EM260 120-3020-000-4720

441

0031400329 EmberStatus emberSerialWriteHex(int8u port,

int8u dataByte);0033000343 EmberStatus emberSerialWriteString(int8u

port, PGM_P string);0034400369 XAP2B_PAGEZERO_ON00370 EmberStatus emberSerialPrintf(int8u port,

PGM_P formatString, ...);00371 XAP2B_PAGEZERO_OFF0037200388 XAP2B_PAGEZERO_ON00389 EmberStatus emberSerialPrintfLine(int8u

port, PGM_P formatString, ...);00390 XAP2B_PAGEZERO_OFF0039100402 XAP2B_PAGEZERO_ON00403 EmberStatus emberSerialPrintCarriageReturn

(int8u port);00404 XAP2B_PAGEZERO_OFF004050040600419 EmberStatus emberSerialPrintfVarArg(int8u

port, PGM_P formatString, va_list ap);0042000436 EmberStatus emberSerialWriteData(int8u port

, int8u *data, int8u length);0043700438 //Host HALs do not use stack buffers.00439 #ifndef HAL_HOST0044000458 EmberStatus emberSerialWriteBuffer(int8u

port, EmberMessageBuffer buffer, int8u start, int8ulength);

00459 #endif //HAL_HOST0046000473 XAP2B_PAGEZERO_ON00474 EmberStatus emberSerialWaitSend(int8u port);00475 XAP2B_PAGEZERO_OFF0047600497 EmberStatus emberSerialGuaranteedPrintf(

int8u port, PGM_P formatString, ...);0049800504 void emberSerialBufferTick(void);0050500511 void emberSerialFlushRx(int8u port);0051200513005140051500536 typedef EmberStatus (emPrintfFlushHandler)(int8u

flushVar,00537 int8u *contents,00538 int8u length);005390054000558 int8u emPrintfInternal(emPrintfFlushHandler

flushHandler,00559 int8u port,00560 PGM_P string,00561 va_list args);005620056300568 #endif // __SERIAL_H__00569

8.95 spi-protocol.h File Reference

#include "app/util/ezsp/ezsp-enum.h"

EmberZNet 4.7.2 API EM260 120-3020-000-4720

442

SPI Protocol Interface

• int8u ∗ halNcpFrame• int8u halNcpSpipErrorByte• void halNcpSerialInit (void)• void halNcpSerialPowerup (void)• void halNcpSerialPowerdown (void)• EzspStatus halNcpHardReset (void)• EzspStatus halNcpHardResetReqBootload (boolean requestBootload)• void halNcpWakeUp (void)• void halNcpSendCommand (void)• void halNcpSendRawCommand (void)• EzspStatus halNcpPollForResponse (void)• void halNcpIsAwakeIsr (boolean isAwake)• boolean halNcpHasData (void)• boolean halNcpVerifySpiProtocolVersion (void)• boolean halNcpVerifySpiProtocolActive (void)

SPI Protocol Test Function

• void spipTest (int16u test, int16u params)


Example AVR SPI Protocol implementation for interfacing with EM260. See SPI Access for documenta-tion.

Definition in file spi-protocol.h.

8.96 spi-protocol.h

0000100020 #ifndef __SPI_PROTOCOL_H__00021 #define __SPI_PROTOCOL_H__0002200023 #include "app/util/ezsp/ezsp-enum.h"00024000290003000038 extern int8u *halNcpFrame;0003900047 extern int8u halNcpSpipErrorByte;0004800052 void halNcpSerialInit(void);0005300058 void halNcpSerialPowerup(void);0005900063 void halNcpSerialPowerdown(void);0006400077 EzspStatus halNcpHardReset(void);0007800093 EzspStatus halNcpHardResetReqBootload(boolean

requestBootload);0009400104 void halNcpWakeUp(void);0010500117 void halNcpSendCommand(void);0011800130 void halNcpSendRawCommand(void);00131

EmberZNet 4.7.2 API EM260 120-3020-000-4720

443

00140 EzspStatus halNcpPollForResponse(void);0014100149 void halNcpIsAwakeIsr(boolean isAwake);0015000155 boolean halNcpHasData(void);001560015700165 boolean halNcpVerifySpiProtocolVersion(void);0016600174 boolean halNcpVerifySpiProtocolActive(void);0017500177001820018300203 void spipTest(int16u test, int16u params);002040020600207 #endif // __SPI_PROTOCOL_H__00208

8.97 spi.h File Reference

Functions

• void halCommonInitSpi (void)• void halCommonSpiWrite (int8u data)• int8u halCommonSpiRead (void)• int8u halCommonSpiReadWrite (int8u data)


Generic SPI manipulation routines. See SPI Access for documentation.

Definition in file spi.h.

8.98 spi.h

0000100026 #ifndef __SPI_H__00027 #define __SPI_H__0002800033 void halCommonInitSpi(void);0003400040 void halCommonSpiWrite(int8u data);0004100047 int8u halCommonSpiRead(void);0004800056 int8u halCommonSpiReadWrite(int8u data);0005700058 #endif //__SPI_H__00059

8.99 system-timer.h File Reference

Macros

• #define halIdleForMilliseconds(duration)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

444

Functions

• int16u halInternalStartSystemTimer (void)• int16u halCommonGetInt16uMillisecondTick (void)• int32u halCommonGetInt32uMillisecondTick (void)• int16u halCommonGetInt16uQuarterSecondTick (void)• EmberStatus halSleepForQuarterSeconds (int32u ∗duration)• EmberStatus halSleepForMilliseconds (int32u ∗duration)• EmberStatus halCommonIdleForMilliseconds (int32u ∗duration)


See System Timer Control for documentation.

Definition in file system-timer.h.

8.100 system-timer.h

0000100031 #ifndef __SYSTEM_TIMER_H__00032 #define __SYSTEM_TIMER_H__0003300034 #ifndef DOXYGEN_SHOULD_SKIP_THIS0003500036 #if defined( EMBER_TEST )00037 #include "unix/simulation/system-timer-sim.h"00038 #elif defined(AVR_ATMEGA_32)00039 #include "avr-atmega/32/system-timer.h"00040 #elif defined(AVR_ATMEGA_128)00041 #include "avr-atmega/128/system-timer.h"00042 #endif0004300044 #endif // DOXYGEN_SHOULD_SKIP_THIS000450004600053 int16u halInternalStartSystemTimer(void);000540005500056 #ifndef DOXYGEN_SHOULD_SKIP_THIS00057 XAP2B_PAGEZERO_ON00058 #endif0005900066 int16u halCommonGetInt16uMillisecondTick

(void);00067 #ifndef DOXYGEN_SHOULD_SKIP_THIS00068 XAP2B_PAGEZERO_OFF00069 #endif0007000080 int32u halCommonGetInt32uMillisecondTick

(void);0008100091 int16u halCommonGetInt16uQuarterSecondTick

(void);0009200134 EmberStatus halSleepForQuarterSeconds(

int32u *duration);0013500177 EmberStatus halSleepForMilliseconds(int32u

*duration);0017800201 EmberStatus halCommonIdleForMilliseconds

(int32u *duration);00202 // Maintain the previous API for backwards compatibility00203 #define halIdleForMilliseconds(duration)

halCommonIdleForMilliseconds((duration))002040020500206 #endif //__SYSTEM_TIMER_H__00207

EmberZNet 4.7.2 API EM260 120-3020-000-4720

445


Functions

• void halCommonSetSystemTime (int32u time)


Functions that provide access to the system clock for ATmega32 microcontroller. See System Timer Con-trol for documentation.

Definition in file avr-atmega/32/system-timer.h.

8.102 avr-atmega/32/system-timer.h

0000100018 #ifndef __32_SYSTEM_TIMER_H__00019 #define __32_SYSTEM_TIMER_H__0002000021 #ifndef __SYSTEM_TIMER_H__00022 #error do not include this file directly - include micro/system-timer.h00023 #endif0002400030 void halCommonSetSystemTime(int32u time);0003100032 #endif //__32_SYSTEM_TIMER_H__00033


Functions

• void halCommonSetSystemTime (int32u time)


Functions that provide access to the system clock for ATmega128 microcontroller. See System TimerControl for documentation.

Definition in file avr-atmega/128/system-timer.h.

8.104 avr-atmega/128/system-timer.h

0000100018 #ifndef __128_SYSTEM_TIMER_H__00019 #define __128_SYSTEM_TIMER_H__0002000021 #ifndef __SYSTEM_TIMER_H__00022 #error do not include this file directly - include micro/system-timer.h00023 #endif0002400030 void halCommonSetSystemTime(int32u time);0003100032 #endif //__128_SYSTEM_TIMER_H__00033

EmberZNet 4.7.2 API EM260 120-3020-000-4720

446

8.105 uart.h File Reference

UART0 Tinies

UART I/O tiny implementations for UART0.

• #define halUart0InitTiny()• #define halUart0WriteByteTiny(x)• EmberStatus halUart0ReadByteTimeoutTiny (int8u ∗dataByte)


Prototypes and defines for the hardware-specific UARTs. See Hardware-Specific UART for documenta-tion.

Definition in file uart.h.

8.106 uart.h

0000100024 #ifndef __UART_H__00025 #define __UART_H__0002600027 #ifndef DOXYGEN_SHOULD_SKIP_THIS0002800029 #define ENABLE_BIT_DEFINITIONS0003000031 #include <ioavr.h>0003200033 #if defined(AVR_ATMEGA_8) || defined(AVR_ATMEGA_32)00034 #define UCSR0C UCSRC00035 #define UPM00 UPM000036 #define UPM01 UPM100037 #define USBS0 USBS00038 #define UBRR0L UBRRL00039 #define UBRR0H UBRRH00040 #define UCSR0B UCSRB00041 #define TXCIE0 TXCIE00042 #define RXCIE0 RXCIE00043 #define TXEN0 TXEN00044 #define RXEN0 RXEN00045 #define UCSR0A UCSRA00046 #define TXC0 TXC00047 #define UDRIE0 UDRIE00048 #define USART0_RXC_vect USART_RXC_vect00049 #define FE0 FE00050 #define DOR0 DOR00051 #define UPE0 PE00052 #define UDR0 UDR00053 #define USART0_UDRE_vect USART_UDRE_vect00054 #define UDRE0 UDRE00055 #define RXC0 RXC0005600057 #else0005800059 #define TXCIE TXCIE000060 #define URSEL 700061 #define UBRRH UBRR0H00062 #define GIFR EIFR00063 #define GICR EIMSK00064 #ifndef AVR_ATMEGA_16900065 #define AS2 AS000066 #define TCN2UB TCN0UB00067 #endif0006800069 #endif00070

EmberZNet 4.7.2 API EM260 120-3020-000-4720

447

00071 #endif //DOXYGEN_SHOULD_SKIP_THIS000720007400078000790008000081 #ifndef AVR_ATMEGA_80008200089 #define halUart0InitTiny() \00090 UBRR0L = UDR0; \00091 UBRR0L = UBRRH; \00092 UCSR0C = BIT(URSEL) | BIT(UCSZ01) | BIT(UCSZ00) | BIT(USBS0); \00093 UBRR0L = 25; \00094 UCSR0B = BIT(TXEN0) | BIT(RXEN0); \00095 UCSR0A = BIT(TXC0);00096 #else //MEGA80009700105 #define halUart0InitTiny() \00106 UBRR0L = UDR0; \00107 UBRR0L = UBRRH; \00108 UCSR0C = BIT(URSEL) | BIT(UCSZ1) | BIT(UCSZ0) | BIT(USBS0); \00109 UBRR0L = 51; \00110 UCSR0B = BIT(TXEN0) | BIT(RXEN0); \00111 UCSR0A = BIT(TXC0);00112 #endif0011300119 #define halUart0WriteByteTiny(x) \00120 while ( !( UCSR0A & BIT(UDRE0)) ) {} \00121 UDR0 = x;0012200135 EmberStatus halUart0ReadByteTimeoutTiny(

int8u *dataByte);001360013800139001400014100142 #endif //__HAL_SERIAL_H__00143

8.107 zigbee-device-common.h File Reference

Macros

• #define ZDO_MESSAGE_OVERHEAD


• EmberStatus emberNodeDescriptorRequest (EmberNodeId target, EmberApsOption options)• EmberStatus emberPowerDescriptorRequest (EmberNodeId target, EmberApsOption options)• EmberStatus emberSimpleDescriptorRequest (EmberNodeId target, int8u targetEndpoint, Ember-

ApsOption options)• EmberStatus emberActiveEndpointsRequest (EmberNodeId target, EmberApsOption options)


• EmberStatus emberBindRequest (EmberNodeId target, EmberEUI64 source, int8u sourceEndpoint,int16u clusterId, int8u type, EmberEUI64 destination, EmberMulticastId groupAddress, int8u destination-Endpoint, EmberApsOption options)

• EmberStatus emberUnbindRequest (EmberNodeId target, EmberEUI64 source, int8u sourceEndpoint,int16u clusterId, int8u type, EmberEUI64 destination, EmberMulticastId groupAddress, int8u destination-Endpoint, EmberApsOption options)

EmberZNet 4.7.2 API EM260 120-3020-000-4720

448

Node Manager Functions

• EmberStatus emberLqiTableRequest (EmberNodeId target, int8u startIndex, EmberApsOption op-tions)

• EmberStatus emberRoutingTableRequest (EmberNodeId target, int8u startIndex, EmberApsOptionoptions)

• EmberStatus emberBindingTableRequest (EmberNodeId target, int8u startIndex, EmberApsOptionoptions)

• EmberStatus emberLeaveRequest (EmberNodeId target, EmberEUI64 deviceAddress, int8u leave-RequestFlags, EmberApsOption options)

• EmberStatus emberPermitJoiningRequest (EmberNodeId target, int8u duration, int8u authentication,EmberApsOption options)

• void emberSetZigDevRequestRadius (int8u radius)• int8u emberGetZigDevRequestRadius (void)• int8u emberGetLastZigDevRequestSequence (void)• int8u emberGetLastAppZigDevRequestSequence (void)


ZigBee Device Object (ZDO) functions available on all platforms. See ZigBee Device Object (ZDO)Information for documentation.

Definition in file zigbee-device-common.h.

8.108 zigbee-device-common.h

0000100016 #define ZDO_MESSAGE_OVERHEAD 10001700036 #ifdef DOXYGEN_SHOULD_SKIP_THIS00037 EmberStatus emberNodeDescriptorRequest(

EmberNodeId target,00038 EmberApsOption options);00039 #else00040 // Macroized to save code space.00041 EmberStatus emberSendZigDevRequestTarget(EmberNodeId

target,00042 int16u clusterId,00043 EmberApsOption options);00044 #define emberNodeDescriptorRequest(target, opts) \00045 (emberSendZigDevRequestTarget((target), NODE_DESCRIPTOR_REQUEST, (opts)))00046 #endif0004700063 #ifdef DOXYGEN_SHOULD_SKIP_THIS00064 EmberStatus emberPowerDescriptorRequest(

EmberNodeId target,00065 EmberApsOption options);00066 #else00067 // Macroized to save code space.00068 #define emberPowerDescriptorRequest(target, opts) \00069 (emberSendZigDevRequestTarget((target), POWER_DESCRIPTOR_REQUEST, (opts)))00070 #endif0007100090 EmberStatus emberSimpleDescriptorRequest

(EmberNodeId target,00091 int8u targetEndpoint,00092 EmberApsOption options);0009300106 #ifdef DOXYGEN_SHOULD_SKIP_THIS00107 EmberStatus emberActiveEndpointsRequest(

EmberNodeId target,00108 EmberApsOption options);00109 #else00110 // Macroized to save code space.

EmberZNet 4.7.2 API EM260 120-3020-000-4720

449

00111 #define emberActiveEndpointsRequest(target, opts) \00112 (emberSendZigDevRequestTarget((target), ACTIVE_ENDPOINTS_REQUEST, (opts)))00113 #endif0011400144 #ifdef DOXYGEN_SHOULD_SKIP_THIS00145 EmberStatus emberBindRequest(EmberNodeId

target,00146 EmberEUI64 source,00147 int8u sourceEndpoint,00148 int16u clusterId,00149 int8u type,00150 EmberEUI64 destination,00151 EmberMulticastId groupAddress,00152 int8u destinationEndpoint,00153 EmberApsOption options);00154 #else00155 // Macroized to save code space.00156 #define emberBindRequest(target, \00157 src, \00158 srcEndpt, \00159 cluster, \00160 type, \00161 dest, \00162 groupAddress, \00163 destEndpt, \00164 opts) \00165 \00166 (emberSendZigDevBindRequest((target), \00167 BIND_REQUEST, \00168 (src), (srcEndpt), (cluster), \00169 (type), (dest), (groupAddress), \00170 (destEndpt), (opts)))0017100172 EmberStatus emberSendZigDevBindRequest(EmberNodeId target

,00173 int16u bindClusterId,00174 EmberEUI64 source,00175 int8u sourceEndpoint,00176 int16u clusterId,00177 int8u type,00178 EmberEUI64 destination,00179 EmberMulticastId

groupAddress,00180 int8u destinationEndpoint,00181 EmberApsOption options);00182 #endif0018300210 #ifdef DOXYGEN_SHOULD_SKIP_THIS00211 EmberStatus emberUnbindRequest(EmberNodeId

target,00212 EmberEUI64 source,00213 int8u sourceEndpoint,00214 int16u clusterId,00215 int8u type,00216 EmberEUI64 destination,00217 EmberMulticastId groupAddress,00218 int8u destinationEndpoint,00219 EmberApsOption options);00220 #else00221 // Macroized to save code space.00222 #define emberUnbindRequest(target, \00223 src, \00224 srcEndpt, \00225 cluster, \00226 type, \00227 dest, \00228 groupAddress, \00229 destEndpt, \00230 opts) \00231 \00232 (emberSendZigDevBindRequest((target), \00233 UNBIND_REQUEST, \00234 (src), (srcEndpt), (cluster), \00235 (type), (dest), (groupAddress), \00236 (destEndpt), (opts)))00237 #endif0023800261 #ifdef DOXYGEN_SHOULD_SKIP_THIS00262 EmberStatus emberLqiTableRequest(EmberNodeId

target,

EmberZNet 4.7.2 API EM260 120-3020-000-4720

450

00263 int8u startIndex,00264 EmberApsOption options);00265 #else00266 #define emberLqiTableRequest(target, startIndex, options) \00267 (emberTableRequest(LQI_TABLE_REQUEST, (target), (startIndex), (options)))0026800269 EmberStatus emberTableRequest(int16u clusterId,00270 EmberNodeId target,00271 int8u startIndex,00272 EmberApsOption options);00273 #endif0027400291 #ifdef DOXYGEN_SHOULD_SKIP_THIS00292 EmberStatus emberRoutingTableRequest(

EmberNodeId target,00293 int8u startIndex,00294 EmberApsOption options);00295 #else00296 #define emberRoutingTableRequest(target, startIndex, options) \00297 (emberTableRequest(ROUTING_TABLE_REQUEST, (target), (startIndex), (options)))00298 #endif0029900317 #ifdef DOXYGEN_SHOULD_SKIP_THIS00318 EmberStatus emberBindingTableRequest(

EmberNodeId target,00319 int8u startIndex,00320 EmberApsOption options);00321 #else00322 #define emberBindingTableRequest(target, startIndex, options) \00323 (emberTableRequest(BINDING_TABLE_REQUEST, (target), (startIndex), (options)))00324 #endif0032500345 EmberStatus emberLeaveRequest(EmberNodeId

target,00346 EmberEUI64 deviceAddress,00347 int8u leaveRequestFlags,00348 EmberApsOption options);0034900366 EmberStatus emberPermitJoiningRequest(

EmberNodeId target,00367 int8u duration,00368 int8u authentication,00369 EmberApsOption options);0037000371 #ifdef DOXYGEN_SHOULD_SKIP_THIS0037200377 void emberSetZigDevRequestRadius(int8u radius);0037800384 int8u emberGetZigDevRequestRadius(void);00392 int8u emberGetLastZigDevRequestSequence(

void);00393 #else00394 extern int8u zigDevRequestRadius;00395 #define emberGetZigDevRequestRadius() (zigDevRequestRadius)00396 #define emberSetZigDevRequestRadius(x) (zigDevRequestRadius=x)00397 #define emberGetLastZigDevRequestSequence() \00398 (emberGetLastAppZigDevRequestSequence())00399 #endif0040000407 int8u emberGetLastAppZigDevRequestSequence

(void);0040800411 #ifndef DOXYGEN_SHOULD_SKIP_THIS00412 //

------------------------------------------------------------------------------00413 // Utility functions used by the library code.0041400415 EmberStatus emberSendZigDevRequest(EmberNodeId

destination,00416 int16u clusterId,00417 EmberApsOption options,00418 int8u *contents,00419 int8u length);0042000430 int8u emberNextZigDevRequestSequence(void);0043100432 #endif // DOXYGEN_SHOULD_SKIP_THIS00433

EmberZNet 4.7.2 API EM260 120-3020-000-4720

451

8.109 zigbee-device-host.h File Reference

Device Discovery Functions




• EmberStatus ezspMatchDescriptorsRequest (EmberNodeId target, int16u profile, int8u inCount, int8uoutCount, int16u ∗inClusters, int16u ∗outClusters, EmberApsOption options)


• EmberStatus ezspEndDeviceBindRequest (EmberNodeId localNodeId, EmberEUI64 localEui64, int8uendpoint, int16u profile, int8u inCount, int8u outCount, int16u ∗inClusters, int16u ∗outClusters,EmberApsOption options)

Function to Decode Address Response Messages

• EmberNodeId ezspDecodeAddressResponse (int8u ∗response, EmberEUI64 eui64Return)


ZigBee Device Object (ZDO) functions not provided by the stack. See ZigBee Device Object (ZDO)Information for documentation.

Definition in file zigbee-device-host.h.

8.110 zigbee-device-host.h

0000100104 EmberStatus emberNetworkAddressRequest(

EmberEUI64 target,00105 boolean reportKids,00106 int8u childStartIndex);0010700125 EmberStatus emberIeeeAddressRequest(

EmberNodeId target,00126 boolean reportKids,00127 int8u childStartIndex,00128 EmberApsOption options);00157 EmberStatus ezspMatchDescriptorsRequest(

EmberNodeId target,00158 int16u profile,00159 int8u inCount,00160 int8u outCount,00161 int16u *inClusters,00162 int16u *outClusters,00163 EmberApsOption options);00189 EmberStatus ezspEndDeviceBindRequest(

EmberNodeId localNodeId,00190 EmberEUI64 localEui64,00191 int8u endpoint,00192 int16u profile,

EmberZNet 4.7.2 API EM260 120-3020-000-4720

452

00193 int8u inCount,00194 int8u outCount,00195 int16u *inClusters,00196 int16u *outClusters,00197 EmberApsOption options);00216 EmberNodeId ezspDecodeAddressResponse(int8u

*response,00217 EmberEUI64 eui64Return);00218

8.111 zigbee-device-stack.h File Reference

Functions



• EmberStatus emberEnergyScanRequest (EmberNodeId target, int32u scanChannels, int8u scanDuration,int16u scanCount)

• EmberStatus emberSetNetworkManagerRequest (EmberNodeId networkManager, int32u activeChannels)• EmberStatus emberChannelChangeRequest (int8u channel)• EmberStatus emberSendDeviceAnnouncement (void)• int8u emberGetLastStackZigDevRequestSequence (void)


ZigBee Device Object (ZDO) functions included in the stack. See ZigBee Device Object for documenta-tion.

Definition in file zigbee-device-stack.h.

8.112 zigbee-device-stack.h

0000100010 #ifndef __ZIGBEE_DEVICE_STACK_H__00011 #define __ZIGBEE_DEVICE_STACK_H__0001200035 EmberStatus emberNetworkAddressRequest(

EmberEUI64 target,00036 boolean reportKids,00037 int8u childStartIndex);0003800055 EmberStatus emberIeeeAddressRequest(

EmberNodeId target,00056 boolean reportKids,00057 int8u childStartIndex,00058 EmberApsOption options);0005900079 EmberStatus emberEnergyScanRequest(EmberNodeId

target,00080 int32u scanChannels,00081 int8u scanDuration,00082 int16u scanCount);0008300097 #ifdef DOXYGEN_SHOULD_SKIP_THIS00098 EmberStatus emberSetNetworkManagerRequest

(EmberNodeId networkManager,00099 int32u activeChannels);00100 #else00101 #define emberSetNetworkManagerRequest(manager, channels) \00102 (emberEnergyScanRequest(EMBER_SLEEPY_BROADCAST_ADDRESS, \

EmberZNet 4.7.2 API EM260 120-3020-000-4720

453

00103 (channels), \00104 0xFF, \00105 (manager)))00106 #endif0010700121 #ifdef DOXYGEN_SHOULD_SKIP_THIS00122 EmberStatus emberChannelChangeRequest(int8u

channel);00123 #else00124 #define emberChannelChangeRequest(channel) \00125 (emberEnergyScanRequest(EMBER_SLEEPY_BROADCAST_ADDRESS, \00126 BIT32(channel), \00127 0xFE, \00128 0))00129 #endif0013000141 EmberStatus emberSendDeviceAnnouncement(

void);0014200149 int8u emberGetLastStackZigDevRequestSequence

(void);0015000154 #endif // __ZIGBEE_DEVICE_STACK_H__

EmberZNet 4.7.2 API EM260 120-3020-000-4720

Documents

EmberZNet 4.7.2 API Reference For the EM260 Co-Processor