Справочник по API-функциям библиотеки EmberZNET_EM250 v.4.3.0 ( PDF ) 5 Мб

EmberZNet 4.7.2 API Reference:
For the EM250 SoC Platform
December 20, 2012
120-3016-000-4720
Silicon Laboratories Inc.
400 West Cesar Chavez
Austin, TX 78701
Tel:1+(512) 416-8500
Fax:1+(512) 416-9669
Toll Free:1+(877) 444-3032
www.silabs.com
Disclaimer
The information in this document is believed to be accurate in all respects at the time
of publication but is subject to change without notice. Silicon Laboratories assumes no
responsibility for errors or omissions, and disclaims responsibility for the functioning of
undescribed features or parameters. Silicon Laboratories makes no warranty, representation, 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 use
or any product or circuit, and specifically disclaims any and all liability, including without limitation consequential or incidental damages. Silicon Laboratories products are not
designed, indended, or authorized for use in applications indended to support or sustain
life, or for any other application in which the failure of the Silicon Laboratories product could create a situation where personal injury or death may occur. Should Buyer
purchase or use Silicon Laboratories products for any such unintended or unauthorized
application, Buyer shall indemnify and hold Silicon Laboratories harmless against all
claims and damages.
Silicon Laboratories, Silicon Labs, and Ember are trademarks of Silicon Laboratories
Inc.
Other products or brandnames mentioned herin are trademarks or registered trademarks
of 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 the
information contained in the html version of these materials that are provided as an online reference for
developers of EmberZNet-based ZigBee wireless applications. There are three key advantages that this
document 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 free
Acrobat 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 networking products based on the EmberZNet PRO Stack Software. This document assumes that the reader has
a solid understanding of embedded systems design and programming in the C language. Experience with
networking 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 Labs
web 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 EM250
120-3016-000-4720
4
Chapter 1
Introduction
The EmberZNet API Reference documentation for the EM250 includes the following API sets:
• EmberZNet Stack API Reference
• Hardware Abstraction Layer (HAL) API Reference
• Application Utilities API Reference
EmberZNet 4.7.2 API EM250
120-3016-000-4720
5
Chapter 2
Deprecated List
File ami-inter-pan.h
The ami-inter-pan library is deprecated and will be removed in a future release. Similar functionality
is available in the Inter-PAN plugin in Application Framework.
File command-interpreter.h
command-interpreter is deprecated and will be removed in a future release. Use command-interpreter2
instead.
File fragment.h
The fragment library is deprecated and will be removed in a future release. Similar functionality is
available in the Fragmentation plugin in Application Framework.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
6
Chapter 3
Module Index
3.1
Modules
Here is a list of all modules:
EmberZNet Stack API Reference . . . . . . . . . .
Stack Information . . . . . . . . . . . . . . . .
Ember Common Data Types . . . . . . . . . .
Network Formation . . . . . . . . . . . . . . .
Packet Buffers . . . . . . . . . . . . . . . . . .
Sending and Receiving Messages . . . . . . . .
End Devices . . . . . . . . . . . . . . . . . . .
Security . . . . . . . . . . . . . . . . . . . . .
Trust Center . . . . . . . . . . . . . . . . .
Smart Energy Security . . . . . . . . . . .
Binding Table . . . . . . . . . . . . . . . . . .
Configuration . . . . . . . . . . . . . . . . . .
Status Codes . . . . . . . . . . . . . . . . . . .
Stack Tokens . . . . . . . . . . . . . . . . . .
ZigBee Device Object . . . . . . . . . . . . . .
Bootloader . . . . . . . . . . . . . . . . . . . .
Event Scheduling . . . . . . . . . . . . . . . .
Manufacturing and Functional Test Library . .
Debugging Utilities . . . . . . . . . . . . . . .
Hardware Abstraction Layer (HAL) API Reference
Common Microcontroller Functions . . . . . .
Token Access . . . . . . . . . . . . . . . . . .
Tokens . . . . . . . . . . . . . . . . . . . .
Simulated EEPROM . . . . . . . . . . . .
Sample APIs for Peripheral Access . . . . . . .
Serial UART Communication . . . . . . .
ADC Control . . . . . . . . . . . . . . . .
Button Control . . . . . . . . . . . . . . .
Buzzer Control . . . . . . . . . . . . . . .
LED Control . . . . . . . . . . . . . . . .
Flash Memory Control . . . . . . . . . . .
SPI Access . . . . . . . . . . . . . . . . .
Symbol Timer Control . . . . . . . . . . .
EmberZNet 4.7.2 API EM250
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
120-3016-000-4720
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
13
14
29
73
80
90
106
113
123
128
131
136
145
165
170
173
175
180
186
190
191
197
198
205
208
209
216
222
224
230
232
235
240
7
System Timer Control . . . . . . . . . . . . . . .
Bootloading . . . . . . . . . . . . . . . . . . . .
Stand-Alone Bootloader . . . . . . . . . . . .
Application Bootloader . . . . . . . . . . . .
HAL Configuration . . . . . . . . . . . . . . . .
Sample Breakout Board Configuration . . . .
MCC PLATFORM_HEADER Configuration
HAL Utilities . . . . . . . . . . . . . . . . . . .
Crash and Watchdog Diagnostics . . . . . . .
Cyclic Redundancy Code (CRC) . . . . . . .
Random Number Generation . . . . . . . . .
Asynchronous Serial Host (ASH) Framework . .
Application Utilities API Reference . . . . . . . . .
Bootloading . . . . . . . . . . . . . . . . . . . .
Stand-Alone Bootloader . . . . . . . . . . . .
Stand-Alone Bootloader for EZSP . . . . . .
Application Bootloader . . . . . . . . . . . .
Command Interpreter . . . . . . . . . . . . . . .
Forming and Joining Networks . . . . . . . . . .
ZigBee Device Object (ZDO) Information . . . .
Message Fragmentation . . . . . . . . . . . . . .
Network Manager . . . . . . . . . . . . . . . . .
Serial Communication . . . . . . . . . . . . . .
Eeprom . . . . . . . . . . . . . . . . . . . . . . . .
Commands2 . . . . . . . . . . . . . . . . . . . . . .
EmberZNet 4.7.2 API EM250
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
120-3016-000-4720
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
242
246
249
254
259
260
272
283
284
286
288
289
290
291
292
299
300
305
310
316
325
328
331
343
345
8
Chapter 4
Data Structure Index
4.1
Data Structures
Here are the data structures with brief descriptions:
EmberAesMmoHashContext
This data structure contains the context data when calculating an AES MMO hash (message digest) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EmberApsFrame
An in-memory representation of a ZigBee APS frame of an incoming or outgoing message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EmberBindingTableEntry
Defines an entry in the binding table . . . . . . . . . . . . . . . . . . . . . . . . . . .
EmberCertificateData
This data structure contains the certificate data that is used for Certificate Based Key
Exchange (CBKE) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EmberCommandEntry
Command entry for a command table . . . . . . . . . . . . . . . . . . . . . . . . . .
EmberCommandStateS
The command state structure. Using a structure allows commands to be read from
multiple sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EmberCurrentSecurityState
This describes the security features used by the stack for a joined device . . . . . . . .
EmberEndpoint
Gives the endpoint information for a particular endpoint . . . . . . . . . . . . . . . .
EmberEndpointDescription
Endpoint information (a ZigBee Simple Descriptor) . . . . . . . . . . . . . . . . . .
EmberEventControl
Control structure for events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EmberInitialSecurityState
This describes the Initial Security features and requirements that will be used when
forming or joining the network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EmberKeyData
This data structure contains the key data that is passed into various other functions . .
EmberKeyStruct
This describes a one of several different types of keys and its associated data . . . . .
EmberZNet 4.7.2 API EM250
120-3016-000-4720
352
352
354
355
356
358
360
361
362
363
364
366
366
9
EmberMacFilterMatchStruct
This structure indicates a matching raw MAC message has been received by the application configured MAC filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EmberMessageDigest
This data structure contains an AES-MMO Hash (the message digest) . . . . . . . . .
EmberMfgSecurityStruct
This structure is used to get/set the security config that is stored in manufacturing tokens
EmberMulticastTableEntry
Defines an entry in the multicast table . . . . . . . . . . . . . . . . . . . . . . . . . .
EmberNeighborTableEntry
Defines an entry in the neighbor table . . . . . . . . . . . . . . . . . . . . . . . . . .
EmberNetworkInitStruct
Defines the network initialization configuration that should be used when emberNetworkInitExtended() is called by the application . . . . . . . . . . . . . . . . . . . . . . . .
EmberNetworkParameters
Holds network parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EmberPrivateKeyData
This data structure contains the private key data that is used for Certificate Based Key
Exchange (CBKE) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EmberPublicKeyData
This data structure contains the public key data that is used for Certificate Based Key
Exchange (CBKE) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EmberRouteTableEntry
Defines an entry in the route table . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EmberSignatureData
This data structure contains a DSA signature. It is the bit concatenation of the ’r’ and
’s’ components of the signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EmberSmacData
This data structure contains the Shared Message Authentication Code (SMAC) data
that is used for Certificate Based Key Exchange (CBKE) . . . . . . . . . . . . . . . .
EmberTaskControl
Control structure for tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EmberVersion
Version struct containing all version information . . . . . . . . . . . . . . . . . . . .
EmberZigbeeNetwork
Defines a ZigBee network and the associated parameters . . . . . . . . . . . . . . . .
InterPanHeader
A struct for keeping track of all of the header info . . . . . . . . . . . . . . . . . . . .
EmberZNet 4.7.2 API EM250
120-3016-000-4720
368
368
369
369
370
372
372
374
374
375
376
377
377
378
379
380
10
Chapter 5
File Index
5.1
File List
Here is a list of all files with brief descriptions:
_EM250_API.top
Starting page for the Ember API documentation for the EM250 exclusively for building
documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
adc.h
Header for A/D converter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
xap2b/adc.h
Header for EM2xx A/D converter . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ami-inter-pan.h
Utilities for sending and receiving ZigBee AMI InterPAN messages. See Sending and
Receiving Messages for documentation . . . . . . . . . . . . . . . . . . . . . . . . .
app-bootload-utils.h
Utilities used for performing application bootloading. See Bootloading for documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
binding-table.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
bootload-utils.h
Utilities used for performing stand-alone bootloading. See Bootloading for documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
bootload.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
bootloader-common.h
Common routines used by EM250 bootloaders. See Bootloading for documentation .
bootloader-interface-app.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
bootloader-interface-standalone-v1.h
Definition of the interface to the standalone bootloader . . . . . . . . . . . . . . . . .
bootloader-interface-standalone.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
button.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
buzzer.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cbke-crypto-engine.h
EmberZNet Smart Energy security API. See Smart Energy Security for documention .
child.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
command-interpreter.h
Processes commands coming from the serial port. See Command Interpreter for documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EmberZNet 4.7.2 API EM250
120-3016-000-4720
382
383
384
386
388
389
391
393
393
394
396
398
398
400
401
405
407
11
command-interpreter2.h
Processes commands coming from the serial port. See Commands2 for documentation
config.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
crc.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dev0455.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dev0455i2c.h
Functions and definitions specific to the breakout board. See also Sample Breakout
Board Configuration for detailed documentation . . . . . . . . . . . . . . . . . . . .
diagnostic.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
xap2b/em250/diagnostic.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
eeprom.h
Ember generic EEPROM Interface . . . . . . . . . . . . . . . . . . . . . . . . . . .
ember-configuration-defaults.h
User-configurable stack memory allocation defaults . . . . . . . . . . . . . . . . . . .
ember-debug.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ember-types.h
Ember data type definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ember.h
The master include file for the EmberZNet API . . . . . . . . . . . . . . . . . . . . .
error-def.h
Return-code definitions for EmberZNet stack API functions . . . . . . . . . . . . . .
error.h
Return codes for Ember API functions and module definitions . . . . . . . . . . . . .
event.h
Scheduling events for future execution. See Event Scheduling for documentation . . .
flash.h
Flash manipulation routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
form-and-join.h
Utilities for forming and joining networks . . . . . . . . . . . . . . . . . . . . . . . .
fragment.h
Splits long messages into smaller blocks for transmission and reassembles received
blocks. See Message Fragmentation for documentation . . . . . . . . . . . . . . . . .
hal.h
Generic set of HAL includes for all platforms . . . . . . . . . . . . . . . . . . . . . .
led.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
mcc.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
message.h
EmberZNet API for sending and receiving messages. See Sending and Receiving Messages for documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
mfglib.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
micro.h
Full HAL functions common across all microcontroller-specific files. See Common
Microcontroller Functions for documentation . . . . . . . . . . . . . . . . . . . . . .
xap2b/em250/micro.h
Utility and convenience functions for the EM250 microcontroller. See Common Microcontroller Functions for documentation . . . . . . . . . . . . . . . . . . . . . . .
network-formation.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
network-manager.h
Utilities for use by the ZigBee network manager. See Network Manager for documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
packet-buffer.h
Packet buffer allocation and management routines See Packet Buffers for documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
random.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EmberZNet 4.7.2 API EM250
120-3016-000-4720
411
413
414
418
433
437
438
439
441
445
459
476
481
493
494
496
497
499
500
501
504
510
512
513
516
518
520
522
525
12
security.h
EmberZNet security API. See Security for documentation . . . . . . . . . . . . . . .
hal/micro/serial.h
Serial hardware abstraction layer interfaces. See Serial UART Communication for documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
app/util/serial/serial.h
High-level serial communication functions . . . . . . . . . . . . . . . . . . . . . . .
sim-eeprom.h
Simulated EEPROM system for wear leveling token storage across flash. See Simulated
EEPROM for documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
spi-protocol.h
Example AVR SPI Protocol implementation for interfacing with EM260 . . . . . . .
spi.h
Generic SPI manipulation routines . . . . . . . . . . . . . . . . . . . . . . . . . . . .
stack-info.h
EmberZNet API for accessing and setting stack information. See Stack Information for
documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
symbol-timer.h
Functions that provide access to symbol time. One symbol period is 16 microseconds .
system-timer.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
token-manufacturing.h
Definitions for manufacturing tokens . . . . . . . . . . . . . . . . . . . . . . . . . .
token-stack.h
Definitions for stack tokens. See Stack Tokens for documentation . . . . . . . . . . .
token.h
Token system for storing non-volatile information. See Tokens for documentation . . .
xap2b/token.h
XAP2b Token system for storing non-volatile information. See Tokens for documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
trust-center.h
EmberZNet security API See Security for documentation . . . . . . . . . . . . . . . .
zigbee-device-common.h
ZigBee Device Object (ZDO) functions available on all platforms. See ZigBee Device
Object (ZDO) Information for documentation . . . . . . . . . . . . . . . . . . . . . .
zigbee-device-library.h
ZigBee Device Object (ZDO) functions not provided by the stack. See ZigBee Device
Object (ZDO) Information for documentation . . . . . . . . . . . . . . . . . . . . . .
zigbee-device-stack.h
ZigBee Device Object (ZDO) functions included in the stack . . . . . . . . . . . . . .
EmberZNet 4.7.2 API EM250
120-3016-000-4720
526
529
534
535
537
538
540
544
544
548
553
558
559
562
564
567
568
13
Chapter 6
Module Documentation
6.1
EmberZNet Stack API Reference
Modules
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
6.1.1
Stack Information
Ember Common Data Types
Network Formation
Packet Buffers
Sending and Receiving Messages
End Devices
Security
Binding Table
Configuration
Status Codes
Stack Tokens
ZigBee Device Object
Bootloader
Event Scheduling
Manufacturing and Functional Test Library
Debugging Utilities
Detailed Description
This documentation describes the application programming interface (API) for the EmberZNet stack. The
file ember.h is the master include file for the EmberZNet API modules.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
14
6.2
Stack Information
Data Structures
• struct EmberEndpointDescription
Endpoint information (a ZigBee Simple Descriptor).
• struct EmberEndpoint
Gives the endpoint information for a particular endpoint.
Macros
•
•
•
•
•
•
•
•
#define EMBER_MAJOR_VERSION
#define EMBER_MINOR_VERSION
#define EMBER_PATCH_VERSION
#define EMBER_SPECIAL_VERSION
#define EMBER_BUILD_NUMBER
#define EMBER_FULL_VERSION
#define EMBER_VERSION_TYPE
#define SOFTWARE_VERSION
Functions
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
void emberStackStatusHandler (EmberStatus status)
EmberNetworkStatus emberNetworkState (void)
boolean emberStackIsUp (void)
EmberEUI64 emberGetEui64 (void)
boolean emberIsLocalEui64 (EmberEUI64 eui64)
EmberNodeId emberGetNodeId (void)
EmberNodeId emberRadioGetNodeId (void)
void emberSetManufacturerCode (int16u code)
void emberSetPowerDescriptor (int16u descriptor)
void emberSetMaximumIncomingTransferSize (int16u size)
void emberSetMaximumOutgoingTransferSize (int16u size)
void emberSetDescriptorCapability (int8u capability)
EmberStatus emberGetNetworkParameters (EmberNetworkParameters ∗parameters)
EmberStatus emberGetNodeType (EmberNodeType ∗resultLocation)
EmberStatus emberSetRadioChannel (int8u channel)
int8u emberGetRadioChannel (void)
EmberStatus emberSetRadioPower (int8s power)
int8s emberGetRadioPower (void)
EmberPanId emberGetPanId (void)
EmberPanId emberRadioGetPanId (void)
void emberGetExtendedPanId (int8u ∗resultLocation)
int8u emberGetEndpoint (int8u index)
boolean emberGetEndpointDescription (int8u endpoint, EmberEndpointDescription ∗result)
int16u emberGetEndpointCluster (int8u endpoint, EmberClusterListId listId, int8u listIndex)
boolean emberIsNodeIdValid (EmberNodeId nodeId)
EmberNodeId emberLookupNodeIdByEui64 (EmberEUI64 eui64)
EmberStatus emberLookupEui64ByNodeId (EmberNodeId nodeId, EmberEUI64 eui64Return)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
15
•
•
•
•
•
•
•
•
void emberCounterHandler (EmberCounterType type, int8u data)
EmberStatus emberGetNeighbor (int8u index, EmberNeighborTableEntry ∗result)
EmberStatus emberGetRouteTableEntry (int8u index, EmberRouteTableEntry ∗result)
int8u emberStackProfile (void)
int8u emberTreeDepth (void)
int8u emberNeighborCount (void)
int8u emberRouteTableSize (void)
int8u emberNextZigbeeSequenceNumber (void)
Variables
• PGM int8u emberStackProfileId [ ]
• int8u emberEndpointCount
• EmberEndpoint emberEndpoints [ ]
Radio-specific Functions
•
•
•
•
•
EmberStatus emberSetTxPowerMode (int16u txPowerMode)
int16u emberGetTxPowerMode (void)
EmberStatus emberSetNodeId (EmberNodeId nodeId)
void emberRadioNeedsCalibratingHandler (void)
void emberCalibrateCurrentChannel (void)
General Functions
•
•
•
•
•
•
•
void emberReverseMemCopy (int8u ∗dest, const int8u ∗src, int8u length)
XAP2B_PAGEZERO_ON int16u emberFetchLowHighInt16u (int8u ∗contents)
XAP2B_PAGEZERO_OFF void emberStoreLowHighInt16u (int8u ∗contents, int16u value)
int32u emberFetchLowHighInt32u (int8u ∗contents)
int32u emberFetchHighLowInt32u (int8u ∗contents)
void emberStoreLowHighInt32u (int8u ∗contents, int32u value)
void emberStoreHighLowInt32u (int8u ∗contents, int32u value)
6.2.1
Detailed Description
See stack-info.h for source code.
See also config.h.
This documentation was produced from the following software release and build.
SOFTWARE_VERSION
0x4700
6.2.2
Macro Definition Documentation
6.2.2.1
#define EMBER MAJOR VERSION
Definition at line 19 of file config.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
High byte = release number,
low byte = patch number
16
6.2.2.2
#define EMBER MINOR VERSION
Definition at line 20 of file config.h.
6.2.2.3
#define EMBER PATCH VERSION
Definition at line 21 of file config.h.
6.2.2.4
#define EMBER SPECIAL VERSION
Definition at line 22 of file config.h.
6.2.2.5
#define EMBER BUILD NUMBER
Definition at line 25 of file config.h.
6.2.2.6
#define EMBER FULL VERSION
Definition at line 27 of file config.h.
6.2.2.7
#define EMBER VERSION TYPE
Definition at line 32 of file config.h.
6.2.2.8
#define SOFTWARE VERSION
Software version. High byte First nibble: Major Version Second nibble: Minor Version Low Byte First
nibble: Patch Version Second nibble: Special Version
Definition at line 43 of file config.h.
6.2.3
Function Documentation
6.2.3.1
void emberStackStatusHandler ( EmberStatus status )
A callback invoked when the status of the stack changes. If the status parameter equals EMBER_NETWORK_UP, then the emberGetNetworkParameters() function can be called to obtain the new network
parameters. If any of the parameters are being stored in nonvolatile memory by the application, the stored
values should be updated.
The application is free to begin messaging once it receives the EMBER_NETWORK_UP status. However,
routes discovered immediately after the stack comes up may be suboptimal. This is because the routes are
based on the neighbor table’s information about two-way links with neighboring nodes, which is obtained
from periodic ZigBee Link Status messages. It can take two or three link status exchange periods (of 16
seconds each) before the neighbor table has a good estimate of link quality to neighboring nodes. Therefore,
the application may improve the quality of initially discovered routes by waiting after startup to give the
neighbor table time to be populated.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
17
Parameters
status Stack status. One of the following:
• EMBER_NETWORK_UP
• EMBER_NETWORK_DOWN
• EMBER_JOIN_FAILED
• EMBER_MOVE_FAILED
• EMBER_CANNOT_JOIN_AS_ROUTER
• EMBER_NODE_ID_CHANGED
• EMBER_PAN_ID_CHANGED
• EMBER_CHANNEL_CHANGED
• EMBER_NO_BEACONS
• EMBER_RECEIVED_KEY_IN_THE_CLEAR
• EMBER_NO_NETWORK_KEY_RECEIVED
• EMBER_NO_LINK_KEY_RECEIVED
• EMBER_PRECONFIGURED_KEY_REQUIRED
6.2.3.2 EmberNetworkStatus emberNetworkState ( void )
Returns the current join status.
Returns a value indicating whether the node is joining, joined to, or leaving a network.
Returns
An EmberNetworkStatus value indicating the current join status.
6.2.3.3 boolean emberStackIsUp ( void )
Indicates whether the stack is currently up.
Returns true if the stack is joined to a network and ready to send and receive messages. This reflects only
the state of the local node; it does not indicate whether or not other nodes are able to communicate with
this node.
Returns
True if the stack is up, false otherwise.
6.2.3.4 EmberEUI64 emberGetEui64 ( void )
Returns the EUI64 ID of the local node.
Returns
The 64-bit ID.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
18
6.2.3.5 boolean emberIsLocalEui64 ( EmberEUI64 eui64 )
Determines whether eui64 is the local node’s EUI64 ID.
Parameters
eui64 An EUI64 ID.
Returns
TRUE if eui64 is the local node’s ID, otherwise FALSE.
6.2.3.6 EmberNodeId emberGetNodeId ( void )
Returns the 16-bit node ID of local node on the current logical network.
Returns
The 16-bit ID.
6.2.3.7 EmberNodeId emberRadioGetNodeId ( void )
Returns the 16-bit node ID of local node on the network it is currently tuned on.
Returns
The 16-bit ID.
6.2.3.8
void emberSetManufacturerCode ( int16u code )
Sets the manufacturer code to the specified value. The manufacturer code is one of the fields of the node
descriptor.
Parameters
code The manufacturer code for the local node.
6.2.3.9
void emberSetPowerDescriptor ( int16u descriptor )
Sets the power descriptor to the specified value. The power descriptor is a dynamic value, therefore you
should call this function whenever the value changes.
Parameters
descriptor The new power descriptor for the local node.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
19
6.2.3.10
void emberSetMaximumIncomingTransferSize ( int16u size )
Sets the maximum incoming transfer size to the specified value. The maximum incoming transfer size is
one of the fields of the node descriptor.
Parameters
size The maximum incoming transfer size for the local node.
6.2.3.11
void emberSetMaximumOutgoingTransferSize ( int16u size )
Sets the maximum outgoing transfer size to the specified value. The maximum outgoing transfer size is
one of the fields of the node descriptor.
Parameters
size The maximum outgoing transfer size for the local node.
6.2.3.12
void emberSetDescriptorCapability ( int8u capability )
Sets the descriptor capability field of the node.
Parameters
capability The descriptor capability of the local node.
6.2.3.13 EmberStatus emberGetNetworkParameters ( EmberNetworkParameters ∗ parameters )
Copies the current network parameters into the structure provided by the caller.
Parameters
parameters A pointer to an EmberNetworkParameters value into which the current network parameters will be copied.
Returns
An EmberStatus value indicating the success or failure of the command.
6.2.3.14 EmberStatus emberGetNodeType ( EmberNodeType ∗ resultLocation )
Copies the current node type into the location provided by the caller.
Parameters
resultLocation A pointer to an EmberNodeType value into which the current node type will be copied.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
20
Returns
An EmberStatus value that indicates the success or failure of the command.
6.2.3.15 EmberStatus emberSetRadioChannel ( int8u channel )
Sets the channel to use for sending and receiving messages on the current logical network. For a list of
available radio channels, see the technical specification for the RF communication module in your Developer Kit.
Note: Care should be taken when using this API, as all devices on a network must use the same channel.
Parameters
channel Desired radio channel.
Returns
An EmberStatus value indicating the success or failure of the command.
6.2.3.16 int8u emberGetRadioChannel ( void )
Gets the radio channel to which a node is set on the current logical network. The possible return values
depend on the radio in use. For a list of available radio channels, see the technical specification for the RF
communication module in your Developer Kit.
Returns
Current radio channel.
6.2.3.17 EmberStatus emberSetRadioPower ( int8s power )
Sets the radio output power at which a node is to operate for the current logical network. Ember radios
have discrete power settings. For a list of available power settings, see the technical specification for the
RF communication module in your Developer Kit. Note: Care should be taken when using this API on a
running network, as it will directly impact the established link qualities neighboring nodes have with the
node on which it is called. This can lead to disruption of existing routes and erratic network behavior.
Note: If the requested power level is not available on a given radio, this function will use the next higher
available power level.
Parameters
power Desired radio output power, in dBm.
Returns
An EmberStatus value indicating the success or failure of the command. Failure indicates that the
requested power level is out of range.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
21
6.2.3.18 int8s emberGetRadioPower ( void )
Gets the radio output power of the current logical network at which a node is operating. Ember radios have
discrete power settings. For a list of available power settings, see the technical specification for the RF
communication module in your Developer Kit.
Returns
Current radio output power, in dBm.
6.2.3.19 EmberPanId emberGetPanId ( void )
Returns the local node’s PAN ID of the current logical network.
Returns
A PAN ID.
6.2.3.20 EmberPanId emberRadioGetPanId ( void )
Returns the local node’s PAN ID of the current radio network.
Returns
A PAN ID.
6.2.3.21
void emberGetExtendedPanId ( int8u ∗ resultLocation )
Fetches a node’s 8 byte Extended PAN identifier.
6.2.3.22 int8u emberGetEndpoint ( int8u index )
Retrieves the endpoint number for the index’th endpoint. index must be less than the value of emberEndpointCount.
This function is provided by the stack, using the data from emberEndpoints, unless the application defines
EMBER_APPLICATION_HAS_GET_ENDPOINT in its CONFIGURATION_HEADER.
Parameters
index The index of an endpoint (as distinct from its endpoint number). This must be less than
the value of emberEndpointCount.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
22
Returns
The endpoint number for the index’th endpoint.
6.2.3.23 boolean emberGetEndpointDescription ( int8u endpoint, EmberEndpointDescription ∗ result
)
Retrieves the endpoint description for the given endpoint.
This function is provided by the stack, using the data from emberEndpoints, unless the application defines
::EMBER_APPLICATION_HAS_GET_ENDPOINT in its ::CONFIGURATION_HEADER.
Parameters
endpoint The endpoint whose description is to be returned.
result A pointer to the location to which to copy the endpoint description.
Returns
TRUE if the description was copied to result or FALSE if the endpoint is not active.
6.2.3.24 int16u emberGetEndpointCluster ( int8u endpoint, EmberClusterListId listId, int8u listIndex
)
Retrieves a cluster ID from one of the cluster lists associated with the given endpoint.
This function is provided by the stack, using the data from emberEndpoints, unless the application defines
::EMBER_APPLICATION_HAS_GET_ENDPOINT in its CONFIGURATION_HEADER.
Parameters
endpoint The endpoint from which the cluster ID is to be read.
listId The list from which the cluster ID is to be read.
listIndex The index of the desired cluster ID in the list. This value must be less than the length of
the list. The length can be found in the EmberEndpointDescription for this endpoint.
Returns
The cluster ID at position listIndex in the specified endpoint cluster list.
6.2.3.25 boolean emberIsNodeIdValid ( EmberNodeId nodeId )
Determines whether nodeId is valid.
Parameters
nodeId A node ID.
Returns
TRUE if nodeId is valid, FALSE otherwise.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
23
6.2.3.26 EmberNodeId emberLookupNodeIdByEui64 ( EmberEUI64 eui64 )
Returns the node ID that corresponds to the specified EUI64. The node ID is found by searching through
all stack tables for the specified EUI64.
Parameters
eui64 The EUI64 of the node to look up.
Returns
The short ID of the node or EMBER_NULL_NODE_ID if the short ID is not known.
6.2.3.27 EmberStatus emberLookupEui64ByNodeId ( EmberNodeId nodeId, EmberEUI64
eui64Return )
Returns the EUI64 that corresponds to the specified node ID. The EUI64 is found by searching through all
stack tables for the specified node ID.
Parameters
nodeId The short ID of the node to look up.
eui64Return The EUI64 of the node is copied here if it is known.
Returns
An EmberStatus value:
• EMBER_SUCCESS - eui64Return has been set to the EUI64 of the node.
• EMBER_ERR_FATAL - The EUI64 of the node is not known.
6.2.3.28
void emberCounterHandler ( EmberCounterType type, int8u data )
A callback invoked to inform the application of the occurrence of an event defined by EmberCounterType,
for example, transmissions and receptions at different layers of the stack.
The application must define ::EMBER_APPLICATION_HAS_COUNTER_HANDLER in its CONFIGURATION_HEADER to use this. This function may be called in ISR context, so processing should be kept
to a minimum.
Parameters
type The type of the event.
data For transmission events, the number of retries used. For other events, this parameter is
unused and is set to zero.
6.2.3.29 EmberStatus emberGetNeighbor ( int8u index, EmberNeighborTableEntry ∗ result )
Copies a neighbor table entry to the structure that result points to. Neighbor table entries are stored in
ascending order by node id, with all unused entries at the end of the table. The number of active neighbors
EmberZNet 4.7.2 API EM250
120-3016-000-4720
24
can be obtained using emberNeighborCount().
Parameters
index The index of a neighbor table entry.
result A pointer to the location to which to copy the neighbor table entry.
Returns
EMBER_ERR_FATAL if the index is greater or equal to the number of active neighbors, or if the
device is an end device. Returns EMBER_SUCCESS otherwise.
6.2.3.30 EmberStatus emberGetRouteTableEntry ( int8u index, EmberRouteTableEntry ∗ result )
Copies a route table entry to the structure that result points to. Unused route table entries have destination 0xFFFF. The route table size can be obtained via emberRouteTableSize().
Parameters
index The index of a route table entry.
result A pointer to the location to which to copy the route table entry.
Returns
EMBER_ERR_FATAL if the index is out of range or the device is an end device, and EMBER_SUCCESS otherwise.
6.2.3.31 int8u emberStackProfile ( void )
Returns the stack profile of the network which the node has joined.
Returns
stack profile
6.2.3.32 int8u emberTreeDepth ( void )
Returns the depth of the node in the network.
Returns
current depth
6.2.3.33 int8u emberNeighborCount ( void )
Returns the number of active entries in the neighbor table.
Returns
number of active entries in the neighbor table
EmberZNet 4.7.2 API EM250
120-3016-000-4720
25
6.2.3.34 int8u emberRouteTableSize ( void )
Returns the size of the route table.
Returns
the size of the route table
6.2.3.35 int8u emberNextZigbeeSequenceNumber ( void )
Increments and returns the ZigBee sequence number.
Returns
the next ZigBee sequence number
6.2.3.36 EmberStatus emberSetTxPowerMode ( int16u txPowerMode )
Enables boost power mode and/or the alternate transmit path.
Boost power mode is a high performance radio mode which offers increased transmit power and receive
sensitivity at the cost of an increase in power consumption. The alternate transmit output path allows for
simplified connection to an external power amplifier via the RF_TX_ALT_P and RF_TX_ALT_N pins
on the em250. emberInit() calls this function using the power mode and transmitter output settings as
specified in the MFG_PHY_CONFIG token (with each bit inverted so that the default token value of 0xffff
corresponds to normal power mode and bi-directional RF transmitter output). The application only needs
to call emberSetTxPowerMode() if it wishes to use a power mode or transmitter output setting different
from that specified in the MFG_PHY_CONFIG token. After this initial call to emberSetTxPowerMode(),
the stack will automatically maintain the specified power mode configuration across sleep/wake cycles.
Note
This function does not alter the MFG_PHY_CONFIG token. The MFG_PHY_CONFIG token must
be properly configured to ensure optimal radio performance when the standalone bootloader runs in
recovery mode. The MFG_PHY_CONFIG can only be set using external tools. IF YOUR PRODUCT
USES BOOST MODE OR THE ALTERNATE TRANSMITTER OUTPUT AND THE STANDALONE BOOTLOADER YOU MUST SET THE PHY_CONFIG TOKEN INSTEAD OF USING THIS
FUNCTION. Contact support@ember.com for instructions on how to set the MFG_PHY_CONFIG token appropriately.
Parameters
txPowerMode Specifies which of the transmit power mode options are to be activated. This parameter
should be set to one of the literal values described in stack/include/ember-types.h. Any
power option not specified in the txPowerMode parameter will be deactivated.
Returns
EMBER_SUCCESS if successful; an error code otherwise.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
26
6.2.3.37 int16u emberGetTxPowerMode ( void )
Returns the current configuration of boost power mode and alternate transmitter output.
Returns
the current tx power mode.
6.2.3.38 EmberStatus emberSetNodeId ( EmberNodeId nodeId )
It allows to set the short node ID of the node. Notice that it can only be set if the stack is in the INITAL
state.
Parameters
nodeId Specifies the short ID to be assigned to the node.
Returns
EMBER_SUCCESS if successful; an error code otherwise.
6.2.3.39
void emberRadioNeedsCalibratingHandler ( void )
The radio calibration callback function.
The Voltage Controlled Oscillator (VCO) can drift with temperature changes. During every call to emberTick(), the stack will check to see if the VCO has drifted. If the VCO has drifted, the stack will call
emberRadioNeedsCalibratingHandler() to inform the application that it should perform calibration of the
current channel as soon as possible. Calibration can take up to 150ms. The default callback function implementation provided here performs calibration immediately. If the application wishes, it can define its own
callback by defining ::EMBER_APPLICATION_HAS_CUSTOM_RADIO_CALIBRATION_CALLBACK in its CONFIGURATION_HEADER. It can then failsafe any critical processes or peripherals before
calling emberCalibrateCurrentChannel(). The application must call emberCalibrateCurrentChannel() in
response to this callback to maintain expected radio performance.
6.2.3.40
void emberCalibrateCurrentChannel ( void )
Calibrates the current channel. The stack will notify the application of the need for channel calibration via
the emberRadioNeedsCalibratingHandler() callback function during emberTick(). This function should
only be called from within the context of the emberRadioNeedsCalibratingHandler() callback function.
Calibration can take up to 150ms. Note if this function is called when the radio is off, it will turn the radio
on and leave it on.
6.2.3.41
void emberReverseMemCopy ( int8u ∗ dest, const int8u ∗ src, int8u length )
This function copies an array of bytes and reverses the order before writing the data to the destination.
Parameters
dest A pointer to the location where the data will be copied to.
src A pointer to the location where the data will be copied from.
length The length (in bytes) of the data to be copied.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
27
6.2.3.42 XAP2B_PAGEZERO_ON int16u emberFetchLowHighInt16u ( int8u ∗ contents )
Returns the value built from the two int8u values contents[0] and contents[1]. contents[0] is
the low byte.
6.2.3.43 XAP2B_PAGEZERO_OFF void emberStoreLowHighInt16u ( int8u ∗ contents, int16u value )
Stores value in contents[0] and contents[1]. contents[0] is the low byte.
6.2.3.44 int32u emberFetchLowHighInt32u ( int8u ∗ contents )
Returns the value built from the four int8u values contents[0], contents[1], contents[2] and
contents[3]. contents[0] is the low byte.
6.2.3.45 int32u emberFetchHighLowInt32u ( int8u ∗ contents )
Description:
Returns the value built from the four int8u values contents[0], contents[1], contents[2]
and contents[3]. contents[3] is the low byte.
6.2.3.46
void emberStoreLowHighInt32u ( int8u ∗ contents, int32u value )
Stores value in contents[0], contents[1], contents[2] and contents[3]. contents[0] is the
low byte.
6.2.3.47
void emberStoreHighLowInt32u ( int8u ∗ contents, int32u value )
Description:
Stores value in contents[0], contents[1], contents[2] and contents[3]. contents[3]
is the low byte.
6.2.4
Variable Documentation
6.2.4.1
PGM int8u emberStackProfileId[ ]
The application must provide a definition for this variable.
6.2.4.2 int8u emberEndpointCount
The application must provide a definition for this variable.
6.2.4.3 EmberEndpoint emberEndpoints[ ]
If emberEndpointCount is nonzero, the application must provide descriptions for each endpoint.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
28
This can be done either by providing a definition of emberEndpoints or by providing definitions of emberGetEndpoint(), emberGetEndpointDescription() and emberGetEndpointCluster(). Using the array is often
simpler, but consumes large amounts of memory if emberEndpointCount is large.
If the application provides definitions for the three functions, it must define EMBER_APPLICATION_HAS_GET_ENDPOINT in its CONFIGURATION_HEADER.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
29
6.3
Ember Common Data Types
Data Structures
• struct EmberVersion
Version struct containing all version information.
• struct EmberZigbeeNetwork
Defines a ZigBee network and the associated parameters.
• struct EmberNetworkInitStruct
Defines the network initialization configuration that should be used when emberNetworkInitExtended() is
called by the application.
• struct EmberNetworkParameters
Holds network parameters.
• struct EmberApsFrame
An in-memory representation of a ZigBee APS frame of an incoming or outgoing message.
• struct EmberBindingTableEntry
Defines an entry in the binding table.
• struct EmberNeighborTableEntry
Defines an entry in the neighbor table.
• struct EmberRouteTableEntry
Defines an entry in the route table.
• struct EmberMulticastTableEntry
Defines an entry in the multicast table.
• struct EmberEventControl
Control structure for events.
• struct EmberTaskControl
Control structure for tasks.
• struct EmberKeyData
This data structure contains the key data that is passed into various other functions.
• struct EmberCertificateData
This data structure contains the certificate data that is used for Certificate Based Key Exchange (CBKE).
• struct EmberPublicKeyData
This data structure contains the public key data that is used for Certificate Based Key Exchange (CBKE).
• struct EmberPrivateKeyData
This data structure contains the private key data that is used for Certificate Based Key Exchange (CBKE).
• struct EmberSmacData
This data structure contains the Shared Message Authentication Code (SMAC) data that is used for Certificate Based Key Exchange (CBKE).
• struct EmberSignatureData
This data structure contains a DSA signature. It is the bit concatenation of the ’r’ and ’s’ components of the
signature.
• struct EmberMessageDigest
This data structure contains an AES-MMO Hash (the message digest).
• struct EmberAesMmoHashContext
This data structure contains the context data when calculating an AES MMO hash (message digest).
• struct EmberInitialSecurityState
This describes the Initial Security features and requirements that will be used when forming or joining the
network.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
30
• struct EmberCurrentSecurityState
This describes the security features used by the stack for a joined device.
• struct EmberKeyStruct
This describes a one of several different types of keys and its associated data.
• struct EmberMfgSecurityStruct
This structure is used to get/set the security config that is stored in manufacturing tokens.
• struct EmberMacFilterMatchStruct
This structure indicates a matching raw MAC message has been received by the application configured
MAC 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 ∗ control
void(∗ handler )(void)
} EmberEventData
• typedef int16u EmberMacFilterMatchData
• typedef int8u EmberLibraryStatus
EmberZNet 4.7.2 API EM250
120-3016-000-4720
31
Enumerations
• enum EmberNodeType {
EMBER_UNKNOWN_DEVICE, EMBER_COORDINATOR, EMBER_ROUTER, EMBER_END_DEVICE,
EMBER_SLEEPY_END_DEVICE, EMBER_MOBILE_END_DEVICE }
• enum EmberNetworkInitBitmask { EMBER_NETWORK_INIT_NO_OPTIONS, EMBER_NETWORK_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_ROUTE_DISCOVERY, EMBER_APS_OPTION_SOURCE_EUI64, EMBER_APS_OPTION_DESTINATION_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_INCOMING_MULTICAST, EMBER_INCOMING_MULTICAST_LOOPBACK,
EMBER_INCOMING_BROADCAST, EMBER_INCOMING_BROADCAST_LOOPBACK }
• enum EmberOutgoingMessageType {
EMBER_OUTGOING_DIRECT, EMBER_OUTGOING_VIA_ADDRESS_TABLE, EMBER_OUTGOING_VIA_BINDING, EMBER_OUTGOING_MULTICAST,
EMBER_OUTGOING_BROADCAST }
• enum EmberNetworkStatus {
EMBER_NO_NETWORK, EMBER_JOINING_NETWORK, EMBER_JOINED_NETWORK, EMBER_JOINED_NETWORK_NO_PARENT,
EMBER_LEAVING_NETWORK }
• enum EmberNetworkScanType { EMBER_ENERGY_SCAN, EMBER_ACTIVE_SCAN }
• enum EmberBindingType { EMBER_UNUSED_BINDING, EMBER_UNICAST_BINDING, EMBER_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_UNSECURED_REJOIN,
EMBER_HIGH_SECURITY_SECURED_REJOIN, EMBER_HIGH_SECURITY_UNSECURED_JOIN, EMBER_HIGH_SECURITY_UNSECURED_REJOIN, EMBER_REJOIN_REASON_NONE,
EMBER_REJOIN_DUE_TO_NWK_KEY_UPDATE, EMBER_REJOIN_DUE_TO_LEAVE_MESSAGE, EMBER_REJOIN_DUE_TO_NO_PARENT, EMBER_REJOIN_DUE_TO_ZLL_TOUCHLINK,
EMBER_REJOIN_DUE_TO_APP_EVENT_5, EMBER_REJOIN_DUE_TO_APP_EVENT_4, EMBER_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_UNSECURED_REJOIN,
EMBER_HIGH_SECURITY_SECURED_REJOIN, EMBER_HIGH_SECURITY_UNSECURED_JOIN, EMBER_HIGH_SECURITY_UNSECURED_REJOIN, EMBER_REJOIN_REASON_NOEmberZNet 4.7.2 API EM250
120-3016-000-4720
32
•
•
•
•
•
•
•
NE,
EMBER_REJOIN_DUE_TO_NWK_KEY_UPDATE, EMBER_REJOIN_DUE_TO_LEAVE_MESSAGE, EMBER_REJOIN_DUE_TO_NO_PARENT, EMBER_REJOIN_DUE_TO_ZLL_TOUCHLINK,
EMBER_REJOIN_DUE_TO_APP_EVENT_5, EMBER_REJOIN_DUE_TO_APP_EVENT_4, EMBER_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, EMBER_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_BROADCAST, EMBER_COUNTER_MAC_RX_UNICAST, EMBER_COUNTER_MAC_TX_UNICAST_SUCCESS,
EMBER_COUNTER_MAC_TX_UNICAST_RETRY, EMBER_COUNTER_MAC_TX_UNICAST_FAILED, EMBER_COUNTER_APS_DATA_RX_BROADCAST, EMBER_COUNTER_APS_DATA_TX_BROADCAST,
EMBER_COUNTER_APS_DATA_RX_UNICAST, EMBER_COUNTER_APS_DATA_TX_UNICAST_SUCCESS, EMBER_COUNTER_APS_DATA_TX_UNICAST_RETRY, EMBER_COUNTER_APS_DATA_TX_UNICAST_FAILED,
EMBER_COUNTER_ROUTE_DISCOVERY_INITIATED, EMBER_COUNTER_NEIGHBOR_ADDED, EMBER_COUNTER_NEIGHBOR_REMOVED, EMBER_COUNTER_NEIGHBOR_STALE,
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_COUNTER_FAILURE, EMBER_COUNTER_APS_FRAME_COUNTER_FAILURE, EMBER_COUNTER_ASH_XOFF,
EMBER_COUNTER_APS_LINK_KEY_NOT_AUTHORIZED, EMBER_COUNTER_NWK_DECRYPTION_FAILURE, EMBER_COUNTER_APS_DECRYPTION_FAILURE, EMBER_COUNTER_ALLOCATE_PACKET_BUFFER_FAILURE,
EMBER_COUNTER_RELAYED_UNICAST, EMBER_COUNTER_PHY_TO_MAC_QUEUE_LIMIT_REACHED, EMBER_COUNTER_PACKET_VALIDATE_LIBRARY_DROPPED_COUNT, EMBER_COUNTER_TYPE_COUNT }
enum EmberInitialSecurityBitmask {
EMBER_DISTRIBUTED_TRUST_CENTER_MODE, EMBER_TRUST_CENTER_GLOBAL_LINK_KEY, EMBER_PRECONFIGURED_NETWORK_KEY_MODE, EMBER_HAVE_TRUST_CENTER_EUI64,
EMBER_TRUST_CENTER_USES_HASHED_LINK_KEY, EMBER_HAVE_PRECONFIGURED_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_NWK_LEAVE_REQUEST_NOT_ALLOWED }
enum EmberCurrentSecurityBitmask {
EMBER_STANDARD_SECURITY_MODE_, EMBER_DISTRIBUTED_TRUST_CENTER_MODE_, EMBER_TRUST_CENTER_GLOBAL_LINK_KEY_, EMBER_HAVE_TRUST_CENTER_LINK_KEY,
EMBER_TRUST_CENTER_USES_HASHED_LINK_KEY_ }
EmberZNet 4.7.2 API EM250
120-3016-000-4720
33
• enum EmberKeyStructBitmask {
EMBER_KEY_HAS_SEQUENCE_NUMBER, EMBER_KEY_HAS_OUTGOING_FRAME_COUNTER, EMBER_KEY_HAS_INCOMING_FRAME_COUNTER, EMBER_KEY_HAS_PARTNER_EUI64,
EMBER_KEY_IS_AUTHORIZED, EMBER_KEY_PARTNER_IS_SLEEPY }
• enum EmberKeyType {
EMBER_TRUST_CENTER_LINK_KEY, EMBER_TRUST_CENTER_MASTER_KEY, EMBER_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, EMBER_TRUST_CENTER_LINK_KEY_ESTABLISHED, EMBER_KEY_ESTABLISHMENT_TIMEOUT,
EMBER_KEY_TABLE_FULL, EMBER_TC_RESPONDED_TO_KEY_REQUEST, EMBER_TC_APP_KEY_SENT_TO_REQUESTER, EMBER_TC_RESPONSE_TO_KEY_REQUEST_FAILED,
EMBER_TC_REQUEST_KEY_TYPE_NOT_SUPPORTED, EMBER_TC_NO_LINK_KEY_FOR_REQUESTER, EMBER_TC_REQUESTER_EUI64_UNKNOWN, EMBER_TC_RECEIVED_FIRST_APP_KEY_REQUEST,
EMBER_TC_TIMEOUT_WAITING_FOR_SECOND_APP_KEY_REQUEST, EMBER_TC_NON_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_KEY_REQUESTS }
• enum EmberKeySettings { EMBER_KEY_PERMISSIONS_NONE, EMBER_KEY_PERMISSIONS_READING_ALLOWED, EMBER_KEY_PERMISSIONS_HASHING_ALLOWED }
• enum EmberMacPassthroughType {
EMBER_MAC_PASSTHROUGH_NONE, EMBER_MAC_PASSTHROUGH_SE_INTERPAN, EMBER_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_TYPE_GA }
• enum EmberLeaveRequestFlags { EMBER_ZIGBEE_LEAVE_AND_REJOIN, EMBER_ZIGBEE_LEAVE_AND_REMOVE_CHILDREN }
EmberZNet 4.7.2 API EM250
120-3016-000-4720
34
• enum EmberLeaveReason {
EMBER_LEAVE_REASON_NONE, EMBER_LEAVE_DUE_TO_NWK_LEAVE_MESSAGE, EMBER_LEAVE_DUE_TO_APS_REMOVE_MESSAGE, EMBER_LEAVE_DUE_TO_ZDO_LEAVE_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. Broadcasts
are normally sent only to routers. Broadcasts can also be forwarded to end devices, either all of them or
only those that do not sleep. Broadcasting to end devices is both significantly more resource-intensive and
significantly 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 EM250
120-3016-000-4720
35
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 ZigBee
Device Profile.
• enum EmberZdoStatus {
EMBER_ZDP_SUCCESS, EMBER_ZDP_INVALID_REQUEST_TYPE, EMBER_ZDP_DEVICE_NOT_FOUND, EMBER_ZDP_INVALID_ENDPOINT,
EMBER_ZDP_NOT_ACTIVE, EMBER_ZDP_NOT_SUPPORTED, EMBER_ZDP_TIMEOUT, EMBER_ZDP_NO_MATCH,
EMBER_ZDP_NO_ENTRY, EMBER_ZDP_NO_DESCRIPTOR, EMBER_ZDP_INSUFFICIENT_SPACE, EMBER_ZDP_NOT_PERMITTED,
EMBER_ZDP_TABLE_FULL, EMBER_ZDP_NOT_AUTHORIZED, EMBER_NWK_ALREADY_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 the
messages.
Note that each message starts with a 1-byte transaction sequence number. This sequence number is used to
match a response command frame to the request frame that it is replying to. The application shall maintain
a 1-byte counter that is copied into this field and incremented by one for each command sent. When a value
of 0xff is reached, the next command shall re-start the counter with a value of 0x00
EmberZNet 4.7.2 API EM250
120-3016-000-4720
36
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>
@code
Request: <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 Descriptor
Available: 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 incoming
transfer 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>
@code
Request: <transaction sequence number: 1> <node ID:2>
Response: <transaction sequence number: 1> <status:1> <node ID:2>
<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 EM250
120-3016-000-4720
37
• #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 request
services 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 EM250
120-3016-000-4720
38
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_BINDING_TABLE_CACHE,
EMBER_ZDP_PRIMARY_DISCOVERY_CACHE, EMBER_ZDP_SECONDARY_DISCOVERY_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 the
device of interest itself, respond. The requesting device can then direct any service discovery requests to
the 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 destination 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>
Response: <transaction sequence number: 1> <status: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 EM250
120-3016-000-4720
39
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
0x01
0x02
0x03
rx mode
0x0C
0x00 off when idle
0x04 on when idle
0x08 unknown
relationship
0x70
0x00
0x10
0x20
0x30
0x40
reserved
0x10
coordinator
router
end device
unknown
parent
child
sibling
other
previous child
The permit-joining byte has the following fields
Name
Mask
permit joining
0x03
reserved
0xFC
Values
0x00 not accepting join requests
0x01 accepting join requests
0x02 unknown
• #define LQI_TABLE_REQUEST
• #define LQI_TABLE_RESPONSE
Routing Table Request / Response
Request: <transaction sequence number: 1> <start index:1>
Response: <transaction sequence number: 1> <status:1>
<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
status
0x07
flags
0x38
Values
0x00
0x01
0x02
0x03
0x04
active
discovery underway
discovery failed
inactive
validation underway
0x08 memory constrained
0x10 many-to-one
0x20 route record required
reserved
EmberZNet 4.7.2 API EM250
0xC0
120-3016-000-4720
40
• #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 be
included. If Dest. Address Mode = 0x01, then the Short Dest. Address will be used and there will be
no 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 children
0x80 rejoin
Response: <transaction sequence number: 1> <status:1>
•
•
•
•
#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>
Response: <transaction sequence number: 1> <status: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 but
not ’manager’. Perform ’count’ scans of the given duration on the
given channels.
If duration is 0xFE, then ’channels’ should have a single channel
and ’count’ and ’manager’ are not present. Switch to the indicated
channel.
If duration is 0xFF, then ’count’ is not present. Set the active
channels and the network manager ID to the values given.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
41
Unicast requests always get a response, which is INVALID_REQUEST if the
duration 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 the
following configuration definitions:
EMBER_APPLICATION_RECEIVES_SUPPORTED_ZDO_REQUESTS EMBER_APPLICATION_HANDLES_UNSUPPORTED_ZDO_REQUESTS EMBER_APPLICATION_HANDLES_ENDPOINT_ZDO_REQUESTS EMBER_APPLICATION_HANDLES_BINDING_ZDO_REQUESTS
See ember-configuration.h for more information.
• enum EmberZdoConfigurationFlags { EMBER_APP_RECEIVES_SUPPORTED_ZDO_REQUESTS, EMBER_APP_HANDLES_UNSUPPORTED_ZDO_REQUESTS, EMBER_APP_HANDLES_ZDO_ENDPOINT_REQUESTS, EMBER_APP_HANDLES_ZDO_BINDING_REQUESTS }
6.3.1
Detailed Description
See ember-types.h for source code.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
42
6.3.2
Macro Definition Documentation
6.3.2.1
#define EUI64 SIZE
Size of EUI64 (an IEEE address) in bytes (8).
Definition at line 72 of file ember-types.h.
6.3.2.2
#define EXTENDED PAN ID SIZE
Size of an extended PAN identifier in bytes (8).
Definition at line 77 of file ember-types.h.
6.3.2.3
#define EMBER ENCRYPTION KEY SIZE
Size of an encryption key in bytes (16).
Definition at line 82 of file ember-types.h.
6.3.2.4
#define EMBER CERTIFICATE SIZE
Size of Implicit Certificates used for Certificate Based Key Exchange.
Definition at line 88 of file ember-types.h.
6.3.2.5
#define EMBER PUBLIC KEY SIZE
Size of Public Keys used in Elliptical Cryptography ECMQV algorithms.
Definition at line 93 of file ember-types.h.
6.3.2.6
#define EMBER PRIVATE KEY SIZE
Size of Private Keys used in Elliptical Cryptography ECMQV algorithms.
Definition at line 98 of file ember-types.h.
6.3.2.7
#define EMBER SMAC SIZE
Size of the SMAC used in Elliptical Cryptography ECMQV algorithms.
Definition at line 103 of file ember-types.h.
6.3.2.8
#define EMBER SIGNATURE SIZE
Size of the DSA signature used in Elliptical Cryptography Digital Signature Algorithms.
Definition at line 109 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
43
6.3.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.
Definition at line 114 of file ember-types.h.
6.3.2.10
#define EMBERSTATUS TYPE
Return type for Ember functions.
Definition at line 121 of file ember-types.h.
6.3.2.11
#define EMBER MAX 802 15 4 CHANNEL NUMBER
The maximum 802.15.4 channel number is 26.
Definition at line 157 of file ember-types.h.
6.3.2.12
#define EMBER MIN 802 15 4 CHANNEL NUMBER
The minimum 802.15.4 channel number is 11.
Definition at line 162 of file ember-types.h.
6.3.2.13
#define EMBER NUM 802 15 4 CHANNELS
There are sixteen 802.15.4 channels.
Definition at line 167 of file ember-types.h.
6.3.2.14
#define EMBER ALL 802 15 4 CHANNELS MASK
Bitmask to scan all 802.15.4 channels.
Definition at line 173 of file ember-types.h.
6.3.2.15
#define EMBER ZIGBEE COORDINATOR ADDRESS
The network ID of the coordinator in a ZigBee network is 0x0000.
Definition at line 178 of file ember-types.h.
6.3.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 node
ID.
Definition at line 184 of file ember-types.h.
6.3.2.17
#define EMBER NULL BINDING
A distinguished binding index used to indicate the absence of a binding.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
44
Definition at line 190 of file ember-types.h.
6.3.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 remote
node ID from the binding table. It indicates that address or binding table entry is not in use.
Definition at line 201 of file ember-types.h.
6.3.2.19
#define EMBER MULTICAST NODE ID
A distinguished network ID that will never be assigned to any node. This value is returned when getting
the remote node ID from the binding table and the given binding table index refers to a multicast binding
entry.
Definition at line 209 of file ember-types.h.
6.3.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 the
remote node ID from the address or binding tables. It indicates that the address or binding table entry is
currently in use but the node ID corresponding to the EUI64 in the table is currently unknown.
Definition at line 218 of file ember-types.h.
6.3.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 the
remote node ID from the address or binding tables. It indicates that the address or binding table entry is
currently in use and network address discovery is underway.
Definition at line 227 of file ember-types.h.
6.3.2.22
#define EMBER NULL ADDRESS TABLE INDEX
A distinguished address table index used to indicate the absence of an address table entry.
Definition at line 233 of file ember-types.h.
6.3.2.23
#define EMBER ZDO ENDPOINT
The endpoint where the ZigBee Device Object (ZDO) resides.
Definition at line 238 of file ember-types.h.
6.3.2.24
#define EMBER BROADCAST ENDPOINT
The broadcast endpoint, as defined in the ZigBee spec.
Definition at line 243 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
45
6.3.2.25
#define EMBER ZDO PROFILE ID
The profile ID used by the ZigBee Device Object (ZDO).
Definition at line 248 of file ember-types.h.
6.3.2.26
#define EMBER WILDCARD PROFILE ID
The profile ID used to address all the public profiles.
Definition at line 253 of file ember-types.h.
6.3.2.27
#define EMBER MAXIMUM STANDARD PROFILE ID
The maximum value for a profile ID in the standard profile range.
Definition at line 258 of file ember-types.h.
6.3.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. This
is the maximum length it will persist, in quarter seconds.
Definition at line 266 of file ember-types.h.
6.3.2.29
#define EMBER BROADCAST ADDRESS
Broadcast to all routers.
Definition at line 315 of file ember-types.h.
6.3.2.30
#define EMBER RX ON WHEN IDLE BROADCAST ADDRESS
Broadcast to all non-sleepy devices.
Definition at line 317 of file ember-types.h.
6.3.2.31
#define EMBER SLEEPY BROADCAST ADDRESS
Broadcast to all devices, including sleepy end devices.
Definition at line 319 of file ember-types.h.
6.3.2.32
#define EMBER LOW RAM CONCENTRATOR
A concentrator with insufficient memory to store source routes for the entire network. Route records are
sent to the concentrator prior to every inbound APS unicast.
Definition at line 586 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
46
6.3.2.33
#define EMBER HIGH RAM CONCENTRATOR
A concentrator with sufficient memory to store source routes for the entire network. Remote nodes stop
sending route records once the concentrator has successfully received one.
Definition at line 591 of file ember-types.h.
6.3.2.34
#define EMBER JOIN DECISION STRINGS
@ brief Defines the CLI enumerations for the EmberJoinDecision enum
Definition at line 619 of file ember-types.h.
6.3.2.35
#define EMBER DEVICE UPDATE STRINGS
@ brief Defines the CLI enumerations for the EmberDeviceUpdate enum.
Definition at line 654 of file ember-types.h.
6.3.2.36
#define emberInitializeNetworkParameters( parameters )
Definition at line 826 of file ember-types.h.
6.3.2.37
#define EMBER COUNTER STRINGS
@ brief Defines the CLI enumerations for the EmberCounterType enum.
Definition at line 1086 of file ember-types.h.
6.3.2.38
#define EMBER TX POWER MODE DEFAULT
The application should call emberSetTxPowerMode() with the txPowerMode parameter set to this value to
disable all power mode options, resulting in normal power mode and bi-directional RF transmitter output.
Definition at line 1194 of file ember-types.h.
6.3.2.39
#define EMBER TX POWER MODE BOOST
The application should call emberSetTxPowerMode() with the txPowerMode parameter set to this value to
enable boost power mode.
Definition at line 1198 of file ember-types.h.
6.3.2.40
#define EMBER TX POWER MODE ALTERNATE
The application should call emberSetTxPowerMode() with the txPowerMode parameter set to this value to
enable the alternate transmitter output.
Definition at line 1203 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
47
6.3.2.41
#define EMBER TX POWER MODE BOOST AND ALTERNATE
The application should call emberSetTxPowerMode() with the txPowerMode parameter set to this value to
enable both boost mode and the alternate transmitter output.
Definition at line 1208 of file ember-types.h.
6.3.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.
Definition at line 1232 of file ember-types.h.
6.3.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 precise
time can be specified using the configuration parameter EMBER_INDIRECT_TRANSMISSION_TIMEOUT). 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 header
information 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 for
alarms 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 source
and destination endpoints are ignored.
Broadcast alarms must use EMBER_BROADCAST_ALARM_CLUSTER as the cluster id and messages
with this cluster ID must be sent to EMBER_RX_ON_WHEN_IDLE_BROADCAST_ADDRESS. A broadcast 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 emberIncomingMessageHandler(). If the receiving node has sleepy end device children, the payload of the alarm is saved and then
forwarded to those children when they poll for data. When a sleepy child polls its parent, it receives only
the most recently arrived broadcast alarm. If the child has already received the most recent broadcast alarm
it is not forwarded again.
Definition at line 1272 of file ember-types.h.
6.3.2.44
#define EMBER UNICAST ALARM CLUSTER
Unicast alarms must use EMBER_UNICAST_ALARM_CLUSTER as the cluster id and messages with
this cluster ID must be unicast.
The payload of a unicast alarm consists of three one-byte length fields followed by three variable length
fields.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
48
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 emberIncomingMessageHandler(). When a node receives a unicast alarm message whose destination is a sleepy end
device child of that node, the payload of the message is saved until the child polls for data. To conserve
memory, the values of the length fields are not saved. The alarm will be forwarded to the child using the
EMBER_CACHED_UNICAST_ALARM_CLUSTER cluster ID.
If a unicast alarm arrives when a previous one is still pending, the two payloads are combined. This
combining is controlled by the length fields in the arriving message. The incoming flag bytes are or’ed with
those of the pending message. If the priority field is not present, or if it is present and the incoming priority
value 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 will
be used for all unicast alarm message sent to a particular device.
Definition at line 1310 of file ember-types.h.
6.3.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 device
using the EMBER_CACHED_UNICAST_ALARM_CLUSTER cluster ID. The payload consists of three
variable 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 unicast
alarms sent to a particular device.
Definition at line 1327 of file ember-types.h.
6.3.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/countersota.h.
Definition at line 1332 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
49
6.3.2.47
#define EMBER REPORT COUNTERS RESPONSE
The cluster id used to respond to an EMBER_REPORT_COUNTERS_REQUEST.
Definition at line 1335 of file ember-types.h.
6.3.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 will
also reset its clusters to zero after a successful response. See app/util/counters/counters-ota.h.
Definition at line 1341 of file ember-types.h.
6.3.2.49
#define EMBER REPORT AND CLEAR COUNTERS RESPONSE
The cluster id used to respond to an EMBER_REPORT_AND_CLEAR_COUNTERS_REQUEST.
Definition at line 1344 of file ember-types.h.
6.3.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 upgrade
devices with Smart Energy Certificates and other security data.
Definition at line 1350 of file ember-types.h.
6.3.2.51
#define EMBER STANDARD SECURITY MODE
This is an EmberInitialSecurityBitmask value but it does not actually set anything. It is the default mode
used by the ZigBee Pro stack. It is defined here so that no legacy code is broken by referencing it.
Definition at line 1414 of file ember-types.h.
6.3.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 the
network.
Definition at line 1419 of file ember-types.h.
6.3.2.53
#define EMBER NO TRUST CENTER MODE
This is the legacy name for the Distributed Trust Center Mode.
Definition at line 1559 of file ember-types.h.
6.3.2.54
#define EMBER GLOBAL LINK KEY
This is the legacy name for the Trust Center Global Link Key.
Definition at line 1563 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
50
6.3.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.
Definition at line 1901 of file ember-types.h.
6.3.2.56
#define EMBER MAC FILTER MATCH ENABLED MASK
Definition at line 1940 of file ember-types.h.
6.3.2.57
#define EMBER MAC FILTER MATCH ON PAN DEST MASK
Definition at line 1941 of file ember-types.h.
6.3.2.58
#define EMBER MAC FILTER MATCH ON PAN SOURCE MASK
Definition at line 1942 of file ember-types.h.
6.3.2.59
#define EMBER MAC FILTER MATCH ON DEST MASK
Definition at line 1943 of file ember-types.h.
6.3.2.60
#define EMBER MAC FILTER MATCH ON SOURCE MASK
Definition at line 1944 of file ember-types.h.
6.3.2.61
#define EMBER MAC FILTER MATCH ENABLED
Definition at line 1947 of file ember-types.h.
6.3.2.62
#define EMBER MAC FILTER MATCH DISABLED
Definition at line 1948 of file ember-types.h.
6.3.2.63
#define EMBER MAC FILTER MATCH ON PAN DEST NONE
Definition at line 1951 of file ember-types.h.
6.3.2.64
#define EMBER MAC FILTER MATCH ON PAN DEST LOCAL
Definition at line 1952 of file ember-types.h.
6.3.2.65
#define EMBER MAC FILTER MATCH ON PAN DEST BROADCAST
Definition at line 1953 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
51
6.3.2.66
#define EMBER MAC FILTER MATCH ON PAN SOURCE NONE
Definition at line 1956 of file ember-types.h.
6.3.2.67
#define EMBER MAC FILTER MATCH ON PAN SOURCE NON LOCAL
Definition at line 1957 of file ember-types.h.
6.3.2.68
#define EMBER MAC FILTER MATCH ON PAN SOURCE LOCAL
Definition at line 1958 of file ember-types.h.
6.3.2.69
#define EMBER MAC FILTER MATCH ON DEST BROADCAST SHORT
Definition at line 1961 of file ember-types.h.
6.3.2.70
#define EMBER MAC FILTER MATCH ON DEST UNICAST SHORT
Definition at line 1962 of file ember-types.h.
6.3.2.71
#define EMBER MAC FILTER MATCH ON DEST UNICAST LONG
Definition at line 1963 of file ember-types.h.
6.3.2.72
#define EMBER MAC FILTER MATCH ON SOURCE LONG
Definition at line 1966 of file ember-types.h.
6.3.2.73
#define EMBER MAC FILTER MATCH ON SOURCE SHORT
Definition at line 1967 of file ember-types.h.
6.3.2.74
#define EMBER MAC FILTER MATCH END
Definition at line 1970 of file ember-types.h.
6.3.2.75
#define NETWORK ADDRESS REQUEST
Definition at line 2054 of file ember-types.h.
6.3.2.76
#define NETWORK ADDRESS RESPONSE
Definition at line 2055 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
52
6.3.2.77
#define IEEE ADDRESS REQUEST
Definition at line 2056 of file ember-types.h.
6.3.2.78
#define IEEE ADDRESS RESPONSE
Definition at line 2057 of file ember-types.h.
6.3.2.79
#define NODE DESCRIPTOR REQUEST
Definition at line 2085 of file ember-types.h.
6.3.2.80
#define NODE DESCRIPTOR RESPONSE
Definition at line 2086 of file ember-types.h.
6.3.2.81
#define POWER DESCRIPTOR REQUEST
Definition at line 2099 of file ember-types.h.
6.3.2.82
#define POWER DESCRIPTOR RESPONSE
Definition at line 2100 of file ember-types.h.
6.3.2.83
#define SIMPLE DESCRIPTOR REQUEST
Definition at line 2116 of file ember-types.h.
6.3.2.84
#define SIMPLE DESCRIPTOR RESPONSE
Definition at line 2117 of file ember-types.h.
6.3.2.85
#define ACTIVE ENDPOINTS REQUEST
Definition at line 2128 of file ember-types.h.
6.3.2.86
#define ACTIVE ENDPOINTS RESPONSE
Definition at line 2129 of file ember-types.h.
6.3.2.87
#define MATCH DESCRIPTORS REQUEST
Definition at line 2143 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
53
6.3.2.88
#define MATCH DESCRIPTORS RESPONSE
Definition at line 2144 of file ember-types.h.
6.3.2.89
#define DISCOVERY CACHE REQUEST
Definition at line 2156 of file ember-types.h.
6.3.2.90
#define DISCOVERY CACHE RESPONSE
Definition at line 2157 of file ember-types.h.
6.3.2.91
#define END DEVICE ANNOUNCE
Definition at line 2168 of file ember-types.h.
6.3.2.92
#define END DEVICE ANNOUNCE RESPONSE
Definition at line 2169 of file ember-types.h.
6.3.2.93
#define SYSTEM SERVER DISCOVERY REQUEST
Definition at line 2183 of file ember-types.h.
6.3.2.94
#define SYSTEM SERVER DISCOVERY RESPONSE
Definition at line 2184 of file ember-types.h.
6.3.2.95
#define FIND NODE CACHE REQUEST
Definition at line 2221 of file ember-types.h.
6.3.2.96
#define FIND NODE CACHE RESPONSE
Definition at line 2222 of file ember-types.h.
6.3.2.97
#define END DEVICE BIND REQUEST
Definition at line 2235 of file ember-types.h.
6.3.2.98
#define END DEVICE BIND RESPONSE
Definition at line 2236 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
54
6.3.2.99
#define UNICAST BINDING
Definition at line 2256 of file ember-types.h.
6.3.2.100
#define UNICAST MANY TO ONE BINDING
Definition at line 2257 of file ember-types.h.
6.3.2.101
#define MULTICAST BINDING
Definition at line 2258 of file ember-types.h.
6.3.2.102
#define BIND REQUEST
Definition at line 2260 of file ember-types.h.
6.3.2.103
#define BIND RESPONSE
Definition at line 2261 of file ember-types.h.
6.3.2.104
#define UNBIND REQUEST
Definition at line 2262 of file ember-types.h.
6.3.2.105
#define UNBIND RESPONSE
Definition at line 2263 of file ember-types.h.
6.3.2.106
#define LQI TABLE REQUEST
Definition at line 2313 of file ember-types.h.
6.3.2.107
#define LQI TABLE RESPONSE
Definition at line 2314 of file ember-types.h.
6.3.2.108
#define ROUTING TABLE REQUEST
Definition at line 2349 of file ember-types.h.
6.3.2.109
#define ROUTING TABLE RESPONSE
Definition at line 2350 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
55
6.3.2.110
#define BINDING TABLE REQUEST
Definition at line 2371 of file ember-types.h.
6.3.2.111
#define BINDING TABLE RESPONSE
Definition at line 2372 of file ember-types.h.
6.3.2.112
#define LEAVE REQUEST
Definition at line 2385 of file ember-types.h.
6.3.2.113
#define LEAVE RESPONSE
Definition at line 2386 of file ember-types.h.
6.3.2.114
#define LEAVE REQUEST REMOVE CHILDREN FLAG
Definition at line 2388 of file ember-types.h.
6.3.2.115
#define LEAVE REQUEST REJOIN FLAG
Definition at line 2389 of file ember-types.h.
6.3.2.116
#define PERMIT JOINING REQUEST
Definition at line 2400 of file ember-types.h.
6.3.2.117
#define PERMIT JOINING RESPONSE
Definition at line 2401 of file ember-types.h.
6.3.2.118
#define NWK UPDATE REQUEST
Definition at line 2429 of file ember-types.h.
6.3.2.119
#define NWK UPDATE RESPONSE
Definition at line 2430 of file ember-types.h.
6.3.2.120
#define COMPLEX DESCRIPTOR REQUEST
Definition at line 2436 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
56
6.3.2.121
#define COMPLEX DESCRIPTOR RESPONSE
Definition at line 2437 of file ember-types.h.
6.3.2.122
#define USER DESCRIPTOR REQUEST
Definition at line 2438 of file ember-types.h.
6.3.2.123
#define USER DESCRIPTOR RESPONSE
Definition at line 2439 of file ember-types.h.
6.3.2.124
#define DISCOVERY REGISTER REQUEST
Definition at line 2440 of file ember-types.h.
6.3.2.125
#define DISCOVERY REGISTER RESPONSE
Definition at line 2441 of file ember-types.h.
6.3.2.126
#define USER DESCRIPTOR SET
Definition at line 2442 of file ember-types.h.
6.3.2.127
#define USER DESCRIPTOR CONFIRM
Definition at line 2443 of file ember-types.h.
6.3.2.128
#define NETWORK DISCOVERY REQUEST
Definition at line 2444 of file ember-types.h.
6.3.2.129
#define NETWORK DISCOVERY RESPONSE
Definition at line 2445 of file ember-types.h.
6.3.2.130
#define DIRECT JOIN REQUEST
Definition at line 2446 of file ember-types.h.
6.3.2.131
#define DIRECT JOIN RESPONSE
Definition at line 2447 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
57
6.3.2.132
#define CLUSTER ID RESPONSE MINIMUM
Definition at line 2450 of file ember-types.h.
6.3.3
Typedef Documentation
6.3.3.1
typedef int8u EmberStatus
Size of EUI64 (an IEEE address) in bytes (8).
Definition at line 122 of file ember-types.h.
6.3.3.2
typedef int8u EmberEUI64[EUI64_SIZE]
EUI 64-bit ID (an IEEE address).
Definition at line 128 of file ember-types.h.
6.3.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.
Definition at line 139 of file ember-types.h.
6.3.3.4
typedef int16u EmberNodeId
16-bit ZigBee network address.
Definition at line 144 of file ember-types.h.
6.3.3.5
typedef int16u EmberMulticastId
16-bit ZigBee multicast group identifier.
Definition at line 147 of file ember-types.h.
6.3.3.6
typedef int16u EmberPanId
802.15.4 PAN ID.
Definition at line 152 of file ember-types.h.
6.3.3.7
typedef int8u EmberTaskId
brief An identifier for a task
Definition at line 1121 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
58
6.3.3.8
typedef { ... } EmberEventData
6.3.3.9
typedef int16u EmberMacFilterMatchData
This is a bitmask describing a filter for MAC data messages that the stack should accept and passthrough
to the application.
Definition at line 1938 of file ember-types.h.
6.3.3.10
typedef int8u EmberLibraryStatus
This indicates the presence, absence, or status of an Ember stack library.
Definition at line 1985 of file ember-types.h.
6.3.4
Enumeration Type Documentation
6.3.4.1
enum EmberVersionType
Type of Ember software version.
Enumerator:
EMBER_VERSION_TYPE_PRE_RELEASE
EMBER_VERSION_TYPE_GA
Definition at line 37 of file ember-types.h.
6.3.4.2
enum EmberLeaveRequestFlags
Size of EUI64 (an IEEE address) in bytes (8).
Enumerator:
EMBER_ZIGBEE_LEAVE_AND_REJOIN Leave and rejoin
EMBER_ZIGBEE_LEAVE_AND_REMOVE_CHILDREN Send all children leave command
Definition at line 270 of file ember-types.h.
6.3.4.3
enum EmberLeaveReason
Size of EUI64 (an IEEE address) in bytes (8).
Enumerator:
EMBER_LEAVE_REASON_NONE
EMBER_LEAVE_DUE_TO_NWK_LEAVE_MESSAGE
EMBER_LEAVE_DUE_TO_APS_REMOVE_MESSAGE
EMBER_LEAVE_DUE_TO_ZDO_LEAVE_MESSAGE
EMBER_LEAVE_DUE_TO_ZLL_TOUCHLINK
EMBER_LEAVE_DUE_TO_APP_EVENT_1
Definition at line 284 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
59
6.3.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. The
application must call emberPollForData() to receive messages.
EMBER_MOBILE_END_DEVICE A sleepy end device that can move through the network.
Definition at line 329 of file ember-types.h.
6.3.4.5
enum EmberNetworkInitBitmask
Defines the options that should be used when initializing the node’s network configuration.
Enumerator:
EMBER_NETWORK_INIT_NO_OPTIONS
EMBER_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.
Definition at line 369 of file ember-types.h.
6.3.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 be
combined with any other options.
Enumerator:
EMBER_APS_OPTION_NONE No options.
EMBER_APS_OPTION_DSA_SIGN This signs the application layer message body (APS Frame
not included) and appends the ECDSA signature to the end of the message. Needed by Smart
Energy 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 APS
layer. Note that when passing a buffer to the stack for DSA signing, the final byte in the buffer has
special significance as an indicator of how many leading bytes should be ignored for signature
purposes. Refer to API documentation of emberDsaSign() or the dsaSign EZSP command for
further details about this requirement.
EMBER_APS_OPTION_ENCRYPTION Send the message using APS Encryption, using the Link
Key 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 mesh
stack, this option and the enable route discovery option must be enabled for an existing route to
be repaired automatically.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
60
EMBER_APS_OPTION_ENABLE_ROUTE_DISCOVERY Send the message with the NWK ’enable route discovery’ flag, which causes a route discovery to be initiated if no route to the destination is known. Note that in the mesh stack, this option and the APS retry option must be
enabled an existing route to be repaired automatically.
EMBER_APS_OPTION_FORCE_ROUTE_DISCOVERY Send the message with the NWK ’force
route 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 the
node 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 up
until the next poll from the (end device) destination.
EMBER_APS_OPTION_ZDO_RESPONSE_REQUIRED This incoming message is a valid ZDO
request and the application is responsible for sending a ZDO response. This flag is used only
within emberIncomingMessageHandler() when EMBER_APPLICATION_RECEIVES_UNSUPPORTED_ZDO_REQUESTS is defined.
EMBER_APS_OPTION_FRAGMENT This message is part of a fragmented message. This option
may only be set for unicasts. The groupId field gives the index of this fragment in the low-order
byte. If the low-order byte is zero this is the first fragment and the high-order byte contains the
number of fragments in the message.
Definition at line 399 of file ember-types.h.
6.3.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.
Definition at line 466 of file ember-types.h.
6.3.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 EM250
120-3016-000-4720
61
EMBER_OUTGOING_VIA_BINDING Unicast sent using an entry in the binding table.
EMBER_OUTGOING_MULTICAST Multicast message. This value is passed to emberMessageSentHandler() only. It may not be passed to emberSendUnicast().
EMBER_OUTGOING_BROADCAST Broadcast message. This value is passed to emberMessageSentHandler() only. It may not be passed to emberSendUnicast().
Definition at line 491 of file ember-types.h.
6.3.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.
Definition at line 516 of file ember-types.h.
6.3.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.
Definition at line 540 of file ember-types.h.
6.3.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-one
destination EUI64. Route discovery should be disabled when sending unicasts via many-to-one
bindings.
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 to
the group.
Definition at line 557 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
62
6.3.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.
Definition at line 600 of file ember-types.h.
6.3.4.13
enum EmberDeviceUpdate
The Status of the Update Device message sent to the Trust Center. The device may have joined or rejoined
insecurely, rejoined securely, or left. MAC Security has been deprecated and therefore there is no secure
join.
Enumerator:
EMBER_STANDARD_SECURITY_SECURED_REJOIN
EMBER_STANDARD_SECURITY_UNSECURED_JOIN
EMBER_DEVICE_LEFT
EMBER_STANDARD_SECURITY_UNSECURED_REJOIN
EMBER_HIGH_SECURITY_SECURED_REJOIN
EMBER_HIGH_SECURITY_UNSECURED_JOIN
EMBER_HIGH_SECURITY_UNSECURED_REJOIN
EMBER_REJOIN_REASON_NONE
EMBER_REJOIN_DUE_TO_NWK_KEY_UPDATE
EMBER_REJOIN_DUE_TO_LEAVE_MESSAGE
EMBER_REJOIN_DUE_TO_NO_PARENT
EMBER_REJOIN_DUE_TO_ZLL_TOUCHLINK
EMBER_REJOIN_DUE_TO_APP_EVENT_5
EMBER_REJOIN_DUE_TO_APP_EVENT_4
EMBER_REJOIN_DUE_TO_APP_EVENT_3
EMBER_REJOIN_DUE_TO_APP_EVENT_2
EMBER_REJOIN_DUE_TO_APP_EVENT_1
Definition at line 634 of file ember-types.h.
6.3.4.14
enum EmberDeviceUpdate
Notes the last rejoin reason.
Enumerator:
EMBER_STANDARD_SECURITY_SECURED_REJOIN
EmberZNet 4.7.2 API EM250
120-3016-000-4720
63
EMBER_STANDARD_SECURITY_UNSECURED_JOIN
EMBER_DEVICE_LEFT
EMBER_STANDARD_SECURITY_UNSECURED_REJOIN
EMBER_HIGH_SECURITY_SECURED_REJOIN
EMBER_HIGH_SECURITY_UNSECURED_JOIN
EMBER_HIGH_SECURITY_UNSECURED_REJOIN
EMBER_REJOIN_REASON_NONE
EMBER_REJOIN_DUE_TO_NWK_KEY_UPDATE
EMBER_REJOIN_DUE_TO_LEAVE_MESSAGE
EMBER_REJOIN_DUE_TO_NO_PARENT
EMBER_REJOIN_DUE_TO_ZLL_TOUCHLINK
EMBER_REJOIN_DUE_TO_APP_EVENT_5
EMBER_REJOIN_DUE_TO_APP_EVENT_4
EMBER_REJOIN_DUE_TO_APP_EVENT_3
EMBER_REJOIN_DUE_TO_APP_EVENT_2
EMBER_REJOIN_DUE_TO_APP_EVENT_1
Definition at line 668 of file ember-types.h.
6.3.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.
Definition at line 698 of file ember-types.h.
6.3.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 approximate
milliseconds each).
EMBER_EVENT_MINUTE_TIME The execution time is in ’binary’ minutes (65536 approximate
milliseconds each).
EMBER_EVENT_ZERO_DELAY The event is scheduled to run at the earliest opportunity.
Definition at line 716 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
64
6.3.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 causes
the device to use an Ember Mobile Node Join, which is functionally equivalent to a MAC association. This value should be used by default.
EMBER_USE_NWK_REJOIN For those networks where the "permit joining" flag is never turned
on, they will need to use a ZigBee NWK Rejoin. This value causes the rejoin to be sent withOUT
NWK security and the Trust Center will be asked to send the NWK key to the device. The NWK
key 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 emberTrustCenterJoinHandler(). For a mobile node this value will cause it to use an Ember Mobile node
rejoin, which is functionally equivalent.
EMBER_USE_NWK_REJOIN_HAVE_NWK_KEY
EMBER_USE_NWK_COMMISSIONING For those networks where all network and security information is known ahead of time, a router device may be commissioned such that it does not
need to send any messages to begin communicating on the network.
Definition at line 741 of file ember-types.h.
6.3.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 unicast.
EMBER_COUNTER_MAC_TX_UNICAST_RETRY The MAC retried a unicast. This is a placeholder and is not used by the emberCounterHandler() callback. Instead the number of MAC
retries 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 unicast.
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 transmitted a data unicast.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
65
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. Instead the
number of APS retries are returned in the data parameter of the callback for the EMBER_COUNTER_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 transmitted a data unicast.
EMBER_COUNTER_ROUTE_DISCOVERY_INITIATED The network layer successfully submitted 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 not
been 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 occurred
in the UART.
EMBER_COUNTER_ASH_FRAMING_ERROR EZSP-UART only. A framing error occurred in
the UART.
EMBER_COUNTER_ASH_OVERRUN_ERROR EZSP-UART only. An overrun error occurred in
the UART.
EMBER_COUNTER_NWK_FRAME_COUNTER_FAILURE A message was dropped at the Network layer because the NWK frame counter was not higher than the last message seen from that
source.
EMBER_COUNTER_APS_FRAME_COUNTER_FAILURE A message was dropped at the APS
layer 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 APS layer because it had APS encryption but the key associated with the sender has not been
authenticated, and thus the key is not authorized for use in APS data messages.
EMBER_COUNTER_NWK_DECRYPTION_FAILURE A NWK encrypted message was received
but dropped because decryption failed.
EMBER_COUNTER_APS_DECRYPTION_FAILURE An APS encrypted message was received
but dropped because decryption failed.
EMBER_COUNTER_ALLOCATE_PACKET_BUFFER_FAILURE The number of times we failed
to allocate a set of linked packet buffers. This doesn’t necessarily mean that the packet buffer
count 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 dropped
a 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 emberTick(). After that limit is hit, packets will be dropped. The number of dropped packets will be
recorded in this counter.
NOTE: For each call to emberCounterHandler() there may be more than 1 packet that was
dropped due to the limit reached. The actual number of packets dropped will be returned in
the ’data’ parameter passed to that function.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
66
EMBER_COUNTER_PACKET_VALIDATE_LIBRARY_DROPPED_COUNT The number of times
we dropped a packet due to the packet-validate library checking a packet and rejecting it due to
length or other formatting problems.
EMBER_COUNTER_TYPE_COUNT A placeholder giving the number of Ember counter types.
Definition at line 964 of file ember-types.h.
6.3.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 Mode
for the device forming the network. (Previously known as EMBER_NO_TRUST_CENTER_MODE)
EMBER_TRUST_CENTER_GLOBAL_LINK_KEY This enables a Global Link Key for the Trust
Center. All nodes will share the same Trust Center Link Key.
EMBER_PRECONFIGURED_NETWORK_KEY_MODE This enables devices that perform MAC
Association with a pre-configured Network Key to join the network. It is only set on the Trust
Center.
EMBER_HAVE_TRUST_CENTER_EUI64 This denotes that the EmberInitialSecurityState::preconfiguredTrustCenterEui64 has a value in it containing the trust center EUI64. The device will only join
a network and accept commands from a trust center with that EUI64. Normally this bit is NOT
set, and the EUI64 of the trust center is learned during the join process. When commissioning a device to join onto an existing network that is using a trust center, and without sending any
messages, this bit must be set and the field EmberInitialSecurityState::preconfiguredTrustCenterEui64 must be populated with the appropriate EUI64.
EMBER_TRUST_CENTER_USES_HASHED_LINK_KEY This denotes that the EmberInitialSecurityState::preconfiguredKey is not the actual Link Key but a Root Key known only to the Trust Center. It is hashed with the IEEE Address of the destination device in order to create the actual Link
Key used in encryption. This is bit is only used by the Trust Center. The joining device need not
set this.
EMBER_HAVE_PRECONFIGURED_KEY This denotes that the EmberInitialSecurityState::preconfiguredKey element has valid data that should be used to configure the initial security state.
EMBER_HAVE_NETWORK_KEY This denotes that the EmberInitialSecurityState::networkKey element 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 attempt
to acquire a Trust Center Link Key during joining. This is only necessary if the device does not
have a pre-configured key.
EMBER_REQUIRE_ENCRYPTED_KEY This denotes that a joining device should only accept an
encrypted network key from the Trust Center (using its pre-configured key). A key sent in-theclear by the Trust Center will be rejected and the join will fail. This option is only valid when
utilizing a pre-configured key.
EMBER_NO_FRAME_COUNTER_RESET This denotes whether the device should NOT reset its
outgoing 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 cases
where a device is joining to the same network again (but not using emberRejoinNetwork()) it
should keep the NWK and APS frame counters stored in its tokens.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
67
EMBER_GET_PRECONFIGURED_KEY_FROM_INSTALL_CODE This denotes that the device
should 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 that
token is not valid than the call to emberSetInitialSecurityState() will fail.
Definition at line 1426 of file ember-types.h.
6.3.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 should
discard or accept network Leave Commands.
Definition at line 1519 of file ember-types.h.
6.3.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 network
with ZigBee Standard Security.
EMBER_DISTRIBUTED_TRUST_CENTER_MODE_ This denotes that the device is running in a
network without a centralized Trust Center.
EMBER_TRUST_CENTER_GLOBAL_LINK_KEY_ This denotes that the device has a Global Link
Key. 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 Link
Key.
EMBER_TRUST_CENTER_USES_HASHED_LINK_KEY_ This denotes that the Trust Center is
using a Hashed Link Key.
Definition at line 1620 of file ember-types.h.
6.3.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 number
associated with it. (i.e. a Network Key).
EMBER_KEY_HAS_OUTGOING_FRAME_COUNTER This indicates that the key has an outgoing frame counter and the corresponding value within the EmberKeyStruct has been populated
with the data.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
68
EMBER_KEY_HAS_INCOMING_FRAME_COUNTER This indicates that the key has an incoming frame counter and the corresponding value within the EmberKeyStruct has been populated
with the data.
EMBER_KEY_HAS_PARTNER_EUI64 This indicates that the key has an associated Partner EUI64 address and the corresponding value within the EmberKeyStruct has been populated with the
data.
EMBER_KEY_IS_AUTHORIZED This indicates the key is authorized for use in APS data messages. If the key is not authorized for use in APS data messages it has not yet gone through a key
agreement protocol, such as CBKE (i.e. ECC)
EMBER_KEY_PARTNER_IS_SLEEPY This indicates that the partner associated with the link is a
sleepy end device. This bit is set automatically if the local device hears a device announce from
the partner indicating it is not an ’RX on when idle’ device.
Definition at line 1672 of file ember-types.h.
6.3.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 Master
Key.
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
Definition at line 1707 of file ember-types.h.
6.3.4.24
enum EmberKeyStatus
This denotes the status of an attempt to establish a key with another device.
Enumerator:
EMBER_APP_LINK_KEY_ESTABLISHED
EMBER_APP_MASTER_KEY_ESTABLISHED
EMBER_TRUST_CENTER_LINK_KEY_ESTABLISHED
EMBER_KEY_ESTABLISHMENT_TIMEOUT
EMBER_KEY_TABLE_FULL
EMBER_TC_RESPONDED_TO_KEY_REQUEST
EMBER_TC_APP_KEY_SENT_TO_REQUESTER
EMBER_TC_RESPONSE_TO_KEY_REQUEST_FAILED
EMBER_TC_REQUEST_KEY_TYPE_NOT_SUPPORTED
EMBER_TC_NO_LINK_KEY_FOR_REQUESTER
EmberZNet 4.7.2 API EM250
120-3016-000-4720
69
EMBER_TC_REQUESTER_EUI64_UNKNOWN
EMBER_TC_RECEIVED_FIRST_APP_KEY_REQUEST
EMBER_TC_TIMEOUT_WAITING_FOR_SECOND_APP_KEY_REQUEST
EMBER_TC_NON_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
Definition at line 1758 of file ember-types.h.
6.3.4.25
enum EmberLinkKeyRequestPolicy
This enumeration determines whether or not a Trust Center answers link key requests.
Enumerator:
EMBER_DENY_KEY_REQUESTS
EMBER_ALLOW_KEY_REQUESTS
Definition at line 1793 of file ember-types.h.
6.3.4.26
enum EmberKeySettings
Enumerator:
EMBER_KEY_PERMISSIONS_NONE
EMBER_KEY_PERMISSIONS_READING_ALLOWED
EMBER_KEY_PERMISSIONS_HASHING_ALLOWED
Definition at line 1877 of file ember-types.h.
6.3.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 bootloader messages
EMBER_MAC_PASSTHROUGH_EMBERNET_SOURCE EmberNet messages filtered by their
source address.
EMBER_MAC_PASSTHROUGH_APPLICATION Application-specific passthrough messages.
EMBER_MAC_PASSTHROUGH_CUSTOM Custom inter-pan filter
Definition at line 1909 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
70
6.3.4.28
enum EmberZdoStatus
Enumerator:
EMBER_ZDP_SUCCESS
EMBER_ZDP_INVALID_REQUEST_TYPE
EMBER_ZDP_DEVICE_NOT_FOUND
EMBER_ZDP_INVALID_ENDPOINT
EMBER_ZDP_NOT_ACTIVE
EMBER_ZDP_NOT_SUPPORTED
EMBER_ZDP_TIMEOUT
EMBER_ZDP_NO_MATCH
EMBER_ZDP_NO_ENTRY
EMBER_ZDP_NO_DESCRIPTOR
EMBER_ZDP_INSUFFICIENT_SPACE
EMBER_ZDP_NOT_PERMITTED
EMBER_ZDP_TABLE_FULL
EMBER_ZDP_NOT_AUTHORIZED
EMBER_NWK_ALREADY_PRESENT
EMBER_NWK_TABLE_FULL
EMBER_NWK_UNKNOWN_DEVICE
Definition at line 1998 of file ember-types.h.
6.3.4.29
enum EmberZdoServerMask
Enumerator:
EMBER_ZDP_PRIMARY_TRUST_CENTER
EMBER_ZDP_SECONDARY_TRUST_CENTER
EMBER_ZDP_PRIMARY_BINDING_TABLE_CACHE
EMBER_ZDP_SECONDARY_BINDING_TABLE_CACHE
EMBER_ZDP_PRIMARY_DISCOVERY_CACHE
EMBER_ZDP_SECONDARY_DISCOVERY_CACHE
EMBER_ZDP_NETWORK_MANAGER
Definition at line 2192 of file ember-types.h.
6.3.4.30
enum EmberZdoConfigurationFlags
Enumerator:
EMBER_APP_RECEIVES_SUPPORTED_ZDO_REQUESTS
EMBER_APP_HANDLES_UNSUPPORTED_ZDO_REQUESTS
EMBER_APP_HANDLES_ZDO_ENDPOINT_REQUESTS
EMBER_APP_HANDLES_ZDO_BINDING_REQUESTS
Definition at line 2466 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
71
6.3.5
Function Documentation
6.3.5.1 int8u∗ emberKeyContents ( EmberKeyData ∗ key )
This function allows the programmer to gain access to the actual key data bytes of the EmberKeyData
struct.
Parameters
key A Pointer to an EmberKeyData structure.
Returns
int8u∗ Returns a pointer to the first byte of the Key data.
6.3.5.2 int8u∗ emberCertificateContents ( EmberCertificateData ∗ cert )
This function allows the programmer to gain access to the actual certificate data bytes of the EmberCertificateData struct.
Parameters
cert A Pointer to an EmberCertificateData structure.
Returns
int8u∗ Returns a pointer to the first byte of the certificate data.
6.3.5.3 int8u∗ emberPublicKeyContents ( EmberPublicKeyData ∗ key )
This function allows the programmer to gain access to the actual public key data bytes of the EmberPublicKeyData struct.
Parameters
key A Pointer to an EmberPublicKeyData structure.
Returns
int8u∗ Returns a pointer to the first byte of the public key data.
6.3.5.4 int8u∗ emberPrivateKeyContents ( EmberPrivateKeyData ∗ key )
This function allows the programmer to gain access to the actual private key data bytes of the EmberPrivateKeyData struct.
Parameters
key A Pointer to an EmberPrivateKeyData structure.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
72
Returns
int8u∗ Returns a pointer to the first byte of the private key data.
6.3.5.5 int8u∗ emberSmacContents ( EmberSmacData ∗ key )
This function allows the programmer to gain access to the actual SMAC (Secured Message Authentication
Code) data of the EmberSmacData struct.
6.3.5.6 int8u∗ emberSignatureContents ( EmberSignatureData ∗ sig )
This function allows the programmer to gain access to the actual ECDSA signature data of the EmberSignatureData struct.
6.3.6
Variable Documentation
6.3.6.1
const EmberVersion emberVersion
Struct containing the version info.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
73
6.4
Network Formation
Functions
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
EmberStatus emberInit (void)
void emberTick (void)
EmberStatus emberNetworkInit (void)
EmberStatus emberNetworkInitExtended (EmberNetworkInitStruct ∗networkInitStruct)
EmberStatus emberFormNetwork (EmberNetworkParameters ∗parameters)
EmberStatus emberPermitJoining (int8u duration)
EmberStatus emberJoinNetwork (EmberNodeType nodeType, EmberNetworkParameters ∗parameters)
EmberStatus emberLeaveNetwork (void)
EmberStatus emberSendZigbeeLeave (EmberNodeId destination, EmberLeaveRequestFlags flags)
EmberStatus emberFindAndRejoinNetworkWithReason (boolean haveCurrentNetworkKey, int32u
channelMask, EmberRejoinReason reason)
EmberStatus emberFindAndRejoinNetwork (boolean haveCurrentNetworkKey, int32u channelMask)
EmberRejoinReason emberGetLastRejoinReason (void)
EmberStatus emberRejoinNetwork (boolean haveCurrentNetworkKey)
EmberStatus emberStartScan (EmberNetworkScanType scanType, int32u channelMask, int8u duration)
EmberStatus emberStopScan (void)
void emberScanCompleteHandler (int8u channel, EmberStatus status)
void emberEnergyScanResultHandler (int8u channel, int8s maxRssiValue)
void emberNetworkFoundHandler (EmberZigbeeNetwork ∗networkFound)
boolean emberStackIsPerformingRejoin (void)
EmberLeaveReason emberGetLastLeaveReason (EmberNodeId ∗returnNodeIdThatSentLeave)
6.4.1
Detailed Description
EmberZNet API for finding, forming, joining, and leaving ZigBee networks. See network-formation.h for
source code.
6.4.2
Function Documentation
6.4.2.1 EmberStatus emberInit ( void )
Initializes the radio and the EmberZNet stack. )
Device configuration functions must be called before emberInit() is called.
Note
The application must check the return value of this function. If the initialization fails, normal messaging functions will not be available. Some failure modes are not fatal, but the application must follow
certain procedures to permit recovery. Ignoring the return code will result in unpredictable radio and
API behavior. (In particular, problems with association will occur.)
Returns
An EmberStatus value indicating successful initialization or the reason for failure.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
74
6.4.2.2
void emberTick ( void )
A periodic tick routine that should be called:
• in the application’s main event loop,
• as soon as possible after any radio interrupts, and
• after emberInit().
6.4.2.3 EmberStatus emberNetworkInit ( void )
Resume network operation after a reboot.
It is required that this be called on boot prior to ANY network operations. This will initialize the networking system and attempt to resume the previous network identity and configuration. If the node was not
previously this routine should still be called.
If the node was previously joined to a network it will retain its original type (e.g. coordinator, router, end
device, etc.)
EMBER_NOT_JOINED is returned if the node is not part of a network.
Returns
An EmberStatus value that indicates one of the following:
• successful initialization,
• EMBER_NOT_JOINED if the node is not part of a network, or
• the reason for failure.
6.4.2.4 EmberStatus emberNetworkInitExtended ( EmberNetworkInitStruct ∗ networkInitStruct )
Resume network operation based on passed parameters.
This routine behaves similar to emberNetworkInit() however the caller can control the operation of the
initialization. Either this routine or emberNetworkInit() must be called to initialize the network before any
network operations are performed.
6.4.2.5 EmberStatus emberFormNetwork ( EmberNetworkParameters ∗ parameters )
Forms a new network by becoming the coordinator.
Note
If using security, the application must call emberSetInitialSecurityState() prior to joining the network.
This also applies when a device leaves a network and wants to form another one.
Parameters
parameters Specification of the new network.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
75
Returns
An EmberStatus value that indicates either the successful formation of the new network, or the reason
that the network formation failed.
6.4.2.6 EmberStatus emberPermitJoining ( int8u duration )
Tells the stack to allow other nodes to join the network with this node as their parent. Joining is initially
disabled by default. This function may only be called after the node is part of a network and the stack is
up.
Parameters
duration A value of 0x00 disables joining. A value of 0xFF enables joining. Any other value
enables joining for that number of seconds.
6.4.2.7 EmberStatus emberJoinNetwork ( EmberNodeType nodeType, EmberNetworkParameters ∗
parameters )
Causes the stack to associate with the network using the specified network parameters. It can take several
seconds for the stack to associate with the local network. Do not send messages until a call to the emberStackStatusHandler() callback informs you that the stack is up.
Note
If using security, the application must call emberSetInitialSecurityState() prior to joining the network.
This also applies when a device leaves a network and wants to join another one.
Parameters
nodeType Specification of the role that this node will have in the network. This role must not be
EMBER_COORDINATOR. To be a coordinator, call emberFormNetwork().
parameters Specification of the network with which the node should associate.
Returns
An EmberStatus value that indicates either:
• that the association process began successfully, or
• the reason for failure.
6.4.2.8 EmberStatus emberLeaveNetwork ( void )
Causes the stack to leave the current network. This generates a call to the emberStackStatusHandler()
callback to indicate that the network is down. The radio will not be used until after a later call to emberFormNetwork() or emberJoinNetwork().
Returns
An EmberStatus value indicating success or reason for failure. A status of EMBER_INVALID_CALL
indicates that the node is either not joined to a network or is already in the process of leaving.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
76
6.4.2.9 EmberStatus emberSendZigbeeLeave ( EmberNodeId destination, EmberLeaveRequestFlags
flags )
Sends a ZigBee NWK leave command to the specified destination.
Parameters
destination is the node Id of the device that is being told to leave.
flags is an bitmask indicating additional considerations for the leave request. See the EmberLeaveRequestFlags enum for more information. Multiple bits may be set.
Returns
An EmberStatus value indicating success or reason for failure. A status of EMBER_INVALID_CALL
indicates that the node not currently joined to the network, or the destination is the local node. To tell
the local device to leave, use the emberLeaveNetwork() API.
6.4.2.10 EmberStatus emberFindAndRejoinNetworkWithReason ( boolean haveCurrentNetworkKey,
int32u channelMask, EmberRejoinReason reason )
The application may call this function when contact with the network has been lost. The most common
usage case is when an end device can no longer communicate with its parent and wishes to find a new one.
Another case is when a device has missed a Network Key update and no longer has the current Network
Key.
Note that a call to emberPollForData() on an end device that has lost contact with its parent will automatically call ::emberRejoinNetwork(TRUE).
The stack will call emberStackStatusHandler() to indicate that the network is down, then try to re-establish
contact with the network by performing an active scan, choosing a network with matching extended pan
id, and sending a ZigBee network rejoin request. A second call to the emberStackStatusHandler() callback
indicates either the success or the failure of the attempt. The process takes approximately 150 milliseconds
per channel to complete.
This call replaces the ::emberMobileNodeHasMoved() API from EmberZNet 2.x, which used MAC association and consequently took half a second longer to complete.
Parameters
haveCurrent- This parameter determines whether the request to rejoin the Network is sent encrypted
NetworkKey (TRUE) or unencrypted (FALSE). The application should first try to use encryption. If
that fails, the application should call this function again and use no encryption. If the
unencrypted rejoin is successful then device will be in the joined but unauthenticated
state. The Trust Center will be notified of the rejoin and send an updated Network encrypted using the device’s Link Key. Sending the rejoin unencrypted is only supported
on networks using Standard Security with link keys (i.e. ZigBee 2006 networks do not
support it).
channelMask A mask indicating the channels to be scanned. See emberStartScan() for format details.
reason An enemuration indicating why the rejoin occurred. The stack will set the reason based
on the ::EmberRejoinReason. An application should use one of the APP_EVENT rejoin
reasons. The stack will never use these. Only if the function return code is EMBER_SUCCESS will the rejoin reason be set.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
77
Returns
An EmberStatus value indicating success or reason for failure.
6.4.2.11 EmberStatus emberFindAndRejoinNetwork ( boolean haveCurrentNetworkKey, int32u
channelMask )
This call is the same emberFindAndRejoinNetworkWithReason() however the reason is assumed to be
::EMBER_REJOIN_REASON_APP_EVENT_1.
6.4.2.12
EmberRejoinReason emberGetLastRejoinReason ( void )
Returns the enumeration for why a rejoin previously occurred..
6.4.2.13 EmberStatus emberRejoinNetwork ( boolean haveCurrentNetworkKey )
A convenience function which calls emberFindAndRejoinNetwork() with a channel mask value for scanning only the current channel. Included for back-compatibility.
6.4.2.14 EmberStatus emberStartScan ( EmberNetworkScanType scanType, int32u channelMask,
int8u duration )
This function will start a scan. EMBER_SUCCESS signals that the scan successfully started. Note that
while a scan can be initiated while the node is currently joined to a network, the node will generally be
unable to communication with its PAN during the scan period, so care should be taken when performing
scans of any significant duration while presently joined to an existing PAN.
Possible error responses and their meanings:
• EMBER_MAC_SCANNING, we are already scanning.
• EMBER_MAC_BAD_SCAN_DURATION, we have set a duration value that is not 0..14 inclusive.
• EMBER_MAC_INCORRECT_SCAN_TYPE, we have requested an undefined scanning type;
• EMBER_MAC_INVALID_CHANNEL_MASK, our channel mask did not specify any valid channels on the current platform.
Parameters
scanType Indicates the type of scan to be performed. Possible values: EMBER_ENERGY_SCAN, EMBER_ACTIVE_SCAN.
channelMask Bits set as 1 indicate that this particular channel should be scanned. Bits set to 0 indicate
that this particular channel should not be scanned. For example, a channelMask value
of 0x00000001 would indicate that only channel 0 should be scanned. Valid channels
range from 11 to 26 inclusive. This translates to a channel mask value of 0x07 FF F8
00. As a convenience, a channelMask of 0 is reinterpreted as the mask for the current
channel.
duration Sets the exponent of the number of scan periods, where a scan period is 960 symbols,
and a symbol is 16 microseconds. The scan will occur for ((2∧ duration) + 1) scan
periods. The value of duration must be less than 15. The time corresponding to the first
few values are as follows: 0 = 31 msec, 1 = 46 msec, 2 = 77 msec, 3 = 138 msec, 4 =
261 msec, 5 = 507 msec, 6 = 998 msec.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
78
6.4.2.15 EmberStatus emberStopScan ( void )
Terminates a scan in progress.
Returns
Returns EMBER_SUCCESS if successful.
6.4.2.16
void emberScanCompleteHandler ( int8u channel, EmberStatus status )
Indicates the status of the current scan. When the scan has completed the stack will call this function
with status set to EMBER_SUCCESS. Prior to the scan completing the stack may call this function with
other status values. Non-EMBER_SUCCESS status values indicate that the scan failed to start successfully
on the channel indicated by the channel parameter. The current scan is ongoing until the stack calls this
function with status set to EMBER_SUCCESS.
Parameters
channel The channel on which the current error occurred. Undefined for the case of EMBER_SUCCESS.
status The error condition that occurred on the current channel. Value will be EMBER_SUCCESS when the scan has completed.
6.4.2.17
void emberEnergyScanResultHandler ( int8u channel, int8s maxRssiValue )
Reports the maximum RSSI value measured on the channel.
Parameters
channel The 802.15.4 channel number on which the RSSI value was measured.
maxRssiValue The maximum RSSI value measured (in units of dBm).
6.4.2.18
void emberNetworkFoundHandler ( EmberZigbeeNetwork ∗ networkFound )
Reports that a network was found, and gives the network parameters useful for deciding which network to
join.
Parameters
networkFound A pointer to a EmberZigbeeNetwork structure that contains the discovered network and
its associated parameters.
6.4.2.19 boolean emberStackIsPerformingRejoin ( void )
Indicates whether the stack is in the process of performing a rejoin.
Returns
Returns TRUE if the device is in the process of performing a rejoin. Returns FALSE otherwise.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
79
6.4.2.20 EmberLeaveReason emberGetLastLeaveReason ( EmberNodeId ∗ returnNodeIdThatSentLeave
)
Indicates the reason why the device left the network (if any). This also will return the device that sent the
leave message, if the leave was due to an over-the-air message.
If returnNodeIdThatSentLeave is a non-NULL pointer, then the node Id of the device that sent the leave
message will be written to the value pointed to be the pointer. If the leave was not due to an over-the-air
message (but an internal API call instead) then EMBER_UNKNOWN_NODE_ID is returned.
Returns
Returns EmberLeaveReason enumeration, or EMBER_LEAVE_REASON_NONE if the device has
not left the network.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
80
6.5
Packet Buffers
Macros
•
•
•
•
#define LOG_PACKET_BUFFER_SIZE
#define PACKET_BUFFER_SIZE
#define EMBER_NULL_MESSAGE_BUFFER
#define emberMessageBufferLength(buffer)
Functions
•
•
•
•
•
XAP2B_PAGEZERO_ON int8u ∗ emberMessageBufferContents (EmberMessageBuffer buffer)
void emberSetMessageBufferLength (EmberMessageBuffer buffer, int8u newLength)
void emberHoldMessageBuffer (EmberMessageBuffer buffer)
void emberReleaseMessageBuffer (EmberMessageBuffer buffer)
int8u emberPacketBufferFreeCount (void)
Buffer Functions
•
•
•
•
•
EmberMessageBuffer emberAllocateLinkedBuffers (int8u count)
EmberMessageBuffer emberFillStackBuffer (int16u count,...)
#define emberStackBufferLink(buffer)
#define emberSetStackBufferLink(buffer, newLink)
#define emberAllocateStackBuffer()
Linked Buffer Utilities
The plural "buffers" in the names of these procedures is a reminder that they deal with linked chains of
buffers.
• EmberMessageBuffer emberFillLinkedBuffers (int8u ∗contents, int8u length)
• void emberCopyToLinkedBuffers (int8u ∗contents, EmberMessageBuffer buffer, int8u startIndex,
int8u length)
• void emberCopyFromLinkedBuffers (EmberMessageBuffer buffer, int8u startIndex, int8u ∗contents,
int8u length)
• void emberCopyBufferBytes (EmberMessageBuffer to, int16u toIndex, EmberMessageBuffer from,
int16u fromIndex, int16u count)
• EmberStatus emberAppendToLinkedBuffers (EmberMessageBuffer buffer, int8u ∗contents, int8u
length)
• EmberStatus emberAppendPgmToLinkedBuffers (EmberMessageBuffer buffer, PGM_P contents,
int8u length)
• EmberStatus emberAppendPgmStringToLinkedBuffers (EmberMessageBuffer buffer, PGM_P suffix)
• EmberStatus emberSetLinkedBuffersLength (EmberMessageBuffer buffer, int8u length)
• int8u ∗ emberGetLinkedBuffersPointer (EmberMessageBuffer buffer, int8u index)
• XAP2B_PAGEZERO_ON int8u emberGetLinkedBuffersByte (EmberMessageBuffer buffer, int8u
index)
• XAP2B_PAGEZERO_OFF void emberSetLinkedBuffersByte (EmberMessageBuffer buffer, int8u
index, int8u byte)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
81
•
•
•
•
•
•
int16u emberGetLinkedBuffersLowHighInt16u (EmberMessageBuffer buffer, int8u index)
void emberSetLinkedBuffersLowHighInt16u (EmberMessageBuffer buffer, int8u index, int16u value)
int32u emberGetLinkedBuffersLowHighInt32u (EmberMessageBuffer buffer, int8u index)
void emberSetLinkedBuffersLowHighInt32u (EmberMessageBuffer buffer, int8u index, int32u value)
EmberMessageBuffer emberCopyLinkedBuffers (EmberMessageBuffer buffer)
EmberMessageBuffer emberMakeUnsharedLinkedBuffer (EmberMessageBuffer buffer, boolean isShared)
6.5.1
Detailed Description
These functions implement a fixed-block-size memory management scheme to store and manipulate EmberZNet packets. Buffers are identified to clients with a 1-byte ID.
Buffers can be linked together to create longer packets. The utility procedures allow you to treat a linked
chain of buffers as a single buffer.
Freeing a buffer automatically decrements the reference count of any following buffer, possibly freeing the
following buffer as well.
Packet buffers may be allocated, held, and released.
See packet-buffer.h for source code.
6.5.2
Macro Definition Documentation
6.5.2.1
#define LOG PACKET BUFFER SIZE
Buffers hold 32 bytes. Defined as the log to ensure it is a power of 2.
Definition at line 38 of file packet-buffer.h.
6.5.2.2
#define PACKET BUFFER SIZE
Buffers hold 32 bytes.
Definition at line 42 of file packet-buffer.h.
6.5.2.3
#define EMBER NULL MESSAGE BUFFER
Provides the message buffer equivalent of NULL.
Definition at line 45 of file packet-buffer.h.
6.5.2.4
#define emberMessageBufferLength( buffer )
Returns the length of a buffer. Implemented as a macro for improved efficiency.
Parameters
buffer A buffer.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
82
Returns
Buffer length.
Definition at line 73 of file packet-buffer.h.
6.5.2.5
#define emberStackBufferLink( buffer )
Returns the buffer that follows this one in the message. EMBER_NULL_MESSAGE_BUFFER is returned
if there is no following buffer.
Parameters
buffer The buffer whose following buffer is desired.
Returns
Returns the buffer that follows buffer in the message. EMBER_NULL_MESSAGE_BUFFER is
returned if there is no following buffer.
Definition at line 185 of file packet-buffer.h.
6.5.2.6
#define emberSetStackBufferLink( buffer, newLink )
Sets the buffer following this one in the message. The final buffer in the message has EMBER_NULL_MESSAGE_BUFFER as its link.
Parameters
buffer The buffer whose link is to be set.
newLink The buffer that is to follow buffer.
Definition at line 196 of file packet-buffer.h.
6.5.2.7
#define emberAllocateStackBuffer( )
Allocates a stack buffer.
Returns
A newly allocated buffer, or EMBER_NULL_MESSAGE_BUFFER if no buffer is available.
Definition at line 205 of file packet-buffer.h.
6.5.3
Function Documentation
6.5.3.1 XAP2B_PAGEZERO_ON int8u∗ emberMessageBufferContents ( EmberMessageBuffer
buffer )
Gets a pointer to a buffer’s contents. This pointer can be used to access only the first PACKET_BUFFER_SIZE bytes in the buffer. To read a message composed of multiple buffers, use emberCopyFromLinkedBuffers().
EmberZNet 4.7.2 API EM250
120-3016-000-4720
83
Parameters
buffer The buffer whose contents are desired.
Returns
Returns a pointer to the contents of buffer.
6.5.3.2
void emberSetMessageBufferLength ( EmberMessageBuffer buffer, int8u newLength )
Sets the length of a buffer.
When asserts are enabled, attempting to set a length greater than the size of the buffer triggers an assert.
Parameters
buffer A buffer
newLength The length to set the buffer to.
6.5.3.3
void emberHoldMessageBuffer ( EmberMessageBuffer buffer )
Holds a message buffer by incrementing its reference count. Implemented as a macro for improved efficiency.
Parameters
buffer A buffer.
6.5.3.4
void emberReleaseMessageBuffer ( EmberMessageBuffer buffer )
Releases a message buffer by decrementing its reference count. Implemented as a macro for improved
efficiency.
Parameters
buffer A buffer.
6.5.3.5 EmberMessageBuffer emberAllocateLinkedBuffers ( int8u count )
Allocates one or more linked buffers.
Parameters
count The number of buffers to allocate.
Returns
The first buffer in the newly allocated chain of buffers, or EMBER_NULL_MESSAGE_BUFFER if
insufficient buffers are available.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
84
6.5.3.6 EmberMessageBuffer emberFillStackBuffer ( int16u count, ... )
Allocates a stack buffer and fills the buffer with data passed in the function call.
Parameters
count Buffer length.
... count bytes, which will be placed in the buffer.
Returns
A newly allocated buffer, or EMBER_NULL_MESSAGE_BUFFER if no buffer is available.
6.5.3.7 EmberMessageBuffer emberFillLinkedBuffers ( int8u ∗ contents, int8u length )
Allocates a chain of stack buffers sufficient to hold length bytes of data and fills the buffers with the data
in contents. If the value of contents is NULL, the buffers are allocated but not filled.
Parameters
contents A pointer to data to place in the allocated buffers.
length The buffer length.
Returns
The first buffer in a series of linked stack buffers, or EMBER_NULL_MESSAGE_BUFFER if insufficient buffers are available.
6.5.3.8
void emberCopyToLinkedBuffers ( int8u ∗ contents, EmberMessageBuffer buffer, int8u
startIndex, int8u length )
Copies a specified number of bytes of data into a buffer, starting at a specified index in the buffer array.
Buffer links are followed as required. No buffers are allocated or released.
Parameters
contents
buffer
startIndex
length
6.5.3.9
A pointer to data to copy into the buffer.
The buffer to copy data into.
The buffer index at which copying should start.
The number of bytes of data to copy.
void emberCopyFromLinkedBuffers ( EmberMessageBuffer buffer, int8u startIndex, int8u ∗
contents, int8u length )
Copies length bytes of data from a buffer to contents, starting at a specified index in the buffer array.
Buffer links are followed as required.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
85
Parameters
buffer
startIndex
contents
length
6.5.3.10
The buffer to copy data from.
The buffer index at which copying should start.
A pointer to data to copy from the buffer.
The number of bytes of data to copy.
void emberCopyBufferBytes ( EmberMessageBuffer to, int16u toIndex,
EmberMessageBuffer from, int16u fromIndex, int16u count )
Copies a specified number of bytes of data from one buffer into another. Buffer links are followed as
required. No buffers are allocated or released.
Parameters
to
toIndex
from
fromIndex
count
The buffer to copy data into.
The position in the destination buffer at which copying should start.
The buffer to copy data from.
The position in the source buffer at which copying should start.
The number of bytes of data to copy.
6.5.3.11 EmberStatus emberAppendToLinkedBuffers ( EmberMessageBuffer buffer, int8u ∗ contents,
int8u length )
Appends length bytes from contents onto a buffer. Combines the functionality of ::setPacketBuffersLength() and ::copyToPacketBuffers().
Parameters
buffer The buffer to append data to.
contents A pointer to data to append.
length The number of bytes of data to append.
Returns
EMBER_SUCCESS if sufficient buffers are available, and EMBER_NO_BUFFERS if not.
6.5.3.12 EmberStatus emberAppendPgmToLinkedBuffers ( EmberMessageBuffer buffer, PGM P
contents, int8u length )
Appends length bytes from contents, a pointer into program space (flash) to buffer.
Parameters
buffer The buffer to append data to.
contents The data to append.
length The number of bytes of data to append.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
86
Returns
EMBER_SUCCESS if sufficient buffers are available, and EMBER_NO_BUFFERS if not.
6.5.3.13 EmberStatus emberAppendPgmStringToLinkedBuffers ( EmberMessageBuffer buffer, PGM P
suffix )
Appends a string from program space (flash) to a buffer.
Parameters
buffer The buffer to append data to.
suffix The string in program space to append.
Returns
EMBER_SUCCESS if sufficient buffers are available, and EMBER_NO_BUFFERS if not.
6.5.3.14 EmberStatus emberSetLinkedBuffersLength ( EmberMessageBuffer buffer, int8u length )
Sets the length of a chain of buffers, adding or removing trailing buffers as needed.
Parameters
buffer The buffer whose length is to be set.
length The length to set.
Returns
EMBER_SUCCESS if changing buffer’s length by length bytes does not require additional
buffers or if sufficient buffers are available, and EMBER_NO_BUFFERS if not.
6.5.3.15 int8u∗ emberGetLinkedBuffersPointer ( EmberMessageBuffer buffer, int8u index )
Gets a pointer to a specified byte in a linked list of buffers.
Parameters
buffer The buffer that the requested byte must come from.
index The index of the requested byte.
Returns
A pointer to the requested byte.
6.5.3.16 XAP2B_PAGEZERO_ON int8u emberGetLinkedBuffersByte ( EmberMessageBuffer buffer,
int8u index )
Gets a specified byte in a linked list of buffers.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
87
Parameters
buffer The buffer that the requested byte must come from.
index The index of the requested byte.
Returns
A byte.
6.5.3.17 XAP2B_PAGEZERO_OFF void emberSetLinkedBuffersByte ( EmberMessageBuffer buffer,
int8u index, int8u byte )
Sets the indexed byte in a linked list of buffers.
Parameters
buffer The buffer holding the byte to be set.
index The index of the byte to set.
byte The value to set the byte to.
6.5.3.18 int16u emberGetLinkedBuffersLowHighInt16u ( EmberMessageBuffer buffer, int8u index )
Gets a little endian 2-byte value from a linked list of buffers.
Parameters
buffer The buffer containing the 2-byte value.
index The index of the low byte.
Returns
The 2-byte value.
6.5.3.19
void emberSetLinkedBuffersLowHighInt16u ( EmberMessageBuffer buffer, int8u index, int16u
value )
Sets a little endian 2-byte value in a linked list of buffers.
Parameters
buffer The buffer to set the 2-byte value in.
index The index of the low byte.
value The 2-byte value to set.
6.5.3.20 int32u emberGetLinkedBuffersLowHighInt32u ( EmberMessageBuffer buffer, int8u index )
Gets a little endian 4-byte value from a linked list of buffers.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
88
Parameters
buffer The buffer containing the 4-byte value.
index The index of the low byte.
Returns
The 4-byte value.
6.5.3.21
void emberSetLinkedBuffersLowHighInt32u ( EmberMessageBuffer buffer, int8u index, int32u
value )
Sets a little endian 4-byte value in a linked list of buffers.
Parameters
buffer The buffer to set the 2-byte value in.
index The index of the low byte.
value The 4-byte value to set.
6.5.3.22 EmberMessageBuffer emberCopyLinkedBuffers ( EmberMessageBuffer buffer )
Copies a chain of linked buffers.
Parameters
buffer The first buffer in the chain to copy.
Returns
A newly created copy of the buffer chain.
6.5.3.23 EmberMessageBuffer emberMakeUnsharedLinkedBuffer ( EmberMessageBuffer buffer,
boolean isShared )
Creates a new, unshared copy of a specified buffer, if that buffer is shared. If it isn’t shared, increments the
reference count by 1 so that the user of the returned buffer can release it in either case.
Parameters
buffer The buffer to copy.
isShared A flag indicating whether the buffer is shared.
Returns
A fresh copy of buffer if isShared is true, and buffer if isShared is not true.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
89
6.5.3.24 int8u emberPacketBufferFreeCount ( void )
Retrieves the current number of free packet buffers.
Returns
The number of free packet buffers.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
90
6.6
Sending and Receiving Messages
Data Structures
• struct InterPanHeader
A struct for keeping track of all of the header info.
Macros
•
•
•
•
•
•
•
•
•
•
#define EMBER_APSC_MAX_ACK_WAIT_HOPS_MULTIPLIER_MS
#define EMBER_APSC_MAX_ACK_WAIT_TERMINAL_SECURITY_MS
#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 emberMaximumApsPayloadLength (void)
• EmberStatus emberSendMulticast (EmberApsFrame ∗apsFrame, int8u radius, int8u nonmemberRadius, EmberMessageBuffer message)
• EmberStatus emberSendUnicast (EmberOutgoingMessageType type, int16u indexOrDestination, EmberApsFrame ∗apsFrame, EmberMessageBuffer message)
• EmberStatus emberSendBroadcast (EmberNodeId destination, EmberApsFrame ∗apsFrame, int8u
radius, EmberMessageBuffer message)
• EmberStatus emberProxyBroadcast (EmberNodeId source, EmberNodeId destination, int8u sequence,
EmberApsFrame ∗apsFrame, int8u radius, EmberMessageBuffer message)
• EmberStatus emberSendManyToOneRouteRequest (int16u concentratorType, int8u radius)
• int8u emberAppendSourceRouteHandler (EmberNodeId destination, EmberMessageBuffer header)
• void emberIncomingRouteRecordHandler (EmberNodeId source, EmberEUI64 sourceEui, int8u relayCount, EmberMessageBuffer header, int8u relayListIndex)
• void emberIncomingManyToOneRouteRequestHandler (EmberNodeId source, EmberEUI64 longId, int8u cost)
• void emberIncomingRouteErrorHandler (EmberStatus status, EmberNodeId target)
• EmberStatus emberCancelMessage (EmberMessageBuffer message)
• void emberMessageSentHandler (EmberOutgoingMessageType type, int16u indexOrDestination, EmberApsFrame ∗apsFrame, EmberMessageBuffer message, EmberStatus status)
• void emberIncomingMessageHandler (EmberIncomingMessageType type, EmberApsFrame ∗apsFrame, EmberMessageBuffer message)
• EmberStatus emberGetLastHopLqi (int8u ∗lastHopLqi)
• EmberStatus emberGetLastHopRssi (int8s ∗lastHopRssi)
• EmberNodeId emberGetSender (void)
• EmberStatus emberGetSenderEui64 (EmberEUI64 senderEui64)
• EmberStatus emberSendReply (int16u clusterId, EmberMessageBuffer reply)
• void emberSetReplyFragmentData (int16u fragmentData)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
91
•
•
•
•
•
•
•
•
•
•
boolean emberAddressTableEntryIsActive (int8u addressTableIndex)
EmberStatus emberSetAddressTableRemoteEui64 (int8u addressTableIndex, EmberEUI64 eui64)
void emberSetAddressTableRemoteNodeId (int8u addressTableIndex, EmberNodeId id)
void emberGetAddressTableRemoteEui64 (int8u addressTableIndex, EmberEUI64 eui64)
EmberNodeId emberGetAddressTableRemoteNodeId (int8u addressTableIndex)
void emberSetExtendedTimeout (EmberEUI64 remoteEui64, boolean extendedTimeout)
boolean emberGetExtendedTimeout (EmberEUI64 remoteEui64)
void emberIdConflictHandler (EmberNodeId conflictingId)
boolean emberPendingAckedMessages (void)
EmberMessageBuffer makeInterPanMessage (InterPanHeader ∗headerData, EmberMessageBuffer
payload)
• int8u parseInterPanMessage (EmberMessageBuffer message, int8u startOffset, InterPanHeader ∗headerData)
Variables
• int16u emberApsAckTimeoutMs
• EmberMulticastTableEntry ∗ emberMulticastTable
• int8u emberMulticastTableSize
6.6.1
Detailed Description
See message.h for source code.
See also ami-inter-pan.h for source code.
6.6.2
Macro Definition Documentation
6.6.2.1
#define EMBER APSC MAX ACK WAIT HOPS MULTIPLIER MS
The per-hop delay allowed for in the calculation of the APS ACK timeout value. This is defined in the
ZigBee specification. This times the maximum number of hops (EMBER_MAX_HOPS) plus the terminal
encrypt/decrypt time is the timeout between retries of an APS acked message, in milliseconds.
Definition at line 32 of file message.h.
6.6.2.2
#define EMBER APSC MAX ACK WAIT TERMINAL SECURITY MS
The terminal encrypt/decrypt time allowed for in the calculation of the APS ACK timeout value. This is
defined in the ZigBee specification.
Definition at line 37 of file message.h.
6.6.2.3
#define INTER PAN UNICAST
Definition at line 29 of file ami-inter-pan.h.
6.6.2.4
#define INTER PAN BROADCAST
Definition at line 30 of file ami-inter-pan.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
92
6.6.2.5
#define INTER PAN MULTICAST
Definition at line 31 of file ami-inter-pan.h.
6.6.2.6
#define MAX INTER PAN MAC SIZE
Definition at line 34 of file ami-inter-pan.h.
6.6.2.7
#define STUB NWK SIZE
Definition at line 38 of file ami-inter-pan.h.
6.6.2.8
#define STUB NWK FRAME CONTROL
Definition at line 39 of file ami-inter-pan.h.
6.6.2.9
#define MAX STUB APS SIZE
Definition at line 42 of file ami-inter-pan.h.
6.6.2.10
#define MAX INTER PAN HEADER SIZE
Definition at line 45 of file ami-inter-pan.h.
6.6.3
Function Documentation
6.6.3.1 int8u emberMaximumApsPayloadLength ( void )
Returns the maximum size of the payload that the Application Support sub-layer will accept.
The size depends on the security level in use. The value is the same as that found in the node descriptor.
Returns
The maximum APS payload length.
6.6.3.2 EmberStatus emberSendMulticast ( EmberApsFrame ∗ apsFrame, int8u radius, int8u
nonmemberRadius, EmberMessageBuffer message )
Sends a multicast message to all endpoints that share a specific multicast ID and are within a specified
number of hops of the sender.
Parameters
apsFrame The APS frame for the message. The multicast will be sent to the groupId in this frame.
radius The message will be delivered to all nodes within this number of hops of the sender. A
value of zero is converted to EMBER_MAX_HOPS.
nonmember- The number of hops that the message will be forwarded by devices that are not members
Radius of the group. A value of 7 or greater is treated as infinite.
message A message.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
93
Returns
An EmberStatus value. For any result other than EMBER_SUCCESS, the message will not be sent.
• EMBER_SUCCESS - The message has been submitted for transmission.
• EMBER_INVALID_BINDING_INDEX - The bindingTableIndex refers to a non-multicast
binding.
• EMBER_NETWORK_DOWN - The node is not part of a network.
• EMBER_MESSAGE_TOO_LONG - The message is too large to fit in a MAC layer frame.
• EMBER_NO_BUFFERS - The free packet buffer pool is empty.
• EMBER_NETWORK_BUSY - Insufficient resources available in Network or MAC layers to
send message.
6.6.3.3 EmberStatus emberSendUnicast ( EmberOutgoingMessageType type, int16u
indexOrDestination, EmberApsFrame ∗ apsFrame, EmberMessageBuffer message )
Sends a unicast message as per the ZigBee specification.
The message will arrive at its destination only if there is a known route to the destination node. Setting the
::ENABLE_ROUTE_DISCOVERY option will cause a route to be discovered if none is known. Setting
the ::FORCE_ROUTE_DISCOVERY option will force route discovery. Routes to end-device children of
the local node are always known.
Setting the APS_RETRY option will cause the message to be retransmitted until either a matching acknowledgment is received or three transmissions have been made.
Note
Using the ::FORCE_ROUTE_DISCOVERY option will cause the first transmission to be consumed
by a route request as part of discovery, so the application payload of this packet will not reach its
destination on the first attempt. If you want the packet to reach its destination, the APS_RETRY
option must be set so that another attempt is made to transmit the message with its application payload
after the route has been constructed.
Setting the ::DESTINATION_EUI64 option will cause the long ID of the destination to be included in the
network header. This is the only way to absolutely guarantee that the message is delivered to the correct
node. Without it, a message may on occasion be delivered to the wrong destination in the event of an id
conflict that has not yet been detected and resolved by the network layer.
Note
When sending fragmented messages, the stack will only assign a new APS sequence number for the
first fragment of the message (i.e., EMBER_APS_OPTION_FRAGMENT is set and the low-order
byte of the groupId field in the APS frame is zero). For all subsequent fragments of the same message,
the application must set the sequence number field in the APS frame to the sequence number assigned
by the stack to the first fragment.
Parameters
type Specifies the outgoing message type. Must be one of EMBER_OUTGOING_DIRECT, EMBER_OUTGOING_VIA_ADDRESS_TABLE, or EMBER_OUTGOING_VIA_BINDING.
indexOr- Depending on the type of addressing used, this is either the EmberNodeId of the destiDestination nation, an index into the address table, or an index into the binding table.
The APS frame which is120-3016-000-4720
to be added to the message.
EmberZNet 4.7.2 API apsFrame
EM250
message Contents of the message.
94
Returns
An EmberStatus value. For any result other than EMBER_SUCCESS, the message will not be sent.
• EMBER_SUCCESS - The message has been submitted for transmission.
• EMBER_INVALID_BINDING_INDEX - The bindingTableIndex refers to a non-unicast
binding.
• EMBER_NETWORK_DOWN - The node is not part of a network.
• EMBER_MESSAGE_TOO_LONG - The message is too large to fit in a MAC layer frame.
• EMBER_MAX_MESSAGE_LIMIT_REACHED - The EMBER_APS_UNICAST_MESSAGE_COUNT limit has been reached.
6.6.3.4 EmberStatus emberSendBroadcast ( EmberNodeId destination, EmberApsFrame ∗
apsFrame, int8u radius, EmberMessageBuffer message )
Sends a broadcast message as per the ZigBee specification.
The message will be delivered to all nodes within radius hops of the sender. A radius of zero is converted
to EMBER_MAX_HOPS.
Parameters
destination The destination to which to send the broadcast. This must be one of three ZigBee
broadcast addresses.
apsFrame The APS frame data to be included in the message.
radius The maximum number of hops the message will be relayed.
message The actual message to be sent.
Returns
An EmberStatus value.
6.6.3.5 EmberStatus emberProxyBroadcast ( EmberNodeId source, EmberNodeId destination, int8u
sequence, EmberApsFrame ∗ apsFrame, int8u radius, EmberMessageBuffer message )
Proxies a broadcast message for another node.
The message will be delivered to all nodes within radius hops of the local node. A radius of zero is
converted to EMBER_MAX_HOPS.
Parameters
source The source from which to send the broadcast.
destination The destination to which to send the broadcast. This must be one of three ZigBee
broadcast addresses.
sequence The NWK sequence number for the message.
apsFrame The APS frame data to be included in the message.
radius The maximum number of hops the message will be relayed.
message The actual message to be sent.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
95
Returns
An EmberStatus value.
6.6.3.6 EmberStatus emberSendManyToOneRouteRequest ( int16u concentratorType, int8u radius )
Sends a route request packet that creates routes from every node in the network back to this node.
This function should be called by an application that wishes to communicate with many nodes, for example,
a gateway, central monitor, or controller. A device using this function was referred to as an "aggregator" in
EmberZNet 2.x and earlier, and is referred to as a "concentrator" in the ZigBee specification and EmberZNet 3.
This function enables large scale networks, because the other devices do not have to individually perform
bandwidth-intensive route discoveries. Instead, when a remote node sends an APS unicast to a concentrator,
its network layer automatically delivers a special route record packet first, which lists the network ids of all
the intermediate relays. The concentrator can then use source routing to send outbound APS unicasts. (A
source routed message is one in which the entire route is listed in the network layer header.) This allows the
concentrator to communicate with thousands of devices without requiring large route tables on neighboring
nodes.
This function is only available in ZigBee Pro (stack profile 2), and cannot be called on end devices. Any
router can be a concentrator (not just the coordinator), and there can be multiple concentrators on a network.
Note that a concentrator does not automatically obtain routes to all network nodes after calling this function.
Remote applications must first initiate an inbound APS unicast.
Many-to-one routes are not repaired automatically. Instead, the concentrator application must call this function to rediscover the routes as necessary, for example, upon failure of a retried APS message. The reason
for this is that there is no scalable one-size-fits-all route repair strategy. A common and recommended
strategy is for the concentrator application to refresh the routes by calling this function periodically.
Parameters
concentrator- Must be either EMBER_HIGH_RAM_CONCENTRATOR or EMBER_LOW_RAMType _CONCENTRATOR. The former is used when the caller has enough memory to store
source routes for the whole network. In that case, remote nodes stop sending route
records once the concentrator has successfully received one. The latter is used when
the concentrator has insufficient RAM to store all outbound source routes. In that case,
route records are sent to the concentrator prior to every inbound APS unicast.
radius The maximum number of hops the route request will be relayed. A radius of zero is
converted to EMBER_MAX_HOPS.
Returns
EMBER_SUCCESS if the route request was successfully submitted to the transmit queue, and EMBER_ERR_FATAL otherwise.
6.6.3.7 int8u emberAppendSourceRouteHandler ( EmberNodeId destination, EmberMessageBuffer
header )
The application can implement this callback to supply source routes to outgoing messages.
The application must define :EMBER_APPLICATION_HAS_SOURCE_ROUTING in its configuration
header to use this. The application uses the supplied destination to look up a source route. If available, the
EmberZNet 4.7.2 API EM250
120-3016-000-4720
96
application appends the source route to the supplied header using the proper frame format, as described in
section 3.4.1.9 "Source Route Subframe Field" of the ZigBee specification. If a source route is appended,
the stack takes care of setting the proper flag in the network frame control field. See app/util/source-route.c
for a sample implementation.
If header is :EMBER_NULL_MESSAGE_BUFFER the only action is to return the size of the source route
frame needed to the destination.
Parameters
destination The network destination of the message.
header The message buffer containing the partially complete packet header. The application
appends the source route frame to this header.
Returns
The size in bytes of the source route frame, or zero if there is not one available.
6.6.3.8
void emberIncomingRouteRecordHandler ( EmberNodeId source, EmberEUI64 sourceEui,
int8u relayCount, EmberMessageBuffer header, int8u relayListIndex )
Reports the arrival of a route record command frame to the application.
The route record command frame lists the short IDs of the relays that were used along the route from the
source to us. This information is used by aggregators to be able to initiate source routed messages. The
application must define EMBER_APPLICATION_HAS_SOURCE_ROUTING in its configuration header
to use this.
Parameters
source
sourceEui
relayCount
header
relayListIndex
6.6.3.9
The id of the node that initiated the route record.
The EUI64 of the node that initiated the route record.
The number of relays in the list.
The message buffer containing the route record frame.
The starting index of the relay list. The relay closest to the source is listed first, and the
relay closest to us is listed last. Short ids are stored low byte first. Be careful to use
buffer-boundary-safe APIs to read the list.
void emberIncomingManyToOneRouteRequestHandler ( EmberNodeId source, EmberEUI64
longId, int8u cost )
A callback indicating that a many-to-one route to the concentrator with the given short and long id is
available for use.
The application must define EMBER_APPLICATION_HAS_INCOMING_MANY_TO_ONE_ROUTE_REQUEST_HANDLER in its configuration header to use this.
Parameters
source The short id of the concentrator that initiated the many-to-one route request.
longId The EUI64 of the concentrator.
cost The path cost to the concentrator.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
97
6.6.3.10
void emberIncomingRouteErrorHandler ( EmberStatus status, EmberNodeId target )
A callback invoked when a route error message is received.
A status of EMBER_SOURCE_ROUTE_FAILURE indicates that a source-routed unicast sent from this
node encountered a broken link. Note that this case occurs only if this node is a concentrator using manyto-one routing for inbound messages and source-routing for outbound messages. The node prior to the
broken link generated the route error message and returned it to us along the many-to-one route.
A status of EMBER_MANY_TO_ONE_ROUTE_FAILURE also occurs only if we are a concentrator, and
indicates that a unicast sent to us along a many-to-one route encountered a broken link. The node prior to
the broken link generated the route error message and forwarded it to us via a randomly chosen neighbor,
taking advantage of the many-to-one nature of the route.
A status of EMBER_MAC_INDIRECT_TIMEOUT indicates that a message sent to the target end device
could not be delivered by the parent because the indirect transaction timer expired. Upon receipt of the
route error, the stack sets the extended timeout for the target node in the address table, if present. It then
calls this handler to indicate receipt of the error.
Note that if the original unicast data message is sent using the EMBER_APS_OPTION_RETRY option, a
new route error message is generated for each failed retry. Thus it is not unusual to receive three route error
messages in succession for a single failed retried APS unicast. On the other hand, it is also not guaranteed
that any route error messages will be delivered successfully at all. The only sure way to detect a route
failure is to use retried APS messages and to check the status of the emberMessageSentHandler().
If the application includes this callback, it must define EMBER_APPLICATION_HAS_INCOMING_ROUTE_ERROR_HANDLER in its configuration header.
Parameters
status EMBER_SOURCE_ROUTE_FAILURE, EMBER_MANY_TO_ONE_ROUTE_FAILURE, EMBER_MAC_INDIRECT_TIMEOUT
target The short id of the remote node.
6.6.3.11 EmberStatus emberCancelMessage ( EmberMessageBuffer message )
DEPRECATED.
Parameters
message A message.
Returns
Always returns EMBER_SUCCESS.
6.6.3.12
void emberMessageSentHandler ( EmberOutgoingMessageType type, int16u
indexOrDestination, EmberApsFrame ∗ apsFrame, EmberMessageBuffer message,
EmberStatus status )
A callback invoked by the stack when it has completed sending a message.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
98
Parameters
type The type of message sent.
indexOr- The destination to which the message was sent, for direct unicasts, or the address taDestination ble or binding index for other unicasts. The value is unspecified for multicasts and
broadcasts.
apsFrame The APS frame for the message.
message The message that was sent.
status An EmberStatus value of EMBER_SUCCESS if an ACK was received from the destination or EMBER_DELIVERY_FAILED if no ACK was received.
6.6.3.13
void emberIncomingMessageHandler ( EmberIncomingMessageType type, EmberApsFrame
∗ apsFrame, EmberMessageBuffer message )
A callback invoked by the EmberZNet stack when a message is received.
The following functions may be called from emberIncomingMessageHandler():
• emberGetLastHopLqi()
• emberGetLastHopRssi()
• emberGetSender()
• emberGetSenderEui64()
• emberGetBindingIndex()
• emberSendReply() (for incoming APS retried unicasts only)
• emberSetReplyBinding()
• emberNoteSendersBinding()
Parameters
type The type of the incoming message. One of the following:
• EMBER_INCOMING_UNICAST
• EMBER_INCOMING_UNICAST_REPLY
• EMBER_INCOMING_MULTICAST
• EMBER_INCOMING_MULTICAST_LOOPBACK
• EMBER_INCOMING_BROADCAST
• EMBER_INCOMING_BROADCAST_LOOPBACK
apsFrame The APS frame from the incoming message.
message The message that was sent.
6.6.3.14 EmberStatus emberGetLastHopLqi ( int8u ∗ lastHopLqi )
Gets the link quality from the node that last relayed the current message.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
99
Note
This function may only be called from within
• emberIncomingMessageHandler()
• emberNetworkFoundHandler()
• emberIncomingRouteRecordHandler()
• ::emberMacPassthroughMessageHandler()
• emberIncomingBootloadMessageHandler()
When this function is called from within one of these handler functions the link quality reported corresponds to the header being processed in that hander function. If this function is called outside of these
handler functions the link quality reported will correspond to a message that was processed earlier.
This function is not available from within emberPollHandler() or emberPollCompleteHandler(). The link
quality information of interest during the emberPollHandler() is from the data request packet itself. This
message must be handled quickly due to strict 15.4 timing requirements, and the link quality information is
not recorded by the stack. The link quality information of interest during the emberPollCompleteHandler()
is from the ACK to the data request packet. The ACK is handled by the hardware and the link quality
information does not make it up to the stack.
Parameters
lastHopLqi The link quality for the last incoming message processed.
Returns
This function always returns EMBER_SUCCESS. It is not necessary to check this return value.
6.6.3.15 EmberStatus emberGetLastHopRssi ( int8s ∗ lastHopRssi )
Gets the receive signal strength indication (RSSI) for the current message.
After a successful call to this function, the quantity referenced by lastHopRssi will contain the energy level
(in units of dBm) observed during the last packet received.
Note
This function may only be called from within:
•
•
•
•
•
emberIncomingMessageHandler()
emberNetworkFoundHandler()
emberIncomingRouteRecordHandler()
::emberMacPassthroughMessageHandler()
emberIncomingBootloadMessageHandler()
When this function is called from within one of these handler functions the RSSI reported corresponds
to the header being processed in that hander function. If this function is called outside of these handler
functions the RSSI reported will correspond to a message that was processed earlier.
This function is not available from within emberPollHandler() or emberPollCompleteHandler(). The RSSI
information of interest during the emberPollHandler() is from the data request packet itself. This message
must be handled quickly due to strict 15.4 timing requirements, and the RSSI information is not recorded
by the stack. The RSSI information of interest during the emberPollCompleteHandler() is from the ACK
to the data request packet. The ACK is handled by the hardware and the RSSI information does not make
it up to the stack.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
100
Parameters
lastHopRssi The RSSI for the last incoming message processed.
Returns
This function always returns EMBER_SUCCESS. It is not necessary to check this return value.
6.6.3.16 EmberNodeId emberGetSender ( void )
Returns the node ID of the sender of the current incoming message.
Note
This function can be called only from within emberIncomingMessageHandler().
Returns
The sender of the current incoming message.
6.6.3.17 EmberStatus emberGetSenderEui64 ( EmberEUI64 senderEui64 )
Returns the EUI64 of the sender of the current incoming message, if the sender chose to include this
information in the message. The EMBER_APS_OPTION_SOURCE_EUI64 bit in the options field of the
APS frame of the incoming message indicates that the EUI64 is present in the message.
Note
This function can be called only from within emberIncomingMessageHandler().
Parameters
senderEui64 The EUI64 of the sender.
Returns
An EmberStatus value:
• EMBER_SUCCESS - senderEui64 has been set to the EUI64 of the sender of the current incoming message.
• EMBER_INVALID_CALL - Either:
1. This function was called outside of the context of the emberIncomingMessageHandler()
callback
2. It was called in the context of emberIncomingMessageHandler() but the incoming message
did not include the EUI64 of the sender.
6.6.3.18 EmberStatus emberSendReply ( int16u clusterId, EmberMessageBuffer reply )
Sends a reply for an application that has received a unicast message.
The reply will be included with the ACK that the stack automatically sends back.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
101
Note
This function may be called only from within emberIncomingMessageHandler().
Parameters
clusterId The cluster ID to use for the reply.
reply A reply message.
Returns
An EmberStatus value. For any result other than EMBER_SUCCESS, the message will not be sent.
• EMBER_SUCCESS - The message has been submitted for transmission.
• EMBER_INVALID_CALL - Either:
1. This function was called outside of the context of the emberIncomingMessageHandler()
callback
2. It was called in the context of emberIncomingMessageHandler() but the incoming message
was not a unicast
3. It was called more than once in the context of emberIncomingMessageHandler().
• EMBER_NETWORK_BUSY - Either:
1. No route available.
2. Insufficient resources available in Network or MAC layers to send message.
6.6.3.19
void emberSetReplyFragmentData ( int16u fragmentData )
Sets the fragment data to be used when sending a reply to a unicast message.
Note
This function may be called only from within emberIncomingMessageHandler().
Parameters
fragmentData The low byte is the block number of the reply. The high byte is the ack bitfield of the
reply.
6.6.3.20 boolean emberAddressTableEntryIsActive ( int8u addressTableIndex )
Indicates whether any messages are currently being sent using this address table entry.
Note that this function does not indicate whether the address table entry is unused. To determine whether
an address table entry is unused, check the remote node ID. The remote node ID will have the value EMBER_TABLE_ENTRY_UNUSED_NODE_ID when the address table entry is not in use.
Parameters
addressTable- The index of an address table entry.
Index
EmberZNet 4.7.2 API EM250
120-3016-000-4720
102
Returns
TRUE if the address table entry is active, FALSE otherwise.
6.6.3.21 EmberStatus emberSetAddressTableRemoteEui64 ( int8u addressTableIndex, EmberEUI64
eui64 )
Sets the EUI64 of an address table entry.
This function will also check other address table entries, the child table and the neighbor table to see if the
node ID for the given EUI64 is already known. If known then this function will also set the node ID. If not
known it will set the node ID to EMBER_UNKNOWN_NODE_ID.
Parameters
addressTable- The index of an address table entry.
Index
eui64 The EUI64 to use for the address table entry.
Returns
EMBER_SUCCESS if the EUI64 was successfully set, and EMBER_ADDRESS_TABLE_ENTRY_IS_ACTIVE otherwise.
6.6.3.22
void emberSetAddressTableRemoteNodeId ( int8u addressTableIndex, EmberNodeId id )
Sets the short ID of an address table entry.
Usually the application will not need to set the short ID in the address table. Once the remote EUI64 is set
the stack is capable of figuring out the short ID on its own. However, in cases where the application does
set the short ID, the application must set the remote EUI64 prior to setting the short ID.
Parameters
addressTable- The index of an address table entry.
Index
id The short ID corresponding to the remote node whose EUI64 is stored in the address
table at the given index or EMBER_TABLE_ENTRY_UNUSED_NODE_ID which
indicates that the entry stored in the address table at the given index is not in use.
6.6.3.23
void emberGetAddressTableRemoteEui64 ( int8u addressTableIndex, EmberEUI64 eui64 )
Gets the EUI64 of an address table entry.
Parameters
addressTable- The index of an address table entry.
Index
eui64 The EUI64 of the address table entry is copied to this location.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
103
6.6.3.24 EmberNodeId emberGetAddressTableRemoteNodeId ( int8u addressTableIndex )
Gets the short ID of an address table entry.
Parameters
addressTable- The index of an address table entry.
Index
Returns
One of the following:
• The short ID corresponding to the remote node whose EUI64 is stored in the address table at the
given index.
• EMBER_UNKNOWN_NODE_ID - Indicates that the EUI64 stored in the address table at the
given index is valid but the short ID is currently unknown.
• EMBER_DISCOVERY_ACTIVE_NODE_ID - Indicates that the EUI64 stored in the address
table at the given location is valid and network address discovery is underway.
• EMBER_TABLE_ENTRY_UNUSED_NODE_ID - Indicates that the entry stored in the address
table at the given index is not in use.
6.6.3.25
void emberSetExtendedTimeout ( EmberEUI64 remoteEui64, boolean extendedTimeout )
Tells the stack whether or not the normal interval between retransmissions of a retried unicast message
should be increased by EMBER_INDIRECT_TRANSMISSION_TIMEOUT.
The interval needs to be increased when sending to a sleepy node so that the message is not retransmitted
until the destination has had time to wake up and poll its parent. The stack will automatically extend the
timeout:
• For our own sleepy children.
• When an address response is received from a parent on behalf of its child.
• When an indirect transaction expiry route error is received.
• When an end device announcement is received from a sleepy node.
Parameters
remoteEui64 The address of the node for which the timeout is to be set.
extended- TRUE if the retry interval should be increased by EMBER_INDIRECT_TRANSMISTimeout SION_TIMEOUT. FALSE if the normal retry interval should be used.
6.6.3.26 boolean emberGetExtendedTimeout ( EmberEUI64 remoteEui64 )
Indicates whether or not the stack will extend the normal interval between retransmissions of a retried
unicast message by EMBER_INDIRECT_TRANSMISSION_TIMEOUT.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
104
Parameters
remoteEui64 The address of the node for which the timeout is to be returned.
Returns
TRUE if the retry interval will be increased by EMBER_INDIRECT_TRANSMISSION_TIMEOUT
and FALSE if the normal retry interval will be used.
6.6.3.27
void emberIdConflictHandler ( EmberNodeId conflictingId )
A callback invoked by the EmberZNet stack when an ID conflict is discovered, that is, two different nodes
in the network were found to be using the same short ID.
The stack automatically removes the conflicting short ID from its internal tables (address, binding, route,
neighbor, and child tables). The application should discontinue any other use of the ID. If the application
includes this callback, it must define ::EMBER_APPLICATION_HAS_ID_CONFLICT_HANDLER in its
configuration header.
Parameters
conflictingId The short ID for which a conflict was detected.
6.6.3.28 boolean emberPendingAckedMessages ( void )
Indicates whether there are pending messages in the APS retry queue.
Returns
TRUE if there is at least a pending message belonging to the current network in the APS retry queue,
FALSE otherwise.
6.6.3.29 EmberMessageBuffer makeInterPanMessage ( InterPanHeader ∗ headerData,
EmberMessageBuffer payload )
Creates an interpan message suitable for passing to emberSendRawMessage().
6.6.3.30 int8u parseInterPanMessage ( EmberMessageBuffer message, int8u startOffset,
InterPanHeader ∗ headerData )
This is meant to be called on the message and offset values passed to emberMacPassthroughMessageHandler(...). The header is parsed and the various fields are written to the InterPanHeader. The returned
value is the offset of the payload in the message, or 0 if the message is not a correctly formed AMI interPAN
message.
6.6.4
Variable Documentation
EmberZNet 4.7.2 API EM250
120-3016-000-4720
105
6.6.4.1 int16u emberApsAckTimeoutMs
The APS ACK timeout value. The stack waits this amount of time between resends of APS retried messages. The default value is:
((EMBER_APSC_MAX_ACK_WAIT_HOPS_MULTIPLIER_MS
* EMBER_MAX_HOPS)
+ EMBER_APSC_MAX_ACK_WAIT_TERMINAL_SECURITY_MS)
6.6.4.2 EmberMulticastTableEntry∗ emberMulticastTable
The multicast table.
Each entry contains a multicast ID and an endpoint, indicating that the endpoint is a member of the multicast
group. Only devices with an endpoint in a multicast group will receive messages sent to that multicast
group.
Entries with with an endpoint of 0 are ignored (the ZDO does not a member of any multicast groups). All
endpoints are initialized to 0 on startup.
6.6.4.3 int8u emberMulticastTableSize
The number of entries in the multicast table.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
106
6.7
End Devices
Functions
• EmberNodeId emberChildId (int8u childIndex)
• int8u emberChildIndex (EmberNodeId childId)
• EmberStatus emberGetChildData (int8u index, EmberEUI64 childEui64Return, EmberNodeType
∗childTypeReturn)
• void emberChildJoinHandler (int8u index, boolean joining)
• EmberStatus emberPollForData (void)
• void emberPollCompleteHandler (EmberStatus status)
• EmberStatus emberSetMessageFlag (EmberNodeId childId)
• EmberStatus emberClearMessageFlag (EmberNodeId childId)
• void emberPollHandler (EmberNodeId childId, boolean transmitExpected)
• int8u emberChildCount (void)
• int8u emberRouterChildCount (void)
• int8u emberMaxChildCount (void)
• int8u emberMaxRouterChildCount (void)
• EmberNodeId emberGetParentNodeId (void)
• EmberEUI64 emberGetParentEui64 (void)
Power Management
• enum {
EMBER_OUTGOING_MESSAGES, EMBER_INCOMING_MESSAGES, EMBER_RADIO_IS_ON, EMBER_TRANSPORT_ACTIVE,
EMBER_APS_LAYER_ACTIVE, EMBER_ASSOCIATING, EMBER_ZLL_TOUCH_LINKING
}
• int16u emberCurrentStackTasks (void)
• boolean emberOkToNap (void)
• boolean emberOkToHibernate (void)
• boolean emberOkToLongPoll (void)
• void emberStackPowerDown (void)
• void emberStackPowerUp (void)
• #define EMBER_HIGH_PRIORITY_TASKS
6.7.1
Detailed Description
EmberZNet API relating to end device children. See child.h for source code.
6.7.2
Macro Definition Documentation
6.7.2.1
#define EMBER HIGH PRIORITY TASKS
A mask of the tasks that prevent a device from sleeping.
Definition at line 256 of file child.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
107
6.7.3
Enumeration Type Documentation
6.7.3.1
anonymous enum
Defines tasks that prevent the stack from sleeping.
Enumerator:
EMBER_OUTGOING_MESSAGES There are messages waiting for transmission.
EMBER_INCOMING_MESSAGES One or more incoming messages are being processed.
EMBER_RADIO_IS_ON The radio is currently powered on. On sleepy devices the radio is turned
off when not in use. On non-sleepy devices (EMBER_COORDINATOR, EMBER_ROUTER,
or EMBER_END_DEVICE) the radio is always on.
EMBER_TRANSPORT_ACTIVE The transport layer has messages awaiting an ACK.
EMBER_APS_LAYER_ACTIVE The ZigBee APS layer has messages awaiting an ACK.
EMBER_ASSOCIATING The node is currently trying to associate with a network.
EMBER_ZLL_TOUCH_LINKING The node is currently touch linking.
Definition at line 233 of file child.h.
6.7.4
Function Documentation
6.7.4.1 EmberNodeId emberChildId ( int8u childIndex )
Converts a child index to a node ID.
Parameters
childIndex The index.
Returns
The node ID of the child or EMBER_NULL_NODE_ID if there isn’t a child at the childIndex specified.
6.7.4.2 int8u emberChildIndex ( EmberNodeId childId )
Converts a node ID to a child index.
Parameters
childId The node ID of the child.
Returns
The child index or 0xFF if the node ID does not belong to a child.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
108
6.7.4.3 EmberStatus emberGetChildData ( int8u index, EmberEUI64 childEui64Return,
EmberNodeType ∗ childTypeReturn )
If there is a child at ’index’ this copies its EUI64 and node type into the return variables and returns EMBER_SUCCESS. If there is no child at ’index’ it returns EMBER_NOT_JOINED. Possible child indexes
run from zero to emberMaxChildCount() - 1.
Parameters
index The index of the child of interest.
childEui64- The child’s EUI64 is copied into here.
Return
childType- The child’s node type is copied into here.
Return
Returns
Returns EMBER_SUCCESS if a child is found at that index, EMBER_NOT_JOINED if not.
6.7.4.4
void emberChildJoinHandler ( int8u index, boolean joining )
This is called by the stack when a child joins or leaves. ’Joining’ is TRUE if the child is joining and FALSE
if leaving.
The index is the same as the value that should be passed to emberGetChildData() to get this child’s data.
Note that if the child is leaving emberGetChildData() will now return EMBER_NOT_JOINED if called
with this index. If the application includes emberChildJoinHandler(), it must define EMBER_APPLICATION_HAS_CHILD_JOIN_HANDLER in its CONFIGURATION_HEADER
Parameters
index The index of the child of interest.
joining True if the child is joining, false if the child is leaving.
6.7.4.5 EmberStatus emberPollForData ( void )
Function to request any pending data from the parent node. This function allows an end device to query its
parent for any pending data.
End devices must call this function periodically to maintain contact with their parent. The parent will
remove a mobile end device from its child table if it has not received a poll from it within the last EMBER_MOBILE_NODE_POLL_TIMEOUT quarter seconds. It will remove a sleepy or non-sleepy end
device if it has not received a poll from it within the last EMBER_END_DEVICE_POLL_TIMEOUT <<
EMBER_END_DEVICE_POLL_TIMEOUT_SHIFT seconds.
If the end device has lost contact with its parent, emberPollForData() calls ::emberRejoinNetwork(TRUE)
and returns EMBER_ERR_FATAL.
The default values for the timeouts are set in config/ember-configuration-defaults.h, and can be overridden
in the application’s configuration header.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
109
Returns
An EmberStatus value:
• EMBER_SUCCESS - The poll message has been submitted for transmission.
• EMBER_INVALID_CALL - The node is not an end device.
• EMBER_NOT_JOINED - The node is not part of a network.
• EMBER_MAC_TRANSMIT_QUEUE_FULL - The MAC layer transmit queue is full.
• EMBER_NO_BUFFERS - There were no buffers available to create the data poll message.
• EMBER_ERR_FATAL - Too much time has elapsed since the last successful poll. A rejoin
attempt has been initiated. This error is not "fatal". The command can be retried until successful.
6.7.4.6
void emberPollCompleteHandler ( EmberStatus status )
@ brief This is called by the stack when a data poll to the parent is complete.
If the application includes emberPollCompleteHandler(), it must define EMBER_APPLICATION_HAS_POLL_COMPLETE_HANDLER within its CONFIGURATION_HEADER
Parameters
status An EmberStatus value:
• EMBER_SUCCESS - Data was received in response to the poll.
• EMBER_MAC_NO_DATA - No data was pending.
• EMBER_DELIVERY_FAILED - The poll message could not be sent.
• EMBER_MAC_NO_ACK_RECEIVED - The poll message was sent but not acknowledged by the parent.
6.7.4.7 EmberStatus emberSetMessageFlag ( EmberNodeId childId )
Sets a flag to indicate that there is a message pending for a child. The next time that the child polls, it will
be informed that it has a pending message. The message is sent from emberPollHandler, which is called
when the child requests the data.
Parameters
childId The ID of the child that just polled for data.
Returns
An EmberStatus value.
• EMBER_SUCCESS - The next time that the child polls, it will be informed that it has pending
data.
• EMBER_NOT_JOINED - The child identified by childId is not our child (it is not in the PAN).
EmberZNet 4.7.2 API EM250
120-3016-000-4720
110
6.7.4.8 EmberStatus emberClearMessageFlag ( EmberNodeId childId )
Clears a flag to indicate that there are no more messages for a child. The next time the child polls, it will
be informed that it does not have any pending messages.
Parameters
childId The ID of the child that no longer has pending messages.
Returns
An EmberStatus value.
• EMBER_SUCCESS - The next time that the child polls, it will be informed that it does not have
any pending messages.
• EMBER_NOT_JOINED - The child identified by childId is not our child (it is not in the PAN).
6.7.4.9
void emberPollHandler ( EmberNodeId childId, boolean transmitExpected )
A callback that allows the application to send a message in response to a poll from a child.
This function is called when a child polls, provided that the pending message flag is set for that child
(see emberSetMessageFlag(). The message should be sent to the child using emberSendUnicast() with the
EMBER_APS_OPTION_POLL_RESPONSE option.
If the application includes ::emberPollHanlder(), it must define EMBER_APPLICATION_HAS_POLL_HANDLER in its CONFIGURATION_HEADER.
Parameters
childId The ID of the child that is requesting data.
transmit- TRUE if the child is expecting an application- supplied data message. FALSE otherExpected wise.
6.7.4.10 int8u emberChildCount ( void )
Returns the number of children the node currently has.
Returns
number of children
6.7.4.11 int8u emberRouterChildCount ( void )
Returns the number of router children that the node currently has.
Returns
number of router children
EmberZNet 4.7.2 API EM250
120-3016-000-4720
111
6.7.4.12 int8u emberMaxChildCount ( void )
Returns the maximum number of children for this node. The return value is undefined for nodes that are
not joined to a network.
Returns
maximum number of children
6.7.4.13 int8u emberMaxRouterChildCount ( void )
Returns the maximum number of router children for this node. The return value is undefined for nodes that
are not joined to a network.
Returns
maximum number of router children
6.7.4.14 EmberNodeId emberGetParentNodeId ( void )
Returns the parent’s node ID. The return value is undefined for nodes without parents (coordinators and
nodes that are not joined to a network).
Returns
parent’s node ID
6.7.4.15 EmberEUI64 emberGetParentEui64 ( void )
Returns the parent’s EUI64. The return value is undefined for nodes without parents (coordinators and
nodes that are not joined to a network).
Returns
parent’s EUI64
6.7.4.16 int16u emberCurrentStackTasks ( void )
Returns a bitmask indicating the stack’s current tasks.
The mask EMBER_HIGH_PRIORITY_TASKS defines which tasks are high priority. Devices should not
sleep if any high priority tasks are active. Active tasks that are not high priority are waiting for messages
to arrive from other devices. If there are active tasks, but no high priority ones, the device may sleep but
should periodically wake up and call emberPollForData() in order to receive messages. Parents will hold
messages for EMBER_INDIRECT_TRANSMISSION_TIMEOUT milliseconds before discarding them.
Returns
A bitmask of the stack’s active tasks.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
112
6.7.4.17 boolean emberOkToNap ( void )
Indicates whether the stack is currently in a state where there are no high priority tasks and may sleep.
There may be tasks expecting incoming messages, in which case the device should periodically wake up
and call emberPollForData() in order to receive messages. This function can only be called when the node
type is EMBER_SLEEPY_END_DEVICE or EMBER_MOBILE_END_DEVICE.
Returns
TRUE if the application may sleep but the stack may be expecting incoming messages.
6.7.4.18 boolean emberOkToHibernate ( void )
Indicates whether the stack currently has any tasks pending.
If there are no pending tasks then emberTick() does not need to be called until the next time a stack API
function is called. This function can only be called when the node type is EMBER_SLEEPY_END_DEVICE or EMBER_MOBILE_END_DEVICE.
Returns
TRUE if the application may sleep for as long as it wishes.
6.7.4.19 boolean emberOkToLongPoll ( void )
Indicates whether the stack is currently in a state that does not require the application to periodically poll.
Returns
TRUE if the application may stop polling periodically.
6.7.4.20
void emberStackPowerDown ( void )
Immediately turns the radio power completely off.
After calling this function, you must not call any other stack function except emberStackPowerUp(). This
is because all other stack functions require that the radio is powered on for their proper operation.
6.7.4.21
void emberStackPowerUp ( void )
Initializes the radio. Typically called coming out of deep sleep.
For non-sleepy devices, also turns the radio on and leaves it in rx mode.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
113
6.8
Security
Modules
• Trust Center
• Smart Energy Security
Macros
• #define EMBER_JOIN_NO_PRECONFIG_KEY_BITMASK
• #define EMBER_JOIN_PRECONFIG_KEY_BITMASK
Functions
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
6.8.1
EmberStatus emberSetInitialSecurityState (EmberInitialSecurityState ∗state)
EmberStatus emberSetExtendedSecurityBitmask (EmberExtendedSecurityBitmask mask)
EmberStatus emberGetExtendedSecurityBitmask (EmberExtendedSecurityBitmask ∗mask)
EmberStatus emberGetCurrentSecurityState (EmberCurrentSecurityState ∗state)
EmberStatus emberGetKey (EmberKeyType type, EmberKeyStruct ∗keyStruct)
boolean emberHaveLinkKey (EmberEUI64 remoteDevice)
EmberStatus emberGenerateRandomKey (EmberKeyData ∗keyAddress)
void emberSwitchNetworkKeyHandler (int8u sequenceNumber)
EmberStatus emberRequestLinkKey (EmberEUI64 partner)
void emberZigbeeKeyEstablishmentHandler (EmberEUI64 partner, EmberKeyStatus status)
EmberStatus emberGetKeyTableEntry (int8u index, EmberKeyStruct ∗result)
EmberStatus emberSetKeyTableEntry (int8u index, EmberEUI64 address, boolean linkKey, EmberKeyData ∗keyData)
EmberStatus emberAddOrUpdateKeyTableEntry (EmberEUI64 address, boolean linkKey, EmberKeyData ∗keyData)
int8u emberFindKeyTableEntry (EmberEUI64 address, boolean linkKey)
EmberStatus emberEraseKeyTableEntry (int8u index)
EmberStatus emberClearKeyTable (void)
EmberStatus emberStopWritingStackTokens (void)
EmberStatus emberStartWritingStackTokens (void)
boolean emberWritingStackTokensEnabled (void)
EmberStatus emberApsCryptMessage (boolean encrypt, EmberMessageBuffer buffer, int8u apsHeaderEndIndex, EmberEUI64 remoteEui64)
EmberStatus emberGetMfgSecurityConfig (EmberMfgSecurityStruct ∗settings)
EmberStatus emberSetMfgSecurityConfig (int32u magicNumber, const EmberMfgSecurityStruct ∗settings)
Detailed Description
This file describes the functions necessary to manage security for a regular device. There are three major
modes for security and applications should link in the appropriate library:
• Residential security uses only network keys. This is the only supported option for ZigBee 2006
devices.
• Standard security uses network keys with optional link keys. Ember strongly recommends using
Link Keys. It is possible for 2006 devices to run on a network that uses Standard Security.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
114
• High Security uses network keys and requires link keys derived via SKKE. Devices that do not
support link keys (i.e. 2006 devices) are not allowed. High Security also uses Entity Authentication
to synchronize frame counters between neighboring devices and children.
See security.h for source code.
6.8.2
Macro Definition Documentation
6.8.2.1
#define EMBER JOIN NO PRECONFIG KEY BITMASK
A non-Trust Center Device configuration bitmask example. There is no Preconfigured Link Key, so the
NWK key is expected to be sent in-the-clear. The device will request a Trust Center Link key after getting
the Network Key.
Definition at line 96 of file security.h.
6.8.2.2
#define EMBER JOIN PRECONFIG KEY BITMASK
A non-Trust Center device configuration bitmask example. The device has a Preconfigured Link Key and
expects to receive a NWK Key encrypted at the APS Layer. A NWK key sent in-the-clear will be rejected.
Definition at line 106 of file security.h.
6.8.3
Function Documentation
6.8.3.1 EmberStatus emberSetInitialSecurityState ( EmberInitialSecurityState ∗ state )
This function sets the initial security state that will be used by the device when it forms or joins a network.
If security is enabled then this function must be called prior to forming or joining the network. It must also
be called if the device left the network and wishes to form or join another network.
This call should not be used when restoring prior network operation from saved state via emberNetworkInit as this will cause saved security settings and keys table from the prior network to be erased, resulting
in improper keys and/or frame counter values being used, which will prevent proper communication with
other devices in the network. Calling emberNetworkInit is sufficient to restore all saved security settings
after a reboot and re-enter the network.
The call may be used by either the Trust Center or non Trust Center devices, the options that are set are
different depending on which role the device will assume. See the EmberInitialSecurityState structure for
more explanation about the various security settings.
The function will return EMBER_SECURITY_CONFIGURATION_INVALID in the following cases:
• Distributed Trust Center Mode was enabled with Hashed Link Keys.
• High Security was specified.
Parameters
state The security configuration to be set.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
115
Returns
An EmberStatus value. EMBER_SUCCESS if the security state has been set successfully. EMBER_INVALID_CALL if the device is not in the EMBER_NO_NETWORK state. The value EMBER_SECURITY_CONFIGURATION_INVALID is returned if the combination of security parameters is not
valid. EMBER_KEY_INVALID is returned if a reserved or invalid key value was passed in the key
structure for one of the keys.
6.8.3.2 EmberStatus emberSetExtendedSecurityBitmask ( EmberExtendedSecurityBitmask mask )
Sets the extended initial security bitmask.
Parameters
mask An object of type EmberExtendedSecurityBitmask that indicates what the extended
security bitmask should be set to.
Returns
EMBER_SUCCESS if the security settings were successfully retrieved. EMBER_INVALID_CALL
otherwise.
6.8.3.3 EmberStatus emberGetExtendedSecurityBitmask ( EmberExtendedSecurityBitmask ∗ mask )
Gets the extended security bitmask that is being used by a device.
Parameters
mask A pointer to an EmberExtendedSecurityBitmask value into which the extended security
bitmask will be copied.
Returns
EMBER_SUCCESS if the security settings were successfully retrieved. EMBER_INVALID_CALL
otherwise.
6.8.3.4 EmberStatus emberGetCurrentSecurityState ( EmberCurrentSecurityState ∗ state )
Gets the security state that is being used by a device joined into the Network.
Parameters
state A pointer to an EmberCurrentSecurityState value into which the security configuration
will be copied.
Returns
EMBER_SUCCESS if the security settings were successfully retrieved. EMBER_NOT_JOINED if
the device is not currently joined in the network.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
116
6.8.3.5 EmberStatus emberGetKey ( EmberKeyType type, EmberKeyStruct ∗ keyStruct )
Gets the specified key and its associated data. This can retrieve the Trust Center Link Key, Current Network
Key, or Next Network Key. On the 35x series chips, the data returned by this call is governed by the security
policy set in the manufacturing token for TOKEN_MFG_SECURITY_CONFIG. See the API calls emberSetMfgSecurityConfig() and emberGetMfgSecurityConfig() for more information. If the security policy is
not set to EMBER_KEY_PERMISSIONS_READING_ALLOWED, then the actual encryption key value
will not be returned. Other meta-data about the key will be returned. The 2xx series chips have no such
restrictions.
Parameters
type The Type of key to get (e.g. Trust Center Link or Network).
keyStruct A pointer to the EmberKeyStruct data structure that will be populated with the pertinent
information.
Returns
EMBER_SUCCESS if the key was retrieved successfully. EMBER_INVALID_CALL if an attempt
was made to retrieve an EMBER_APPLICATION_LINK_KEY or EMBER_APPLICATION_MASTER_KEY.
6.8.3.6 boolean emberHaveLinkKey ( EmberEUI64 remoteDevice )
Returns TRUE if a link key is available for securing messages sent to the remote device.
Parameters
remoteDevice The long address of a some other device in the network.
Returns
boolean Returns TRUE if a link key is available.
6.8.3.7 EmberStatus emberGenerateRandomKey ( EmberKeyData ∗ keyAddress )
Generates a Random Key (link, network, or master) and returns the result.
It copies the key into the array that result points to. This is an time-expensive operation as it needs to
obtain truly random numbers.
Parameters
keyAddress A pointer to the location in which to copy the generated key.
Returns
EMBER_SUCCESS on success, EMBER_INSUFFICIENT_RANDOM_DATA on failure.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
117
6.8.3.8
void emberSwitchNetworkKeyHandler ( int8u sequenceNumber )
A callback to inform the application that the Network Key has been updated and the node has been switched
over to use the new key. The actual key being used is not passed up, but the sequence number is.
Parameters
sequence- The sequence number of the new network key.
Number
6.8.3.9 EmberStatus emberRequestLinkKey ( EmberEUI64 partner )
A function to request a Link Key from the Trust Center with another device device on the Network (which
could be the Trust Center). A Link Key with the Trust Center is possible but the requesting device cannot
be the Trust Center. Link Keys are optional in ZigBee Standard Security and thus the stack cannot know
whether the other device supports them.
If the partner device is the Trust Center, then only that device needs to request the key. The Trust Center
will immediately respond to those requests and send the key back to the device.
If the partner device is not the Trust Center, then both devices must request an Application Link Key with
each other. The requests will be sent to the Trust Center for it to answer. The Trust Center will store the
first request and wait EMBER_REQUEST_KEY_TIMEOUT for the second request to be received. The
Trust Center only supports one outstanding Application key request at a time and therefore will ignore
other requests that are not associated with the first request.
Sleepy devices should poll at a higher rate until a response is received or the request times out.
The success or failure of the request is returned via emberZigbeeKeyEstablishmentHandler(...)
Parameters
partner The IEEE address of the partner device. If NULL is passed in then the Trust Center
IEEE Address is assumed.
Returns
EMBER_SUCCESS if the call succeeds, or EMBER_NO_BUFFERS.
6.8.3.10
void emberZigbeeKeyEstablishmentHandler ( EmberEUI64 partner, EmberKeyStatus status )
A callback to the application to notify it of the status of the request for a Link Key. The application
should define EMBER_APPLICATION_HAS_ZIGBEE_KEY_ESTABLISHMENT_HANDLER in order
to implement its own handler.
Parameters
partner The IEEE address of the partner device. Or all zeros if the Key establishment failed.
status The status of the key establishment.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
118
6.8.3.11 EmberStatus emberGetKeyTableEntry ( int8u index, EmberKeyStruct ∗ result )
A function used to obtain data from the Key Table. On the 35x series chips, the data returned by this
call is governed by the security policy set in the manufacturing token for TOKEN_MFG_SECURITY_CONFIG. See the API calls emberSetMfgSecurityConfig() and emberGetMfgSecurityConfig() for more
information. If the security policy is not set to EMBER_KEY_PERMISSIONS_READING_ALLOWED,
then the actual encryption key value will not be returned. Other meta-data about the key will be returned.
The 2xx series chips have no such restrictions.
Parameters
index The index in the key table of the entry to get.
result A pointer to the location of an EmberKeyStruct that will contain the results retrieved
by the stack.
Returns
EMBER_TABLE_ENTRY_ERASED if the index is an erased key entry. EMBER_INDEX_OUT_OF_RANGE if the passed index is not valid. EMBER_SUCCESS on success.
6.8.3.12 EmberStatus emberSetKeyTableEntry ( int8u index, EmberEUI64 address, boolean linkKey,
EmberKeyData ∗ keyData )
A function to set an entry in the key table.
Parameters
index
address
keyData
linkKey
The index in the key table of the entry to set.
The address of the partner device associated with the key.
A pointer to the key data associated with the key entry.
A boolean indicating whether this is a Link or Master Key.
Returns
EMBER_KEY_INVALID if the passed key data is using one of the reserved key values. EMBER_INDEX_OUT_OF_RANGE if passed index is not valid. EMBER_SUCCESS on success.
6.8.3.13 EmberStatus emberAddOrUpdateKeyTableEntry ( EmberEUI64 address, boolean linkKey,
EmberKeyData ∗ keyData )
This function add a new entry in the key table or updates an existing entry with a new key. It first searches
the key table for an entry that has a matching EUI64. If it does not find one it searches for the first free
entry. If it is successful in either case, it sets the entry with the EUI64, key data, and flag that indicates if it
is a Link or Master Key. The Incoming Frame Counter for that key is also reset to 0. If no existing entry
was found, and there was not a free entry in the table, then the call will fail.
Parameters
address The IEEE Address of the partner device that shares the key.
linkKey A boolean indicating whether this is a Link or Master key.
keyData A pointer to the actual key data.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
119
Returns
EMBER_TABLE_FULL if no free entry was found to add. EMBER_KEY_INVALID if the passed
key was a reserved value. ::EMBER_KEY_TABLE_ADDRESS_NOT_VALID if the passed address
is reserved or invalid. EMBER_SUCCESS on success.
6.8.3.14 int8u emberFindKeyTableEntry ( EmberEUI64 address, boolean linkKey )
A function to search the key table and find an entry matching the specified IEEE address and key type.
Parameters
address The IEEE Address of the partner device that shares the key. To find the first empty
entry pass in an address of all zeros.
linkKey A boolean indicating whether to search for an entry containing a Link or Master Key.
Returns
The index that matches the search criteria, or 0xFF if no matching entry was found.
6.8.3.15 EmberStatus emberEraseKeyTableEntry ( int8u index )
A function to clear a single entry in the key table.
Parameters
index The index in the key table of the entry to erase.
Returns
EMBER_SUCCESS if the index is valid and the key data was erased. EMBER_KEY_INVALID if
the index is out of range for the size of the key table.
6.8.3.16 EmberStatus emberClearKeyTable ( void )
This function clears the key table of the current network.
Returns
EMBER_SUCCESS if the key table was successfully cleared. EMBER_INVALID_CALL otherwise.
6.8.3.17 EmberStatus emberStopWritingStackTokens ( void )
This function suppresses normal write operations of the stack tokens. This is only done in rare circumstances when the device already has network parameters but needs to conditionally rejoin a network in
order to perform a security message exchange (i.e. key establishment). If the network is not authenticated
properly, it will need to forget any stack data it used and return to the old network. By suppressing writing of the stack tokens the device will not have stored any persistent data about the network and a reboot
will clear the RAM copies. The Smart Energy profile feature Trust Center Swap-out uses this in order to
securely replace the Trust Center and re-authenticate to it.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
120
Returns
EMBER_SUCCESS if it could allocate temporary buffers to store network information. EMBER_NO_BUFFERS otherwise.
6.8.3.18 EmberStatus emberStartWritingStackTokens ( void )
This function will immediately write the value of stack tokens and then resume normal network operation
by writing the stack tokens at appropriate intervals or changes in state. It has no effect unless a previous
call was made to emberStopWritingStackTokens().
Returns
EMBER_SUCCESS if it had previously unwritten tokens from a call to emberStopWritingStackTokens() that it now wrote to the token system. EMBER_INVALID_CALL otherwise.
6.8.3.19 boolean emberWritingStackTokensEnabled ( void )
This function will determine whether stack tokens will be written to persistent storage when they change.
By default it is set to TRUE meaning the stack will update its internal tokens via HAL calls when the
associated RAM values change.
Returns
TRUE if the device will update the persistent storage for tokens when values in RAM change. FALSE
otherwise.
6.8.3.20 EmberStatus emberApsCryptMessage ( boolean encrypt, EmberMessageBuffer buffer, int8u
apsHeaderEndIndex, EmberEUI64 remoteEui64 )
This function performs APS encryption/decryption of messages directly. Normally the stack handles all
APS encryption/decryption automatically and there is no need to call this function. If APS data is sent
or received via some other means (such as over interpan) then APS encryption/decryption must be done
manually. If decryption is performed then the Auxiliary security header and MIC will be removed from
the message. If encrypting, then the auxiliary header and MIC will be added to the message. This is only
available on SOC platforms.
Parameters
encrypt
buffer
apsHeaderEndIndex
a boolean indicating whether perform encryption (TRUE) or decryption (FALSE).
An EmberMessageBuffer containing the APS frame to decrypt or encrypt.
The index into the buffer where the APS header ends. If encryption is being performed
this should point to the APS payload, where an Auxiliary header will be inserted. If
decryption is being performed, this should point to the start of the Auxiliary header
frame.
remoteEui64 the EmberEUI64 of the remote device the message was received from (decryption) or
being sent to (encryption).
EmberZNet 4.7.2 API EM250
120-3016-000-4720
121
Returns
EMBER_SUCCESS if encryption/decryption was performed successfully. An appropriate EmberStatus code on failure.
6.8.3.21 EmberStatus emberGetMfgSecurityConfig ( EmberMfgSecurityStruct ∗ settings )
This function will retrieve the security configuration stored in manufacturing tokens. It is only available on
the 35x series. See emberSetMfgSecurityConfig() for more details.
Parameters
settings A pointer to the EmberMfgSecurityStruct variable that will contain the returned data.
Returns
EMBER_SUCCESS if the tokens were successfully read. EmberStatus error code otherwise.
6.8.3.22 EmberStatus emberSetMfgSecurityConfig ( int32u magicNumber, const
EmberMfgSecurityStruct ∗ settings )
This function will set the security configuration to be stored in manufacturing tokens. It is only available
on the 35x series. This API must be called with care. Once set, a manufacturing token CANNOT BE
UNSET without using the ISA3 tools and connecting the chip via JTAG. Additionally, a chip with read
protection enabled cannot have its configuration changed without a full chip erase. Thus this provides a
way to disallow access to the keys at runtime that cannot be undone.
To call this API the magic number must be passed in corresponding to EMBER_MFG_SECURITY_CONFIG_MAGIC_NUMBER. This prevents accidental calls to this function when emberGetMfgSecurityConfig() was actually intended.
This function will disable external access to the actual key data used for decryption/encryption outside
the stack. Attempts to call emberGetKey() or emberGetKeyTableEntry() will return the meta-data (e.g.
sequence number, associated EUI64, frame counters) but the key value may be modified, see below.
The stack always has access to the actual key data.
If the EmberKeySettings within the EmberMfgSecurityStruct are set to EMBER_KEY_PERMISSIONS_NONE then the key value with be set to zero when emberGetKey() or emberGetKeyTableEntry() is called.
If the EmberKeySettings within the EmberMfgSecurityStruct are set to EMBER_KEY_PERMISSIONS_HASHING_ALLOWED, then the AES-MMO hash of the key will replace the actual key data when calls to
emberGetKey() or emberGetKeyTableEntry() are made. If the EmberKeySettings within the EmberMfgSecurityStruct are set to EMBER_KEY_PERMISSIONS_READING_ALLOWED, then the actual key
data is returned. This is the default value of the token.
Parameters
magicNumber A 32-bit value that must correspond to EMBER_MFG_SECURITY_CONFIG_MAGIC_NUMBER, otherwise EMBER_INVALID_CALL will be returned.
settings The security settings that are intended to be set by the application and written to manufacturing token.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
122
Returns
EMBER_BAD_ARGUMENT if the passed magic number is invalid. EMBER_INVALID_CALL if
the chip does not support writing MFG tokens (i.e. em2xx) EMBER_SECURITY_CONFIGURATION_INVALID if there was an attempt to write an unerased manufacturing token (i.e. the token has
already been set).
EmberZNet 4.7.2 API EM250
120-3016-000-4720
123
6.9
Trust Center
Macros
• #define EMBER_FORM_TRUST_CENTER_NETWORK_BITMASK
• #define EMBER_FORM_DISTRIBUTED_TRUST_CENTER_NETWORk_BITMASK
Functions
• EmberStatus emberBroadcastNextNetworkKey (EmberKeyData ∗key)
• EmberStatus emberSendUnicastNetworkKeyUpdate (EmberNodeId targetShort, EmberEUI64 targetLong, EmberKeyData ∗newKey)
• EmberStatus emberBroadcastNetworkKeySwitch (void)
• EmberJoinDecision emberTrustCenterJoinHandler (EmberNodeId newNodeId, EmberEUI64 newNodeEui64, EmberDeviceUpdate status, EmberNodeId parentOfNewNode)
• EmberStatus emberBecomeTrustCenter (EmberKeyData ∗newNetworkKey)
• EmberStatus emberSendRemoveDevice (EmberNodeId destShort, EmberEUI64 destLong, EmberEUI64 deviceToRemoveLong)
Variables
• EmberLinkKeyRequestPolicy emberTrustCenterLinkKeyRequestPolicy
• EmberLinkKeyRequestPolicy emberAppLinkKeyRequestPolicy
6.9.1
Detailed Description
This file describes the routines used by the Trust Center to manage devices in the network. The Trust center
decides whether to use preconfigured keys or not and manages passing out keys to joining and rejoining
devices. The Trust Center also sends out new keys and decides when to start using them.
See trust-center.h for source code
6.9.2
Macro Definition Documentation
6.9.2.1
#define EMBER FORM TRUST CENTER NETWORK BITMASK
A Trust Center device configuration bitmask example. The Trust Center is expected to be setup with a
Network Key Preconfigured Link Key that is global throughout all devices on the Network. The decision
whether or not to send the key in-the-clear is NOT controlled through this bitmask. That is controlled via
the emberTrustCenterJoinHandler(...) function.
Definition at line 29 of file trust-center.h.
6.9.2.2
#define EMBER FORM DISTRIBUTED TRUST CENTER NETWORk BITMASK
A coordinator device configuration bitmask example. The coordinator is expected to be setup with a Network Key and a Preconfigured Link Key that is global throughout all devices on the Network. The decision
whether or not to send the key in-the-clear is decentralized, and each individual router can make this decision via the emberTrustCenterJoinHandler(...) function.
Definition at line 42 of file trust-center.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
124
6.9.3
Function Documentation
6.9.3.1 EmberStatus emberBroadcastNextNetworkKey ( EmberKeyData ∗ key )
This function broadcasts a new encryption key, but does not tell the nodes in the network to start using it.
To tell nodes to switch to the new key, use emberBroadcastNetworkKeySwitch(). This is only valid for the
Trust Center/Coordinator. It is not valid when operating in Distributed Trust Center mode.
It is up to the application to determine how quickly to send the Switch Key after sending the alternate
encryption key. The factors to consider are the polling rate of sleepy end devices, and the buffer size of
their parent nodes. Sending too quickly may cause a sleepy end device to miss the Alternate Encryption
Key and only get the Switch Key message, which means it will be unable to change to the new network
key.
Parameters
key A pointer to a 16-byte encryption key (EMBER_ENCRYPTION_KEY_SIZE). A NULL (or all zero key) may be passed in, which will cause the stack to randomly generate
a new key.
Returns
An EmberStatus value that indicates the success or failure of the command.
6.9.3.2 EmberStatus emberSendUnicastNetworkKeyUpdate ( EmberNodeId targetShort, EmberEUI64
targetLong, EmberKeyData ∗ newKey )
This function sends a unicast update of the network key to the target device. The APS command will be
encrypted using the device’s current APS link key. On success, the bit ::EMBER_KEY_UNICAST_NWK_KEY_UPDATE_SENT will be set in the link key table entry for the device. When a successful call is
made to emberBroadcastNetworkKeySwitch(), the bit will be cleared for all entries.
On the first call to this function the trust center’s local copy of the alternate NWK key will be updated with
the new value.
Both the short and long address of the device must be known ahead of time and passed in as parameters.
It is assumed that the application has already generated the new network key and will pass the same key
value on subsequent calls to send the key to different nodes in the network.
Parameters
targetStort the short node ID of the device to send a NWK key update to.
targetLong the EUI64 of the node to send a key update NWK key update to.
nwkKey a pointer to the new NWK key value.
Returns
an EmberStatus value that indicates the success or failure of the command.
6.9.3.3 EmberStatus emberBroadcastNetworkKeySwitch ( void )
This function broadcasts a switch key message to tell all nodes to change to the sequence number of the
previously sent Alternate Encryption Key.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
125
This function is only valid for the Trust Center/Coordinator, and will also cause the Trust Center/Coordinator
to change its Network Key. It is not valid when operating in Distributed Trust Center mode.
Returns
An EmberStatus value that indicates the success or failure of the command.
6.9.3.4 EmberJoinDecision emberTrustCenterJoinHandler ( EmberNodeId newNodeId, EmberEUI64
newNodeEui64, EmberDeviceUpdate status, EmberNodeId parentOfNewNode )
A callback that allows the application running on the Trust Center (which is the coordinator for ZigBee
networks) to control which nodes are allowed to join the network. If the node is allowed to join, the trust
center must decide how to send it the Network Key, encrypted or unencrypted.
A default handler is provided and its behavior is as follows. A status of ::EMBER_DEVICE_SECURED_REJOIN means that the device has the Network Key, no action is required from the Trust Center. A status
of EMBER_DEVICE_LEFT also requires no action. In both cases EMBER_NO_ACTION is returned.
When operating in a network with a Trust Center and there is a Global Link Key configured, EMBER_USE_PRECONFIGURED_KEY will be returned which means the Trust Center is using a pre-configured
Link Key. The Network Key will be sent to the joining node encrypted with the Link Key. If a Link Key
has not been set on the Trust Center, EMBER_DENY_JOIN is returned.
The ::EMBER_ASK_TRUST_CENTER decision has been deprecated. This function will not be called for
a router or end device when operating in a Network With a Trust Center.
If the device is a router in a network that is operating in a Distributed Trust Center Security mode, then the
handler will be called by the stack.
The default handler in a Distributed Trust Center Security mode network is as follows: If the router received
an encrypted Network Key when it joined, then a pre-configured Link key will be used to send the Network
Key Encrypted to the joining device (EMBER_USE_PRECONFIGURED_KEY). If the router received the
Network Key in the clear, then it will also send the key in the clear to the joining node (EMBER_SEND_KEY_IN_THE_CLEAR).
Parameters
newNodeId The node id of the device wishing to join.
newNodeEui64 The EUI64 of the device wishing to join.
status The EmberUpdateDeviceStatus indicating whether the device is joining/rejoining or
leaving.
parentOfNew- The node id of the parent of device wishing to join.
Node
Returns
EMBER_USE_PRECONFIGURED_KEY to allow the node to join without sending it the key. EMBER_SEND_KEY_IN_THE_CLEAR to allow the node to join and send it the key. EMBER_DENY_JOIN to reject the join attempt. value should not be returned if the local node is itself the trust
center).
6.9.3.5 EmberStatus emberBecomeTrustCenter ( EmberKeyData ∗ newNetworkKey )
This function causes a coordinator to become the Trust Center when it is operating in a network that is
not using one. It will send out an updated Network Key to all devices that will indicate a transition of
EmberZNet 4.7.2 API EM250
120-3016-000-4720
126
the network to now use a Trust Center. The Trust Center should also switch all devices to using this new
network key with a call to emberBroadcastNetworkKeySwitch().
Parameters
newNetwork- The key data for the Updated Network Key.
Key
Returns
An EmberStatus value that indicates the success or failure of the command.
6.9.3.6 EmberStatus emberSendRemoveDevice ( EmberNodeId destShort, EmberEUI64 destLong,
EmberEUI64 deviceToRemoveLong )
This sends an APS remove device command to the destination. If the destination is an end device then, this
must be sent to the parent of the end device. In that case the deviceToRemoveLong and the destLong will
be different values. Otherwise if a router is being asked to leave, then those parameters will be the same.
This command will be APS encrypted with the destination device’s link key, which means a link key must
be present.
Parameters
destShort The short node ID of the destination of the command.
destLong The EUI64 of the destination of the command.
deviceTo- The EUI64 of the target device being asked to leave.
RemoveLong
Returns
An EmberStatus value indicating success or failure of the operation.
6.9.4
Variable Documentation
6.9.4.1 EmberLinkKeyRequestPolicy emberTrustCenterLinkKeyRequestPolicy
This variable controls the policy that the Trust Center uses for determining whether to allow or deny requests for Trust Center link keys.
The following is a good set of guidelines for TC Link key requests:
• If preconfigured TC link keys are setup on devices, requests for the TC key should never be allowed
(EMBER_DENY_KEY_REQUESTS).
• If devices request link keys during joining (i.e. join in the clear and set EMBER_GET_LINK_KEY_WHEN_JOINING) then it is advisable to allow requesting keys from the TC for a short period of
time (e.g. the same amount of time "permit joining" is turned on). Afterwards requests for the TC
link key should be denied.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
127
6.9.4.2 EmberLinkKeyRequestPolicy emberAppLinkKeyRequestPolicy
This variable controls the policy that the Trust Center uses for determining whether to allow or deny requests for application link keys between device pairs. When a request is received and the policy is EMBER_ALLOW_KEY_REQUESTS, the TC will generate a random key and send a copy to both devices
encrypted with their individual link keys.
Generally application link key requests may always be allowed.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
128
6.10
Smart Energy Security
Functions
• EmberStatus emberGetCertificate (EmberCertificateData ∗result)
• EmberStatus emberGenerateCbkeKeys (void)
• EmberStatus emberCalculateSmacs (boolean amInitiator, EmberCertificateData ∗partnerCert, EmberPublicKeyData ∗partnerEphemeralPublicKey)
• EmberStatus emberClearTemporaryDataMaybeStoreLinkKey (boolean storeLinkKey)
• EmberStatus emberDsaSign (EmberMessageBuffer messageToSign)
• void emberGenerateCbkeKeysHandler (EmberStatus status, EmberPublicKeyData ∗ephemeralPublicKey)
• void emberCalculateSmacsHandler (EmberStatus status, EmberSmacData ∗initiatorSmac, EmberSmacData ∗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)
6.10.1
Detailed Description
This file describes functionality for Certificate Based Key Exchange (CBKE). This is used by Smart Energy
devices 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.10.2
Function Documentation
6.10.2.1 EmberStatus emberGetCertificate ( EmberCertificateData ∗ result )
Retrieves the implicit certificate stored in the MFG tokens of the device.
Parameters
result 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 token
contains uninitialized data.
6.10.2.2 EmberStatus emberGenerateCbkeKeys ( void )
This function begins the process of generating an ephemeral public/private ECC key pair.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
129
If no other ECC operation is going on, it will immediately return with EMBER_OPERATION_IN_PROGRESS. It will delay a period of time to let APS retries take place, but then it will shutdown the radio and
consume 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.10.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 Secured
Message Authentication Code (SMAC).
If no other ECC operation is going on, it will immediately return with EMBER_OPERATION_IN_PROGRESS. It will delay a period of time to let APS retries take place, but then it will shutdown the radio and
consume the CPU processing until SMACs calculations are complete. This may take up to 3.5 seconds.
The calculated SMACS are returned via emberCalculateSmacsHandler().
Parameters
amInitiator 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 implicit certificate.
partner- A pointer to an EmberPublicKeyData structure that contains the CBKE partner’s
Ephemeral- ephemeral public key.
PublicKey
Returns
EMBER_OPERATION_IN_PROGRESS if the stack has queued up the operation for execution.
6.10.2.4 EmberStatus emberClearTemporaryDataMaybeStoreLinkKey ( boolean storeLinkKey )
This function should be called when all CBKE operations are done. Any temporary data created during
calls to emberGenerateCbkeKeys() or emberCalculateSmacs() is wiped out. If the local device has validated that the partner device has generated the same SMACS as itself, it should set ’storeLinkKey’ to
TRUE. Otherwise it should pass in FALSE.
Parameters
storeLinkKey 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 is
TRUE, then this function returns the results of whether or not the link key was stored. EMBER_SUCCESS is returned when key was stored successfully.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
130
6.10.2.5 EmberStatus emberDsaSign ( EmberMessageBuffer messageToSign )
6.10.2.6
void emberGenerateCbkeKeysHandler ( EmberStatus status, EmberPublicKeyData ∗
ephemeralPublicKey )
6.10.2.7
void emberCalculateSmacsHandler ( EmberStatus status, EmberSmacData ∗ initiatorSmac,
EmberSmacData ∗ responderSmac )
6.10.2.8
void emberDsaSignHandler ( EmberStatus status, EmberMessageBuffer signedMessage )
6.10.2.9 EmberStatus emberSetPreinstalledCbkeData ( EmberPublicKeyData ∗ caPublic,
EmberCertificateData ∗ myCert, EmberPrivateKeyData ∗ myKey )
6.10.2.10 boolean emberGetStackCertificateEui64 ( EmberEUI64 certEui64 )
6.10.2.11 EmberStatus emberDsaVerify ( EmberMessageDigest ∗ digest, EmberCertificateData ∗
signerCertificate, EmberSignatureData ∗ receivedSig )
6.10.2.12
void emberDsaVerifyHandler ( EmberStatus status )
EmberZNet 4.7.2 API EM250
120-3016-000-4720
131
6.11
Binding Table
Functions
•
•
•
•
•
•
•
•
•
•
•
•
EmberStatus emberSetBinding (int8u index, EmberBindingTableEntry ∗value)
EmberStatus emberGetBinding (int8u index, EmberBindingTableEntry ∗result)
EmberStatus emberDeleteBinding (int8u index)
boolean emberBindingIsActive (int8u index)
EmberNodeId emberGetBindingRemoteNodeId (int8u index)
void emberSetBindingRemoteNodeId (int8u index, EmberNodeId id)
EmberStatus emberClearBindingTable (void)
EmberStatus emberRemoteSetBindingHandler (EmberBindingTableEntry ∗entry)
EmberStatus emberRemoteDeleteBindingHandler (int8u index)
int8u emberGetBindingIndex (void)
EmberStatus emberSetReplyBinding (int8u index, EmberBindingTableEntry ∗entry)
EmberStatus emberNoteSendersBinding (int8u index)
6.11.1
Detailed Description
EmberZNet binding table API. See binding-table.h for source code.
6.11.2
Function Documentation
6.11.2.1 EmberStatus emberSetBinding ( int8u index, EmberBindingTableEntry ∗ value )
Sets an entry in the binding table by copying the structure pointed to by value into the binding table.
Note
You do not need to reserve memory for value.
Parameters
index The index of a binding table entry.
value A pointer to a structure.
Returns
An EmberStatus value that indicates the success or failure of the command.
6.11.2.2 EmberStatus emberGetBinding ( int8u index, EmberBindingTableEntry ∗ result )
Copies a binding table entry to the structure that result points to.
Parameters
index The index of a binding table entry.
result A pointer to the location to which to copy the binding table entry.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
132
Returns
An EmberStatus value that indicates the success or failure of the command.
6.11.2.3 EmberStatus emberDeleteBinding ( int8u index )
Deletes a binding table entry.
Parameters
index The index of a binding table entry.
Returns
An EmberStatus value that indicates the success or failure of the command.
6.11.2.4 boolean emberBindingIsActive ( int8u index )
Indicates whether any messages are currently being sent using this binding table entry.
Note that this function does not indicate whether a binding is clear. To determine whether a binding is
clear, check the EmberBindingTableEntry structure that defines the binding. The type field should have the
value EMBER_UNUSED_BINDING.
Parameters
index The index of a binding table entry.
Returns
TRUE if the binding table entry is active, FALSE otherwise.
6.11.2.5 EmberNodeId emberGetBindingRemoteNodeId ( int8u index )
Returns the node ID for the binding’s destination, if the ID is known.
If a message is sent using the binding and the destination’s ID is not known, the stack will discover the
ID by broadcasting a ZDO address request. The application can avoid the need for this discovery be calling emberNoteSendersBinding() whenever a message arrives from the binding’s destination, or by calling
emberSetBindingRemoteNodeId() when it knows the correct ID via some other means, such as having
saved it in nonvolatile memory.
The destination’s node ID is forgotten when the binding is changed, when the local node reboots or, much
more rarely, when the destination node changes its ID in response to an ID conflict.
Parameters
index The index of a binding table entry.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
133
Returns
The short ID of the destination node or EMBER_NULL_NODE_ID if no destination is known.
6.11.2.6
void emberSetBindingRemoteNodeId ( int8u index, EmberNodeId id )
Set the node ID for the binding’s destination. See emberGetBindingRemoteNodeId() for a description.
Parameters
index The index of a binding table entry.
id The ID of the binding’s destination.
6.11.2.7 EmberStatus emberClearBindingTable ( void )
Deletes all binding table entries.
Returns
An EmberStatus value that indicates the success or failure of the command.
6.11.2.8 EmberStatus emberRemoteSetBindingHandler ( EmberBindingTableEntry ∗ entry )
A callback invoked when a remote node requests that a binding be added to the local binding table (via the
ZigBee Device Object at endpoint 0).
The application is free to add the binding to the binding table, ignore the request, or take some other action.
It is recommended that nonvolatile bindings be used for remote provisioning applications.
The binding’s type defaults to EMBER_UNICAST_BINDING. The application should set the type as
appropriate for the binding’s local endpoint and cluster ID.
If the application includes emberRemoteSetBindingHandler(), it must define EMBER_APPLICATION_HAS_REMOTE_BINDING_HANDLER in its CONFIGURATION_HEADER and also include emberRemoteDeleteBindingHandler().
Parameters
entry A pointer to a new binding table entry.
Returns
EMBER_SUCCESS if the binding was added to the table and any other status if not.
6.11.2.9 EmberStatus emberRemoteDeleteBindingHandler ( int8u index )
A callback invoked when a remote node requests that a binding be removed from the local binding table
(via the ZigBee Device Object at endpoint 0).
The application is free to remove the binding from the binding table, ignore the request, or take some other
action.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
134
If the application includes emberRemoteDeleteBindingHandler(), it must define EMBER_APPLICATION_HAS_REMOTE_BINDING_HANDLER in its CONFIGURATION_HEADER and also include emberRemoteSetBindingHandler().
Parameters
index The index of the binding entry to be removed.
Returns
EMBER_SUCCESS if the binding was removed from the table and any other status if not.
6.11.2.10 int8u emberGetBindingIndex ( void )
Returns a binding index that matches the current incoming message, if known.
A binding matches the incoming message if:
• The binding’s source endpoint is the same as the message’s destination endpoint.
• The binding’s destination endpoint is the same as the message’s source endpoint.
• The source of the message has been previously identified as the the binding’s remote node by a
successful address discovery or by the application via a call to either emberSetReplyBinding() or
emberNoteSendersBinding().
Note
This function can be called only from within emberIncomingMessageHandler().
Returns
The index of a binding that matches the current incoming message or 0xFF if there is no matching
binding.
6.11.2.11 EmberStatus emberSetReplyBinding ( int8u index, EmberBindingTableEntry ∗ entry )
Creates a binding table entry for the sender of a message, which can be used to send messages to that
sender.
This function is identical to emberSetBinding() except that calling it tells the stack that this binding corresponds to the sender of the current message. The stack uses this information to associate the sender’s
routing info with the binding table entry.
Note
This function may only be called from within emberIncomingMessageHandler().
Parameters
index The index of the binding to set.
entry A pointer to data for the binding.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
135
Returns
An EmberStatus value that indicates the success or failure of the command.
6.11.2.12 EmberStatus emberNoteSendersBinding ( int8u index )
Updates the routing information associated with a binding table entry for the sender of a message.
This function should be used in place of emberSetReplyBinding() when a message arrives from a remote
endpoint for which a binding already exists.
Parameters
index The index of the binding to update.
Returns
An EmberStatus value that indicates the success or failure of the command.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
136
6.12
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
EmberZNet 4.7.2 API EM250
120-3016-000-4720
137
6.12.1
Detailed Description
All configurations have defaults, therefore many applications may not need to do anything special. However, 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 packet
buffers 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 the
appropriate macro and providing the corresponding callback function. For example, an application with
custom debug channel input must implement emberDebugHandler() to process it. Along with the
function definition, the application should provide the following line in its CONFIGURATION_HEADER:
#define EMBER_APPLICATION_HAS_DEBUG_HANDLER
See ember-configuration-defaults.h for source code.
6.12.2
Macro Definition Documentation
6.12.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.12.2.2
#define EMBER API MINOR VERSION
The minor version number of the Ember stack release that the application is built against.
Definition at line 65 of file ember-configuration-defaults.h.
6.12.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
Definition at line 81 of file ember-configuration-defaults.h.
6.12.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 is
6, for profile 1 the value is 14.
Definition at line 98 of file ember-configuration-defaults.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
138
6.12.2.5
#define EMBER SECURITY LEVEL
The security level used for security at the MAC and network layers. The supported values are 0 (no
security) and 5 (payload is encrypted and a four-byte MIC is used for authentication).
Definition at line 123 of file ember-configuration-defaults.h.
6.12.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_MAX_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 ignored and the default value used instead.
Definition at line 152 of file ember-configuration-defaults.h.
6.12.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 Link
Key. 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. The
rest 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 Link
Key is stored separately from this table.
Definition at line 169 of file ember-configuration-defaults.h.
6.12.2.8
#define EMBER CERTIFICATE TABLE SIZE
The number of entries for the field upgradeable certificate table. Normally certificates (such as SE certs) are
stored in the runtime-unmodifiable MFG area. However for those devices wishing to add new certificates
after manufacturing, they will have to use the normal token space. This defines the size of that table. For
most devices 0 is appropriate since there is no need to change certificates in the field. For those wishing
to field upgrade devices with new certificates, 1 is the correct size. Anything more is simply wasting
SimEEPROM.
Definition at line 182 of file ember-configuration-defaults.h.
6.12.2.9
#define EMBER MAX DEPTH
The maximum depth of the tree in ZigBee 2006. This implicitly determines the maximum diameter of the
network (EMBER_MAX_HOPS) if that value is not overridden.
Definition at line 195 of file ember-configuration-defaults.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
139
6.12.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 the
default is two times the max depth (EMBER_MAX_DEPTH).
Definition at line 208 of file ember-configuration-defaults.h.
6.12.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).
Definition at line 218 of file ember-configuration-defaults.h.
6.12.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 kept
track of in the child table, not the neighbor table. The default is 16. Setting this value lower than 8 is not
recommended.
Each neighbor table entry consumes 18 bytes of RAM (6 for the table itself and 12 bytes of security data).
Definition at line 232 of file ember-configuration-defaults.h.
6.12.2.13
#define EMBER NEIGHBOR TABLE SIZE
Definition at line 234 of file ember-configuration-defaults.h.
6.12.2.14
#define EMBER INDIRECT TRANSMISSION TIMEOUT
The maximum amount of time (in milliseconds) that the MAC will hold a message for indirect transmission
to a child.
The default is 3000 milliseconds (3 sec). The maximum value is 30 seconds (30000 milliseconds).larger
values will cause rollover confusion.
Definition at line 244 of file ember-configuration-defaults.h.
6.12.2.15
#define EMBER MAX INDIRECT TRANSMISSION TIMEOUT
Definition at line 246 of file ember-configuration-defaults.h.
6.12.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=TRUE (0xFFFD). However setting this to true can change locally generated multicasts to be sent to the
sleepy broadcast address (0xFFFF). Changing the default is NOT ZigBee Pro compliant and may not be
interoperable.
Definition at line 259 of file ember-configuration-defaults.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
140
6.12.2.17
#define EMBER END DEVICE POLL TIMEOUT
The maximum amount of time, in units determined by EMBER_END_DEVICE_POLL_TIMEOUT_SHIFT, that an EMBER_END_DEVICE or EMBER_SLEEPY_END_DEVICE can wait between polls. The
timeout 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 device
from its tables. Note: there is a separate EMBER_MOBILE_NODE_POLL_TIMEOUT for mobile end
devices.
Using the default values of both EMBER_END_DEVICE_POLL_TIMEOUT and EMBER_END_DEVICE_POLL_TIMEOUT_SHIFT results in a timeout of 320 seconds, or just over five minutes. The maximum value for EMBER_END_DEVICE_POLL_TIMEOUT is 255.
Definition at line 278 of file ember-configuration-defaults.h.
6.12.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_TIMEOUT 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 seconds, or approximately one minute. The maximum value for EMBER_END_DEVICE_POLL_TIMEOUT_SHIFT is 14.
Definition at line 289 of file ember-configuration-defaults.h.
6.12.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 poll
is heard within this timeout, then the parent removes the mobile node from its tables. The default is 20
quarter seconds (5 seconds). The maximum is 255 quarter seconds.
Definition at line 299 of file ember-configuration-defaults.h.
6.12.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 buffers
for the payload. The default is 10 messages.
Each APS retried message consumes 6 bytes of RAM, in addition to two or more packet buffers.
Definition at line 315 of file ember-configuration-defaults.h.
6.12.2.21
#define EMBER BINDING TABLE SIZE
The maximum number of bindings supported by the stack. The default is 0 bindings. Each binding consumes 2 bytes of RAM.
Definition at line 321 of file ember-configuration-defaults.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
141
6.12.2.22
#define EMBER ADDRESS TABLE SIZE
The maximum number of EUI64<->network address associations that the stack can maintain. The default
value is 8.
Address table entries are 10 bytes in size.
Definition at line 329 of file ember-configuration-defaults.h.
6.12.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.
Definition at line 339 of file ember-configuration-defaults.h.
6.12.2.24
#define EMBER ROUTE TABLE SIZE
The maximum number of destinations to which a node can route messages. This include both messages
originating at this node and those relayed for others. The default value is 16.
Route table entries are 6 bytes in size.
Definition at line 352 of file ember-configuration-defaults.h.
6.12.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.
Definition at line 368 of file ember-configuration-defaults.h.
6.12.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.
Definition at line 381 of file ember-configuration-defaults.h.
6.12.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 0xFF
is reserved. The default value is 32.
Source route table entries are 4 bytes in size.
Definition at line 391 of file ember-configuration-defaults.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
142
6.12.2.28
#define EMBER DEFAULT BROADCAST TABLE SIZE
The maximum number broadcasts during a single broadcast timeout period. The minimum and default
value is 15 and can only be changed only on compatible Ember stacks. Be very careful when changing
the 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 can
overwhelm all its neighbors with more broadcasts than they can support. In general, this value should be
left alone.
Broadcast table entries are 5 bytes in size.
Definition at line 411 of file ember-configuration-defaults.h.
6.12.2.29
#define EMBER BROADCAST TABLE SIZE
Definition at line 414 of file ember-configuration-defaults.h.
6.12.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 to
which the output is sent can be changed by defining EMBER_ASSERT_SERIAL_PORT as the desired
port.
The default is to have assert output on and sent to serial port 1.
Definition at line 432 of file ember-configuration-defaults.h.
6.12.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 this
limit.
EMBER_MAXIMUM_ALARM_DATA_SIZE is defined to be 16.
The maximum payload on any particular device is determined by the configuration parameters, EMBER_BROADCAST_ALARM_DATA_SIZE and EMBER_UNICAST_ALARM_DATA_SIZE, neither of
which may be greater than ::MBER_MAXIMUM_ALARM_DATA_SIZE.
Definition at line 448 of file ember-configuration-defaults.h.
6.12.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 table
entry. 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. Broadcast
alarms whose length is larger will not be buffered or forwarded to sleepy end device children. This paEmberZNet 4.7.2 API EM250
120-3016-000-4720
143
rameter must be in the inclusive range 0 ... EMBER_MAXIMUM_ALARM_DATA_SIZE. The default
value is 0.
Definition at line 468 of file ember-configuration-defaults.h.
6.12.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. This
parameter must be in the inclusive range 0 ... EMBER_MAXIMUM_ALARM_DATA_SIZE. The default
value is 0.
Definition at line 482 of file ember-configuration-defaults.h.
6.12.2.34
#define EMBER FRAGMENT DELAY MS
The time the stack will wait (in milliseconds) between sending blocks of a fragmented message. The
default value is 0.
Definition at line 491 of file ember-configuration-defaults.h.
6.12.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 to
be 8.
Definition at line 497 of file ember-configuration-defaults.h.
6.12.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 is
EMBER_FRAGMENT_MAX_WINDOW_SIZE. The default value is 1.
Definition at line 504 of file ember-configuration-defaults.h.
6.12.2.37
#define EMBER BINDING TABLE TOKEN SIZE
Definition at line 510 of file ember-configuration-defaults.h.
6.12.2.38
#define EMBER CHILD TABLE TOKEN SIZE
Definition at line 513 of file ember-configuration-defaults.h.
6.12.2.39
#define EMBER KEY TABLE TOKEN SIZE
Definition at line 516 of file ember-configuration-defaults.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
144
6.12.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 Trust
Center this is the time it will hold the first request and wait for a second matching request. If both arrive
within this time period, the Trust Center will reply to both with the new key. If both requests are not
received then the Trust Center will discard the request. The time is in minutes. The maximum time is 10
minutes. A value of 0 minutes indicates that the Trust Center will not buffer the request but instead respond
immediately. Only 1 outstanding request is supported at a time.
The Zigbee Pro Compliant value is 0.
Definition at line 532 of file ember-configuration-defaults.h.
6.12.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 default
value is 60.
Definition at line 541 of file ember-configuration-defaults.h.
6.12.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 minute
to trigger a PAN id change. Very rarely, a corrupt beacon can pass the CRC check and trigger a false
PAN id conflict. This is more likely to happen in very large dense networks. Setting this value to 2 or 3
dramatically reduces the chances of a spurious PAN id change. The maximum value is 63. The default
value is 1.
Definition at line 553 of file ember-configuration-defaults.h.
6.12.2.43
#define EMBER TASK COUNT
The number of event tasks that can be tracked for the purpose of processor idling. The EmberZNet stack
requires 1, an application and associated libraries may use additional tasks, though typically no more than
3 are needed for most applications.
Definition at line 562 of file ember-configuration-defaults.h.
6.12.2.44
#define EMBER SUPPORTED NETWORKS
The number of networks supported by the stack.
Definition at line 571 of file ember-configuration-defaults.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
145
6.13
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 EM250
120-3016-000-4720
146
•
•
•
•
#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 EM250
120-3016-000-4720
147
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 EM250
120-3016-000-4720
148
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)
6.13.1
Detailed Description
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 turn
included by ember.h.
6.13.2
Macro Definition Documentation
6.13.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 EM250
120-3016-000-4720
149
Parameters
symbol 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.13.2.2
#define EMBER SUCCESS( x00 )
The generic "no error" message.
Definition at line 43 of file error-def.h.
6.13.2.3
#define EMBER ERR FATAL( x01 )
The generic "fatal error" message.
Definition at line 53 of file error-def.h.
6.13.2.4
#define EMBER BAD ARGUMENT( x02 )
An invalid value was passed as an argument to a function.
Definition at line 63 of file error-def.h.
6.13.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).
Definition at line 74 of file error-def.h.
6.13.2.6
#define EMBER INCOMPATIBLE STATIC MEMORY DEFINITIONS( x05 )
The static memory definitions in ember-static-memory.h are incompatible with this stack version.
Definition at line 85 of file error-def.h.
6.13.2.7
#define EMBER EEPROM MFG VERSION MISMATCH( x06 )
The manufacturing token format in non-volatile memory is different than what the stack expects (returned
at initialization).
Definition at line 96 of file error-def.h.
6.13.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 initialization).
Definition at line 107 of file error-def.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
150
6.13.2.9
#define EMBER NO BUFFERS( x18 )
There are no more buffers.
Definition at line 124 of file error-def.h.
6.13.2.10
#define EMBER SERIAL INVALID BAUD RATE( x20 )
Specified an invalid baud rate.
Definition at line 140 of file error-def.h.
6.13.2.11
#define EMBER SERIAL INVALID PORT( x21 )
Specified an invalid serial port.
Definition at line 150 of file error-def.h.
6.13.2.12
#define EMBER SERIAL TX OVERFLOW( x22 )
Tried to send too much data.
Definition at line 160 of file error-def.h.
6.13.2.13
#define EMBER SERIAL RX OVERFLOW( x23 )
There was not enough space to store a received character and the character was dropped.
Definition at line 171 of file error-def.h.
6.13.2.14
#define EMBER SERIAL RX FRAME ERROR( x24 )
Detected a UART framing error.
Definition at line 181 of file error-def.h.
6.13.2.15
#define EMBER SERIAL RX PARITY ERROR( x25 )
Detected a UART parity error.
Definition at line 191 of file error-def.h.
6.13.2.16
#define EMBER SERIAL RX EMPTY( x26 )
There is no received data to process.
Definition at line 201 of file error-def.h.
6.13.2.17
#define EMBER SERIAL RX OVERRUN ERROR( x27 )
The receive interrupt was not handled in time, and a character was dropped.
Definition at line 212 of file error-def.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
151
6.13.2.18
#define EMBER MAC TRANSMIT QUEUE FULL( x39 )
The MAC transmit queue is full.
Definition at line 228 of file error-def.h.
6.13.2.19
#define EMBER MAC UNKNOWN HEADER TYPE( x3A )
MAC header FCF error on receive.
Definition at line 239 of file error-def.h.
6.13.2.20
#define EMBER MAC ACK HEADER TYPE( x3B )
MAC ACK header received.
Definition at line 248 of file error-def.h.
6.13.2.21
#define EMBER MAC SCANNING( x3D )
The MAC can’t complete this task because it is scanning.
Definition at line 259 of file error-def.h.
6.13.2.22
#define EMBER MAC NO DATA( x31 )
No pending data exists for device doing a data poll.
Definition at line 269 of file error-def.h.
6.13.2.23
#define EMBER MAC JOINED NETWORK( x32 )
Attempt to scan when we are joined to a network.
Definition at line 279 of file error-def.h.
6.13.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.
Definition at line 290 of file error-def.h.
6.13.2.25
#define EMBER MAC INCORRECT SCAN TYPE( x34 )
emberStartScan was called with an incorrect scan type.
Definition at line 300 of file error-def.h.
6.13.2.26
#define EMBER MAC INVALID CHANNEL MASK( x35 )
emberStartScan was called with an invalid channel mask.
Definition at line 310 of file error-def.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
152
6.13.2.27
#define EMBER MAC COMMAND TRANSMIT FAILURE( x36 )
Failed to scan current channel because we were unable to transmit the relevent MAC command.
Definition at line 321 of file error-def.h.
6.13.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.
Definition at line 332 of file error-def.h.
6.13.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.
Definition at line 343 of file error-def.h.
6.13.2.30
#define EMBER MAC INDIRECT TIMEOUT( x42 )
Indirect data message timed out before polled.
Definition at line 353 of file error-def.h.
6.13.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. The
GREEN 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.
Definition at line 376 of file error-def.h.
6.13.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. The
RED 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 the
function halSimEepromErasePage() as soon as possible to erase a page.
Definition at line 392 of file error-def.h.
6.13.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 been
lost. 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 to set
a token.
Definition at line 407 of file error-def.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
153
6.13.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 with
the token information compiled into the code image being run.
Definition at line 425 of file error-def.h.
6.13.2.35
#define EMBER SIM EEPROM INIT 2 FAILED( x49 )
Attempt 2 to initialize the Simulated EEPROM has failed.
This failure means Attempt 1 failed, and the token system failed to properly reload default tokens and reset
the Simulated EEPROM.
Definition at line 438 of file error-def.h.
6.13.2.36
#define EMBER SIM EEPROM INIT 3 FAILED( x4A )
Attempt 3 to initialize the Simulated EEPROM has failed.
This failure means one or both of the tokens ::TOKEN_MFG_NVDATA_VERSION or ::TOKEN_STACK_NVDATA_VERSION were incorrect and the token system failed to properly reload default tokens and
reset the Simulated EEPROM.
Definition at line 452 of file error-def.h.
6.13.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 fully
functional 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 as
monitoring frequency.
Note
Common situations will trigger an expected repair, such as using an erased chip or changing token
definitions.
Definition at line 470 of file error-def.h.
6.13.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 be
programmed is already programmed. The flash write routines were asked to flip a bit from a 0 to 1, which
is physically impossible and the write was therefore inhibited. The data in the flash cannot be trusted after
this error.
Definition at line 491 of file error-def.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
154
6.13.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. The
data in the flash cannot be trusted after this error, and it is possible this error is the result of exceeding the
life cycles of the flash.
Definition at line 504 of file error-def.h.
6.13.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 an
invalid address. The data in the flash cannot be trusted after this error, and it is possible this error is
the result of exceeding the life cycles of the flash.
Definition at line 517 of file error-def.h.
6.13.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 the
flash cannot be trusted after this error, and it is possible this error is the result of exceeding the life
cycles of the flash.
Definition at line 530 of file error-def.h.
6.13.2.42
#define EMBER ERR BOOTLOADER TRAP TABLE BAD( x58 )
The bootloader received an invalid message (failed attempt to go into bootloader).
Definition at line 549 of file error-def.h.
6.13.2.43
#define EMBER ERR BOOTLOADER TRAP UNKNOWN( x59 )
Bootloader received an invalid message (failed attempt to go into bootloader).
Definition at line 560 of file error-def.h.
6.13.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 image
exceeded memory bounds.
Definition at line 571 of file error-def.h.
6.13.2.45
#define EMBER DELIVERY FAILED( x66 )
The APS layer attempted to send or deliver a message, but it failed.
Definition at line 589 of file error-def.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
155
6.13.2.46
#define EMBER BINDING INDEX OUT OF RANGE( x69 )
This binding index is out of range for the current binding table.
Definition at line 599 of file error-def.h.
6.13.2.47
#define EMBER ADDRESS TABLE INDEX OUT OF RANGE( x6A )
This address table index is out of range for the current address table.
Definition at line 610 of file error-def.h.
6.13.2.48
#define EMBER INVALID BINDING INDEX( x6C )
An invalid binding table index was given to a function.
Definition at line 620 of file error-def.h.
6.13.2.49
#define EMBER INVALID CALL( x70 )
The API call is not allowed given the current state of the stack.
Definition at line 631 of file error-def.h.
6.13.2.50
#define EMBER COST NOT KNOWN( x71 )
The link cost to a node is not known.
Definition at line 641 of file error-def.h.
6.13.2.51
#define EMBER MAX MESSAGE LIMIT REACHED( x72 )
The maximum number of in-flight messages (i.e. EMBER_APS_UNICAST_MESSAGE_COUNT) has
been reached.
Definition at line 652 of file error-def.h.
6.13.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.
Definition at line 662 of file error-def.h.
6.13.2.53
#define EMBER BINDING IS ACTIVE( x75 )
The application is trying to delete or overwrite a binding that is in use.
Definition at line 673 of file error-def.h.
6.13.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 EM250
120-3016-000-4720
156
Definition at line 683 of file error-def.h.
6.13.2.55
#define EMBER ADC CONVERSION DONE( x80 )
Conversion is complete.
Definition at line 700 of file error-def.h.
6.13.2.56
#define EMBER ADC CONVERSION BUSY( x81 )
Conversion cannot be done because a request is being processed.
Definition at line 711 of file error-def.h.
6.13.2.57
#define EMBER ADC CONVERSION DEFERRED( x82 )
Conversion is deferred until the current request has been processed.
Definition at line 722 of file error-def.h.
6.13.2.58
#define EMBER ADC NO CONVERSION PENDING( x84 )
No results are pending.
Definition at line 732 of file error-def.h.
6.13.2.59
#define EMBER SLEEP INTERRUPTED( x85 )
Sleeping (for a duration) has been abnormally interrupted and exited prematurely.
Definition at line 743 of file error-def.h.
6.13.2.60
#define EMBER PHY TX UNDERFLOW( x88 )
The transmit hardware buffer underflowed.
Definition at line 760 of file error-def.h.
6.13.2.61
#define EMBER PHY TX INCOMPLETE( x89 )
The transmit hardware did not finish transmitting a packet.
Definition at line 770 of file error-def.h.
6.13.2.62
#define EMBER PHY INVALID CHANNEL( x8A )
An unsupported channel setting was specified.
Definition at line 780 of file error-def.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
157
6.13.2.63
#define EMBER PHY INVALID POWER( x8B )
An unsupported power setting was specified.
Definition at line 790 of file error-def.h.
6.13.2.64
#define EMBER PHY TX BUSY( x8C )
The requested operation cannot be completed because the radio is currently busy, either transmitting a
packet or performing calibration.
Definition at line 801 of file error-def.h.
6.13.2.65
#define EMBER PHY TX CCA FAIL( x8D )
The transmit attempt failed because all CCA attempts indicated that the channel was busy.
Definition at line 812 of file error-def.h.
6.13.2.66
#define EMBER PHY OSCILLATOR CHECK FAILED( x8E )
The software installed on the hardware doesn’t recognize the hardware radio type.
Definition at line 823 of file error-def.h.
6.13.2.67
#define EMBER PHY ACK RECEIVED( x8F )
The expected ACK was received after the last transmission.
Definition at line 833 of file error-def.h.
6.13.2.68
#define EMBER NETWORK UP( x90 )
The stack software has completed initialization and is ready to send and receive packets over the air.
Definition at line 852 of file error-def.h.
6.13.2.69
#define EMBER NETWORK DOWN( x91 )
The network is not operating.
Definition at line 862 of file error-def.h.
6.13.2.70
#define EMBER JOIN FAILED( x94 )
An attempt to join a network failed.
Definition at line 872 of file error-def.h.
6.13.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 EM250
120-3016-000-4720
158
Definition at line 883 of file error-def.h.
6.13.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 devices
joining ZigBee Pro networks (or vice versa) must join as End Devices, not Routers.
Definition at line 895 of file error-def.h.
6.13.2.73
#define EMBER NODE ID CHANGED( x99 )
The local node ID has changed. The application can obtain the new node ID by calling emberGetNodeId().
Definition at line 905 of file error-def.h.
6.13.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().
Definition at line 915 of file error-def.h.
6.13.2.75
#define EMBER CHANNEL CHANGED( x9B )
The channel has changed.
Definition at line 923 of file error-def.h.
6.13.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 joining
node.
Definition at line 932 of file error-def.h.
6.13.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 back
a Network Key in-the-clear when an encrypted Network Key was required. (EMBER_REQUIRE_ENCRYPTED_KEY).
Definition at line 943 of file error-def.h.
6.13.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.
Definition at line 953 of file error-def.h.
6.13.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_WHEN_JOINING) but no response was ever received.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
159
Definition at line 963 of file error-def.h.
6.13.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 sent
encrypted data using a pre-configured key.
Definition at line 974 of file error-def.h.
6.13.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.
Definition at line 990 of file error-def.h.
6.13.2.82
#define EMBER INVALID SECURITY LEVEL( x95 )
The chosen security level (the value of EMBER_SECURITY_LEVEL) is not supported by the stack.
Definition at line 1000 of file error-def.h.
6.13.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 address (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.
Definition at line 1014 of file error-def.h.
6.13.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 key
first.
Definition at line 1023 of file error-def.h.
6.13.2.85
#define EMBER SECURITY STATE NOT SET( xA8 )
There was an attempt to form or join a network with security without calling emberSetInitialSecurityState()
first.
Definition at line 1032 of file error-def.h.
6.13.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 set
using either the local device’s or Trust Center’s IEEE address. Or an entry already exists in the table with
the same IEEE address. An Address of all zeros or all F’s are not valid addresses in 802.15.4.
Definition at line 1045 of file error-def.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
160
6.13.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.
Definition at line 1054 of file error-def.h.
6.13.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. The
Trust Center must wait at least a period equal to the broadcast timeout so that all routers have a chance to
receive the broadcast of the new network key.
Definition at line 1065 of file error-def.h.
6.13.2.89
#define EMBER SIGNATURE VERIFY FAILURE( xB9 )
The received signature corresponding to the message that was passed to the CBKE Library failed verification, it is not valid.
Definition at line 1074 of file error-def.h.
6.13.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 for
use in APS data messages. APS Commands (sent by the stack) are allowed. To use it for encryption of
APS data messages it must be authorized using a key agreement protocol (such as CBKE).
Definition at line 1086 of file error-def.h.
6.13.2.91
#define EMBER SECURITY DATA INVALID( xBD )
The security data provided was not valid, or an integrity check failed.
Definition at line 1096 of file error-def.h.
6.13.2.92
#define EMBER NOT JOINED( x93 )
The node has not joined a network.
Definition at line 1114 of file error-def.h.
6.13.2.93
#define EMBER NETWORK BUSY( xA1 )
A message cannot be sent because the network is currently overloaded.
Definition at line 1124 of file error-def.h.
6.13.2.94
#define EMBER INVALID ENDPOINT( xA3 )
The application tried to send a message using an endpoint that it has not defined.
Definition at line 1135 of file error-def.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
161
6.13.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 been
reported to the application.
Definition at line 1146 of file error-def.h.
6.13.2.96
#define EMBER INSUFFICIENT RANDOM DATA( xA5 )
An attempt to generate random bytes failed because of insufficient random data from the radio.
Definition at line 1156 of file error-def.h.
6.13.2.97
#define EMBER SOURCE ROUTE FAILURE( xA9 )
A ZigBee route error command frame was received indicating that a source routed message from this node
failed en route.
Definition at line 1166 of file error-def.h.
6.13.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 a
many-to-one route failed en route. The route error frame was delivered by an ad-hoc search for a functioning route.
Definition at line 1177 of file error-def.h.
6.13.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 chip
it is running on. The software (stack) on the chip must be replaced with software that is compatible with
the chip.
Definition at line 1198 of file error-def.h.
6.13.2.100
#define EMBER INDEX OUT OF RANGE( xB1 )
An index was passed into the function that was larger than the valid range.
Definition at line 1209 of file error-def.h.
6.13.2.101
#define EMBER TABLE FULL( xB4 )
There are no empty entries left in the table.
Definition at line 1218 of file error-def.h.
6.13.2.102
#define EMBER TABLE ENTRY ERASED( xB6 )
The requested table entry has been erased and contains no valid data.
Definition at line 1228 of file error-def.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
162
6.13.2.103
#define EMBER LIBRARY NOT PRESENT( xB5 )
The requested function cannot be executed because the library that contains the necessary functionality is
not present.
Definition at line 1238 of file error-def.h.
6.13.2.104
#define EMBER OPERATION IN PROGRESS( xBA )
The stack accepted the command and is currently processing the request. The results will be returned via
an appropriate handler.
Definition at line 1248 of file error-def.h.
6.13.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 other
authentication to verify the new TC is authorized to take over.
Definition at line 1259 of file error-def.h.
6.13.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 the
network stack or HAL.
Definition at line 1277 of file error-def.h.
6.13.2.107
#define EMBER APPLICATION ERROR 1( xF1 )
This error is reserved for customer application use. This will never be returned from any portion of the
network stack or HAL.
Definition at line 1278 of file error-def.h.
6.13.2.108
#define EMBER APPLICATION ERROR 2( xF2 )
This error is reserved for customer application use. This will never be returned from any portion of the
network stack or HAL.
Definition at line 1279 of file error-def.h.
6.13.2.109
#define EMBER APPLICATION ERROR 3( xF3 )
This error is reserved for customer application use. This will never be returned from any portion of the
network stack or HAL.
Definition at line 1280 of file error-def.h.
6.13.2.110
#define EMBER APPLICATION ERROR 4( xF4 )
This error is reserved for customer application use. This will never be returned from any portion of the
network stack or HAL.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
163
Definition at line 1281 of file error-def.h.
6.13.2.111
#define EMBER APPLICATION ERROR 5( xF5 )
This error is reserved for customer application use. This will never be returned from any portion of the
network stack or HAL.
Definition at line 1282 of file error-def.h.
6.13.2.112
#define EMBER APPLICATION ERROR 6( xF6 )
This error is reserved for customer application use. This will never be returned from any portion of the
network stack or HAL.
Definition at line 1283 of file error-def.h.
6.13.2.113
#define EMBER APPLICATION ERROR 7( xF7 )
This error is reserved for customer application use. This will never be returned from any portion of the
network stack or HAL.
Definition at line 1284 of file error-def.h.
6.13.2.114
#define EMBER APPLICATION ERROR 8( xF8 )
This error is reserved for customer application use. This will never be returned from any portion of the
network stack or HAL.
Definition at line 1285 of file error-def.h.
6.13.2.115
#define EMBER APPLICATION ERROR 9( xF9 )
This error is reserved for customer application use. This will never be returned from any portion of the
network stack or HAL.
Definition at line 1286 of file error-def.h.
6.13.2.116
#define EMBER APPLICATION ERROR 10( xFA )
This error is reserved for customer application use. This will never be returned from any portion of the
network stack or HAL.
Definition at line 1287 of file error-def.h.
6.13.2.117
#define EMBER APPLICATION ERROR 11( xFB )
This error is reserved for customer application use. This will never be returned from any portion of the
network stack or HAL.
Definition at line 1288 of file error-def.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
164
6.13.2.118
#define EMBER APPLICATION ERROR 12( xFC )
This error is reserved for customer application use. This will never be returned from any portion of the
network stack or HAL.
Definition at line 1289 of file error-def.h.
#define EMBER APPLICATION ERROR 13( xFD )
6.13.2.119
This error is reserved for customer application use. This will never be returned from any portion of the
network stack or HAL.
Definition at line 1290 of file error-def.h.
#define EMBER APPLICATION ERROR 14( xFE )
6.13.2.120
This error is reserved for customer application use. This will never be returned from any portion of the
network stack or HAL.
Definition at line 1291 of file error-def.h.
#define EMBER APPLICATION ERROR 15( xFF )
6.13.2.121
This error is reserved for customer application use. This will never be returned from any portion of the
network stack or HAL.
Definition at line 1292 of file error-def.h.
6.13.3
Enumeration Type Documentation
6.13.3.1
anonymous enum
Enumerator:
EMBER_ERROR_CODE_COUNT Gets defined as a count of all the possible return codes in the
EmberZNet stack API.
Definition at line 39 of file error.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
165
6.14
Stack Tokens
Macros
• #define TOKEN_NEXT_ADDRESS(region, address)
• #define CURRENT_STACK_TOKEN_VERSION
Convenience Macros
The following convenience macros are used to simplify the definition process for commonly specified parameters to the basic TOKEN_DEF macro. Please see hal/micro/token.h for a more complete explanation.
•
•
•
•
•
•
•
#define DEFINE_BASIC_TOKEN(name, type,...)
#define DEFINE_COUNTER_TOKEN(name, type,...)
#define DEFINE_INDEXED_TOKEN(name, type, arraysize,...)
#define DEFINE_FIXED_BASIC_TOKEN(name, type, address,...)
#define DEFINE_FIXED_COUNTER_TOKEN(name, type, address,...)
#define DEFINE_FIXED_INDEXED_TOKEN(name, type, arraysize, address,...)
#define DEFINE_MFG_TOKEN(name, type, address,...)
Creator Codes
The CREATOR is used as a distinct identifier tag for the token.
The CREATOR is necessary because the token name is defined differently depending on the hardware
platform, therefore the CREATOR makes sure that token definitions and data stay tagged and known. The
only requirement is that each creator definition must be unique. Please see hal/micro/token.h for a more
complete explanation.
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
#define CREATOR_STACK_NVDATA_VERSION
#define CREATOR_STACK_BOOT_COUNTER
#define CREATOR_STACK_NONCE_COUNTER
#define CREATOR_STACK_ANALYSIS_REBOOT
#define CREATOR_STACK_KEYS
#define CREATOR_STACK_NODE_DATA
#define CREATOR_STACK_CLASSIC_DATA
#define CREATOR_STACK_ALTERNATE_KEY
#define CREATOR_STACK_APS_FRAME_COUNTER
#define CREATOR_STACK_TRUST_CENTER
#define CREATOR_STACK_NETWORK_MANAGEMENT
#define CREATOR_STACK_PARENT_INFO
#define CREATOR_MULTI_NETWORK_STACK_KEYS
#define CREATOR_MULTI_NETWORK_STACK_NODE_DATA
#define CREATOR_MULTI_NETWORK_STACK_ALTERNATE_KEY
#define CREATOR_MULTI_NETWORK_STACK_TRUST_CENTER
#define CREATOR_MULTI_NETWORK_STACK_NETWORK_MANAGEMENT
#define CREATOR_MULTI_NETWORK_STACK_PARENT_INFO
#define CREATOR_MULTI_NETWORK_STACK_NONCE_COUNTER
#define CREATOR_STACK_BINDING_TABLE
#define CREATOR_STACK_CHILD_TABLE
EmberZNet 4.7.2 API EM250
120-3016-000-4720
166
•
•
•
•
#define CREATOR_STACK_KEY_TABLE
#define CREATOR_STACK_CERTIFICATE_TABLE
#define CREATOR_STACK_ZLL_DATA
#define CREATOR_STACK_ZLL_SECURITY
6.14.1
Detailed Description
The tokens listed here are divided into three sections (the three main types of tokens mentioned in token.h):
• manufacturing
• stack
• application
For a full explanation of the tokens, see hal/micro/token.h. See token-stack.h for source code.
There is a set of tokens predefined in the APPLICATION DATA section at the end of token-stack.h because
these tokens are required by the stack, but they are classified as application tokens since they are sized by
the application via its CONFIGURATION_HEADER.
The user application can include its own tokens in a header file similar to this one. The macro ::APPLICATION_TOKEN_HEADER should be defined to equal the name of the header file in which application
tokens are defined. See the APPLICATION DATA section at the end of token-stack.h for examples of
token definitions.
Since token-stack.h contains both the typedefs and the token defs, there are two #defines used to select
which one is needed when this file is included. #define DEFINETYPES is used to select the type definitions
and #define DEFINETOKENS is used to select the token definitions. Refer to token.h and token.c to see
how these are used.
6.14.2
Macro Definition Documentation
6.14.2.1
#define TOKEN NEXT ADDRESS( region, address )
By default, tokens are automatically located after the previous token.
If a token needs to be placed at a specific location, one of the DEFINE_FIXED_∗ definitions should be
used. This macro is inherently used in the DEFINE_FIXED_∗ definition to locate a token, and under
special circumstances (such as manufacturing tokens) it may be explicitely used.
Parameters
region A name for the next region being located.
address The address of the beginning of the next region.
Definition at line 59 of file token-stack.h.
6.14.2.2
#define DEFINE BASIC TOKEN( name, type, ... )
Definition at line 95 of file token-stack.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
167
6.14.2.3
#define DEFINE COUNTER TOKEN( name, type, ... )
Definition at line 98 of file token-stack.h.
6.14.2.4
#define DEFINE INDEXED TOKEN( name, type, arraysize, ... )
Definition at line 101 of file token-stack.h.
6.14.2.5
#define DEFINE FIXED BASIC TOKEN( name, type, address, ... )
Definition at line 104 of file token-stack.h.
6.14.2.6
#define DEFINE FIXED COUNTER TOKEN( name, type, address, ... )
Definition at line 108 of file token-stack.h.
6.14.2.7
#define DEFINE FIXED INDEXED TOKEN( name, type, arraysize, address, ... )
Definition at line 112 of file token-stack.h.
6.14.2.8
#define DEFINE MFG TOKEN( name, type, address, ... )
Definition at line 116 of file token-stack.h.
6.14.2.9
#define CREATOR STACK NVDATA VERSION
Definition at line 146 of file token-stack.h.
6.14.2.10
#define CREATOR STACK BOOT COUNTER
Definition at line 147 of file token-stack.h.
6.14.2.11
#define CREATOR STACK NONCE COUNTER
Definition at line 148 of file token-stack.h.
6.14.2.12
#define CREATOR STACK ANALYSIS REBOOT
Definition at line 149 of file token-stack.h.
6.14.2.13
#define CREATOR STACK KEYS
Definition at line 150 of file token-stack.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
168
6.14.2.14
#define CREATOR STACK NODE DATA
Definition at line 151 of file token-stack.h.
6.14.2.15
#define CREATOR STACK CLASSIC DATA
Definition at line 152 of file token-stack.h.
6.14.2.16
#define CREATOR STACK ALTERNATE KEY
Definition at line 153 of file token-stack.h.
6.14.2.17
#define CREATOR STACK APS FRAME COUNTER
Definition at line 154 of file token-stack.h.
6.14.2.18
#define CREATOR STACK TRUST CENTER
Definition at line 155 of file token-stack.h.
6.14.2.19
#define CREATOR STACK NETWORK MANAGEMENT
Definition at line 156 of file token-stack.h.
6.14.2.20
#define CREATOR STACK PARENT INFO
Definition at line 157 of file token-stack.h.
6.14.2.21
#define CREATOR MULTI NETWORK STACK KEYS
Definition at line 159 of file token-stack.h.
6.14.2.22
#define CREATOR MULTI NETWORK STACK NODE DATA
Definition at line 160 of file token-stack.h.
6.14.2.23
#define CREATOR MULTI NETWORK STACK ALTERNATE KEY
Definition at line 161 of file token-stack.h.
6.14.2.24
#define CREATOR MULTI NETWORK STACK TRUST CENTER
Definition at line 162 of file token-stack.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
169
6.14.2.25
#define CREATOR MULTI NETWORK STACK NETWORK MANAGEMENT
Definition at line 163 of file token-stack.h.
6.14.2.26
#define CREATOR MULTI NETWORK STACK PARENT INFO
Definition at line 164 of file token-stack.h.
6.14.2.27
#define CREATOR MULTI NETWORK STACK NONCE COUNTER
Definition at line 167 of file token-stack.h.
6.14.2.28
#define CREATOR STACK BINDING TABLE
Definition at line 170 of file token-stack.h.
6.14.2.29
#define CREATOR STACK CHILD TABLE
Definition at line 171 of file token-stack.h.
6.14.2.30
#define CREATOR STACK KEY TABLE
Definition at line 172 of file token-stack.h.
6.14.2.31
#define CREATOR STACK CERTIFICATE TABLE
Definition at line 173 of file token-stack.h.
6.14.2.32
#define CREATOR STACK ZLL DATA
Definition at line 174 of file token-stack.h.
6.14.2.33
#define CREATOR STACK ZLL SECURITY
Definition at line 175 of file token-stack.h.
6.14.2.34
#define CURRENT STACK TOKEN VERSION
The current version number of the stack tokens. MSB is the version, LSB is a complement.
Please see hal/micro/token.h for a more complete explanation.
Definition at line 209 of file token-stack.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
170
6.15
ZigBee Device Object
Functions
• EmberStatus emberNetworkAddressRequest (EmberEUI64 target, boolean reportKids, int8u childStartIndex)
• EmberStatus emberIeeeAddressRequest (EmberNodeId target, boolean reportKids, int8u childStartIndex, EmberApsOption options)
• 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)
6.15.1
Detailed Description
See zigbee-device-stack.h for source code.
6.15.2
Function Documentation
6.15.2.1 EmberStatus emberNetworkAddressRequest ( EmberEUI64 target, boolean reportKids, int8u
childStartIndex )
Request the 16 bit network address of a node whose EUI64 is known.
Parameters
target 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.
6.15.2.2 EmberStatus emberIeeeAddressRequest ( EmberNodeId target, boolean reportKids, int8u
childStartIndex, EmberApsOption options )
Request the EUI64 of a node whose 16 bit network address is known.
Parameters
target
reportKids
childStartIndex
EmberZNet 4.7.2 API EM250
options
The network address of the node.
TRUE to request that the target list their children in the response.
The index of the first child to list in the response. Ignored if reportKids is FALSE.
The options to use when120-3016-000-4720
sending the request. See emberSendUnicast() for a description.
171
Returns
An EmberStatus value.
• EMBER_SUCCESS
• EMBER_NO_BUFFERS
• EMBER_NETWORK_DOWN
• EMBER_NETWORK_BUSY
6.15.2.3 EmberStatus emberEnergyScanRequest ( EmberNodeId target, int32u scanChannels, int8u
scanDuration, int16u scanCount )
Request that an energy scan be performed and its results returned. This request may only be sent by the
current network manager and must be unicast, not broadcast.
Parameters
target 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
An EmberStatus value.
• EMBER_SUCCESS
• EMBER_NO_BUFFERS
• EMBER_NETWORK_DOWN
• EMBER_NETWORK_BUSY
6.15.2.4 EmberStatus emberSetNetworkManagerRequest ( EmberNodeId networkManager, int32u
activeChannels )
Broadcasts a request to set the identity of the network manager and the active channel mask. The mask is
used when scanning for the network after missing a channel update.
Parameters
network- The network address of the network manager.
Manager
activeChannels The new active channel mask.
Returns
An EmberStatus value.
• EMBER_SUCCESS
• EMBER_NO_BUFFERS
EmberZNet 4.7.2 API EM250
120-3016-000-4720
172
• EMBER_NETWORK_DOWN
• EMBER_NETWORK_BUSY
6.15.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 for
the broadcast to propagate.
Parameters
channel The channel to change to.
Returns
An EmberStatus value.
• EMBER_SUCCESS
• EMBER_NO_BUFFERS
• EMBER_NETWORK_DOWN
• EMBER_NETWORK_BUSY
6.15.2.6 EmberStatus emberSendDeviceAnnouncement ( void )
Sends a broadcast for a ZDO Device announcement. Normally it is NOT required to call this as the stack
automatically sends a device announcement during joining or rejoining, as per the spec. However if the
device wishes to re-send its device announcement they can use this call.
Returns
An EmberStatus value.
• EMBER_SUCCESS
• EMBER_INVALID_CALL
6.15.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 EM250
120-3016-000-4720
173
6.16
Bootloader
Functions
• EmberStatus emberSendBootloadMessage (boolean broadcast, EmberEUI64 destEui64, EmberMessageBuffer message)
• void emberIncomingBootloadMessageHandler (EmberEUI64 longId, EmberMessageBuffer message)
• void emberBootloadTransmitCompleteHandler (EmberMessageBuffer message, EmberStatus status)
6.16.1
Detailed Description
EmberZNet bootload API. See bootload.h for source code.
6.16.2
Function Documentation
6.16.2.1 EmberStatus emberSendBootloadMessage ( boolean broadcast, EmberEUI64 destEui64,
EmberMessageBuffer message )
Transmits the given bootload message to a neighboring node using a specific 802.15.4 header that allows
the EmberZNet stack as well as the bootloader to recognize the message, but will not interfere with other
ZigBee stacks.
Parameters
broadcast If TRUE, the destination address and pan id are both set to the broadcast address.
destEui64 The EUI64 of the target node. Ignored if the broadcast field is set to TRUE.
message The bootloader message to send.
Returns
EMBER_SUCCESS if the message was successfully submitted to the transmit queue, and EMBER_ERR_FATAL otherwise.
6.16.2.2
void emberIncomingBootloadMessageHandler ( EmberEUI64 longId, EmberMessageBuffer
message )
A callback invoked by the EmberZNet stack when a bootload message is received. If the application
includes emberIncomingBootloadMessageHandler(), it must define EMBER_APPLICATION_HAS_BOOTLOAD_HANDLERS in its CONFIGURATION_HEADER.
Parameters
longId The EUI64 of the sending node.
message The bootload message that was sent.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
174
6.16.2.3
void emberBootloadTransmitCompleteHandler ( EmberMessageBuffer message, EmberStatus
status )
A callback invoked by the EmberZNet stack when the MAC has finished transmitting a bootload message.
If the application includes this callback, it must define EMBER_APPLICATION_HAS_BOOTLOAD_HANDLERS in its CONFIGURATION_HEADER.
Parameters
message The message that was sent.
status EMBER_SUCCESS if the transmission was successful, or EMBER_DELIVERY_FAILED if not.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
175
6.17
Event Scheduling
Macros
•
•
•
•
•
•
•
•
•
•
#define __EVENT_H__
#define emberEventControlSetInactive(control)
#define emberEventControlGetActive(control)
#define emberEventControlSetActive(control)
#define emberEventControlSetDelayMS(control, delay)
#define emberEventControlSetDelayQS(control, delay)
#define emberEventControlSetDelayMinutes(control, delay)
#define emberEventControlGetRemainingMS(control)
#define emberTaskEnableIdling(allow)
#define emberMarkTaskActive(taskid)
Functions
•
•
•
•
•
•
•
•
•
•
•
•
•
•
void emEventControlSetActive (EmberEventControl ∗event)
void emEventControlSetDelayMS (EmberEventControl ∗event, int16u delay)
void emEventControlSetDelayQS (EmberEventControl ∗event, int16u delay)
void emEventControlSetDelayMinutes (EmberEventControl ∗event, int16u delay)
int32u emEventControlGetRemainingMS (EmberEventControl ∗event)
void emberRunEvents (EmberEventData ∗events)
void emberRunTask (EmberTaskId taskid)
int32u emberMsToNextEvent (EmberEventData ∗events, int32u maxMs)
int32u emberMsToNextEventExtended (EmberEventData ∗events, int32u maxMs, int8u ∗returnIndex)
int32u emberMsToNextStackEvent (void)
EmberTaskId emberTaskInit (EmberEventData ∗events)
boolean emberMarkTaskIdle (EmberTaskId taskid)
void emTaskEnableIdling (boolean allow)
void emMarkTaskActive (EmberTaskId taskid)
6.17.1
Detailed Description
These macros implement an event abstraction that allows the application to schedule code to run after
some specified time interval. An event consists of a procedure to be called at some point in the future and
a control object that determines the procedure should be called. Events are also useful for when an ISR
needs to initiate an action that should run outside of ISR context.
See event.h for source code.
Note that while not required, it is recommended that the event-handling procedure explicitly define the
recurrence of the next event, either by rescheduling it via some kind of emberEventControlSetDelayXX()
call or by deactivating it via a call to emberEventControlSetInactive(). In cases where the handler does not
explicitly reschedule or cancel the event, the default behavior of the event control system is to keep the
event immediately active as if the handler function had called emberEventControlSetActive(someEvent) or
emberEventControlSetDelayMS(someEvent, EMBER_EVENT_ZERO_DELAY)
The time units are all in ’binary’ One ’millisecond’ is 1/1024 of a second. One ’quarter second’ is 256
milliseconds (which happens to work out to be the same as a real quarter second) One ’minute’ is 65536
EmberZNet 4.7.2 API EM250
120-3016-000-4720
176
(0x10000) milliseconds (64 ∗ 4 ’quarter seconds’). The accuracy of the base ’millisecond’ depends on your
timer source.
Following are some brief usage examples.
EmberEventControl delayEvent;
EmberEventControl signalEvent;
EmberEventControl periodicEvent;
void delayEventHandler(void)
{
// Disable this event until its next use.
emberEventControlSetInactive(delayEvent);
}
void signalEventHandler(void)
{
// Disable this event until its next use.
emberEventControlSetInactive(signalEvent);
// Sometimes we need to do something 100 ms later.
if (somethingIsExpected)
emberEventControlSetDelayMS(delayEvent, 100);
}
void periodicEventHandler(void)
{
emberEventControlSetDelayQS(periodicEvent, 4);
}
void someIsr(void)
{
// Set the signal event to run at the first opportunity.
emberEventControlSetActive(signalEvent);
}
// Put the controls and handlers in an array. They will be run in
// this order.
EmberEventData events[] =
{
{ &delayEvent,
delayEventHandler },
{ &signalEvent,
signalEentHandler },
{ &periodicEvent, periodicEventHandler },
{ NULL, NULL }
// terminator
};
void main(void)
{
// Cause the periodic event to occur once a second.
emberEventControlSetDelayQS(periodicEvent, 4);
while (TRUE) {
emberRunEvents(events);
}
}
6.17.2
Macro Definition Documentation
6.17.2.1
#define EVENT H
Definition at line 106 of file event.h.
6.17.2.2
#define emberEventControlSetInactive( control )
Sets this EmberEventControl as inactive (no pending event).
Definition at line 110 of file event.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
177
6.17.2.3
#define emberEventControlGetActive( control )
Returns TRUE if the event is active, FALSE otherwise.
Definition at line 115 of file event.h.
6.17.2.4
#define emberEventControlSetActive( control )
Sets this EmberEventControl to run at the next available opportunity.
Definition at line 121 of file event.h.
6.17.2.5
#define emberEventControlSetDelayMS( control, delay )
Sets this EmberEventControl to run "delay" milliseconds in the future.
Definition at line 131 of file event.h.
6.17.2.6
#define emberEventControlSetDelayQS( control, delay )
Sets this EmberEventControl to run "delay" quarter seconds in the future. The ’quarter seconds’ are actually
256 milliseconds long.
Definition at line 141 of file event.h.
6.17.2.7
#define emberEventControlSetDelayMinutes( control, delay )
Sets this EmberEventControl to run "delay" minutes in the future. The ’minutes’ are actually 65536
(0x10000) milliseconds long.
Definition at line 152 of file event.h.
6.17.2.8
#define emberEventControlGetRemainingMS( control )
Returns The amount of milliseconds remaining before the event is scheduled to run. If the event is inactive,
MAX_INT32U_VALUE is returned.
Definition at line 163 of file event.h.
6.17.2.9
#define emberTaskEnableIdling( allow )
Call this to indicate that an application supports processor idling.
Definition at line 229 of file event.h.
6.17.2.10
#define emberMarkTaskActive( taskid )
Indicates that a task has something to do, so the CPU should not be idled until emberMarkTaskIdle is next
called on this task.
Definition at line 237 of file event.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
178
6.17.3
Function Documentation
6.17.3.1
void emEventControlSetActive ( EmberEventControl ∗ event )
Sets this EmberEventControl to run at the next available opportunity.
6.17.3.2
void emEventControlSetDelayMS ( EmberEventControl ∗ event, int16u delay )
Sets this EmberEventControl to run "delay" milliseconds in the future.
6.17.3.3
void emEventControlSetDelayQS ( EmberEventControl ∗ event, int16u delay )
Sets this EmberEventControl to run "delay" quarter seconds in the future. The ’quarter seconds’ are actually
256 milliseconds long.
6.17.3.4
void emEventControlSetDelayMinutes ( EmberEventControl ∗ event, int16u delay )
Sets this EmberEventControl to run "delay" minutes in the future. The ’minutes’ are actually 65536
(0x10000) milliseconds long.
6.17.3.5 int32u emEventControlGetRemainingMS ( EmberEventControl ∗ event )
Returns The amount of milliseconds remaining before the event is scheduled to run. If the event is inactive,
MAX_INT32U_VALUE is returned.
6.17.3.6
void emberRunEvents ( EmberEventData ∗ events )
An application typically creates an array of events along with their handlers.
The main loop passes the array to emberRunEvents() in order to call the handlers of any events whose time
has arrived.
6.17.3.7
void emberRunTask ( EmberTaskId taskid )
If an application has initialized a task via emberTaskInit, to run the events associated with that task, it
should could emberRunTask() instead of emberRunEvents().
6.17.3.8 int32u emberMsToNextEvent ( EmberEventData ∗ events, int32u maxMs )
Returns the number of milliseconds before the next event is scheduled to expire, or maxMs if no event is
scheduled to expire within that time. NOTE: If any events are modified within an interrupt, in order to
guarantee the accuracy of this API, it must be called with interrupts disabled or from within an ATOMIC()
block.
6.17.3.9 int32u emberMsToNextEventExtended ( EmberEventData ∗ events, int32u maxMs, int8u ∗
returnIndex )
This function does the same as emberMsToNextEvent() with the following addition. If the returnIndex is
non-NULL, it will set the value pointed to by the pointer to be equal to the index of the event that is ready
EmberZNet 4.7.2 API EM250
120-3016-000-4720
179
to fire next. If no events are active, then it returns 0xFF.
6.17.3.10 int32u emberMsToNextStackEvent ( void )
Returns the number of milliseconds before the next stack event is scheduled to expire.
6.17.3.11 EmberTaskId emberTaskInit ( EmberEventData ∗ events )
Initializes a task to be used for managing events and processor idling state. Returns the EmberTaskId which
represents the newly created task.
6.17.3.12 boolean emberMarkTaskIdle ( EmberTaskId taskid )
Indicates that a task has nothing to do (unless any events are pending) and that it would be safe to idle the
CPU if all other tasks also have nothing to do. This API should always be called with interrupts disabled.
It will forcibly re-enable interrupts before returning Returns TRUE if the processor was idled, FALSE if
idling wasn’t permitted because some other task has something to do.
6.17.3.13
void emTaskEnableIdling ( boolean allow )
6.17.3.14
void emMarkTaskActive ( EmberTaskId taskid )
EmberZNet 4.7.2 API EM250
120-3016-000-4720
180
6.18
Manufacturing and Functional Test Library
Functions
•
•
•
•
•
•
•
•
•
•
•
•
•
•
EmberStatus mfglibStart (void(∗mfglibRxCallback)(int8u ∗packet, int8u linkQuality, int8s rssi))
EmberStatus mfglibEnd (void)
EmberStatus mfglibStartTone (void)
EmberStatus mfglibStopTone (void)
EmberStatus mfglibStartStream (void)
EmberStatus mfglibStopStream (void)
EmberStatus mfglibSendPacket (int8u ∗packet, int16u repeat)
EmberStatus mfglibSetChannel (int8u chan)
int8u mfglibGetChannel (void)
EmberStatus mfglibSetPower (int16u txPowerMode, int8s power)
int8s mfglibGetPower (void)
void mfglibSetSynOffset (int8s synOffset)
int8s mfglibGetSynOffset (void)
void mfglibTestContModCal (int8u channel, int32u duration)
6.18.1
Detailed Description
This is a manufacturing and functional test library for testing and verifying the RF component of products
at manufacture time. See mfglib.h for source code.
Developers can optionally include this library in their application code. The goal is that in most cases, this
will eliminate the need for developers to load multiple images into their hardware at manufacturing time.
This library can optionally be compiled into the developer’s production code and run at manufacturing
time. Any interface to the library is handled by the application.
This library cannot assist in hardware start up.
Many functions in this file return an EmberStatus value. See error-def.h for definitions of all EmberStatus
return values.
6.18.2
Function Documentation
6.18.2.1 EmberStatus mfglibStart ( void(∗)(int8u ∗packet, int8u linkQuality, int8s rssi) mfglibRxCallback
)
Activates use of mfglib test routines and enables the radio receiver to report packets it receives to the
caller-specified ::mfglibRxCallback() routine.
It is legal to pass in a NULL. These packets will not be passed up with a CRC failure. The first byte of
the packet in the callback is the length. All other functions will return an error until mfglibStart() has been
called.
Application Usage:
Use this function to enter test mode.
Note: This function should only be called shortly after initialization and prior to forming or joining a
network.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
181
Parameters
mfglibRx- Function pointer to callback routine invoked whenever a valid packet is received.
Callback emberTick() must be called routinely for this callback to function correctly.
Returns
One of the following:
• EMBER_SUCCESS if the mfg test mode has been enabled.
• EMBER_ERR_FATAL if the mfg test mode is not available.
6.18.2.2 EmberStatus mfglibEnd ( void )
Deactivates use of Manufacturing and Functional Test Library test routines.
This restores the hardware to the state it was in prior to mfglibStart() and stops receiving packets started by
mfglibStart() at the same time.
Application Usage:
Use this function to exit the mfg test mode.
Note: It may be desirable to also reboot after use of manufacturing mode to ensure all application state is
properly re-initialized.
Returns
One of the following:
• EMBER_SUCCESS if the mfg test mode has been exited.
• EMBER_ERR_FATAL if the mfg test mode cannot be exited.
6.18.2.3 EmberStatus mfglibStartTone ( void )
Starts transmitting the tone feature of the radio.
In this mode, the radio will transmit an unmodulated tone on the currently set channel and power level.
Upon successful return, the tone will be transmitting. To stop transmitting a tone, the application must call
mfglibStopTone(), allowing it the flexibility to determine its own criteria for tone duration, such as time,
event, and so on.
Application Usage:
Use this function to transmit a tone.
Returns
One of the following:
• EMBER_SUCCESS if the transmit tone has started.
• EMBER_ERR_FATAL if the tone cannot be started.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
182
6.18.2.4 EmberStatus mfglibStopTone ( void )
Stops transmitting a tone started by mfglibStartTone().
Application Usage:
Use this function to stop transmitting a tone.
Returns
One of the following:
• EMBER_SUCCESS if the transmit tone has stopped.
• EMBER_ERR_FATAL if the tone cannot be stopped.
6.18.2.5 EmberStatus mfglibStartStream ( void )
Starts transmitting a random stream of characters. This is so that the radio modulation can be measured.
Application Usage:
Use this function to enable the measurement of radio modulation.
Returns
One of the following:
• EMBER_SUCCESS if the transmit stream has started.
• EMBER_ERR_FATAL if the stream cannot be started.
6.18.2.6 EmberStatus mfglibStopStream ( void )
Stops transmitting a random stream of characters started by mfglibStartStream().
Application Usage:
Use this function to end the measurement of radio modulation.
Returns
One of the following:
• EMBER_SUCCESS if the transmit stream has stopped.
• EMBER_ERR_FATAL if the stream cannot be stopped.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
183
6.18.2.7 EmberStatus mfglibSendPacket ( int8u ∗ packet, int16u repeat )
Sends a single packet, (repeat + 1) times.
Application Usage:
Use this function to send raw data. Note that packet array must be word-aligned (begin at even address),
such that ((((int16u)packet) & 1) == 0) holds true. (This is generally done by either declaring packet
as a local variable or putting it in a global declaration immediately following the declaration of an
int16u.)
Parameters
packet Packet to be sent. First byte of the packet is always the length byte, whose value does
not include itself but does include the 16-bit CRC in the length calculation. The CRC
gets appended automatically by the radio as it transmits the packet, so the host does
not need to provide this as part of packetContents. The total length of packet contents
(Length Byte+1) going out the radio should not be >128 or <6 bytes. Note that the
packet array should not include the CRC, as this appended by the radio automatically.
repeat Number of times to repeat sending the packet after having been sent once. A value of
0 means send once and don’t repeat.
Returns
One of the following:
• EMBER_SUCCESS if the packet was sent.
• EMBER_ERR_FATAL if the mfg test mode is not available or TONE or STREAM test is running.
6.18.2.8 EmberStatus mfglibSetChannel ( int8u chan )
Selects the radio channel. The channel range is from 11 to 26.
Customers can set any valid channel they want. Calibration occurs if this is the first time after power up.
Application Usage:
Use this function to change channels.
Parameters
chan Valid values depend upon the radio used.
Returns
One of the following:
• EMBER_SUCCESS if the channel has been set.
• ::EMBER_ERROR_INVALID_CHANNEL if the channel requested is invalid.
• EMBER_ERR_FATAL if the mfg test mode is not available or TONE or STREAM test is running.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
184
6.18.2.9 int8u mfglibGetChannel ( void )
Returns the current radio channel, as previously set via mfglibSetChannel().
Application Usage:
Use this function to get current channel.
Returns
Current channel.
6.18.2.10 EmberStatus mfglibSetPower ( int16u txPowerMode, int8s power )
First select the transmit power mode, and then include a method for selecting the radio transmit power.
Valid power settings depend upon the specific radio in use. Ember radios have discrete power settings, and
then requested power is rounded to a valid power setting. The actual power output is available to the caller
via mfglibGetPower().
Application Usage:
Use this function to adjust the transmit power.
Parameters
txPowerMode boost mode or external PA.
power Power in units of dBm, which can be negative.
Returns
One of the following:
• EMBER_SUCCESS if the power has been set.
• ::EMBER_ERROR_INVALID_POWER if the power requested is invalid.
• EMBER_ERR_FATAL if the mfg test mode is not available or TONE or STREAM test is running.
6.18.2.11 int8s mfglibGetPower ( void )
returns the current radio power setting as previously set via mfglibSetPower().
Application Usage:
Use this function to get current power setting.
Returns
current power setting.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
185
6.18.2.12
void mfglibSetSynOffset ( int8s synOffset )
set the synth offset in 11.7kHz steps. This function does NOT write the new synth offset to the token, it
only changes it in memory. It can be changed as many times as you like, and the setting will be lost when
a reset occurs. The value will survive deep sleep, but will not survive a reset, thus it will not take effect in
the bootloader. If you would like it to be permanent (and accessible to the bootloader), you must write the
TOKEN_MFG_SYNTH_FREQ_OFFSET token using the token API or em3xx_load –patch.
Application Usage:
Use this function to compensate for tolerances in the crystal oscillator or capacitors. This function
does not effect a permanent change; once you have found the offset you want, you must write it to a
token using the token API for it to be permanent.
Parameters
synOffset the number of 11.7kHz steps to offset the carrier frequency (may be negative)
6.18.2.13 int8s mfglibGetSynOffset ( void )
get the current synth offset in 11.7kHz steps. see mfglibSetSynOffset() for details
Returns
the synth offset in 11.7kHz steps
6.18.2.14
void mfglibTestContModCal ( int8u channel, int32u duration )
Run mod DAC calibration on the given channel for the given amount of time.
If the duration argument == 0, this test will run forever (until the chip is reset).
Application Usage:
Use this function to run the active transmit part of mod DAC calibration.
Parameters
channel Selects the channel to transmit on.
duration Duration in ms, 0 == infinite.
Returns
None.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
186
6.19
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,...)
6.19.1
Detailed Description
EmberZNet debugging utilities. See ember-debug.h for source code.
6.19.2
Macro Definition Documentation
6.19.2.1
#define NO DEBUG
Definition at line 20 of file ember-debug.h.
6.19.2.2
#define BASIC DEBUG
Definition at line 21 of file ember-debug.h.
6.19.2.3
#define FULL DEBUG
Definition at line 22 of file ember-debug.h.
6.19.2.4
#define emberDebugInit( port )
This function is obsolete and no longer required to initialize the debug system.
Parameters
port Ignored because the port used for debug communication is automatically determined
for each platform.
Definition at line 30 of file ember-debug.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
187
6.19.3
Function Documentation
6.19.3.1
void emberDebugAssert ( PGM P filename, int linenumber )
Prints the filename and line number to the debug serial port.
Parameters
filename The name of the file where the assert occurred.
linenumber The line number in the file where the assert occurred.
6.19.3.2
void emberDebugMemoryDump ( int8u ∗ start, int8u ∗ end )
Prints the contents of RAM to the debug serial port.
Parameters
start 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.19.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 emberDebugPrintf(). 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);
Parameters
formatString A string of conversion specification characters describing the arguments to be printed.
... The arguments to be printed.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
188
6.19.3.4
void emDebugSendVuartMessage ( int8u ∗ buff, int8u len )
internal debug command used by the HAL to send vuart data out the the debug channel
Parameters
buff pointer to the data to send
len lenght of the data to send
6.19.3.5
void emberDebugError ( EmberStatus code )
Prints an EmberStatus return code to the serial port.
Parameters
code The EmberStatus code to print.
6.19.3.6 boolean emberDebugReportOff ( void )
Turns off all debug output.
Returns
The current state (TRUE for on, FALSE for off).
6.19.3.7
void emberDebugReportRestore ( boolean state )
Restores the state of the debug output.
Parameters
state The state returned from emberDebugReportOff(). This is done so that debug output is
not blindly turned on.
6.19.3.8
void emberDebugPrintf ( PGM P formatString, ... )
Prints text debug messages.
Parameters
formatString Takes the following:
%%
%c
%s
EmberZNet 4.7.2 API EM250
Percent sign
Single-byte char
RAM string
120-3016-000-4720
189
%p
%u
%d
%x, %%2x, %%4x
EmberZNet 4.7.2 API EM250
Flash string (does not follow the printf standard)
Two-byte unsigned decimal
Two-byte signed decimal
1-, 2-, 4-byte hex value (always 0 padded; does
not follow the printf standard)
120-3016-000-4720
190
6.20
Hardware Abstraction Layer (HAL) API Reference
Modules
•
•
•
•
•
•
•
•
Common Microcontroller Functions
Token Access
Sample APIs for Peripheral Access
System Timer Control
Bootloading
HAL Configuration
HAL Utilities
Asynchronous Serial Host (ASH) Framework
6.20.1
Detailed Description
<center><h1>EM250 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. This
API must be implemented. Custom applications can change the implementation of the API but its functionality must remain the same.
hal: API that is used by sample applications. Custom applications can remove this API or change its
implementation as they see fit.
halStack: API used only by the EmberZNet stack. This API must be implemented and should not be
directly called from any application. Custom applications can change the implementation of the API, but
its functionality must remain the same.
halInternal: API that is internal to the HAL. The EmberZNet stack and applications must never call this
API directly. Custom applications can change this API as they see fit. However, be careful not to impact
the functionalty of any halStack or halCommon APIs.
See also hal.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
191
6.21
Common Microcontroller Functions
Macros
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
#define halGetEm2xxResetInfo()
#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
#define MILLISECOND_TICKS_PER_SECOND
Functions
•
•
•
•
•
•
•
•
•
•
•
•
void halStackProcessBootCount (void)
int8u halGetResetInfo (void)
PGM_P halGetResetString (void)
void halInternalAssertFailed (PGM_P filename, int linenumber)
void halInternalResetWatchDog (void)
boolean halInternalWatchDogEnabled (void)
void rcSetCalibration (int16u value)
int16u rcGetCalibration (void)
void halInternalCalibrateRc (void)
int16u halInternalStackUsed (boolean lastReBoot)
int32u halGetWakeInfo (void)
void halCommonDelayMilliseconds (int16u ms)
6.21.1
Detailed Description
Many of the supplied example applications use these microcontroller functions. See hal/micro/micro.h for
source code.
Note
The term SFD refers to the Start Frame Delimiter.
See also hal/micro/xap2b/em250/micro.h for source code.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
192
6.21.2
Macro Definition Documentation
6.21.2.1
#define halGetEm2xxResetInfo( )
Calls ::halGetExtendedResetInfo() and translates the EM35x reset code to the corresponding value used
by the EM2XX HAL. EM35x reset codes not present in the EM2XX are returned after being OR’ed with
0x80.
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.21.2.2
#define RESET UNKNOWN
Defines conditions representing possible reasons for a reset.
Definition at line 84 of file xap2b/em250/micro.h.
6.21.2.3
#define RESET EXTERNAL
Definition at line 85 of file xap2b/em250/micro.h.
6.21.2.4
#define RESET POWERON
Definition at line 86 of file xap2b/em250/micro.h.
6.21.2.5
#define RESET WATCHDOG
Definition at line 87 of file xap2b/em250/micro.h.
6.21.2.6
#define RESET BROWNOUT
Definition at line 88 of file xap2b/em250/micro.h.
6.21.2.7
#define RESET JTAG
Definition at line 89 of file xap2b/em250/micro.h.
6.21.2.8
#define RESET ASSERT
Definition at line 90 of file xap2b/em250/micro.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
193
6.21.2.9
#define RESET RSTACK
Definition at line 91 of file xap2b/em250/micro.h.
6.21.2.10
#define RESET CSTACK
Definition at line 92 of file xap2b/em250/micro.h.
6.21.2.11
#define RESET BOOTLOADER
Definition at line 93 of file xap2b/em250/micro.h.
6.21.2.12
#define RESET PC ROLLOVER
Definition at line 94 of file xap2b/em250/micro.h.
6.21.2.13
#define RESET SOFTWARE
Definition at line 95 of file xap2b/em250/micro.h.
6.21.2.14
#define RESET PROTFAULT
Definition at line 96 of file xap2b/em250/micro.h.
6.21.2.15
#define RESET FLASH VERIFY FAIL
Definition at line 97 of file xap2b/em250/micro.h.
6.21.2.16
#define RESET FLASH WRITE INHIBIT
Definition at line 98 of file xap2b/em250/micro.h.
6.21.2.17
#define RESET BOOTLOADER IMG BAD
Definition at line 99 of file xap2b/em250/micro.h.
6.21.2.18
#define MILLISECOND TICKS PER SECOND
Definition at line 162 of file xap2b/em250/micro.h.
6.21.3
Function Documentation
6.21.3.1
void halStackProcessBootCount ( void )
Called from emberInit and provides a means for the HAL to increment a boot counter, most commonly in
non-volatile memory.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
194
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, for
example, 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.21.3.2 int8u halGetResetInfo ( void )
Gets information about what caused the microcontroller to reset.
Returns
A code identifying the cause of the reset.
6.21.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.21.3.4
void halInternalAssertFailed ( PGM P filename, int linenumber )
Called implicitly through the standard C language assert() macro. An implementation where notification
is, for instance, sent over the serial port can provide meaningful and useful debugging information.
Note
Liberal usage of assert() consumes flash space.
Parameters
filename Name of the file throwing the assert.
linenumber Line number that threw the assert.
6.21.3.5
void halInternalResetWatchDog ( void )
Resets the watchdog timer. This function is pointed to by the macro halResetWatchdog().
EmberZNet 4.7.2 API EM250
120-3016-000-4720
195
Warning
Be very careful when using this as you can easily get into an infinite loop.
6.21.3.6 boolean halInternalWatchDogEnabled ( void )
Finds out if the watchdog is currently enabled.
Returns
A boolean value indicating if the watchdog is current enabled.
6.21.3.7
void rcSetCalibration ( int16u value )
Sets the 1kHz calibration register with the input parameter.
Parameters
value The value to write into the 1kHz calibration register..
6.21.3.8 int16u rcGetCalibration ( void )
Retrieves the current 1kHz calibration word.
Returns
The value in the 1kHz calibration register.
6.21.3.9
void halInternalCalibrateRc ( void )
Calibrates the internal RC to generate a 1024 Hz (1kHz) clock.
6.21.3.10 int16u halInternalStackUsed ( boolean lastReBoot )
Returns the number of bytes currently used by the stack or used by the stack prior to the last boot or reboot.
Returns
The number of bytes used by the stack.
6.21.3.11 int32u halGetWakeInfo ( void )
Obtains the events that caused the last wake from sleep.
If bits[16:0] are set, they correspond to GPIO[16:0] as the wake event(s). Bit 30 is Sleep Timer Compare
A event. Bit 31 is SIF activity.
Returns
The events that caused the last wake from sleep.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
196
6.21.3.12
void halCommonDelayMilliseconds ( int16u ms )
EmberZNet 4.7.2 API EM250
120-3016-000-4720
197
6.22
Token Access
Modules
• Tokens
• Simulated EEPROM
6.22.1
Detailed Description
The token system stores such non-volatile information as the manufacturing ID, channel number, transmit
power, and various pieces of information that the application needs to be persistent between device power
cycles. The token system is design to abstract implementation details and simplify interacting with differing
non-volatile systems. The majority of tokens are stored in Simulated EEPROM (in Flash) where they can
be rewritten. Manufacturing tokens are stored in dedicated regions of flash and are not designed to be
rewritten.
Refer to the Tokens module for a detailed description of the token system.
Refer to the Simulated EEPROM module for a detailed description of the necessary support functions for
Simulated EEPROM.
Refer to the simeeprom2 module for a detailed description of the necessary support functions for Simulated
EEPROM, version 2.
Refer to token-stack.h for stack token definitions.
Refer to token-manufacturing.h for manufaturing token definitions.
Note
Simulated EEPROM, version 2 is only supported on EM335x chips.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
198
6.23
Tokens
Macros
•
•
•
•
•
•
#define halCommonGetToken(data, token)
#define halCommonGetMfgToken(data, token)
#define halCommonGetIndexedToken(data, token, index)
#define halCommonSetToken(token, data)
#define halCommonSetIndexedToken(token, index, data)
#define halCommonIncrementCounterToken(token)
Functions
• EmberStatus halStackInitTokens (void)
• XAP2B_PAGEZERO_ON void halInternalGetTokenData (void ∗data, int16u token, int8u index,
int8u len)
• XAP2B_PAGEZERO_OFF void halInternalGetMfgTokenData (void ∗data, int16u ID, int8u index,
int8u len)
• void halInternalSetTokenData (int16u token, int8u index, void ∗data, int8u len)
• void halInternalIncrementCounterToken (int8u token)
6.23.1
Detailed Description
There are three main types of tokens:
• Manufacturing tokens: Tokens that are set at the factory and must not be changed through software
operations.
• Stack-level tokens: Tokens that can be changed via the appropriate stack API calls.
• Application level tokens: Tokens that can be set via the token system API calls in this file.
The token system API controls writing tokens to non-volatile data and reading tokens from non-volatile
data. If an application wishes to use application specific normal tokens, it must do so by creating its
own token header file similar to token-stack.h. The macro APPLICATION_TOKEN_HEADER should be
defined to equal the name of the header file in which application tokens are defined. If an application
wishes to use application specific manufacturing tokens, it must do so by creating its own manufacturing
token header file similar to token-manufacturing.h. The macro APPLICATION_MFG_TOKEN_HEADER
should be defined to equal the name of the header file in which manufacturing tokens are defined.
Because the token system is based on memory locations within non-volatile storage, the token information
could become out of sync without some kind of version tracking. The two defines, CURRENT_MFG_TOKEN_VERSION and CURRENT_STACK_TOKEN_VERSION, are used to make sure the stack stays
in sync with the proper token set. If the application defines its own tokens, it is recommended that the
application also define an application token to be a application version to ensure the application stays in
sync with the proper token set.
The most general format of a token definition is:
#define CREATOR_name 16bit_value
#ifdef DEFINETYPES
typedef data_type type
#endif //DEFINETYPES
#ifdef DEFINETOKENS
DEFINE_*_TOKEN(name, type, ... ,defaults)
#endif //DEFINETOKENS
EmberZNet 4.7.2 API EM250
120-3016-000-4720
199
The defined CREATOR is used as a distinct identifier tag for the token. The CREATOR is necessary
because the token name is defined differently depending on underlying implementation, so the CREATOR makes sure token definitions and data stay tagged and known. The only requirement on these creator
definitions is that they all must be unique. A favorite method for picking creator codes is to use two ASCII
characters inorder to make the codes more memorable. The ’name’ part of the #define CREATOR_name must match the ’name’ provided in the DEFINE_∗_TOKEN because the token system uses this
name to automatically link the two.
The typedef provides a convenient and efficient abstraction of the token data. Since some tokens are structs
with multiple pieces of data inside of them, type defining the token type allows more efficient and readable
local copies of the tokens throughout the code.
The typedef is wrapped with an #ifdef DEFINETYPES because the typdefs and token defs live in the
same file, and DEFINETYPES is used to select only the typedefs when the file is included. Similarly, the
DEFINE_∗_TOKEN is wrapped with an #ifdef DEFINETOKENS as a method for selecting only the
token definitions when the file is included.
The abstract definition, DEFINE_∗_TOKEN(name, type, ...
complete definitions:
,defaults), has seven possible
• DEFINE_BASIC_TOKEN(name, type, ...)
• DEFINE_INDEXED_TOKEN(name, type, arraysize, ...)
• DEFINE_COUNTER_TOKEN(name, type, ...)
• DEFINE_MFG_TOKEN(name, type, address, ...)
The three fields common to all DEFINE_∗_TOKEN are:
name - The name of the token, which all information is tied to.
type - Type of the token which is the same as the typedef mentioned before.
... - The default value to which the token is set upon initialization.
Note
The old DEFINE_FIXED∗ token definitions are no longer used. They remain defined for backwards
compatibility. In current systems, the Simulated EEPROM is used for storing non-manufacturing
tokens and the Simulated EEPROM intelligently manages where tokens are stored to provide wear
leveling across the flash memory and increase the number of write cycles. Manufacturing tokens live
at a fixed address, but they must use DEFINE_MFG_TOKEN so the token system knows they are
manufacturing tokens.
DEFINE_BASIC_TOKEN is the simplest definition and will be used for the majority of tokens (tokens
that are not indexed, not counters, and not manufacturing). Basic tokens are designed for data storage that
is always accessed as a single element.
DEFINE_INDEXED_TOKEN should be used on tokens that look like arrays. For example, data storage
that looks like:
int32u myData[5]
This example data storage can be a token with typedef of int32u and defined as INDEXED with arraysize
of 5. The extra field in this token definition is: arraysize - The number of elements in the indexed token.
Indexed tokens are designed for data storage that is logically grouped together, but elements are accessed
individually.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
200
DEFINE_COUNTER_TOKEN should be used on tokens that are simple numbers where the majority of
operations on the token is to increment the count. The reason for using DEFINE_COUNTER_TOKEN
instead of DEFINE_BASIC_TOKEN is the special support that the token system provides for incrementing counters. The function call halCommonIncrementCounterToken() only operates on counter
tokens and is more efficient in terms of speed, data compression, and write cyles for incrementing simple
numbers in the token system.
DEFINE_MFG_TOKEN is a DEFINE_BASIC_TOKEN token at a specific address and the token is manufacturing data that is written only once. The major difference is this token is designated manufacturing,
which means the token system treats it differently from stack or app tokens. Primarily, a manufacturing
token is written only once and lives at a fixed address outside of the Simulated EEPROM system. Being a
write once token, the token system will also aid in debugging by asserting if there is an attempt to write a
manufacturing token.
Here is an example of two application tokens:
#define CREATOR_SENSOR_NAME
0x5354
#define CREATOR_SENSOR_PARAMETERS 0x5350
#ifdef DEFINETYPES
typedef int8u tokTypeSensorName[10];
typedef struct {
int8u initValues[5];
int8u reportInterval;
int16u calibrationValue;
} tokTypeSensorParameters;
#endif //DEFINETYPES
#ifdef DEFINETOKENS
DEFINE_BASIC_TOKEN(SENSOR_NAME,
tokTypeSensorName,
{’U’,’N’,’A’,’M’,’E’,’D’,’ ’,’ ’,’ ’,’ ’})
DEFINE_BASIC_TOKEN(SENSOR_PARAMETERS,
tokTypeSensorParameters,
{{0x01,0x02,0x03,0x04,0x05},5,0x0000})
#endif //DEFINETOKENS
Here is an example of how to use the two application tokens:
{
tokTypeSensorName sensor;
tokTypeSensorParameters params;
halCommonGetToken(&sensor, TOKEN_SENSOR_NAME);
halCommonGetToken(&params, TOKEN_SENSOR_PARAMETERS);
if(params.calibrationValue == 0xBEEF) {
params.reportInterval = 5;
}
halCommonSetToken(TOKEN_SENSOR_PARAMETERS, &params);
}
See token-stack.h to see the default set of tokens and their values.
The nodetest utility app can be used for generic manipulation such as loading default token values, viewing
tokens, and writing tokens. The nodetest utility cannot work with customer defined application tokens
or manufacturing tokens. Using the nodetest utility will erase customer defined application tokens
in the Simulated EEPROM.
The Simulated EEPROM will initialize tokens to their default values if the token does not yet exist, the
token’s creator code is changed, or the token’s size changes.
Changing the number indexes in an INDEXED token will not alter existing entries. If the number of
indexes is reduced, the entires that still fit in the token will retain their data and the entries that no longer
fit will be erased. If the number of indexes is increased, the existing entries retain their data and the new
entries are initialized to the token’s defaults.
Further details on exact implementation can be found in code comments in token-stack.h file, the platform
specific token-manufacturing.h file, the platform specific token.h file, and the platform specific token.c file.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
201
Some functions in this file return an EmberStatus value. See error-def.h for definitions of all EmberStatus
return values.
See hal/micro/token.h for source code.
See also hal/micro/xap2b/token.h for source code.
6.23.2
Macro Definition Documentation
6.23.2.1
#define halCommonGetToken( data, token )
Macro that copies the token value from non-volatile storage into a RAM location. This macro can only be
used with tokens that are defined using DEFINE_BASIC_TOKEN.
Note
To better understand the parameters of this macro, refer to the example of token usage above.
Parameters
data A pointer to where the token data should be placed.
token The token name used in DEFINE_∗_TOKEN, prepended with TOKEN_.
Definition at line 276 of file token.h.
6.23.2.2
#define halCommonGetMfgToken( data, token )
Macro that copies the token value from non-volatile storage into a RAM location. This macro can only be
used with tokens that are defined using DEFINE_MFG_TOKEN.
Note
To better understand the parameters of this macro, refer to the example of token usage above.
Parameters
data A pointer to where the token data should be placed.
token The token name used in DEFINE_∗_TOKEN, prepended with TOKEN_.
Definition at line 291 of file token.h.
6.23.2.3
#define halCommonGetIndexedToken( data, token, index )
Macro that copies the token value from non-volatile storage into a RAM location. This macro can only be
used with tokens that are defined using DEFINE_INDEXED_TOKEN.
Note
To better understand the parameters of this macro, refer to the example of token usage above.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
202
Parameters
data A pointer to where the token data should be placed.
token The token name used in DEFINE_∗_TOKEN, prepended with TOKEN_.
index The index to access in the indexed token.
Definition at line 307 of file token.h.
6.23.2.4
#define halCommonSetToken( token, data )
Macro that sets the value of a token in non-volatile storage. This macro can only be used with tokens that
are defined using DEFINE_BASIC_TOKEN.
Note
To better understand the parameters of this macro, refer to the example of token usage above.
Parameters
token The token name used in DEFINE_∗_TOKEN, prepended with TOKEN_.
data A pointer to the data being written.
Definition at line 321 of file token.h.
6.23.2.5
#define halCommonSetIndexedToken( token, index, data )
Macro that sets the value of a token in non-volatile storage. This macro can only be used with tokens that
are defined using DEFINE_INDEXED_TOKEN.
Note
To better understand the parameters of this macro, refer to the example of token usage above.
Parameters
token The token name used in DEFINE_∗_TOKEN, prepended with TOKEN_.
index The index to access in the indexed token.
data A pointer to where the token data should be placed.
Definition at line 338 of file token.h.
6.23.2.6
#define halCommonIncrementCounterToken( token )
Macro that increments the value of a token that is a counter. This macro can only be used with tokens that
are defined using either DEFINE_COUNTER_TOKEN.
Note
To better understand the parameters of this macro, refer to the example of token usage above.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
203
Parameters
token The token name used in DEFINE_∗_TOKEN, prepended with TOKEN_.
Definition at line 351 of file token.h.
6.23.3
Function Documentation
6.23.3.1 EmberStatus halStackInitTokens ( void )
Initializes and enables the token system. Checks if the manufacturing and stack non-volatile data versions
are correct.
Returns
An EmberStatus value indicating the success or failure of the command.
6.23.3.2 XAP2B_PAGEZERO_ON void halInternalGetTokenData ( void ∗ data, int16u token, int8u
index, int8u len )
Copies the token value from non-volatile storage into a RAM location. This is the internal function that
the two exposed APIs (halCommonGetToken and halCommonGetIndexedToken) expand out to. The API
simplifies the access into this function by hiding the size parameter and hiding the value 0x7F used for the
index parameter in scalar tokens.
Parameters
data A pointer to where the data being read should be placed.
token The name of the token to get data from. On this platform that name is defined as an
address.
index The index to access. If the token being accessed is not an indexed token, this parameter
is set by the API to be 0x7F.
len The length of the token being worked on. This value is automatically set by the API to
be the size of the token.
6.23.3.3 XAP2B_PAGEZERO_OFF void halInternalGetMfgTokenData ( void ∗ data, int16u ID, int8u
index, int8u len )
Description:
Copies the token value from non-volatile storage into a RAM location. This is the internal function
that the exposed API (halCommonGetMfgToken) expands out to. The API simplifies the access into
this function by hiding the size parameter.
Parameters
data,: A pointer to where the data being read should be placed.
token,: The name of the token to get data from. On this platform that name is defined as an
address.
len,: The length of the token being worked on. This value is automatically set by the API to
be the size of the token.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
204
6.23.3.4
void halInternalSetTokenData ( int16u token, int8u index, void ∗ data, int8u len )
Sets the value of a token in non-volatile storage.
This is the internal function that the two exposed APIs (halCommonSetToken and halCommonSetIndexedToken) expand out to. The API simplifies the access into this function by hiding the size parameter and
hiding the value 0x7F used for the index parameter in scalar tokens.
Parameters
token The name of the token to get data from. On this platform that name is defined as an
address.
index The index to access. If the token being accessed is not an indexed token, this parameter
is set by the API to be 0x7F.
data A pointer to the data being written.
len The length of the token being worked on. This value is automatically set by the API to
be the size of the token.
6.23.3.5
void halInternalIncrementCounterToken ( int8u token )
Increments the value of a token that is a counter.
This is the internal function that the exposed API (halCommonIncrementCounterToken) expand out to.
This internal function is used as a level of simple redirection providing clean seperation from the lower
token handler code.
Parameters
token The name of the token.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
205
6.24
Simulated EEPROM
Functions
• void halSimEepromCallback (EmberStatus status)
• void halSimEepromErasePage (void)
• void halSimEepromStatus (int16u ∗freeWordsInCurrPage, int16u ∗totalPageUseCount)
6.24.1
Detailed Description
The Simulated EEPROM system (typically referred to as SimEE) is designed to operate under the Token
Access API and provide a non-volatile storage system. Since the flash write cycles are finite, the Simulated
EEPROM’s primary purpose is to perform wear leveling across several hardware flash pages, ultimately
increasing the number of times tokens may be written before a hardware failure.
The Simulated EEPROM needs to periodically perform a page erase operation to recover storage area for
future token writes. The page erase operation requires an ATOMIC block of 21ms. Since this is such a long
time to not be able to service any interrupts, the page erase operation is under application control providing
the application the opportunity to decide when to perform the operation and complete any special handling
needed that might be needed.
Note
The best, safest, and recommended practice is for the application to regularly and always call the
function halSimEepromErasePage() when the application can expect and deal with the page erase
delay. halSimEepromErasePage() will immediately return if there is nothing to erase. If there is
something that needs to be erased, doing so as regularly and as soon as possible will keep the SimEE
in the healthiest state possible.
::ERASE_CRITICAL_THRESHOLD is the metric the freePtr is compared against. This metric is set to
about 3/4 full. The freePtr is a marker used internally by the Simulated EEPROM to track where data ends
and where available write space begins. If the freePtr crosses this threhold, halSimEepromCallback() will
be called with an EmberStatus of EMBER_SIM_EEPROM_ERASE_PAGE_RED, indicating a critical
need for the application to call halSimEepromErasePage() which will erase a hardware page and provide
fresh storage for the Simulated EEPROM to write token data. If freePtr is less than the threshold, the
callback will have an EmberStatus of EMBER_SIM_EEPROM_ERASE_PAGE_GREEN indicating the
application should call halSimEepromErasePage() at its earliest convenience, but doing so is not critically
important at this time.
Some functions in this file return an EmberStatus value. See error-def.h for definitions of all EmberStatus
return values.
See hal/micro/sim-eeprom.h for source code.
6.24.2
Function Documentation
6.24.2.1
void halSimEepromCallback ( EmberStatus status )
The Simulated EEPROM callback function, implemented by the application.
Parameters
status An EmberStatus error code indicating one of the conditions described below.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
206
This callback will report an EmberStatus of EMBER_SIM_EEPROM_ERASE_PAGE_GREEN whenever
a token is set and a page needs to be erased. This ERASE_PAGE_GREEN means the amount of free storage
available has not passed the ::ERASE_CRITICAL_THRESHOLD and erasing is desired but not critical at
this time.
This callback will report an EmberStatus of EMBER_SIM_EEPROM_ERASE_PAGE_RED whenever
a token is set and a page must be erased. This ERASE_PAGE_RED means the amount of free storage
available has passed the ::ERASE_CRITICAL_THRESHOLD and erasing is critical to prevent possible
data loss occuring on future writes.
If the application does not call halSimEepromErasePage() often enough, it is possible for the Simulated
EEPROM to run out of available space to write new data. When this happens, this callback will report an
EmberStatus of EMBER_SIM_EEPROM_FULL indicating that the Simulated EEPROM has run out of
room, the data currently being set has been lost, and any future write attempts will be lost as well. If this
Status is ever returned, the application must call halSimEepromErasePage() eight times to guarantee there
is sufficient room to write new data.
This callback will report an EmberStatus of EMBER_SIM_EEPROM_REPAIRING when the Simulated
EEPROM needs to repair itself. While there’s nothing for an app to do when the SimEE is going to repair
itself (SimEE has to be fully functional for the rest of the system to work), alert the application to the fact
that repairing is occuring. There are debugging scenarios where an app might want to know that repairing
is happening; such as monitoring frequency.
Note
Common situations will trigger an expected repair, such as using a new chip or changing token definitions.
If the callback ever reports the status EMBER_ERR_FLASH_WRITE_INHIBITED or EMBER_ERR_FLASH_VERIFY_FAILED, this indicates a catastrophic failure in flash writing, meaning either the address
being written is not empty or the write itself has failed. If EMBER_ERR_FLASH_WRITE_INHIBITED is encountered, the function ::halInternalSimEeRepair(FALSE) should be called and the chip should
then be reset to allow proper initialization to recover. If EMBER_ERR_FLASH_VERIFY_FAILED is
encountered the Simulated EEPROM (and tokens) on the specific chip with this error should not be trusted
anymore.
6.24.2.2
void halSimEepromErasePage ( void )
Erases a hardware flash page, if needed.
This function can be called at anytime from anywhere in the application (except ISRs) and will only take
effect if needed (otherwise it will return immediately). Since this function takes 21ms to erase a hardware
page during which interrupts cannot be serviced, it is preferable to call this function while in a state that can
withstand being unresponsive for so long. The Simulated EEPROM will periodically request through the
halSimEepromCallback() that a page be erased. The Simulated EEPROM will never erase a page (which
could result in data loss) and relies entirely on the application to call this function to approve a page erase
(only one erase per call to this function).
The Simulated EEPROM depends on the ability to move between two Virtual Pages, which are comprised
of multiple hardware pages. Before moving to the unused Virtual Page, all hardware pages comprising the
unused Virtual Page must be erased first. The erase time of a hardware flash page is 21ms. During this time
the chip will be unresponsive and unable to service an interrupt or execute any code (due to the flash being
unavailable during the erase procedure). This function is used to trigger a page erase.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
207
6.24.2.3
void halSimEepromStatus ( int16u ∗ freeWordsInCurrPage, int16u ∗ totalPageUseCount )
Provides two basic statistics.
• The number of unused words in the current page
• The total page use count
There is a lot of management and state processing involved with the Simulated EEPROM, and most of it
has no practical purpose in the application. These two parameters provide a simple metric for knowing
how soon the Simulated EEPROM will need to switch to the other Virtual Page (::freeWordsInCurrPage)
and how many times (approximatly) the switch has occured (::totalPageUseCount).
Parameters
freeWordsInCurrPage
totalPageUseCount
EmberZNet 4.7.2 API EM250
A 16 bit number equal to the difference between the top of the Virtual Page and the
freePtr; the unused words.
The value of the highest page counter between the two Virtual Pages indicating how
many times the Simulated EEPROM has switched between the pages (and approximate
write cycles).
120-3016-000-4720
208
6.25
Sample APIs for Peripheral Access
Modules
•
•
•
•
•
•
•
•
Serial UART Communication
ADC Control
Button Control
Buzzer Control
LED Control
Flash Memory Control
SPI Access
Symbol Timer Control
6.25.1
Detailed Description
These are sample API for accessing peripherals and can be modified as needed for your applications.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
209
6.26
Serial UART Communication
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 higherlevel serial code uses these functions, so they should not be called directly. The HAL should also implement
the 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)
boolean halInternalUart1FlowControlRxIsEnabled (void)
boolean halInternalUart1XonRefreshDone (void)
boolean halInternalUart1TxIsIdle (void)
#define halInternalUartFlowControl(port)
#define halInternalUartRxPump(port)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
210
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)
6.26.1
Detailed Description
This API contains the HAL interfaces that applications must implement for the high-level serial code. This
header describes the interface between the high-level serial APIs in app/util/serial/serial.h and the low level
UART implementation.
Some functions in this file return an EmberStatus value. See error-def.h for definitions of all EmberStatus
return values.
See hal/micro/serial.h for source code.
6.26.2
Macro Definition Documentation
6.26.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.26.2.2
#define EMBER SERIAL FIFO
A numerical definition for a possible serial mode the code can test for.
Definition at line 56 of file hal/micro/serial.h.
6.26.2.3
#define EMBER SERIAL BUFFER
A numerical definition for a possible serial mode the code can test for.
Definition at line 57 of file hal/micro/serial.h.
6.26.2.4
#define EMBER SERIAL LOWLEVEL
A numerical definition for a possible serial mode the code can test for.
Definition at line 58 of file hal/micro/serial.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
211
6.26.2.5
#define FIFO ENQUEUE( queue, data, size )
Macro that enqueues a byte of data in a FIFO queue.
Parameters
queue Pointer to the FIFO queue.
data Data byte to be enqueued.
size Size used to control the wrap-around of the FIFO pointers.
Definition at line 233 of file hal/micro/serial.h.
6.26.2.6
#define FIFO DEQUEUE( queue, size )
Macro that de-queues a byte of data from a FIFO queue.
Parameters
queue Pointer to the FIFO queue.
size Size used to control the wrap-around of the FIFO pointers.
Definition at line 255 of file hal/micro/serial.h.
6.26.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 resume
transmission.
Parameters
port Serial port number (0 or 1). (Does nothing for port 0)
Definition at line 424 of file hal/micro/serial.h.
6.26.2.8
#define halInternalUartRxPump( port )
This function exists only in Buffer Mode on the EM2xx and in software UART (SOFTUART) mode on
the EM3xx. This function is called by emberSerialReadByte(). It is responsible for maintaining synchronization between the emSerialRxQueue and the UART DMA.
Parameters
port Serial port number (0 or 1).
Definition at line 437 of file hal/micro/serial.h.
6.26.3
Enumeration Type Documentation
EmberZNet 4.7.2 API EM250
120-3016-000-4720
212
6.26.3.1
enum SerialBaudRate
Assign numerical values for variables that hold Baud Rate parameters.
Enumerator:
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
Definition at line 269 of file hal/micro/serial.h.
6.26.3.2
enum NameOfType
Assign numerical values for the types of parity. Use for variables that hold Parity parameters.
Enumerator:
DEFINE_PARITY
DEFINE_PARITY
DEFINE_PARITY
Definition at line 309 of file hal/micro/serial.h.
6.26.4
Function Documentation
6.26.4.1 EmberStatus halInternalUartInit ( int8u port, SerialBaudRate rate, SerialParity parity, int8u
stopBits )
Initializes the UART to the given settings (same parameters as emberSerialInit() ).
Parameters
EmberZNet 4.7.2 API EM250
120-3016-000-4720
213
port
rate
parity
stopBits
Serial port number (0 or 1).
Baud rate (see SerialBaudRate).
Parity value (see SerialParity).
Number of stop bits.
Returns
An error code if initialization failed (such as invalid baud rate), otherise EMBER_SUCCESS.
6.26.4.2
void halInternalPowerDownUart ( void )
This function is typically called by ::halPowerDown() and it is responsible for performing all the work
internal to the UART needed to stop the UART before a sleep cycle.
6.26.4.3
void halInternalPowerUpUart ( void )
This function is typically called by ::halPowerUp() and it is responsible for performing all the work internal
to the UART needed to restart the UART after a sleep cycle.
6.26.4.4
void halInternalStartUartTx ( int8u port )
Called by serial code whenever anything is queued for transmission to start any interrupt-driven transmission. May be called when transmission is already in progess.
Parameters
port Serial port number (0 or 1).
6.26.4.5
void halInternalStopUartTx ( int8u port )
Called by serial code to stop any interrupt-driven serial transmission currently in progress.
Parameters
port Serial port number (0 or 1).
6.26.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 transmission. Should wait for anything currently in the UART hardware registers to finish transmission first, and
block until data is finished being sent.
Parameters
port Serial port number (0 or 1).
data Pointer to the data to be transmitted.
length The length of data to be transmitted
EmberZNet 4.7.2 API EM250
120-3016-000-4720
214
6.26.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.
Parameters
port Serial port number (0 or 1).
dataByte The byte to receive data into.
6.26.4.8
void halInternalWaitUartTxComplete ( int8u port )
Blocks until the UART has finished transmitting any data in its hardware registers.
Parameters
port Serial port number (0 or 1).
6.26.4.9
void halInternalRestartUart ( void )
This function is typically called by halInternalPowerUpBoard() and it is responsible for performing all the
work internal to the UART needed to restart the UART after a sleep cycle. (For example, resyncing the
DMA hardware and the serial FIFO.)
6.26.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 or
an XOFF. Returns TRUE is the host is able to send.
6.26.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 is
complete.
6.26.4.12 boolean halInternalUart1TxIsIdle ( void )
Returns true if the uart transmitter is idle, including the transmit shift register.
6.26.4.13
void emSerialBufferNextMessageIsr ( EmSerialBufferQueue ∗ q )
When new serial transmission is started and bufferQueue->nextByte is equal to NULL, this can be
called to set up nextByte and lastByte for the next message.
Parameters
q Pointer to the buffer queue structure for the port.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
215
6.26.4.14
void emSerialBufferNextBlockIsr ( EmSerialBufferQueue ∗ q, int8u port )
When a serial transmission is in progress and bufferQueue->nextByte has been sent and incremented leaving it equal to lastByte, this should be called to set up nextByte and lastByte for the next
block.
Parameters
q Pointer to the buffer queue structure for the port.
port Serial port number (0 or 1).
6.26.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 UART
data has been received over the debug channel.
Parameters
data Pointer to the the data received
length Length of the data received
EmberZNet 4.7.2 API EM250
120-3016-000-4720
216
6.27
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_INT }
• enum {
ADC_CONVERSION_TIME_US_32, ADC_CONVERSION_TIME_US_64, ADC_CONVERSION_TIME_US_128, ADC_CONVERSION_TIME_US_256,
ADC_CONVERSION_TIME_US_512, ADC_CONVERSION_TIME_US_1024, ADC_CONVERSION_TIME_US_2048, ADC_CONVERSION_TIME_US_4096 }
• enum {
ADC_SOURCE_ADC0_GND, ADC_SOURCE_ADC1_GND, ADC_SOURCE_ADC2_GND, ADC_SOURCE_ADC3_GND,
ADC_SOURCE_VDD_PADS_GND, ADC_SOURCE_VDD_GND, ADC_SOURCE_VGND, ADC_SOURCE_VREF,
ADC_SOURCE_ADC0_ADC1, ADC_SOURCE_ADC2_ADC3 }
Functions
• void halInternalInitAdc (void)
• void halInternalSleepAdc (void)
• EmberStatus halStartAdcConversion (ADCUser id, ADCReferenceType reference, ADCChannelType 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)
6.27.1
Detailed Description
Sample A/D converter driver.
See adc.h for source code.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
217
Note
EM35x ADC driver support is preliminary and essentailly untested - please do not attempt to use this
ADC 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 microcontroller is started. Call halInternalSleepAdc() to sleep the module and halInternalInitAdc() to wake up
the module.
A "user" is a separate thread of execution and usage. That is, internal Ember code is one user and clients
are 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 may
require.
Many functions in this file return an EmberStatus value. See error-def.h for definitions of all EmberStatus
return values.
6.27.2
Macro Definition Documentation
6.27.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.27.3
Typedef Documentation
6.27.3.1
typedef int8u ADCChannelType
A type for the channel enumeration.
Definition at line 73 of file adc.h.
6.27.3.2
typedef int8u ADCReferenceType
A type for the reference voltage enumeration.
Definition at line 77 of file adc.h.
6.27.3.3
typedef int8u ADCRateType
A type for the sample rate enumeration.
Definition at line 81 of file adc.h.
6.27.4
Enumeration Type Documentation
EmberZNet 4.7.2 API EM250
120-3016-000-4720
218
6.27.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.
See Also
NUM_ADC_USERS
Enumerator:
ADC_USER_LQI LQI User ID.
ADC_USER_APP Application User ID
ADC_USER_APP2 Application User ID
Definition at line 51 of file adc.h.
6.27.4.2
anonymous enum
ADCReferenceType enumeration. Note: EM2xx only supports one reference type: Internal.
Enumerator:
ADC_REF_INT Internal reference.
Definition at line 26 of file xap2b/adc.h.
6.27.4.3
anonymous enum
ADCRateType enumeration for the EM2xx.
Enumerator:
ADC_CONVERSION_TIME_US_32 Rate 32 us, 5 effective bits in ADC_DATA[15:11]
ADC_CONVERSION_TIME_US_64 Rate 64 us, 6 effective bits in ADC_DATA[15:10]
ADC_CONVERSION_TIME_US_128 Rate 128 us, 7 effective bits in ADC_DATA[15:9]
ADC_CONVERSION_TIME_US_256 Rate 256 us, 8 effective bits in ADC_DATA[15:8]
ADC_CONVERSION_TIME_US_512 Rate 512 us, 9 effective bits in ADC_DATA[15:7]
ADC_CONVERSION_TIME_US_1024 Rate 1024 us, 10 effective bits in ADC_DATA[15:6]
ADC_CONVERSION_TIME_US_2048 Rate 2048 us, 11 effective bits in ADC_DATA[15:5]
ADC_CONVERSION_TIME_US_4096 Rate 4096 us, 12 effective bits in ADC_DATA[15:4]
Definition at line 34 of file xap2b/adc.h.
6.27.4.4
anonymous enum
EM250 ADC channel values for ADCChannelType.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
219
Enumerator:
ADC_SOURCE_ADC0_GND Channel 0 : ADC0 on GPIO[4]
ADC_SOURCE_ADC1_GND Channel 1 : ADC1 on GPIO[5]
ADC_SOURCE_ADC2_GND Channel 2 : ADC2 on GPIO[6]
ADC_SOURCE_ADC3_GND Channel 3 : ADC3 on GPIO[7]
ADC_SOURCE_VDD_PADS_GND Channel 4 : Battery (VDD_PADS, 2.1-3.6V pad supply)
ADC_SOURCE_VDD_GND Channel 5 : Regulator (VDD, 1.8V core supply
ADC_SOURCE_VGND Channel 7 : VSS (0V)
ADC_SOURCE_VREF Channel 8 : VREF
ADC_SOURCE_ADC0_ADC1 Channel 9 : (Differential) ADC0-ADC1 on GPIO[4]-GPIO[5]
ADC_SOURCE_ADC2_ADC3 Channel 10: (Differential) ADC2-ADC3 on GPIO[6]-GPIO[7]
Definition at line 56 of file xap2b/adc.h.
6.27.5
Function Documentation
6.27.5.1
void halInternalInitAdc ( void )
Initializes and powers-up the ADC. Should also be called to wake from sleep. The ADC is required for
EM250 stack operation so this function must be called from halInit.
6.27.5.2
void halInternalSleepAdc ( void )
Shuts down the voltage reference and ADC system to minimize power consumption in sleep.
6.27.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 ADC
channel enum), and set rate to reflect the number of bits of accuracy desired (see the ADC rates
enum, fixed at ADC_CONVERSION_TIME_US_256 for the Atmega).
Parameters
id 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 channels
enum. For basic, single-ended Atmel channels, see the Atmega single-ended ADC
channels enum. For more complex measurements on Atmels (differential and amped
channel numbers), see the Atmel datasheet for your micro.
rate EM250 rate number (see the ADC EM250 rate enum). Fixed at ADC_CONVERSION_TIME_US_256 for AVR Atmega.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
220
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.27.5.4 EmberStatus halRequestAdcData ( ADCUser id, int16u ∗ value )
Returns the status of a pending conversion previously started by halStartAdcConversion(). If the conversion
is complete, writes the raw register value of the conversion (the unaltered value taken directly from the ADC’s data register) into value.
Parameters
id An ADC user.
value Pointer to an int16u to be loaded with the new value. Take note that the Atmel’s ADC
only generates 8-bit values which are loaded into the lower 8 bits of value.
Returns
One of the following:
• 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.27.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 value
of the conversion (the unaltered value taken directly from the ADC’s data register) into value and returns
EMBER_ADC_CONVERSION_DONE, or immediately returns EMBER_ADC_NO_CONVERSION_PENDING.
Parameters
id An ADC user.
value Pointer to an int16u to be loaded with the new value. Take note that the Atmel’s ADC
only generates 8-bit values which are loaded into the lower 8 bits of value.
Returns
One of the following:
• EMBER_ADC_CONVERSION_DONE if the conversion is complete.
• EMBER_ADC_NO_CONVERSION_PENDING if id does not have a pending conversion.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
221
6.27.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 does
not call this function, the first time (and only the first time) the function halConvertValueToVolts() is
called, this function is invoked. To maintain accurate volt calculations, the application should call this
whenever it expects the temperature of the micro to change.
Parameters
id An ADC user.
Returns
One of the following:
• EMBER_ADC_CONVERSION_DONE if the calibration is complete.
• EMBER_ERR_FATAL if the calibration failed.
6.27.5.7 int16s halConvertValueToVolts ( int16u value )
Convert the raw register value (the unaltered value taken directly from the ADC’s data register) into a
signed 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.
Parameters
value An int16u to be converted.
Returns
Volts as signed fixed point with units 10∧ -4 Volts.
6.27.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 is
not intended to be called from any function other than halInternalInitAdc(). This function ensures that
the master cell voltage and current bias values are calibrated before calibrating Vref.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
222
6.28
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
6.28.1
Detailed Description
Sample API functions for using push-buttons. See button.h for source code.
6.28.2
Macro Definition Documentation
6.28.2.1
#define BUTTON PRESSED
Button state is pressed.
Definition at line 24 of file button.h.
6.28.2.2
#define BUTTON RELEASED
Button state is released.
Definition at line 28 of file button.h.
6.28.3
Function Documentation
6.28.3.1
void halInternalInitButton ( void )
Initializes the buttons. This function is automatically called by ::halInit().
6.28.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 the
actual state of the pin.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
223
Parameters
button 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.28.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 the
buttons.
Parameters
button 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.28.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 executed
in response to changes of state in each of the buttons, or callbacks to the appropriate functionality.
Parameters
button 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_PRESSED if the button has been pressed or BUTTON_RELEASED if the button has been
released.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
224
6.29
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 EM250
120-3016-000-4720
225
6.29.1
Detailed Description
Sample API functions for playing tunes on a piezo buzzer. See buzzer.h for source code.
6.29.2
Macro Definition Documentation
6.29.2.1
#define NOTE C3
A note which can be used in tune structure definitions.
Definition at line 23 of file buzzer.h.
6.29.2.2
#define NOTE Db3
A note which can be used in tune structure definitions.
Definition at line 24 of file buzzer.h.
6.29.2.3
#define NOTE D3
A note which can be used in tune structure definitions.
Definition at line 25 of file buzzer.h.
6.29.2.4
#define NOTE Eb3
A note which can be used in tune structure definitions.
Definition at line 26 of file buzzer.h.
6.29.2.5
#define NOTE E3
A note which can be used in tune structure definitions.
Definition at line 27 of file buzzer.h.
6.29.2.6
#define NOTE F3
A note which can be used in tune structure definitions.
Definition at line 28 of file buzzer.h.
6.29.2.7
#define NOTE Gb3
A note which can be used in tune structure definitions.
Definition at line 29 of file buzzer.h.
6.29.2.8
#define NOTE G3
A note which can be used in tune structure definitions.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
226
Definition at line 30 of file buzzer.h.
6.29.2.9
#define NOTE Ab3
A note which can be used in tune structure definitions.
Definition at line 31 of file buzzer.h.
6.29.2.10
#define NOTE A3
A note which can be used in tune structure definitions.
Definition at line 32 of file buzzer.h.
6.29.2.11
#define NOTE Bb3
A note which can be used in tune structure definitions.
Definition at line 33 of file buzzer.h.
6.29.2.12
#define NOTE B3
A note which can be used in tune structure definitions.
Definition at line 34 of file buzzer.h.
6.29.2.13
#define NOTE C4
A note which can be used in tune structure definitions.
Definition at line 35 of file buzzer.h.
6.29.2.14
#define NOTE Db4
A note which can be used in tune structure definitions.
Definition at line 36 of file buzzer.h.
6.29.2.15
#define NOTE D4
A note which can be used in tune structure definitions.
Definition at line 37 of file buzzer.h.
6.29.2.16
#define NOTE Eb4
A note which can be used in tune structure definitions.
Definition at line 38 of file buzzer.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
227
6.29.2.17
#define NOTE E4
A note which can be used in tune structure definitions.
Definition at line 39 of file buzzer.h.
6.29.2.18
#define NOTE F4
A note which can be used in tune structure definitions.
Definition at line 40 of file buzzer.h.
6.29.2.19
#define NOTE Gb4
A note which can be used in tune structure definitions.
Definition at line 41 of file buzzer.h.
6.29.2.20
#define NOTE G4
A note which can be used in tune structure definitions.
Definition at line 42 of file buzzer.h.
6.29.2.21
#define NOTE Ab4
A note which can be used in tune structure definitions.
Definition at line 43 of file buzzer.h.
6.29.2.22
#define NOTE A4
A note which can be used in tune structure definitions.
Definition at line 44 of file buzzer.h.
6.29.2.23
#define NOTE Bb4
A note which can be used in tune structure definitions.
Definition at line 45 of file buzzer.h.
6.29.2.24
#define NOTE B4
A note which can be used in tune structure definitions.
Definition at line 46 of file buzzer.h.
6.29.2.25
#define NOTE C5
A note which can be used in tune structure definitions.
Definition at line 47 of file buzzer.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
228
6.29.2.26
#define NOTE Db5
A note which can be used in tune structure definitions.
Definition at line 48 of file buzzer.h.
6.29.2.27
#define NOTE D5
A note which can be used in tune structure definitions.
Definition at line 49 of file buzzer.h.
6.29.2.28
#define NOTE Eb5
A note which can be used in tune structure definitions.
Definition at line 50 of file buzzer.h.
6.29.2.29
#define NOTE E5
A note which can be used in tune structure definitions.
Definition at line 51 of file buzzer.h.
6.29.2.30
#define NOTE F5
A note which can be used in tune structure definitions.
Definition at line 52 of file buzzer.h.
6.29.2.31
#define NOTE Gb5
A note which can be used in tune structure definitions.
Definition at line 53 of file buzzer.h.
6.29.2.32
#define NOTE G5
A note which can be used in tune structure definitions.
Definition at line 54 of file buzzer.h.
6.29.2.33
#define NOTE Ab5
A note which can be used in tune structure definitions.
Definition at line 55 of file buzzer.h.
6.29.2.34
#define NOTE A5
A note which can be used in tune structure definitions.
Definition at line 56 of file buzzer.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
229
6.29.2.35
#define NOTE Bb5
A note which can be used in tune structure definitions.
Definition at line 57 of file buzzer.h.
#define NOTE B5
6.29.2.36
A note which can be used in tune structure definitions.
Definition at line 58 of file buzzer.h.
6.29.3
Function Documentation
6.29.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 the
tune is complete.
Parameters
tune A pointer to tune to play.
bkg Determines whether the tune plays in the background. If TRUE, tune plays in background; if FALSE, tune plays in foreground.
A tune is implemented as follows:
int8u PGM hereIamTune[] = {
NOTE_B4, 1,
0,
1,
NOTE_B5, 5,
0,
0
};
6.29.3.2
//All tunes are stored in flash.
//Plays the note B4 for 100 milliseconds.
//Pause for 100 milliseconds.
//Plays the note B5 for 500 milliseconds.
//NULL terminates the tune.
void halStackIndicatePresence ( void )
Causes something to happen on a node (such as playing a tune on the buzzer) that can be used to indicate
where it physically is.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
230
6.30
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)
6.30.1
Detailed Description
Sample API funtions for controlling LEDs. When specifying an LED to use, always use the BOARDLEDx
definitions that are defined within the BOARD_HEADER.
See led.h for source code.
6.30.2
Typedef Documentation
6.30.2.1
typedef enum HalBoardLedPins HalBoardLed
Ensures that the definitions from the BOARD_HEADER are always used as parameters to the LED functions.
Definition at line 30 of file led.h.
6.30.3
Function Documentation
6.30.3.1
void halInternalInitLed ( void )
Configures GPIOs pertaining to the control of LEDs.
6.30.3.2
void halToggleLed ( HalBoardLed led )
Atomically wraps an XOR or similar operation for a single GPIO pin attached to an LED.
Parameters
led Identifier (from BOARD_HEADER) for the LED to be toggled.
6.30.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 EM250
120-3016-000-4720
231
Parameters
led Identifier (from BOARD_HEADER) for the LED to turn on.
6.30.3.4
void halClearLed ( HalBoardLed led )
Turns off (clears) a GPIO pin connected to an LED, which turns off the LED.
Parameters
led Identifier (from BOARD_HEADER) for the LED to turn off.
6.30.3.5
void halStackIndicateActivity ( boolean turnOn )
Called by the stack to indicate activity over the radio (for both transmission and reception). It is called once
with turnOn TRUE and shortly thereafter with turnOn FALSE.
Typically does something interesting, such as change the state of an LED.
Parameters
turnOn See Usage.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
232
6.31
Flash Memory Control
Functions
•
•
•
•
void halInternalFlashInit (void)
EmberStatus halInternalFlashVerifyInit (void)
EmberStatus halInternalFlashPageErase (int8u pageSelect)
XAP2B_PAGEZERO_ON EmberStatus halInternalFlashBlockRead (int16u addr, int16u ∗data, int16u
length)
• XAP2B_PAGEZERO_OFF
XAP2B_PAGEZERO_ON EmberStatus halInternalFlashBlockWrite (int16u addr, int16u ∗data, int16s
length)
6.31.1
Detailed Description
Note
During an erase or a write the flash is not available, which means code will not be executable from
flash. Therefore, these routines copy their core functionality into RAM buffers for RAM execution.
Additonally, this also means all interrupts will be disabled.
Hardware documentation indicates 40us for a write and 21ms for an erase.
Bit map of the Window and Page register access into flash memory:
----------------------------------------------------------------------| 15 | 14 | 13 | 12 | 11 | 10 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
----------------------------------------------------------------------|
FLASH_PAGE (pageSelect)
| (in_page - smallest erasable unit)|
----------------------------------------------------------------------| FLASH_WINDOW |
(in_window - CODE mapped to DATA)
|
-----------------------------------------------------------------------
See flash.h for source code. All functions in flash.h return an EmberStatus value. See error-def.h for
definitions of all EmberStatus return values.
6.31.2
Function Documentation
6.31.2.1
void halInternalFlashInit ( void )
Initializes the flash code.
Page Erase and Block Write most both be executed from RAM. For this to occur, the code has to be copied
into RAM - halInternalFlashInit() triggers the copy. Additionally, there is a simple active flag that will
supress an erase or write if flash has not been initialized yet, preventing a potential crash.
6.31.2.2 EmberStatus halInternalFlashVerifyInit ( void )
Verify flash routines in RAM remain uncorrupted.
A paranoid application can use this to check if something has corrupted the flash routines copied into RAM. Returns EMBER_SUCCESS if all is well, EMBER_ERR_FLASH_VERIFY_FAILED if corruption
is detected. An application can then decide whether to crash and diagnose such corruption, or call halInternalFlashInit() again to eradicate the corruption and recover.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
233
6.31.2.3 EmberStatus halInternalFlashPageErase ( int8u pageSelect )
Erases a hardware page.
A hardware page is defined to be 0x0200 rows and each row is a word. The flash is addressed from 0x0000
to 0xFFFF meaning there 128 hardware pages of size 0x0200 each.
Parameters
pageSelect The page number to be erased. The top 7 bits of the address correspond to the hardware
page. This function expects pageSelect to be those top 7 bits shifted right so they
occupy the bottom 7 bits of the 8 bit pageSelect.
Returns
An EmberStatus value indicating the success or failure of the command.
6.31.2.4 XAP2B_PAGEZERO_ON EmberStatus halInternalFlashBlockRead ( int16u addr, int16u ∗
data, int16u length )
Reads a block of words from flash.
Parameters
addr The absolute address to begin reading from. The address is NOT a pointer. Due to the
CPU’s handling of pointers, words, and bytes, the address must be passed around and
worked with as a simple 16bit value. At the critical moments the flash routines will cast
the address to a pointer for the actual hardware access.
data A pointer to where the data being read should be placed.
length The number of words to read.
Returns
An EmberStatus value indicating the success or failure of the command.
6.31.2.5 XAP2B_PAGEZERO_OFF XAP2B_PAGEZERO_ON EmberStatus
halInternalFlashBlockWrite ( int16u addr, int16u ∗ data, int16s length )
Writes a block of words from flash.
A page is erased to 0xFFFF at every address. A write can only flip a bit from 1 to 0. Only two writes can
be performed at the same address between page erasures covering that address.
Parameters
addr The absolute address to begin writing at. The address is NOT a pointer. Due to the
CPU’s handling of pointers, words, and bytes, the address must be passed around and
worked with as a simple 16bit value. At the critical moments the flash routines will cast
the address to a pointer for the actual hardware access.
data A pointer to the data that should be written.
length The number of words to write.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
234
Returns
An EmberStatus value indicating the success or failure of the command.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
235
6.32
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)
6.32.1
Detailed Description
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 of
the SPI bus through chip selects and hold lines.
Some functions in this file return an EmberStatus value. See error-def.h for definitions of all EmberStatus
return values.
See also spi-protocol.h for source code.
For complete documentation of the SPI Protocol, refer to the EM260 Datasheet.
6.32.2
Function Documentation
6.32.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 EM250
120-3016-000-4720
236
6.32.2.2
void halCommonSpiWrite ( int8u data )
Writes a byte over the SPI.
Parameters
data The byte to be sent out over the SPI.
6.32.2.3 int8u halCommonSpiRead ( void )
Reads a byte over the SPI without changing the mode.
Returns
The byte read.
6.32.2.4 int8u halCommonSpiReadWrite ( int8u data )
Reads and writes a byte over the SPI.
Parameters
data The byte to be sent out over the SPI.
Returns
The byte read.
6.32.2.5
void halNcpSerialInit ( void )
Initializes the SPI Protocol.
6.32.2.6
void halNcpSerialPowerup ( void )
Reinitializes the SPI Protocol when coming out of sleep (powerdown).
6.32.2.7
void halNcpSerialPowerdown ( void )
Shuts down the SPI Protocol when entering sleep (powerdown).
6.32.2.8
EzspStatus halNcpHardReset ( void )
Forcefully resets the EM260 by pulling on the nRESET line; waits for the EM260 to boot; verifies that is
has booted; verifies the EM260 is active; verifies the SPI Protocol version. When this function returns, the
EM260 is ready to accept all commands.
This function is the same as halNcpHardResetReqBootload(), except that the EM260 cannot be told to
enter bootload mode through the nWAKE signal.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
237
Returns
A EzspStatus value indicating the success or failure of the command.
6.32.2.9
EzspStatus halNcpHardResetReqBootload ( boolean requestBootload )
Forcefully resets the EM260 by pulling on the nRESET line; sets the nWAKE signal based upon the state
of the requestBootload boolean; waits for the EM260 to boot; verifies that is has booted; verifies the EM260 is active; verifies the SPI Protocol version. When this function returns, the EM260 is ready to accept
all commands.
This function is the same as halNcpHardReset(), except that the ability to request the EM260 enter bootload
mode through the nWAKE signal is made available.
Returns
A EzspStatus value indicating the success or failure of the command.
6.32.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 Protocol calls halNcpIsAwakeIsr() once the wakeup handshaking is complete and the EM260 is ready to accept
commands.
6.32.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 an
EZSP Frame. If sending a command other than EZSP, use halNcpSendRawCommand(). This function
returns immediately after transmission of the Command has completed and the transaction has entered the
Wait section. The EZSP must now call halNcpPollForResponse() until the Response is received.
6.32.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 the
transaction. This function returns immediately after transmission of the Command has completed and the
transaction has entered the Wait section. The upper layer must now call halNcpPollForResponse() until the
the Response is received.
6.32.2.13
EzspStatus halNcpPollForResponse ( void )
After sending a Command with halNcpSendCommand(), the upper layer repeatedly calls this function until
the SPI Protocol has finished reception of a Response.
Returns
A EzspStatus value indicating the success or failure of the command.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
238
6.32.2.14
void halNcpIsAwakeIsr ( boolean isAwake )
The SPI Protocol calls halNcpIsAwakeIsr() once the wakeup handshaking is complete and the EM260 is
ready to accept a command.
Parameters
isAwake TRUE if the wake handshake completed and the EM260 is awake. FALSE is the wake
handshake failed and the EM260 is unresponsive.
6.32.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.32.2.16 boolean halNcpVerifySpiProtocolVersion ( void )
Transmits the SPI Protocol Version Command and checks the response against a literal value to verify the
SPI 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.32.2.17 boolean halNcpVerifySpiProtocolActive ( void )
Transmits the SPI Status Command and checks the response against a literal value to verify the SPI Protocol
is active.
Returns
TRUE if the SPI Protocol is active. FALSE if the SPI Protocol is not active.
6.32.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 any
test application or used as inspiration or a template for further testing. To invoke a test, simply call spipTest() with the desired parameters. (For example, this function can be accessed through a user driven
interface to provide a convenient method for invoking a test or set of tests.)
Parameters
test 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’ initiates
a transaction with whatever data is in buffer.
params The parameters passed into a given test. For example, test ’A’ simply write a byte on
the SPI. The byte written is provided by params.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
239
6.32.3
Variable Documentation
6.32.3.1 int8u∗ halNcpFrame
A pointer to the length byte at the start of the Payload. Upper layers will write the command to this location
before starting a transaction. The upper layer will read the response from this location after a transaction
completes. This pointer is the upper layers’ primary access into the command/response buffer.
6.32.3.2 int8u halNcpSpipErrorByte
This error byte is the third byte found in a special SPI Protocol error case. It provides more detail concerning the error. Refer to the EM260 Datasheet for a more detailed description of this byte. The application
does not need to work with this byte, but it can be useful information when developing.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
240
6.33
Symbol Timer Control
Symbol Timer Functions
• void halInternalStartSymbolTimer (void)
• void halInternalSfdCaptureIsr (void)
• int32u halStackGetInt32uSymbolTick (void)
MAC Timer Support Functions
These functions are used for MAC layer timing.
Applications should not directly call these functions. They are used internally by the operation of the stack.
•
•
•
•
void halStackOrderInt16uSymbolDelayA (int16u symbols)
void halStackOrderNextSymbolDelayA (int16u symbols)
void halStackCancelSymbolDelayA (void)
void halStackSymbolDelayAIsr (void)
6.33.1
Detailed Description
See symbol-timer.h for source code.
6.33.2
Function Documentation
6.33.2.1
void halInternalStartSymbolTimer ( void )
Initializes the symbol timer. This function is only implemented when a general purpose microcontroller
timer peripheral is used to implement the symbol timer (e.g. AVR/EM2420) When a dedicated symbol
timer peripheral exists (e.g. EM2xx, EM3xx) this initialization is performed directly by the PHY.
6.33.2.2
void halInternalSfdCaptureIsr ( void )
Should be called by the radio HAL whenever an SFD (Start Frame Delimiter) is detected.
6.33.2.3 int32u halStackGetInt32uSymbolTick ( void )
Returns the current symbol time in symbol ticks (16 microseconds).
Returns
The least significant 32 bits of the current symbol time in symbol ticks (16 microseconds).
6.33.2.4
void halStackOrderInt16uSymbolDelayA ( int16u symbols )
Sets up a timer and calls an interrupt-context callback when it expires.
Used by the MAC to request an interrupt callback at a specified amount of time in the future.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
241
Parameters
symbols The delay, in symbol ticks (16 microseconds).
6.33.2.5
void halStackOrderNextSymbolDelayA ( int16u symbols )
Sets up a timer and calls an interrupt-context callback when it expires.
Note
This is different from halStackOrderInt16uSymbolDelayA() in that it sets up the interrupt a specific
number of symbols after the last timer interrupt occurred, instead of from the time this function is
called.
Used by the MAC to request periodic timer based interrupts.
Parameters
symbols The delay, in symbol ticks (16 microseconds).
6.33.2.6
void halStackCancelSymbolDelayA ( void )
Cancels the timer set up by halStackOrderInt16uSymbolDelayA().
6.33.2.7
void halStackSymbolDelayAIsr ( void )
This is the interrupt level callback into the stack that is called when the timers set by halStackOrder∗SymbolDelayA expire.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
242
6.34
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)
6.34.1
Detailed Description
Functions that provide access to the system clock. A single system tick (as returned by halCommonGetInt16uMillisecondTick() 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 approximately
0.25 seconds.
The values used by the time support functions will wrap after an interval. The length of the interval depends
on the length of the tick and the number of bits in the value. However, there is no issue when comparing
time deltas of less than half this interval with a subtraction, if all data types are the same.
See system-timer.h for source code.
6.34.2
Macro Definition Documentation
6.34.2.1
#define halIdleForMilliseconds( duration )
Definition at line 203 of file system-timer.h.
6.34.3
Function Documentation
6.34.3.1 int16u halInternalStartSystemTimer ( void )
Initializes the system tick.
Returns
Time to update the async registers after RTC is started (units of 100 microseconds).
EmberZNet 4.7.2 API EM250
120-3016-000-4720
243
6.34.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.34.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.34.3.4 int16u halCommonGetInt16uQuarterSecondTick ( void )
Returns the current system time in quarter second ticks, as a 16-bit value.
EmberStack Usage:
Unused, implementation optional.
Returns
The least significant 16 bits of the current system time, in system ticks multiplied by 256.
6.34.3.5 EmberStatus halSleepForQuarterSeconds ( int32u ∗ duration )
Uses the system timer to enter ::SLEEPMODE_WAKETIMER for approximately the specified amount of
time (provided in quarter seconds).
This function returns EMBER_SUCCESS and the duration parameter is decremented to 0 after sleeping
for the specified amount of time. If an interrupt occurs that brings the chip out of sleep, the function returns
EMBER_SLEEP_INTERRUPTED and the duration parameter reports the amount of time remaining out
of the original request.
Note
This routine always enables interrupts.
The maximum sleep time of the hardware is limited on AVR-based platforms to 8 seconds, on EM2XX-based platforms to 64 seconds, and on EM35x platforms to 48.5 days. Any sleep duration greater
than this limit will wake up briefly (e.g. 16 microseconds) to reenable another sleep cycle.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
244
The EM2xx has a 16 bit sleep timer, which normally runs at 1024Hz. In order to support long sleep
durations, the chip will periodically wake up to manage a larger timer in software. This periodic wakeup
is normally triggered once every 32 seconds. However, this period can be extended to once every 2.275
hours by building with ENABLE_LONG_SLEEP_CYCLES defined. This definition enables the use
of a prescaler when sleeping for more than 63 seconds at a time. However, this define also imposes the
following 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 the
system timer.
EmberStack Usage:
Unused, implementation optional.
Parameters
duration The amount of time, expressed in quarter seconds, that the micro should be placed into
::SLEEPMODE_WAKETIMER. When the function returns, this parameter provides
the amount of time remaining out of the original sleep time request (normally the return
value will be 0).
Returns
An EmberStatus value indicating the success or failure of the command.
6.34.3.6 EmberStatus halSleepForMilliseconds ( int32u ∗ duration )
Uses the system timer to enter ::SLEEPMODE_WAKETIMER for approximately the specified amount of
time (provided in milliseconds). Note that since the system timer ticks at a rate of 1024Hz, a second is
comprised of 1024 milliseconds in this function.
This function returns EMBER_SUCCESS and the duration parameter is decremented to 0 after sleeping
for the specified amount of time. If an interrupt occurs that brings the chip out of sleep, the function returns
EMBER_SLEEP_INTERRUPTED and the duration parameter reports the amount of time remaining out
of 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 attempt
to sleep for less than 3 milliseconds on EM2XX-based platforms will cause the function to immediately
exit without sleeping and return EMBER_SLEEP_INTERRUPTED.
The maximum sleep time of the hardware is limited on EM2XX-based platforms to 32 seconds. Any
sleep duration greater than this limit will wake up briefly (e.g. 16 microseconds) to reenable another
sleep cycle. Due to this limitation, this function should not be used with durations within 3 milliseconds of a multiple 32 seconds. The short sleep cycle that results from such durations is not handled
reliably by the system timer on EM2XX-based platforms. If a sleep duration within 3 milliseconds of
a multiple of 32 seconds is desired, halSleepForQuarterSeconds should be used.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
245
EmberStack Usage:
Unused, implementation optional.
Parameters
duration The amount of time, expressed in milliseconds (1024 milliseconds = 1 second), that
the micro should be placed into ::SLEEPMODE_WAKETIMER. When the function
returns, this parameter provides the amount of time remaining out of the original sleep
time request (normally the return value will be 0).
Returns
An EmberStatus value indicating the success or failure of the command.
6.34.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 for
the specified amount of time. If an interrupt occurs that brings the chip out of idle, the function returns
EMBER_SLEEP_INTERRUPTED and the duration parameter reports the amount of time remaining out
of the original request.
Note
This routine always enables interrupts.
EmberStack Usage:
Unused, implementation optional.
Parameters
duration The amount of time, expressed in milliseconds, that the micro should be placed into
::SLEEPMODE_IDLE. When the function returns, this parameter provides the amount
of time remaining out of the original idle time request (normally the return value will
be 0).
Returns
An EmberStatus value indicating the success or failure of the command.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
246
6.35
Bootloading
Modules
• Stand-Alone Bootloader
• Application Bootloader
Common Bootloader Functions
•
•
•
•
•
•
•
•
•
int32u updateCrcNoTable (int32u accumulator, int8u data)
int32u calculateCrc32 (int32u previous, int8u ∗data, int16u length, boolean reset)
void serPutChar (int8u ch)
void serPutStr (char ∗str)
void serPutBuf (const int8u buf[ ], int8u size)
void serPutHex (int8u byte)
void serPutHexInt (int16u word)
void sc2I2cInit (void)
void sc2I2cIntInit (void)
6.35.1
Detailed Description
Stand-Alone Bootloader supports over-the-air bootloading and Application Bootloader loads an image
from remote storage.
See also bootloader-common.h for source code.
6.35.2
Function Documentation
6.35.2.1 int32u updateCrcNoTable ( int32u accumulator, int8u data )
calculate CRC
Parameters
accumulator stores CRC result for each iteration
data data to operate on
Returns
result
6.35.2.2 int32u calculateCrc32 ( int32u previous, int8u ∗ data, int16u length, boolean reset )
CRC-32 for image validation.
Parameters
previous
data
length
reset
EmberZNet 4.7.2 API EM250
previous calculation
data to operate on
length of data param
signal reset of calculation to start value
120-3016-000-4720
247
Returns
result
6.35.2.3
void serPutChar ( int8u ch )
Wait for transmit free then transmit character from SC1 UART. EM250 based.
Parameters
ch character to transmit
6.35.2.4
void serPutStr ( char ∗ str )
Transmit a string from SC1 UART. EM250 based.
Parameters
str string to transmit
6.35.2.5
void serPutBuf ( const int8u buf[ ], int8u size )
Transmit a buffer of characters from SC1 UART. EM250 based.
Parameters
buf buffer to transmit
size size of buffer to transmit
6.35.2.6
void serPutHex ( int8u byte )
Transmit a hex byte value from SC1 UART. EM250 based.
Parameters
byte hex value to transmit
6.35.2.7
void serPutHexInt ( int16u word )
Transmit a two byte hex value from SC1 UART. EM250 based.
Parameters
word two byte hex value to transmit
EmberZNet 4.7.2 API EM250
120-3016-000-4720
248
6.35.2.8
void sc2I2cInit ( void )
Initialize serial controller SC2 for 400kbps I2C operation.
6.35.2.9
void sc2I2cIntInit ( void )
Initialize serial controller SC2 for 400kbps I2C operation and turn on interrupts.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
249
6.36
Stand-Alone Bootloader
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)
6.36.1
Detailed Description
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.36.2
Macro Definition Documentation
6.36.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.36.2.2
#define STANDALONE BOOTLOADER NORMAL MODE
Define a numerical value for the normal bootloader mode.
Definition at line 37 of file bootloader-interface-standalone.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
250
6.36.2.3
#define STANDALONE BOOTLOADER RECOVERY MODE
Define a numerical value for the recovery bootloader mode.
Definition at line 41 of file bootloader-interface-standalone.h.
6.36.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.36.2.5
#define halBootloadAppStart( space, segment, ramPtr )
Trap for accessing bootloadAppStart()
Parameters
space 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 flash
address 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 application
bootloader API is not installed. EMBER_SUCCESS if the segment is written.
Definition at line 127 of file bootloader-interface-standalone-v1.h.
6.36.2.6
#define halBootloadAdjustFlash( space, segment, ramPtr )
Trap for accessing halInternalAdjustFlashBlock()
Parameters
space 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 flash
address 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 application
bootloader API is not installed. EMBER_SUCCESS if the segment is written.
Definition at line 167 of file bootloader-interface-standalone-v1.h.
6.36.3
Enumeration Type Documentation
EmberZNet 4.7.2 API EM250
120-3016-000-4720
251
6.36.3.1
anonymous enum
Enumerator:
BOOTLOADER_MODE_MENU
BOOTLOADER_MODE_PASSTHROUGH
BOOTLOADER_MODE_CLONE
BOOTLOADER_MODE_CLONE_RECOVERY
BOOTLOADER_MODE_PASSTHROUGH_RECOVERY
Definition at line 182 of file bootloader-interface-standalone-v1.h.
6.36.4
Function Documentation
6.36.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 of
the installed standalone bootloader.
6.36.4.2 EmberStatus halLaunchStandaloneBootloader ( int8u mode )
Quits the current application and launches the standalone bootloader (if installed). The function returns an
error if the standalone bootloader is not present.
Parameters
mode 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 overthe-air image transfer on the current channel with current power settings.
• STANDALONE_BOOTLOADER_RECOVERY_MODE Will listen for an overthe-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.36.4.3 EmberStatus halInternalStandaloneBootloaderTrap ( int16u assumedBootloaderType, int8u
trapNumber, ... )
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 normal
circumstances because they improve readability and automatically check for bootloader type.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
252
Parameters
assumedBootloaderType
trapNumber
...
There are different traps for the stand-alone and application bootloaders. This guards
against calling a trap from the wrong bootloader type.
Trap identifier.
Parameter list corresponding to the trap.
Returns
An error if the trap identifier is invalid, or EMBER_SUCCESS.
6.36.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 pages
will remain unchanged other than having been erased and rewritten.
Parameters
dst 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.36.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-air
mode (usually the serial port). The function returns an error if the stand-alone bootloader is not present.
Parameters
mode 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 XMODEM, either to the current node or via single hop over the air passthrough mode.
• BOOTLOADER_MODE_PASSTHROUGH_RECOVERY: Special mode to allow uploading an image over the air to a node that has been lost as a result of an
unsuccessful bootload.
• BOOTLOADER_MODE_CLONE: Upload the current node image to the new
node.
• BOOTLOADER_MODE_CLONE_RECOVERY: Special mode to allow cloning
of the current node’s image to a node that has been lost as a result of an unsuccessful bootload.
eui64 For BOOTLOADER_MODE_CLONE and BOOTLOADER_MODE_MENU, this parameter specifies the EUI64 of the other node for single hop over the air bootloading.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
253
Returns
An error if the stand-alone bootloader is not present, or EMBER_SUCCESS.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
254
6.37
Application Bootloader
Macros
• #define BOOTLOADER_SEGMENT_SIZE_LOG2
• #define BOOTLOADER_SEGMENT_SIZE
• #define BL_IMAGE_IS_VALID_CONTINUE
Functions
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
int8u halAppBootloaderInit (void)
const HalEepromInformationType ∗ halAppBootloaderInfo (void)
void halAppBootloaderShutdown (void)
void halAppBootloaderImageIsValidReset (void)
int16u halAppBootloaderImageIsValid (void)
EmberStatus halAppBootloaderInstallNewImage (void)
int8u halAppBootloaderWriteRawStorage (int32u address, const int8u ∗data, int16u len)
int8u halAppBootloaderReadRawStorage (int32u address, int8u ∗data, int16u len)
int8u halAppBootloaderEraseRawStorage (int32u address, int32u len)
boolean halAppBootloaderStorageBusy (void)
int8u halAppBootloaderReadDownloadSpace (int16u pageToBeRead, int8u ∗destRamBuffer)
int8u halAppBootloaderWriteDownloadSpace (int16u pageToBeWritten, int8u ∗RamPtr)
int8u halAppBootloaderGetImageData (int32u ∗timestamp, int8u ∗userData)
int16u halAppBootloaderGetVersion (void)
int16u halAppBootloaderGetRecoveryVersion (void)
6.37.1
Detailed Description
Defiunition of the application 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-app.h for source code.
6.37.2
Macro Definition Documentation
6.37.2.1
#define BOOTLOADER SEGMENT SIZE LOG2
This is the working unit of data for the app bootloader. We want it as big as possible, but it must be a factor
of the NVM page size and fit into a single Zigbee packet. We choose 2∧ 6 = 64 bytes.
Definition at line 27 of file bootloader-interface-app.h.
6.37.2.2
#define BOOTLOADER SEGMENT SIZE
This is the working unit of data for the app bootloader. We want it as big as possible, but it must be a factor
of the NVM page size and fit into a single Zigbee packet. We choose 2∧ 6 = 64 bytes.
Definition at line 32 of file bootloader-interface-app.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
255
6.37.2.3
#define BL IMAGE IS VALID CONTINUE
Define a numerical value for checking image validity when calling the image interface functions.
Definition at line 65 of file bootloader-interface-app.h.
6.37.3
Function Documentation
6.37.3.1 int8u halAppBootloaderInit ( void )
Call this function as part of your application initialization to ensure the storage mechanism is ready to use.
Note: some earlier drivers may assert instead of returning an error if initialization fails.
Returns
::EEPROM_SUCCESS or ::EEPROM_ERR_INVALID_CHIP
6.37.3.2
const HalEepromInformationType∗ halAppBootloaderInfo ( void )
Call this function to get information about the attached storage device and its capabilities.
Returns
A pointer to a HalEepromInformationType data structure, or NULL if the driver does not support this
API
6.37.3.3
void halAppBootloaderShutdown ( void )
Call this function when you are done accessing the storage mechanism to ensure that it is returned to its
lowest power state.
6.37.3.4
void halAppBootloaderImageIsValidReset ( void )
Call this function once before checking for a valid image to reset the call flag.
6.37.3.5 int16u halAppBootloaderImageIsValid ( void )
Reads the app image out of storage, calculates the total file CRC to verify the image is intact.
Caller should loop calling this function while it returns BL_IMAGE_IS_VALID_CONTINUE to get final
result. This allows caller to service system needs during validation.
Call halAppBootloaderImageIsValidReset() before calling halAppBootloaderImageIsValid() to reset the
call flag.
Here is an example application call:
halAppBootloaderImageIsValidReset();
while ( (pages = halAppBootloaderImageIsValid() )
== BL_IMAGE_IS_VALID_CONTINUE) {
// make app specific calls here, if any
emberTick();
}
EmberZNet 4.7.2 API EM250
120-3016-000-4720
256
Returns
One of the following:
• Number of pages in a valid image
• 0 for an invalid image
• BL_IMAGE_IS_VALID_CONTINUE (-1) to continue to iterate for the final result.
6.37.3.6 EmberStatus halAppBootloaderInstallNewImage ( void )
Invokes the bootloader to install the application in storage. This function resets the device to start the
bootloader code and does not return!
6.37.3.7 int8u halAppBootloaderWriteRawStorage ( int32u address, const int8u ∗ data, int16u len )
Writes data to the specified raw storage address and length without being restricted to any page size Note: Not all storage implementations support accesses that are not page aligned, refer to the HalEepromInformationType structure for more information. Note: Some storage devices require contents to be erased
before new data can be written, and will return an ::EEPROM_ERR_ERASE_REQUIRED error if write is
called on a location that is not already erased. Refer to the HalEepromInformationType structure to see if
the attached storage device requires erasing.
Parameters
address Address to start writing data
data A pointer to the buffer of data to write.
len Length of the data to write
Returns
::EEPROM_SUCCESS or ::EEPROM_ERR.
6.37.3.8 int8u halAppBootloaderReadRawStorage ( int32u address, int8u ∗ data, int16u len )
Reads data from the specified raw storage address and length without being restricted to any page size
Note: Not all storage implementations support accesses that are not page aligned, refer to the HalEepromInformationType structure for more information.
Parameters
address Address from which to start reading data
data A pointer to a buffer where data should be read into
len Length of the data to read
Returns
::EEPROM_SUCCESS or ::EEPROM_ERR.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
257
6.37.3.9 int8u halAppBootloaderEraseRawStorage ( int32u address, int32u len )
Erases the specified region of the storage device. Note: Most devices require the specified region to be
page aligned, and will return an error if an unaligned region is specified. Note: Many devices take an
extremely long time to perform an erase operation. When erasing a large region, it may be preferable to
make multiple calls to this API so that other application functionality can be performed while the erase is in
progress. The halAppBootloaderStorageBusy() API may be used to determine when the last erase operation
has completed. Erase timing information can be found in the HalEepromInformationType structure.
Parameters
address Address to start erasing
len Length of the region to be erased
Returns
::EEPROM_SUCCESS or ::EEPROM_ERR.
6.37.3.10 boolean halAppBootloaderStorageBusy ( void )
Determine if the attached storage device is still busy performing the last operation, such as a write or an
erase.
Returns
::TRUE if still busy or ::FALSE if not.
6.37.3.11 int8u halAppBootloaderReadDownloadSpace ( int16u pageToBeRead, int8u ∗ destRamBuffer )
Converts pageToBeRead to an address and the calls storage read function. Note: This function is deprecated. It has been replaced by halAppBootloaderReadRawStorage()
Parameters
pageToBeRead pass in the page to be read. This will be converted to the appropriate address. Pages are
::EEPROM_PAGE_SIZE long.
destRamBuffer a pointer to the buffer to write to.
Returns
::EEPROM_SUCCESS or ::EEPROM_ERR.
6.37.3.12 int8u halAppBootloaderWriteDownloadSpace ( int16u pageToBeWritten, int8u ∗ RamPtr )
Converts pageToBeWritten to an address and calls the storage write function. Note: This function is
deprecated. It has been replaced by halAppBootloaderWriteRawStorage()
Parameters
pageToBe- pass in the page to be written. This will be converted to the appropriate address. Pages
Written are ::EEPROM_PAGE_SIZE long.
RamPtr a pointer to the data to be written.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
258
Returns
::EEPROM_SUCCESS or ::EEPROM_ERR
6.37.3.13 int8u halAppBootloaderGetImageData ( int32u ∗ timestamp, int8u ∗ userData )
Read the application image data from storage.
Parameters
timestamp write the image timestamp to this data pointer.
userData write the user data field to this buffer.
Returns
::EEPROM_SUCCESS or ::EEPROM_ERR
6.37.3.14 int16u halAppBootloaderGetVersion ( void )
Returns the application bootloader version.
6.37.3.15 int16u halAppBootloaderGetRecoveryVersion ( void )
Returns the recovery image version.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
259
6.38
HAL Configuration
Modules
• Sample Breakout Board Configuration
• MCC PLATFORM_HEADER Configuration
6.38.1
Detailed Description
EmberZNet 4.7.2 API EM250
120-3016-000-4720
260
6.39
Sample Breakout Board Configuration
Custom Baud Rate Definitions
The following define is used when defining a custom baud rate for the UART. This define provides a simple
hook into the definition of the baud rates used with the UART. The baudSettings[] array in uart.c links the
BAUD_∗ defines with the actual register values needed for operating the UART. The array baudSettings[]
can be edited directly for a custom baud rate or another entry (the register settings) can be provided here
with this define.
• #define EMBER_SERIAL_BAUD_CUSTOM
LED Definitions
The following are used to aid in the abstraction with the LED connections. The microcontroller-specific
sources use these definitions so they are able to work across a variety of boards which could have different
connections. The names and ports/pins used below are intended to match with a schematic of the system
to provide the abstraction.
The HalBoardLedPins enum values should always be used when manipulating the state of LEDs, as they
directly refer to the GPIOs to which the LEDs are connected.
Note
• LEDs 0 and 1 are on the RCM.
• LEDs 2 and 3 are on the breakout board (dev0455).
• enum HalBoardLedPins {
BOARDLED0, BOARDLED1, BOARDLED2, BOARDLED3,
BOARD_ACTIVITY_LED, BOARD_HEARTBEAT_LED, BOARDLED0, BOARDLED1,
BOARDLED2, BOARDLED3, BOARD_ACTIVITY_LED, BOARD_HEARTBEAT_LED }
• #define BOARDLED_MASK
Button Definitions
The following are used to aid in the abstraction with the Button connections. The microcontroller-specific
sources use these definitions so they are able to work across a variety of boards which could have different
connections. The names and ports/pins used 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 the
GPIOs to which the buttons are connected.
Note
The GPIO number must match the IRQ letter
•
•
•
•
•
#define BUTTON0
#define BUTTON0_INTCFG
#define BUTTON0_FLT_BIT
#define BUTTON0_MOD_BITS
#define BUTTON0_INT_BIT
EmberZNet 4.7.2 API EM250
120-3016-000-4720
261
•
•
•
•
•
#define BUTTON1
#define BUTTON1_INTCFG
#define BUTTON1_FLT_BIT
#define BUTTON1_MOD_BITS
#define BUTTON1_INT_BIT
UART Protocol Connection Items
The following are used to aid in the abstraction with the EZSP-UART Protocol. The HAL uses these
definitions so it is able to work across a variety of boards which could have different connections. The
names and ports/pins used below are intended to match with a schematic of the system to provide the
abstraction.
•
•
•
•
#define SC1_TXD
#define SC1_RXD
#define SC1_nCTS
#define SC1_nRTS
Temperature sensor ADC channel
Define the analog input channel connected to the LM-20 temperature sensor. The scale factor compensates
for different platform input ranges. GPIO6/ADC2 must be an analog input. GPIO7 must be an output and
set to a high level to power the sensor.
• #define TEMP_SENSOR_ADC_CHANNEL
• #define TEMP_SENSOR_SCALE_FACTOR
Packet Trace
When PACKET_TRACE is defined, ::GPIO_CFG will automatically be setup by halInit() to enable Packet
Trace support on GPIO Pins 4 and 5, in addition to the configuration specified below.
Note
This define will override any settings for GPIO 4 and 5.
• #define PACKET_TRACE
ENABLE OSC32K
When ENABLE_OSC32K is defined, halInit() will configure system timekeeping to utilize the external
32.768 kHz crystal oscillator rather than the internal 1 kHz RC oscillator.
On initial powerup the 32.768 kHz crystal oscillator will take a little while to start stable oscillation. This
only happens on initial powerup, not on wake-from-sleep, since the crystal usually stays running in deep
sleep mode.
When ENABLE_OSC32K is defined the crystal oscillator is started as part of halInit(). After the crystal
is started we delay for OSC32K_STARTUP_DELAY_MS (time in milliseconds). This delay allows the
crystal oscillator to stabilize before we start using it for system timing.
If you set OSC32K_STARTUP_DELAY_MS to less than the crystal’s startup time:
EmberZNet 4.7.2 API EM250
120-3016-000-4720
262
• The system timer won’t produce a reliable one millisecond tick before the crystal is stable.
• You may see some number of ticks of unknown period occur before the crystal is stable.
• halInit() will complete and application code will begin running, but any events based on the system
timer will not be accurate until the crystal is stable.
• An unstable system timer will only affect the APIs in system-timer.h.
Typical 32.768 kHz crystals measured by Ember take about 400 milliseconds to stabilize. Be sure to
characterize your particular crystal’s stabilization time since crystal behavior can vary.
• #define OSC32K_STARTUP_DELAY_MS
GPIO Configuration Definitions
This define does not equate to anything. It is used as a trigger to disable bias adjustment of the 24 MHz
crystal oscillator on the RCM (0452) plugged into the Breakout board (dev0455). Default is to enable bias
adjustment.
The following are used to specify the GPIO configuration to establish when Powered (POWERUP_), and
when Deep Sleeping (POWERDN_). The reason for separate Deep Sleep settings is to allow for a slightly
different configuration that minimizes power consumption during Deep Sleep. For example, inputs that
might float could be pulled up or down, and output states chosen with care, e.g. to turn off LEDs or other
devices that might consume power or be unnecessary when Deep Sleeping.
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
#define GPIO(n)
#define POWERUP_GPIO_DBG
#define POWERUP_GPIO_CFG
#define POWERUP_GPIO_DIRH
#define POWERUP_GPIO_DIRL
#define POWERUP_GPIO_CLRH
#define POWERUP_GPIO_CLRL
#define POWERUP_GPIO_SETH
#define POWERUP_GPIO_SETL
#define POWERUP_GPIO_PUH
#define POWERUP_GPIO_PUL
#define POWERUP_GPIO_PDH
#define POWERUP_GPIO_PDL
#define POWERDN_GPIO_DBG
#define POWERDN_GPIO_CFG
#define POWERDN_GPIO_DIRH
#define POWERDN_GPIO_DIRL
#define POWERDN_GPIO_CLRH
#define POWERDN_GPIO_CLRL
#define POWERDN_GPIO_SETH
#define POWERDN_GPIO_SETL
#define POWERDN_GPIO_PUH
#define POWERDN_GPIO_PUL
#define POWERDN_GPIO_PDH
#define POWERDN_GPIO_PDL
#define WAKE_ON_GPIO0
EmberZNet 4.7.2 API EM250
120-3016-000-4720
263
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
#define WAKE_ON_GPIO1
#define WAKE_ON_GPIO2
#define WAKE_ON_GPIO3
#define WAKE_ON_GPIO4
#define WAKE_ON_GPIO5
#define WAKE_ON_GPIO6
#define WAKE_ON_GPIO7
#define WAKE_ON_GPIO8
#define WAKE_ON_GPIO9
#define WAKE_ON_GPIO10
#define WAKE_ON_GPIO11
#define WAKE_ON_GPIO12
#define WAKE_ON_GPIO13
#define WAKE_ON_GPIO14
#define WAKE_ON_GPIO15
#define WAKE_ON_GPIO16
Board Specific Functions
The following macros exist to aid in the initialization, power up from sleep, and power down to sleep
operations. These macros are responsible for either initializing directly, or calling initialization functions
for 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()
6.39.1
Detailed Description
Functions and definitions specific to the breakout board. The file dev0455.h is the default BOARD_HEADER file used with the breakout board of the development kit.
See also dev0455i2c.h.
6.39.2
Macro Definition Documentation
6.39.2.1
#define EMBER SERIAL BAUD CUSTOM
Description:
This define is the register setting for generating a baud of
1. Refer to the EM250 datasheet’s discussion on UART baud rates for the equation used to derive
this value.
Definition at line 39 of file dev0455.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
264
6.39.2.2
#define BOARDLED MASK
This mask indicates which GPIO the LEDs are connected to. A bit is set for each GPIO to which an LED
is connected.
Definition at line 80 of file dev0455.h.
6.39.2.3
#define BUTTON0
The actual GPIO the BUTTON0 is connected to. This define should be used whenever referencing BUTTON0.
Definition at line 105 of file dev0455.h.
6.39.2.4
#define BUTTON0 INTCFG
The interrupt configuration register for BUTTON0.
Definition at line 109 of file dev0455.h.
6.39.2.5
#define BUTTON0 FLT BIT
The filter bit for BUTTON0.
Definition at line 113 of file dev0455.h.
6.39.2.6
#define BUTTON0 MOD BITS
The interrupt trigger selection for BUTTON0.
Definition at line 117 of file dev0455.h.
6.39.2.7
#define BUTTON0 INT BIT
The interrupt bit for BUTTON0.
Definition at line 121 of file dev0455.h.
6.39.2.8
#define BUTTON1
The actual GPIO the BUTTON1 is connected to. This define should be used whenever referencing BUTTON1.
Definition at line 127 of file dev0455.h.
6.39.2.9
#define BUTTON1 INTCFG
The interrupt configuration register for BUTTON1.
Definition at line 131 of file dev0455.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
265
6.39.2.10
#define BUTTON1 FLT BIT
The filter bit for BUTTON1.
Definition at line 135 of file dev0455.h.
6.39.2.11
#define BUTTON1 MOD BITS
The interrupt trigger selection for BUTTON1.
Definition at line 139 of file dev0455.h.
6.39.2.12
#define BUTTON1 INT BIT
The interrupt bit for BUTTON1.
Definition at line 143 of file dev0455.h.
6.39.2.13
#define SC1 TXD
Definition at line 156 of file dev0455.h.
6.39.2.14
#define SC1 RXD
Definition at line 157 of file dev0455.h.
6.39.2.15
#define SC1 nCTS
Definition at line 158 of file dev0455.h.
6.39.2.16
#define SC1 nRTS
Definition at line 159 of file dev0455.h.
6.39.2.17
#define TEMP SENSOR ADC CHANNEL
Definition at line 171 of file dev0455.h.
6.39.2.18
#define TEMP SENSOR SCALE FACTOR
Definition at line 172 of file dev0455.h.
6.39.2.19
#define PACKET TRACE
This define does not equate to anything. It is used as a trigger to enable Packet Trace support on the
breakout board (dev0455).
Definition at line 190 of file dev0455.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
266
6.39.2.20
#define OSC32K STARTUP DELAY MS
Definition at line 226 of file dev0455.h.
6.39.2.21
#define GPIO( n )
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 313 of file dev0455.h.
6.39.2.22
#define POWERUP GPIO DBG
Powered setting of GPIO_DBG debug configuration register.
Definition at line 318 of file dev0455.h.
6.39.2.23
#define POWERUP GPIO CFG
Powered setting of GPIO_CFG configuration register.
EMBER_SERIAL1_RTSCTS
Definition at line 330 of file dev0455.h.
6.39.2.24
#define POWERUP GPIO DIRH
Powered setting of GPIO_DIRH GPIO16 output-enable register.
Definition at line 338 of file dev0455.h.
6.39.2.25
#define POWERUP GPIO DIRL
Powered setting of GPIO_DIRL GPIO15..0 output-enable register.
Definition at line 346 of file dev0455.h.
6.39.2.26
#define POWERUP GPIO CLRH
Powered setting of ::GPIO_CLRH clear GPIO16 output register.
Definition at line 352 of file dev0455.h.
6.39.2.27
#define POWERUP GPIO CLRL
Powered setting of ::GPIO_CLRL clear GPIO15..0 outputs register.
Definition at line 356 of file dev0455.h.
6.39.2.28
#define POWERUP GPIO SETH
Powered setting of ::GPIO_SETH set GPIO16 output register.
Definition at line 360 of file dev0455.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
267
6.39.2.29
#define POWERUP GPIO SETL
Powered setting of ::GPIO_SETL set GPIO15..0 outputs register.
Definition at line 368 of file dev0455.h.
6.39.2.30
#define POWERUP GPIO PUH
Powered setting of ::GPIO_PUH GPIO16 pullup resistor enable register.
Definition at line 375 of file dev0455.h.
6.39.2.31
#define POWERUP GPIO PUL
Powered setting of ::GPIO_PUL GPIO15..0 pullup resistors enable register.
Definition at line 383 of file dev0455.h.
6.39.2.32
#define POWERUP GPIO PDH
Powered setting of ::GPIO_PDH GPIO16 pulldown resistor enable register.
Definition at line 390 of file dev0455.h.
6.39.2.33
#define POWERUP GPIO PDL
Powered setting of GPIO_PDL GPIO15..0 pulldown resistors enable register.
Definition at line 398 of file dev0455.h.
6.39.2.34
#define POWERDN GPIO DBG
Deep Sleep setting of ::GPIO_DBG debug configuration register.
Definition at line 404 of file dev0455.h.
6.39.2.35
#define POWERDN GPIO CFG
Deep Sleep setting of ::GPIO_CFG configuration register.
Definition at line 408 of file dev0455.h.
6.39.2.36
#define POWERDN GPIO DIRH
Deep Sleep setting of ::GPIO_DIRH GPIO16 output-enable register.
Definition at line 413 of file dev0455.h.
6.39.2.37
#define POWERDN GPIO DIRL
Deep Sleep setting of ::GPIO_DIRL GPIO15..0 output-enable register.
Definition at line 417 of file dev0455.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
268
6.39.2.38
#define POWERDN GPIO CLRH
Deep Sleep setting of ::GPIO_CLRH clear GPIO16 output register.
Definition at line 421 of file dev0455.h.
6.39.2.39
#define POWERDN GPIO CLRL
Deep Sleep setting of ::GPIO_CLRL clear GPIO15..0 outputs register.
Definition at line 425 of file dev0455.h.
6.39.2.40
#define POWERDN GPIO SETH
Deep Sleep setting of ::GPIO_SETH set GPIO16 output register.
Definition at line 429 of file dev0455.h.
6.39.2.41
#define POWERDN GPIO SETL
Deep Sleep setting of ::GPIO_SETL set GPIO15..0 outputs register.
Definition at line 433 of file dev0455.h.
6.39.2.42
#define POWERDN GPIO PUH
Deep Sleep setting of ::GPIO_PUH GPIO16 pullup resistor enable register.
Definition at line 438 of file dev0455.h.
6.39.2.43
#define POWERDN GPIO PUL
Deep Sleep setting of ::GPIO_PUL GPIO15..0 pullup resistors enable register.
Definition at line 444 of file dev0455.h.
6.39.2.44
#define POWERDN GPIO PDH
Deep Sleep setting of ::GPIO_PDH GPIO16 pulldown resistor enable register.
Definition at line 463 of file dev0455.h.
6.39.2.45
#define POWERDN GPIO PDL
Deep Sleep setting of ::GPIO_PDL GPIO15..0 pulldown resistors enable register.
Definition at line 469 of file dev0455.h.
6.39.2.46
#define WAKE ON GPIO0
A convenient define that chooses if this external signal can be used as source to wake from deep sleep. Any
change in the state of the signal will wake up the CPU.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
269
Definition at line 486 of file dev0455.h.
6.39.2.47
#define WAKE ON GPIO1
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 487 of file dev0455.h.
6.39.2.48
#define WAKE ON GPIO2
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 488 of file dev0455.h.
6.39.2.49
#define WAKE ON GPIO3
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 489 of file dev0455.h.
6.39.2.50
#define WAKE ON GPIO4
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 490 of file dev0455.h.
6.39.2.51
#define WAKE ON GPIO5
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 491 of file dev0455.h.
6.39.2.52
#define WAKE ON GPIO6
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 492 of file dev0455.h.
6.39.2.53
#define WAKE ON GPIO7
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 493 of file dev0455.h.
6.39.2.54
#define WAKE ON GPIO8
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 494 of file dev0455.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
270
6.39.2.55
#define WAKE ON GPIO9
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 495 of file dev0455.h.
6.39.2.56
#define WAKE ON GPIO10
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 496 of file dev0455.h.
6.39.2.57
#define WAKE ON GPIO11
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 497 of file dev0455.h.
6.39.2.58
#define WAKE ON GPIO12
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 498 of file dev0455.h.
6.39.2.59
#define WAKE ON GPIO13
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 499 of file dev0455.h.
6.39.2.60
#define WAKE ON GPIO14
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 500 of file dev0455.h.
6.39.2.61
#define WAKE ON GPIO15
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 501 of file dev0455.h.
6.39.2.62
#define WAKE ON GPIO16
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 502 of file dev0455.h.
6.39.2.63
#define halInternalInitBoard( )
Initialize the board. This function is called from ::halInit().
Definition at line 522 of file dev0455.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
271
6.39.2.64
#define halInternalPowerDownBoard( )
Power down the board. This macro is called from ::halPowerDown().
Definition at line 538 of file dev0455.h.
6.39.2.65
#define halInternalPowerUpBoard( )
Power up the board. This macro is called from ::halPowerUp().
Definition at line 560 of file dev0455.h.
6.39.3
Enumeration Type Documentation
6.39.3.1
enum HalBoardLedPins
Assign each GPIO with an LED connected to a convenient name. BOARD_ACTIVITY_LED and BOARD_HEARTBEAT_LED provide a further layer of abstraction ontop of the 4 LEDs for verbose coding.
Enumerator:
BOARDLED0
BOARDLED1
BOARDLED2
BOARDLED3
BOARD_ACTIVITY_LED
BOARD_HEARTBEAT_LED
BOARDLED0
BOARDLED1
BOARDLED2
BOARDLED3
BOARD_ACTIVITY_LED
BOARD_HEARTBEAT_LED
Definition at line 68 of file dev0455.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
272
6.40
MCC PLATFORM HEADER Configuration
Macros
•
•
•
•
•
•
•
•
•
•
•
•
#define _HAL_USING_XAP2B_PRAGMAS_
#define XAP2B_PAGEZERO_ON
#define XAP2B_PAGEZERO_OFF
#define _HAL_USE_COMMON_PGM_
#define BIGENDIAN_CPU
#define NO_STRIPPING
#define EEPROM
#define __SOURCEFILE__
#define assert(condition)
#define __delay_cycles(x)
#define DEBUG_LEVEL
#define halResetWatchdog()
Functions
• XAP2B_PAGEZERO_ON void halInternalAssertFailed (const char ∗filename, int linenumber)
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
Global Interrupt Manipulation Macros
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
#define START_ATOMIC_CLOCK()
#define STOP_ATOMIC_CLOCK()
#define DECLARE_INTERRUPT_STATE
#define DECLARE_INTERRUPT_STATE_LITE
#define DISABLE_INTERRUPTS()
#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()
EmberZNet 4.7.2 API EM250
120-3016-000-4720
273
Miscellaneous Macros
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
unsigned int __udivx2 (unsigned long a, unsigned int b)
int __divx2 (long a, int b)
unsigned int __uremx2 (unsigned long a, unsigned int b)
int __remx2 (long a, int b)
#define MAIN_FUNCTION_PARAMETERS
#define MAIN_FUNCTION_ARGUMENTS
#define __attribute__(nothing)
#define UNUSED
#define SIGNED_ENUM
#define simulatedTimePasses()
#define simulatedTimePassesMs(x)
#define simulatedSerialTimePasses()
#define halCommonUDiv32By16(x, y)
#define halCommonSDiv32By16(x, y)
#define halCommonUMod32By16(x, y)
#define halCommonSMod32By16(x, y)
C Standard Library Memory Utilities
These should be used in place of the standard library functions.
These functions have the same parameters and expected results as their C Standard Library equivalents but
may take advantage of certain implementation optimizations.
Unless otherwise noted, these functions are utilized by the EmberStack and are therefore required to be
implemented in the HAL. Additionally, unless otherwise noted, applications that find these functions useful
may utilize them.
•
•
•
•
•
•
•
•
•
•
•
•
XAP2B_PAGEZERO_OFF void void ∗ src
XAP2B_PAGEZERO_OFF void void int16u bytes
XAP2B_PAGEZERO_ON void halCommonMemCopy (void ∗dest, const void ∗src, int16u bytes)
XAP2B_PAGEZERO_OFF void halCommonMemPGMCopy (void ∗dest, void const ∗source, int16u
bytes) void halCommonBC(void ∗dest
void halCommonMemSet (void ∗dest, int8u val, int16u bytes)
XAP2B_PAGEZERO_ON int8s halCommonMemCompare (const void ∗source0, const void ∗source1,
int16u bytes)
XAP2B_PAGEZERO_OFF int8s halCommonMemPGMCompare (const void ∗source0, void const
∗source1, int16u bytes)
#define MEMSET(d, v, l)
#define MEMCOPY(d, s, l)
#define MEMFASTCOPY(d, s, l)
#define MEMCOMPARE(s0, s1, l)
#define MEMPGMCOMPARE(s0, s1, l)
External Declarations
These are routines that are defined in certain header files that we don’t want to include, e.g. stdlib.h
• int abs (int I)
• #define PLATCOMMONOKTOINCLUDE
EmberZNet 4.7.2 API EM250
120-3016-000-4720
274
6.40.1
Detailed Description
Compiler and Platform specific definitions and typedefs for the Microcosm C Compiler (MCC). See mcc.h
for source code.
6.40.2
Macro Definition Documentation
6.40.2.1
#define HAL USING XAP2B PRAGMAS
Definition at line 39 of file mcc.h.
6.40.2.2
#define XAP2B PAGEZERO ON
Definition at line 40 of file mcc.h.
6.40.2.3
#define XAP2B PAGEZERO OFF
Definition at line 41 of file mcc.h.
6.40.2.4
#define HAL USE COMMON PGM
Definition at line 59 of file mcc.h.
6.40.2.5
#define BIGENDIAN CPU
A convenient method for code to know whether the processor is big-endian or little-endian. For the XAP2b,
we are big-endian.
Definition at line 66 of file mcc.h.
6.40.2.6
#define NO STRIPPING
A friendlier name for the compiler’s intrinsic for not stripping. Since this is not actually possible with this
compiler, attempting to use this define will throw a compile time error.
Definition at line 74 of file mcc.h.
6.40.2.7
#define EEPROM
A friendlier name for the compiler’s intrinsic for eeprom reference. Since there is no internal EEPROM
available on this platform, attempting to use this define will throw a compile time error.
Definition at line 82 of file mcc.h.
6.40.2.8
#define SOURCEFILE
The ::SOURCEFILE macro is used by asserts to list the filename if it isn’t otherwise defined, set it to the
compiler intrinsic which specifies just the filename of the sourcefile if possible. On older compilers we
didn’t have this option so we set this to the whole filename and path of the sourcefile.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
275
Definition at line 98 of file mcc.h.
6.40.2.9
#define assert( condition )
A custom implementation of the C language assert macro. This macro implements the conditional evaluation and calls the function halInternalAssertFailed(). (see hal/micro/micro.h)
Definition at line 117 of file mcc.h.
6.40.2.10
#define delay cycles( x )
__delay_cycles() is an intrinsic IAR WB call; however, we have explicity disallowed it since it is too
specific to the system clock.
Note
Please use halCommonDelayMicroseconds() instead, because it correctly accounts for various system
clock speeds.
Definition at line 130 of file mcc.h.
6.40.2.11
#define DEBUG LEVEL
Set debug level based on whether DEBUG or DEBUG_OFF are defined.
Definition at line 144 of file mcc.h.
6.40.2.12
#define halResetWatchdog( )
Macro to reset the watchdog timer.
Warning
be very careful when using this to avoid an infinite loop.
Definition at line 152 of file mcc.h.
6.40.2.13
#define START ATOMIC CLOCK( )
This macro should be called in the local variable declarations section of any function which calls DISABLE_INTERRUPTS() or RESTORE_INTERRUPTS().
Definition at line 229 of file mcc.h.
6.40.2.14
#define STOP ATOMIC CLOCK( )
This macro should be called in the local variable declarations section of any function which calls DISABLE_INTERRUPTS() or RESTORE_INTERRUPTS().
Definition at line 230 of file mcc.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
276
6.40.2.15
#define DECLARE INTERRUPT STATE
This macro should be called in the local variable declarations section of any function which calls DISABLE_INTERRUPTS() or RESTORE_INTERRUPTS().
Definition at line 238 of file mcc.h.
6.40.2.16
#define DECLARE INTERRUPT STATE LITE
This macro should be called in the local variable declarations section of any function which calls DISABLE_INTERRUPTS() or RESTORE_INTERRUPTS().
Definition at line 239 of file mcc.h.
6.40.2.17
#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 with
RESTORE_INTERRUPTS_LITE().
Definition at line 250 of file mcc.h.
6.40.2.18
#define DISABLE INTERRUPTS LITE( )
This macro should be called in the local variable declarations section of any function which calls DISABLE_INTERRUPTS() or RESTORE_INTERRUPTS().
Definition at line 259 of file mcc.h.
6.40.2.19
#define RESTORE INTERRUPTS( )
Restore the global interrupt state previously saved by DISABLE_INTERRUPTS()
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 with
DISABLE_INTERRUPTS_LITE().
Definition at line 277 of file mcc.h.
6.40.2.20
#define RESTORE INTERRUPTS LITE( )
This macro should be called in the local variable declarations section of any function which calls DISABLE_INTERRUPTS() or RESTORE_INTERRUPTS().
Definition at line 287 of file mcc.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
277
6.40.2.21
#define INTERRUPTS ON( )
Enable global interrupts without regard to the current or previous state.
Definition at line 301 of file mcc.h.
6.40.2.22
#define INTERRUPTS OFF( )
Disable global interrupts without regard to the current or previous state.
Definition at line 315 of file mcc.h.
6.40.2.23
#define INTERRUPTS WERE ON( )
Returns
TRUE if global interrupt flag was enabled when DISABLE_INTERRUPTS() was called.
Definition at line 328 of file mcc.h.
6.40.2.24
#define INTERRUPTS ARE OFF( )
Returns
TRUE if the current global interrupt flag is enabled.
Definition at line 333 of file mcc.h.
6.40.2.25
#define ATOMIC( code )
A block of code may be made atomic by wrapping it with this macro. Something which is atomic cannot
be interrupted by interrupts.
Note
Use the LITE version only if you are certain interrupts will not be disabled very long.
Definition at line 342 of file mcc.h.
6.40.2.26
#define ATOMIC LITE( code )
This macro should be called in the local variable declarations section of any function which calls DISABLE_INTERRUPTS() or RESTORE_INTERRUPTS().
Definition at line 350 of file mcc.h.
6.40.2.27
#define HANDLE PENDING INTERRUPTS( )
Allows any pending interrupts to be executed. Usually this would be called at a safe point while interrupts
are disabled (such as within an ISR).
Takes no action if interrupts are already enabled.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
278
The implementation accounts for a XAP2b related oddity, wherein two instructions must be executed (SIFs
in this instance) to ensure the interrupt occurs and is processed before interrupts are turned back off.
Definition at line 370 of file mcc.h.
6.40.2.28
#define MAIN FUNCTION PARAMETERS
Define the parameters to main(), and for those functions that are passed the arguments from main().
Definition at line 396 of file mcc.h.
6.40.2.29
#define MAIN FUNCTION ARGUMENTS
Define the parameters to main(), and for those functions that are passed the arguments from main().
Definition at line 397 of file mcc.h.
6.40.2.30
#define attribute ( nothing )
Define attribute to nothing since it isn’t handled by NCC.
Definition at line 403 of file mcc.h.
6.40.2.31
#define UNUSED
Declare a variable as unused to avoid a warning. Has no effect in NCC builds.
Definition at line 410 of file mcc.h.
6.40.2.32
#define SIGNED ENUM
Some platforms need to cast enum values that have the high bit set.
Definition at line 416 of file mcc.h.
6.40.2.33
#define simulatedTimePasses( )
Stubs for code not running in simulation.
Definition at line 422 of file mcc.h.
6.40.2.34
#define simulatedTimePassesMs( x )
Define the parameters to main(), and for those functions that are passed the arguments from main().
Definition at line 423 of file mcc.h.
6.40.2.35
#define simulatedSerialTimePasses( )
Define the parameters to main(), and for those functions that are passed the arguments from main().
Definition at line 424 of file mcc.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
279
6.40.2.36
#define halCommonUDiv32By16( x, y )
Provide a portable name for the int32u by int16u division library function (which can perform the division
with only a single assembly instruction).
Definition at line 452 of file mcc.h.
6.40.2.37
#define halCommonSDiv32By16( x, y )
Provide a portable name for the int32s by int16s division library function (which can perform the division
with only a single assembly instruction).
Definition at line 459 of file mcc.h.
6.40.2.38
#define halCommonUMod32By16( x, y )
Provide a portable name for the int32u by int16u modulo library function (which can perform the division
with only a single assembly instruction).
Definition at line 466 of file mcc.h.
6.40.2.39
#define halCommonSMod32By16( x, y )
Provide a portable name for the int32s by int16s modulo library function (which can perform the division
with only a single assembly instruction).
Definition at line 473 of file mcc.h.
6.40.2.40
#define MEMSET( d, v, l )
Friendly convenience macro pointing to the full HAL function.
Definition at line 544 of file mcc.h.
6.40.2.41
#define MEMCOPY( d, s, l )
Friendly convenience macro pointing to the full HAL function.
Definition at line 545 of file mcc.h.
6.40.2.42
#define MEMFASTCOPY( d, s, l )
Friendly convenience macro pointing to the full HAL function.
Definition at line 546 of file mcc.h.
6.40.2.43
#define MEMCOMPARE( s0, s1, l )
Friendly convenience macro pointing to the full HAL function.
Definition at line 547 of file mcc.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
280
6.40.2.44
#define MEMPGMCOMPARE( s0, s1, l )
Friendly convenience macro pointing to the full HAL function.
Definition at line 548 of file mcc.h.
6.40.2.45
#define PLATCOMMONOKTOINCLUDE
Definition at line 564 of file mcc.h.
6.40.3
Typedef Documentation
6.40.3.1
typedef unsigned char boolean
Definition at line 49 of file mcc.h.
6.40.3.2
typedef unsigned char int8u
Definition at line 50 of file mcc.h.
6.40.3.3
typedef signed char int8s
Definition at line 51 of file mcc.h.
6.40.3.4
typedef unsigned int int16u
Definition at line 52 of file mcc.h.
6.40.3.5
typedef signed int int16s
Definition at line 53 of file mcc.h.
6.40.3.6
typedef unsigned long int32u
Definition at line 54 of file mcc.h.
6.40.3.7
typedef signed long int32s
Definition at line 55 of file mcc.h.
6.40.3.8
typedef unsigned int PointerType
Definition at line 56 of file mcc.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
281
6.40.4
Function Documentation
6.40.4.1 XAP2B_PAGEZERO_ON void halInternalAssertFailed ( const char ∗ filename, int linenumber
)
A prototype definition for use by the assert macro. (see hal/micro/micro.h)
6.40.4.2
unsigned int udivx2 ( unsigned long a, unsigned int b )
Normally, when the compiler needs to divide or modulo an int32 by an int16, the divisor will be promoted
to a 32bit number and the compiler will invoke one of the library functions __div, _udiv, __rem, or __urem
which operates on 2 32bit values However, the __div and __udiv functions (which are also used by __rem
and __urem) are very large (over 600 bytes each). However, he XAP2b can perform an int32 by int16
division or modulo with a single built in assembly instruction. Since the compiler will not automatically
use this assembly instruction, we must access it manually. To do so, these library functions are prototyped
here so they are available to the entire codebase. However, It is preferred to instead use the halCommonXXxx32By16() macros which can be generalized across other platforms.
6.40.4.3
int divx2 ( long a, int b )
Define the parameters to main(), and for those functions that are passed the arguments from main().
6.40.4.4
unsigned int uremx2 ( unsigned long a, unsigned int b )
Define the parameters to main(), and for those functions that are passed the arguments from main().
6.40.4.5
int remx2 ( long a, int b )
Define the parameters to main(), and for those functions that are passed the arguments from main().
6.40.4.6 XAP2B_PAGEZERO_ON void halCommonMemCopy ( void ∗ dest, const void ∗ src, int16u
bytes )
Refer to the C stdlib memcpy().
6.40.4.7 XAP2B_PAGEZERO_OFF void halCommonMemPGMCopy ( void ∗ dest, void const ∗ source,
int16u bytes )
Same as the C stdlib memcpy(), but handles copying from const program space.
Refer to the C stdlib memcpy().
6.40.4.8
void halCommonMemSet ( void ∗ dest, int8u val, int16u bytes )
Refer to the C stdlib memset().
EmberZNet 4.7.2 API EM250
120-3016-000-4720
282
6.40.4.9 XAP2B_PAGEZERO_ON int8s halCommonMemCompare ( const void ∗ source0, const void
∗ source1, int16u bytes )
Refer to the C stdlib memcmp().
6.40.4.10 XAP2B_PAGEZERO_OFF int8s halCommonMemPGMCompare ( const void ∗ source0, void
const ∗ source1, int16u bytes )
Same as the C stdlib memcpy(), but handles copying from constant program space.
6.40.4.11
6.40.5
int abs ( int I )
Variable Documentation
6.40.5.1 XAP2B_PAGEZERO_OFF void void∗ src
Friendly convenience macro pointing to the full HAL function.
Definition at line 517 of file mcc.h.
6.40.5.2 XAP2B_PAGEZERO_OFF void void int16u bytes
Friendly convenience macro pointing to the full HAL function.
Definition at line 517 of file mcc.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
283
6.41
HAL Utilities
Modules
• Crash and Watchdog Diagnostics
• Cyclic Redundancy Code (CRC)
• Random Number Generation
6.41.1
Detailed Description
EmberZNet 4.7.2 API EM250
120-3016-000-4720
284
6.42
Crash and Watchdog Diagnostics
Functions
• void halStartPCDiagnostics (void)
• void halStopPCDiagnostics (void)
• int16u halGetPCDiagnostics (void)
EM250-Specific Diagnostic Supplement Definitions
•
•
•
•
•
int16u emResetCause
int8u ∗ emStackLwm
int8u emStackBase [ ]
int8u emStackTop [ ]
void halInternalInitPCDiagnostics (void)
6.42.1
Detailed Description
Program counter diagnostic functions. Unless otherwise noted, the EmberNet stack 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.
Use these utilities with microcontrollers whose watchdog circuits do not make it possible to find out where
they were executing when a watchdog was triggered. Enabling the program counter (PC) diagnostics
enables a periodic timer interrupt that saves the current PC to a reserved, unitialized memory address. This
address can be read after a reset.
Some functions in this file return an EmberStatus value. See error-def.h for definitions of all EmberStatus
return values.
See hal/micro/diagnostic.h for source code.
See also hal/micro/xap2b/em250/diagnostic.h for source code.
6.42.2
Function Documentation
6.42.2.1
void halStartPCDiagnostics ( void )
Starts a timer that initiates sampling the microcontroller’s program counter.
6.42.2.2
void halStopPCDiagnostics ( void )
Stops the timer that was started by halStartPCDiagnostics().
6.42.2.3 int16u halGetPCDiagnostics ( void )
Provides a captured PC location from the last run.
Application Usage:
Call this function when an application starts, before calling halStartPCDiagnostics().
EmberZNet 4.7.2 API EM250
120-3016-000-4720
285
Returns
The most recently sampled program counter location.
6.42.2.4
void halInternalInitPCDiagnostics ( void )
This routine must be called once during boot before enabling interrupts.
6.42.3
Variable Documentation
6.42.3.1 int16u emResetCause
This routine must be called once during boot before enabling interrupts.
6.42.3.2 int8u∗ emStackLwm
This routine must be called once during boot before enabling interrupts.
6.42.3.3 int8u emStackBase[ ]
This routine must be called once during boot before enabling interrupts.
6.42.3.4 int8u emStackTop[ ]
This routine must be called once during boot before enabling interrupts.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
286
6.43
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)
6.43.1
Detailed Description
Functions that provide access to cyclic redundancy code (CRC) calculation. See crc.h for source code.
6.43.2
Macro Definition Documentation
6.43.2.1
#define INITIAL CRC
Definition at line 49 of file crc.h.
6.43.2.2
#define CRC32 START
Definition at line 50 of file crc.h.
6.43.2.3
#define CRC32 END
Definition at line 51 of file crc.h.
6.43.3
Function Documentation
6.43.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 with
an initial value, then repeatedly until all data is processed.
Parameters
newByte The new byte to be run through CRC.
prevResult The previous CRC result.
Returns
The new CRC result.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
287
6.43.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, then
repeatedly until all data is processed.
Parameters
newByte The new byte to be run through CRC.
prevResult The previous CRC result.
Returns
The new CRC result.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
288
6.44
Random Number Generation
Functions
• void halStackSeedRandom (int32u seed)
• int16u halCommonGetRandom (void)
6.44.1
Detailed Description
Functions that provide access to random numbers. These functions may be hardware accelerated, though
often are not.
See random.h for source code.
6.44.2
Function Documentation
6.44.2.1
void halStackSeedRandom ( int32u seed )
Seeds the halCommonGetRandom() pseudorandom number generator.
Called by the stack during initialization with a seed from the radio.
Parameters
seed A seed for the pseudorandom number generator.
6.44.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 it
is critical to implement this function to return quickly.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
289
6.45
Asynchronous Serial Host (ASH) Framework
EmberZNet 4.7.2 API EM250
120-3016-000-4720
290
6.46
Application Utilities API Reference
Modules
•
•
•
•
•
•
•
Bootloading
Command Interpreter
Forming and Joining Networks
ZigBee Device Object (ZDO) Information
Message Fragmentation
Network Manager
Serial Communication
6.46.1
Detailed Description
The Application Utilities API consists of sample utilities you can modify and use in your applications.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
291
6.47
Bootloading
Modules
• Stand-Alone Bootloader
• Stand-Alone Bootloader for EZSP
• Application Bootloader
6.47.1
Detailed Description
For a thorough discussion of bootloading, see the Bootloading chapter of the EmberZNet Application Developers Guide. There are three forms of the bootloading API.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
292
6.48
Stand-Alone Bootloader
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_WAIT_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_STATE_START_SENDING_IMAGE,
BOOTLOAD_STATE_SENDING_IMAGE, BOOTLOAD_STATE_WAIT_FOR_IMAGE_ACK, BOOTLOAD_STATE_WAIT_FOR_COMPLETE_ACK, BOOTLOAD_STATE_DONE,
BOOTLOAD_STATE_NORMAL, BOOTLOAD_STATE_QUERY, BOOTLOAD_STATE_SEND_QUERY_RESP, BOOTLOAD_STATE_INITIATE,
BOOTLOAD_STATE_SEND_INITIATE_RESP, BOOTLOAD_STATE_RX_IMAGE, BOOTLOAD_STATE_SEND_DATA, BOOTLOAD_STATE_WAIT_FOR_DATA_ACK,
BOOTLOAD_STATE_REPORT_ERROR, BOOTLOAD_STATE_SEND_COMPLETE, BOOTLOAD_STATE_WAIT_FOR_COMPLETE_ACK, BOOTLOAD_STATE_VALIDATE,
BOOTLOAD_STATE_SEND_VALIDATE_RESP, BOOTLOAD_STATE_UPDATE, BOOTLOAD_STATE_SEND_UPDATE_RESP }
Functions
• void bootloadUtilInit (int8u appPort, int8u bootloadPort)
• EmberStatus bootloadUtilSendRequest (EmberEUI64 targetEui, int16u mfgId, int8u hardwareTag[BOOTLOAD_HARDWARE_TAG_SIZE], int8u encryptKey[BOOTLOAD_AUTH_COMMON_SIZE], bootloadMode mode)
• void bootloadUtilSendQuery (EmberEUI64 target)
• void bootloadUtilStartBootload (EmberEUI64 target, bootloadMode mode)
• void bootloadUtilTick (void)
• boolean bootloadUtilLaunchRequestHandler (int16u manufacturerId, int8u hardwareTag[BOOTLOAD_HARDWARE_TAG_SIZE], EmberEUI64 sourceEui)
• void bootloadUtilQueryResponseHandler (boolean bootloaderActive, int16u manufacturerId, int8u
hardwareTag[BOOTLOAD_HARDWARE_TAG_SIZE], EmberEUI64 targetEui, int8u bootloaderCapabilities, 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 divisible
by the size of a 128-bit AES block.
• #define BOOTLOAD_AUTH_COMMON_SIZE
• #define BOOTLOAD_AUTH_CHALLENGE_SIZE
• #define BOOTLOAD_AUTH_RESPONSE_SIZE
EmberZNet 4.7.2 API EM250
120-3016-000-4720
293
Bootload State Variables
Used to check whether a bootloading process is currently happening.
• bootloadState blState
• #define IS_BOOTLOADING
6.48.1
Detailed Description
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 xmodem
protocol.
2. Load a new image on a remote node over-the-air (OTA) from a host (PC), also known as a passthru
bootload.
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 bootload packets) and the target node (node being loaded with a new image) need to be one hop away because
bootload 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 recovery
packets 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_BOOTLOAD_HANDLERS within their CONFIGURATION_HEADER .
6.48.2
Macro Definition Documentation
6.48.2.1
#define BOOTLOAD AUTH COMMON SIZE
Definition at line 66 of file bootload-utils.h.
6.48.2.2
#define BOOTLOAD AUTH CHALLENGE SIZE
Definition at line 67 of file bootload-utils.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
294
6.48.2.3
#define BOOTLOAD AUTH RESPONSE SIZE
Definition at line 68 of file bootload-utils.h.
6.48.2.4
#define BOOTLOAD HARDWARE TAG SIZE
Size of hardware tag which is an array of int8u.
// End set of defines
Definition at line 76 of file bootload-utils.h.
6.48.2.5
#define IS BOOTLOADING
Definition at line 300 of file bootload-utils.h.
6.48.3
Enumeration Type Documentation
6.48.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.
Definition at line 82 of file bootload-utils.h.
6.48.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 to
limit its activities. For example, when passthru bootloading is going on, do not print anything to a serial
port because it may violate the XModem protocol. Also, try to limit radio activities to a minimum to avoid
any 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
EmberZNet 4.7.2 API EM250
120-3016-000-4720
295
BOOTLOAD_STATE_WAIT_FOR_COMPLETE_ACK Wait for OTA end transmission ack
BOOTLOAD_STATE_DONE Finish bootloading
BOOTLOAD_STATE_NORMAL initial state (no bootloading)
BOOTLOAD_STATE_QUERY after sending query message
BOOTLOAD_STATE_SEND_QUERY_RESP wait to send query response
BOOTLOAD_STATE_INITIATE after send initiate message
BOOTLOAD_STATE_SEND_INITIATE_RESP wait to send initiate response
BOOTLOAD_STATE_RX_IMAGE during receiving OTA data messages
BOOTLOAD_STATE_SEND_DATA during sending OTA data messages
BOOTLOAD_STATE_WAIT_FOR_DATA_ACK wait for ack on data message
BOOTLOAD_STATE_REPORT_ERROR wait to send error message
BOOTLOAD_STATE_SEND_COMPLETE after sending complete message
BOOTLOAD_STATE_WAIT_FOR_COMPLETE_ACK wait for ack on "complete" msg
BOOTLOAD_STATE_VALIDATE after sending validate message
BOOTLOAD_STATE_SEND_VALIDATE_RESP wait to send validate response
BOOTLOAD_STATE_UPDATE after sending update message
BOOTLOAD_STATE_SEND_UPDATE_RESP wait to send update response
Definition at line 106 of file bootload-utils.h.
6.48.4
Function Documentation
6.48.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 when
doing passthru bootloading, we do not want to print any additional data that can cause an XModem
transaction to fail.
Parameters
appPort Port used for printing information.
bootloadPort Port used for passthru bootloading.
6.48.4.2 EmberStatus bootloadUtilSendRequest ( EmberEUI64 targetEui, int16u
mfgId, int8u hardwareTag[BOOTLOAD HARDWARE TAG SIZE], int8u
encryptKey[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. The
source node then enters a state waiting for the target node to send an authentication challenge, which it will
EmberZNet 4.7.2 API EM250
120-3016-000-4720
296
encrypt and send back as a response. MfgId and harwareTag information is sent over the air to the target
node to verify whether to go into bootload mode. The encryption key is saved on the source node for later
authentication. The mode indicates the bootload mode that the source will be using.
Parameters
targetEui
mfgId
hardwareTag
encryptKey
mode
Node to be bootloaded.
Manufacturer ID (vendor specific).
Hardware ID, such as a board (vendor specific).
Key used in the authentication process.
Bootload mode to be used is passthru (0x01).
Returns
EMBER_SUCESS if successful, or EMBER_NO_BUFFERS, or EMBER_ERR_FATAL if the function was called too soon after a previous call to it.
6.48.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 gather
information regarding a neighboring node, especially the eui64 of the node. Unicast query is used when
we already know the eui64 of the target node that we needs information from.
Parameters
target The node we want to gather information from. If the value is NULL, that means we
want to do a broadcast query.
6.48.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 source
node resetting, the network being too busy, a software reset, and so on. However, the failure is not caused
by a target node losing power. After the failure, the node stays in bootload mode on the same (current)
channel.
Parameters
target 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 node
that replies will be bootloaded.
mode bootload mode to be used, such as passthru (0x01).
6.48.4.5
void bootloadUtilTick ( void )
A function in the application’s heartbeat or tick function that contains basic bootloading state machine and
also manages the bootload timer.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
297
6.48.4.6 boolean bootloadUtilLaunchRequestHandler ( int16u manufacturerId, int8u
hardwareTag[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 will
launch after successful completion of the bootloader launch authentication protocol.
Parameters
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 to
launch the bootloader.
6.48.4.7
void bootloadUtilQueryResponseHandler ( boolean bootloaderActive, int16u manufacturerId,
int8u hardwareTag[BOOTLOAD HARDWARE TAG SIZE], EmberEUI64 targetEui, int8u
bootloaderCapabilities, int8u platform, int8u micro, int8u phy, int16u blVersion )
A callback function invoked by bootload-utils when a bootload query response message is received.
This is particularly useful when the application needs to decide which node to bootload. Several attributes
of the responding node are provided to the application. The application can use these attributes to decide
whether to bootload or how to bootload a given node.
Parameters
bootloaderActive
manufacturerId
hardwareTag
targetEui
bootloaderCapabilities
platform
micro
TRUE if the responding node is running the bootloader, FALSE if not.
The manufacturer specification (vendor specific) of the responding node.
The hardware specification (vendor specific) of the responding node.
The EUI64 of the responding node.
If the lsb is 1, the bootloader on the responding node supports encrypted bootloader
message payloads.
The type of platform of the responding node. 1 is avr-atmega, 2 is xap2b.
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 means
unknown. For example, a version field of 0x1234 is version 1.2, build 34.
6.48.4.8
void bootloadUtilSendAuthResponse ( EmberEUI64 target )
A function called by a parent node to send an authentication response message to the sleepy or mobile
end-device target node.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
298
The message is sent as a Just-In-Time (JIT) message, hence, the end-device target needs to poll for the
message.
The bootload utility library will call this function automatically if bootloading the router node.
Parameters
target The end-device target node being bootloaded.
6.48.5
Variable Documentation
6.48.5.1 bootloadState blState
EmberZNet 4.7.2 API EM250
120-3016-000-4720
299
6.49
Stand-Alone Bootloader for EZSP
EmberZNet 4.7.2 API EM250
120-3016-000-4720
300
6.50
Application Bootloader
Macros
• #define APP_BOOTLOAD_ENDPOINT
Enumerations
• enum bootloadState {
BOOTLOAD_STATE_NORMAL, BOOTLOAD_STATE_QUERY, BOOTLOAD_STATE_WAIT_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_STATE_START_SENDING_IMAGE,
BOOTLOAD_STATE_SENDING_IMAGE, BOOTLOAD_STATE_WAIT_FOR_IMAGE_ACK, BOOTLOAD_STATE_WAIT_FOR_COMPLETE_ACK, BOOTLOAD_STATE_DONE,
BOOTLOAD_STATE_NORMAL, BOOTLOAD_STATE_QUERY, BOOTLOAD_STATE_SEND_QUERY_RESP, BOOTLOAD_STATE_INITIATE,
BOOTLOAD_STATE_SEND_INITIATE_RESP, BOOTLOAD_STATE_RX_IMAGE, BOOTLOAD_STATE_SEND_DATA, BOOTLOAD_STATE_WAIT_FOR_DATA_ACK,
BOOTLOAD_STATE_REPORT_ERROR, BOOTLOAD_STATE_SEND_COMPLETE, BOOTLOAD_STATE_WAIT_FOR_COMPLETE_ACK, BOOTLOAD_STATE_VALIDATE,
BOOTLOAD_STATE_SEND_VALIDATE_RESP, BOOTLOAD_STATE_UPDATE, BOOTLOAD_STATE_SEND_UPDATE_RESP }
Functions
•
•
•
•
•
•
•
•
•
void appBootloadUtilTick (void)
void appBootloadUtilInit (int8u appPort, int8u bootloadPort, int16u appProfileId)
void appBootloadUtilStartXModem (void)
void appBootloadUtilSendQuery (int16u address, boolean isJIT)
void appBootloadUtilStartBootload (EmberNodeId target)
void appBootloadUtilValidate (EmberNodeId target)
void appBootloadUtilUpdate (EmberNodeId target)
void appBootloadUtilIncomingMessageHandler (EmberMessageBuffer message)
void appBootloadUtilMessageSent (int16u destination, EmberApsFrame ∗apsFrame, EmberMessageBuffer message, EmberStatus status)
Callbacks
Callback functions used by the application bootload library.
• int16u appBootloadUtilGetAppVersionHandler (void)
• void appBootloadUtilValidatingEEPROMImageHandler (void)
6.50.1
Detailed Description
All functions and variables defined here can be used by applications. See app-bootload-utils.h for source
code.
Applications can use this library to:
EmberZNet 4.7.2 API EM250
120-3016-000-4720
301
• Load a new (application) image onto its external memory (EEPROM) serially through the UART
port 1 using the xmodem protocol.
• Load an image from its EEPROM onto a remote node over-the-air (OTA).
The library provides support for bootloading one node at a time over multiple hops away. Additional code
is required to support bootloading multiple nodes simultaneously.
Note that if a problem occurs during installing of a new image, the application bootloader will run a
recovery image on the failed node. Then a new image needs to be uploaded serially (via RS232) onto the
node using xmodem protocol application such as hyperterm.
The following diagrams show typical usage of application bootloader and recovery images.
A diagram for loading an image to external memory (EEPROM):
[host pc] –(RS232 or Ethernet)– {uart1 or port 4901}[node] – {EEPROM}
A diagram for typical application bootloading:
[source node]–(OTA)[relay node(s)]–[target node]
A diagram for bootloading via a recovery image:
[host pc] –(RS232 or Ethernet)– {uart1 or port 4901}[node] – {EEPROM}
The library also demonstrates Zigbee Cluster Library (ZCL) usage. The library uses only manufacturerspecific commands and attributes. Its attributes are stored in the zcl utility attribute table under app/ha/gen. Additionally, the library uses an Ember-assigned application profile value of 0xC00D. The user must
change this value to his/her company’s application profile value during deployment. The company can
obtain a range of application profiles from the Zigbee organization if it does not already have them.
Note
Applications that use the bootload utilities need to #define USE_APP_BOOTLOADER_LIB within
their CONFIGURATION_HEADER
6.50.2
Macro Definition Documentation
6.50.2.1
#define APP BOOTLOAD ENDPOINT
Selected endpoint used for application bootloading.
This is used to filtered incoming radio messages.
Definition at line 69 of file app-bootload-utils.h.
6.50.3
Enumeration Type Documentation
6.50.3.1
enum bootloadState
A value that application can check whether bootloading is in progress. Used in a bootload state machine.
This is necessary because we want the application to be aware that bootloading is going on and it needs to
limit its activities. For example, the application should not print anything to the serial port when passthru
bootloading is going on because it may violate the XModem protocol. Try to limit radio activities to a
minimum to avoid any interruptions to the bootload progress.
∗The following bootload states are supported by the application bootload utility library.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
302
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
BOOTLOAD_STATE_NORMAL initial state (no bootloading)
BOOTLOAD_STATE_QUERY after sending query message
BOOTLOAD_STATE_SEND_QUERY_RESP wait to send query response
BOOTLOAD_STATE_INITIATE after send initiate message
BOOTLOAD_STATE_SEND_INITIATE_RESP wait to send initiate response
BOOTLOAD_STATE_RX_IMAGE during receiving OTA data messages
BOOTLOAD_STATE_SEND_DATA during sending OTA data messages
BOOTLOAD_STATE_WAIT_FOR_DATA_ACK wait for ack on data message
BOOTLOAD_STATE_REPORT_ERROR wait to send error message
BOOTLOAD_STATE_SEND_COMPLETE after sending complete message
BOOTLOAD_STATE_WAIT_FOR_COMPLETE_ACK wait for ack on "complete" msg
BOOTLOAD_STATE_VALIDATE after sending validate message
BOOTLOAD_STATE_SEND_VALIDATE_RESP wait to send validate response
BOOTLOAD_STATE_UPDATE after sending update message
BOOTLOAD_STATE_SEND_UPDATE_RESP wait to send update response
Definition at line 86 of file app-bootload-utils.h.
6.50.4
Function Documentation
6.50.4.1
void appBootloadUtilTick ( void )
A function called in the application’s heartbeat or tick function. The function contains basic bootloading
state machine and also manages the bootload timer.
6.50.4.2
void appBootloadUtilInit ( int8u appPort, int8u bootloadPort, int16u appProfileId )
Bootload library initialization. The application needs to define the ports to be used for printing information
and for serial bootload.
Note that the bootload port has to be the RS232 port since it needs to receive the image via xmodem
protocol.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
303
Parameters
appPort Port used for printing information
bootloadPort Port used for serial bootloading
appProfileId Application profile id used
6.50.4.3
void appBootloadUtilStartXModem ( void )
Starts the bootload process on a target node that is currently running stack/application.
The source node sends bootload initiate message to tell the target that it wants to start bootloading. The
source node then enters a state waiting for the target node to send an initiate_response, which tells the
source node whether the target node is able to participate in the bootload process, along with the error code
indicating the reason if it is not able.
6.50.4.4
void appBootloadUtilSendQuery ( int16u address, boolean isJIT )
Sends a query message to gather information about the node(s) with specified address within the EMBER_MAX_HOPS radius.
A query message is sent as a broadcast. The query is generally used to gather information regarding nodes
in the network, especially the eui64 and short id of the node.
Parameters
address the broadcast address that we want to send to. The valid addresses are EMBER_BROADCAST_ADDRESS, EMBER_SLEEPY_BROADCAST_ADDRESS, and EMBER_RX_ON_WHEN_IDLE_BROADCAST_ADDRESS.
isJIT specify whether the query message is being sent via JIT method or not. The flag is set
to TRUE if parent nodes is sending the query to the child node when the child polls.
6.50.4.5
void appBootloadUtilStartBootload ( EmberNodeId target )
Starts the bootload process on a target node that is currently running stack/application.
The source node sends a bootload initiate message to tell the target that it wants to start bootloading. The
source node then enters a state waiting for the target node to send an initiate_response, which tells the
source node whether the target node is able to participate in the bootload process, along with the error code
indicating the reason if it is not able.
Parameters
target Node short id to be bootloaded
6.50.4.6
void appBootloadUtilValidate ( EmberNodeId target )
Validates the image on the EEPROM on a target node.
The target node can be a short id of a single node or one of the broadcast addresses. After sending the
message, the source node enters a state waiting for the target node to send a validate_response with status
and image information (timestamp and imageinfo) which tells the source node whether the target node has
valid image on its EEPROM.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
304
If the target address is its own, then halAppBootloaderGetImageData() is called directly and no message is
sent out.
Parameters
target Node short id to be bootloaded or broadcast address if wanting to update multiple nodes
at the same time.
6.50.4.7
void appBootloadUtilUpdate ( EmberNodeId target )
Installs new image (on EEPROM) on a target node.
The target node can be a short id of a single node or one of the broadcast addresses. After sending the
message, the source node enters a state waiting for the target node to send an update_response with status
which tells the source node whether the target node is able to update the image or not.
If the target address is its own, then halAppBootloaderInstallNewImage() is called directly and no message
is sent out.
Parameters
target Node short id to be bootloaded or broadcast address if wanting to update multiple nodes
at the same time.
6.50.4.8
void appBootloadUtilIncomingMessageHandler ( EmberMessageBuffer message )
Called in emberIncomingMessageHander() to pass the application bootload message to the library for
further processing.
6.50.4.9
void appBootloadUtilMessageSent ( int16u destination, EmberApsFrame ∗ apsFrame,
EmberMessageBuffer message, EmberStatus status )
Called in emberMessageSentHandler() to pass the sent application bootload message and status to the
library for further processing.
6.50.4.10 int16u appBootloadUtilGetAppVersionHandler ( void )
A callback function called by the library to get the application version and id. MSB returned is the id and
LSB is the version.
6.50.4.11
void appBootloadUtilValidatingEEPROMImageHandler ( void )
A callback function called by the library to allow the application to perform any tasks necessary while the
node is validating its external EEPROM image.
The validating process can take around ten seconds. Note that while the node is validating EEPROM
image, it continues to receive messages over the air. It is strongly recommended that the application calls
emberTick() within this function in order to service these messages. Not doing so can lead to the node
running out of buffer when it finishes validating the image.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
305
6.51
Command Interpreter
Data Structures
• struct EmberCommandEntry
Command entry for a command table.
• struct EmberCommandStateS
The 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_MANY_COMMAND_ARGUMENTS, EMBER_CMD_ERR_ARGUMENT_OUT_OF_RANGE, EMBER_CMD_ERR_ARGUMENT_SYNTAX_ERROR,
EMBER_CMD_ERR_STRING_TOO_LONG, EMBER_CMD_ERR_NO_BINARY_STRING_TERMINATOR, 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_TYPE }
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 EM250
120-3016-000-4720
306
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 command 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)
6.51.1
Detailed Description
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 arguments
10
// integer base
};
emberCommandReaderInit(&testState);
1. Applications specify the commands that can be interpreted by defining a commands table 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 arguments
the 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 bundled
into an EmberCommandState structure. Using a structure allows commands to be read from multiple
sources.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
307
4. The application provides an instance of the EmberCommandState structure to the interpreter by
calling emberCommandReaderInit().
6.51.2
Macro Definition Documentation
6.51.2.1
#define EMBER COMMENT CHARACTER
The command table’s comment indicator. A comment consists of a ’#’ followed by any characters up to an
end-of-line.
Definition at line 75 of file command-interpreter.h.
6.51.2.2
#define EMBER MAX COMMAND LENGTH
The maximum number of characters in a command.
Definition at line 81 of file command-interpreter.h.
6.51.2.3
#define TEMP GREATER THAN MAX ARG SIZE
Definition at line 96 of file command-interpreter.h.
6.51.2.4
#define PERFORM BOUNDS CHECKING
Definition at line 97 of file command-interpreter.h.
6.51.2.5
#define emberUnsignedCommandArgument( state, index )
Definition at line 231 of file command-interpreter.h.
6.51.2.6
#define emberSignedCommandArgument( state, index )
Definition at line 234 of file command-interpreter.h.
6.51.2.7
#define emberBufferCommandArgument( state, index )
Definition at line 237 of file command-interpreter.h.
6.51.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 string
size.
void emberProcessCommandInput(EmberCommandState
*state, int8u port);
Definition at line 264 of file command-interpreter.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
308
6.51.2.9
#define emberCommandName( state )
Return a pointer to the command name being executed.
Parameters
state The command state structure.
Definition at line 270 of file command-interpreter.h.
6.51.3
Typedef Documentation
6.51.3.1
typedef int16u ArgTypeU
Definition at line 95 of file command-interpreter.h.
6.51.3.2
typedef void(∗ CommandAction)(struct EmberCommandStateS ∗state)
Definition at line 102 of file command-interpreter.h.
6.51.3.3
typedef struct EmberCommandStateS EmberCommandState
The command state structure. Using a structure allows commands to be read from multiple sources.
6.51.4
Enumeration Type Documentation
6.51.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 emberCommandErrorNames[] 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 terminator
EMBER_CMD_SUCCESS
EMBER_CMD_ERR_PORT_PROBLEM
EmberZNet 4.7.2 API EM250
120-3016-000-4720
309
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_TYPE
Definition at line 153 of file command-interpreter.h.
6.51.5
Function Documentation
6.51.5.1
void emberCommandReaderInit ( EmberCommandState ∗ state )
Initialize a command state.
Parameters
state The command state structure.
6.51.5.2 boolean emberProcessCommandString ( EmberCommandState ∗ state, int8u ∗ input, int8u
size )
Parses ’size’ characters from ’input’.
Returns
TRUE if an end of line character was read. If the application uses a command line prompt, this
indeicates it is time to print the prompt.
6.51.6
Variable Documentation
6.51.6.1
PGM NO CONST PGM P emberCommandErrorNames[ ]
EmberZNet 4.7.2 API EM250
120-3016-000-4720
310
6.52
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
6.52.1
Detailed Description
Functions for finding an existing network to join and for finding an unused PAN id with which to form a
network.
Summary of application requirements:
For the SOC:
• Define ::EMBER_APPLICATION_HAS_ENERGY_SCAN_RESULT_HANDLER in the configuration 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 EM250
120-3016-000-4720
311
For an EZSP Host:
• Define ::EZSP_APPLICATION_HAS_ENERGY_SCAN_RESULT_HANDLER in the configuration 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 implement the callbacks itself if necessary. In this case the appropriate form-and-join callback function must be
called 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 emberScanForNextJoinableNetwork(). Thus if the first joinable network found is not the correct one, the application
can continue scanning without starting from the beginning and without finding the same network that it has
already rejected. The library can also be used on the host processor.
6.52.2
Macro Definition Documentation
6.52.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 NetworkInfo
struct used in the adapter code. Its value should not be changed unless the underlying adapter code is
updated accordingly. Note that this constant’s value may be different than sizeof(NetworkInfo) because
some compilers pad the structs to align on word boundaries. Thus, the adapter code stores/retrieves these
pieces 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_BUFFER_SIZE).
Definition at line 68 of file form-and-join.h.
6.52.2.2
#define NETWORK STORAGE SIZE SHIFT
Log_base2 of NETWORK_STORAGE_SIZE.
Definition at line 72 of file form-and-join.h.
6.52.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 an
8-bit quantity (less than 256).
Note for EZSP Host Platforms: In the host implementation of this library, the storage size for the detected
networks buffer is controlled by ::EZSP_HOST_FORM_AND_JOIN_BUFFER_SIZE, so that limits the
highest value that the host can set for FORM_AND_JOIN_MAX_NETWORKS.
Definition at line 94 of file form-and-join.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
312
6.52.3
Function Documentation
6.52.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 the
least average energy. Then picks a short PAN id that does not appear during an active scan on the chosen
channel. The chosen PAN id and channel are returned via the emberUnusedPanIdFoundHandler() callback.
If an error occurs, the application is informed via the emberScanErrorHandler().
Parameters
channelMask
duration The duration of the energy scan. See the documentation for emberStartScan() in
stack/include/network-formation.h for information on duration values.
Returns
EMBER_LIBRARY_NOT_PRESENT if the form and join library is not available.
6.52.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 informed
via the emberScanErrorHandler(), and scanning stops.
If the application determines that the discovered network is not the correct one, it may call emberScanForNextJoinableNetwork() to continue the scanning process where it was left off and find a different joinable
network. If the next network is not the correct one, the application can continue to call emberScanForNextJoinableNetwork(). Each call must occur within 30 seconds of the previous one, otherwise the state of the
scan process is deleted to free up memory. Calling emberScanForJoinableNetwork() causes any old state
to be forgotten and starts scanning from the beginning.
Parameters
channelMask
extendedPanId
Returns
EMBER_LIBRARY_NOT_PRESENT if the form and join library is not available.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
313
6.52.3.3 EmberStatus emberScanForNextJoinableNetwork ( void )
See emberScanForJoinableNetwork().
6.52.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 expecting
scan results to be passed to it from the application.
6.52.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().
Parameters
panId
channel
6.52.3.6
void emberJoinableNetworkFoundHandler ( EmberZigbeeNetwork ∗ networkFound, int8u lqi,
int8s rssi )
A callback the application needs to implement.
Notifies the application of the network found after a call to emberScanForJoinableNetwork() or emberScanForNextJoinableNetwork().
Parameters
networkFound
lqi The lqi value of the received beacon.
rssi The rssi value of the received beacon.
6.52.3.7
void emberScanErrorHandler ( EmberStatus status )
A callback the application needs to implement.
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 seconds
after 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 EM250
120-3016-000-4720
314
Parameters
status
6.52.3.8 boolean emberFormAndJoinScanCompleteHandler ( int8u channel, EmberStatus status )
The application must call this function from within its emberScanCompleteHandler() (on the node) or
ezspScanCompleteHandler() (on an EZSP host). Default callback implementations are provided in the
form-and-join-∗-callbacks.c files.
Returns
TRUE iff the library made use of the call.
6.52.3.9 boolean emberFormAndJoinNetworkFoundHandler ( EmberZigbeeNetwork ∗ networkFound,
int8u lqi, int8s rssi )
The application must call this function from within its emberNetworkFoundHandler() (on the node) or
ezspNetworkFoundHandler() (on an EZSP host). Default callback implementations are provided in the
form-and-join-∗-callbacks.c files.
Returns
TRUE iff the library made use of the call.
6.52.3.10 boolean emberFormAndJoinEnergyScanResultHandler ( int8u channel, int8s maxRssiValue )
The application must call this function from within its emberEnergyScanResultHandler() (on the node) or
ezspEnergyScanResultHandler() (on an EZSP host). Default callback implementations are provided in the
form-and-join-∗-callbacks.c files.
Returns
TRUE iff the library made use of the call.
6.52.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. The
application must call emberFormAndJoinTick() regularly. This function does not exist for the EZSP host
library.
6.52.3.12
void emberFormAndJoinTaskInit ( void )
When processor idling is desired on the SOC, this must be called to properly initialize the form and join
library.
6.52.3.13
void emberFormAndJoinRunTask ( void )
When processor idling is desired on the SOC, this should be called regularly instead of emberFormAndJoinTick()
EmberZNet 4.7.2 API EM250
120-3016-000-4720
315
6.52.3.14
void emberFormAndJoinCleanup ( EmberStatus status )
When form-and-join state is no longer needed, the application can call this routine to cleanup and free
resources. On the SOC platforms this will free the allocated message buffer.
6.52.4
Variable Documentation
6.52.4.1 boolean emberEnableDualChannelScan
With some board layouts, the EM250 and EM260 are susceptible to a dual channel issue in which packets
from 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, version
B0 solve the problem.
Setting the emberEnableDualChannelScan variable to TRUE enables a software workaround to the dual
channel issue which can be used with vulnerable boards. After emberScanForJoinableNetwork() discovers
a network on one of the susceptible channels, the channel number that differs by 12 is also scanned. If
the same network can be heard there, the true channel is determined by comparing the link quality of
the received beacons. The default value of emberEnableDualChannelScan is TRUE for the EM250 and
EM260. It is not used on other platforms.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
316
6.53
ZigBee Device Object (ZDO) Information
Macros
• #define ZDO_MESSAGE_OVERHEAD
Service Discovery Functions
• EmberStatus emberMatchDescriptorsRequest (EmberNodeId target, int16u profile, EmberMessageBuffer inClusters, EmberMessageBuffer outClusters, EmberApsOption options)
Binding Manager Functions
• EmberStatus emberEndDeviceBindRequest (int8u endpoint, EmberApsOption options)
Function to Decode Address Response Messages
• EmberNodeId emberDecodeAddressResponse (EmberMessageBuffer response, EmberEUI64 eui64Return)
Service Discovery Functions
• EmberStatus emberNodeDescriptorRequest (EmberNodeId target, EmberApsOption options)
• EmberStatus emberPowerDescriptorRequest (EmberNodeId target, EmberApsOption options)
• EmberStatus emberSimpleDescriptorRequest (EmberNodeId target, int8u targetEndpoint, EmberApsOption options)
• EmberStatus emberActiveEndpointsRequest (EmberNodeId target, EmberApsOption options)
Binding Manager Functions
• EmberStatus emberBindRequest (EmberNodeId target, EmberEUI64 source, int8u sourceEndpoint,
int16u clusterId, int8u type, EmberEUI64 destination, EmberMulticastId groupAddress, int8u destinationEndpoint, EmberApsOption options)
• EmberStatus emberUnbindRequest (EmberNodeId target, EmberEUI64 source, int8u sourceEndpoint,
int16u clusterId, int8u type, EmberEUI64 destination, EmberMulticastId groupAddress, int8u destinationEndpoint, EmberApsOption options)
Node Manager Functions
• EmberStatus emberLqiTableRequest (EmberNodeId target, int8u startIndex, EmberApsOption options)
• EmberStatus emberRoutingTableRequest (EmberNodeId target, int8u startIndex, EmberApsOption
options)
• EmberStatus emberBindingTableRequest (EmberNodeId target, int8u startIndex, EmberApsOption
options)
• EmberStatus emberLeaveRequest (EmberNodeId target, EmberEUI64 deviceAddress, int8u leaveRequestFlags, EmberApsOption options)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
317
• EmberStatus emberPermitJoiningRequest (EmberNodeId target, int8u duration, int8u authentication,
EmberApsOption options)
• void emberSetZigDevRequestRadius (int8u radius)
• int8u emberGetZigDevRequestRadius (void)
• int8u emberGetLastZigDevRequestSequence (void)
• int8u emberGetLastAppZigDevRequestSequence (void)
6.53.1
Detailed Description
For getting information about nodes of a ZigBee network via a ZigBee Device Object (ZDO). See zigbeedevice-library.h and zigbee-device-common.h for source code.
The ZDO library provides functions that construct and send several common ZDO requests. It also provides
a function for extracting the two addresses from a ZDO address response. The format of all the ZDO
requests and responses that the stack supports is described in stack/include/zigbee-device-stack.h. Since
the library doesn’t handle all of these requests and responses, the application must construct any other
requests 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 emberSendBroadcast() or emberSendUnicast().
The result of the send is reported to the application as normal via emberMessageSentHandler().
The following code shows an example of an application’s use of emberSimpleDescriptorRequest(). The
command 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 emberDecodeAddressResponse().
void emberIncomingMessageHandler(
EmberIncomingMessageType type,
EmberApsFrame *apsFrame,
EmberMessageBuffer message)
{
if (apsFrame->profileId == EMBER_ZDO_PROFILE_ID)
{
switch (apsFrame->clusterId) {
case NETWORK_ADDRESS_RESPONSE:
case IEEE_ADDRESS_RESPONSE:
{
EmberEUI64 eui64;
EmberNodeId nodeId = emberDecodeAddressResponse
(message, eui64);
// Use nodeId and eui64 here.
break;
EmberZNet 4.7.2 API EM250
120-3016-000-4720
318
}
default:
// Handle other incoming ZDO responses here.
}
} else {
// Handle incoming application messages here.
}
}
6.53.2
Macro Definition Documentation
6.53.2.1
#define ZDO MESSAGE OVERHEAD
ZDO messages start with a sequence number.
Definition at line 16 of file zigbee-device-common.h.
6.53.3
Function Documentation
6.53.3.1 EmberStatus emberMatchDescriptorsRequest ( EmberNodeId target, int16u profile,
EmberMessageBuffer inClusters, EmberMessageBuffer 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.
Parameters
target 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.
inClusters The list of input clusters. To not match any input clusters, use EMBER_NULL_MESSAGE_BUFFER.
outClusters The list of output clusters. To not match any output clusters, use EMBER_NULL_MESSAGE_BUFFER.
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.
Returns
An EmberStatus value. EMBER_SUCCESS, EMBER_NO_BUFFERS, EMBER_NETWORK_DOWN or EMBER_NETWORK_BUSY.
6.53.3.2 EmberStatus emberEndDeviceBindRequest ( int8u endpoint, EmberApsOption options )
An end device bind request to the coordinator. The simple descriptor of the specified endpoint is used to
construct the request. If the coordinator receives a second end device bind request then a binding is created
for every matching cluster.
Parameters
endpoint The endpoint on the local device whose simple descriptor will be used to create the
request.
options The options to use when sending the request. See emberSendUnicast() for a description.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
319
Returns
An EmberStatus value. EMBER_SUCCESS, EMBER_NO_BUFFERS, EMBER_NETWORK_DOWN or EMBER_NETWORK_BUSY.
6.53.3.3 EmberNodeId emberDecodeAddressResponse ( EmberMessageBuffer response,
EmberEUI64 eui64Return )
Extracts the EUI64 and the node ID from an address response message.
Parameters
response 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. Otherwise, returns EMBER_NULL_NODE_ID.
6.53.3.4 EmberStatus emberNodeDescriptorRequest ( EmberNodeId target, EmberApsOption
options )
Request the specified node to send its node descriptor. The node descriptor contains information about the
capabilities of the ZigBee node. It describes logical type, APS flags, frequency band, MAC capabilities
flags, manufacturer code and maximum buffer size. It is defined in the ZigBee Application Framework
Specification.
Parameters
target The node whose node descriptor is desired.
options The options to use when sending the request. See emberSendUnicast() for a description.
Returns
An EmberStatus value. EMBER_SUCCESS, EMBER_NO_BUFFERS, EMBER_NETWORK_DOWN or EMBER_NETWORK_BUSY.
6.53.3.5 EmberStatus emberPowerDescriptorRequest ( EmberNodeId target, EmberApsOption
options )
Request the specified node to send its power descriptor. The power descriptor gives a dynamic indication
of the power status of the node. It describes current power mode, available power sources, current power
source and current power source level. It is defined in the ZigBee Application Framework Specification.
Parameters
target The node whose power descriptor is desired.
options The options to use when sending the request. See emberSendUnicast() for a description.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
320
Returns
An EmberStatus value. EMBER_SUCCESS, EMBER_NO_BUFFERS, EMBER_NETWORK_DOWN or EMBER_NETWORK_BUSY.
6.53.3.6 EmberStatus emberSimpleDescriptorRequest ( EmberNodeId target, int8u targetEndpoint,
EmberApsOption options )
Request the specified node to send the simple descriptor for the specified endpoint. The simple descriptor
contains information specific to a single endpoint. It describes the application profile identifier, application
device identifier, application device version, application flags, application input clusters and application
output clusters. It is defined in the ZigBee Application Framework Specification.
Parameters
target 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
An EmberStatus value. EMBER_SUCCESS, EMBER_NO_BUFFERS, EMBER_NETWORK_DOWN or EMBER_NETWORK_BUSY.
6.53.3.7 EmberStatus emberActiveEndpointsRequest ( EmberNodeId target, EmberApsOption
options )
Request the specified node to send a list of its active endpoints. An active endpoint is one for which a
simple descriptor is available.
Parameters
target The node whose active endpoints are desired.
options The options to use when sending the request. See emberSendUnicast() for a description.
Returns
An EmberStatus value. EMBER_SUCCESS, EMBER_NO_BUFFERS, EMBER_NETWORK_DOWN or EMBER_NETWORK_BUSY.
6.53.3.8 EmberStatus emberBindRequest ( EmberNodeId target, EmberEUI64 source, int8u
sourceEndpoint, int16u clusterId, int8u type, EmberEUI64 destination, EmberMulticastId
groupAddress, int8u destinationEndpoint, EmberApsOption options )
Send a request to create a binding entry with the specified contents on the specified node.
Parameters
target The node on which the binding will be created.
source The source EUI64 in the binding entry.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
321
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 UNICAST_MANY_TO_ONE_BINDING. UNICAST_MANY_TO_ONE_BINDING is
an Ember-specific extension and should be used only when the target is an Ember device.
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- The destination endpoint in the binding entry for the UNICAST_BINDING or UNICEndpoint AST_MANY_TO_ONE_BINDING.
options The options to use when sending the request. See emberSendUnicast() for a description.
Returns
An EmberStatus value. EMBER_SUCCESS, EMBER_NO_BUFFERS, EMBER_NETWORK_DOWN or EMBER_NETWORK_BUSY.
6.53.3.9 EmberStatus emberUnbindRequest ( EmberNodeId target, EmberEUI64 source, int8u
sourceEndpoint, int16u clusterId, int8u type, EmberEUI64 destination, EmberMulticastId
groupAddress, int8u destinationEndpoint, EmberApsOption options )
Send a request to remove a binding entry with the specified contents from the specified node.
Parameters
target
source
sourceEndpoint
clusterId
type
destination
groupAddress
destinationEndpoint
options
The node on which the binding will be removed.
The source EUI64 in the binding entry.
The source endpoint in the binding entry.
The cluster ID in the binding entry.
The type of binding, either UNICAST_BINDING, MULTICAST_BINDING, or UNICAST_MANY_TO_ONE_BINDING. UNICAST_MANY_TO_ONE_BINDING is
an Ember-specific extension and should be used only when the target is an Ember device.
The destination EUI64 in the binding entry for the UNICAST_BINDING or UNICAST_MANY_TO_ONE_BINDING.
The group address for the MULTICAST_BINDING.
The destination endpoint in the binding entry for the UNICAST_BINDING or UNICAST_MANY_TO_ONE_BINDING.
The options to use when sending the request. See emberSendUnicast() for a description.
Returns
An EmberStatus value.
• EMBER_SUCCESS
• EMBER_NO_BUFFERS _ EMBER_NETWORK_DOWN
• EMBER_NETWORK_BUSY
EmberZNet 4.7.2 API EM250
120-3016-000-4720
322
6.53.3.10 EmberStatus emberLqiTableRequest ( EmberNodeId target, int8u startIndex,
EmberApsOption options )
Request the specified node to send its LQI (neighbor) table. The response gives PAN ID, EUI64, node
ID and cost for each neighbor. The EUI64 is only available if security is enabled. The other fields in the
response are set to zero. The response format is defined in the ZigBee Device Profile Specification.
Parameters
target 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
An EmberStatus value. EMBER_SUCCESS, EMBER_NO_BUFFERS, EMBER_NETWORK_DOWN or EMBER_NETWORK_BUSY.
6.53.3.11 EmberStatus emberRoutingTableRequest ( EmberNodeId target, int8u startIndex,
EmberApsOption options )
Request the specified node to send its routing table. The response gives destination node ID, status and
many-to-one flags, and the next hop node ID. The response format is defined in the ZigBee Device Profile
Specification.
Parameters
target 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
An EmberStatus value. EMBER_SUCCESS, EMBER_NO_BUFFERS, EMBER_NETWORK_DOWN or EMBER_NETWORK_BUSY.
6.53.3.12 EmberStatus emberBindingTableRequest ( EmberNodeId target, int8u startIndex,
EmberApsOption options )
Request the specified node to send its nonvolatile bindings. The response gives source address, source
endpoint, cluster ID, destination address and destination endpoint for each binding entry. The response
format is defined in the ZigBee Device Profile Specification. Note that bindings that have the Emberspecific UNICAST_MANY_TO_ONE_BINDING type are reported as having the standard UNICAST_BINDING type.
Parameters
target 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.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
323
Returns
An EmberStatus value. EMBER_SUCCESS, EMBER_NO_BUFFERS, EMBER_NETWORK_DOWN or EMBER_NETWORK_BUSY.
6.53.3.13 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 removed
must be the node to which the request is sent or one of its children.
Parameters
target 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 of
the target device to remove that child.
leaveRequest- A bitmask of leave options. Include LEAVE_REQUEST_REMOVE_CHILDREN_FFlags LAG if the target is to remove their children and/or LEAVE_REQUEST_REJOIN_FLAG if the target is to rejoin the network immediately after leaving.
options The options to use when sending the request. See emberSendUnicast() for a description.
Returns
An EmberStatus value. EMBER_SUCCESS, EMBER_NO_BUFFERS, EMBER_NETWORK_DOWN or EMBER_NETWORK_BUSY.
6.53.3.14 EmberStatus emberPermitJoiningRequest ( EmberNodeId target, int8u duration, int8u
authentication, EmberApsOption options )
Request the specified node to allow or disallow association.
Parameters
target The node which will allow or disallow association. The request can be broadcast by using a broadcast address (0xFFFC/0xFFFD/0xFFFF). No response is sent if the request
is broadcast.
duration A value of 0x00 disables joining. A value of 0xFF enables joining. Any other value
enables 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
An EmberStatus value. EMBER_SUCCESS, EMBER_NO_BUFFERS, EMBER_NETWORK_DOWN or EMBER_NETWORK_BUSY.
6.53.3.15
void emberSetZigDevRequestRadius ( int8u radius )
Change the default radius for broadcast ZDO requests.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
324
Parameters
radius The radius to be used for future ZDO request broadcasts.
6.53.3.16 int8u emberGetZigDevRequestRadius ( void )
Retrieve the default radius for broadcast ZDO requests.
Returns
The radius to be used for future ZDO request broadcasts.
6.53.3.17 int8u emberGetLastZigDevRequestSequence ( void )
Provide access to the application ZDO transaction sequence number for last request. This function has
been deprecated and replaced by emberGetLastAppZigDevRequestSequence().
Returns
Last application ZDO transaction sequence number used
6.53.3.18 int8u emberGetLastAppZigDevRequestSequence ( void )
Provide access to the application ZDO transaction sequence number for last request.
Returns
Last application ZDO transaction sequence number used
EmberZNet 4.7.2 API EM250
120-3016-000-4720
325
6.54
Message Fragmentation
Transmitting
• EmberStatus emberFragmentSendUnicast (EmberOutgoingMessageType type, int16u indexOrDestination,
EmberApsFrame ∗apsFrame, EmberMessageBuffer payload, int8u maxFragmentSize)
• boolean emberFragmentMessageSent (EmberApsFrame ∗apsFrame, EmberMessageBuffer buffer,
EmberStatus status)
• void emberFragmentMessageSentHandler (EmberStatus status)
Receiving
• boolean emberFragmentIncomingMessage (EmberApsFrame ∗apsFrame, EmberMessageBuffer payload)
• void emberFragmentTick (void)
6.54.1
Detailed Description
Splits long messages into smaller blocks for transmission and reassembles received blocks. See fragment.h
for source code.
EMBER_FRAGMENT_WINDOW_SIZE controls how many blocks are sent at a time. EMBER_FRAGMENT_DELAY_MS controls the spacing between blocks.
To send a long message, the application calls emberFragmentSendUnicast(). The application must add a
call to emberFragmentMessageSent() at the start of its emberMessageSentHandler(). If emberFragmentMessageSent() returns TRUE, the fragmentation code has handled the event and the application must
not process it further. The fragmentation code calls the application-defined emberFragmentMessageSentHandler() when it has finished sending the long message.
To receive a long message, the application must add a call to emberFragmentIncomingMessage() at the
start of its emberIncomingMessageHandler(). If emberFragmentIncomingMessage() returns TRUE, the
fragmentation code has handled the message and the application must not process it further. The application
must also call emberFragmentTick() regularly.
6.54.2
Function Documentation
6.54.2.1 EmberStatus emberFragmentSendUnicast ( EmberOutgoingMessageType type, int16u
indexOrDestination, EmberApsFrame ∗ apsFrame, EmberMessageBuffer payload, int8u
maxFragmentSize )
Sends a long message by splitting it into blocks. Only one long message can be sent at a time. Calling this
function a second time aborts the first message.
Parameters
type Specifies the outgoing message type. Must be one of EMBER_OUTGOING_DIRECT, EMBER_OUTGOING_VIA_ADDRESS_TABLE, or EMBER_OUTGOING_VIA_BINDING.
indexOr- Depending on the type of addressing used, this is either the EmberNodeId of the destiDestination nation, an index into the address table, or an index into the binding table.
apsFrame The APS frame for the message.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
326
payload The long message to be sent.
maxFragment- The message will be broken into blocks no larger than this.
Size
Returns
An EmberStatus value.
• EMBER_SUCCESS
• EMBER_MESSAGE_TOO_LONG
• EMBER_NO_BUFFERS
• EMBER_NETWORK_DOWN
• EMBER_NETWORK_BUSY
• EMBER_INVALID_CALL is returned if the payload length is zero or if the window size (EMBER_FRAGMENT_WINDOW_SIZE) is zero.
6.54.2.2 boolean emberFragmentMessageSent ( EmberApsFrame ∗ apsFrame, EmberMessageBuffer
buffer, EmberStatus status )
The application must call this function at the start of its emberMessageSentHandler(). If it returns TRUE,
the fragmentation code has handled the event and the application must not process it further.
Parameters
apsFrame The APS frame passed to emberMessageSentHandler().
buffer The buffer passed to emberMessageSentHandler().
status The status passed to emberMessageSentHandler().
Returns
TRUE if the sent message was a block of a long message. The fragmentation code has handled the
event so the application must return immediately from its emberMessageSentHandler(). Returns FALSE otherwise. The fragmentation code has not handled the event so the application must continue to
process it.
6.54.2.3
void emberFragmentMessageSentHandler ( EmberStatus status )
The fragmentation code calls this application-defined handler when it finishes sending a long message.
Parameters
status EMBER_SUCCESS if all the blocks of the long message were delivered to the destination, otherwise EMBER_DELIVERY_FAILED, EMBER_NO_BUFFERS, EMBER_NETWORK_DOWN or EMBER_NETWORK_BUSY.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
327
6.54.2.4 boolean emberFragmentIncomingMessage ( EmberApsFrame ∗ apsFrame,
EmberMessageBuffer payload )
The application must call this function at the start of its emberIncomingMessageHandler(). If it returns TRUE, the fragmentation code has handled the message and the application must not process it further. When
the final block of a long message is received, this function replaces the message with the reassembled long
message and returns FALSE so that the application processes it.
Parameters
apsFrame The APS frame passed to emberIncomingMessageHandler().
payload The payload passed to emberIncomingMessageHandler().
Returns
TRUE if the incoming message was a block of an incomplete long message. The fragmentation code
has handled the message so the application must return immediately from its emberIncomingMessageHandler(). Returns FALSE if the incoming message was not part of a long message. The fragmentation
code has not handled the message so the application must continue to process it. Returns FALSE if
the incoming message was a block that completed a long message. The fragmentation code replaces
the message with the reassembled long message so the application must continue to process it.
6.54.2.5
void emberFragmentTick ( void )
Used by the fragmentation code to time incoming blocks. The application must call this function regularly.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
328
6.55
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)
6.55.1
Detailed Description
The network manager is an optional function of one device in the ZigBee network. Devices on the network
send unsolicited ZDO energy scan reports to the network manager when more than 25% of unicasts fail
within 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 emberSetNetworkManagerRequest(). It processes the energy scan reports from the devices on the network, and is responsible for
determining if the network should change channels in an attempt to resolve reliability problems that might
be caused by RF interference.
Note that EmberZNet networks are quite robust to many interferers such as 802.11 (WiFi), and the presence
of interferers does not necessarily degrade application performance or require a channel change. Because
changing channels is disruptive to network operation, channel changes should not be done solely because
of 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. In
general, it is difficult to automatically determine with certainty that network problems are caused by RF
interference. 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 EM250
120-3016-000-4720
329
An application implementing network manager functionality using this library should pass all incoming
messages to nmUtilProcessIncomingMessage, which will return TRUE if the message was processed as a
ZDO energy scan report. The application should not make any calls to emberEnergyScanRequest(), as the
library assumes all incoming scan reports are unsolicited and indicate unicast failures.
When NM_WARNING_LIMIT reports have been processed within NM_WINDOW_SIZE minutes, the
nmUtilWarningHandler callback, which must be implemented by the application, is invoked. The default
values for these parameters are set in network-manager.h and may be modified using #defines within the
application configuration header.
The application may use the nmUtilWarningHandler callback, along with other application-specific information, to decide if and when to change the channel by calling nmUtilChangeChannelRequest. This
function chooses a new channel from the NM_CHANNEL_MASK parameter using information gathered
over time.
In the event of a network-wide channel change, it is possible that some devices, especially sleepy end
devices, do not receive the broadcast and remain on the old channel. Devices should use the API emberFindAndRejoinNetwork to get back to the right channel.
Two implementations of this library are provided: network-manager.c, and network-manager-lite.c. The
former keeps track of the mean and deviation of the energy on each channel and uses these stats to choose
the channel to change to. This consumes a fair amount of RAM. The latter takes the simpler (and possibly
more effective) approach of just avoiding past bad channels. Application developers are encouraged to use
and modify either of these solutions to take into account their own application-specific needs.
6.55.2
Macro Definition Documentation
6.55.2.1
#define NM WARNING LIMIT
Definition at line 97 of file network-manager.h.
6.55.2.2
#define NM WINDOW SIZE
Definition at line 101 of file network-manager.h.
6.55.2.3
#define NM CHANNEL MASK
Definition at line 107 of file network-manager.h.
6.55.2.4
#define NM WATCHLIST SIZE
Definition at line 113 of file network-manager.h.
6.55.3
Function Documentation
6.55.3.1
void nmUtilWarningHandler ( void )
callback called when unsolicited scan reports hit limit. This callback must be implemented by the application. It is called when the number of unsolicited scan reports received within NM_WINDOW_LIMIT
minutes reaches NM_WARNING_LIMIT.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
330
6.55.3.2 boolean nmUtilProcessIncoming ( EmberApsFrame ∗ apsFrame, int8u messageLength, int8u
∗ message )
Called from the app in emberIncomingMessageHandler. Returns TRUE if and only if the library processed
the message.
Parameters
apsFrame
messageLength
message
6.55.3.3 EmberStatus nmUtilChangeChannelRequest ( void )
Chooses a new channel and broadcasts a ZDO channel change request.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
331
6.56
Serial Communication
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 ∗bytesRead, 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 formatString,...)
void emberSerialBufferTick (void)
void emberSerialFlushRx (int8u port)
Printf Prototypes
These prototypes are for the internal printf implementation, in case it is desired to use it elsewhere. See the
code 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 EM250
120-3016-000-4720
332
6.56.1
Detailed Description
Unless otherwise noted, the EmberNet stack 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. On some
platforms, 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 all
EmberStatus return values. See app/util/serial/serial.h for source code. To use these serial routines, they
must be properly configured.
If the Ember serial library is built using EMBER_SERIAL_USE_STDIO, then the Ember serial code will
redirect to stdio.h. EMBER_SERIAL_USE_STDIO will not consume any of the usual Ember serial library
buffers and does not require use of any of the other EMBER_SERIALx definitions described here. In this
mode, 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 are
stored:
– Buffered mode: Uses stack linked buffers. This method can be more efficient if many messages
received 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 into
the 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 easily
extended. The ports are numbered 0 and 1 and should be accessed using those numbers. The ports can be
set 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 FIFO
mode, the Queue Size is the size of the FIFO and represents the number of bytes that can be waiting for
transmission at any given time. In buffered mode, the Queue Size represents the number of whole messages
that can be waiting for transmission at any given time. A single message is created for each call to any of
the serial APIs.
To specify a Use mode and Queue Size, place declarations in the compiler preprocessor options when
building 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 EM250
120-3016-000-4720
333
– ::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 main
event 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 than
the 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 affect
any code that has tight timing requirements.
If ::EMBER_SERIAL0_BLOCKING or ::EMBER_SERIAL1_BLOCKING is defined, then the call to the
port will block until space is available, guaranteeing that the entire message is sent. Note that in buffered
mode, even if blocking mode is in effect entire messages may be dropped if insufficient stack buffers are
available 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 the
queue 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 invalid
or unused serial port may result in unexplained behavior. In some cases EMBER_ERR_FATAL may be
returned.
6.56.2
Macro Definition Documentation
6.56.2.1
#define emberSerialWriteUsed( port )
Returns the number of bytes (in FIFO mode) or messages (in buffered mode) that are currently queued and
still being sent.
Parameters
port 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 EM250
120-3016-000-4720
334
6.56.3
Typedef Documentation
6.56.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 emPrintfInternal
function below, for performing the actual flushing of a formatted string to a destination such as a serial
port.
Parameters
flushVar,: 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.56.4
Function Documentation
6.56.4.1 EmberStatus emberSerialInit ( int8u port, SerialBaudRate rate, SerialParity parity, int8u
stopBits )
Initializes a serial port to a specific baud rate, parity, and number of stop bits. Eight data bits are always
used.
Parameters
port
rate
parity
stopBits
A serial port number (0 or 1).
The baud rate (see SerialBaudRate).
The parity value (see SerialParity).
The number of stop bits.
Returns
An error code if initialization failed (such as invalid baudrate), or EMBER_SUCCESS.
6.56.4.2 int16u emberSerialReadAvailable ( int8u port )
Returns the number of bytes currently available for reading in the specified RX queue.
Parameters
port A serial port number (0 or 1).
Returns
The number of bytes available.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
335
6.56.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. For
errors other than EMBER_SERIAL_RX_EMPTY multiple bytes of data may have been lost and serial
protocols should attempt to resynchronize.
Parameters
port A serial port number (0 or 1).
dataByte A pointer to storage location for the byte.
Returns
One of the following (see the Main Page):
• 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.56.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. In
the event of an error, some valid data may have already been read before the error occurred, in which case
that data will be in the buffer pointed to by data and the number of bytes successfully read will be placed
in bytesRead.
Parameters
port
data
length
bytesRead
A serial port number (0 or 1).
A pointer to storage location for the data. It must be at least length in size.
The number of bytes to read.
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 NULL, in which case it is ignored.
Returns
One of the following (see the Main Page):
• 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 all the data requested is returned
EmberZNet 4.7.2 API EM250
120-3016-000-4720
336
6.56.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 return
before length bytes is read if a timeout is reached or an error occurs. Returns EMBER_SERIAL_RX_EMPTY if a timeout occurs.
Parameters
port
data
length
bytesRead
firstByteTimeout
subsequentByteTimeout
A serial port number (0 or 1).
A pointer to storage location for the data. It must be at least length in size.
The maximum number of bytes to read.
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 parameter
may be NULL, in which case it is ignored.
The amount of time, in milliseconds, to wait for the first byte to arrive (if the queue
is empty when the function is called). This value must be a minimum of 2 due to the
timer resolution.
The amount of time, in milliseconds, to wait after the previous byte was received for
the next byte to arrive. This value must be a minimum of 2 due to the timer resolution.
Returns
One of the following (see the Main Page):
• EMBER_SERIAL_RX_EMPTY if the timeout was exceeded before the requested amount of
data was read
• 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 all the data requested is returned
6.56.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 converts
to uppercase. Blocks until a line has been read or max has been exceeded. Calls on halResetWatchdog().
Parameters
port 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.
Returns
EMBER_SUCCESS
EmberZNet 4.7.2 API EM250
120-3016-000-4720
337
6.56.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. Always
converts 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.
Parameters
port 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 start
a line read.
Returns
One of the following (see the Main Page):
• 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.56.4.8 int16u emberSerialWriteAvailable ( int8u port )
Returns the number of bytes (in FIFO mode) or messages (in buffered mode) that can currently be queued
to send without blocking or dropping.
Parameters
port A serial port number (0 or 1).
Returns
The number of bytes or messages available for queueing.
6.56.4.9 EmberStatus emberSerialWriteByte ( int8u port, int8u dataByte )
Queues a single byte of data for transmission on the specified port.
Parameters
port A serial port number (0 or 1).
dataByte The byte to be queued.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
338
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.
6.56.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 transmission
on the specified port. Values less than 0xF are always zero padded and queued as "0F".
Parameters
port A serial port number (0 or 1).
dataByte The byte to be converted.
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.
6.56.4.11 EmberStatus emberSerialWriteString ( int8u port, PGM P string )
Queues a string for transmission on the specified port.
Parameters
port A serial port number (0 or 1).
string The string to be queued.
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.
6.56.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
EmberZNet 4.7.2 API EM250
120-3016-000-4720
339
• 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)
Parameters
port A serial port number (0 or 1).
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.
6.56.4.13 XAP2B_PAGEZERO_OFF XAP2B_PAGEZERO_ON EmberStatus emberSerialPrintfLine
( int8u port, PGM P formatString, ... )
Printf for printing on a specified port. Same as emberSerialPrintf() except it prints a carriage return at the
the end of the text.
Parameters
port A serial port number (0 or 1).
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.
6.56.4.14 XAP2B_PAGEZERO_OFF XAP2B_PAGEZERO_ON EmberStatus
emberSerialPrintCarriageReturn ( int8u port )
Prints "\r\n" to the specified serial port.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
340
Parameters
port A serial port number (0 or 1).
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.
6.56.4.15 XAP2B_PAGEZERO_OFF EmberStatus emberSerialPrintfVarArg ( int8u port, PGM P
formatString, va list ap )
Prints a format string with a variable argument list.
Parameters
port A serial port number (0 or 1).
formatString A printf style format string.
ap A variable argument list.
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.
6.56.4.16 EmberStatus emberSerialWriteData ( int8u port, int8u ∗ data, int8u length )
Queues an arbitrary chunk of data for transmission on a specified port.
Parameters
port A serial port number (0 or 1).
data A pointer to data.
length The number of bytes to queue.
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 EM250
120-3016-000-4720
341
6.56.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 arbitrary
initial offset within the linked buffer chain.
Parameters
port
buffer
start
length
A serial port number (0 or 1).
The starting buffer in linked buffer chain.
The offset from first buffer in chain.
The number of bytes to queue.
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.
6.56.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 this
function before serial reinitialization to ensure that transmission is complete.
Parameters
port A serial port number (0 or 1).
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.
6.56.4.19 XAP2B_PAGEZERO_OFF EmberStatus emberSerialGuaranteedPrintf ( int8u port, PGM P
formatString, ... )
A printf routine that takes over the specified serial port and immediately transmits the given data regardless
of 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 cause
for the reset needs to be transmitted first.
Parameters
EmberZNet 4.7.2 API EM250
120-3016-000-4720
342
port A serial port number (0 or 1).
formatString The string to print.
... Formatting specifiers. See emberSerialPrintf() for arguments.
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.
6.56.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, similar
to emberTick(). It frees buffers that are used to queue messages. Note: This function has no effect if FIFO
mode is being used.
6.56.4.21
void emberSerialFlushRx ( int8u port )
Flushes the receive buffer in case none of the incoming serial data is wanted.
Parameters
port A serial port number (0 or 1).
6.56.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 the
passed data into the string.
Parameters
flushHandler,: The name of an internal function, which has parameters matching the function emPrintfFlushHandler above, responsible for flushing a string formatted by this
function, emPrintfInternal, to the appropriate buffer or function that performs
the actual transmission.
port The destination of the flush performed above, most commonly serial port number (0 or
1).
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 EM250
120-3016-000-4720
343
6.57
Eeprom
Macros
•
•
•
•
•
•
#define EEPROM_SIZE
#define EEPROM_TOTAL_SIZE
#define EEPROM_PAGE_SZ
#define EEPROM_IMAGE_END
#define EEPROM_TOTAL_PAGES
#define EEPROM_LAST_PAGE
6.57.1
Detailed Description
The file eeprom.h defines generic EEPROM parameters. Include device specific header file below.
The following is the EEPROM memory map as shipped. Ember reserves a 3kByte section at the top of
memory for the recovery image and a 2kByte section below the recovery image for future use.
Changing EEPROM_SIZE below will change the size of the application image space without changing
the size or relative location of the recovery and reserved sections. See eeprom.c for more information on
modifying EEPROM functionality.
Memory map:
|-------------------|
|
|
| RECOVERY IMAGE
|
| 3kB
|
|-------------------|
|
|
| RESERVED
|
| 2kB
|
|-------------------|
|
|
| APPLICATION IMAGE |
| 123kB
|
|-------------------|
0x1ffff
0x1f400
0x1f3ff
0x1ec00
0x1ebff
0
6.57.2
Macro Definition Documentation
6.57.2.1
#define EEPROM SIZE
Definition at line 47 of file eeprom.h.
6.57.2.2
#define EEPROM TOTAL SIZE
Definition at line 50 of file eeprom.h.
6.57.2.3
#define EEPROM PAGE SZ
Definition at line 51 of file eeprom.h.
6.57.2.4
#define EEPROM IMAGE END
Definition at line 54 of file eeprom.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
344
6.57.2.5
#define EEPROM TOTAL PAGES
Definition at line 55 of file eeprom.h.
6.57.2.6
#define EEPROM LAST PAGE
Definition at line 56 of file eeprom.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
345
6.58
Commands2
Data Structures
• struct EmberCommandEntry
Command entry for a command table.
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
• 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_MANY_COMMAND_ARGUMENTS, EMBER_CMD_ERR_ARGUMENT_OUT_OF_RANGE, EMBER_CMD_ERR_ARGUMENT_SYNTAX_ERROR,
EMBER_CMD_ERR_STRING_TOO_LONG, EMBER_CMD_ERR_NO_BINARY_STRING_TERMINATOR, 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_TYPE }
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 EM250
120-3016-000-4720
346
Variables
• EmberCommandEntry ∗ emberCurrentCommand
• EmberCommandEntry emberCommandTable [ ]
• int8u emberCommandInterpreter2Configuration
Command Table Settings
• #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 command 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 leftPad)
• #define emberCopyKeyArgument(index, keyDataPointer)
• #define emberCopyEui64Argument(index, eui64)
6.58.1
Detailed Description
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 EM250
120-3016-000-4720
347
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 array 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 arguments
the 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 command
input. 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 retrieve command arguments.
The command interpreter does extensive processing and validation of the command input before calling the
function that implements the command. It checks that the number, type, syntax, and range of all arguments
are correct. It performs any conversions necessary (for example, converting integers and strings input
in hexadecimal notation into the corresponding bytes), so that no additional parsing is necessary within
command functions. If there is an error in the command input, emberCommandErrorHandler() is called
rather than a command function.
The command interpreter allows inexact matches of command names. The input command may be either
shorter or longer than the actual command. However, if more than one inexact match is found and there
is no exact match, an error of type EMBER_CMD_ERR_NO_SUCH_COMMAND will be generated. To
disable this feature, define EMBER_REQUIRE_EXACT_COMMAND_NAME in the application configuration header.
6.58.2
Macro Definition Documentation
6.58.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 EM250
120-3016-000-4720
348
6.58.2.2
#define EMBER COMMAND BUFFER LENGTH
The maximum number of arguments a command can have. A nested command counts as an argument.
Definition at line 108 of file command-interpreter2.h.
6.58.2.3
#define EMBER COMMAND INTEPRETER HAS DESCRIPTION FIELD
Whether or not the command entry structure will include descriptions for the commands. This consumes
additional CONST space, which is expensive on the XAP. By default descriptions are not included.
Definition at line 116 of file command-interpreter2.h.
6.58.2.4
#define MAX TOKEN COUNT
Definition at line 123 of file command-interpreter2.h.
6.58.2.5
#define emberCommandEntryAction( name, action, argumentTypes, description )
Definition at line 180 of file command-interpreter2.h.
6.58.2.6
#define emberCommandEntrySubMenu( name, subMenu, description )
Definition at line 184 of file command-interpreter2.h.
6.58.2.7
#define emberCommandEntryTerminator( )
Definition at line 188 of file command-interpreter2.h.
6.58.2.8
#define EMBER COMMAND INTERPRETER CONFIGURATION ECHO
Definition at line 221 of file command-interpreter2.h.
6.58.2.9
#define emberCopyKeyArgument( index, keyDataPointer )
A convenience macro for copying security key arguments to an EmberKeyData pointer.
Definition at line 292 of file command-interpreter2.h.
6.58.2.10
#define emberCopyEui64Argument( index, eui64 )
A convenience macro for copying eui64 arguments to an EmberEUI64.
Definition at line 299 of file command-interpreter2.h.
6.58.2.11
#define emberProcessCommandInput( port )
Process input coming in on the given serial port.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
349
Returns
TRUE if an end of line character was read. If the application uses a command line prompt, this
indicates it is time to print the prompt.
void emberProcessCommandInput(int8u port);
Definition at line 336 of file command-interpreter2.h.
6.58.2.12
#define emberCommandInterpreterEchoOn( )
Turn echo of command line on.
Definition at line 341 of file command-interpreter2.h.
6.58.2.13
#define emberCommandInterpreterEchoOff( )
Turn echo of command line off.
Definition at line 347 of file command-interpreter2.h.
6.58.2.14
#define emberCommandInterpreterIsEchoOn( )
Returns true if echo is on, false otherwise.
Definition at line 353 of file command-interpreter2.h.
6.58.3
Typedef Documentation
6.58.3.1
typedef void(∗ CommandAction)(void)
Definition at line 125 of file command-interpreter2.h.
6.58.4
Enumeration Type Documentation
6.58.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 emberCommandErrorNames[] 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 EM250
120-3016-000-4720
350
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 terminator
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_TYPE
Definition at line 229 of file command-interpreter2.h.
6.58.5
Function Documentation
6.58.5.1 int8u emberCommandArgumentCount ( void )
Returns the number of arguments for the current command.
6.58.5.2 int32u emberUnsignedCommandArgument ( int8u argNum )
Retrieves unsigned integer arguments.
6.58.5.3 int16s emberSignedCommandArgument ( int8u argNum )
Retrieves signed integer arguments.
6.58.5.4 int8u∗ emberStringCommandArgument ( int8s argNum, int8u ∗ length )
Retrieve quoted string or hex string arguments. Hex strings have already been converted into binary. To
retrieve the name of the command itself, use an argNum of -1. For example, to retrieve the first character
of the command, do: int8u firstChar = emberStringCommandArgument(-1, NULL)[0]. If the command is
nested, an index of -2, -3, etc will work to retrieve the higher level command names.
6.58.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 nonzero
but less than maxLength and leftPad is TRUE, leading zeroes are prepended to bring the total length of
the 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 padding
them with zeroes. See emberCopyKeyArgument and emberCopyEui64Argument for convenience macros
for this purpose.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
351
6.58.5.6
void emberCommandActionHandler ( const CommandAction action )
The application may implement this handler. To override the default handler, define EMBER_APPLICATION_HAS_COMMAND_ACTION_HANDLER in the CONFIGURATION_HEADER.
6.58.5.7
void emberCommandErrorHandler ( EmberCommandStatus status )
The application may implement this handler. To override the default handler, define EMBER_APPLICATION_HAS_COMMAND_ERROR_HANDLER in the CONFIGURATION_HEADER. Defining this
will also remove the help functions emberPrintCommandUsage(), emberPrintCommandUsageNotes(), and
emberPrintCommandTable().
6.58.5.8
void emberPrintCommandUsage ( EmberCommandEntry ∗ entry )
6.58.5.9
void emberPrintCommandUsageNotes ( void )
6.58.5.10
void emberPrintCommandTable ( void )
6.58.5.11
void emberCommandReaderInit ( void )
Initialize the command interpreter.
6.58.5.12 boolean emberProcessCommandString ( int8u ∗ input, int8u sizeOrPort )
Process the given string as a command.
6.58.6
Variable Documentation
6.58.6.1 EmberCommandEntry∗ emberCurrentCommand
A pointer to the currently matching command entry. Only valid from within a command function. If the
original command was nested, points to the final (non-nested) command entry.
6.58.6.2 EmberCommandEntry emberCommandTable[ ]
6.58.6.3 int8u emberCommandInterpreter2Configuration
Configuration byte.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
352
Chapter 7
Data Structure Documentation
7.1
EmberAesMmoHashContext Struct Reference
#include <ember-types.h>
Data Fields
• int8u result [EMBER_AES_HASH_BLOCK_SIZE]
• int32u length
7.1.1
Detailed Description
This data structure contains the context data when calculating an AES MMO hash (message digest).
Definition at line 1403 of file ember-types.h.
7.1.2
Field Documentation
7.1.2.1 int8u EmberAesMmoHashContext::result[EMBER_AES_HASH_BLOCK_SIZE]
Definition at line 1404 of file ember-types.h.
7.1.2.2 int32u EmberAesMmoHashContext::length
Definition at line 1405 of file ember-types.h.
The documentation for this struct was generated from the following file:
• ember-types.h
7.2
EmberApsFrame Struct Reference
#include <ember-types.h>
EmberZNet 4.7.2 API EM250
120-3016-000-4720
353
Data Fields
•
•
•
•
•
•
•
int16u profileId
int16u clusterId
int8u sourceEndpoint
int8u destinationEndpoint
EmberApsOption options
int16u groupId
int8u sequence
7.2.1
Detailed Description
An in-memory representation of a ZigBee APS frame of an incoming or outgoing message.
Definition at line 835 of file ember-types.h.
7.2.2
Field Documentation
7.2.2.1 int16u EmberApsFrame::profileId
The application profile ID that describes the format of the message.
Definition at line 837 of file ember-types.h.
7.2.2.2 int16u EmberApsFrame::clusterId
The cluster ID for this message.
Definition at line 839 of file ember-types.h.
7.2.2.3 int8u EmberApsFrame::sourceEndpoint
The source endpoint.
Definition at line 841 of file ember-types.h.
7.2.2.4 int8u EmberApsFrame::destinationEndpoint
The destination endpoint.
Definition at line 843 of file ember-types.h.
7.2.2.5 EmberApsOption EmberApsFrame::options
A bitmask of options from the enumeration above.
Definition at line 845 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
354
7.2.2.6 int16u EmberApsFrame::groupId
The group ID for this message, if it is multicast mode.
Definition at line 847 of file ember-types.h.
7.2.2.7 int8u EmberApsFrame::sequence
The sequence number.
Definition at line 849 of file ember-types.h.
The documentation for this struct was generated from the following file:
• ember-types.h
7.3
EmberBindingTableEntry Struct Reference
#include <ember-types.h>
Data Fields
•
•
•
•
•
•
7.3.1
EmberBindingType type
int8u local
int16u clusterId
int8u remote
EmberEUI64 identifier
int8u networkIndex
Detailed Description
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).
Definition at line 859 of file ember-types.h.
7.3.2
Field Documentation
7.3.2.1 EmberBindingType EmberBindingTableEntry::type
The type of binding.
Definition at line 861 of file ember-types.h.
7.3.2.2 int8u EmberBindingTableEntry::local
The endpoint on the local node.
Definition at line 863 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
355
7.3.2.3 int16u EmberBindingTableEntry::clusterId
A cluster ID that matches one from the local endpoint’s simple descriptor. This cluster ID is set by the
provisioning application to indicate which part an endpoint’s functionality is bound to this particular remote
node and is used to distinguish between unicast and multicast bindings. Note that a binding can be used to
to send messages with any cluster ID, not just that listed in the binding.
Definition at line 871 of file ember-types.h.
7.3.2.4 int8u EmberBindingTableEntry::remote
The endpoint on the remote node (specified by identifier).
Definition at line 873 of file ember-types.h.
7.3.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
Definition at line 878 of file ember-types.h.
7.3.2.6 int8u EmberBindingTableEntry::networkIndex
The index of the network the binding belongs to.
Definition at line 880 of file ember-types.h.
The documentation for this struct was generated from the following file:
• ember-types.h
7.4
EmberCertificateData Struct Reference
#include <ember-types.h>
Data Fields
• int8u contents [EMBER_CERTIFICATE_SIZE]
7.4.1
Detailed Description
This data structure contains the certificate data that is used for Certificate Based Key Exchange (CBKE).
Definition at line 1364 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
356
7.4.2
Field Documentation
7.4.2.1 int8u EmberCertificateData::contents[EMBER_CERTIFICATE_SIZE]
Definition at line 1366 of file ember-types.h.
The documentation for this struct was generated from the following file:
• ember-types.h
7.5
EmberCommandEntry Struct Reference
#include <command-interpreter.h>
Data Fields
•
•
•
•
•
PGM_P longName
CommandAction action
PGM_P argumentTypes
PGM_P description
PGM_P name
7.5.1
Detailed Description
Command entry for a command table.
Definition at line 108 of file command-interpreter.h.
7.5.2
Field Documentation
7.5.2.1
PGM P EmberCommandEntry::longName
Use letters, digits, and underscores, ’_’, for the long command name. Command names are case-sensitive.
Definition at line 115 of file command-interpreter.h.
7.5.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 nested
command, then action field has to be set to NULL.
Definition at line 119 of file command-interpreter.h.
7.5.2.3
PGM P EmberCommandEntry::argumentTypes
String that specifies the number and types of arguments the command accepts. The argument specifiers
are:
EmberZNet 4.7.2 API EM250
120-3016-000-4720
357
• 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 ’,"",’ in
buffer 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 16
then all integers are read as hexidecimal. If integerBase is 10 then a decimal is the default and a 0x prefix
indicates a hexidecimal integer.
In case of normal (non-nested) commands, argumentTypes is a string that specifies the number and types
of 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 be
entered in hex by using curly braces, for example: { 08 A1 f2 }. There must be an even number of
hex 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 command 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 either
decimal 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 EmberCommandEntry array.
Definition at line 141 of file command-interpreter.h.
7.5.2.4
PGM P EmberCommandEntry::description
A description of the command.
Definition at line 144 of file command-interpreter.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
358
7.5.2.5
PGM P EmberCommandEntry::name
Use letters, digits, and underscores, ’_’, for the command name. Command names are case-sensitive.
Definition at line 137 of file command-interpreter2.h.
The documentation for this struct was generated from the following files:
• command-interpreter.h
• command-interpreter2.h
7.6
EmberCommandStateS Struct Reference
#include <command-interpreter.h>
Data Fields
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
7.6.1
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
Detailed Description
The command state structure. Using a structure allows commands to be read from multiple sources.
Definition at line 176 of file command-interpreter.h.
7.6.2
Field Documentation
7.6.2.1 EmberCommandEntry∗ EmberCommandStateS::commands
The table of commands created in the application.
Definition at line 179 of file command-interpreter.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
359
7.6.2.2
void(∗ EmberCommandStateS::errorHandler)(struct EmberCommandStateS ∗state)
Definition at line 180 of file command-interpreter.h.
7.6.2.3 ArgTypeU∗ EmberCommandStateS::arguments
Arguments filled in by the interpreter.
Definition at line 182 of file command-interpreter.h.
7.6.2.4 int8u EmberCommandStateS::maximumArguments
Definition at line 184 of file command-interpreter.h.
7.6.2.5 int8u EmberCommandStateS::integerBase
Determines whether integers are parsed using base 10 or base 16. Valid values are only 10 or 16.
Definition at line 188 of file command-interpreter.h.
7.6.2.6 int8u EmberCommandStateS::argumentCount
Set by the interpreter for use by the command function.
Definition at line 190 of file command-interpreter.h.
7.6.2.7 int8u EmberCommandStateS::state
Finite-state machine’s current state.
Definition at line 195 of file command-interpreter.h.
7.6.2.8 int8u EmberCommandStateS::error
First error found in this command.
Definition at line 197 of file command-interpreter.h.
7.6.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.
Definition at line 201 of file command-interpreter.h.
7.6.2.10 int16u EmberCommandStateS::commandIndex
Definition at line 203 of file command-interpreter.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
360
7.6.2.11
PGM P EmberCommandStateS::argumentSpecs
Stepped forward as arguments are read.
Definition at line 205 of file command-interpreter.h.
7.6.2.12 int8u EmberCommandStateS::stringLength
Bytes read in so far.
Definition at line 207 of file command-interpreter.h.
7.6.2.13 int8u EmberCommandStateS::binaryLength
Remaining bytes in the binary block.
Definition at line 209 of file command-interpreter.h.
7.6.2.14 EmberMessageBuffer EmberCommandStateS::stringBuffer
Definition at line 211 of file command-interpreter.h.
7.6.2.15 ArgTypeU EmberCommandStateS::integerValue
Definition at line 213 of file command-interpreter.h.
7.6.2.16 int8u EmberCommandStateS::integerSign
Valid values are ’+’ or ’-’.
Definition at line 215 of file command-interpreter.h.
7.6.2.17 int8u EmberCommandStateS::currentIntegerBase
Definition at line 217 of file command-interpreter.h.
7.6.2.18 EmberCommandEntry∗ EmberCommandStateS::currentCommands
Used for pointing to a table of subcommands.
Definition at line 220 of file command-interpreter.h.
The documentation for this struct was generated from the following file:
• command-interpreter.h
7.7
EmberCurrentSecurityState Struct Reference
#include <ember-types.h>
EmberZNet 4.7.2 API EM250
120-3016-000-4720
361
Data Fields
• EmberCurrentSecurityBitmask bitmask
• EmberEUI64 trustCenterLongAddress
7.7.1
Detailed Description
This describes the security features used by the stack for a joined device.
Definition at line 1657 of file ember-types.h.
7.7.2
Field Documentation
7.7.2.1 EmberCurrentSecurityBitmask EmberCurrentSecurityState::bitmask
This bitmask indicates the security features currently in use on this node.
Definition at line 1660 of file ember-types.h.
7.7.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).
Definition at line 1664 of file ember-types.h.
The documentation for this struct was generated from the following file:
• ember-types.h
7.8
EmberEndpoint Struct Reference
#include <stack-info.h>
Data Fields
•
•
•
•
7.8.1
int8u endpoint
EmberEndpointDescription PGM ∗ description
int16u PGM ∗ inputClusterList
int16u PGM ∗ outputClusterList
Detailed Description
Gives the endpoint information for a particular endpoint.
Definition at line 283 of file stack-info.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
362
7.8.2
Field Documentation
7.8.2.1 int8u EmberEndpoint::endpoint
An endpoint of the application on this node.
Definition at line 285 of file stack-info.h.
7.8.2.2 EmberEndpointDescription PGM∗ EmberEndpoint::description
The endpoint’s description.
Definition at line 287 of file stack-info.h.
7.8.2.3 int16u PGM∗ EmberEndpoint::inputClusterList
Input clusters the endpoint will accept.
Definition at line 289 of file stack-info.h.
7.8.2.4 int16u PGM∗ EmberEndpoint::outputClusterList
Output clusters the endpoint may send.
Definition at line 291 of file stack-info.h.
The documentation for this struct was generated from the following file:
• stack-info.h
7.9
EmberEndpointDescription Struct Reference
#include <stack-info.h>
Data Fields
•
•
•
•
•
int16u profileId
int16u deviceId
int8u deviceVersion
int8u inputClusterCount
int8u outputClusterCount
7.9.1
Detailed Description
Endpoint information (a ZigBee Simple Descriptor).
This is a ZigBee Simple Descriptor and contains information about an endpoint. This information is shared
with other nodes in the network by the ZDO.
Definition at line 267 of file stack-info.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
363
7.9.2
Field Documentation
7.9.2.1 int16u EmberEndpointDescription::profileId
Identifies the endpoint’s application profile.
Definition at line 269 of file stack-info.h.
7.9.2.2 int16u EmberEndpointDescription::deviceId
The endpoint’s device ID within the application profile.
Definition at line 271 of file stack-info.h.
7.9.2.3 int8u EmberEndpointDescription::deviceVersion
The endpoint’s device version.
Definition at line 273 of file stack-info.h.
7.9.2.4 int8u EmberEndpointDescription::inputClusterCount
The number of input clusters.
Definition at line 275 of file stack-info.h.
7.9.2.5 int8u EmberEndpointDescription::outputClusterCount
The number of output clusters.
Definition at line 277 of file stack-info.h.
The documentation for this struct was generated from the following file:
• stack-info.h
7.10
EmberEventControl Struct Reference
#include <ember-types.h>
Data Fields
• EmberEventUnits status
• EmberTaskId taskid
• int32u timeToExecute
7.10.1
Detailed Description
Control structure for events.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
364
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.
Definition at line 1130 of file ember-types.h.
7.10.2
Field Documentation
7.10.2.1 EmberEventUnits EmberEventControl::status
The event’s status, either inactive or the units for timeToExecute.
Definition at line 1132 of file ember-types.h.
7.10.2.2 EmberTaskId EmberEventControl::taskid
The id of the task this event belongs to.
Definition at line 1134 of file ember-types.h.
7.10.2.3 int32u EmberEventControl::timeToExecute
How long before the event fires. Units are always in milliseconds
Definition at line 1138 of file ember-types.h.
The documentation for this struct was generated from the following file:
• ember-types.h
7.11
EmberInitialSecurityState Struct Reference
#include <ember-types.h>
Data Fields
•
•
•
•
•
int16u bitmask
EmberKeyData preconfiguredKey
EmberKeyData networkKey
int8u networkKeySequenceNumber
EmberEUI64 preconfiguredTrustCenterEui64
7.11.1
Detailed Description
This describes the Initial Security features and requirements that will be used when forming or joining the
network.
Definition at line 1577 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
365
7.11.2
Field Documentation
7.11.2.1 int16u EmberInitialSecurityState::bitmask
This bitmask enumerates which security features should be used, as well as the presence of valid data
within other elements of the EmberInitialSecurityState data structure. For more details see the EmberInitialSecurityBitmask.
Definition at line 1582 of file ember-types.h.
7.11.2.2 EmberKeyData EmberInitialSecurityState::preconfiguredKey
This is the pre-configured key that can used by devices when joining the network if the Trust Center does
not send the initial security data in-the-clear. For the Trust Center, it will be the global link key and must be
set regardless of whether joining devices are expected to have a pre-configured Link Key. This parameter
will only be used if the EmberInitialSecurityState::bitmask sets the bit indicating EMBER_HAVE_PRECONFIGURED_KEY
Definition at line 1591 of file ember-types.h.
7.11.2.3 EmberKeyData EmberInitialSecurityState::networkKey
This is the Network Key used when initially forming the network. This must be set on the Trust Center. It
is not needed for devices joining the network. This parameter will only be used if the EmberInitialSecurityState::bitmask sets the bit indicating EMBER_HAVE_NETWORK_KEY.
Definition at line 1597 of file ember-types.h.
7.11.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. It
is used to indicate a particular of the network key for updating and switching. This parameter will only be
used if the EMBER_HAVE_NETWORK_KEY is set. Generally it should be set to 0 when forming the
network; joining devices can ignore this value.
Definition at line 1604 of file ember-types.h.
7.11.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 set
prior to joining the network and instead it is learned during the joining message exchange. This field
is 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 using
commissioning mode. It is required to be in little-endian format.
Definition at line 1612 of file ember-types.h.
The documentation for this struct was generated from the following file:
• ember-types.h
EmberZNet 4.7.2 API EM250
120-3016-000-4720
366
7.12
EmberKeyData Struct Reference
#include <ember-types.h>
Data Fields
• int8u contents [EMBER_ENCRYPTION_KEY_SIZE]
7.12.1
Detailed Description
This data structure contains the key data that is passed into various other functions.
Definition at line 1357 of file ember-types.h.
7.12.2
Field Documentation
7.12.2.1 int8u EmberKeyData::contents[EMBER_ENCRYPTION_KEY_SIZE]
This is the key byte data.
Definition at line 1359 of file ember-types.h.
The documentation for this struct was generated from the following file:
• ember-types.h
7.13
EmberKeyStruct Struct Reference
#include <ember-types.h>
Data Fields
•
•
•
•
•
•
•
EmberKeyStructBitmask bitmask
EmberKeyType type
EmberKeyData key
int32u outgoingFrameCounter
int32u incomingFrameCounter
int8u sequenceNumber
EmberEUI64 partnerEUI64
7.13.1
Detailed Description
This describes a one of several different types of keys and its associated data.
Definition at line 1730 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
367
7.13.2
Field Documentation
7.13.2.1 EmberKeyStructBitmask EmberKeyStruct::bitmask
This bitmask indicates whether various fields in the structure contain valid data. It also contains the index
of the network the key belongs to.
Definition at line 1734 of file ember-types.h.
7.13.2.2 EmberKeyType EmberKeyStruct::type
This indicates the type of the security key.
Definition at line 1736 of file ember-types.h.
7.13.2.3 EmberKeyData EmberKeyStruct::key
This is the actual key data.
Definition at line 1738 of file ember-types.h.
7.13.2.4 int32u EmberKeyStruct::outgoingFrameCounter
This is the outgoing frame counter associated with the key. It will contain valid data based on the EmberKeyStructBitmask.
Definition at line 1741 of file ember-types.h.
7.13.2.5 int32u EmberKeyStruct::incomingFrameCounter
This is the incoming frame counter associated with the key. It will contain valid data based on the EmberKeyStructBitmask.
Definition at line 1744 of file ember-types.h.
7.13.2.6 int8u EmberKeyStruct::sequenceNumber
This is the sequence number associated with the key. It will contain valid data based on the EmberKeyStructBitmask.
Definition at line 1747 of file ember-types.h.
7.13.2.7 EmberEUI64 EmberKeyStruct::partnerEUI64
This is the Partner EUI64 associated with the key. It will contain valid data based on the EmberKeyStructBitmask.
Definition at line 1750 of file ember-types.h.
The documentation for this struct was generated from the following file:
• ember-types.h
EmberZNet 4.7.2 API EM250
120-3016-000-4720
368
7.14
EmberMacFilterMatchStruct Struct Reference
#include <ember-types.h>
Data Fields
• int8u filterIndexMatch
• EmberMacPassthroughType legacyPassthroughType
• EmberMessageBuffer message
7.14.1
Detailed Description
This structure indicates a matching raw MAC message has been received by the application configured
MAC filters.
Definition at line 1975 of file ember-types.h.
7.14.2
Field Documentation
7.14.2.1 int8u EmberMacFilterMatchStruct::filterIndexMatch
Definition at line 1976 of file ember-types.h.
7.14.2.2 EmberMacPassthroughType EmberMacFilterMatchStruct::legacyPassthroughType
Definition at line 1977 of file ember-types.h.
7.14.2.3 EmberMessageBuffer EmberMacFilterMatchStruct::message
Definition at line 1978 of file ember-types.h.
The documentation for this struct was generated from the following file:
• ember-types.h
7.15
EmberMessageDigest Struct Reference
#include <ember-types.h>
Data Fields
• int8u contents [EMBER_AES_HASH_BLOCK_SIZE]
7.15.1
Detailed Description
This data structure contains an AES-MMO Hash (the message digest).
Definition at line 1396 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
369
7.15.2
Field Documentation
7.15.2.1 int8u EmberMessageDigest::contents[EMBER_AES_HASH_BLOCK_SIZE]
Definition at line 1397 of file ember-types.h.
The documentation for this struct was generated from the following file:
• ember-types.h
7.16
EmberMfgSecurityStruct Struct Reference
#include <ember-types.h>
Data Fields
• EmberKeySettings keySettings
7.16.1
Detailed Description
This structure is used to get/set the security config that is stored in manufacturing tokens.
Definition at line 1892 of file ember-types.h.
7.16.2
Field Documentation
7.16.2.1 EmberKeySettings EmberMfgSecurityStruct::keySettings
Definition at line 1893 of file ember-types.h.
The documentation for this struct was generated from the following file:
• ember-types.h
7.17
EmberMulticastTableEntry Struct Reference
#include <ember-types.h>
Data Fields
• EmberMulticastId multicastId
• int8u endpoint
• int8u networkIndex
EmberZNet 4.7.2 API EM250
120-3016-000-4720
370
7.17.1
Detailed Description
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.
Definition at line 948 of file ember-types.h.
7.17.2
Field Documentation
7.17.2.1 EmberMulticastId EmberMulticastTableEntry::multicastId
The multicast group ID.
Definition at line 950 of file ember-types.h.
7.17.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 multicast
groups).
Definition at line 954 of file ember-types.h.
7.17.2.3 int8u EmberMulticastTableEntry::networkIndex
The network index of the network the entry is related to.
Definition at line 956 of file ember-types.h.
The documentation for this struct was generated from the following file:
• ember-types.h
7.18
EmberNeighborTableEntry Struct Reference
#include <ember-types.h>
Data Fields
•
•
•
•
•
•
int16u shortId
int8u averageLqi
int8u inCost
int8u outCost
int8u age
EmberEUI64 longId
7.18.1
Detailed Description
Defines an entry in the neighbor table.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
371
A neighbor table entry stores information about the reliability of RF links to and from neighboring nodes.
Definition at line 889 of file ember-types.h.
7.18.2
Field Documentation
7.18.2.1 int16u EmberNeighborTableEntry::shortId
The neighbor’s two byte network id.
Definition at line 891 of file ember-types.h.
7.18.2.2 int8u EmberNeighborTableEntry::averageLqi
An exponentially weighted moving average of the link quality values of incoming packets from this neighbor as reported by the PHY.
Definition at line 894 of file ember-types.h.
7.18.2.3 int8u EmberNeighborTableEntry::inCost
The incoming cost for this neighbor, computed from the average LQI. Values range from 1 for a good link
to 7 for a bad link.
Definition at line 897 of file ember-types.h.
7.18.2.4 int8u EmberNeighborTableEntry::outCost
The outgoing cost for this neighbor, obtained from the most recently received neighbor exchange message
from the neighbor. A value of zero means that a neighbor exchange message from the neighbor has not
been received recently enough, or that our id was not present in the most recently received one. EmberZNet
Pro only.
Definition at line 904 of file ember-types.h.
7.18.2.5 int8u EmberNeighborTableEntry::age
In EmberZNet Pro, the number of aging periods elapsed since a neighbor exchange message was last
received 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 16
seconds.
Definition at line 910 of file ember-types.h.
7.18.2.6 EmberEUI64 EmberNeighborTableEntry::longId
The 8 byte EUI64 of the neighbor.
Definition at line 912 of file ember-types.h.
The documentation for this struct was generated from the following file:
• ember-types.h
EmberZNet 4.7.2 API EM250
120-3016-000-4720
372
7.19
EmberNetworkInitStruct Struct Reference
#include <ember-types.h>
Data Fields
• EmberNetworkInitBitmask bitmask
7.19.1
Detailed Description
Defines the network initialization configuration that should be used when emberNetworkInitExtended() is
called by the application.
Definition at line 387 of file ember-types.h.
7.19.2
Field Documentation
7.19.2.1 EmberNetworkInitBitmask EmberNetworkInitStruct::bitmask
Definition at line 388 of file ember-types.h.
The documentation for this struct was generated from the following file:
• ember-types.h
7.20
EmberNetworkParameters Struct Reference
#include <ember-types.h>
Data Fields
•
•
•
•
•
•
•
•
int8u extendedPanId [8]
int16u panId
int8s radioTxPower
int8u radioChannel
EmberJoinMethod joinMethod
EmberNodeId nwkManagerId
int8u nwkUpdateId
int32u channels
7.20.1
Detailed Description
Holds network parameters.
For information about power settings and radio channels, see the technical specification for the RF communication module in your Developer Kit.
Definition at line 790 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
373
7.20.2
Field Documentation
7.20.2.1 int8u EmberNetworkParameters::extendedPanId[8]
The network’s extended PAN identifier.
Definition at line 792 of file ember-types.h.
7.20.2.2 int16u EmberNetworkParameters::panId
The network’s PAN identifier.
Definition at line 794 of file ember-types.h.
7.20.2.3 int8s EmberNetworkParameters::radioTxPower
A power setting, in dBm.
Definition at line 796 of file ember-types.h.
7.20.2.4 int8u EmberNetworkParameters::radioChannel
A radio channel. Be sure to specify a channel supported by the radio.
Definition at line 798 of file ember-types.h.
7.20.2.5 EmberJoinMethod EmberNetworkParameters::joinMethod
Join method: The protocol messages used to establish an initial parent. It is ignored when forming a ZigBee
network, or when querying the stack for its network parameters.
Definition at line 803 of file ember-types.h.
7.20.2.6 EmberNodeId EmberNetworkParameters::nwkManagerId
NWK Manager ID. The ID of the network manager in the current network. This may only be set at joining
when using EMBER_USE_NWK_COMMISSIONING as the join method.
Definition at line 809 of file ember-types.h.
7.20.2.7 int8u EmberNetworkParameters::nwkUpdateId
NWK Update ID. The value of the ZigBee nwkUpdateId known by the stack. This is used to determine the
newest instance of the network after a PAN ID or channel change. This may only be set at joining when
using EMBER_USE_NWK_COMMISSIONING as the join method.
Definition at line 815 of file ember-types.h.
7.20.2.8 int32u EmberNetworkParameters::channels
NWK channel mask. The list of preferred channels that the NWK manager has told this device to use when
searching for the network. This may only be set at joining when using EMBER_USE_NWK_COMMISSIONING as the join method.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
374
Definition at line 821 of file ember-types.h.
The documentation for this struct was generated from the following file:
• ember-types.h
7.21
EmberPrivateKeyData Struct Reference
#include <ember-types.h>
Data Fields
• int8u contents [EMBER_PRIVATE_KEY_SIZE]
7.21.1
Detailed Description
This data structure contains the private key data that is used for Certificate Based Key Exchange (CBKE).
Definition at line 1377 of file ember-types.h.
7.21.2
Field Documentation
7.21.2.1 int8u EmberPrivateKeyData::contents[EMBER_PRIVATE_KEY_SIZE]
Definition at line 1378 of file ember-types.h.
The documentation for this struct was generated from the following file:
• ember-types.h
7.22
EmberPublicKeyData Struct Reference
#include <ember-types.h>
Data Fields
• int8u contents [EMBER_PUBLIC_KEY_SIZE]
7.22.1
Detailed Description
This data structure contains the public key data that is used for Certificate Based Key Exchange (CBKE).
Definition at line 1371 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
375
7.22.2
Field Documentation
7.22.2.1 int8u EmberPublicKeyData::contents[EMBER_PUBLIC_KEY_SIZE]
Definition at line 1372 of file ember-types.h.
The documentation for this struct was generated from the following file:
• ember-types.h
7.23
EmberRouteTableEntry Struct Reference
#include <ember-types.h>
Data Fields
•
•
•
•
•
•
int16u destination
int16u nextHop
int8u status
int8u age
int8u concentratorType
int8u routeRecordState
7.23.1
Detailed Description
Defines an entry in the route table.
A route table entry stores information about the next hop along the route to the destination.
Definition at line 920 of file ember-types.h.
7.23.2
Field Documentation
7.23.2.1 int16u EmberRouteTableEntry::destination
The short id of the destination.
Definition at line 922 of file ember-types.h.
7.23.2.2 int16u EmberRouteTableEntry::nextHop
The short id of the next hop to this destination.
Definition at line 924 of file ember-types.h.
7.23.2.3 int8u EmberRouteTableEntry::status
Indicates whether this entry is active (0), being discovered (1), or unused (3).
Definition at line 927 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
376
7.23.2.4 int8u EmberRouteTableEntry::age
The number of seconds since this route entry was last used to send a packet.
Definition at line 930 of file ember-types.h.
7.23.2.5 int8u EmberRouteTableEntry::concentratorType
Indicates whether this destination is a High RAM Concentrator (2), a Low RAM Concentrator (1), or not a
concentrator (0).
Definition at line 933 of file ember-types.h.
7.23.2.6 int8u EmberRouteTableEntry::routeRecordState
For a High RAM Concentrator, indicates whether a route record is needed (2), has been sent (1), or is no
long needed (0) because a source routed message from the concentrator has been received.
Definition at line 938 of file ember-types.h.
The documentation for this struct was generated from the following file:
• ember-types.h
7.24
EmberSignatureData Struct Reference
#include <ember-types.h>
Data Fields
• int8u contents [EMBER_SIGNATURE_SIZE]
7.24.1
Detailed Description
This data structure contains a DSA signature. It is the bit concatenation of the ’r’ and ’s’ components of
the signature.
Definition at line 1390 of file ember-types.h.
7.24.2
Field Documentation
7.24.2.1 int8u EmberSignatureData::contents[EMBER_SIGNATURE_SIZE]
Definition at line 1391 of file ember-types.h.
The documentation for this struct was generated from the following file:
• ember-types.h
EmberZNet 4.7.2 API EM250
120-3016-000-4720
377
7.25
EmberSmacData Struct Reference
#include <ember-types.h>
Data Fields
• int8u contents [EMBER_SMAC_SIZE]
7.25.1
Detailed Description
This data structure contains the Shared Message Authentication Code (SMAC) data that is used for Certificate Based Key Exchange (CBKE).
Definition at line 1383 of file ember-types.h.
7.25.2
Field Documentation
7.25.2.1 int8u EmberSmacData::contents[EMBER_SMAC_SIZE]
Definition at line 1384 of file ember-types.h.
The documentation for this struct was generated from the following file:
• ember-types.h
7.26
EmberTaskControl Struct Reference
#include <ember-types.h>
Data Fields
• int32u nextEventTime
• EmberEventData ∗ events
• boolean busy
7.26.1
Detailed Description
Control structure for tasks.
This structure should not be accessed directly.
Definition at line 1176 of file ember-types.h.
7.26.2
Field Documentation
7.26.2.1 int32u EmberTaskControl::nextEventTime
Definition at line 1178 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
378
7.26.2.2 EmberEventData∗ EmberTaskControl::events
Definition at line 1180 of file ember-types.h.
7.26.2.3 boolean EmberTaskControl::busy
Definition at line 1182 of file ember-types.h.
The documentation for this struct was generated from the following file:
• ember-types.h
7.27
EmberVersion Struct Reference
#include <ember-types.h>
Data Fields
•
•
•
•
•
•
int16u build
int8u major
int8u minor
int8u patch
int8u special
EmberVersionType type
7.27.1
Detailed Description
Version struct containing all version information.
Definition at line 55 of file ember-types.h.
7.27.2
Field Documentation
7.27.2.1 int16u EmberVersion::build
Definition at line 56 of file ember-types.h.
7.27.2.2 int8u EmberVersion::major
Definition at line 57 of file ember-types.h.
7.27.2.3 int8u EmberVersion::minor
Definition at line 58 of file ember-types.h.
7.27.2.4 int8u EmberVersion::patch
Definition at line 59 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
379
7.27.2.5 int8u EmberVersion::special
Definition at line 60 of file ember-types.h.
7.27.2.6 EmberVersionType EmberVersion::type
Definition at line 61 of file ember-types.h.
The documentation for this struct was generated from the following file:
• ember-types.h
7.28
EmberZigbeeNetwork Struct Reference
#include <ember-types.h>
Data Fields
•
•
•
•
•
•
int16u panId
int8u channel
boolean allowingJoin
int8u extendedPanId [8]
int8u stackProfile
int8u nwkUpdateId
7.28.1
Detailed Description
Defines a ZigBee network and the associated parameters.
Definition at line 354 of file ember-types.h.
7.28.2
Field Documentation
7.28.2.1 int16u EmberZigbeeNetwork::panId
Definition at line 355 of file ember-types.h.
7.28.2.2 int8u EmberZigbeeNetwork::channel
Definition at line 356 of file ember-types.h.
7.28.2.3 boolean EmberZigbeeNetwork::allowingJoin
Definition at line 357 of file ember-types.h.
7.28.2.4 int8u EmberZigbeeNetwork::extendedPanId[8]
Definition at line 358 of file ember-types.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
380
7.28.2.5 int8u EmberZigbeeNetwork::stackProfile
Definition at line 359 of file ember-types.h.
7.28.2.6 int8u EmberZigbeeNetwork::nwkUpdateId
Definition at line 360 of file ember-types.h.
The documentation for this struct was generated from the following file:
• ember-types.h
7.29
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
7.29.1
Detailed Description
A struct for keeping track of all of the header info.
Definition at line 51 of file ami-inter-pan.h.
7.29.2
Field Documentation
7.29.2.1 int8u InterPanHeader::messageType
Definition at line 52 of file ami-inter-pan.h.
7.29.2.2 int16u InterPanHeader::panId
Definition at line 57 of file ami-inter-pan.h.
7.29.2.3 boolean InterPanHeader::hasLongAddress
Definition at line 58 of file ami-inter-pan.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
381
7.29.2.4 EmberNodeId InterPanHeader::shortAddress
Definition at line 59 of file ami-inter-pan.h.
7.29.2.5 EmberEUI64 InterPanHeader::longAddress
Definition at line 60 of file ami-inter-pan.h.
7.29.2.6 int16u InterPanHeader::profileId
Definition at line 63 of file ami-inter-pan.h.
7.29.2.7 int16u InterPanHeader::clusterId
Definition at line 64 of file ami-inter-pan.h.
7.29.2.8 int16u InterPanHeader::groupId
Definition at line 65 of file ami-inter-pan.h.
The documentation for this struct was generated from the following file:
• ami-inter-pan.h
EmberZNet 4.7.2 API EM250
120-3016-000-4720
382
Chapter 8
File Documentation
8.1
EM250 API.top File Reference
8.1.1
Detailed Description
Starting page for the Ember API documentation for the EM250 exclusively for building documentation.
This file is used by Doxygen to generate the main page for the Ember API documentation, EM250.
Definition in file _EM250_API.top.
8.2
EM250 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 EM250
120-3016-000-4720
383
• void halInternalSleepAdc (void)
• EmberStatus halStartAdcConversion (ADCUser id, ADCReferenceType reference, ADCChannelType 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)
8.3.1
Detailed Description
Header for A/D converter. See ADC Control for documentation.
Definition in file adc.h.
8.4
00001
00039
00040
00041
00042
00043
00051
00052
00053
00054
00055
00056
00057
00059
00061
00063
00064
00065
00069
00070
00073
00074
00077
00078
00081
00082
00083
00084
00085
00086
00087
00088
00089
00090
00091
00092
00093
00094
00095
00100
00101
00102
00106
00107
00108
00139
adc.h
#ifndef __ADC_H__
#define __ADC_H__
#ifdef DOXYGEN_SHOULD_SKIP_THIS
enum ADCUser
#else
// A type for the ADC User enumeration.
typedef int8u ADCUser;
enum
#endif //DOXYGEN_SHOULD_SKIP_THIS
{
ADC_USER_LQI = 0,
ADC_USER_APP = 1,
ADC_USER_APP2 = 2
};
#define NUM_ADC_USERS 3 // make sure to update if the above is adjusted
typedef int8u ADCChannelType;
typedef int8u ADCReferenceType;
typedef int8u ADCRateType;
#if defined(AVR_ATMEGA) || defined(EMBER_TEST)
#include "avr-atmega/adc.h"
#elif defined(XAP2B)
#include "xap2b/adc.h"
#elif defined(CORTEXM3)
#include "cortexm3/adc.h"
#else
// platform that doesn’t have ADC support
#endif
void halInternalInitAdc(void);
void halInternalSleepAdc(void);
EmberStatus halStartAdcConversion(ADCUser
id,
00140
ADCReferenceType reference,
00141
ADCChannelType channel,
00142
ADCRateType rate);
00143
00164 EmberStatus halRequestAdcData(ADCUser id,
EmberZNet 4.7.2 API EM250
120-3016-000-4720
384
int16u *value);
00165
00166
00184 EmberStatus halReadAdcBlocking(ADCUser id,
int16u *value);
00185
00186
00203 EmberStatus halAdcCalibrate(ADCUser id);
00204
00205
00217 int16s halConvertValueToVolts(int16u value);
00218
00219
00228 void emberCalibrateVref(void);
00229
00230
00231 #endif // __ADC_H__
00232
8.5
adc.h File Reference
Enumerations
• enum { ADC_REF_INT }
• enum {
ADC_CONVERSION_TIME_US_32, ADC_CONVERSION_TIME_US_64, ADC_CONVERSION_TIME_US_128, ADC_CONVERSION_TIME_US_256,
ADC_CONVERSION_TIME_US_512, ADC_CONVERSION_TIME_US_1024, ADC_CONVERSION_TIME_US_2048, ADC_CONVERSION_TIME_US_4096 }
• enum {
ADC_SOURCE_ADC0_GND, ADC_SOURCE_ADC1_GND, ADC_SOURCE_ADC2_GND, ADC_SOURCE_ADC3_GND,
ADC_SOURCE_VDD_PADS_GND, ADC_SOURCE_VDD_GND, ADC_SOURCE_VGND, ADC_SOURCE_VREF,
ADC_SOURCE_ADC0_ADC1, ADC_SOURCE_ADC2_ADC3 }
8.5.1
Detailed Description
Header for EM2xx A/D converter. See ADC Control for documentation.
Definition in file xap2b/adc.h.
8.6
00001
00009
00010
00011
00012
00013
00014
00015
00016
00017
00026
00028
00029
00030
00031
00034
00036
xap2b/adc.h
#ifndef __EM2XX_ADC_H__
#define __EM2XX_ADC_H__
#ifndef DOXYGEN_SHOULD_SKIP_THIS
#ifndef __ADC_H__
#error do not include this file directly - include micro/adc.h
#endif
#endif
enum {
ADC_REF_INT
};
= 42
enum {
ADC_CONVERSION_TIME_US_32
EmberZNet 4.7.2 API EM250
= 0x0,
120-3016-000-4720
385
00038
00040
00042
00044
00046
00048
00050
00051
00052
00053
00056
00057
00059
00061
00063
00065
00067
00069
00071
00073
00075
00077
00078
00079
00080
00084
8.7
ADC_CONVERSION_TIME_US_64
ADC_CONVERSION_TIME_US_128
ADC_CONVERSION_TIME_US_256
ADC_CONVERSION_TIME_US_512
ADC_CONVERSION_TIME_US_1024
ADC_CONVERSION_TIME_US_2048
ADC_CONVERSION_TIME_US_4096
=
=
=
=
=
=
=
0x1,
0x2,
0x3,
0x4,
0x5,
0x6,
0x7,
};
enum
{
ADC_SOURCE_ADC0_GND
ADC_SOURCE_ADC1_GND
ADC_SOURCE_ADC2_GND
ADC_SOURCE_ADC3_GND
ADC_SOURCE_VDD_PADS_GND
ADC_SOURCE_VDD_GND
ADC_SOURCE_VGND
ADC_SOURCE_VREF
ADC_SOURCE_ADC0_ADC1
ADC_SOURCE_ADC2_ADC3
};
=
=
=
=
=
=
=
=
=
=
0x0,
0x1,
0x2,
0x3,
0x4,
0x5,
0x7,
0x8,
0x9,
0xA
#endif //__EM2XX_ADC_H__
ami-inter-pan.h File Reference
Data Structures
• struct InterPanHeader
A 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
Functions
• EmberMessageBuffer makeInterPanMessage (InterPanHeader ∗headerData, EmberMessageBuffer
payload)
• int8u parseInterPanMessage (EmberMessageBuffer message, int8u startOffset, InterPanHeader ∗headerData)
8.7.1
Detailed Description
Utilities for sending and receiving ZigBee AMI InterPAN messages. See Sending and Receiving Messages
for documentation.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
386
Deprecated The ami-inter-pan library is deprecated and will be removed in a future release. Similar
functionality is available in the Inter-PAN plugin in Application Framework.
Definition in file ami-inter-pan.h.
8.8
00001
00019
00020
00021
00022
00023
00024
00025
00026
00027
00028
00029
00030
00031
00032
00033
00034
00035
00036
00037
00038
00039
00040
00041
00042
00043
00044
00045
00046
00047
00051
00052
00053
00054
00055
00056
00057
00058
00059
00060
00061
00062
00063
00064
00065
ami-inter-pan.h
#ifndef AMI_INTER_PAN_H
#define AMI_INTER_PAN_H
//
//
//
//
//
//
The three types of inter-PAN messages.
corresponding APS frame controls.
The values are actually the
0x03 is the special interPAN message type. Unicast mode is 0x00,
broadcast mode is 0x08, and multicast mode is 0x0C.
#define INTER_PAN_UNICAST
0x03
#define INTER_PAN_BROADCAST 0x0B
#define INTER_PAN_MULTICAST 0x0F
// Frame control, sequence, dest PAN ID, dest, source PAN ID, source.
#define MAX_INTER_PAN_MAC_SIZE (2 + 1 + 2 + 8 + 2 + 8)
// Short form has a short destination.
// NWK stub frame has two control bytes.
#define STUB_NWK_SIZE 2
#define STUB_NWK_FRAME_CONTROL 0x000B
// APS frame control, group ID, cluster ID, profile ID
#define MAX_STUB_APS_SIZE (1 + 2 + 2 + 2)
// Short form has no group ID.
#define MAX_INTER_PAN_HEADER_SIZE \
(MAX_INTER_PAN_MAC_SIZE + STUB_NWK_SIZE + MAX_STUB_APS_SIZE)
typedef struct {
int8u messageType;
values
// one of the INTER_PAN_...CAST
// MAC addressing
// For outgoing messages this is the destination. For incoming messages
// it is the source, which always has a long address.
int16u panId;
boolean hasLongAddress;
// always TRUE for incoming
messages
EmberNodeId shortAddress;
EmberEUI64 longAddress;
// APS data
int16u profileId;
int16u clusterId;
int16u groupId;
// only used for
INTER_PAN_MULTICAST
00066 } InterPanHeader;
00067
00068
00072 EmberMessageBuffer makeInterPanMessage(
InterPanHeader *headerData,
00073
EmberMessageBuffer
payload);
00074
00082 int8u parseInterPanMessage(EmberMessageBuffer
message,
00083
int8u startOffset,
00084
InterPanHeader *headerData);
00085
00086 #endif // AMI_INTER_PAN_H
00087
EmberZNet 4.7.2 API EM250
120-3016-000-4720
387
8.9
app-bootload-utils.h File Reference
Macros
• #define APP_BOOTLOAD_ENDPOINT
Enumerations
• enum bootloadState {
BOOTLOAD_STATE_NORMAL, BOOTLOAD_STATE_QUERY, BOOTLOAD_STATE_WAIT_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_STATE_START_SENDING_IMAGE,
BOOTLOAD_STATE_SENDING_IMAGE, BOOTLOAD_STATE_WAIT_FOR_IMAGE_ACK, BOOTLOAD_STATE_WAIT_FOR_COMPLETE_ACK, BOOTLOAD_STATE_DONE,
BOOTLOAD_STATE_NORMAL, BOOTLOAD_STATE_QUERY, BOOTLOAD_STATE_SEND_QUERY_RESP, BOOTLOAD_STATE_INITIATE,
BOOTLOAD_STATE_SEND_INITIATE_RESP, BOOTLOAD_STATE_RX_IMAGE, BOOTLOAD_STATE_SEND_DATA, BOOTLOAD_STATE_WAIT_FOR_DATA_ACK,
BOOTLOAD_STATE_REPORT_ERROR, BOOTLOAD_STATE_SEND_COMPLETE, BOOTLOAD_STATE_WAIT_FOR_COMPLETE_ACK, BOOTLOAD_STATE_VALIDATE,
BOOTLOAD_STATE_SEND_VALIDATE_RESP, BOOTLOAD_STATE_UPDATE, BOOTLOAD_STATE_SEND_UPDATE_RESP }
Functions
•
•
•
•
•
•
•
•
•
void appBootloadUtilTick (void)
void appBootloadUtilInit (int8u appPort, int8u bootloadPort, int16u appProfileId)
void appBootloadUtilStartXModem (void)
void appBootloadUtilSendQuery (int16u address, boolean isJIT)
void appBootloadUtilStartBootload (EmberNodeId target)
void appBootloadUtilValidate (EmberNodeId target)
void appBootloadUtilUpdate (EmberNodeId target)
void appBootloadUtilIncomingMessageHandler (EmberMessageBuffer message)
void appBootloadUtilMessageSent (int16u destination, EmberApsFrame ∗apsFrame, EmberMessageBuffer message, EmberStatus status)
Callbacks
Callback functions used by the application bootload library.
• int16u appBootloadUtilGetAppVersionHandler (void)
• void appBootloadUtilValidatingEEPROMImageHandler (void)
8.9.1
Detailed Description
Utilities used for performing application bootloading. See Bootloading for documentation.
Definition in file app-bootload-utils.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
388
8.10
00001
00061
00062
00063
00064
00069
00070
00071
00072
00073
00086
00087
00088
00089
00090
00091
00092
00093
00094
00095
00096
00097
00098
00099
00100
00101
00102
00103
00104
00105
00106
00107
00108
00109
00110
00111
00112
00118
00119
00130
app-bootload-utils.h
// *******************************************************************
// Literals needed by the application.
#define APP_BOOTLOAD_ENDPOINT 240
#ifdef DOXYGEN_SHOULD_SKIP_THIS
enum bootloadState
#else
typedef int8u bootloadState;
enum
#endif
{
BOOTLOAD_STATE_NORMAL,
BOOTLOAD_STATE_QUERY,
BOOTLOAD_STATE_SEND_QUERY_RESP,
BOOTLOAD_STATE_INITIATE,
BOOTLOAD_STATE_SEND_INITIATE_RESP,
BOOTLOAD_STATE_RX_IMAGE,
BOOTLOAD_STATE_SEND_DATA,
BOOTLOAD_STATE_WAIT_FOR_DATA_ACK,
BOOTLOAD_STATE_REPORT_ERROR,
BOOTLOAD_STATE_SEND_COMPLETE,
BOOTLOAD_STATE_WAIT_FOR_COMPLETE_ACK,
BOOTLOAD_STATE_VALIDATE,
BOOTLOAD_STATE_SEND_VALIDATE_RESP,
BOOTLOAD_STATE_UPDATE,
BOOTLOAD_STATE_SEND_UPDATE_RESP
};
// *******************************************************************
// Public functions that are called by the application.
void appBootloadUtilTick(void);
void appBootloadUtilInit(int8u appPort, int8u
bootloadPort, int16u appProfileId);
00131
00143 void appBootloadUtilStartXModem(void);
00144
00160 void appBootloadUtilSendQuery(int16u address,
boolean isJIT);
00161
00175 void appBootloadUtilStartBootload(EmberNodeId
target);
00176
00192 void appBootloadUtilValidate(EmberNodeId
target);
00193
00209 void appBootloadUtilUpdate(EmberNodeId target);
00210
00215 void appBootloadUtilIncomingMessageHandler
(EmberMessageBuffer message);
00216
00221 void appBootloadUtilMessageSent(int16u
destination,
00222
EmberApsFrame *apsFrame,
00223
EmberMessageBuffer message,
00224
EmberStatus status);
00225
00226 // *******************************************************************
00227 // Callback functions used by the application bootload library.
00228
00238 int16u appBootloadUtilGetAppVersionHandler
(void);
00239
00252 void appBootloadUtilValidatingEEPROMImageHandler
(void);
00253
EmberZNet 4.7.2 API EM250
120-3016-000-4720
389
8.11
binding-table.h File Reference
Functions
•
•
•
•
•
•
•
•
•
•
•
•
EmberStatus emberSetBinding (int8u index, EmberBindingTableEntry ∗value)
EmberStatus emberGetBinding (int8u index, EmberBindingTableEntry ∗result)
EmberStatus emberDeleteBinding (int8u index)
boolean emberBindingIsActive (int8u index)
EmberNodeId emberGetBindingRemoteNodeId (int8u index)
void emberSetBindingRemoteNodeId (int8u index, EmberNodeId id)
EmberStatus emberClearBindingTable (void)
EmberStatus emberRemoteSetBindingHandler (EmberBindingTableEntry ∗entry)
EmberStatus emberRemoteDeleteBindingHandler (int8u index)
int8u emberGetBindingIndex (void)
EmberStatus emberSetReplyBinding (int8u index, EmberBindingTableEntry ∗entry)
EmberStatus emberNoteSendersBinding (int8u index)
8.11.1
Detailed Description
See Binding Table for documentation.
Definition in file binding-table.h.
8.12
binding-table.h
00001
00027 EmberStatus emberSetBinding(int8u index,
EmberBindingTableEntry *value);
00028
00040 EmberStatus emberGetBinding(int8u index,
EmberBindingTableEntry *result);
00041
00049 EmberStatus emberDeleteBinding(int8u index);
00050
00063 boolean emberBindingIsActive(int8u index);
00064
00086 EmberNodeId emberGetBindingRemoteNodeId(
int8u index);
00087
00095 void emberSetBindingRemoteNodeId(int8u index,
EmberNodeId id);
00096
00102 EmberStatus emberClearBindingTable(void);
00103
00126 EmberStatus emberRemoteSetBindingHandler
(EmberBindingTableEntry *entry);
00127
00145 EmberStatus emberRemoteDeleteBindingHandler
(int8u index);
00146
00167 int8u emberGetBindingIndex(void);
00168
00186 EmberStatus emberSetReplyBinding(int8u
index, EmberBindingTableEntry *entry);
00187
00199 EmberStatus emberNoteSendersBinding(int8u
index);
00200
00201 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00202 // This is defined in hal/ember-configuration.c.
00203 extern int8u emberBindingTableSize;
00204 #endif
00205
EmberZNet 4.7.2 API EM250
120-3016-000-4720
390
8.13
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_WAIT_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_STATE_START_SENDING_IMAGE,
BOOTLOAD_STATE_SENDING_IMAGE, BOOTLOAD_STATE_WAIT_FOR_IMAGE_ACK, BOOTLOAD_STATE_WAIT_FOR_COMPLETE_ACK, BOOTLOAD_STATE_DONE,
BOOTLOAD_STATE_NORMAL, BOOTLOAD_STATE_QUERY, BOOTLOAD_STATE_SEND_QUERY_RESP, BOOTLOAD_STATE_INITIATE,
BOOTLOAD_STATE_SEND_INITIATE_RESP, BOOTLOAD_STATE_RX_IMAGE, BOOTLOAD_STATE_SEND_DATA, BOOTLOAD_STATE_WAIT_FOR_DATA_ACK,
BOOTLOAD_STATE_REPORT_ERROR, BOOTLOAD_STATE_SEND_COMPLETE, BOOTLOAD_STATE_WAIT_FOR_COMPLETE_ACK, BOOTLOAD_STATE_VALIDATE,
BOOTLOAD_STATE_SEND_VALIDATE_RESP, BOOTLOAD_STATE_UPDATE, BOOTLOAD_STATE_SEND_UPDATE_RESP }
Functions
• void bootloadUtilInit (int8u appPort, int8u bootloadPort)
• EmberStatus bootloadUtilSendRequest (EmberEUI64 targetEui, int16u mfgId, int8u hardwareTag[BOOTLOAD_HARDWARE_TAG_SIZE], int8u encryptKey[BOOTLOAD_AUTH_COMMON_SIZE], bootloadMode mode)
• void bootloadUtilSendQuery (EmberEUI64 target)
• void bootloadUtilStartBootload (EmberEUI64 target, bootloadMode mode)
• void bootloadUtilTick (void)
• boolean bootloadUtilLaunchRequestHandler (int16u manufacturerId, int8u hardwareTag[BOOTLOAD_HARDWARE_TAG_SIZE], EmberEUI64 sourceEui)
• void bootloadUtilQueryResponseHandler (boolean bootloaderActive, int16u manufacturerId, int8u
hardwareTag[BOOTLOAD_HARDWARE_TAG_SIZE], EmberEUI64 targetEui, int8u bootloaderCapabilities, 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 divisible
by the size of a 128-bit AES block.
• #define BOOTLOAD_AUTH_COMMON_SIZE
• #define BOOTLOAD_AUTH_CHALLENGE_SIZE
• #define BOOTLOAD_AUTH_RESPONSE_SIZE
EmberZNet 4.7.2 API EM250
120-3016-000-4720
391
Bootload State Variables
Used to check whether a bootloading process is currently happening.
• #define IS_BOOTLOADING
• bootloadState blState
8.13.1
Detailed Description
Utilities used for performing stand-alone bootloading. See Bootloading for documentation.
Definition in file bootload-utils.h.
8.14
00001
00058
00059
00060
00066
00067
00068
00069
00076
00077
00078
00079
00082
00083
00084
00085
00086
00087
00089
00091
00092
00093
00094
00095
00106
00107
00108
00109
00110
00111
00112
00113
00114
bootload-utils.h
// *******************************************************************
// Literals that are needed by the application.
#define BOOTLOAD_AUTH_COMMON_SIZE
16
#define BOOTLOAD_AUTH_CHALLENGE_SIZE BOOTLOAD_AUTH_COMMON_SIZE
#define BOOTLOAD_AUTH_RESPONSE_SIZE BOOTLOAD_AUTH_COMMON_SIZE
#define BOOTLOAD_HARDWARE_TAG_SIZE 16
#ifdef DOXYGEN_SHOULD_SKIP_THIS
enum bootloadMode
#else
typedef int8u bootloadMode;
enum
#endif
{
BOOTLOAD_MODE_NONE,
BOOTLOAD_MODE_PASSTHRU,
};
#ifdef DOXYGEN_SHOULD_SKIP_THIS
enum bootloadState
#else
typedef int8u bootloadState;
enum
#endif
{
BOOTLOAD_STATE_NORMAL,
BOOTLOAD_STATE_QUERY,
BOOTLOAD_STATE_WAIT_FOR_AUTH_CHALLENGE,
00115
00116
00117
00118
BOOTLOAD_STATE_WAIT_FOR_AUTH_RESPONSE,
BOOTLOAD_STATE_DELAY_BEFORE_START,
BOOTLOAD_STATE_START_UNICAST_BOOTLOAD,
BOOTLOAD_STATE_START_BROADCAST_BOOTLOAD
,
00119
00120
00121
00122
00123
00124
00125
00126
00127
00128
00129
00143
BOOTLOAD_STATE_START_SENDING_IMAGE,
BOOTLOAD_STATE_SENDING_IMAGE,
BOOTLOAD_STATE_WAIT_FOR_IMAGE_ACK,
BOOTLOAD_STATE_WAIT_FOR_COMPLETE_ACK,
BOOTLOAD_STATE_DONE
};
// *******************************************************************
// Public functions that are called by the application.
void bootloadUtilInit(int8u appPort, int8u
bootloadPort);
00144
00166 EmberStatus bootloadUtilSendRequest(
EmberEUI64 targetEui,
EmberZNet 4.7.2 API EM250
120-3016-000-4720
392
00167
00168
int16u mfgId,
int8u hardwareTag[
BOOTLOAD_HARDWARE_TAG_SIZE],
00169
int8u encryptKey[
BOOTLOAD_AUTH_COMMON_SIZE],
00170
bootloadMode mode);
00171
00184 void bootloadUtilSendQuery(EmberEUI64 target);
00185
00203 void bootloadUtilStartBootload(EmberEUI64
target, bootloadMode mode);
00204
00210 void bootloadUtilTick(void);
00211
00212
00213 // *******************************************************************
00214 // Callback functions used by the bootload library.
00215
00234 boolean bootloadUtilLaunchRequestHandler(int16u
manufacturerId,
00235
int8u hardwareTag[
BOOTLOAD_HARDWARE_TAG_SIZE],
00236
EmberEUI64 sourceEui);
00237
00267 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);
00276
00289 void bootloadUtilSendAuthResponse(EmberEUI64
target);
00290
00291
00292 // *******************************************************************
00293 // Bootload state variables
00294
00299 extern bootloadState blState;
00300 #define IS_BOOTLOADING ((blState != BOOTLOAD_STATE_NORMAL) && \
00301
(blState != BOOTLOAD_STATE_DONE))
00302
8.15
bootload.h File Reference
Functions
• EmberStatus emberSendBootloadMessage (boolean broadcast, EmberEUI64 destEui64, EmberMessageBuffer message)
• void emberIncomingBootloadMessageHandler (EmberEUI64 longId, EmberMessageBuffer message)
• void emberBootloadTransmitCompleteHandler (EmberMessageBuffer message, EmberStatus status)
8.15.1
Detailed Description
See Bootloader for documentation.
Definition in file bootload.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
393
8.16
bootload.h
00001
00030 EmberStatus emberSendBootloadMessage(boolean
broadcast,
00031
EmberEUI64 destEui64,
00032
EmberMessageBuffer
message);
00033
00043 void emberIncomingBootloadMessageHandler(
EmberEUI64 longId,
00044
EmberMessageBuffer
message);
00045
00055 void emberBootloadTransmitCompleteHandler(
EmberMessageBuffer message,
00056
EmberStatus status);
00057
8.17
bootloader-common.h File Reference
Common Bootloader Functions
•
•
•
•
•
•
•
•
•
int32u updateCrcNoTable (int32u accumulator, int8u data)
int32u calculateCrc32 (int32u previous, int8u ∗data, int16u length, boolean reset)
void serPutChar (int8u ch)
void serPutStr (char ∗str)
void serPutBuf (const int8u buf[ ], int8u size)
void serPutHex (int8u byte)
void serPutHexInt (int16u word)
void sc2I2cInit (void)
void sc2I2cIntInit (void)
8.17.1
Detailed Description
provides common routines used by EM250 bootloaders. See Bootloading for documentation.
Definition in file bootloader-common.h.
8.18
00001
00025
00026
00027
00028
00038
00039
00040
00041
00042
00048
00049
00055
00056
00063
00064
00070
00071
00077
00078
bootloader-common.h
int32u updateCrcNoTable(int32u accumulator,
int8u data);
int32u calculateCrc32(int32u previous,
int8u *data,
int16u length,
boolean reset);
void serPutChar(int8u ch);
void serPutStr(char *str);
void serPutBuf(const int8u buf[], int8u size);
void serPutHex(int8u byte);
void serPutHexInt(int16u word);
EmberZNet 4.7.2 API EM250
120-3016-000-4720
394
00081 void sc2I2cInit(void);
00082
00086 void sc2I2cIntInit(void);
00087
8.19
bootloader-interface-app.h File Reference
#include "hal/micro/bootloader-eeprom.h"
Macros
• #define BOOTLOADER_SEGMENT_SIZE_LOG2
• #define BOOTLOADER_SEGMENT_SIZE
• #define BL_IMAGE_IS_VALID_CONTINUE
Functions
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
int8u halAppBootloaderInit (void)
const HalEepromInformationType ∗ halAppBootloaderInfo (void)
void halAppBootloaderShutdown (void)
void halAppBootloaderImageIsValidReset (void)
int16u halAppBootloaderImageIsValid (void)
EmberStatus halAppBootloaderInstallNewImage (void)
int8u halAppBootloaderWriteRawStorage (int32u address, const int8u ∗data, int16u len)
int8u halAppBootloaderReadRawStorage (int32u address, int8u ∗data, int16u len)
int8u halAppBootloaderEraseRawStorage (int32u address, int32u len)
boolean halAppBootloaderStorageBusy (void)
int8u halAppBootloaderReadDownloadSpace (int16u pageToBeRead, int8u ∗destRamBuffer)
int8u halAppBootloaderWriteDownloadSpace (int16u pageToBeWritten, int8u ∗RamPtr)
int8u halAppBootloaderGetImageData (int32u ∗timestamp, int8u ∗userData)
int16u halAppBootloaderGetVersion (void)
int16u halAppBootloaderGetRecoveryVersion (void)
8.19.1
Detailed Description
See Application Bootloader for documentation.
Definition in file bootloader-interface-app.h.
8.20
00001
00018
00019
00020
00021
00022
00027
00028
00032
00033
bootloader-interface-app.h
#ifndef __BOOTLOADER_INTERFACE_APP_H__
#define __BOOTLOADER_INTERFACE_APP_H__
#include "hal/micro/bootloader-eeprom.h"
#define BOOTLOADER_SEGMENT_SIZE_LOG2
6
#define BOOTLOADER_SEGMENT_SIZE
(1 << BOOTLOADER_SEGMENT_SIZE_LOG2)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
395
00034
00042
00043
00050
00051
00055
00056
00060
00061
00065
00066
00092
00093
00094
00099
int8u halAppBootloaderInit(void);
const HalEepromInformationType *halAppBootloaderInfo(void);
void halAppBootloaderShutdown(void);
void halAppBootloaderImageIsValidReset(void);
#define BL_IMAGE_IS_VALID_CONTINUE
((int16u)0xFFFF)
int16u halAppBootloaderImageIsValid(void);
EmberStatus halAppBootloaderInstallNewImage
(void);
00100
00101
00102
00123 int8u halAppBootloaderWriteRawStorage(
int32u address,
00124
const int8u *data,
00125
int16u len);
00126
00141 int8u halAppBootloaderReadRawStorage(int32u
address, int8u *data, int16u len);
00142
00160 int8u halAppBootloaderEraseRawStorage(
int32u address, int32u len);
00161
00167 boolean halAppBootloaderStorageBusy(void);
00168
00181 int8u halAppBootloaderReadDownloadSpace(
int16u pageToBeRead,
00182
int8u* destRamBuffer);
00183
00184
00197 int8u halAppBootloaderWriteDownloadSpace
(int16u pageToBeWritten,
00198
int8u* RamPtr);
00199
00208 int8u halAppBootloaderGetImageData(int32u
*timestamp, int8u *userData);
00209
00210
00213 int16u halAppBootloaderGetVersion(void);
00214
00215
00218 int16u halAppBootloaderGetRecoveryVersion
(void);
00219
00220
00221 #endif //__BOOTLOADER_INTERFACE_APP_H__
00222
8.21
bootloader-interface-standalone-v1.h File Reference
Macros
• #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 }
EmberZNet 4.7.2 API EM250
120-3016-000-4720
396
Functions
• EmberStatus halInternalStandaloneBootloaderTrap (int16u assumedBootloaderType, int8u trapNumber,...)
• void halInternalAdjustFlashBlock (int16u ∗dst, int16u ∗src, int8u size)
• EmberStatus halLaunchStandaloneBootloaderV1 (int8u mode, int8u ∗eui64)
8.21.1
Detailed Description
Definition of the interface to the standalone bootloader. See Stand-Alone Bootloader for documentation.
Some functions in this file return an EmberStatus value. See error-def.h for definitions of all EmberStatus
return values.
Definition in file bootloader-interface-standalone-v1.h.
8.22
00001
00019
00020
00021
00026
00027
00028
00029
00030
00031
00032
00033
00034
00035
00036
00037
00038
00039
00040
00041
00042
00043
00044
00045
00046
00047
00048
00049
00050
00051
00052
00053
00054
00055
00056
00057
00058
00059
00060
00061
00062
00063
00064
00067
00071
00072
00073
00074
00075
00076
00077
00078
00079
bootloader-interface-standalone-v1.h
#ifndef __BOOTLOADER_STANDALONE_V1_H__
#define __BOOTLOADER_STANDALONE_V1_H__
#define BOOTLOADER_TYPE_STANDALONE
0xBEEF
// BOOTLOADER_TYPE_APP is defined in bootloader-interface-app.h
#ifndef DOXYGEN_SHOULD_SKIP_THIS
// Automatically used by the trap functions for triggering the bootloader
#define BOOTLOADER_APP_REQUEST_KEY 0xFA27
// Constants used by the standalone bootloader
#define FLASH_TAB_POINTERS
#define FLASH_TAB_POINTERS_DEFAULT_TOKEN_TAB_PTR
#define FLASH_TAB_POINTERS_UPPER_TOKEN_TAB_PTR
#define FLASH_TAB_POINTERS_BOOT_TRAP_TAB_PTR
#define FLASH_TAB_POINTERS_HELPERFUNC_TAB
#define BOOTLOADER_TRAPTAB_SIGNATURE
0x00F0
0
//DEPRECATED
2
//DEPRECATED
4
6
0xBEEF
#ifdef __HAS_ELPM__
#define LPM_HIGH(x,y) \
do {
\
int8u reg;
\
reg = RAMPZ;
\
y = __extended_load_program_memory(x); \
RAMPZ = reg;
\
} while(0)
//
#define LPM_HIGH __extended_load_program_memory
#define FLASH_HIGH __farflash
#else
#define LPM_HIGH(x,y) \
do { \
y = __load_program_memory(x); \
} while(0)
#define FLASH_HIGH __flash
#endif // __HAS_ELPM__
#ifdef DOXYGEN_SHOULD_SKIP_THIS
enum StandaloneBootloaderTraps
#else
typedef int8u StandaloneBootloaderTraps;
enum
#endif
{
BOOT_TRAP_APP_START = 1,
BOOT_TRAP_FLASH_ADJUST = 3
EmberZNet 4.7.2 API EM250
120-3016-000-4720
397
00080 };
00081 #endif // DOXYGEN_SHOULD_SKIP_THIS
00082
00083
00101 EmberStatus halInternalStandaloneBootloaderTrap
(int16u assumedBootloaderType,
00102
int8u trapNumber, ...);
00103
00104 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00105
00108 void bootloadAppStart(void);
00109 #endif // DOXYGEN_SHOULD_SKIP_THIS
00110
00111 #ifdef DOXYGEN_SHOULD_SKIP_THIS
00112
00127 #define halBootloadAppStart(space, segment, ramPtr);
00128 #else
00129 #define halBootloadAppStart(space, segment, ramPtr)
\
00130
halInternalStandaloneBootloaderTrap(BOOTLOADER_TYPE_APP,
\
00131
BOOT_TRAP_APP_START)
00132 #endif // DOXYGEN_SHOULD_SKIP_THIS
00133
00149 void halInternalAdjustFlashBlock(int16u* dst,
int16u* src, int8u size);
00150
00151 #ifdef DOXYGEN_SHOULD_SKIP_THIS
00152
00167 #define halBootloadAdjustFlash(space, segment, ramPtr);
00168 #else
00169 #define halBootloadAdjustFlash(space, segment, ramPtr)
\
00170
halInternalStandaloneBootloaderTrap(BOOTLOADER_TYPE_APP,
\
00171
BOOT_TRAP_FLASH_ADJUST, \
00172
(segment), (ramPtr), (space))
00173 #endif // DOXYGEN_SHOULD_SKIP_THIS
00174
00175 // 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 gatewayID
00178
//
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 hop
00181
00182 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 =
0x03
00188 };
00189
00214 EmberStatus halLaunchStandaloneBootloaderV1
(int8u mode, int8u *eui64);
00215
00217
00218 #endif //__BOOTLOADER_STANDALONE_V1_H__
00219
8.23
bootloader-interface-standalone.h File Reference
Macros
• #define NO_BOOTLOADER_MODE
• #define STANDALONE_BOOTLOADER_NORMAL_MODE
• #define STANDALONE_BOOTLOADER_RECOVERY_MODE
Functions
• int16u halGetStandaloneBootloaderVersion (void)
• EmberStatus halLaunchStandaloneBootloader (int8u mode)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
398
8.23.1
Detailed Description
See Stand-Alone Bootloader for documentation.
Definition in file bootloader-interface-standalone.h.
8.24
bootloader-interface-standalone.h
00001
00017 #ifndef __BOOTLOADER_STANDALONE_H__
00018 #define __BOOTLOADER_STANDALONE_H__
00019
00028 int16u halGetStandaloneBootloaderVersion
(void);
00029
00033 #define NO_BOOTLOADER_MODE
0xFF
00034
00037 #define STANDALONE_BOOTLOADER_NORMAL_MODE
1
00038
00041 #define STANDALONE_BOOTLOADER_RECOVERY_MODE 0
00042
00061 EmberStatus halLaunchStandaloneBootloader
(int8u mode);
00062
00063
00064 #endif //__BOOTLOADER_STANDALONE_H__
00065
8.25
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
8.25.1
Detailed Description
See Button Control for documentation.
Definition in file button.h.
8.26
button.h
00001
00024 #define BUTTON_PRESSED
00025
EmberZNet 4.7.2 API EM250
1
120-3016-000-4720
399
00028
00029
00036
00037
00049
00050
00063
00064
00079
00080
8.27
#define BUTTON_RELEASED 0
void halInternalInitButton(void);
int8u halButtonState(int8u button);
int8u halButtonPinState(int8u button);
void halButtonIsr(int8u button, int8u state);
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
#define NOTE_B4
#define NOTE_C5
#define NOTE_Db5
#define NOTE_D5
#define NOTE_Eb5
#define NOTE_E5
#define NOTE_F5
EmberZNet 4.7.2 API EM250
120-3016-000-4720
400
•
•
•
•
•
•
#define NOTE_Gb5
#define NOTE_G5
#define NOTE_Ab5
#define NOTE_A5
#define NOTE_Bb5
#define NOTE_B5
8.27.1
Detailed Description
See Buzzer Control for documentation.
Definition in file buzzer.h.
8.28
00001
00023
00024
00025
00026
00027
00028
00029
00030
00031
00032
00033
00034
00035
00036
00037
00038
00039
00040
00041
00042
00043
00044
00045
00046
00047
00048
00049
00050
00051
00052
00053
00054
00055
00056
00057
00058
00059
00082
00083
00084
00089
00090
8.29
buzzer.h
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
NOTE_C3 119
NOTE_Db3
NOTE_D3 106
NOTE_Eb3
NOTE_E3 94
NOTE_F3 89
NOTE_Gb3
NOTE_G3 79
NOTE_Ab3
NOTE_A3 70
NOTE_Bb3
NOTE_B3 63
NOTE_C4 59
NOTE_Db4
NOTE_D4 52
NOTE_Eb4
NOTE_E4 46
NOTE_F4 44
NOTE_Gb4
NOTE_G4 39
NOTE_Ab4
NOTE_A4 35
NOTE_Bb4
NOTE_B4 31
NOTE_C5 29
NOTE_Db5
NOTE_D5 26
NOTE_Eb5
NOTE_E5 23
NOTE_F5 21
NOTE_Gb5
NOTE_G5 19
NOTE_Ab5
NOTE_A5 17
NOTE_Bb5
NOTE_B5 15
112
100
84
74
66
55
49
41
37
33
27
24
20
18
16
void halPlayTune_P(int8u PGM *tune, boolean bkg);
void halStackIndicatePresence(void);
cbke-crypto-engine.h File Reference
Functions
• EmberStatus emberGetCertificate (EmberCertificateData ∗result)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
401
• EmberStatus emberGenerateCbkeKeys (void)
• EmberStatus emberCalculateSmacs (boolean amInitiator, EmberCertificateData ∗partnerCert, EmberPublicKeyData ∗partnerEphemeralPublicKey)
• EmberStatus emberClearTemporaryDataMaybeStoreLinkKey (boolean storeLinkKey)
• EmberStatus emberDsaSign (EmberMessageBuffer messageToSign)
• void emberGenerateCbkeKeysHandler (EmberStatus status, EmberPublicKeyData ∗ephemeralPublicKey)
• void emberCalculateSmacsHandler (EmberStatus status, EmberSmacData ∗initiatorSmac, EmberSmacData ∗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)
8.29.1
Detailed Description
EmberZNet Smart Energy security API. See Smart Energy Security for documention.
Definition in file cbke-crypto-engine.h.
8.30
cbke-crypto-engine.h
00001
00030 EmberStatus emberGetCertificate(
EmberCertificateData* result);
00031
00047 EmberStatus emberGenerateCbkeKeys(void);
00048
00071 EmberStatus emberCalculateSmacs(boolean
amInitiator,
00072
EmberCertificateData*
partnerCert,
00073
EmberPublicKeyData*
partnerEphemeralPublicKey);
00074
00089 EmberStatus emberClearTemporaryDataMaybeStoreLinkKey
(boolean storeLinkKey);
00090
00091 /* @brief LEGACY FUNCTION: This functionality has been replaced by a single
00092 * bit in the ::EmberApsFrame, ::EMBER_APS_OPTION_DSA_SIGN. Devices wishing
00093 * to send signed messages should use that as it requires fewer function calls
00094 * and message buffering. emberDsaSignHandler() is still called when using
00095 * ::EMBER_APS_OPTION_DSA_SIGN. However, this function is still supported.
00096 *
00097 * This function begins the process of signing the passed message
00098 * 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 it
00101 * will shutdown the radio and consume the CPU processing until the signing
00102 * is complete. This may take up to 1 second.
00103 *
00104 * The signed message will be returned in ::emberDsaSignHandler().
00105 *
00106 * Note that the last byte of the buffer contents passed to this function has
00107 * special significance. As the typical use case for DSA signing is to sign
the
00108 * ZCL payload of a DRLC Report Event Status message in SE 1.0, there is often
00109 * 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 a
00111 * special indicator to signify how many bytes of leading data in the buffer
00112 * should be excluded from consideration during the signing process. If the
EmberZNet 4.7.2 API EM250
120-3016-000-4720
402
00113 * 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 replaced
00116 * by the signature type indicator (0x01 for ECDSA signatures), and the
00117 * 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 from
00121 *
the signing operation. See note above regarding special requirements
00122 *
for this buffer.
00123 *
00124 * @return ::EMBER_OPERATION_IN_PROGRESS if the stack has queued up the
00125 *
operation for execution. ::EMBER_INVALID_CALL if the operation can’t be
00126 *
performed in this context (possibly because another ECC operation is
00127 *
pending.)
00128 */
00129 EmberStatus emberDsaSign(EmberMessageBuffer
messageToSign);
00130
00131
00132 /* @brief This function is an application callback that must be defined
00133 * when using CBKE. It is called when the ephemeral key generation operation
00134 * is complete. The newly generated public key is passed back to the
00135 * application to be sent to the CBKE partner over-the-air. Internally
00136 * the stack saves the public and private key pair until it the function
00137 * ::emberClearTemporaryDataMaybeStoreLinkKey() is called by the application.
00138 *
00139 * @param status This is the ::EmberStatus value indicating the success or
00140 *
failure of the operation.
00141 * @param ephemeralPublicKey A pointer to an ::EmberPublicKeyData structure
00142 *
containing the newly generated public key.
00143 */
00144 void emberGenerateCbkeKeysHandler(EmberStatus
status,
00145
EmberPublicKeyData*
ephemeralPublicKey);
00146
00147 /* @brief This function is an application callback that must be defined
00148 * when using CBKE. It is called when the shared secret generation is
00149 * complete and the link key and SMACs have been derived. The link key is
00150 * stored in a temporary location until the application decides to
00151 * store or discard the key by calling
00152 * ::emberClearTemporaryDataMaybeStoreLinkKey().
00153 *
00154 * @param status This is the ::EmberStatus value indicating the success or
00155 *
failure of the operation.
00156 * @param initiatorSmac This is a pointer to the ::EmberSmacData structure
00157 *
to the initiator’s version of the SMAC.
00158 * @param responderSmac This is a pointer to the ::EmberSmacData structure
00159 *
to the responder’s version of the SMAC.
00160 */
00161 void emberCalculateSmacsHandler(EmberStatus
status,
00162
EmberSmacData* initiatorSmac,
00163
EmberSmacData* responderSmac);
00164
00165 /* @brief This function is an application callback that must be defined
00166 * when using CBKE. This callback is provided to the application to let
00167 * it know that the ECC operations have completed and the radio has been turned
00168 * back on. When using the sign-and-send option of the ::EmberApsFrame,
00169 * ::EMBER_APS_OPTION_DSA_SIGN, the handler will NOT return the complete
00170 * signed message. This callback is merely informative. If ::emberDsaSign()
00171 * has been called, the message plus signature will be returned to the caller
00172 * and it must be sent separately by one of the message send primitives
00173 * (such as ::emberSendUnicast()).
00174 *
00175 * @param status This is the ::EmberStatus value indicating the success or
00176 *
failure of the operation.
00177 * @param signedMessage This is the ::EmberMessageBuffer indicating the newly
00178 *
signed message, if ::emberDsaSign() was called. If message was signed
00179 *
using ::EMBER_APS_OPTION_DSA_SIGN then this will be
00180 *
::EMBER_NULL_MESSAGE_BUFFER.
00181 */
00182 void emberDsaSignHandler(EmberStatus status,
00183
EmberMessageBuffer signedMessage);
00184
00185
00186 /* @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 them
EmberZNet 4.7.2 API EM250
120-3016-000-4720
403
00189
00190
00191
00192
00193
00194
00195
00196
00197
00198
00199
00200
00201
00202
00203
00204
00205
00206
00207
00208
00209
00210
00211
00212
00213
00214
00215
00216
00217
00218
00219
00220
00221
00222
00223
00224
00225
00226
00227
00228
00229
00230
00231
00232
00233
00234
00235
00236
00237
00238
* in MFG tokens when the chip is manufactured. However this function
* allows the certificate to be updated at runtime after the device has
* been deployed.
The behavior of this function differs based on the hardware platform.
*
*
* For the 2xx:
* To use this functionality the application must also set
* the stack configuration value ::EMBER_CERTIFICATE_TABLE_SIZE to 1.
* Attempts to call this function with ::EMBER_CERTIFICATE_TABLE_SIZE of 0
* will return ::EMBER_SECURITY_CONFIGURATION_INVALID.
* The passed security data will be persistently stored in stack tokens.
* The certificate contains the EUI64 it is associated with. If that
* EUI64 matches the EUI64 currently in use by the device, this
* function may be called at any time, even while running in a network.
* If the EUI64 does not match, this function may only be called when the
* network is in a state of ::EMBER_NO_NETWORK. Attempts to do otherwise
* will result in a return value of ::EMBER_INVALID_CALL.
*
* For the 3xx:
* This function allows a one-time write of the MFG token if it has not
* already been set. It does NOT utilize the ::EMBER_CERTIFICATE_TABLE_SIZE
* so that should remain set at 0. Attempts to write the certificate that
* has already been written will return a result of
* ::EMBER_ERR_FLASH_WRITE_INHIBITED. If the EUI64 in the certificate is
* the same as the current EUI of the device then this function may be called
* while the stack is up. If the EUI in the certificate is different than
* the current value, this function may only be called when the network is in
* a state of ::EMBER_NO_NETWORK. Attempts to do otherwise will result in a
* return value of ::EMBER_INVALID_CALL. If the EUI in the certificate is
* different than the current value this function will also write the
* Custom EUI64 MFG token. If that token has already been written the
operation
* will fail and return a result of ::EMBER_BAD_ARGUMENT.
* If all the above criteria is met the token will be written and
* ::EMBER_SUCCESS will be returned.
*
* @note The device will immediately and persistently <b>change its EUI64
* to match the value in the certificate</b>.
*
* @param caPublic A pointer to the CA public key data that will be stored
in stack tokens.
*
* @param myCert A pointer to the certificate data that will be stored in
stack tokens.
*
* @param mykey A pointer to the private key data that will be stored in
stack tokens.
*
* @return The ::EmberStatus value indicating success or failure of the
operation.
*
*/
EmberStatus emberSetPreinstalledCbkeData
(EmberPublicKeyData* caPublic,
EmberCertificateData
* myCert,
EmberPrivateKeyData
* myKey);
00239
00240 /* @brief This function retrieves the EUI64 from the stack token
00241 * 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 zero
00244 * or if the CBKE library is not present, this function returns FALSE
00245 * 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 EUI64
00249 *
return value is valid. FALSE otherwise.
00250 */
00251 boolean emberGetStackCertificateEui64(EmberEUI64
certEui64);
00252
00253 /* @brief This function verifies the ECDSA signature of the
00254 * calculated digest and the associated received signature, using
00255 * the signerCertificate passed in. It is expected that the application
00256 * obtains the signerCertificate and performs the message digest calculation
00257 * on its own.
00258 */
00259 EmberStatus emberDsaVerify(EmberMessageDigest
* digest,
00260
EmberCertificateData*
signerCertificate,
00261
EmberSignatureData* receivedSig);
EmberZNet 4.7.2 API EM250
120-3016-000-4720
404
00262
00263 /* @brief This callback is executed by the stack when the DSA verification
00264 * has completed and has a result. If the result is EMBER_SUCCESS, the
00265 * signature is valid. If the result is EMBER_SIGNATURE_VERIFY_FAILURE
00266 * then the signature is invalid. If the result is anything else then the
00267 * signature verify operation failed and the validity is unknown.
00268 */
00269 void emberDsaVerifyHandler(EmberStatus status);
00270
00271
8.31
child.h File Reference
Functions
• EmberNodeId emberChildId (int8u childIndex)
• int8u emberChildIndex (EmberNodeId childId)
• EmberStatus emberGetChildData (int8u index, EmberEUI64 childEui64Return, EmberNodeType
∗childTypeReturn)
• void emberChildJoinHandler (int8u index, boolean joining)
• EmberStatus emberPollForData (void)
• void emberPollCompleteHandler (EmberStatus status)
• EmberStatus emberSetMessageFlag (EmberNodeId childId)
• EmberStatus emberClearMessageFlag (EmberNodeId childId)
• void emberPollHandler (EmberNodeId childId, boolean transmitExpected)
• int8u emberChildCount (void)
• int8u emberRouterChildCount (void)
• int8u emberMaxChildCount (void)
• int8u emberMaxRouterChildCount (void)
• EmberNodeId emberGetParentNodeId (void)
• EmberEUI64 emberGetParentEui64 (void)
Power Management
• #define EMBER_HIGH_PRIORITY_TASKS
• enum {
EMBER_OUTGOING_MESSAGES, EMBER_INCOMING_MESSAGES, EMBER_RADIO_IS_ON, EMBER_TRANSPORT_ACTIVE,
EMBER_APS_LAYER_ACTIVE, EMBER_ASSOCIATING, EMBER_ZLL_TOUCH_LINKING
}
• int16u emberCurrentStackTasks (void)
• boolean emberOkToNap (void)
• boolean emberOkToHibernate (void)
• boolean emberOkToLongPoll (void)
• void emberStackPowerDown (void)
• void emberStackPowerUp (void)
8.31.1
Detailed Description
See End Devices for documentation.
Definition in file child.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
405
8.32
00001
00023
00024
00031
00032
00047
00048
00049
00050
00066
child.h
EmberNodeId emberChildId(int8u childIndex);
int8u emberChildIndex(EmberNodeId childId);
EmberStatus emberGetChildData(int8u index,
EmberEUI64 childEui64Return,
EmberNodeType *childTypeReturn);
void emberChildJoinHandler(int8u index, boolean
joining);
00067
00098 EmberStatus emberPollForData(void);
00099
00114 void emberPollCompleteHandler(EmberStatus
status);
00115
00129 EmberStatus emberSetMessageFlag(EmberNodeId
childId);
00130
00143 EmberStatus emberClearMessageFlag(EmberNodeId
childId);
00144
00162 void emberPollHandler(EmberNodeId childId, boolean
transmitExpected);
00163
00164
00165 #ifdef DOXYGEN_SHOULD_SKIP_THIS
00166
00170 int8u emberChildCount(void);
00171
00177 int8u emberRouterChildCount(void);
00178
00184 int8u emberMaxChildCount(void);
00185
00191 int8u emberMaxRouterChildCount(void);
00192
00199 EmberNodeId emberGetParentNodeId(void);
00200
00207 EmberEUI64 emberGetParentEui64(void);
00208
00209 #else
// Doxygen ignores the following
00210
00211 extern int8u emMaxEndDeviceChildren;
// maximum for this node
00212 extern int8u emEndDeviceChildCount;
// how many we have
00213
00214 // The ’+ 0’ prevents anyone from accidentally assigning to these.
00215 #define emberChildCount()
(emEndDeviceChildCount + 0)
00216 #define emberRouterChildCount()
0
00217 #define emberMaxChildCount()
(emMaxEndDeviceChildren + 0)
00218 #define emberMaxRouterChildCount() 0
00219
00220 // Implemented in ember-stack-common.c
00221 EmberNodeId emberGetParentNodeId(void);
00222 int8u* emberGetParentEui64(void);
00223
00224
00225 #endif
00226
00230
00233 enum
00234 {
00236
EMBER_OUTGOING_MESSAGES = 0x01,
00238
EMBER_INCOMING_MESSAGES = 0x02,
00243
EMBER_RADIO_IS_ON = 0x04,
00245
EMBER_TRANSPORT_ACTIVE = 0x08,
00247
EMBER_APS_LAYER_ACTIVE = 0x10,
00249
EMBER_ASSOCIATING = 0x20,
00251
EMBER_ZLL_TOUCH_LINKING = 0x40,
00252 };
00253
00256 #define EMBER_HIGH_PRIORITY_TASKS \
00257 (EMBER_OUTGOING_MESSAGES | EMBER_INCOMING_MESSAGES | EMBER_RADIO_IS_ON)
00258
00272 int16u emberCurrentStackTasks(void);
00273
00285 #ifdef DOXYGEN_SHOULD_SKIP_THIS
EmberZNet 4.7.2 API EM250
120-3016-000-4720
406
00286
00287
00288
00289
00290
00291
00301
00302
00303
00304
00305
00306
00312
00313
00314
00315
00316
00317
00325
00326
00331
00332
00333
00334
00335
00336
boolean emberOkToNap(void);
#else
#define emberOkToNap() \
(! (emberCurrentStackTasks() & EMBER_HIGH_PRIORITY_TASKS))
#endif
#ifdef DOXYGEN_SHOULD_SKIP_THIS
boolean emberOkToHibernate(void);
#else
#define emberOkToHibernate() (! emberCurrentStackTasks())
#endif
#ifdef DOXYGEN_SHOULD_SKIP_THIS
boolean emberOkToLongPoll(void);
#else
#define emberOkToLongPoll() (! emberPendingAckedMessages())
#endif
void emberStackPowerDown(void);
void emberStackPowerUp(void);
// @} END Power Management
// @} END addtogroup
8.33
command-interpreter.h File Reference
Data Structures
• struct EmberCommandEntry
Command entry for a command table.
• struct EmberCommandStateS
The 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_MANY_COMMAND_ARGUMENTS, EMBER_CMD_ERR_ARGUMENT_OUT_OF_RANGE, EMB-
EmberZNet 4.7.2 API EM250
120-3016-000-4720
407
ER_CMD_ERR_ARGUMENT_SYNTAX_ERROR,
EMBER_CMD_ERR_STRING_TOO_LONG, EMBER_CMD_ERR_NO_BINARY_STRING_TERMINATOR, 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_TYPE }
Functions
• void emberCommandReaderInit (EmberCommandState ∗state)
• boolean emberProcessCommandString (EmberCommandState ∗state, int8u ∗input, int8u size)
Variables
• PGM_NO_CONST PGM_P emberCommandErrorNames [ ]
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 command 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)
8.33.1
Detailed Description
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 commandinterpreter2 instead.
Definition in file command-interpreter.h.
8.34
00001
00013
00014
00015
00071
00072
00075
command-interpreter.h
#ifndef __COMMAND_INTERPRETER_H__
#define __COMMAND_INTERPRETER_H__
#ifndef EMBER_COMMENT_CHARACTER
#define EMBER_COMMENT_CHARACTER
EmberZNet 4.7.2 API EM250
’#’
120-3016-000-4720
408
00076
00077
00078
00079
00081
00082
00083
00087
00088
00089
00090
00091
00092
00093
00094
00095
00096
00097
00098
00099
00100
00101
#endif
#ifndef EMBER_MAX_COMMAND_LENGTH
#define EMBER_MAX_COMMAND_LENGTH
#endif
12
//Since the Cortex-M3 platform is native 32bit, we enable 32bit unsigned
//arguments in the command interpreter. This is useful since any addresses or
//similar arguments are best supplied as 32bits. All other platforms are both
//not native 32bit and even more resource constrained, so only use 16bit args.
#ifdef CORTEXM3
typedef int32u ArgTypeU;
#define TEMP_GREATER_THAN_MAX_ARG_SIZE (0)
#define PERFORM_BOUNDS_CHECKING (!((type==’u’)&&(size==’4’)))
#else //everything else needs to save space
typedef int16u ArgTypeU;
#define TEMP_GREATER_THAN_MAX_ARG_SIZE (0xFFFF < temp)
#define PERFORM_BOUNDS_CHECKING (1)
#endif
struct EmberCommandStateS;
this type.
// To allow forward use of
00102
00103 typedef void (*CommandAction)(struct EmberCommandStateS
*state);
00104
00105
00106 #ifdef DOXYGEN_SHOULD_SKIP_THIS
00107
00109 typedef struct {
00110 #else
00111 typedef PGM struct {
00112 #endif
00113
00116
PGM_P longName;
00120
CommandAction action;
00142
PGM_P argumentTypes;
00145
PGM_P description;
00146 } EmberCommandEntry;
00147
00148 #ifdef DOXYGEN_SHOULD_SKIP_THIS
00149
00154 enum EmberCommandStatus
00155 #else
00156 typedef int8u EmberCommandStatus;
00157 enum
00158 #endif
00159 {
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
00169
EMBER_CMD_ERR_STRING_TOO_LONG,
EMBER_CMD_ERR_NO_BINARY_STRING_TERMINATOR
00170 };
00171
00172 extern PGM_NO_CONST PGM_P emberCommandErrorNames[];
00173
00177 typedef struct EmberCommandStateS {
00180
EmberCommandEntry *commands;
00181
void (* errorHandler)(struct EmberCommandStateS
*state);
00183
ArgTypeU *arguments;
00184
00185
int8u maximumArguments;
00189
int8u integerBase;
00191
int8u argumentCount;
00192
00193
// The rest are internal settings
00194
//
EmberZNet 4.7.2 API EM250
120-3016-000-4720
409
00196
00198
00202
00203
00204
00206
00208
00210
00211
00212
00213
00214
00216
00217
00218
00219
00221
00222
00223
00224
00225
00232
00233
00234
00235
00236
00237
00238
00239
00240
00247
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;
} EmberCommandState;
#define emberUnsignedCommandArgument(state, index) \
((state)->arguments[index])
#define emberSignedCommandArgument(state, index) \
((int16s) ((state)->arguments[index]))
#define emberBufferCommandArgument(state, index) \
(LOW_BYTE((state)->arguments[index]))
void emberCommandReaderInit(EmberCommandState
*state);
00248
00254 boolean emberProcessCommandString(EmberCommandState
*state,
00255
int8u *input,
00256
int8u size);
00257
00266 #define emberProcessCommandInput(state, port) \
00267 emberProcessCommandString(state, NULL, port)
00268
00272 #define emberCommandName(state) (state->command)
00273
00274
00278 #endif //__COMMAND_INTERPRETER_H__
8.35
command-interpreter2.h File Reference
Data Structures
• struct EmberCommandEntry
Command entry for a command table.
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()
EmberZNet 4.7.2 API EM250
120-3016-000-4720
410
Typedefs
• typedef void(∗ CommandAction )(void)
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_MANY_COMMAND_ARGUMENTS, EMBER_CMD_ERR_ARGUMENT_OUT_OF_RANGE, EMBER_CMD_ERR_ARGUMENT_SYNTAX_ERROR,
EMBER_CMD_ERR_STRING_TOO_LONG, EMBER_CMD_ERR_NO_BINARY_STRING_TERMINATOR, 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_TYPE }
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
Command Table Settings
• #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 command 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)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
411
•
•
•
•
•
•
#define emberCopyEui64Argument(index, eui64)
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 leftPad)
8.35.1
Detailed Description
Processes commands coming from the serial port. See Commands2 for documentation.
Definition in file command-interpreter2.h.
8.36
00001
00010
00011
00012
00100
00101
00104
00105
00106
00107
00108
00109
00110
00115
00116
00117
00118
00119
00123
00124
00125
00126
00127
00128
00129
00131
00132
00133
00134
00135
00138
00144
00171
00175
00176
00177
00178
00179
00180
00181
00182
00183
00184
00185
00186
00187
00188
00189
00190
00191
00192
00193
00194
command-interpreter2.h
#ifndef __COMMAND_INTERPRETER2_H__
#define __COMMAND_INTERPRETER2_H__
#ifndef EMBER_MAX_COMMAND_ARGUMENTS
#define EMBER_MAX_COMMAND_ARGUMENTS 10
#endif
#ifndef EMBER_COMMAND_BUFFER_LENGTH
#define EMBER_COMMAND_BUFFER_LENGTH 100
#endif
#if defined(DOXYGEN_SHOULD_SKIP_THIS)
#define EMBER_COMMAND_INTEPRETER_HAS_DESCRIPTION_FIELD
#endif
// The (+ 1) takes into account the leading command.
#define MAX_TOKEN_COUNT (EMBER_MAX_COMMAND_ARGUMENTS + 1)
typedef void (*CommandAction)(void);
#ifdef DOXYGEN_SHOULD_SKIP_THIS
typedef struct {
#else
typedef PGM struct {
#endif
PGM_P name;
CommandAction action;
PGM_P argumentTypes;
PGM_P description;
} EmberCommandEntry;
#if defined(EMBER_COMMAND_INTEPRETER_HAS_DESCRIPTION_FIELD)
/* @brief Macro to define a CLI action */
#define emberCommandEntryAction(name, action, argumentTypes, description) \
{ (name), (action), (argumentTypes), (description) }
/* @brief Macro to define a CLI sub-menu (nested command) */
#define emberCommandEntrySubMenu(name, subMenu, description)
{ (name), NULL, (PGM_P)(subMenu), (description) }
\
/* @briefy Macro to define a command entry array terminator.*/
#define emberCommandEntryTerminator() \
{ NULL, NULL, NULL, NULL }
#else // Don’t include description data in struct
/* @brief Macro to define a CLI action */
#define emberCommandEntryAction(name, action, argumentTypes, description) \
EmberZNet 4.7.2 API EM250
120-3016-000-4720
412
00195
{ (name), (action), (argumentTypes), NULL }
00196
00197
/* @brief Macro to define a CLI sub-menu (nested command) */
00198
#define emberCommandEntrySubMenu(name, subMenu, description) \
00199
{ (name), NULL, (PGM_P)(subMenu), NULL }
00200
00201
/* @briefy Macro to define a command entry array terminator.*/
00202
#define emberCommandEntryTerminator() \
00203
{ NULL, NULL, NULL, NULL }
00204
00205 #endif
00206
00213 extern EmberCommandEntry *emberCurrentCommand
;
00214
00215 extern EmberCommandEntry emberCommandTable[];
00216
00220 extern int8u emberCommandInterpreter2Configuration
;
00221
00222 #define EMBER_COMMAND_INTERPRETER_CONFIGURATION_ECHO (0x01)
00223
00224 #ifdef DOXYGEN_SHOULD_SKIP_THIS
00225
00230 enum EmberCommandStatus
00231 #else
00232 typedef int8u EmberCommandStatus;
00233 enum
00234 #endif
00235 {
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_TYPE
00244 };
00245
00255 int8u emberCommandArgumentCount(void);
00256
00258 int32u emberUnsignedCommandArgument(int8u
argNum);
00259
00261 int16s emberSignedCommandArgument(int8u
argNum);
00262
00271 int8u *emberStringCommandArgument(int8s
argNum, int8u *length);
00272
00285 int8u emberCopyStringArgument(int8s argNum,
00286
int8u *destination,
00287
int8u maxLength,
00288
boolean leftPad);
00289
00293 #define emberCopyKeyArgument(index, keyDataPointer)
\
00294
(emberCopyStringArgument((index),
\
00295
emberKeyContents((keyDataPointer)), \
00296
EMBER_ENCRYPTION_KEY_SIZE,
\
00297
TRUE))
00298
00300 #define emberCopyEui64Argument(index, eui64) \
00301
(emberCopyStringArgument((index), (eui64), EUI64_SIZE, TRUE))
00302
00310 void emberCommandActionHandler(const CommandAction
action);
00317 void emberCommandErrorHandler(EmberCommandStatus
status);
00318 void emberPrintCommandUsage(EmberCommandEntry
*entry);
00319 void emberPrintCommandUsageNotes(void);
00320 void emberPrintCommandTable(void);
00321
00324 void emberCommandReaderInit(void);
00325
00328 boolean emberProcessCommandString(int8u *input,
EmberZNet 4.7.2 API EM250
120-3016-000-4720
413
int8u sizeOrPort);
00329
00338
00339
00340
00343
00344
00345
00346
00349
00350
00351
00352
00355
00356
00357
00358
00361
#define emberProcessCommandInput(port) \
emberProcessCommandString(NULL, port)
#define emberCommandInterpreterEchoOn()
(emberCommandInterpreter2Configuration
|= EMBER_COMMAND_INTERPRETER_CONFIGURATION_ECHO)
\
\
#define emberCommandInterpreterEchoOff()
(emberCommandInterpreter2Configuration
&= (~EMBER_COMMAND_INTERPRETER_CONFIGURATION_ECHO))
\
\
#define emberCommandInterpreterIsEchoOn()
(emberCommandInterpreter2Configuration
& EMBER_COMMAND_INTERPRETER_CONFIGURATION_ECHO)
\
\
#endif // __COMMAND_INTERPRETER2_H__
8.37
config.h File Reference
Macros
•
•
•
•
•
•
•
•
#define EMBER_MAJOR_VERSION
#define EMBER_MINOR_VERSION
#define EMBER_PATCH_VERSION
#define EMBER_SPECIAL_VERSION
#define EMBER_BUILD_NUMBER
#define EMBER_FULL_VERSION
#define EMBER_VERSION_TYPE
#define SOFTWARE_VERSION
8.37.1
Detailed Description
See Stack Information for documentation.
Definition in file config.h.
8.38
00001
00018
00019
00020
00021
00022
00023
00024
00025
00026
00027
00028
00029
00030
00031
00032
00033
00043
00044
config.h
// The 4 digit version: A.B.C.D
#define EMBER_MAJOR_VERSION
4
#define EMBER_MINOR_VERSION
7
#define EMBER_PATCH_VERSION
2
#define EMBER_SPECIAL_VERSION 0
// 2 bytes
#define EMBER_BUILD_NUMBER
88
((int16u)EMBER_MAJOR_VERSION << 12) \
| ((int16u)EMBER_MINOR_VERSION << 8) \
| ((int16u)EMBER_PATCH_VERSION << 4) \
| ((int16u)EMBER_SPECIAL_VERSION))
#define EMBER_FULL_VERSION (
#define EMBER_VERSION_TYPE EMBER_VERSION_TYPE_PRE_RELEASE
#define SOFTWARE_VERSION EMBER_FULL_VERSION
EmberZNet 4.7.2 API EM250
120-3016-000-4720
414
8.39
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)
8.39.1
Detailed Description
See Cyclic Redundancy Code (CRC) for detailed documentation.
Definition in file crc.h.
8.40
crc.h
00001
00007 #ifndef __CRC_H__
00008 #define __CRC_H__
00009
00028 int16u halCommonCrc16(int8u newByte, int16u
prevResult);
00029
00030
00046 int32u halCommonCrc32(int8u newByte, int32u
prevResult);
00047
00048 // Commonly used initial and expected final CRC32 values
00049 #define INITIAL_CRC
0xFFFFFFFFL
00050 #define CRC32_START
INITIAL_CRC
00051 #define CRC32_END
0xDEBB20E3L // For CRC32 POLYNOMIAL run
LSB-MSB
00052
00053
00057 #endif //__CRC_H__
00058
8.41
dev0455.h File Reference
Custom Baud Rate Definitions
The following define is used when defining a custom baud rate for the UART. This define provides a simple
hook into the definition of the baud rates used with the UART. The baudSettings[] array in uart.c links the
BAUD_∗ defines with the actual register values needed for operating the UART. The array baudSettings[]
can be edited directly for a custom baud rate or another entry (the register settings) can be provided here
with this define.
• #define EMBER_SERIAL_BAUD_CUSTOM
EmberZNet 4.7.2 API EM250
120-3016-000-4720
415
LED Definitions
The following are used to aid in the abstraction with the LED connections. The microcontroller-specific
sources use these definitions so they are able to work across a variety of boards which could have different
connections. The names and ports/pins used below are intended to match with a schematic of the system
to provide the abstraction.
The HalBoardLedPins enum values should always be used when manipulating the state of LEDs, as they
directly refer to the GPIOs to which the LEDs are connected.
Note
• LEDs 0 and 1 are on the RCM.
• LEDs 2 and 3 are on the breakout board (dev0455).
• #define BOARDLED_MASK
• enum HalBoardLedPins {
BOARDLED0, BOARDLED1, BOARDLED2, BOARDLED3,
BOARD_ACTIVITY_LED, BOARD_HEARTBEAT_LED, BOARDLED0, BOARDLED1,
BOARDLED2, BOARDLED3, BOARD_ACTIVITY_LED, BOARD_HEARTBEAT_LED }
Button Definitions
The following are used to aid in the abstraction with the Button connections. The microcontroller-specific
sources use these definitions so they are able to work across a variety of boards which could have different
connections. The names and ports/pins used 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 the
GPIOs to which the buttons are connected.
Note
The GPIO number must match the IRQ letter
•
•
•
•
•
•
•
•
•
•
#define BUTTON0
#define BUTTON0_INTCFG
#define BUTTON0_FLT_BIT
#define BUTTON0_MOD_BITS
#define BUTTON0_INT_BIT
#define BUTTON1
#define BUTTON1_INTCFG
#define BUTTON1_FLT_BIT
#define BUTTON1_MOD_BITS
#define BUTTON1_INT_BIT
UART Protocol Connection Items
The following are used to aid in the abstraction with the EZSP-UART Protocol. The HAL uses these
definitions so it is able to work across a variety of boards which could have different connections. The
names and ports/pins used below are intended to match with a schematic of the system to provide the
abstraction.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
416
•
•
•
•
#define SC1_TXD
#define SC1_RXD
#define SC1_nCTS
#define SC1_nRTS
Temperature sensor ADC channel
Define the analog input channel connected to the LM-20 temperature sensor. The scale factor compensates
for different platform input ranges. GPIO6/ADC2 must be an analog input. GPIO7 must be an output and
set to a high level to power the sensor.
• #define TEMP_SENSOR_ADC_CHANNEL
• #define TEMP_SENSOR_SCALE_FACTOR
Packet Trace
When PACKET_TRACE is defined, ::GPIO_CFG will automatically be setup by halInit() to enable Packet
Trace support on GPIO Pins 4 and 5, in addition to the configuration specified below.
Note
This define will override any settings for GPIO 4 and 5.
• #define PACKET_TRACE
ENABLE OSC32K
When ENABLE_OSC32K is defined, halInit() will configure system timekeeping to utilize the external
32.768 kHz crystal oscillator rather than the internal 1 kHz RC oscillator.
On initial powerup the 32.768 kHz crystal oscillator will take a little while to start stable oscillation. This
only happens on initial powerup, not on wake-from-sleep, since the crystal usually stays running in deep
sleep mode.
When ENABLE_OSC32K is defined the crystal oscillator is started as part of halInit(). After the crystal
is started we delay for OSC32K_STARTUP_DELAY_MS (time in milliseconds). This delay allows the
crystal oscillator to stabilize before we start using it for system timing.
If you set OSC32K_STARTUP_DELAY_MS to less than the crystal’s startup time:
• The system timer won’t produce a reliable one millisecond tick before the crystal is stable.
• You may see some number of ticks of unknown period occur before the crystal is stable.
• halInit() will complete and application code will begin running, but any events based on the system
timer will not be accurate until the crystal is stable.
• An unstable system timer will only affect the APIs in system-timer.h.
Typical 32.768 kHz crystals measured by Ember take about 400 milliseconds to stabilize. Be sure to
characterize your particular crystal’s stabilization time since crystal behavior can vary.
• #define OSC32K_STARTUP_DELAY_MS
EmberZNet 4.7.2 API EM250
120-3016-000-4720
417
GPIO Configuration Definitions
This define does not equate to anything. It is used as a trigger to disable bias adjustment of the 24 MHz
crystal oscillator on the RCM (0452) plugged into the Breakout board (dev0455). Default is to enable bias
adjustment.
The following are used to specify the GPIO configuration to establish when Powered (POWERUP_), and
when Deep Sleeping (POWERDN_). The reason for separate Deep Sleep settings is to allow for a slightly
different configuration that minimizes power consumption during Deep Sleep. For example, inputs that
might float could be pulled up or down, and output states chosen with care, e.g. to turn off LEDs or other
devices that might consume power or be unnecessary when Deep Sleeping.
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
#define GPIO(n)
#define POWERUP_GPIO_DBG
#define POWERUP_GPIO_CFG
#define POWERUP_GPIO_DIRH
#define POWERUP_GPIO_DIRL
#define POWERUP_GPIO_CLRH
#define POWERUP_GPIO_CLRL
#define POWERUP_GPIO_SETH
#define POWERUP_GPIO_SETL
#define POWERUP_GPIO_PUH
#define POWERUP_GPIO_PUL
#define POWERUP_GPIO_PDH
#define POWERUP_GPIO_PDL
#define POWERDN_GPIO_DBG
#define POWERDN_GPIO_CFG
#define POWERDN_GPIO_DIRH
#define POWERDN_GPIO_DIRL
#define POWERDN_GPIO_CLRH
#define POWERDN_GPIO_CLRL
#define POWERDN_GPIO_SETH
#define POWERDN_GPIO_SETL
#define POWERDN_GPIO_PUH
#define POWERDN_GPIO_PUL
#define POWERDN_GPIO_PDH
#define POWERDN_GPIO_PDL
#define WAKE_ON_GPIO0
#define WAKE_ON_GPIO1
#define WAKE_ON_GPIO2
#define WAKE_ON_GPIO3
#define WAKE_ON_GPIO4
#define WAKE_ON_GPIO5
#define WAKE_ON_GPIO6
#define WAKE_ON_GPIO7
#define WAKE_ON_GPIO8
#define WAKE_ON_GPIO9
#define WAKE_ON_GPIO10
#define WAKE_ON_GPIO11
#define WAKE_ON_GPIO12
#define WAKE_ON_GPIO13
#define WAKE_ON_GPIO14
#define WAKE_ON_GPIO15
#define WAKE_ON_GPIO16
EmberZNet 4.7.2 API EM250
120-3016-000-4720
418
Board Specific Functions
The following macros exist to aid in the initialization, power up from sleep, and power down to sleep
operations. These macros are responsible for either initializing directly, or calling initialization functions
for 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()
8.41.1
Detailed Description
See Sample Breakout Board Configuration for detailed documentation.
Note
The file dev0455.h is intended to be copied, renamed, and customized for customer-specific hardware.
Definition in file dev0455.h.
8.42
00001
00019
00020
00021
00039
00040
00068
00069
00070
00071
00072
00073
00074
00075
00080
00081
00105
00106
00109
00110
00113
00114
00117
00118
00121
00122
00127
00128
00131
00132
00135
00136
00139
00140
00143
00144
00156
00157
00158
00159
00160
00171
dev0455.h
#ifndef __BOARD_H__
#define __BOARD_H__
#define EMBER_SERIAL_BAUD_CUSTOM
13
enum HalBoardLedPins {
BOARDLED0 = 14,
BOARDLED1 = 13,
BOARDLED2 = 12,
BOARDLED3 = 11,
BOARD_ACTIVITY_LED = BOARDLED0,
BOARD_HEARTBEAT_LED = BOARDLED1
};
#define BOARDLED_MASK 0x7800
#define BUTTON0
8
#define BUTTON0_INTCFG
GPIO_INTCFGA
#define BUTTON0_FLT_BIT
GPIO_INTFILT_BIT
#define BUTTON0_MOD_BITS
GPIO_INTMOD_BIT
#define BUTTON0_INT_BIT
INT_GPIOA
#define BUTTON1
15
#define BUTTON1_INTCFG
GPIO_INTCFGC
#define BUTTON1_FLT_BIT
GPIO_INTFILT_BIT
#define BUTTON1_MOD_BITS
GPIO_INTMOD_BIT
#define BUTTON1_INT_BIT
INT_GPIOC
#define
#define
#define
#define
//the pin, also value used throughout HAL and app
//the pin, also value used throughout HAL and app
SC1_TXD
9
SC1_RXD 10
SC1_nCTS 11
SC1_nRTS 12
#define TEMP_SENSOR_ADC_CHANNEL ADC_SOURCE_ADC2_GND
EmberZNet 4.7.2 API EM250
120-3016-000-4720
419
00172
00173
00190
00191
00226
00227
00228
00229
00230
00231
00238
00239
00259
00260
00263
00264
00265
00266
00267
00268
00269
00270
00271
00272
00273
00274
00275
00276
00277
00278
00279
00280
00281
00282
00283
00284
00285
00286
00287
00288
00289
00290
00291
00292
00293
00294
00295
00313
00314
00318
00319
00322
00323
00324
00325
00326
00327
00328
00329
00330
00331
00332
00333
00334
00335
00338
00339
00342
00343
00344
00345
00346
00347
00348
00349
00352
00353
00356
00357
00360
#define TEMP_SENSOR_SCALE_FACTOR 1
#define PACKET_TRACE
// We do have PACKET_TRACE support
#define OSC32K_STARTUP_DELAY_MS (0)
#if OSC32K_STARTUP_DELAY_MS > MAX_INT16U_VALUE
#error "OSC32K_STARTUP_DELAY_MS must fit in 16 bits."
#endif
//#define ENABLE_OSC32K
// Enable 32.768 kHz osc instead of 1 kHz RC osc
//#define DISABLE_OSC24M_BIAS_TRIM
// Disable 24 MHz bias trim adjustment
//Since the two GPIO config registers affect multiple modules, it is not
//possible for one or more of the modules to own the configuration
//of the GPIO. This is the only place the registers should be touched.
//The groups of comments below are setting for a couple common modes.
/*
//GPIO[16,15,14,13]
//+ SC1-2 + SC2-2 + CAP2-0 + CAP1-0 + GPIO[12,11,3,0]
GPIO_DBG = 0x0000;
GPIO_CFG = 0x0010;
*/
/*
// TMR1OB
//+ GPIO[15,14,13]
//+ SC1-2 + SC2-4S + CAP2-0 + CAP1-2h + GPIO[12,11]
GPIO_DBG = 0x0000;
GPIO_CFG = 0x0058;
*/
/*
//GPIO[16,15,14,13]
//+ SC1-3M + SC2-4S + CAP2-2 + CAP1-2h + GPIO[12]
GPIO_DBG = 0x0000;
GPIO_CFG = 0x00F0;
*/
/*
** DEFAULT CONFIGURATION **
// TMR1OB
//+ GPIO[15,14,13]
//+ SC1-2 + SC2-3M + CAP2-0 + CAP1-2 + GPIO[12,11,3]
//+ ADC2
GPIO_DBG = 0x0000;
GPIO_CFG = 0x0498;
*/
#define GPIO(n) (1u << ((n) & 0xF))
#define POWERUP_GPIO_DBG
0
#ifdef EMBER_SERIAL1_RTSCTS
#ifdef PACKET_TRACE
#define POWERUP_GPIO_CFG
#else
#define POWERUP_GPIO_CFG
#endif //PACKET_TRACE
#else
#ifdef PACKET_TRACE
#define POWERUP_GPIO_CFG
#else
#define POWERUP_GPIO_CFG
#endif //PACKET_TRACE
#endif //EMBER_SERIAL1_RTSCTS
#define POWERUP_GPIO_DIRH
#ifdef EMBER_SERIAL1_RTSCTS
#define POWERUP_GPIO_DIRL
#else
#define POWERUP_GPIO_DIRL
0x1468 // UART + RST/CTS + PacketTrace
0x0468 // UART + RST/CTS
0x1498 // UART + PacketTrace
0x0498 // UART
0
// GPIO16 = Input
(BOARDLED_MASK|GPIO(7)|GPIO(5)|GPIO(4)|GPIO(3)\
|BIT(SC1_nRTS)|BIT(SC1_TXD))//RTS, TXD are output
(BOARDLED_MASK|GPIO(7)|GPIO(5)|GPIO(4)|GPIO(3))
// LEDs & GPIO7,5,4,3 outputs
#endif
#define POWERUP_GPIO_CLRH
0
// No output state change
#define POWERUP_GPIO_CLRL
GPIO(4)
// GPIO4 low
#define POWERUP_GPIO_SETH
0
// No output state change
EmberZNet 4.7.2 API EM250
120-3016-000-4720
420
00361
00364
00365
00366
00367
00368
00369
00370
00371
00375
00376
00380
00381
00382
00383
00384
00385
00386
00390
00391
00395
00396
00397
00398
00399
00400
00404
00405
00408
00409
00413
00414
00417
00418
00421
00422
00425
00426
00429
00430
00433
00434
00438
00439
00443
00444
00445
00446
00447
00448
00449
00450
00451
00452
00453
00454
00455
00456
00457
00458
00459
00463
00464
00468
00469
00470
00471
00472
00473
00474
00475
00476
00477
00478
00479
00480
00486
00487
00488
00489
#ifdef EMBER_SERIAL1_RTSCTS
#define POWERUP_GPIO_SETL
(BOARDLED_MASK|GPIO(7)|GPIO(5) \
|BIT(SC1_nRTS)|BIT(SC1_TXD))//RTS, TXD are high
#else
#define POWERUP_GPIO_SETL
(BOARDLED_MASK|GPIO(7)|GPIO(5))
// LEDs off (high), GPIO7,5 high
#endif
#define POWERUP_GPIO_PUH
0
#ifdef EMBER_SERIAL1_RTSCTS
#define POWERUP_GPIO_PUL
#else
#define POWERUP_GPIO_PUL
// No pullup on GPIO16
(GPIO(BUTTON1)|GPIO(BUTTON0)|BIT(SC1_RXD))
(GPIO(BUTTON1)|GPIO(BUTTON0))
// Pullup Buttons
#endif
#define POWERUP_GPIO_PDH
0
#ifdef EMBER_SERIAL1_RTSCTS
#define POWERUP_GPIO_PDL
#else
#define POWERUP_GPIO_PDL
#endif
#define POWERDN_GPIO_DBG
// No pulldown on GPIO16
(BIT(SC1_nCTS))
// PD only on GPIO11 (nCTS)
0x0000
// No pulldowns on GPIO15..0
POWERUP_GPIO_DBG
#define POWERDN_GPIO_CFG
#define POWERDN_GPIO_DIRH
(POWERUP_GPIO_CFG & ~0x4F00)
// Disable analog I/O switches
POWERUP_GPIO_DIRH
#define POWERDN_GPIO_DIRL
POWERUP_GPIO_DIRL
#define POWERDN_GPIO_CLRH
0
// No output state change
#define POWERDN_GPIO_CLRL
0x0000
// No output state change
#define POWERDN_GPIO_SETH
0
// No output state change
#define POWERDN_GPIO_SETL
BOARDLED_MASK
// LEDs off (high)
#define POWERDN_GPIO_PUH
POWERUP_GPIO_PUH
#ifdef PACKET_TRACE
#define POWERDN_GPIO_PUL
#else
#define POWERDN_GPIO_PUL
(POWERUP_GPIO_PUL
|GPIO(0)
|GPIO(1)
|GPIO(5)
|GPIO(9)
|GPIO(10)
)
/*
/*
/*
/*
/*
SC1
SC1
PTI
SC2
SC2
MOSI
MISO
DATA
TXD
RXD
pull
pull
pull
pull
pull
up
up
up
up
up
*/
*/
*/
*/
*/
\
\
\
\
\
\
(POWERUP_GPIO_PUL
|GPIO(0)
|GPIO(1)
|GPIO(9)
|GPIO(10)
)
/*
/*
/*
/*
SC1
SC1
SC2
SC2
MOSI
MISO
TXD
RXD
pull
pull
pull
pull
up
up
up
up
*/
*/
*/
*/
\
\
\
\
\
#endif//PACKET_TRACE
#define POWERDN_GPIO_PDH
#ifdef PACKET_TRACE
#define POWERDN_GPIO_PDL
#else
#define POWERDN_GPIO_PDL
(POWERUP_GPIO_PDH|GPIO(16)) // TMR1 pull down
(POWERUP_GPIO_PDL
|GPIO(2)
|GPIO(4)
|GPIO(6)
)
\
/* SC1 MSCLK pull down */ \
/* PTI
EN pull down */ \
/* GPIO6
pull down */ \
(POWERUP_GPIO_PDL
|GPIO(2)
|GPIO(6)
)
\
/* SC1 MSCLK pull down */ \
/* GPIO6
pull down */ \
#endif//PACKET_TRACE
#define
#define
#define
#define
EmberZNet 4.7.2 API EM250
WAKE_ON_GPIO0
WAKE_ON_GPIO1
WAKE_ON_GPIO2
WAKE_ON_GPIO3
FALSE
FALSE
FALSE
FALSE
120-3016-000-4720
421
00490
00491
00492
00493
00494
00495
00496
00497
00498
00499
00500
00501
00502
00503
00521
00522
00523
00524
00525
00526
00527
00528
00529
00530
00531
00532
00533
00534
00538
00539
00540
00541
00542
00543
00544
00545
00546
00547
00548
00549
00550
00551
00552
00553
00554
00555
00556
00560
00561
00562
00563
00564
00565
00566
00567
00568
00569
00570
00571
00572
00573
00574
00575
00576
00577
00578
00579
00580
00581
8.43
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
WAKE_ON_GPIO4
WAKE_ON_GPIO5
WAKE_ON_GPIO6
WAKE_ON_GPIO7
WAKE_ON_GPIO8
WAKE_ON_GPIO9
WAKE_ON_GPIO10
WAKE_ON_GPIO11
WAKE_ON_GPIO12
WAKE_ON_GPIO13
WAKE_ON_GPIO14
WAKE_ON_GPIO15
WAKE_ON_GPIO16
FALSE
FALSE
FALSE
FALSE
TRUE
FALSE
FALSE
FALSE
FALSE
FALSE
FALSE
TRUE
FALSE
//BUTTON0
//BUTTON1
#ifndef EZSP_UART
#define halInternalInitBoard()
do {
halInternalPowerUpBoard();
halInternalRestartUart();
halInternalInitButton();
} while(0)
#else
#define halInternalInitBoard()
do {
halInternalPowerUpBoard();
} while(0)
#endif
#define halInternalPowerDownBoard()
do {
/* GPIO Output configuration */
GPIO_CLRH = POWERDN_GPIO_CLRH; /*
GPIO_CLRL = POWERDN_GPIO_CLRL; /*
GPIO_SETH = POWERDN_GPIO_SETH; /*
GPIO_SETL = POWERDN_GPIO_SETL; /*
GPIO_DIRH = POWERDN_GPIO_DIRH; /*
GPIO_DIRL = POWERDN_GPIO_DIRL; /*
/* GPIO Mode Config (see above) */
GPIO_DBG
= POWERDN_GPIO_DBG;
GPIO_CFG
= POWERDN_GPIO_CFG;
/* GPIO Pullup/Pulldown Config */
GPIO_PDH
= POWERDN_GPIO_PDH;
GPIO_PDL
= POWERDN_GPIO_PDL;
GPIO_PUH
= POWERDN_GPIO_PUH;
GPIO_PUL
= POWERDN_GPIO_PUL;
} while(0)
#define halInternalPowerUpBoard()
do {
/* GPIO Pullup/Pulldown Config */
GPIO_PUH
= POWERUP_GPIO_PUH;
GPIO_PUL
= POWERUP_GPIO_PUL;
GPIO_PDH
= POWERUP_GPIO_PDH;
GPIO_PDL
= POWERUP_GPIO_PDL;
/* GPIO Mode Config (see above) */
GPIO_DBG
= POWERUP_GPIO_DBG;
GPIO_CFG
= POWERUP_GPIO_CFG;
/* GPIO Output configuration */
GPIO_CLRH = POWERUP_GPIO_CLRH; /*
GPIO_CLRL = POWERUP_GPIO_CLRL; /*
GPIO_SETH = POWERUP_GPIO_SETH; /*
GPIO_SETL = POWERUP_GPIO_SETL; /*
GPIO_DIRH = POWERUP_GPIO_DIRH; /*
GPIO_DIRL = POWERUP_GPIO_DIRL; /*
} while(0)
\
\
\
\
\
\
\
\
output
output
output
output
output
output
output
output
output
output
output
output
states
states
states
states
enables
enables
states
states
states
states
enables
enables
#endif //__BOARD_H__
dev0455i2c.h File Reference
EmberZNet 4.7.2 API EM250
120-3016-000-4720
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
422
Custom Baud Rate Definitions
The following define is used with defining a custom baud rate for the UART. This define provides a simple
hook into the definition of the baud rates used with the UART. The baudSettings[] array in uart.c links the
BAUD_∗ defines with the actual register values needed for operating the UART. The array baudSettings[]
can be edited directly for a custom baud rate or another entry (the register settings) can be provided here
with this define.
• #define EMBER_SERIAL_BAUD_CUSTOM
LED Definitions
The following are used to aid in the abstraction with the LED connections. The microcontroller-specific
sources use these definitions so they are able to work across a variety of boards which could have different
connections. The names and ports/pins used below are intended to match with a schematic of the system
to provide the abstraction.
The BOARDLEDn enum values should always be used when manipulating the state of LEDs, as they
directly refer to the GPIOs to which the LEDs are connected.
Note
LEDs 0 and 1 are on the RCM.
LEDs 2 and 3 are on the breakout board (dev0455).
• #define BOARDLED_MASK
• enum HalBoardLedPins {
BOARDLED0, BOARDLED1, BOARDLED2, BOARDLED3,
BOARD_ACTIVITY_LED, BOARD_HEARTBEAT_LED, BOARDLED0, BOARDLED1,
BOARDLED2, BOARDLED3, BOARD_ACTIVITY_LED, BOARD_HEARTBEAT_LED }
Button Definitions
The following are used to aid in the abstraction with the Button connections. The microcontroller-specific
sources use these definitions so they are able to work across a variety of boards which could have different
connections. The names and ports/pins used 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 the
GPIOs to which the buttons are connected.
Note
The GPIO number must match the IRQ letter
•
•
•
•
•
•
•
•
•
•
#define BUTTON0
#define BUTTON0_INTCFG
#define BUTTON0_FLT_BIT
#define BUTTON0_MOD_BITS
#define BUTTON0_INT_BIT
#define BUTTON1
#define BUTTON1_INTCFG
#define BUTTON1_FLT_BIT
#define BUTTON1_MOD_BITS
#define BUTTON1_INT_BIT
EmberZNet 4.7.2 API EM250
120-3016-000-4720
423
UART Protocol Connection Items
The following are used to aid in the abstraction with the EZSP-UART Protocol. The HAL uses these
definitions so it is able to work across a variety of boards which could have different connections. The
names and ports/pins used below are intended to match with a schematic of the system to provide the
abstraction.
•
•
•
•
#define SC1_TXD
#define SC1_RXD
#define SC1_nCTS
#define SC1_nRTS
Temperature sensor ADC channel
Define the analog input channel connected to the LM-20 temperature sensor. The scale factor compensates
for different platform input ranges. GPIO6/ADC2 must be an analog input. GPIO7 must be an output and
set to a high level to power the sensor.
• #define TEMP_SENSOR_ADC_CHANNEL
• #define TEMP_SENSOR_SCALE_FACTOR
Packet Trace
When PACKET_TRACE is defined, GPIO_CFG will automatically be setup by halInit() to enable Packet
Trace support on GPIO Pins 4 and 5, in addition to the configuration specified below.
Note
This define will override any settings for GPIO 4 and 5.
• #define PACKET_TRACE
ENABLE OSC32K
When ENABLE_OSC32K is defined, halInit() will configure system timekeeping to utilize the external
32.768 kHz crystal oscillator rather than the internal 1 kHz RC oscillator.
On initial powerup the 32.768 kHz crystal oscillator will take a little while to start stable oscillation. This
only happens on initial powerup, not on wake-from-sleep, since the crystal usually stays running in deep
sleep mode.
When ENABLE_OSC32K is defined the crystal oscillator is started as part of halInit(). After the crystal
is started we delay for OSC32K_STARTUP_DELAY_MS (time in milliseconds). This delay allows the
crystal oscillator to stabilize before we start using it for system timing.
If you set OSC32K_STARTUP_DELAY_MS to less than the crystal’s startup time:
• The system timer won’t produce a reliable one millisecond tick before the crystal is stable.
• You may see some number of ticks of unknown period occur before the crystal is stable.
• halInit() will complete and application code will begin running, but any events based on the system
timer will not be accurate until the crystal is stable.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
424
• An unstable system timer will only affect the APIs in system-timer.h.
Typical 32.768 kHz crystals measured by Ember take about 400 milliseconds to stabilize. Be sure to
characterize your particular crystal’s stabilization time since crystal behavior can vary.
• #define OSC32K_STARTUP_DELAY_MS
GPIO Configuration Definitions
This define does not equate to anything. It is used as a trigger to disable bias adjustment of the 24 MHz
crystal oscillator on the RCM (0452) plugged into the Breakout board (dev0455). Default is to enable bias
adjustment.
The following are used to specify the GPIO configuration to establish when Powered (POWERUP_), and
when Deep Sleeping (POWERDN_). The reason for separate Deep Sleep settings is to allow for a slightly
different configuration that minimizes power consumption during Deep Sleep. For example, inputs that
might float could be pulled up or down, and output states chosen with care, e.g. to turn off LEDs or other
devices that might consume power or be unnecessary when Deep Sleeping.
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
#define GPIO(n)
#define POWERUP_GPIO_DBG
#define POWERUP_GPIO_CFG
#define POWERUP_GPIO_DIRH
#define POWERUP_GPIO_DIRL
#define POWERUP_GPIO_CLRH
#define POWERUP_GPIO_CLRL
#define POWERUP_GPIO_SETH
#define POWERUP_GPIO_SETL
#define POWERUP_GPIO_PUH
#define POWERUP_GPIO_PUL
#define POWERUP_GPIO_PDH
#define POWERUP_GPIO_PDL
#define POWERDN_GPIO_DBG
#define POWERDN_GPIO_CFG
#define POWERDN_GPIO_DIRH
#define POWERDN_GPIO_DIRL
#define POWERDN_GPIO_CLRH
#define POWERDN_GPIO_CLRL
#define POWERDN_GPIO_SETH
#define POWERDN_GPIO_SETL
#define POWERDN_GPIO_PUH
#define POWERDN_GPIO_PUL
#define POWERDN_GPIO_PDH
#define POWERDN_GPIO_PDL
#define WAKE_ON_GPIO0
#define WAKE_ON_GPIO1
#define WAKE_ON_GPIO2
#define WAKE_ON_GPIO3
#define WAKE_ON_GPIO4
#define WAKE_ON_GPIO5
#define WAKE_ON_GPIO6
EmberZNet 4.7.2 API EM250
120-3016-000-4720
425
•
•
•
•
•
•
•
•
•
•
#define WAKE_ON_GPIO7
#define WAKE_ON_GPIO8
#define WAKE_ON_GPIO9
#define WAKE_ON_GPIO10
#define WAKE_ON_GPIO11
#define WAKE_ON_GPIO12
#define WAKE_ON_GPIO13
#define WAKE_ON_GPIO14
#define WAKE_ON_GPIO15
#define WAKE_ON_GPIO16
Board Specific Functions
The following macros exist to aid in the initialization, power up from sleep, and power down to sleep
operations. These macros are responsible for either initializing directly, or calling initialization functions
for 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()
8.43.1
Detailed Description
Functions and definitions specific to the breakout board. See also Sample Breakout Board Configuration
for detailed documentation. Based on the default BOARD_HEADER file (dev0455.h) for use with the
breakout board (development kit) expanded to use the SC2 I2C interface.
Definition in file dev0455i2c.h.
8.43.2
Macro Definition Documentation
8.43.2.1
#define EMBER SERIAL BAUD CUSTOM
This define is the register setting for generating a baud of.
1. Refer to the EM250 datasheet’s discussion on UART baud rates for the equation used to derive this
value.
Definition at line 37 of file dev0455i2c.h.
8.43.2.2
#define BOARDLED MASK
This mask indicates which GPIO the LEDs are connected to. A bit is set for each GPIO to which an LED
is connected.
Definition at line 75 of file dev0455i2c.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
426
8.43.2.3
#define BUTTON0
The actual GPIO BUTTON0 is connected to. This define should be used whenever referencing BUTTON0.
Definition at line 97 of file dev0455i2c.h.
8.43.2.4
#define BUTTON0 INTCFG
The interrupt configuration register for BUTTON0.
Definition at line 101 of file dev0455i2c.h.
8.43.2.5
#define BUTTON0 FLT BIT
The filter bit for BUTTON0.
Definition at line 105 of file dev0455i2c.h.
8.43.2.6
#define BUTTON0 MOD BITS
The interrupt trigger selection for BUTTON0.
Definition at line 109 of file dev0455i2c.h.
8.43.2.7
#define BUTTON0 INT BIT
The interrupt bit for BUTTON0.
Definition at line 113 of file dev0455i2c.h.
8.43.2.8
#define BUTTON1
The actual GPIO BUTTON1 is connected to. This define should be used whenever referencing BUTTON1.
Definition at line 119 of file dev0455i2c.h.
8.43.2.9
#define BUTTON1 INTCFG
The interrupt configuration register for BUTTON1.
Definition at line 123 of file dev0455i2c.h.
8.43.2.10
#define BUTTON1 FLT BIT
The filter bit for BUTTON1.
Definition at line 127 of file dev0455i2c.h.
8.43.2.11
#define BUTTON1 MOD BITS
The interrupt trigger selection for BUTTON1.
Definition at line 131 of file dev0455i2c.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
427
8.43.2.12
#define BUTTON1 INT BIT
The interrupt bit for BUTTON1.
Definition at line 135 of file dev0455i2c.h.
8.43.2.13
#define SC1 TXD
Definition at line 147 of file dev0455i2c.h.
8.43.2.14
#define SC1 RXD
Definition at line 148 of file dev0455i2c.h.
8.43.2.15
#define SC1 nCTS
Definition at line 149 of file dev0455i2c.h.
8.43.2.16
#define SC1 nRTS
Definition at line 150 of file dev0455i2c.h.
8.43.2.17
#define TEMP SENSOR ADC CHANNEL
Definition at line 162 of file dev0455i2c.h.
8.43.2.18
#define TEMP SENSOR SCALE FACTOR
Definition at line 163 of file dev0455i2c.h.
8.43.2.19
#define PACKET TRACE
This define does not equate to anything. It is used as a trigger to enable Packet Trace support on the
breakout board (dev0455).
Definition at line 179 of file dev0455i2c.h.
8.43.2.20
#define OSC32K STARTUP DELAY MS
Definition at line 213 of file dev0455i2c.h.
8.43.2.21
#define GPIO( n )
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 300 of file dev0455i2c.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
428
8.43.2.22
#define POWERUP GPIO DBG
Powered setting of GPIO_DBG debug configuration register.
Definition at line 305 of file dev0455i2c.h.
8.43.2.23
#define POWERUP GPIO CFG
EMBER_SERIAL1_RTSCTS.
Powered setting of GPIO_CFG configuration register.
Definition at line 317 of file dev0455i2c.h.
8.43.2.24
#define POWERUP GPIO DIRH
Powered setting of GPIO_DIRH GPIO16 output-enable register.
Definition at line 325 of file dev0455i2c.h.
8.43.2.25
#define POWERUP GPIO DIRL
Powered setting of GPIO_DIRL GPIO15..0 output-enable register.
Definition at line 333 of file dev0455i2c.h.
8.43.2.26
#define POWERUP GPIO CLRH
Powered setting of GPIO_CLRH clear GPIO16 output register.
Definition at line 339 of file dev0455i2c.h.
8.43.2.27
#define POWERUP GPIO CLRL
Powered setting of GPIO_CLRL clear GPIO15..0 outputs register.
Definition at line 343 of file dev0455i2c.h.
8.43.2.28
#define POWERUP GPIO SETH
Powered setting of GPIO_SETH set GPIO16 output register.
Definition at line 347 of file dev0455i2c.h.
8.43.2.29
#define POWERUP GPIO SETL
Powered setting of GPIO_SETL set GPIO15..0 outputs register.
Definition at line 355 of file dev0455i2c.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
429
8.43.2.30
#define POWERUP GPIO PUH
Powered setting of GPIO_PUH GPIO16 pullup resistor enable register.
Definition at line 362 of file dev0455i2c.h.
8.43.2.31
#define POWERUP GPIO PUL
Powered setting of GPIO_PUL GPIO15..0 pullup resistors enable register.
Definition at line 370 of file dev0455i2c.h.
8.43.2.32
#define POWERUP GPIO PDH
Powered setting of GPIO_PDH GPIO16 pulldown resistor enable register.
Definition at line 377 of file dev0455i2c.h.
8.43.2.33
#define POWERUP GPIO PDL
Powered setting of GPIO_PDL GPIO15..0 pulldown resistors enable register.
Definition at line 385 of file dev0455i2c.h.
8.43.2.34
#define POWERDN GPIO DBG
Deep Sleep setting of GPIO_DBG debug configuration register.
Definition at line 391 of file dev0455i2c.h.
8.43.2.35
#define POWERDN GPIO CFG
Deep Sleep setting of GPIO_CFG configuration register.
Definition at line 395 of file dev0455i2c.h.
8.43.2.36
#define POWERDN GPIO DIRH
Deep Sleep setting of GPIO_DIRH GPIO16 output-enable register.
Definition at line 400 of file dev0455i2c.h.
8.43.2.37
#define POWERDN GPIO DIRL
Deep Sleep setting of GPIO_DIRL GPIO15..0 output-enable register.
Definition at line 404 of file dev0455i2c.h.
8.43.2.38
#define POWERDN GPIO CLRH
Deep Sleep setting of GPIO_CLRH clear GPIO16 output register.
Definition at line 408 of file dev0455i2c.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
430
8.43.2.39
#define POWERDN GPIO CLRL
Deep Sleep setting of GPIO_CLRL clear GPIO15..0 outputs register.
Definition at line 412 of file dev0455i2c.h.
8.43.2.40
#define POWERDN GPIO SETH
Deep Sleep setting of GPIO_SETH set GPIO16 output register.
Definition at line 416 of file dev0455i2c.h.
8.43.2.41
#define POWERDN GPIO SETL
Deep Sleep setting of GPIO_SETL set GPIO15..0 outputs register.
Definition at line 420 of file dev0455i2c.h.
8.43.2.42
#define POWERDN GPIO PUH
Deep Sleep setting of GPIO_PUH GPIO16 pullup resistor enable register.
Definition at line 425 of file dev0455i2c.h.
8.43.2.43
#define POWERDN GPIO PUL
Deep Sleep setting of GPIO_PUL GPIO15..0 pullup resistors enable register.
Definition at line 431 of file dev0455i2c.h.
8.43.2.44
#define POWERDN GPIO PDH
Deep Sleep setting of GPIO_PDH GPIO16 pulldown resistor enable register.
Definition at line 450 of file dev0455i2c.h.
8.43.2.45
#define POWERDN GPIO PDL
Deep Sleep setting of GPIO_PDL GPIO15..0 pulldown resistors enable register.
Definition at line 456 of file dev0455i2c.h.
8.43.2.46
#define WAKE ON GPIO0
A convenient define that chooses if this external signal can be used as source to wake from deep sleep. Any
change in the state of the signal will wake up the CPU.
Definition at line 474 of file dev0455i2c.h.
8.43.2.47
#define WAKE ON GPIO1
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
431
Definition at line 475 of file dev0455i2c.h.
8.43.2.48
#define WAKE ON GPIO2
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 476 of file dev0455i2c.h.
8.43.2.49
#define WAKE ON GPIO3
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 477 of file dev0455i2c.h.
8.43.2.50
#define WAKE ON GPIO4
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 478 of file dev0455i2c.h.
8.43.2.51
#define WAKE ON GPIO5
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 479 of file dev0455i2c.h.
8.43.2.52
#define WAKE ON GPIO6
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 480 of file dev0455i2c.h.
8.43.2.53
#define WAKE ON GPIO7
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 481 of file dev0455i2c.h.
8.43.2.54
#define WAKE ON GPIO8
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 482 of file dev0455i2c.h.
8.43.2.55
#define WAKE ON GPIO9
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 483 of file dev0455i2c.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
432
8.43.2.56
#define WAKE ON GPIO10
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 484 of file dev0455i2c.h.
8.43.2.57
#define WAKE ON GPIO11
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 485 of file dev0455i2c.h.
8.43.2.58
#define WAKE ON GPIO12
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 486 of file dev0455i2c.h.
8.43.2.59
#define WAKE ON GPIO13
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 487 of file dev0455i2c.h.
8.43.2.60
#define WAKE ON GPIO14
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 488 of file dev0455i2c.h.
8.43.2.61
#define WAKE ON GPIO15
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 489 of file dev0455i2c.h.
8.43.2.62
#define WAKE ON GPIO16
A convenience macro to convert GPIO# into bit mask for the GPIO registers.
Definition at line 490 of file dev0455i2c.h.
8.43.2.63
#define halInternalInitBoard( )
Initialize the board. This function is called from halInit().
Definition at line 510 of file dev0455i2c.h.
8.43.2.64
#define halInternalPowerDownBoard( )
Power down the board. This function is called from halPowerDown().
Definition at line 527 of file dev0455i2c.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
433
8.43.2.65
#define halInternalPowerUpBoard( )
Power up the board. This function is called from halPowerUp().
Definition at line 551 of file dev0455i2c.h.
8.43.3
Enumeration Type Documentation
8.43.3.1
enum HalBoardLedPins
Assign each GPIO with an LED connected to a convenient name. BOARD_ACTIVITY_LED and BOARD_HEARTBEAT_LED provide a further layer of abstraction ontop of the 4 LEDs for verbose coding.
Enumerator:
BOARDLED0
BOARDLED1
BOARDLED2
BOARDLED3
BOARD_ACTIVITY_LED
BOARD_HEARTBEAT_LED
BOARDLED0
BOARDLED1
BOARDLED2
BOARDLED3
BOARD_ACTIVITY_LED
BOARD_HEARTBEAT_LED
Definition at line 63 of file dev0455i2c.h.
8.44
00001
00018
00019
00020
00037
00038
00039
00063
00064
00065
00066
00067
00068
00069
00070
00075
00076
00077
00097
00098
00101
00102
00105
00106
00109
dev0455i2c.h
#ifndef __BOARD_H__
#define __BOARD_H__
#define EMBER_SERIAL_BAUD_CUSTOM
13
enum HalBoardLedPins {
BOARDLED0 = 14,
BOARDLED1 = 13,
BOARDLED2 = 12,
BOARDLED3 = 11,
BOARD_ACTIVITY_LED = BOARDLED0,
BOARD_HEARTBEAT_LED = BOARDLED1
};
#define BOARDLED_MASK 0x7800
#define BUTTON0
8
#define BUTTON0_INTCFG
GPIO_INTCFGA
#define BUTTON0_FLT_BIT
GPIO_INTFILT_BIT
#define BUTTON0_MOD_BITS
GPIO_INTMOD_BIT
EmberZNet 4.7.2 API EM250
//the pin, also value used throughout HAL and app
120-3016-000-4720
434
00110
00113
00114
00119
00120
00123
00124
00127
00128
00131
00132
00135
00136
00137
00147
00148
00149
00150
00151
00152
00162
00163
00164
00179
00180
00181
00213
00214
00215
00216
00217
00218
00225
00227
00243
00245
00246
00247
00248
00249
00250
00251
00252
00253
00254
00255
00256
00257
00258
00259
00260
00261
00262
00263
00264
00265
00266
00267
00268
00269
00270
00271
00272
00273
00274
00275
00276
00277
00278
00279
00280
00281
00282
00283
00284
00300
00301
00305
00306
00309
#define BUTTON0_INT_BIT
INT_GPIOA
#define BUTTON1
15
#define BUTTON1_INTCFG
GPIO_INTCFGC
#define BUTTON1_FLT_BIT
GPIO_INTFILT_BIT
#define BUTTON1_MOD_BITS
GPIO_INTMOD_BIT
#define BUTTON1_INT_BIT
INT_GPIOC
#define
#define
#define
#define
//the pin, also value used throughout HAL and app
SC1_TXD
9
SC1_RXD 10
SC1_nCTS 11
SC1_nRTS 12
#define TEMP_SENSOR_ADC_CHANNEL ADC_SOURCE_ADC2_GND
#define TEMP_SENSOR_SCALE_FACTOR 1
#define PACKET_TRACE
// We do have PACKET_TRACE support
#define OSC32K_STARTUP_DELAY_MS (0)
#if OSC32K_STARTUP_DELAY_MS > MAX_INT16U_VALUE
#error "OSC32K_STARTUP_DELAY_MS must fit in 16 bits."
#endif
//#define ENABLE_OSC32K
// Enable 32.768 kHz osc instead of 1 kHz RC osc
//#define DISABLE_OSC24M_BIAS_TRIM
// Disable 24 MHz bias trim adjustment
//Since the two GPIO config registers affect multiple modules, it is not
//possible for one or more of the modules to own the configuration
//of the GPIO. This is the only place the registers should be touched.
//The groups of comments below are setting for a couple common modes.
/*
//GPIO[16,15,14,13]
//+ SC1-2 + SC2-2 + CAP2-0 + CAP1-0 + GPIO[12,11,3,0]
GPIO_DBG = 0x0000;
GPIO_CFG = 0x0010;
*/
/*
// TMR1OB
//+ GPIO[15,14,13]
//+ SC1-2 + SC2-4S + CAP2-0 + CAP1-2h + GPIO[12,11]
GPIO_DBG = 0x0000;
GPIO_CFG = 0x0058;
*/
/*
//GPIO[16,15,14,13]
//+ SC1-3M + SC2-4S + CAP2-2 + CAP1-2h + GPIO[12]
GPIO_DBG = 0x0000;
GPIO_CFG = 0x00F0;
*/
/*
** DEFAULT CONFIGURATION **
// TMR1OB
//+ GPIO[15,14,13]
//+ SC1-2 + SC2-3M + CAP2-0 + CAP1-2 + GPIO[12,11,3]
//+ ADC2
GPIO_DBG = 0x0000;
GPIO_CFG = 0x0498;
*/
/*
** enable SC2 for I2C use **
GPIO_DBG = 0x0000;
GPIO_CFG = 0x0010; // SC2-2 mode, enable GPIOs 4,5,6,7,8,13,14,15,16
*/
#define GPIO(n) (1u << ((n) & 0xF))
#define POWERUP_GPIO_DBG
#ifdef EMBER_SERIAL1_RTSCTS
EmberZNet 4.7.2 API EM250
0
// Note: RTSCTS not configured
120-3016-000-4720
435
00310
00311
00312
00313
00314
00315
00316
00317
00318
00319
00320
00321
00322
00325
00326
00329
00330
00331
00332
00333
00334
00335
00336
00339
00340
00343
00344
00347
00348
00351
00352
00353
00354
00355
00356
00357
00358
00362
00363
00367
00368
00369
00370
00371
00372
00373
00377
00378
00382
00383
00384
00385
00386
00387
00391
00392
00395
00396
00400
00401
00404
00405
00408
00409
00412
00413
00416
00417
00420
00421
00425
00426
00430
00431
00432
00433
00434
00435
00436
00437
#ifdef PACKET_TRACE
#define POWERUP_GPIO_CFG
#else
#define POWERUP_GPIO_CFG
#endif //PACKET_TRACE
#else
#ifdef PACKET_TRACE
#define POWERUP_GPIO_CFG
#else
#define POWERUP_GPIO_CFG
#endif //PACKET_TRACE
#endif //EMBER_SERIAL1_RTSCTS
#define POWERUP_GPIO_DIRH
#ifdef EMBER_SERIAL1_RTSCTS
#define POWERUP_GPIO_DIRL
#else
#define POWERUP_GPIO_DIRL
0x1010 // UART + I2C + PacketTrace
0x0010 // UART + I2C
0x1010 // UART + I2C + PacketTrace
0x0010 // UART + I2C
0
// GPIO16 = Input
(BOARDLED_MASK|GPIO(7)|GPIO(5)|GPIO(4)|GPIO(3)\
|BIT(SC1_nRTS)|BIT(SC1_TXD))//RTS, TXD are output
(BOARDLED_MASK|GPIO(7)|GPIO(5)|GPIO(4)|GPIO(3))
// LEDs & GPIO7,5,4,3 outputs
#endif
#define POWERUP_GPIO_CLRH
0
// No output state change
#define POWERUP_GPIO_CLRL
GPIO(4)
// GPIO4 low
#define POWERUP_GPIO_SETH
0
// No output state change
#ifdef EMBER_SERIAL1_RTSCTS
#define POWERUP_GPIO_SETL
(BOARDLED_MASK|GPIO(7)|GPIO(5) \
|BIT(SC1_nRTS)|BIT(SC1_TXD))//RTS, TXD are high
#else
#define POWERUP_GPIO_SETL
(BOARDLED_MASK|GPIO(7)|GPIO(5))
// LEDs off (high), GPIO7,5 high
#endif
#define POWERUP_GPIO_PUH
0
#ifdef EMBER_SERIAL1_RTSCTS
#define POWERUP_GPIO_PUL
#else
#define POWERUP_GPIO_PUL
// No pullup on GPIO16
(GPIO(BUTTON1)|GPIO(BUTTON0)|BIT(SC1_RXD))
(GPIO(BUTTON1)|GPIO(BUTTON0))
// Pullup Buttons
#endif
#define POWERUP_GPIO_PDH
0
#ifdef EMBER_SERIAL1_RTSCTS
#define POWERUP_GPIO_PDL
#else
#define POWERUP_GPIO_PDL
#endif
#define POWERDN_GPIO_DBG
#define POWERDN_GPIO_CFG
#define POWERDN_GPIO_DIRH
// No pulldown on GPIO16
(BIT(SC1_nCTS))
// PD only on GPIO11 (nCTS)
0x0000
// No pulldowns on GPIO15..0
POWERUP_GPIO_DBG
(POWERUP_GPIO_CFG & ~0x4F00)
// Disable analog I/O switches
POWERUP_GPIO_DIRH
#define POWERDN_GPIO_DIRL
POWERUP_GPIO_DIRL
#define POWERDN_GPIO_CLRH
0
// No output state change
#define POWERDN_GPIO_CLRL
0x0000
// No output state change
#define POWERDN_GPIO_SETH
0
// No output state change
#define POWERDN_GPIO_SETL
BOARDLED_MASK
// LEDs off (high)
#define POWERDN_GPIO_PUH
POWERUP_GPIO_PUH
#ifdef PACKET_TRACE
#define POWERDN_GPIO_PUL
EmberZNet 4.7.2 API EM250
(POWERUP_GPIO_PUL
|GPIO(0)
|GPIO(1)
|GPIO(5)
|GPIO(9)
|GPIO(10)
)
/*
/*
/*
/*
/*
SC1
SC1
PTI
SC2
SC2
120-3016-000-4720
MOSI
MISO
DATA
TXD
RXD
pull
pull
pull
pull
pull
up
up
up
up
up
*/
*/
*/
*/
*/
\
\
\
\
\
\
436
00438
00439
00440
00441
00442
00443
00444
00445
00446
00450
00451
00455
00456
00457
00458
00459
00460
00461
00462
00463
00464
00465
00466
00467
00469
00474
00475
00476
00477
00478
00479
00480
00481
00482
00483
00484
00485
00486
00487
00488
00489
00490
00491
00492
00493
00495
00496
00509
00510
00511
00512
00513
00514
00515
00516
00517
00518
00519
00520
00521
00522
00527
00528
00529
00530
00531
00532
00533
00534
00535
00536
00537
00538
00539
00540
00541
00542
00543
00544
00545
#else
#define POWERDN_GPIO_PUL
(POWERUP_GPIO_PUL
|GPIO(0)
|GPIO(1)
|GPIO(9)
|GPIO(10)
)
/*
/*
/*
/*
SC1
SC1
SC2
SC2
MOSI
MISO
TXD
RXD
pull
pull
pull
pull
up
up
up
up
*/
*/
*/
*/
\
\
\
\
\
#endif//PACKET_TRACE
#define POWERDN_GPIO_PDH
#ifdef PACKET_TRACE
#define POWERDN_GPIO_PDL
#else
#define POWERDN_GPIO_PDL
(POWERUP_GPIO_PDH|GPIO(16)) // TMR1 pull down
(POWERUP_GPIO_PDL
|GPIO(2)
|GPIO(4)
|GPIO(6)
)
\
/* SC1 MSCLK pull down */ \
/* PTI
EN pull down */ \
/* GPIO6
pull down */ \
(POWERUP_GPIO_PDL
|GPIO(2)
|GPIO(6)
)
\
/* SC1 MSCLK pull down */ \
/* GPIO6
pull down */ \
#endif//PACKET_TRACE
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
WAKE_ON_GPIO0
WAKE_ON_GPIO1
WAKE_ON_GPIO2
WAKE_ON_GPIO3
WAKE_ON_GPIO4
WAKE_ON_GPIO5
WAKE_ON_GPIO6
WAKE_ON_GPIO7
WAKE_ON_GPIO8
WAKE_ON_GPIO9
WAKE_ON_GPIO10
WAKE_ON_GPIO11
WAKE_ON_GPIO12
WAKE_ON_GPIO13
WAKE_ON_GPIO14
WAKE_ON_GPIO15
WAKE_ON_GPIO16
FALSE
FALSE
FALSE
FALSE
FALSE
FALSE
FALSE
FALSE
TRUE
FALSE
FALSE
FALSE
FALSE
FALSE
FALSE
TRUE
FALSE
//BUTTON0
//BUTTON1
#ifndef EZSP_UART
#define halInternalInitBoard()
do {
halInternalPowerUpBoard();
halInternalRestartUart();
halInternalInitButton();
} while(0)
#else
#define halInternalInitBoard()
do {
halInternalPowerUpBoard();
} while(0)
#endif
#define halInternalPowerDownBoard()
do {
/* GPIO Output configuration */
GPIO_CLRH = POWERDN_GPIO_CLRH; /*
GPIO_CLRL = POWERDN_GPIO_CLRL; /*
GPIO_SETH = POWERDN_GPIO_SETH; /*
GPIO_SETL = POWERDN_GPIO_SETL; /*
GPIO_DIRH = POWERDN_GPIO_DIRH; /*
GPIO_DIRL = POWERDN_GPIO_DIRL; /*
/* GPIO Mode Config (see above) */
GPIO_DBG
= POWERDN_GPIO_DBG;
GPIO_CFG
= POWERDN_GPIO_CFG;
/* GPIO Pullup/Pulldown Config */
GPIO_PDH
= POWERDN_GPIO_PDH;
GPIO_PDL
= POWERDN_GPIO_PDL;
GPIO_PUH
= POWERDN_GPIO_PUH;
GPIO_PUL
= POWERDN_GPIO_PUL;
} while(0)
EmberZNet 4.7.2 API EM250
\
\
\
\
\
\
\
\
output
output
output
output
output
output
states
states
states
states
enables
enables
120-3016-000-4720
*/
*/
*/
*/
*/
*/
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
437
00551 #define halInternalPowerUpBoard()
00552
do {
00553
/* GPIO Pullup/Pulldown Config */
00554
GPIO_PUH
= POWERUP_GPIO_PUH;
00555
GPIO_PUL
= POWERUP_GPIO_PUL;
00556
GPIO_PDH
= POWERUP_GPIO_PDH;
00557
GPIO_PDL
= POWERUP_GPIO_PDL;
00558
/* GPIO Mode Config (see above) */
00559
GPIO_DBG
= POWERUP_GPIO_DBG;
00560
GPIO_CFG
= POWERUP_GPIO_CFG;
00561
/* GPIO Output configuration */
00562
GPIO_CLRH = POWERUP_GPIO_CLRH; /*
00563
GPIO_CLRL = POWERUP_GPIO_CLRL; /*
00564
GPIO_SETH = POWERUP_GPIO_SETH; /*
00565
GPIO_SETL = POWERUP_GPIO_SETL; /*
00566
GPIO_DIRH = POWERUP_GPIO_DIRH; /*
00567
GPIO_DIRL = POWERUP_GPIO_DIRL; /*
00568
} while(0)
00569
00570
00571 #endif //__BOARD_H__
8.45
output
output
output
output
output
output
states
states
states
states
enables
enables
diagnostic.h File Reference
Functions
• void halStartPCDiagnostics (void)
• void halStopPCDiagnostics (void)
• int16u halGetPCDiagnostics (void)
8.45.1
Detailed Description
See Crash and Watchdog Diagnostics for detailed documentation.
Definition in file diagnostic.h.
8.46
00001
00028
00029
00030
00034
00035
00039
00040
00048
00049
00050
00051
00052
00053
00054
00055
00056
00057
00058
00059
00060
00061
00062
00063
00064
00065
00066
00067
diagnostic.h
#ifndef __DIAGNOSTIC_H__
#define __DIAGNOSTIC_H__
void halStartPCDiagnostics(void);
void halStopPCDiagnostics(void);
int16u halGetPCDiagnostics(void);
#ifdef ENABLE_DATA_LOGGING
// A pair of utility functions for logging trace data
XAP2B_PAGEZERO_ON
void halLogData(int8u v1, int8u v2, int8u v3, int8u v4);
XAP2B_PAGEZERO_OFF
void halPrintLogData(int8u port);
#endif
#ifdef ENABLE_ATOMIC_CLOCK
#if defined(XAP2B)
void halResetAtomicClock(void);
void halStartAtomicClock(int16u intState);
void halStopAtomicClock(int16u intState);
void halPrintAtomicTiming(int8u port, boolean reset);
#elif defined (AVR_ATMEGA)
void halResetAtomicClock(void);
void halStartAtomicClock(void);
void halStopAtomicClock(void);
EmberZNet 4.7.2 API EM250
120-3016-000-4720
*/
*/
*/
*/
*/
*/
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
438
00068
00069
00070
00071
00072
00073
void halPrintAtomicTiming(int8u port, boolean reset);
#endif
#endif
#endif //__DIAGNOSTIC_H__
8.47
diagnostic.h File Reference
EM250-Specific Diagnostic Supplement Definitions
•
•
•
•
•
int16u emResetCause
int8u ∗ emStackLwm
int8u emStackBase [ ]
int8u emStackTop [ ]
void halInternalInitPCDiagnostics (void)
8.47.1
Detailed Description
See Crash and Watchdog Diagnostics for detailed documentation.
Definition in file xap2b/em250/diagnostic.h.
8.48
xap2b/em250/diagnostic.h
00001
00016 #ifndef __EM250_DIAGNOSTIC_H__
00017 #define __EM250_DIAGNOSTIC_H__
00018
00019 extern int16u
emResetCause;
// In
cstartup.xap
00020 extern int8u *
emStackLwm;
// In
cstartup.xap
00021 extern int8u
emStackBase[];
// In
cstartup.xap
00022 extern int8u
emStackTop[];
// In
cstartup.xap
00023
00024 // Copy important nvCrashInfo fields before nvCrashInfo is reused by
00025 // interrupt processing.
00028 extern void
halInternalInitPCDiagnostics( void );
00029
00030
00031 #if
(defined(DEBUG) || defined(HALTEST))
00032
00034 // EM250 DEBUG enhancements
00035
00036 // Return pointer to last incarnation’s crashInfo data
00037 // This must be called during boot prior to enabling interrupts.
00038 // Caller could then make a copy of it if so desired and they
00039 // have RAM to spare.
00040 extern crashInfo_t *halInternalGetCrashInfo( void );
00041
00042 // Return Cstack pointer based on LWM (Low Water Mark)
00043 // or SPR (Stack Pointer Register)
00044 extern int8u *halInternalCstackPointer( boolean lwmOrSpr );
00045
00046 // Return bytes of Cstack used based on LWM (Low Water Mark)
00047 // or SPR (Stack Pointer Register)
00048 extern int16s halInternalCstackUsed( boolean lwmOrSpr );
00049
00050 // Print info about last crash or reboot
00051 // This must be called at boot after serial port has been
00052 // configured but before interrupts are enabled and before
00053 // calling halStartPCDiagnostics() (unless the app retained
EmberZNet 4.7.2 API EM250
120-3016-000-4720
439
00054
00055
00056
00057
00058
00059
00060
00061
00062
00063
00064
// a copy of the crashInfo by calling halInternalGetCrashInfo()
// and passes that copy as 2nd argument).
extern void
halInternalPrintCrashInfo( int8u port, crashInfo_t *ci );
#endif//(defined(DEBUG) || defined(HALTEST))
#ifdef
DEBUG
extern int8s halInternalSetWatchPoint( watchPoint_t *newWp );
extern void
halInternalClearWatchPoint( int8u index );
extern int16u halInternalDebugExceptionIsr( int16u flags, int16u
pcbContext );
00065
00066 #endif//DEBUG
00067
00068 #endif//__EM250_DIAGNOSTIC_H__
00069
8.49
eeprom.h File Reference
Macros
•
•
•
•
•
•
#define EEPROM_SIZE
#define EEPROM_TOTAL_SIZE
#define EEPROM_PAGE_SZ
#define EEPROM_IMAGE_END
#define EEPROM_TOTAL_PAGES
#define EEPROM_LAST_PAGE
8.49.1
Detailed Description
Ember generic EEPROM Interface. See Eeprom for documentation.
Definition in file eeprom.h.
8.50
00001
00046
00047
00048
00049
00050
00051
00052
00053
00054
00055
00056
00057
eeprom.h
// device size
#define EEPROM_SIZE
(128ul * 1024ul)
// 128 kBytes
// device parameters and control
#define EEPROM_TOTAL_SIZE (EEPROM_SIZE)
#define EEPROM_PAGE_SZ
(EEPROM_PAGE_SIZE)
// image settings
#define EEPROM_IMAGE_END (EEPROM_IMAGE_START + EEPROM_TOTAL_SIZE)
#define EEPROM_TOTAL_PAGES (EEPROM_TOTAL_SIZE / EEPROM_PAGE_SZ)
#define EEPROM_LAST_PAGE (EEPROM_TOTAL_PAGES - 1) // zero based range
8.51
ember-configuration-defaults.h File Reference
Macros
• #define EMBER_API_MAJOR_VERSION
• #define EMBER_API_MINOR_VERSION
EmberZNet 4.7.2 API EM250
120-3016-000-4720
440
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
#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
EmberZNet 4.7.2 API EM250
120-3016-000-4720
441
8.51.1
Detailed Description
User-configurable stack memory allocation defaults.
Note
Application developers should not modify any portion of this file. Doing so may cause mysterious
bugs. Allocations should be adjusted only by defining the appropriate macros in the application’s
CONFIGURATION_HEADER.
See Configuration for documentation.
Definition in file ember-configuration-defaults.h.
8.52
00001
00014
00015
00016
00017
00018
00019
00047
00048
00049
00050
00051
00052
00053
00054
00055
00058
00059
00060
00061
00062
00065
00066
00067
00080
00081
00082
00083
00084
00085
00086
00087
00088
00089
00090
00091
00092
00093
00094
00098
00099
00100
00101
00102
00103
00104
00105
00106
00107
00108
00109
00110
00111
00112
00113
ember-configuration-defaults.h
//
//
//
//
//
Todo:
- explain how to use a configuration header
- the documentation of the custom handlers should
go in hal/ember-configuration.c, not here
- the stack profile documentation is out of date
#ifndef __EMBER_CONFIGURATION_DEFAULTS_H__
#define __EMBER_CONFIGURATION_DEFAULTS_H__
#ifdef CONFIGURATION_HEADER
#include CONFIGURATION_HEADER
#endif
#ifndef EMBER_API_MAJOR_VERSION
#define EMBER_API_MAJOR_VERSION 2
#endif
#ifndef EMBER_API_MINOR_VERSION
#define EMBER_API_MINOR_VERSION 0
#endif
#ifndef EMBER_STACK_PROFILE
#define EMBER_STACK_PROFILE 0
#endif
#if (EMBER_STACK_PROFILE == 2)
#define EMBER_MAX_DEPTH
15
#define EMBER_SECURITY_LEVEL
5
#define EMBER_MIN_ROUTE_TABLE_SIZE
10
#define EMBER_MIN_DISCOVERY_TABLE_SIZE
4
#define EMBER_INDIRECT_TRANSMISSION_TIMEOUT 7680
#define EMBER_SEND_MULTICASTS_TO_SLEEPY_ADDRESS FALSE
#endif
#ifndef EMBER_MAX_END_DEVICE_CHILDREN
#define EMBER_MAX_END_DEVICE_CHILDREN 6
#endif
#ifndef DOXYGEN_SHOULD_SKIP_THIS
/* Need to put in a compile time check to make sure that we aren’t specifying
* too many child devices. The NCP may or may not support 64 end devices. But
* the host code doesn’t matter.
*/
#if defined(HAL_HAS_INT64) || defined(EZSP_HOST)
#if EMBER_MAX_END_DEVICE_CHILDREN > 64
#error "EMBER_MAX_END_DEVICE_CHILDREN can not exceed 64."
#endif
#else
#if EMBER_MAX_END_DEVICE_CHILDREN > 32
#error "EMBER_MAX_END_DEVICE_CHILDREN can not exceed 32."
#endif
EmberZNet 4.7.2 API EM250
120-3016-000-4720
442
00114
00115
00116
00117
00118
00119
00123
00124
00125
00126
00127
00128
00129
00130
00131
00132
00133
00134
00135
00136
00137
00138
00152
00153
00154
00168
00169
00170
00171
00181
00182
00183
00184
00185
00186
00187
00188
00194
00195
00196
00197
00198
00199
00200
00207
00208
00209
00210
00217
00218
00219
00220
00232
00233
00234
00235
00236
00243
00244
00245
00246
00247
#endif
#endif // DOXYGEN_SHOULD_SKIP_THIS
#ifndef EMBER_SECURITY_LEVEL
#define EMBER_SECURITY_LEVEL 5
#endif
#if ! (EMBER_SECURITY_LEVEL == 0
|| EMBER_SECURITY_LEVEL == 5)
#error "Unsupported security level"
#endif
\
#ifdef EMBER_CHILD_TABLE_SIZE
#if (EMBER_MAX_END_DEVICE_CHILDREN < EMBER_CHILD_TABLE_SIZE)
#undef EMBER_CHILD_TABLE_SIZE
#endif
#endif
#ifndef EMBER_CHILD_TABLE_SIZE
#define EMBER_CHILD_TABLE_SIZE EMBER_MAX_END_DEVICE_CHILDREN
#endif
#ifndef EMBER_KEY_TABLE_SIZE
#define EMBER_KEY_TABLE_SIZE 0
#endif
#ifndef EMBER_CERTIFICATE_TABLE_SIZE
#define EMBER_CERTIFICATE_TABLE_SIZE 0
#else
#if EMBER_CERTIFICATE_TABLE_SIZE > 1
#error "EMBER_CERTIFICATE_TABLE_SIZE > 1 is not supported!"
#endif
#endif
#ifndef EMBER_MAX_DEPTH
#define EMBER_MAX_DEPTH
15
#elif (EMBER_MAX_DEPTH > 15)
// Depth is a 4-bit field
#error "EMBER_MAX_DEPTH cannot be greater than 15"
#endif
#ifndef EMBER_MAX_HOPS
#define EMBER_MAX_HOPS (2 * EMBER_MAX_DEPTH)
#endif
#ifndef EMBER_PACKET_BUFFER_COUNT
#define EMBER_PACKET_BUFFER_COUNT 24
#endif
#define EMBER_MAX_NEIGHBOR_TABLE_SIZE 16
#ifndef EMBER_NEIGHBOR_TABLE_SIZE
#define EMBER_NEIGHBOR_TABLE_SIZE 16
#endif
#ifndef EMBER_INDIRECT_TRANSMISSION_TIMEOUT
#define EMBER_INDIRECT_TRANSMISSION_TIMEOUT 3000
#endif
#define EMBER_MAX_INDIRECT_TRANSMISSION_TIMEOUT 30000
#if (EMBER_INDIRECT_TRANSMISSION_TIMEOUT
\
00248
> EMBER_MAX_INDIRECT_TRANSMISSION_TIMEOUT)
00249
#error "Indirect transmission timeout too large."
00250 #endif
00251
00258 #ifndef EMBER_SEND_MULTICASTS_TO_SLEEPY_ADDRESS
00259
#define EMBER_SEND_MULTICASTS_TO_SLEEPY_ADDRESS FALSE
00260 #endif
00261
00262
00277 #ifndef EMBER_END_DEVICE_POLL_TIMEOUT
00278
#define EMBER_END_DEVICE_POLL_TIMEOUT 5
00279 #endif
00280
00288 #ifndef EMBER_END_DEVICE_POLL_TIMEOUT_SHIFT
00289
#define EMBER_END_DEVICE_POLL_TIMEOUT_SHIFT 6
00290 #endif
00291
EmberZNet 4.7.2 API EM250
120-3016-000-4720
443
00298
00299
00300
00301
00314
00315
00316
00317
00320
00321
00322
00323
00328
00329
00330
00331
00338
00339
00340
00341
00348
00349
00350
00351
00352
00353
00354
00355
00356
00357
00358
00364
00365
00366
00367
00368
00369
00370
00371
00372
00373
00374
00380
00381
00382
00383
00390
00391
00392
00393
00405
00406
00407
00408
00409
00410
00411
00412
00413
00414
00415
00416
00417
00418
00419
00420
00430
00431
00432
00433
00434
00448
00449
00467
00468
00469
00470
00471
#ifndef EMBER_MOBILE_NODE_POLL_TIMEOUT
#define EMBER_MOBILE_NODE_POLL_TIMEOUT 20
#endif
#ifndef EMBER_APS_UNICAST_MESSAGE_COUNT
#define EMBER_APS_UNICAST_MESSAGE_COUNT 10
#endif
#ifndef EMBER_BINDING_TABLE_SIZE
#define EMBER_BINDING_TABLE_SIZE 0
#endif
#ifndef EMBER_ADDRESS_TABLE_SIZE
#define EMBER_ADDRESS_TABLE_SIZE 8
#endif
#ifndef EMBER_RESERVED_MOBILE_CHILD_ENTRIES
#define EMBER_RESERVED_MOBILE_CHILD_ENTRIES 0
#endif
#ifndef EMBER_ROUTE_TABLE_SIZE
#ifdef EMBER_MIN_ROUTE_TABLE_SIZE
#define EMBER_ROUTE_TABLE_SIZE EMBER_MIN_ROUTE_TABLE_SIZE
#else
#define EMBER_ROUTE_TABLE_SIZE 16
#endif
#elif defined(EMBER_MIN_ROUTE_TABLE_SIZE) \
&& EMBER_ROUTE_TABLE_SIZE < EMBER_MIN_ROUTE_TABLE_SIZE
#error "EMBER_ROUTE_TABLE_SIZE is less than required by stack profile."
#endif
#ifndef EMBER_DISCOVERY_TABLE_SIZE
#ifdef EMBER_MIN_DISCOVERY_TABLE_SIZE
#define EMBER_DISCOVERY_TABLE_SIZE EMBER_MIN_DISCOVERY_TABLE_SIZE
#else
#define EMBER_DISCOVERY_TABLE_SIZE 8
#endif
#elif defined(EMBER_MIN_DISCOVERY_TABLE_SIZE) \
&& EMBER_DISCOVERY_TABLE_SIZE < EMBER_MIN_DISCOVERY_TABLE_SIZE
#error "EMBER_DISCOVERY_TABLE_SIZE is less than required by stack profile."
#endif
#ifndef EMBER_MULTICAST_TABLE_SIZE
#define EMBER_MULTICAST_TABLE_SIZE 8
#endif
#ifndef EMBER_SOURCE_ROUTE_TABLE_SIZE
#define EMBER_SOURCE_ROUTE_TABLE_SIZE 32
#endif
#if !defined(EMBER_ZLL_STACK) && (EMBER_STACK_PROFILE == 2) &&
!defined(EMBER_TEST)
#if defined(EMBER_BROADCAST_TABLE_SIZE)
#error "Cannot override broadcast table size unless (EMBER_STACK_PROFILE !=
2) or EMBER_ZLL_STACK"
#endif
#endif
#define EMBER_DEFAULT_BROADCAST_TABLE_SIZE 15
#ifndef EMBER_BROADCAST_TABLE_SIZE
#define EMBER_BROADCAST_TABLE_SIZE EMBER_DEFAULT_BROADCAST_TABLE_SIZE
#elif EMBER_BROADCAST_TABLE_SIZE < EMBER_DEFAULT_BROADCAST_TABLE_SIZE
#error "EMBER_BROADCAST_TABLE_SIZE is less than the minimum value of 15."
#elif 254 < EMBER_BROADCAST_TABLE_SIZE
#error "EMBER_BROADCAST_TABLE_SIZE is larger than the maximum value of 254."
#endif
#if !defined(EMBER_ASSERT_OUTPUT_DISABLED) \
&& !defined(EMBER_ASSERT_SERIAL_PORT)
#define EMBER_ASSERT_SERIAL_PORT 1
#endif
#define EMBER_MAXIMUM_ALARM_DATA_SIZE 16
#ifndef EMBER_BROADCAST_ALARM_DATA_SIZE
#define EMBER_BROADCAST_ALARM_DATA_SIZE 0
#elif EMBER_MAXIMUM_ALARM_DATA_SIZE < EMBER_BROADCAST_ALARM_DATA_SIZE
#error "EMBER_BROADCAST_ALARM_DATA_SIZE is too large."
#endif
EmberZNet 4.7.2 API EM250
120-3016-000-4720
444
00472
00481
00482
00483
00484
00485
00486
00490
00491
00492
00493
00497
00498
00503
00504
00505
00506
00507
00508
00509
00510
00511
00512
00513
00514
00515
00516
00517
00518
00531
00532
00533
00534
00535
00536
00540
00541
00542
00543
00552
00553
00554
00555
00561
00562
00563
00564
00567
00568
00569
00570
00571
00572
00573
00574
00575
00576
00577
00578
00579
00581
00582
00583
00584
00585
00587
00588
00589
00590
00591
00592
00597
8.53
#ifndef EMBER_UNICAST_ALARM_DATA_SIZE
#define EMBER_UNICAST_ALARM_DATA_SIZE 0
#elif EMBER_MAXIMUM_ALARM_DATA_SIZE < EMBER_UNICAST_ALARM_DATA_SIZE
#error "EMBER_UNICAST_ALARM_DATA_SIZE is too large."
#endif
#ifndef EMBER_FRAGMENT_DELAY_MS
#define EMBER_FRAGMENT_DELAY_MS 0
#endif
#define EMBER_FRAGMENT_MAX_WINDOW_SIZE 8
#ifndef EMBER_FRAGMENT_WINDOW_SIZE
#define EMBER_FRAGMENT_WINDOW_SIZE 1
#elif EMBER_FRAGMENT_MAX_WINDOW_SIZE < EMBER_FRAGMENT_WINDOW_SIZE
#error "EMBER_FRAGMENT_WINDOW_SIZE is too large."
#endif
#ifndef EMBER_BINDING_TABLE_TOKEN_SIZE
#define EMBER_BINDING_TABLE_TOKEN_SIZE EMBER_BINDING_TABLE_SIZE
#endif
#ifndef EMBER_CHILD_TABLE_TOKEN_SIZE
#define EMBER_CHILD_TABLE_TOKEN_SIZE EMBER_CHILD_TABLE_SIZE
#endif
#ifndef EMBER_KEY_TABLE_TOKEN_SIZE
#define EMBER_KEY_TABLE_TOKEN_SIZE EMBER_KEY_TABLE_SIZE
#endif
#ifndef EMBER_REQUEST_KEY_TIMEOUT
#define EMBER_REQUEST_KEY_TIMEOUT 0
#elif EMBER_REQUEST_KEY_TIMEOUT > 10
#error "EMBER_REQUEST_KEY_TIMEOUT is too large."
#endif
#ifndef EMBER_END_DEVICE_BIND_TIMEOUT
#define EMBER_END_DEVICE_BIND_TIMEOUT 60
#endif
#ifndef EMBER_PAN_ID_CONFLICT_REPORT_THRESHOLD
#define EMBER_PAN_ID_CONFLICT_REPORT_THRESHOLD 1
#endif
#ifndef EMBER_TASK_COUNT
#define EMBER_TASK_COUNT (3)
#endif
#ifndef EMBER_SUPPORTED_NETWORKS
#ifdef EMBER_TEST
#define EMBER_SUPPORTED_NETWORKS 2
#else
#define EMBER_SUPPORTED_NETWORKS 1
#endif
#endif
#if defined(EMBER_ZLL_STACK)
#ifndef EMBER_ZLL_GROUP_ADDRESSES
#define EMBER_ZLL_GROUP_ADDRESSES 1
#endif
#ifndef EMBER_ZLL_RSSI_THRESHOLD
#define EMBER_ZLL_RSSI_THRESHOLD -128
#endif
#endif // EMBER_ZLL_STACK
#endif //__EMBER_CONFIGURATION_DEFAULTS_H__
ember-debug.h File Reference
EmberZNet 4.7.2 API EM250
120-3016-000-4720
445
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,...)
8.53.1
Detailed Description
See Debugging Utilities for documentation.
Definition in file ember-debug.h.
8.54
00001
00008
00009
00010
00019
00020
00021
00022
00023
00030
00031
00032
00033
00039
00040
00041
00049
ember-debug.h
#ifndef __EMBER_DEBUG_H__
#define __EMBER_DEBUG_H__
// Define the values for DEBUG_LEVEL
#define NO_DEBUG
0
#define BASIC_DEBUG 1
#define FULL_DEBUG 2
#define emberDebugInit(port) do {} while(FALSE)
#if (DEBUG_LEVEL >= BASIC_DEBUG) || defined(DOXYGEN_SHOULD_SKIP_THIS)
void emberDebugAssert(PGM_P filename, int linenumber);
void emberDebugMemoryDump(int8u *start, int8u *
end);
00050
00077 void emberDebugBinaryPrintf(PGM_P formatString, ...);
00078
00086 void emDebugSendVuartMessage(int8u *buff, int8u
len);
00087
00088 #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)
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)
00094
00095 #if (DEBUG_LEVEL == FULL_DEBUG) || defined(DOXYGEN_SHOULD_SKIP_THIS)
00096
00100 void emberDebugError(EmberStatus code);
00101
00106 boolean emberDebugReportOff(void);
00107
EmberZNet 4.7.2 API EM250
120-3016-000-4720
446
00113
00114
00115
00116
00132
00133
00134
00135
00136
00137
00138
00139
00140
00141
00142
00146
00147
8.55
void emberDebugReportRestore(boolean state);
// Format: Same as emberSerialPrintf
// emberDebugPrintf("format string"[, parameters ...])
void emberDebugPrintf(PGM_P formatString, ...);
#else // (DEBUG_LEVEL == FULL_DEBUG) || defined(DOXYGEN_SHOULD_SKIP_THIS)
#define emberDebugError(code) do {} while(FALSE)
// Note the following doesn’t have a do{}while(FALSE)
//
because it has a return value
#define emberDebugReportOff() (FALSE)
#define emberDebugReportRestore(state) do {} while(FALSE)
#define emberDebugPrintf(...) do {} while(FALSE)
#endif // (DEBUG_LEVEL == FULL_DEBUG) || defined(DOXYGEN_SHOULD_SKIP_THIS)
#endif // __EMBER_DEBUG_H__
ember-types.h File Reference
Data Structures
• struct EmberVersion
Version struct containing all version information.
• struct EmberZigbeeNetwork
Defines a ZigBee network and the associated parameters.
• struct EmberNetworkInitStruct
Defines the network initialization configuration that should be used when emberNetworkInitExtended() is
called by the application.
• struct EmberNetworkParameters
Holds network parameters.
• struct EmberApsFrame
An in-memory representation of a ZigBee APS frame of an incoming or outgoing message.
• struct EmberBindingTableEntry
Defines an entry in the binding table.
• struct EmberNeighborTableEntry
Defines an entry in the neighbor table.
• struct EmberRouteTableEntry
Defines an entry in the route table.
• struct EmberMulticastTableEntry
Defines an entry in the multicast table.
• struct EmberEventControl
Control structure for events.
• struct EmberTaskControl
Control structure for tasks.
• struct EmberKeyData
This data structure contains the key data that is passed into various other functions.
• struct EmberCertificateData
This data structure contains the certificate data that is used for Certificate Based Key Exchange (CBKE).
• struct EmberPublicKeyData
This data structure contains the public key data that is used for Certificate Based Key Exchange (CBKE).
• struct EmberPrivateKeyData
This data structure contains the private key data that is used for Certificate Based Key Exchange (CBKE).
EmberZNet 4.7.2 API EM250
120-3016-000-4720
447
• struct EmberSmacData
This data structure contains the Shared Message Authentication Code (SMAC) data that is used for Certificate Based Key Exchange (CBKE).
• struct EmberSignatureData
This data structure contains a DSA signature. It is the bit concatenation of the ’r’ and ’s’ components of the
signature.
• struct EmberMessageDigest
This data structure contains an AES-MMO Hash (the message digest).
• struct EmberAesMmoHashContext
This data structure contains the context data when calculating an AES MMO hash (message digest).
• struct EmberInitialSecurityState
This describes the Initial Security features and requirements that will be used when forming or joining the
network.
• struct EmberCurrentSecurityState
This describes the security features used by the stack for a joined device.
• struct EmberKeyStruct
This describes a one of several different types of keys and its associated data.
• struct EmberMfgSecurityStruct
This structure is used to get/set the security config that is stored in manufacturing tokens.
• struct EmberMacFilterMatchStruct
This structure indicates a matching raw MAC message has been received by the application configured
MAC 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
EmberZNet 4.7.2 API EM250
120-3016-000-4720
448
•
•
•
•
#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 ∗ control
void(∗ handler )(void)
} EmberEventData
• typedef int16u EmberMacFilterMatchData
• typedef int8u EmberLibraryStatus
Enumerations
• enum EmberNodeType {
EMBER_UNKNOWN_DEVICE, EMBER_COORDINATOR, EMBER_ROUTER, EMBER_END_DEVICE,
EMBER_SLEEPY_END_DEVICE, EMBER_MOBILE_END_DEVICE }
• enum EmberNetworkInitBitmask { EMBER_NETWORK_INIT_NO_OPTIONS, EMBER_NETWORK_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_ROUTE_DISCOVERY, EMBER_APS_OPTION_SOURCE_EUI64, EMBER_APS_OPTION_DESTINATION_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_INCOMING_MULTICAST, EMBER_INCOMING_MULTICAST_LOOPBACK,
EMBER_INCOMING_BROADCAST, EMBER_INCOMING_BROADCAST_LOOPBACK }
• enum EmberOutgoingMessageType {
EMBER_OUTGOING_DIRECT, EMBER_OUTGOING_VIA_ADDRESS_TABLE, EMBER_OUTGOING_VIA_BINDING, EMBER_OUTGOING_MULTICAST,
EMBER_OUTGOING_BROADCAST }
• enum EmberNetworkStatus {
EMBER_NO_NETWORK, EMBER_JOINING_NETWORK, EMBER_JOINED_NETWORK, EMBER_JOINED_NETWORK_NO_PARENT,
EMBER_LEAVING_NETWORK }
• enum EmberNetworkScanType { EMBER_ENERGY_SCAN, EMBER_ACTIVE_SCAN }
• enum EmberBindingType { EMBER_UNUSED_BINDING, EMBER_UNICAST_BINDING, EMBER_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 }
EmberZNet 4.7.2 API EM250
120-3016-000-4720
449
• enum EmberDeviceUpdate {
EMBER_STANDARD_SECURITY_SECURED_REJOIN, EMBER_STANDARD_SECURITY_UNSECURED_JOIN, EMBER_DEVICE_LEFT, EMBER_STANDARD_SECURITY_UNSECURED_REJOIN,
EMBER_HIGH_SECURITY_SECURED_REJOIN, EMBER_HIGH_SECURITY_UNSECURED_JOIN, EMBER_HIGH_SECURITY_UNSECURED_REJOIN, EMBER_REJOIN_REASON_NONE,
EMBER_REJOIN_DUE_TO_NWK_KEY_UPDATE, EMBER_REJOIN_DUE_TO_LEAVE_MESSAGE, EMBER_REJOIN_DUE_TO_NO_PARENT, EMBER_REJOIN_DUE_TO_ZLL_TOUCHLINK,
EMBER_REJOIN_DUE_TO_APP_EVENT_5, EMBER_REJOIN_DUE_TO_APP_EVENT_4, EMBER_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_UNSECURED_REJOIN,
EMBER_HIGH_SECURITY_SECURED_REJOIN, EMBER_HIGH_SECURITY_UNSECURED_JOIN, EMBER_HIGH_SECURITY_UNSECURED_REJOIN, EMBER_REJOIN_REASON_NONE,
EMBER_REJOIN_DUE_TO_NWK_KEY_UPDATE, EMBER_REJOIN_DUE_TO_LEAVE_MESSAGE, EMBER_REJOIN_DUE_TO_NO_PARENT, EMBER_REJOIN_DUE_TO_ZLL_TOUCHLINK,
EMBER_REJOIN_DUE_TO_APP_EVENT_5, EMBER_REJOIN_DUE_TO_APP_EVENT_4, EMBER_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, EMBER_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_BROADCAST, EMBER_COUNTER_MAC_RX_UNICAST, EMBER_COUNTER_MAC_TX_UNICAST_SUCCESS,
EMBER_COUNTER_MAC_TX_UNICAST_RETRY, EMBER_COUNTER_MAC_TX_UNICAST_FAILED, EMBER_COUNTER_APS_DATA_RX_BROADCAST, EMBER_COUNTER_APS_DATA_TX_BROADCAST,
EMBER_COUNTER_APS_DATA_RX_UNICAST, EMBER_COUNTER_APS_DATA_TX_UNICAST_SUCCESS, EMBER_COUNTER_APS_DATA_TX_UNICAST_RETRY, EMBER_COUNTER_APS_DATA_TX_UNICAST_FAILED,
EMBER_COUNTER_ROUTE_DISCOVERY_INITIATED, EMBER_COUNTER_NEIGHBOR_ADDED, EMBER_COUNTER_NEIGHBOR_REMOVED, EMBER_COUNTER_NEIGHBOR_STALE,
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_COUNTER_FAILURE, EMBER_COUNTER_APS_FRAME_COUNTER_FAILURE, EMBER_COUNTER_ASH_XOFF,
EMBER_COUNTER_APS_LINK_KEY_NOT_AUTHORIZED, EMBER_COUNTER_NWK_DEEmberZNet 4.7.2 API EM250
120-3016-000-4720
450
•
•
•
•
•
•
•
•
•
CRYPTION_FAILURE, EMBER_COUNTER_APS_DECRYPTION_FAILURE, EMBER_COUNTER_ALLOCATE_PACKET_BUFFER_FAILURE,
EMBER_COUNTER_RELAYED_UNICAST, EMBER_COUNTER_PHY_TO_MAC_QUEUE_LIMIT_REACHED, EMBER_COUNTER_PACKET_VALIDATE_LIBRARY_DROPPED_COUNT, EMBER_COUNTER_TYPE_COUNT }
enum EmberInitialSecurityBitmask {
EMBER_DISTRIBUTED_TRUST_CENTER_MODE, EMBER_TRUST_CENTER_GLOBAL_LINK_KEY, EMBER_PRECONFIGURED_NETWORK_KEY_MODE, EMBER_HAVE_TRUST_CENTER_EUI64,
EMBER_TRUST_CENTER_USES_HASHED_LINK_KEY, EMBER_HAVE_PRECONFIGURED_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_NWK_LEAVE_REQUEST_NOT_ALLOWED }
enum EmberCurrentSecurityBitmask {
EMBER_STANDARD_SECURITY_MODE_, EMBER_DISTRIBUTED_TRUST_CENTER_MODE_, 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_COUNTER, EMBER_KEY_HAS_INCOMING_FRAME_COUNTER, EMBER_KEY_HAS_PARTNER_EUI64,
EMBER_KEY_IS_AUTHORIZED, EMBER_KEY_PARTNER_IS_SLEEPY }
enum EmberKeyType {
EMBER_TRUST_CENTER_LINK_KEY, EMBER_TRUST_CENTER_MASTER_KEY, EMBER_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, EMBER_TRUST_CENTER_LINK_KEY_ESTABLISHED, EMBER_KEY_ESTABLISHMENT_TIMEOUT,
EMBER_KEY_TABLE_FULL, EMBER_TC_RESPONDED_TO_KEY_REQUEST, EMBER_TC_APP_KEY_SENT_TO_REQUESTER, EMBER_TC_RESPONSE_TO_KEY_REQUEST_FAILED,
EMBER_TC_REQUEST_KEY_TYPE_NOT_SUPPORTED, EMBER_TC_NO_LINK_KEY_FOR_REQUESTER, EMBER_TC_REQUESTER_EUI64_UNKNOWN, EMBER_TC_RECEIVED_FIRST_APP_KEY_REQUEST,
EMBER_TC_TIMEOUT_WAITING_FOR_SECOND_APP_KEY_REQUEST, EMBER_TC_NON_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_KEY_REQUESTS }
enum EmberKeySettings { EMBER_KEY_PERMISSIONS_NONE, EMBER_KEY_PERMISSIONS_READING_ALLOWED, EMBER_KEY_PERMISSIONS_HASHING_ALLOWED }
enum EmberMacPassthroughType {
EMBER_MAC_PASSTHROUGH_NONE, EMBER_MAC_PASSTHROUGH_SE_INTERPAN, EMBER_MAC_PASSTHROUGH_EMBERNET, EMBER_MAC_PASSTHROUGH_EMBERNET_SOURCE,
EMBER_MAC_PASSTHROUGH_APPLICATION, EMBER_MAC_PASSTHROUGH_CUSTOM
}
EmberZNet 4.7.2 API EM250
120-3016-000-4720
451
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_TYPE_GA }
enum EmberLeaveRequestFlags { EMBER_ZIGBEE_LEAVE_AND_REJOIN, EMBER_ZIGBEE_LEAVE_AND_REMOVE_CHILDREN }
enum EmberLeaveReason {
EMBER_LEAVE_REASON_NONE, EMBER_LEAVE_DUE_TO_NWK_LEAVE_MESSAGE, EMBER_LEAVE_DUE_TO_APS_REMOVE_MESSAGE, EMBER_LEAVE_DUE_TO_ZDO_LEAVE_MESSAGE,
EMBER_LEAVE_DUE_TO_ZLL_TOUCHLINK, EMBER_LEAVE_DUE_TO_APP_EVENT_1 }
typedef int8u EmberStatus
typedef int8u EmberEUI64 [EUI64_SIZE]
EmberZNet 4.7.2 API EM250
120-3016-000-4720
452
•
•
•
•
•
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. Broadcasts
are normally sent only to routers. Broadcasts can also be forwarded to end devices, either all of them or
only those that do not sleep. Broadcasting to end devices is both significantly more resource-intensive and
significantly 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
ZDO response status.
Most responses to ZDO commands contain a status byte. The meaning of this byte is defined by the ZigBee
Device Profile.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
453
• enum EmberZdoStatus {
EMBER_ZDP_SUCCESS, EMBER_ZDP_INVALID_REQUEST_TYPE, EMBER_ZDP_DEVICE_NOT_FOUND, EMBER_ZDP_INVALID_ENDPOINT,
EMBER_ZDP_NOT_ACTIVE, EMBER_ZDP_NOT_SUPPORTED, EMBER_ZDP_TIMEOUT, EMBER_ZDP_NO_MATCH,
EMBER_ZDP_NO_ENTRY, EMBER_ZDP_NO_DESCRIPTOR, EMBER_ZDP_INSUFFICIENT_SPACE, EMBER_ZDP_NOT_PERMITTED,
EMBER_ZDP_TABLE_FULL, EMBER_ZDP_NOT_AUTHORIZED, EMBER_NWK_ALREADY_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 the
messages.
Note that each message starts with a 1-byte transaction sequence number. This sequence number is used to
match a response command frame to the request frame that it is replying to. The application shall maintain
a 1-byte counter that is copied into this field and incremented by one for each command sent. When a value
of 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>
@code
Request: <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 Descriptor
Available: 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 incoming
transfer 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
EmberZNet 4.7.2 API EM250
120-3016-000-4720
454
Power Descriptor Request / Response
<br>
@code
Request: <transaction sequence number: 1> <node ID:2>
Response: <transaction sequence number: 1> <status:1> <node ID:2>
<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
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
EmberZNet 4.7.2 API EM250
120-3016-000-4720
455
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 request
services 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_BINDING_TABLE_CACHE,
EMBER_ZDP_PRIMARY_DISCOVERY_CACHE, EMBER_ZDP_SECONDARY_DISCOVERY_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 the
device of interest itself, respond. The requesting device can then direct any service discovery requests to
the 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
EmberZNet 4.7.2 API EM250
120-3016-000-4720
456
Binding types and Request / Response
Bind and unbind have the same formats. There are two possible formats, depending on whether the destination 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>
Response: <transaction sequence number: 1> <status: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
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
0x01
0x02
0x03
rx mode
0x0C
0x00 off when idle
0x04 on when idle
0x08 unknown
relationship
0x70
0x00
0x10
0x20
0x30
0x40
reserved
0x10
coordinator
router
end device
unknown
parent
child
sibling
other
previous child
The permit-joining byte has the following fields
Name
Mask
permit joining
0x03
reserved
0xFC
Values
0x00 not accepting join requests
0x01 accepting join requests
0x02 unknown
• #define LQI_TABLE_REQUEST
• #define LQI_TABLE_RESPONSE
EmberZNet 4.7.2 API EM250
120-3016-000-4720
457
Routing Table Request / Response
Request: <transaction sequence number: 1> <start index:1>
Response: <transaction sequence number: 1> <status:1>
<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
status
0x07
flags
0x38
Values
0x00
0x01
0x02
0x03
0x04
active
discovery underway
discovery failed
inactive
validation underway
0x08 memory constrained
0x10 many-to-one
0x20 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 be
included. If Dest. Address Mode = 0x01, then the Short Dest. Address will be used and there will be
no 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 children
0x80 rejoin
Response: <transaction sequence number: 1> <status:1>
•
•
•
•
#define LEAVE_REQUEST
#define LEAVE_RESPONSE
#define LEAVE_REQUEST_REMOVE_CHILDREN_FLAG
#define LEAVE_REQUEST_REJOIN_FLAG
EmberZNet 4.7.2 API EM250
120-3016-000-4720
458
Permit Joining Request / Response
Request:
<transaction sequence number: 1>
<duration:1> <permit authentication:1>
Response: <transaction sequence number: 1> <status: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 but
not ’manager’. Perform ’count’ scans of the given duration on the
given channels.
If duration is 0xFE, then ’channels’ should have a single channel
and ’count’ and ’manager’ are not present. Switch to the indicated
channel.
If duration is 0xFF, then ’count’ is not present. Set the active
channels and the network manager ID to the values given.
Unicast requests always get a response, which is INVALID_REQUEST if the
duration 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 the
following configuration definitions:
EmberZNet 4.7.2 API EM250
120-3016-000-4720
459
EMBER_APPLICATION_RECEIVES_SUPPORTED_ZDO_REQUESTS EMBER_APPLICATION_HANDLES_UNSUPPORTED_ZDO_REQUESTS EMBER_APPLICATION_HANDLES_ENDPOINT_ZDO_REQUESTS EMBER_APPLICATION_HANDLES_BINDING_ZDO_REQUESTS
See ember-configuration.h for more information.
• enum EmberZdoConfigurationFlags { EMBER_APP_RECEIVES_SUPPORTED_ZDO_REQUESTS, EMBER_APP_HANDLES_UNSUPPORTED_ZDO_REQUESTS, EMBER_APP_HANDLES_ZDO_ENDPOINT_REQUESTS, EMBER_APP_HANDLES_ZDO_BINDING_REQUESTS }
8.55.1
Detailed Description
Ember data type definitions. See Ember Common Data Types for details.
Definition in file ember-types.h.
8.55.2
Variable Documentation
8.55.2.1 EmberEventControl∗ control
The control structure for the event.
Definition at line 1167 of file ember-types.h.
8.55.2.2
void(∗ handler)(void)
The procedure to call when the event fires.
Definition at line 1169 of file ember-types.h.
8.56
00001
00020
00021
00022
00023
00024
ember-types.h
#ifndef EMBER_TYPES_H
#define EMBER_TYPES_H
#ifndef DOXYGEN_SHOULD_SKIP_THIS
#include "stack/config/ember-configuration-defaults.h
"
00025 #include "stack/include/ember-static-struct.h"
00026 #endif //DOXYGEN_SHOULD_SKIP_THIS
00027
00032
00036 #ifdef DOXYGEN_SHOULD_SKIP_THIS
00037 enum EmberVersionType
00038 #else
00039 typedef int8u EmberVersionType;
00040 enum
00041 #endif
00042 {
00043
EMBER_VERSION_TYPE_PRE_RELEASE = 0x00,
00044
// Anything other than 0xAA is considered pre-release
00045
// We may define other types in the future (e.g. beta, alpha)
00046
// We chose an arbitrary number (0xAA) to allow for expansion, but
00047
// to prevent ambiguity in case 0x00 or 0xFF is accidentally retrieved
00048
// as the version type.
00049
EMBER_VERSION_TYPE_GA = 0xAA,
00050 };
00051
00055 typedef struct {
00056
int16u build;
EmberZNet 4.7.2 API EM250
120-3016-000-4720
460
00057
00058
00059
00060
00061
00062
00063
00067
00068
00072
00073
00077
00078
00082
00083
00088
00089
00093
00094
00098
00099
00103
00104
00109
00110
00114
00115
00116
00120
00121
00122
00123
00124
00128
00129
00139
00140
00144
00145
00147
00148
00152
00153
00157
00158
00162
00163
00167
00168
00169
00173
00174
00178
00179
00184
00185
00190
00191
00201
00202
00209
00210
00218
00219
00227
00228
00233
00234
00238
00239
00243
00244
00248
00249
00253
00254
00258
00259
00260
00266
int8u major;
int8u minor;
int8u patch;
int8u special;
EmberVersionType type;
} EmberVersion;
extern const EmberVersion emberVersion;
#define EUI64_SIZE 8
#define EXTENDED_PAN_ID_SIZE 8
#define EMBER_ENCRYPTION_KEY_SIZE 16
#define EMBER_CERTIFICATE_SIZE 48
#define EMBER_PUBLIC_KEY_SIZE 22
#define EMBER_PRIVATE_KEY_SIZE 21
#define EMBER_SMAC_SIZE 16
#define EMBER_SIGNATURE_SIZE 42
#define EMBER_AES_HASH_BLOCK_SIZE 16
#ifndef __EMBERSTATUS_TYPE__
#define __EMBERSTATUS_TYPE__
typedef int8u EmberStatus;
#endif //__EMBERSTATUS_TYPE__
typedef int8u EmberEUI64[EUI64_SIZE];
typedef int8u EmberMessageBuffer;
typedef int16u EmberNodeId;
typedef int16u EmberMulticastId;
typedef int16u EmberPanId;
#define EMBER_MAX_802_15_4_CHANNEL_NUMBER 26
#define EMBER_MIN_802_15_4_CHANNEL_NUMBER 11
#define EMBER_NUM_802_15_4_CHANNELS \
(EMBER_MAX_802_15_4_CHANNEL_NUMBER - EMBER_MIN_802_15_4_CHANNEL_NUMBER + 1)
#define EMBER_ALL_802_15_4_CHANNELS_MASK 0x07FFF800UL
#define EMBER_ZIGBEE_COORDINATOR_ADDRESS 0x0000
#define EMBER_NULL_NODE_ID 0xFFFF
#define EMBER_NULL_BINDING 0xFF
#define EMBER_TABLE_ENTRY_UNUSED_NODE_ID
0xFFFF
#define EMBER_MULTICAST_NODE_ID
0xFFFE
#define EMBER_UNKNOWN_NODE_ID
0xFFFD
#define EMBER_DISCOVERY_ACTIVE_NODE_ID
0xFFFC
#define EMBER_NULL_ADDRESS_TABLE_INDEX 0xFF
#define EMBER_ZDO_ENDPOINT 0
#define EMBER_BROADCAST_ENDPOINT 0xFF
#define EMBER_ZDO_PROFILE_ID
0x0000
#define EMBER_WILDCARD_PROFILE_ID
0xFFFF
#define EMBER_MAXIMUM_STANDARD_PROFILE_ID
0x7FFF
#define EMBER_BROADCAST_TABLE_TIMEOUT_QS (20 * 4)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
461
00267
00268
00269
00270
00271
00272
00273
00274
00275
00277
00278
00280
#ifdef DOXYGEN_SHOULD_SKIP_THIS
enum EmberLeaveRequestFlags
#else
typedef int8u EmberLeaveRequestFlags;
enum
#endif
{
EMBER_ZIGBEE_LEAVE_AND_REJOIN
= 0x20,
EMBER_ZIGBEE_LEAVE_AND_REMOVE_CHILDREN
= 0x40,
00281 };
00282
00283 #ifdef DOXYGEN_SHOULD_SKIP_THIS
00284 enum EmberLeaveReason
00285 #else
00286 typedef int8u EmberLeaveReason;
00287 enum
00288 #endif
00289 {
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
optional
00294
EMBER_LEAVE_DUE_TO_ZDO_LEAVE_MESSAGE = 3
,
00295
EMBER_LEAVE_DUE_TO_ZLL_TOUCHLINK
= 4,
00296
00297
EMBER_LEAVE_DUE_TO_APP_EVENT_1
= 0xFF,
00298 };
00299
00301
00302
00315 #define EMBER_BROADCAST_ADDRESS 0xFFFC
00316
00317 #define EMBER_RX_ON_WHEN_IDLE_BROADCAST_ADDRESS 0xFFFD
00318
00319 #define EMBER_SLEEPY_BROADCAST_ADDRESS 0xFFFF
00320
00328 #ifdef DOXYGEN_SHOULD_SKIP_THIS
00329 enum EmberNodeType
00330 #else
00331 typedef int8u EmberNodeType;
00332 enum
00333 #endif
00334 {
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 = 5
00349 };
00350
00354 typedef struct {
00355
int16u panId;
00356
int8u channel;
00357
boolean allowingJoin;
00358
int8u extendedPanId[8];
00359
int8u stackProfile;
00360
int8u nwkUpdateId;
00361 } EmberZigbeeNetwork;
00362
00363
00368 #ifdef DOXYGEN_SHOULD_SKIP_THIS
00369 enum EmberNetworkInitBitmask
00370 #else
00371 typedef int16u EmberNetworkInitBitmask;
00372 enum
00373 #endif
00374 {
00375
EMBER_NETWORK_INIT_NO_OPTIONS
= 0x0000
,
00379
EMBER_NETWORK_INIT_PARENT_INFO_IN_TOKEN
= 0x0001,
EmberZNet 4.7.2 API EM250
120-3016-000-4720
462
00380
00381
00382
00387
00388
00389
00390
00391
00398
00399
00400
00401
00402
00403
00404
00406
00418
00421
00425
00431
00434
00436
00438
00441
00446
00451
00457
00458
00459
00460
00461
00465
00466
00467
00468
00469
00470
00471
00473
00475
00477
00479
00481
00483
00484
00485
00486
00490
00491
00492
00493
00494
00495
00496
00498
00500
00502
00505
00508
00509
00510
00511
00515
00516
00517
00518
00519
00520
00521
00523
00525
};
typedef struct {
EmberNetworkInitBitmask bitmask;
} EmberNetworkInitStruct;
#ifdef DOXYGEN_SHOULD_SKIP_THIS
enum EmberApsOption
#else
typedef int16u EmberApsOption;
enum
#endif
{
EMBER_APS_OPTION_NONE
EMBER_APS_OPTION_DSA_SIGN
EMBER_APS_OPTION_ENCRYPTION
,
EMBER_APS_OPTION_RETRY
EMBER_APS_OPTION_ENABLE_ROUTE_DISCOVERY
= 0x0100,
EMBER_APS_OPTION_FORCE_ROUTE_DISCOVERY
= 0x0200,
EMBER_APS_OPTION_SOURCE_EUI64
0x0400,
EMBER_APS_OPTION_DESTINATION_EUI64
0x0800,
EMBER_APS_OPTION_ENABLE_ADDRESS_DISCOVERY
= 0x1000,
EMBER_APS_OPTION_POLL_RESPONSE
0x2000,
EMBER_APS_OPTION_ZDO_RESPONSE_REQUIRED
= 0x4000,
EMBER_APS_OPTION_FRAGMENT
SIGNED_ENUM 0x8000
};
= 0x0000,
= 0x0010,
= 0x0020
= 0x0040,
=
=
=
=
#ifdef DOXYGEN_SHOULD_SKIP_THIS
enum EmberIncomingMessageType
#else
typedef int8u EmberIncomingMessageType;
enum
#endif
{
EMBER_INCOMING_UNICAST,
EMBER_INCOMING_UNICAST_REPLY,
EMBER_INCOMING_MULTICAST,
EMBER_INCOMING_MULTICAST_LOOPBACK,
EMBER_INCOMING_BROADCAST,
EMBER_INCOMING_BROADCAST_LOOPBACK
};
#ifdef DOXYGEN_SHOULD_SKIP_THIS
enum EmberOutgoingMessageType
#else
typedef int8u EmberOutgoingMessageType;
enum
#endif
{
EMBER_OUTGOING_DIRECT,
EMBER_OUTGOING_VIA_ADDRESS_TABLE,
EMBER_OUTGOING_VIA_BINDING,
EMBER_OUTGOING_MULTICAST,
EMBER_OUTGOING_BROADCAST
};
#ifdef DOXYGEN_SHOULD_SKIP_THIS
enum EmberNetworkStatus
#else
typedef int8u EmberNetworkStatus;
enum
#endif
{
EMBER_NO_NETWORK,
EMBER_JOINING_NETWORK,
EmberZNet 4.7.2 API EM250
120-3016-000-4720
463
00527
00530
00532
00533
00534
00535
00539
00540
00541
00542
00543
00544
00545
00547
00549
00550
00551
00552
00556
00557
00558
00559
00560
00561
00562
00564
00566
00570
00574
00575
00576
00577
00586
00587
00591
00592
00594
00595
00599
00600
00601
00602
00603
00604
00605
00607
00609
00611
00613
00614
00615
00619
00620
00621
00622
00623
00624
00625
00631
00632
00633
00634
00635
00636
00637
00638
00639
00640
00641
00642
00643
00644
00645
00646
00647
EMBER_JOINED_NETWORK,
EMBER_JOINED_NETWORK_NO_PARENT,
EMBER_LEAVING_NETWORK
};
#ifdef DOXYGEN_SHOULD_SKIP_THIS
enum EmberNetworkScanType
#else
typedef int8u EmberNetworkScanType;
enum
#endif
{
EMBER_ENERGY_SCAN,
EMBER_ACTIVE_SCAN
};
#ifdef DOXYGEN_SHOULD_SKIP_THIS
enum EmberBindingType
#else
typedef int8u EmberBindingType;
enum
#endif
{
EMBER_UNUSED_BINDING
=
EMBER_UNICAST_BINDING
=
EMBER_MANY_TO_ONE_BINDING
=
EMBER_MULTICAST_BINDING
=
};
0,
1,
2,
3,
#define EMBER_LOW_RAM_CONCENTRATOR 0xFFF8
#define EMBER_HIGH_RAM_CONCENTRATOR 0xFFF9
#ifdef DOXYGEN_SHOULD_SKIP_THIS
enum EmberJoinDecision
#else
typedef int8u EmberJoinDecision;
enum
#endif
{
EMBER_USE_PRECONFIGURED_KEY = 0,
EMBER_SEND_KEY_IN_THE_CLEAR,
EMBER_DENY_JOIN,
EMBER_NO_ACTION
};
#define EMBER_JOIN_DECISION_STRINGS
"use preconfigured key",
"send key in the clear",
"deny join",
"no action",
\
\
\
\
// These map to the actual values within the APS Command frame so they cannot
// be arbitrarily changed.
#ifdef DOXYGEN_SHOULD_SKIP_THIS
enum EmberDeviceUpdate
#else
typedef int8u EmberDeviceUpdate;
enum
#endif
{
EMBER_STANDARD_SECURITY_SECURED_REJOIN
= 0,
EMBER_STANDARD_SECURITY_UNSECURED_JOIN
= 1,
EMBER_DEVICE_LEFT
= 2,
EMBER_STANDARD_SECURITY_UNSECURED_REJOIN
= 3,
EMBER_HIGH_SECURITY_SECURED_REJOIN
=
4,
EMBER_HIGH_SECURITY_UNSECURED_JOIN
=
5,
/* 6 Reserved */
EMBER_HIGH_SECURITY_UNSECURED_REJOIN
EmberZNet 4.7.2 API EM250
120-3016-000-4720
464
00648
00649
00650
00654
00655
00656
00657
00658
00659
00660
00661
00662
00663
00667
00668
00669
00670
00671
00672
00673
00674
00675
00676
00677
00678
00679
00680
00681
00682
00683
00684
00685
00686
00687
00688
00689
00690
00691
00692
00693
00697
00698
00699
00700
00701
00702
00703
00705
00707
00708
00709
00710
00715
00716
00717
00718
00719
00720
00721
00723
00725
00728
00731
00733
00734
00735
00736
00740
00741
00742
00743
00744
00745
00746
00752
00753
00764
00765
00766
= 7,
/* 8 - 15 Reserved */
};
#define EMBER_DEVICE_UPDATE_STRINGS
"secured rejoin",
"UNsecured join",
"device left",
"UNsecured rejoin",
"high secured rejoin",
"high UNsecured join",
"RESERVED",
/* reserved status code, per the spec. */
"high UNsecured rejoin",
#ifdef DOXYGEN_SHOULD_SKIP_THIS
enum EmberDeviceUpdate
#else
typedef int8u EmberRejoinReason;
enum
#endif
{
EMBER_REJOIN_REASON_NONE
EMBER_REJOIN_DUE_TO_NWK_KEY_UPDATE
EMBER_REJOIN_DUE_TO_LEAVE_MESSAGE
EMBER_REJOIN_DUE_TO_NO_PARENT
EMBER_REJOIN_DUE_TO_ZLL_TOUCHLINK
=
=
=
=
=
0,
1,
2,
3,
4,
// App. Framework events
// 0xA0 - 0xE0
// Customer Defined Events
//
I numbered these backwards in case there is ever request
//
for more application events. We can expand them
//
without renumbering the previous ones.
EMBER_REJOIN_DUE_TO_APP_EVENT_5
= 0xFB,
EMBER_REJOIN_DUE_TO_APP_EVENT_4
= 0xFC,
EMBER_REJOIN_DUE_TO_APP_EVENT_3
= 0xFD,
EMBER_REJOIN_DUE_TO_APP_EVENT_2
= 0xFE,
EMBER_REJOIN_DUE_TO_APP_EVENT_1
= 0xFF,
};
#ifdef DOXYGEN_SHOULD_SKIP_THIS
enum EmberClusterListId
#else
typedef int8u EmberClusterListId;
enum
#endif
{
EMBER_INPUT_CLUSTER_LIST
EMBER_OUTPUT_CLUSTER_LIST
};
= 0,
= 1
#ifdef DOXYGEN_SHOULD_SKIP_THIS
enum EmberEventUnits
#else
typedef int8u EmberEventUnits;
enum
#endif
{
EMBER_EVENT_INACTIVE = 0,
EMBER_EVENT_MS_TIME,
EMBER_EVENT_QS_TIME,
EMBER_EVENT_MINUTE_TIME,
EMBER_EVENT_ZERO_DELAY
};
#ifdef DOXYGEN_SHOULD_SKIP_THIS
enum EmberJoinMethod
#else
typedef int8u EmberJoinMethod;
enum
#endif
{
EMBER_USE_MAC_ASSOCIATION
EMBER_USE_NWK_REJOIN
EmberZNet 4.7.2 API EM250
= 0,
= 1,
120-3016-000-4720
\
\
\
\
\
\
\
\
465
00767
00768
00769
00770
00771
00772
00773
00774
00775
00780
00781
00782
00783
00790
00792
00794
00796
00798
00803
00804
00809
00815
00821
00822
00823
00824
00825
00826
00827
00828
00829
/* For those networks where the "permit joining" flag is never turned
* on, they will need to use a NWK Rejoin. If those devices have been
* preconfigured with the NWK key (including sequence number) they can use
* a secured rejoin. This is only necessary for end devices since they need
* a parent. Routers can simply use the ::EMBER_USE_NWK_COMMISSIONING
* join method below.
*/
EMBER_USE_NWK_REJOIN_HAVE_NWK_KEY = 2,
EMBER_USE_NWK_COMMISSIONING
= 3,
};
typedef struct {
int8u
extendedPanId[8];
int16u panId;
int8s
radioTxPower;
int8u
radioChannel;
EmberJoinMethod joinMethod;
EmberNodeId nwkManagerId;
int8u nwkUpdateId;
int32u channels;
} EmberNetworkParameters;
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define emberInitializeNetworkParameters(parameters) \
(MEMSET(parameters, 0, sizeof(EmberNetworkParameters)))
#else
void emberInitializeNetworkParameters(
EmberNetworkParameters* parameters);
00830 #endif
00831
00835 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;
00851
00852
00859 typedef struct {
00861
EmberBindingType type;
00863
int8u local;
00871
int16u clusterId;
00873
int8u remote;
00878
EmberEUI64 identifier;
00880
int8u networkIndex;
00881 } EmberBindingTableEntry;
00882
00883
00889 typedef struct {
00891
int16u shortId;
00894
int8u averageLqi;
00897
int8u inCost;
00904
int8u outCost;
00910
int8u age;
00912
EmberEUI64 longId;
00913 } EmberNeighborTableEntry;
00914
00920 typedef struct {
00922
int16u destination;
00924
int16u nextHop;
00927
int8u status;
00930
int8u age;
00933
int8u concentratorType;
00938
int8u routeRecordState;
00939 } EmberRouteTableEntry;
00940
00948 typedef struct {
00950
EmberMulticastId multicastId;
00954
int8u endpoint;
00956
int8u networkIndex;
00957 } EmberMulticastTableEntry;
00958
00963 #ifdef DOXYGEN_SHOULD_SKIP_THIS
EmberZNet 4.7.2 API EM250
120-3016-000-4720
466
00964
00965
00966
00967
00968
00969
00971
00973
00975
00977
00983
00985
00986
00988
00990
00992
00994
01000
01002
01003
01006
01007
01009
01011
01013
01014
01016
01018
01019
01021
01023
01025
01026
01029
01030
01033
01034
01036
01037
01041
enum EmberCounterType
#else
typedef int8u EmberCounterType;
enum
#endif
{
EMBER_COUNTER_MAC_RX_BROADCAST = 0,
EMBER_COUNTER_MAC_TX_BROADCAST = 1,
EMBER_COUNTER_MAC_RX_UNICAST = 2,
EMBER_COUNTER_MAC_TX_UNICAST_SUCCESS = 3,
EMBER_COUNTER_MAC_TX_UNICAST_RETRY = 4,
EMBER_COUNTER_MAC_TX_UNICAST_FAILED = 5,
EMBER_COUNTER_APS_DATA_RX_BROADCAST = 6,
EMBER_COUNTER_APS_DATA_TX_BROADCAST = 7,
EMBER_COUNTER_APS_DATA_RX_UNICAST = 8,
EMBER_COUNTER_APS_DATA_TX_UNICAST_SUCCESS
= 9,
EMBER_COUNTER_APS_DATA_TX_UNICAST_RETRY
= 10,
EMBER_COUNTER_APS_DATA_TX_UNICAST_FAILED
= 11,
EMBER_COUNTER_ROUTE_DISCOVERY_INITIATED
= 12,
EMBER_COUNTER_NEIGHBOR_ADDED = 13,
EMBER_COUNTER_NEIGHBOR_REMOVED = 14,
EMBER_COUNTER_NEIGHBOR_STALE = 15,
EMBER_COUNTER_JOIN_INDICATION = 16,
EMBER_COUNTER_CHILD_REMOVED = 17,
EMBER_COUNTER_ASH_OVERFLOW_ERROR = 18,
EMBER_COUNTER_ASH_FRAMING_ERROR = 19,
EMBER_COUNTER_ASH_OVERRUN_ERROR = 20,
EMBER_COUNTER_NWK_FRAME_COUNTER_FAILURE
= 21,
EMBER_COUNTER_APS_FRAME_COUNTER_FAILURE
= 22,
EMBER_COUNTER_ASH_XOFF = 23,
EMBER_COUNTER_APS_LINK_KEY_NOT_AUTHORIZED
= 24,
01042
01045
EMBER_COUNTER_NWK_DECRYPTION_FAILURE = 25
,
01046
01049
EMBER_COUNTER_APS_DECRYPTION_FAILURE = 26
,
01050
01055
01056
01058
01059
01071
01072
01077
EMBER_COUNTER_ALLOCATE_PACKET_BUFFER_FAILURE
= 27,
EMBER_COUNTER_RELAYED_UNICAST = 28,
EMBER_COUNTER_PHY_TO_MAC_QUEUE_LIMIT_REACHED
= 29,
EMBER_COUNTER_PACKET_VALIDATE_LIBRARY_DROPPED_COUNT
= 30,
01078
01080
EMBER_COUNTER_TYPE_COUNT = 31
01081 };
01082
01086 #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",
EmberZNet 4.7.2 API EM250
\
\
\
\
\
\
\
\
\
\
\
\
120-3016-000-4720
467
01098
01099
01100
01101
01102
01103
01104
01105
01106
01107
01108
01109
01110
01111
01112
01113
01114
01115
01116
01117
01118
01119
01121
01122
01123
01124
01130
01132
01134
01138
01139
01140
01141
01148
01150
01154
01155
01156
01157
01165
01167
01169
01170
01171
01176
01177
01178
01179
01180
01181
01182
01183
01184
01189
01194
01195
01198
01199
01203
01204
01208
01209
01210
01211
01212
01213
01214
01215
01216
01217
01219
01224
01232
01233
01272
01273
01310
01311
01327
"APS Tx Ucast Fail",
"Route Disc Initiated",
"Neighbor Added",
"Neighbor Removed",
"Neighbor Stale",
"Join Indication",
"Child Moved",
"ASH Overflow",
"ASH Frame Error",
"ASH Overrun Error",
"NWK FC Failure",
"APS FC Failure",
"ASH XOff",
"APS Unauthorized Key",
"NWK Decrypt Failures",
"APS Decrypt Failures",
"Packet Buffer Allocate Failures",
"Relayed Ucast",
"Phy to MAC queue limit reached",
"Packet Validate drop count",
NULL
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
\
typedef int8u EmberTaskId;
#ifndef EZSP_HOST
typedef struct {
EmberEventUnits status;
EmberTaskId taskid;
int32u timeToExecute;
} EmberEventControl;
#else
// host applications use an older, basic form of the event system
typedef struct {
EmberEventUnits status;
int16u timeToExecute;
} EmberEventControl;
#endif
typedef PGM struct {
EmberEventControl *control;
void (*handler)(void);
} EmberEventData;
typedef struct {
// The time when the next event associated with this task will fire
int32u nextEventTime;
// The list of events associated with this task
EmberEventData *events;
// A flag that indicates the task has something to do other than events
boolean busy;
} EmberTaskControl;
#define EMBER_TX_POWER_MODE_DEFAULT
0x0000
#define EMBER_TX_POWER_MODE_BOOST
0x0001
#define EMBER_TX_POWER_MODE_ALTERNATE
0x0002
#define EMBER_TX_POWER_MODE_BOOST_AND_ALTERNATE (EMBER_TX_POWER_MODE_BOOST
\
|EMBER_TX_POWER_MODE_ALTERNATE)
#ifndef DOXYGEN_SHOULD_SKIP_THIS
// The application does not ever need to call emberSetTxPowerMode() with the
// txPowerMode parameter set to this value. This value is used internally by
// the stack to indicate that the default token configuration has not been
// overridden by a prior call to emberSetTxPowerMode().
#define EMBER_TX_POWER_MODE_USE_TOKEN
0x8000
#endif//DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_PRIVATE_PROFILE_ID
0xC00E
#define EMBER_BROADCAST_ALARM_CLUSTER
0x0000
#define EMBER_UNICAST_ALARM_CLUSTER
0x0001
#define EMBER_CACHED_UNICAST_ALARM_CLUSTER
0x0002
EmberZNet 4.7.2 API EM250
120-3016-000-4720
468
01328
01332
01333
01335
01336
01341
01342
01344
01345
01350
01351
01353
01354
01357
01359
01360
01361
01364
01365
01366
01367
01368
01371
01372
01373
01374
01377
01378
01379
01380
01383
01384
01385
01386
01390
01391
01392
01393
01396
01397
01398
01399
01403
01404
01405
01406
01407
01408
01414
01415
01419
01420
01421
01425
01426
01427
01428
01429
01430
01431
01434
#define EMBER_REPORT_COUNTERS_REQUEST 0x0003
#define EMBER_REPORT_COUNTERS_RESPONSE 0x8003
#define EMBER_REPORT_AND_CLEAR_COUNTERS_REQUEST 0x0004
#define EMBER_REPORT_AND_CLEAR_COUNTERS_RESPONSE 0x8004
#define EMBER_OTA_CERTIFICATE_UPGRADE_CLUSTER 0x0005
typedef struct {
int8u contents[EMBER_ENCRYPTION_KEY_SIZE];
} EmberKeyData;
typedef struct {
/* This is the certificate byte data. */
int8u contents[EMBER_CERTIFICATE_SIZE];
} EmberCertificateData;
typedef struct {
int8u contents[EMBER_PUBLIC_KEY_SIZE];
} EmberPublicKeyData;
typedef struct {
int8u contents[EMBER_PRIVATE_KEY_SIZE];
} EmberPrivateKeyData;
typedef struct {
int8u contents[EMBER_SMAC_SIZE];
} EmberSmacData;
typedef struct {
int8u contents[EMBER_SIGNATURE_SIZE];
} EmberSignatureData;
typedef struct {
int8u contents[EMBER_AES_HASH_BLOCK_SIZE];
} EmberMessageDigest;
typedef struct {
int8u result[EMBER_AES_HASH_BLOCK_SIZE];
int32u length;
} EmberAesMmoHashContext;
#define EMBER_STANDARD_SECURITY_MODE 0x0000
#define EMBER_TRUST_CENTER_NODE_ID 0x0000
#ifdef DOXYGEN_SHOULD_SKIP_THIS
enum EmberInitialSecurityBitmask
#else
typedef int16u EmberInitialSecurityBitmask;
enum
#endif
{
EMBER_DISTRIBUTED_TRUST_CENTER_MODE
= 0x0002,
01437
EMBER_TRUST_CENTER_GLOBAL_LINK_KEY
=
0x0004,
01440
EMBER_PRECONFIGURED_NETWORK_KEY_MODE
= 0x0008,
01441
01442 #if !defined DOXYGEN_SHOULD_SKIP_THIS
01443
// 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 #endif
01448
01458
EMBER_HAVE_TRUST_CENTER_EUI64
=
0x0040,
01459
01466
EMBER_TRUST_CENTER_USES_HASHED_LINK_KEY
= 0x0084,
01467
EmberZNet 4.7.2 API EM250
120-3016-000-4720
469
01471
01475
01480
01486
01494
01500
01501
01502
01503
01504
01505
01506
01507
01508
01509
01510
01511
01512
01513
01514
01518
01519
01520
01521
01522
01523
01524
01525
01526
01527
01528
01529
01530
01531
01532
01533
01536
01537
01538
01539
01542
01543
01544
01545
01549
01550
01551
01552
01553
01554
01555
01556
01559
01560
01563
01564
01565
01566
01567
01568
01569
01570
01571
01572
01573
01574
01577
01582
01591
01597
01604
01612
EMBER_HAVE_PRECONFIGURED_KEY
=
0x0100,
EMBER_HAVE_NETWORK_KEY
= 0x0200,
EMBER_GET_LINK_KEY_WHEN_JOINING
=
0x0400,
EMBER_REQUIRE_ENCRYPTED_KEY
= 0x0800
,
EMBER_NO_FRAME_COUNTER_RESET
=
0x1000,
EMBER_GET_PRECONFIGURED_KEY_FROM_INSTALL_CODE
= 0x2000,
#if !defined DOXYGEN_SHOULD_SKIP_THIS
// Internal data
EM_SAVED_IN_TOKEN
#define EM_SECURITY_INITIALIZED
= 0x4000,
0x00008000L
// This is only used internally. High security is not released or supported
// except for golden unit compliance.
#define EMBER_HIGH_SECURITY_MODE
0x0001
#else
/* All other bits are reserved and must be zero. */
#endif
};
#ifdef DOXYGEN_SHOULD_SKIP_THIS
enum EmberExtendedSecurityBitmask
#else
typedef int16u EmberExtendedSecurityBitmask;
enum
#endif
{
#ifndef DOXYGEN_SHOULD_SKIP_THIS
// If this bit is set, we set the ’key token data’ field in the Initial
// Security Bitmask to 0 (No Preconfig Key token), otherwise we leave the
// field as it is.
EMBER_PRECONFIG_KEY_NOT_VALID
= 0x0001,
#endif
// bits 1-3 are unused.
EMBER_JOINER_GLOBAL_LINK_KEY
= 0x0010,
// bit 5-7 reserved for future use (stored in TOKEN).
EMBER_NWK_LEAVE_REQUEST_NOT_ALLOWED =
0x0100,
#ifndef DOXYGEN_SHOULD_SKIP_THIS
EMBER_R18_STACK_BEHAVIOR
#endif
= 0x0200,
// bits 10-11 are reserved for future use (stored in RAM only).
// bits 12-15 are unused.
};
#define EMBER_NO_TRUST_CENTER_MODE
#define EMBER_GLOBAL_LINK_KEY
EMBER_DISTRIBUTED_TRUST_CENTER_MODE
EMBER_TRUST_CENTER_GLOBAL_LINK_KEY
#if !defined DOXYGEN_SHOULD_SKIP_THIS
#define NO_TRUST_CENTER_KEY_TOKEN
#define TRUST_CENTER_KEY_TOKEN_MASK
#define SECURITY_BIT_TOKEN_MASK
#define SECURITY_LOWER_BIT_MASK
#define SECURITY_UPPER_BIT_MASK
#endif
0x0000
0x0030
0x71FF
0x000000FF // ""
0x00FF0000L // ""
typedef struct {
int16u bitmask;
EmberKeyData preconfiguredKey;
EmberKeyData networkKey;
int8u networkKeySequenceNumber;
EmberEUI64 preconfiguredTrustCenterEui64
;
01613 } EmberInitialSecurityState;
EmberZNet 4.7.2 API EM250
120-3016-000-4720
470
01614
01615
01619
01620
01621
01622
01623
01624
01625
01626
01627
01628
01631
01634
01637
01638
01639
01640
01641
01642
#ifdef DOXYGEN_SHOULD_SKIP_THIS
enum EmberCurrentSecurityBitmask
#else
typedef int16u EmberCurrentSecurityBitmask;
enum
#endif
{
#if defined DOXYGEN_SHOULD_SKIP_THIS
// These options are the same for Initial and Current Security state
EMBER_STANDARD_SECURITY_MODE_
0x0000,
EMBER_DISTRIBUTED_TRUST_CENTER_MODE_
= 0x0002,
EMBER_TRUST_CENTER_GLOBAL_LINK_KEY_
= 0x0004,
#else
// Bit 3 reserved
#endif
=
EMBER_HAVE_TRUST_CENTER_LINK_KEY
0x0010,
=
01643
01645
01646
01647
01648
01649
01650
01651
01652
01653
01654
01657
01660
01664
01665
01666
01667
01671
01672
01673
01674
01675
01676
01677
01680
01684
01688
01692
01696
01701
01702
01703
01704
01706
01707
01708
01709
01710
01711
01712
01714
01716
01718
01720
01722
01724
01725
01726
01730
01734
01736
01738
01741
EMBER_TRUST_CENTER_USES_HASHED_LINK_KEY_
= 0x0084,
// Bits 1,5,6, 8-15 reserved
};
#if !defined DOXYGEN_SHOULD_SKIP_THIS
#define INITIAL_AND_CURRENT_BITMASK
#endif
0x00FF
typedef struct {
EmberCurrentSecurityBitmask bitmask;
EmberEUI64 trustCenterLongAddress;
} EmberCurrentSecurityState;
#ifdef DOXYGEN_SHOULD_SKIP_THIS
enum EmberKeyStructBitmask
#else
typedef int16u EmberKeyStructBitmask;
enum
#endif
{
EMBER_KEY_HAS_SEQUENCE_NUMBER
EMBER_KEY_HAS_OUTGOING_FRAME_COUNTER
0x0002,
EMBER_KEY_HAS_INCOMING_FRAME_COUNTER
0x0004,
EMBER_KEY_HAS_PARTNER_EUI64
EMBER_KEY_IS_AUTHORIZED
EMBER_KEY_PARTNER_IS_SLEEPY
= 0x0001,
=
=
= 0x0008,
= 0x0010,
= 0x0020,
};
#ifdef DOXYGEN_SHOULD_SKIP_THIS
enum EmberKeyType
#else
typedef int8u EmberKeyType;
enum
#endif
{
EMBER_TRUST_CENTER_LINK_KEY
EMBER_TRUST_CENTER_MASTER_KEY
EMBER_CURRENT_NETWORK_KEY
EMBER_NEXT_NETWORK_KEY
EMBER_APPLICATION_LINK_KEY
EMBER_APPLICATION_MASTER_KEY
};
=
=
=
=
=
=
1,
2,
3,
4,
5,
6,
typedef struct {
EmberKeyStructBitmask bitmask;
EmberKeyType type;
EmberKeyData key;
int32u outgoingFrameCounter;
EmberZNet 4.7.2 API EM250
120-3016-000-4720
471
01744
01747
01750
01751
01752
01753
01757
01758
01759
01760
01761
01762
01763
01764
01765
01766
int32u incomingFrameCounter;
int8u sequenceNumber;
EmberEUI64 partnerEUI64;
} EmberKeyStruct;
#ifdef DOXYGEN_SHOULD_SKIP_THIS
enum EmberKeyStatus
#else
typedef int8u EmberKeyStatus;
enum
#endif
{
EMBER_APP_LINK_KEY_ESTABLISHED
= 1,
EMBER_APP_MASTER_KEY_ESTABLISHED
= 2,
EMBER_TRUST_CENTER_LINK_KEY_ESTABLISHED
= 3,
01767
EMBER_KEY_ESTABLISHMENT_TIMEOUT
= 4,
01768
EMBER_KEY_TABLE_FULL
= 5,
01769
01770
// These are success status values applying only to the
01771
// Trust Center answering key requests
01772
EMBER_TC_RESPONDED_TO_KEY_REQUEST
= 6
,
01773
EMBER_TC_APP_KEY_SENT_TO_REQUESTER
=
7,
01774
01775
// These are failure status values applying only to the
01776
// Trust Center answering key requests
01777
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 };
01788
01792 #ifdef DOXYGEN_SHOULD_SKIP_THIS
01793 enum EmberLinkKeyRequestPolicy
01794 #else
01795 typedef int8u EmberLinkKeyRequestPolicy;
01796 enum
01797 #endif
01798 {
01799
EMBER_DENY_KEY_REQUESTS = 0x00,
01800
EMBER_ALLOW_KEY_REQUESTS = 0x01,
01801 };
01802
01803
01811 #if defined DOXYGEN_SHOULD_SKIP_THIS
01812 int8u* emberKeyContents(EmberKeyData* key);
01813 #else
01814 #define emberKeyContents(key) ((key)->contents)
01815 #endif
01816
01824 #if defined DOXYGEN_SHOULD_SKIP_THIS
01825 int8u* emberCertificateContents(
EmberCertificateData* cert);
01826 #else
01827 #define emberCertificateContents(cert) ((cert)->contents)
01828 #endif
01829
01837 #if defined DOXYGEN_SHOULD_SKIP_THIS
01838 int8u* emberPublicKeyContents(EmberPublicKeyData
* key);
01839 #else
EmberZNet 4.7.2 API EM250
120-3016-000-4720
472
01840
01841
01842
01850
01851
#define emberPublicKeyContents(key) ((key)->contents)
#endif
#if defined DOXYGEN_SHOULD_SKIP_THIS
int8u* emberPrivateKeyContents(EmberPrivateKeyData
* key);
01852 #else
01853 #define emberPrivateKeyContents(key) ((key)->contents)
01854 #endif
01855
01860 #if defined DOXYGEN_SHOULD_SKIP_THIS
01861 int8u* emberSmacContents(EmberSmacData* key)
;
01862 #else
01863 #define emberSmacContents(key) ((key)->contents)
01864 #endif
01865
01869 #if defined DOXYGEN_SHOULD_SKIP_THIS
01870 int8u* emberSignatureContents(EmberSignatureData
* sig);
01871 #else
01872 #define emberSignatureContents(sig) ((sig)->contents)
01873 #endif
01874
01875
01876 #ifdef DOXYGEN_SHOULD_SKIP_THIS
01877 enum EmberKeySettings
01878 #else
01879 typedef int16u EmberKeySettings;
01880 enum
01881 #endif
01882 {
01883
EMBER_KEY_PERMISSIONS_NONE
= 0x0000,
01884
EMBER_KEY_PERMISSIONS_READING_ALLOWED =
0x0001,
01885
EMBER_KEY_PERMISSIONS_HASHING_ALLOWED =
0x0002,
01886 };
01887
01888
01892 typedef struct {
01893
EmberKeySettings keySettings;
01894 } EmberMfgSecurityStruct;
01895
01896
01901 #define EMBER_MFG_SECURITY_CONFIG_MAGIC_NUMBER 0xCABAD11FUL
01902
01903
01908 #ifdef DOXYGEN_SHOULD_SKIP_THIS
01909 enum EmberMacPassthroughType
01910 #else
01911 typedef int8u EmberMacPassthroughType;
01912 enum
01913 #endif
01914 {
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,
01924
EMBER_MAC_PASSTHROUGH_APPLICATION
=
0x08,
01926
EMBER_MAC_PASSTHROUGH_CUSTOM
= 0x10,
01927
01928 #if !defined DOXYGEN_SHOULD_SKIP_THIS
01929
01930
EM_MAC_PASSTHROUGH_INTERNAL
= 0x80
01931 #endif
01932 };
01933
01938 typedef int16u EmberMacFilterMatchData;
01939
01940 #define EMBER_MAC_FILTER_MATCH_ENABLED_MASK
0x0001
01941 #define EMBER_MAC_FILTER_MATCH_ON_PAN_DEST_MASK
0x0003
01942 #define EMBER_MAC_FILTER_MATCH_ON_PAN_SOURCE_MASK
0x000C
01943 #define EMBER_MAC_FILTER_MATCH_ON_DEST_MASK
0x0030
01944 #define EMBER_MAC_FILTER_MATCH_ON_SOURCE_MASK
0x0080
01945
01946 // Globally turn on/off this filter
EmberZNet 4.7.2 API EM250
120-3016-000-4720
473
01947
01948
01949
01950
01951
01952
01953
01954
01955
01956
01957
01958
01959
01960
01961
01962
01963
01964
01965
01966
01967
01968
01969
#define EMBER_MAC_FILTER_MATCH_ENABLED
#define EMBER_MAC_FILTER_MATCH_DISABLED
0x0000
0x0001
// Pick
#define
#define
#define
0x0000
0x0001
0x0002
either one of these
EMBER_MAC_FILTER_MATCH_ON_PAN_DEST_NONE
EMBER_MAC_FILTER_MATCH_ON_PAN_DEST_LOCAL
EMBER_MAC_FILTER_MATCH_ON_PAN_DEST_BROADCAST
// and one of these
#define EMBER_MAC_FILTER_MATCH_ON_PAN_SOURCE_NONE
0x0000
#define EMBER_MAC_FILTER_MATCH_ON_PAN_SOURCE_NON_LOCAL 0x0004
#define EMBER_MAC_FILTER_MATCH_ON_PAN_SOURCE_LOCAL
0x0008
// and one of these
#define EMBER_MAC_FILTER_MATCH_ON_DEST_BROADCAST_SHORT 0x0000
#define EMBER_MAC_FILTER_MATCH_ON_DEST_UNICAST_SHORT
0x0010
#define EMBER_MAC_FILTER_MATCH_ON_DEST_UNICAST_LONG
0x0020
// and one of these
#define EMBER_MAC_FILTER_MATCH_ON_SOURCE_LONG
#define EMBER_MAC_FILTER_MATCH_ON_SOURCE_SHORT
0x0000
0x0080
// Last entry should set this and nothing else. No other bits will be
examined.
01970 #define EMBER_MAC_FILTER_MATCH_END
0x8000
01971
01975 typedef struct {
01976
int8u filterIndexMatch;
01977
EmberMacPassthroughType legacyPassthroughType
;
01978
EmberMessageBuffer message;
01979 } EmberMacFilterMatchStruct;
01980
01981
01985 typedef int8u EmberLibraryStatus;
01986
01991
01997 #ifdef DOXYGEN_SHOULD_SKIP_THIS
01998 enum EmberZdoStatus
01999 #else
02000 typedef int8u EmberZdoStatus;
02001 enum
02002 #endif
02003 {
02004
// These values are taken from Table 48 of ZDP Errata 043238r003 and Table 2
02005
// of NWK 02130r10.
02006
EMBER_ZDP_SUCCESS
= 0x00,
02007
// 0x01 to 0x7F are reserved
02008
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,
02021
EMBER_ZDP_NOT_AUTHORIZED
= 0x8d,
02022
02023
EMBER_NWK_ALREADY_PRESENT
= 0xC5,
02024
EMBER_NWK_TABLE_FULL
= 0xC7,
02025
EMBER_NWK_UNKNOWN_DEVICE
= 0xC8
02026 };
02027
02040
02041
02042
02043
02044
02045
02046
02047
02048
02049
02050
02051
EmberZNet 4.7.2 API EM250
120-3016-000-4720
474
02052
02053
02054
02055
02056
02057
02058
02059
02066
02067
02068
02069
02070
02071
02072
02073
02074
02075
02076
02077
02078
02079
02080
02081
02082
02083
02085
02086
02087
02088
02097
02099
02100
02101
02102
02116
02117
02118
02119
02128
02129
02130
02131
02143
02144
02145
02146
02156
02157
02158
02159
02168
02169
02170
02171
02183
02184
02185
02186
02191
02192
02193
02194
02195
02196
02197
02198
02199
02200
02201
02202
02203
02204
02205
#define
#define
#define
#define
NETWORK_ADDRESS_REQUEST
NETWORK_ADDRESS_RESPONSE
IEEE_ADDRESS_REQUEST
IEEE_ADDRESS_RESPONSE
0x0000
0x8000
0x0001
0x8001
//
<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 Descriptor Available:
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 incoming transfer 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
0x0002
#define NODE_DESCRIPTOR_RESPONSE
0x8002
//
See ZigBee document 053474, Section 2.3.2.4 for more details.
#define POWER_DESCRIPTOR_REQUEST
0x0003
#define POWER_DESCRIPTOR_RESPONSE
0x8003
#define SIMPLE_DESCRIPTOR_REQUEST
#define SIMPLE_DESCRIPTOR_RESPONSE
0x0004
0x8004
#define ACTIVE_ENDPOINTS_REQUEST
#define ACTIVE_ENDPOINTS_RESPONSE
0x0005
0x8005
#define MATCH_DESCRIPTORS_REQUEST
#define MATCH_DESCRIPTORS_RESPONSE
0x0006
0x8006
#define DISCOVERY_CACHE_REQUEST
#define DISCOVERY_CACHE_RESPONSE
0x0012
0x8012
#define END_DEVICE_ANNOUNCE
0x0013
#define END_DEVICE_ANNOUNCE_RESPONSE 0x8013
#define SYSTEM_SERVER_DISCOVERY_REQUEST 0x0015
#define SYSTEM_SERVER_DISCOVERY_RESPONSE 0x8015
#ifdef DOXYGEN_SHOULD_SKIP_THIS
enum EmberZdoServerMask
#else
typedef int16u EmberZdoServerMask;
enum
#endif
{
EMBER_ZDP_PRIMARY_TRUST_CENTER
0x0001,
EMBER_ZDP_SECONDARY_TRUST_CENTER
0x0002,
EMBER_ZDP_PRIMARY_BINDING_TABLE_CACHE
= 0x0004,
EMBER_ZDP_SECONDARY_BINDING_TABLE_CACHE
= 0x0008,
EMBER_ZDP_PRIMARY_DISCOVERY_CACHE
0x0010,
EMBER_ZDP_SECONDARY_DISCOVERY_CACHE
0x0020,
EMBER_ZDP_NETWORK_MANAGER
// Bits 0x0080 to 0x8000 are reserved.
EmberZNet 4.7.2 API EM250
=
=
=
=
= 0x0040,
120-3016-000-4720
475
02206
02207
02221
02222
02223
02224
02235
02236
02237
02238
02256
02257
02258
02259
02260
02261
02262
02263
02264
02265
02313
02314
02315
02316
02349
02350
02351
02352
02371
02372
02373
02374
02385
02386
02387
02388
02389
02390
02391
02400
02401
02402
02403
02429
02430
02431
02432
02436
02437
02438
02439
02440
02441
02442
02443
02444
02445
02446
02447
02448
02449
02450
02451
02452
02465
02466
02467
02468
02469
02470
02471
02472
02473
02474
02475
02476
};
#define FIND_NODE_CACHE_REQUEST
#define FIND_NODE_CACHE_RESPONSE
#define END_DEVICE_BIND_REQUEST
#define END_DEVICE_BIND_RESPONSE
0x001C
0x801C
0x0020
0x8020
#define UNICAST_BINDING
0x03
#define UNICAST_MANY_TO_ONE_BINDING 0x83
#define MULTICAST_BINDING
0x01
#define
#define
#define
#define
BIND_REQUEST
BIND_RESPONSE
UNBIND_REQUEST
UNBIND_RESPONSE
0x0021
0x8021
0x0022
0x8022
#define LQI_TABLE_REQUEST
#define LQI_TABLE_RESPONSE
0x0031
0x8031
#define ROUTING_TABLE_REQUEST
#define ROUTING_TABLE_RESPONSE
0x0032
0x8032
#define BINDING_TABLE_REQUEST
#define BINDING_TABLE_RESPONSE
0x0033
0x8033
#define LEAVE_REQUEST
#define LEAVE_RESPONSE
0x0034
0x8034
#define LEAVE_REQUEST_REMOVE_CHILDREN_FLAG 0x40
#define LEAVE_REQUEST_REJOIN_FLAG
0x80
#define PERMIT_JOINING_REQUEST
#define PERMIT_JOINING_RESPONSE
0x0036
0x8036
#define NWK_UPDATE_REQUEST
#define NWK_UPDATE_RESPONSE
0x0038
0x8038
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
COMPLEX_DESCRIPTOR_REQUEST
COMPLEX_DESCRIPTOR_RESPONSE
USER_DESCRIPTOR_REQUEST
USER_DESCRIPTOR_RESPONSE
DISCOVERY_REGISTER_REQUEST
DISCOVERY_REGISTER_RESPONSE
USER_DESCRIPTOR_SET
USER_DESCRIPTOR_CONFIRM
NETWORK_DISCOVERY_REQUEST
NETWORK_DISCOVERY_RESPONSE
DIRECT_JOIN_REQUEST
DIRECT_JOIN_RESPONSE
0x0010
0x8010
0x0011
0x8011
0x0012
0x8012
0x0014
0x8014
0x0030
0x8030
0x0035
0x8035
#define CLUSTER_ID_RESPONSE_MINIMUM
0x8000
#ifdef DOXYGEN_SHOULD_SKIP_THIS
enum EmberZdoConfigurationFlags
#else
typedef int8u EmberZdoConfigurationFlags;
enum
#endif
{
EMBER_APP_RECEIVES_SUPPORTED_ZDO_REQUESTS
= 0x01,
EMBER_APP_HANDLES_UNSUPPORTED_ZDO_REQUESTS
= 0x02,
EMBER_APP_HANDLES_ZDO_ENDPOINT_REQUESTS
= 0x04,
EMBER_APP_HANDLES_ZDO_BINDING_REQUESTS
= 0x08
EmberZNet 4.7.2 API EM250
120-3016-000-4720
476
02477 };
02478
02480
02481 #endif // EMBER_TYPES_H
02482
8.57
ember.h File Reference
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
"ember-types.h"
"stack-info.h"
"network-formation.h"
"packet-buffer.h"
"message.h"
"raw-message.h"
"child.h"
"security.h"
"aes-mmo.h"
"binding-table.h"
"bootload.h"
"error.h"
"zigbee-device-stack.h"
"event.h"
"ember-debug.h"
"library.h"
"multi-network.h"
PHY Information
Bit masks for TOKEN_MFG_RADIO_BANDS_SUPPORTED.
• #define RADIO_BANDS_SUPPORTED_2400
8.57.1
Detailed Description
The master include file for the EmberZNet API. See EmberZNet Stack API Reference for documentation.
Definition in file ember.h.
8.57.2
Macro Definition Documentation
8.57.2.1
#define RADIO BANDS SUPPORTED 2400
2.4GHz band
Definition at line 69 of file ember.h.
8.58
ember.h
00001
00021 #ifndef __EMBER_H__
EmberZNet 4.7.2 API EM250
120-3016-000-4720
477
00022
00023
00024
00025
00026
00027
00028
00029
00030
00031
00032
00033
00034
00035
00036
00037
00038
00039
00040
00041
00042
00043
00044
00045
00046
00047
00048
00049
00050
00051
00052
00053
00054
00055
00056
00057
00062
00063
00064
00065
00066
00067
00069
00070
00071
00072
00073
00074
00076
00077
00078
00081
00083
00084
00085
00086
00087
00088
00089
00090
00091
00092
00093
00094
00095
00096
8.59
#define __EMBER_H__
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
"ember-types.h"
"stack-info.h"
"network-formation.h"
"packet-buffer.h"
"message.h"
"raw-message.h"
"child.h"
"security.h"
"aes-mmo.h"
"binding-table.h"
"bootload.h"
"error.h"
"zigbee-device-stack.h"
"event.h"
"ember-debug.h"
"library.h"
"multi-network.h"
#if defined(EMBER_ZLL_STACK)
#ifndef EMBER_SCRIPTED_TEST
#define EMBER_PARAMETERIZED_BROADCAST_TABLE
#endif
#include "zll-types.h"
#include "zll-api.h"
#endif
// We strip the multi-network code for flash saving purposes on the EM2xx and
// EM351 platforms.
#ifndef EMBER_MULTI_NETWORK_STRIPPED
#if defined(XAP2B) || defined(CORTEXM3_EM351)
#define EMBER_MULTI_NETWORK_STRIPPED
#endif // defined(XAP2B) || defined(CORTEXM3_EM351)
#endif // EMBER_MULTI_NETWORK_STRIPPED
#ifndef DOXYGEN_SHOULD_SKIP_THIS
#define RADIO_BANDS_SUPPORTED_868
#define RADIO_BANDS_SUPPORTED_915
#define RADIO_BANDS_SUPPORTED_433
#endif // DOXYGEN_SHOULD_SKIP_THIS
BIT(0)
BIT(1)
BIT(2)
#define RADIO_BANDS_SUPPORTED_2400
BIT(3)
#ifndef DOXYGEN_SHOULD_SKIP_THIS
#define RADIO_BANDS_SUPPORTED_408
#endif // DOXYGEN_SHOULD_SKIP_THIS
BIT(4)
#ifndef DOXYGEN_SHOULD_SKIP_THIS
#include "config/config.h"
#ifdef DEBUG_ASSERT
extern boolean enableFailure;
extern int8u rateOfFailure;
extern int8u failuresInARow;
static int8u bufferFailure;
boolean generateFailure(void);
void dumpFailure(void);
#endif
#endif //DOXYGEN_SHOULD_SKIP_THIS
#endif // __EMBER_H__
error-def.h File Reference
Generic Messages
These messages are system wide.
• #define EMBER_SUCCESS(x00)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
478
•
•
•
•
•
•
#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)
#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)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
479
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)
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)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
480
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)
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)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
481
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)
8.59.1
Detailed Description
Return-code definitions for EmberZNet stack API functions. See Status Codes for documentation.
Definition in file error-def.h.
8.60
00001
00038
00039
00040
00043
00044
00045
00046
00047
00048
00049
00050
00053
00054
00055
00056
00057
00058
00059
00060
00063
00064
00065
00066
00067
00068
00069
00070
00074
00075
00076
00077
error-def.h
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_SUCCESS(0x00)
#else
DEFINE_ERROR(SUCCESS, 0)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_ERR_FATAL(0x01)
#else
DEFINE_ERROR(ERR_FATAL, 0x01)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_BAD_ARGUMENT(0x02)
#else
DEFINE_ERROR(BAD_ARGUMENT, 0x02)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_EEPROM_MFG_STACK_VERSION_MISMATCH(0x04)
#else
DEFINE_ERROR(EEPROM_MFG_STACK_VERSION_MISMATCH, 0x04)
#endif //DOXYGEN_SHOULD_SKIP_THIS
EmberZNet 4.7.2 API EM250
120-3016-000-4720
482
00078
00079
00080
00081
00085
00086
00087
00088
00089
00090
00091
00092
00096
00097
00098
00099
00100
00101
00102
00103
00107
00108
00109
00110
00111
00113
00114
00119
00120
00121
00124
00125
00126
00127
00128
00130
00135
00136
00137
00140
00141
00142
00143
00144
00145
00146
00147
00150
00151
00152
00153
00154
00155
00156
00157
00160
00161
00162
00163
00164
00165
00166
00167
00171
00172
00173
00174
00175
00176
00177
00178
00181
00182
00183
00184
00185
00186
00187
00188
00191
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_INCOMPATIBLE_STATIC_MEMORY_DEFINITIONS(0x05)
#else
DEFINE_ERROR(INCOMPATIBLE_STATIC_MEMORY_DEFINITIONS, 0x05)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_EEPROM_MFG_VERSION_MISMATCH(0x06)
#else
DEFINE_ERROR(EEPROM_MFG_VERSION_MISMATCH, 0x06)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_EEPROM_STACK_VERSION_MISMATCH(0x07)
#else
DEFINE_ERROR(EEPROM_STACK_VERSION_MISMATCH, 0x07)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_NO_BUFFERS(0x18)
#else
DEFINE_ERROR(NO_BUFFERS, 0x18)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_SERIAL_INVALID_BAUD_RATE(0x20)
#else
DEFINE_ERROR(SERIAL_INVALID_BAUD_RATE, 0x20)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_SERIAL_INVALID_PORT(0x21)
#else
DEFINE_ERROR(SERIAL_INVALID_PORT, 0x21)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_SERIAL_TX_OVERFLOW(0x22)
#else
DEFINE_ERROR(SERIAL_TX_OVERFLOW, 0x22)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_SERIAL_RX_OVERFLOW(0x23)
#else
DEFINE_ERROR(SERIAL_RX_OVERFLOW, 0x23)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_SERIAL_RX_FRAME_ERROR(0x24)
#else
DEFINE_ERROR(SERIAL_RX_FRAME_ERROR, 0x24)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_SERIAL_RX_PARITY_ERROR(0x25)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
483
00192
00193
00194
00195
00196
00197
00198
00201
00202
00203
00204
00205
00206
00207
00208
00212
00213
00214
00215
00216
00218
00223
00224
00225
00228
00229
00230
00231
00232
00233
00234
00235
00236
00239
00240
00241
00242
00243
00244
00245
00248
00249
00250
00251
00252
00253
00254
00255
00256
00259
00260
00261
00262
00263
00264
00265
00266
00269
00270
00271
00272
00273
00274
00275
00276
00279
00280
00281
00282
00283
00284
00285
00286
00290
00291
00292
00293
00294
00295
00296
#else
DEFINE_ERROR(SERIAL_RX_PARITY_ERROR, 0x25)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_SERIAL_RX_EMPTY(0x26)
#else
DEFINE_ERROR(SERIAL_RX_EMPTY, 0x26)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_SERIAL_RX_OVERRUN_ERROR(0x27)
#else
DEFINE_ERROR(SERIAL_RX_OVERRUN_ERROR, 0x27)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_MAC_TRANSMIT_QUEUE_FULL(0x39)
#else
// Internal
DEFINE_ERROR(MAC_TRANSMIT_QUEUE_FULL, 0x39)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_MAC_UNKNOWN_HEADER_TYPE(0x3A)
#else
DEFINE_ERROR(MAC_UNKNOWN_HEADER_TYPE, 0x3A)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_MAC_ACK_HEADER_TYPE(0x3B)
#else
DEFINE_ERROR(MAC_ACK_HEADER_TYPE, 0x3B)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_MAC_SCANNING(0x3D)
#else
DEFINE_ERROR(MAC_SCANNING, 0x3D)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_MAC_NO_DATA(0x31)
#else
DEFINE_ERROR(MAC_NO_DATA, 0x31)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_MAC_JOINED_NETWORK(0x32)
#else
DEFINE_ERROR(MAC_JOINED_NETWORK, 0x32)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_MAC_BAD_SCAN_DURATION(0x33)
#else
DEFINE_ERROR(MAC_BAD_SCAN_DURATION, 0x33)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
EmberZNet 4.7.2 API EM250
120-3016-000-4720
484
00297
00300
00301
00302
00303
00304
00305
00306
00307
00310
00311
00312
00313
00314
00315
00316
00317
00321
00322
00323
00324
00325
00326
00327
00328
00332
00333
00334
00335
00336
00337
00338
00339
00343
00344
00345
00346
00347
00348
00349
00350
00353
00354
00355
00356
00357
00359
00360
00365
00366
00367
00368
00376
00377
00378
00379
00380
00381
00382
00383
00392
00393
00394
00395
00396
00397
00398
00399
00407
00408
00409
00410
00411
00412
00413
00414
00415
00416
00417
00418
#define EMBER_MAC_INCORRECT_SCAN_TYPE(0x34)
#else
DEFINE_ERROR(MAC_INCORRECT_SCAN_TYPE, 0x34)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_MAC_INVALID_CHANNEL_MASK(0x35)
#else
DEFINE_ERROR(MAC_INVALID_CHANNEL_MASK, 0x35)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_MAC_COMMAND_TRANSMIT_FAILURE(0x36)
#else
DEFINE_ERROR(MAC_COMMAND_TRANSMIT_FAILURE, 0x36)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_MAC_NO_ACK_RECEIVED(0x40)
#else
DEFINE_ERROR(MAC_NO_ACK_RECEIVED, 0x40)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_MAC_RADIO_NETWORK_SWITCH_FAILED(0x41)
#else
DEFINE_ERROR(MAC_RADIO_NETWORK_SWITCH_FAILED, 0x41)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_MAC_INDIRECT_TIMEOUT(0x42)
#else
DEFINE_ERROR(MAC_INDIRECT_TIMEOUT, 0x42)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_SIM_EEPROM_ERASE_PAGE_GREEN(0x43)
#else
DEFINE_ERROR(SIM_EEPROM_ERASE_PAGE_GREEN, 0x43)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_SIM_EEPROM_ERASE_PAGE_RED(0x44)
#else
DEFINE_ERROR(SIM_EEPROM_ERASE_PAGE_RED, 0x44)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_SIM_EEPROM_FULL(0x45)
#else
DEFINE_ERROR(SIM_EEPROM_FULL, 0x45)
#endif //DOXYGEN_SHOULD_SKIP_THIS
//
//
Errors 46 and 47 are now defined below in the
flash error block (was attempting to prevent renumbering)
#ifdef DOXYGEN_SHOULD_SKIP_THIS
EmberZNet 4.7.2 API EM250
120-3016-000-4720
485
00425
00426
00427
00428
00429
00430
00431
00432
00438
00439
00440
00441
00442
00443
00444
00445
00452
00453
00454
00455
00456
00457
00458
00459
00470
00471
00472
00473
00474
00476
00477
00482
00483
00484
00491
00492
00493
00494
00495
00496
00497
00498
00504
00505
00506
00507
00508
00509
00510
00511
00517
00518
00519
00520
00521
00522
00523
00524
00530
00531
00532
00533
00534
00536
00537
00542
00543
00544
00545
00549
00550
00551
00552
00553
00554
00555
00556
00560
00561
00562
#define EMBER_SIM_EEPROM_INIT_1_FAILED(0x48)
#else
DEFINE_ERROR(SIM_EEPROM_INIT_1_FAILED, 0x48)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_SIM_EEPROM_INIT_2_FAILED(0x49)
#else
DEFINE_ERROR(SIM_EEPROM_INIT_2_FAILED, 0x49)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_SIM_EEPROM_INIT_3_FAILED(0x4A)
#else
DEFINE_ERROR(SIM_EEPROM_INIT_3_FAILED, 0x4A)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_SIM_EEPROM_REPAIRING(0x4D)
#else
DEFINE_ERROR(SIM_EEPROM_REPAIRING, 0x4D)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_ERR_FLASH_WRITE_INHIBITED(0x46)
#else
DEFINE_ERROR(ERR_FLASH_WRITE_INHIBITED, 0x46)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_ERR_FLASH_VERIFY_FAILED(0x47)
#else
DEFINE_ERROR(ERR_FLASH_VERIFY_FAILED, 0x47)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_ERR_FLASH_PROG_FAIL(0x4B)
#else
DEFINE_ERROR(ERR_FLASH_PROG_FAIL, 0x4B)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_ERR_FLASH_ERASE_FAIL(0x4C)
#else
DEFINE_ERROR(ERR_FLASH_ERASE_FAIL, 0x4C)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_ERR_BOOTLOADER_TRAP_TABLE_BAD(0x58)
#else
DEFINE_ERROR(ERR_BOOTLOADER_TRAP_TABLE_BAD, 0x58)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_ERR_BOOTLOADER_TRAP_UNKNOWN(0x59)
#else
DEFINE_ERROR(ERR_BOOTLOADER_TRAP_UNKNOWN, 0x59)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
486
00563
00564
00565
00566
00567
00571
00572
00573
00574
00575
00577
00578
00583
00584
00585
00589
00590
00591
00592
00593
00594
00595
00596
00599
00600
00601
00602
00603
00604
00605
00606
00610
00611
00612
00613
00614
00615
00616
00617
00620
00621
00622
00623
00624
00625
00626
00627
00631
00632
00633
00634
00635
00636
00637
00638
00641
00642
00643
00644
00645
00646
00647
00648
00652
00653
00654
00655
00656
00657
00658
00662
00663
00664
00665
00666
00667
00668
00669
00673
00674
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_ERR_BOOTLOADER_NO_IMAGE(0x05A)
#else
DEFINE_ERROR(ERR_BOOTLOADER_NO_IMAGE, 0x5A)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_DELIVERY_FAILED(0x66)
#else
DEFINE_ERROR(DELIVERY_FAILED, 0x66)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_BINDING_INDEX_OUT_OF_RANGE(0x69)
#else
DEFINE_ERROR(BINDING_INDEX_OUT_OF_RANGE, 0x69)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_ADDRESS_TABLE_INDEX_OUT_OF_RANGE(0x6A)
#else
DEFINE_ERROR(ADDRESS_TABLE_INDEX_OUT_OF_RANGE, 0x6A)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_INVALID_BINDING_INDEX(0x6C)
#else
DEFINE_ERROR(INVALID_BINDING_INDEX, 0x6C)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_INVALID_CALL(0x70)
#else
DEFINE_ERROR(INVALID_CALL, 0x70)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_COST_NOT_KNOWN(0x71)
#else
DEFINE_ERROR(COST_NOT_KNOWN, 0x71)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_MAX_MESSAGE_LIMIT_REACHED(0x72)
#else
DEFINE_ERROR(MAX_MESSAGE_LIMIT_REACHED, 0x72)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_MESSAGE_TOO_LONG(0x74)
#else
DEFINE_ERROR(MESSAGE_TOO_LONG, 0x74)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_BINDING_IS_ACTIVE(0x75)
#else
EmberZNet 4.7.2 API EM250
120-3016-000-4720
487
00675
00676
00677
00678
00679
00683
00684
00685
00686
00687
00689
00694
00695
00696
00697
00700
00701
00702
00703
00704
00705
00706
00707
00711
00712
00713
00714
00715
00716
00717
00718
00722
00723
00724
00725
00726
00727
00728
00729
00732
00733
00734
00735
00736
00737
00738
00739
00743
00744
00745
00746
00747
00749
00754
00755
00756
00757
00760
00761
00762
00763
00764
00765
00766
00767
00770
00771
00772
00773
00774
00775
00776
00777
00780
00781
00782
00783
00784
00785
00786
DEFINE_ERROR(BINDING_IS_ACTIVE, 0x75)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_ADDRESS_TABLE_ENTRY_IS_ACTIVE(0x76)
#else
DEFINE_ERROR(ADDRESS_TABLE_ENTRY_IS_ACTIVE, 0x76)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_ADC_CONVERSION_DONE(0x80)
#else
DEFINE_ERROR(ADC_CONVERSION_DONE, 0x80)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_ADC_CONVERSION_BUSY(0x81)
#else
DEFINE_ERROR(ADC_CONVERSION_BUSY, 0x81)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_ADC_CONVERSION_DEFERRED(0x82)
#else
DEFINE_ERROR(ADC_CONVERSION_DEFERRED, 0x82)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_ADC_NO_CONVERSION_PENDING(0x84)
#else
DEFINE_ERROR(ADC_NO_CONVERSION_PENDING, 0x84)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_SLEEP_INTERRUPTED(0x85)
#else
DEFINE_ERROR(SLEEP_INTERRUPTED, 0x85)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_PHY_TX_UNDERFLOW(0x88)
#else
DEFINE_ERROR(PHY_TX_UNDERFLOW, 0x88)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_PHY_TX_INCOMPLETE(0x89)
#else
DEFINE_ERROR(PHY_TX_INCOMPLETE, 0x89)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_PHY_INVALID_CHANNEL(0x8A)
#else
DEFINE_ERROR(PHY_INVALID_CHANNEL, 0x8A)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
EmberZNet 4.7.2 API EM250
120-3016-000-4720
488
00787
00790
00791
00792
00793
00794
00795
00796
00797
00801
00802
00803
00804
00805
00806
00807
00808
00812
00813
00814
00815
00816
00817
00818
00819
00823
00824
00825
00826
00827
00828
00829
00830
00833
00834
00835
00836
00837
00839
00845
00846
00847
00848
00852
00853
00854
00855
00856
00857
00858
00859
00862
00863
00864
00865
00866
00867
00868
00869
00872
00873
00874
00875
00876
00877
00878
00879
00883
00884
00885
00886
00887
00888
00889
00890
00895
00896
00897
00898
00899
#define EMBER_PHY_INVALID_POWER(0x8B)
#else
DEFINE_ERROR(PHY_INVALID_POWER, 0x8B)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_PHY_TX_BUSY(0x8C)
#else
DEFINE_ERROR(PHY_TX_BUSY, 0x8C)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_PHY_TX_CCA_FAIL(0x8D)
#else
DEFINE_ERROR(PHY_TX_CCA_FAIL, 0x8D)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_PHY_OSCILLATOR_CHECK_FAILED(0x8E)
#else
DEFINE_ERROR(PHY_OSCILLATOR_CHECK_FAILED, 0x8E)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_PHY_ACK_RECEIVED(0x8F)
#else
DEFINE_ERROR(PHY_ACK_RECEIVED, 0x8F)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_NETWORK_UP(0x90)
#else
DEFINE_ERROR(NETWORK_UP, 0x90)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_NETWORK_DOWN(0x91)
#else
DEFINE_ERROR(NETWORK_DOWN, 0x91)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_JOIN_FAILED(0x94)
#else
DEFINE_ERROR(JOIN_FAILED, 0x94)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_MOVE_FAILED(0x96)
#else
DEFINE_ERROR(MOVE_FAILED, 0x96)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_CANNOT_JOIN_AS_ROUTER(0x98)
#else
DEFINE_ERROR(CANNOT_JOIN_AS_ROUTER, 0x98)
#endif //DOXYGEN_SHOULD_SKIP_THIS
EmberZNet 4.7.2 API EM250
120-3016-000-4720
489
00900
00901
00902
00905
00906
00907
00908
00909
00910
00911
00912
00915
00916
00917
00918
00919
00920
00921
00923
00924
00925
00926
00927
00928
00929
00932
00933
00934
00935
00936
00937
00938
00939
00943
00944
00945
00946
00947
00948
00949
00950
00953
00954
00955
00956
00957
00958
00959
00960
00963
00964
00965
00966
00967
00968
00969
00970
00974
00975
00976
00977
00978
00979
00981
00985
00986
00990
00991
00992
00993
00994
00995
00996
01000
01001
01002
01003
01004
01005
01006
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_NODE_ID_CHANGED(0x99)
#else
DEFINE_ERROR(NODE_ID_CHANGED, 0x99)
#endif
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_PAN_ID_CHANGED(0x9A)
#else
DEFINE_ERROR(PAN_ID_CHANGED, 0x9A)
#endif
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_CHANNEL_CHANGED(0x9B)
#else
DEFINE_ERROR(CHANNEL_CHANGED, 0x9B)
#endif
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_NO_BEACONS(0xAB)
#else
DEFINE_ERROR(NO_BEACONS, 0xAB)
#endif
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_RECEIVED_KEY_IN_THE_CLEAR(0xAC)
#else
DEFINE_ERROR(RECEIVED_KEY_IN_THE_CLEAR, 0xAC)
#endif
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_NO_NETWORK_KEY_RECEIVED(0xAD)
#else
DEFINE_ERROR(NO_NETWORK_KEY_RECEIVED, 0xAD)
#endif
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_NO_LINK_KEY_RECEIVED(0xAE)
#else
DEFINE_ERROR(NO_LINK_KEY_RECEIVED, 0xAE)
#endif
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_PRECONFIGURED_KEY_REQUIRED(0xAF)
#else
DEFINE_ERROR(PRECONFIGURED_KEY_REQUIRED, 0xAF)
#endif
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_KEY_INVALID(0xB2)
#else
DEFINE_ERROR(KEY_INVALID, 0xB2)
#endif // DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_INVALID_SECURITY_LEVEL(0x95)
#else
DEFINE_ERROR(INVALID_SECURITY_LEVEL, 0x95)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
EmberZNet 4.7.2 API EM250
120-3016-000-4720
490
01014
01015
01016
01017
01018
01019
01020
01023
01024
01025
01026
01027
01028
01029
01032
01033
01034
01035
01036
01037
01038
01045
01046
01047
01048
01049
01050
01051
01054
01055
01056
01057
01058
01059
01060
01065
01066
01067
01068
01069
01070
01071
01074
01075
01076
01077
01078
01079
01080
01086
01087
01088
01089
01090
01091
01092
01093
01096
01097
01098
01099
01100
01102
01103
01108
01109
01110
01111
01114
01115
01116
01117
01118
01119
01120
01124
01125
01126
01127
01128
#define EMBER_APS_ENCRYPTION_ERROR(0xA6)
#else
DEFINE_ERROR(APS_ENCRYPTION_ERROR, 0xA6)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_TRUST_CENTER_MASTER_KEY_NOT_SET(0xA7)
#else
DEFINE_ERROR(TRUST_CENTER_MASTER_KEY_NOT_SET, 0xA7)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_SECURITY_STATE_NOT_SET(0xA8)
#else
DEFINE_ERROR(SECURITY_STATE_NOT_SET, 0xA8)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_KEY_TABLE_INVALID_ADDRESS(0xB3)
#else
DEFINE_ERROR(KEY_TABLE_INVALID_ADDRESS, 0xB3)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_SECURITY_CONFIGURATION_INVALID(0xB7)
#else
DEFINE_ERROR(SECURITY_CONFIGURATION_INVALID, 0xB7)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_TOO_SOON_FOR_SWITCH_KEY(0xB8)
#else
DEFINE_ERROR(TOO_SOON_FOR_SWITCH_KEY, 0xB8)
#endif
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_SIGNATURE_VERIFY_FAILURE(0xB9)
#else
DEFINE_ERROR(SIGNATURE_VERIFY_FAILURE, 0xB9)
#endif
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_KEY_NOT_AUTHORIZED(0xBB)
#else
DEFINE_ERROR(KEY_NOT_AUTHORIZED, 0xBB)
#endif
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_SECURITY_DATA_INVALID(0xBD)
#else
DEFINE_ERROR(SECURITY_DATA_INVALID, 0xBD)
#endif
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_NOT_JOINED(0x93)
#else
DEFINE_ERROR(NOT_JOINED, 0x93)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_NETWORK_BUSY(0xA1)
#else
DEFINE_ERROR(NETWORK_BUSY, 0xA1)
#endif //DOXYGEN_SHOULD_SKIP_THIS
EmberZNet 4.7.2 API EM250
120-3016-000-4720
491
01129
01130
01131
01135
01136
01137
01138
01139
01140
01141
01142
01146
01147
01148
01149
01150
01151
01152
01156
01157
01158
01159
01160
01161
01162
01163
01166
01167
01168
01169
01170
01171
01172
01177
01178
01179
01180
01181
01182
01184
01189
01190
01191
01192
01198
01199
01200
01201
01202
01203
01204
01205
01209
01210
01211
01212
01213
01214
01215
01218
01219
01220
01221
01222
01223
01224
01228
01229
01230
01231
01232
01233
01234
01238
01239
01240
01241
01242
01243
01244
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_INVALID_ENDPOINT(0xA3)
#else
DEFINE_ERROR(INVALID_ENDPOINT, 0xA3)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_BINDING_HAS_CHANGED(0xA4)
#else
DEFINE_ERROR(BINDING_HAS_CHANGED, 0xA4)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_INSUFFICIENT_RANDOM_DATA(0xA5)
#else
DEFINE_ERROR(INSUFFICIENT_RANDOM_DATA, 0xA5)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_SOURCE_ROUTE_FAILURE(0xA9)
#else
DEFINE_ERROR(SOURCE_ROUTE_FAILURE, 0xA9)
#endif
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_MANY_TO_ONE_ROUTE_FAILURE(0xAA)
#else
DEFINE_ERROR(MANY_TO_ONE_ROUTE_FAILURE, 0xAA)
#endif
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_STACK_AND_HARDWARE_MISMATCH(0xB0)
#else
DEFINE_ERROR(STACK_AND_HARDWARE_MISMATCH, 0xB0)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_INDEX_OUT_OF_RANGE(0xB1)
#else
DEFINE_ERROR(INDEX_OUT_OF_RANGE, 0xB1)
#endif
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_TABLE_FULL(0xB4)
#else
DEFINE_ERROR(TABLE_FULL, 0xB4)
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_TABLE_ENTRY_ERASED(0xB6)
#else
DEFINE_ERROR(TABLE_ENTRY_ERASED, 0xB6)
#endif
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_LIBRARY_NOT_PRESENT(0xB5)
#else
DEFINE_ERROR(LIBRARY_NOT_PRESENT, 0xB5)
#endif
#ifdef DOXYGEN_SHOULD_SKIP_THIS
EmberZNet 4.7.2 API EM250
120-3016-000-4720
492
01248
01249
01250
01251
01252
01253
01254
01259
01260
01261
01262
01263
01265
01271
01272
01273
01277
01278
01279
01280
01281
01282
01283
01284
01285
01286
01287
01288
01289
01290
01291
01292
01293
01294
01295
01296
01297
01298
01299
01300
01301
01302
01303
01304
01305
01306
01307
01308
01309
01310
01311
01313
#define EMBER_OPERATION_IN_PROGRESS(0xBA)
#else
DEFINE_ERROR(OPERATION_IN_PROGRESS, 0xBA)
#endif
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_TRUST_CENTER_EUI_HAS_CHANGED(0xBC)
#else
DEFINE_ERROR(TRUST_CENTER_EUI_HAS_CHANGED, 0xBC)
#endif
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define EMBER_APPLICATION_ERROR_0(0xF0)
#define EMBER_APPLICATION_ERROR_1(0xF1)
#define EMBER_APPLICATION_ERROR_2(0xF2)
#define EMBER_APPLICATION_ERROR_3(0xF3)
#define EMBER_APPLICATION_ERROR_4(0xF4)
#define EMBER_APPLICATION_ERROR_5(0xF5)
#define EMBER_APPLICATION_ERROR_6(0xF6)
#define EMBER_APPLICATION_ERROR_7(0xF7)
#define EMBER_APPLICATION_ERROR_8(0xF8)
#define EMBER_APPLICATION_ERROR_9(0xF9)
#define EMBER_APPLICATION_ERROR_10(0xFA)
#define EMBER_APPLICATION_ERROR_11(0xFB)
#define EMBER_APPLICATION_ERROR_12(0xFC)
#define EMBER_APPLICATION_ERROR_13(0xFD)
#define EMBER_APPLICATION_ERROR_14(0xFE)
#define EMBER_APPLICATION_ERROR_15(0xFF)
#else
DEFINE_ERROR( APPLICATION_ERROR_0, 0xF0)
DEFINE_ERROR( APPLICATION_ERROR_1, 0xF1)
DEFINE_ERROR( APPLICATION_ERROR_2, 0xF2)
DEFINE_ERROR( APPLICATION_ERROR_3, 0xF3)
DEFINE_ERROR( APPLICATION_ERROR_4, 0xF4)
DEFINE_ERROR( APPLICATION_ERROR_5, 0xF5)
DEFINE_ERROR( APPLICATION_ERROR_6, 0xF6)
DEFINE_ERROR( APPLICATION_ERROR_7, 0xF7)
DEFINE_ERROR( APPLICATION_ERROR_8, 0xF8)
DEFINE_ERROR( APPLICATION_ERROR_9, 0xF9)
DEFINE_ERROR( APPLICATION_ERROR_10, 0xFA)
DEFINE_ERROR( APPLICATION_ERROR_11, 0xFB)
DEFINE_ERROR( APPLICATION_ERROR_12, 0xFC)
DEFINE_ERROR( APPLICATION_ERROR_13, 0xFD)
DEFINE_ERROR( APPLICATION_ERROR_14, 0xFE)
DEFINE_ERROR( APPLICATION_ERROR_15, 0xFF)
#endif //DOXYGEN_SHOULD_SKIP_THIS
8.61
error.h File Reference
Macros
• #define __EMBERSTATUS_TYPE__
• #define DEFINE_ERROR(symbol, value)
Typedefs
• typedef int8u EmberStatus
Enumerations
• enum { EMBER_ERROR_CODE_COUNT }
EmberZNet 4.7.2 API EM250
120-3016-000-4720
493
8.61.1
Detailed Description
Return codes for Ember API functions and module definitions. See Status Codes for documentation.
Definition in file error.h.
8.61.2
Macro Definition Documentation
8.61.2.1
#define EMBERSTATUS TYPE
Return type for Ember functions.
Definition at line 18 of file error.h.
8.61.3
Typedef Documentation
8.61.3.1
typedef int8u EmberStatus
Definition at line 19 of file error.h.
8.62
00001
00011
00012
00013
00017
00018
00019
00020
00021
00035
00036
00037
00038
00039
00040
00041
00042
00043
00046
00047
00048
00049
00050
00051
00052
00053
error.h
#ifndef __ERRORS_H__
#define __ERRORS_H__
#ifndef __EMBERSTATUS_TYPE__
#define __EMBERSTATUS_TYPE__
typedef int8u EmberStatus;
#endif //__EMBERSTATUS_TYPE__
#define DEFINE_ERROR(symbol, value) \
EMBER_ ## symbol = value,
enum {
#ifndef DOXYGEN_SHOULD_SKIP_THIS
#include "include/error-def.h"
#endif //DOXYGEN_SHOULD_SKIP_THIS
EMBER_ERROR_CODE_COUNT
};
#undef DEFINE_ERROR
#endif // __ERRORS_H__
8.63
event.h File Reference
Macros
•
•
•
•
•
#define __EVENT_H__
#define emberEventControlSetInactive(control)
#define emberEventControlGetActive(control)
#define emberEventControlSetActive(control)
#define emberEventControlSetDelayMS(control, delay)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
494
•
•
•
•
•
#define emberEventControlSetDelayQS(control, delay)
#define emberEventControlSetDelayMinutes(control, delay)
#define emberEventControlGetRemainingMS(control)
#define emberTaskEnableIdling(allow)
#define emberMarkTaskActive(taskid)
Functions
•
•
•
•
•
•
•
•
•
•
•
•
•
•
void emEventControlSetActive (EmberEventControl ∗event)
void emEventControlSetDelayMS (EmberEventControl ∗event, int16u delay)
void emEventControlSetDelayQS (EmberEventControl ∗event, int16u delay)
void emEventControlSetDelayMinutes (EmberEventControl ∗event, int16u delay)
int32u emEventControlGetRemainingMS (EmberEventControl ∗event)
void emberRunEvents (EmberEventData ∗events)
void emberRunTask (EmberTaskId taskid)
int32u emberMsToNextEvent (EmberEventData ∗events, int32u maxMs)
int32u emberMsToNextEventExtended (EmberEventData ∗events, int32u maxMs, int8u ∗returnIndex)
int32u emberMsToNextStackEvent (void)
EmberTaskId emberTaskInit (EmberEventData ∗events)
boolean emberMarkTaskIdle (EmberTaskId taskid)
void emTaskEnableIdling (boolean allow)
void emMarkTaskActive (EmberTaskId taskid)
8.63.1
Detailed Description
Scheduling events for future execution. See Event Scheduling for documentation.
Definition in file event.h.
8.64
00001
00009
00010
00011
00012
00013
00100
00101
00102
00103
00104
00105
00106
00107
00110
00111
00112
00115
00116
00117
00121
00122
00123
00127
event.h
#ifdef XAP2B
// The xap2b platform does not support processor idling
#define EMBER_NO_IDLE_SUPPORT
#endif
// Controlling events
// Possible event status values. Having zero as the ’inactive’ value
// causes events to initially be inactive.
//
#ifndef __EVENT_H__
#define __EVENT_H__
#define emberEventControlSetInactive(control)
\
do { (control).status = EMBER_EVENT_INACTIVE; } while(0)
#define emberEventControlGetActive(control)
((control).status != EMBER_EVENT_INACTIVE)
\
#define emberEventControlSetActive(control)
do { emEventControlSetActive(&(control)); } while(0)
\
void emEventControlSetActive(EmberEventControl
*event);
00128
00131 #define emberEventControlSetDelayMS(control, delay)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
\
495
00132
do { emEventControlSetDelayMS(&(control), (delay)); } while(0)
00133
00136 void emEventControlSetDelayMS(EmberEventControl
*event, int16u delay);
00137
00141 #define emberEventControlSetDelayQS(control, delay)
\
00142
do { emEventControlSetDelayQS(&(control), (delay)); } while(0)
00143
00147 void emEventControlSetDelayQS(EmberEventControl
*event, int16u delay);
00148
00152 #define emberEventControlSetDelayMinutes(control, delay)
\
00153
do { emEventControlSetDelayMinutes(&(control), (delay)); } while(0)
00154
00158 void emEventControlSetDelayMinutes(
EmberEventControl*event, int16u delay);
00159
00163 #define emberEventControlGetRemainingMS(control)
\
00164
(emEventControlGetRemainingMS(&(control)))
00165
00169 int32u emEventControlGetRemainingMS(
EmberEventControl *event);
00170
00171
00172 // Running events
00173
00180 void emberRunEvents(EmberEventData *events);
00181
00186 void emberRunTask(EmberTaskId taskid);
00187
00195 int32u emberMsToNextEvent(EmberEventData
*events, int32u maxMs);
00196
00202 int32u emberMsToNextEventExtended(
EmberEventData *events, int32u maxMs, int8u* returnIndex);
00203
00207 int32u emberMsToNextStackEvent(void);
00208
00209
00214 EmberTaskId emberTaskInit(EmberEventData
*events);
00215
00224 boolean emberMarkTaskIdle(EmberTaskId taskid);
00225
00226 #ifndef EMBER_NO_IDLE_SUPPORT
00227
00229
#define emberTaskEnableIdling(allow) \
00230
do { emTaskEnableIdling((allow)); } while(0)
00231
00232
void emTaskEnableIdling(boolean allow);
00233
00237
#define emberMarkTaskActive(taskid) \
00238
do { emMarkTaskActive((taskid)); } while(0)
00239
00240
void emMarkTaskActive(EmberTaskId taskid);
00241 #else
00242
#define emberTaskEnableIdling(allow) do {} while(0)
00243
#define emberMarkTaskActive(taskid)
do {} while(0)
00244 #endif // EMBER_NO_IDLE_SUPPORT
00245
00246 #endif // __EVENT_H__
00247
00248 // @} END addtogroup
00249
00250
8.65
flash.h File Reference
Functions
• void halInternalFlashInit (void)
• EmberStatus halInternalFlashVerifyInit (void)
• EmberStatus halInternalFlashPageErase (int8u pageSelect)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
496
• XAP2B_PAGEZERO_ON EmberStatus halInternalFlashBlockRead (int16u addr, int16u ∗data, int16u
length)
• XAP2B_PAGEZERO_OFF
XAP2B_PAGEZERO_ON EmberStatus halInternalFlashBlockWrite (int16u addr, int16u ∗data, int16s
length)
8.65.1
Detailed Description
Flash manipulation routines. See Flash Memory Control for documentation.
Definition in file flash.h.
8.66
00001
00038
00039
00040
00041
00042
00043
00044
00045
00046
00055
00056
00065
flash.h
#ifndef __EM250_FLASH_H__
#define __EM250_FLASH_H__
#ifndef DOXYGEN_SHOULD_SKIP_THIS
#ifdef XAP2B // don’t include memmap.h for non-XAP builds
#include "memmap.h"
// Flash (and simEE) parameters
#endif //XAP2B
#endif // DOXYGEN_SHOULD_SKIP_THIS
void halInternalFlashInit(void);
EmberStatus halInternalFlashVerifyInit(
void);
00066
00081 EmberStatus halInternalFlashPageErase(int8u
pageSelect);
00082
00098 XAP2B_PAGEZERO_ON
00099 EmberStatus halInternalFlashBlockRead(
int16u addr, int16u *data, int16u length);
00100 XAP2B_PAGEZERO_OFF
00101
00122 XAP2B_PAGEZERO_ON
00123 EmberStatus halInternalFlashBlockWrite(
int16u addr, int16u *data, int16s length);
00124 XAP2B_PAGEZERO_OFF
00125
00126
00127 #endif //__EM250_FLASH_H__
00128
8.67
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)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
497
• 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
8.67.1
Detailed Description
Utilities for forming and joining networks. See Forming and Joining Networks for documentation.
Definition in file form-and-join.h.
8.68
00001
00068
00069
00072
00073
00087
00088
00089
00090
00091
00092
00093
00094
00095
00096
00097
00098
00099
00100
00101
00102
00103
00104
00121
form-and-join.h
#define NETWORK_STORAGE_SIZE
16
#define NETWORK_STORAGE_SIZE_SHIFT 4
#ifndef FORM_AND_JOIN_MAX_NETWORKS
#ifdef EZSP_HOST
// the host’s buffer is 16-bit array, so translate to bytes for comparison
#define FORM_AND_JOIN_MAX_NETWORKS \
(EZSP_HOST_FORM_AND_JOIN_BUFFER_SIZE * 2 / NETWORK_STORAGE_SIZE)
#else
// use highest value that won’t exceed max EmberMessageBuffer length
#define FORM_AND_JOIN_MAX_NETWORKS 15
#endif
#endif
// Check that this value isn’t too large for the SoC implementation to handle
#ifndef EZSP_HOST
#if (FORM_AND_JOIN_MAX_NETWORKS > 15)
#error "FORM_AND_JOIN_MAX_NETWORKS can’t exceed 15 on SoC platform"
#endif
#endif
EmberStatus emberScanForUnusedPanId(int32u
channelMask, int8u duration);
00122
00149 EmberStatus emberScanForJoinableNetwork(
int32u channelMask, int8u* extendedPanId);
00150
00152 EmberStatus emberScanForNextJoinableNetwork
(void);
00153
00169 extern boolean emberEnableDualChannelScan;
00170
00175 boolean emberFormAndJoinIsScanning(void);
00176
EmberZNet 4.7.2 API EM250
120-3016-000-4720
498
00177 //
-----------------------------------------------------------------------------00178 // Callbacks the application needs to implement.
00179
00188 void emberUnusedPanIdFoundHandler(EmberPanId
panId, int8u channel);
00189
00200 void emberJoinableNetworkFoundHandler(
EmberZigbeeNetwork *networkFound,
00201
int8u lqi,
00202
int8s rssi);
00203
00221 void emberScanErrorHandler(EmberStatus status);
00222
00223 //
-----------------------------------------------------------------------------00224 // Library functions the application must call from within the
00225 // corresponding EmberZNet or EZSP callback.
00226
00234 boolean emberFormAndJoinScanCompleteHandler(
int8u channel, EmberStatus status);
00235
00243 boolean emberFormAndJoinNetworkFoundHandler(
EmberZigbeeNetwork *networkFound,
00244
int8u lqi,
00245
int8s rssi);
00246
00254 boolean emberFormAndJoinEnergyScanResultHandler
(int8u channel, int8s maxRssiValue);
00255
00260 void emberFormAndJoinTick(void);
00261
00265 void emberFormAndJoinTaskInit(void);
00266
00270 void emberFormAndJoinRunTask(void);
00271
00276 void emberFormAndJoinCleanup(EmberStatus
status);
00277
00278
00279
8.69
fragment.h File Reference
Transmitting
• EmberStatus emberFragmentSendUnicast (EmberOutgoingMessageType type, int16u indexOrDestination,
EmberApsFrame ∗apsFrame, EmberMessageBuffer payload, int8u maxFragmentSize)
• boolean emberFragmentMessageSent (EmberApsFrame ∗apsFrame, EmberMessageBuffer buffer,
EmberStatus status)
• void emberFragmentMessageSentHandler (EmberStatus status)
Receiving
• boolean emberFragmentIncomingMessage (EmberApsFrame ∗apsFrame, EmberMessageBuffer payload)
• void emberFragmentTick (void)
8.69.1
Detailed Description
Splits long messages into smaller blocks for transmission and reassembles received blocks. See Message
Fragmentation for documentation.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
499
Deprecated The fragment library is deprecated and will be removed in a future release. Similar functionality is available in the Fragmentation plugin in Application Framework.
Definition in file fragment.h.
8.70
fragment.h
00001
00068 EmberStatus emberFragmentSendUnicast(
EmberOutgoingMessageType type,
00069
int16u indexOrDestination,
00070
EmberApsFrame *apsFrame,
00071
EmberMessageBuffer
payload,
00072
int8u maxFragmentSize);
00073
00088 boolean emberFragmentMessageSent(EmberApsFrame
*apsFrame,
00089
EmberMessageBuffer buffer,
00090
EmberStatus status);
00091
00099 void emberFragmentMessageSentHandler(EmberStatus
status);
00100
00127 boolean emberFragmentIncomingMessage(EmberApsFrame
*apsFrame,
00128
EmberMessageBuffer
payload);
00129
00133 void emberFragmentTick(void);
00134
8.71
hal.h File Reference
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
8.71.1
"micro/micro.h"
"micro/adc.h"
"micro/button.h"
"micro/buzzer.h"
"micro/crc.h"
"micro/endian.h"
"micro/led.h"
"micro/random.h"
"micro/serial.h"
"micro/spi.h"
"micro/system-timer.h"
"micro/bootloader-eeprom.h"
"micro/bootloader-interface.h"
"micro/diagnostic.h"
"micro/token.h"
Detailed Description
Generic set of HAL includes for all platforms. See also Hardware Abstraction Layer (HAL) API Reference
for more documentation.
Some HAL includes are not used or present in builds intended for the Host processor connected to the
Ember Network Coprocessor.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
500
Definition in file hal.h.
8.72
00001
00063
00064
00065
00066
00067
00068
00069
00070
00071
00072
00073
00074
00075
00076
00077
00078
00079
00080
00081
00082
00083
00084
00085
00086
00087
00088
00089
00090
00091
00092
00093
00094
00095
00096
00097
00098
00099
00100
00101
00102
00103
00104
00105
00106
00107
00108
00109
00110
00111
00112
00113
00114
00115
00116
00117
00118
00119
00120
00121
00122
00123
00124
00125
00126
00127
00128
00129
00130
00131
00132
00133
hal.h
#ifndef __HAL_H__
#define __HAL_H__
#ifdef HAL_HOST
#include "host/button-common.h"
#include "host/crc.h"
#include "host/led-common.h"
#include "host/micro-common.h"
#include "host/serial.h"
#include "host/system-timer.h"
#include "host/bootloader-eeprom.h"
//Pull in the micro specific ADC, buzzer, and clocks headers. The
//specific header is chosen by the build include path pointing at
//the appropriate directory.
#include "adc.h"
#include "buzzer.h"
#else //HAL_MICRO
// Keep micro and board first for specifics used by other headers
#include "micro/micro.h"
#if !defined(STACK) && defined(BOARD_HEADER)
#include BOARD_HEADER
#endif
#if (! defined(EMBER_STACK_IP))
// Pro Stack
#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"
//Host processors do not use the following modules, therefore the header
//files should be ignored.
#ifndef EZSP_HOST
#include "micro/bootloader-interface.h"
#include "micro/diagnostic.h"
#include "micro/token.h"
//No public HAL code in release 4.0 uses the symbol timer,
//therefore it should not be in doxygen.
#ifndef DOXYGEN_SHOULD_SKIP_THIS
#include "micro/symbol-timer.h"
#endif // DOXYGEN_SHOULD_SKIP_THIS
#endif //EZSP_HOST
#else
// IP Stack
#include "micro/endian.h"
#include "micro/random.h"
#include "micro/serial.h"
#include "micro/system-timer.h"
//Host processors do not use the following modules, therefore the header
//files should be ignored.
#ifndef UNIX_HOST
#include "micro/adc.h"
#include "micro/button.h"
#include "micro/buzzer.h"
#include "micro/crc.h"
#include "micro/led.h"
#include "micro/spi.h"
#include "micro/bootloader-interface.h"
#include "micro/diagnostic.h"
#include "micro/token.h"
EmberZNet 4.7.2 API EM250
120-3016-000-4720
501
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_THIS
00137
#include "micro/symbol-timer.h"
00138
#endif // DOXYGEN_SHOULD_SKIP_THIS
00139
#endif //UNIX_HOST
00140
00141 #endif // !EMBER_STACK_IP
00142
00143 #endif
00144
00145 #endif //__HAL_H__
00146
8.73
led.h File Reference
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)
8.73.1
Detailed Description
See LED Control for documentation.
Definition in file led.h.
8.74
00001
00022
00023
00027
00028
00029
00030
00031
00032
00033
00034
00035
00036
00042
00043
00049
00050
00056
00057
00067
00068
led.h
void halInternalInitLed(void);
#if defined(STACK) || defined(MINIMAL_HAL)
typedef int8u HalBoardLed;
#else
typedef enum HalBoardLedPins HalBoardLed;
#endif
// Note: Even though many compilers will use 16 bits for an enum instead of 8,
// we choose to use an enum here. The possible compiler inefficiency does not
//
//
affect stack-based parameters and local variables, which is the
general case for led paramters.
void halToggleLed(HalBoardLed led);
void halSetLed(HalBoardLed led);
void halClearLed(HalBoardLed led);
void halStackIndicateActivity(boolean turnOn);
EmberZNet 4.7.2 API EM250
120-3016-000-4720
502
8.75
mcc.h File Reference
#include "hal/micro/generic/compiler/platform-common.h"
Macros
•
•
•
•
•
•
•
•
•
•
•
•
#define _HAL_USING_XAP2B_PRAGMAS_
#define XAP2B_PAGEZERO_ON
#define XAP2B_PAGEZERO_OFF
#define _HAL_USE_COMMON_PGM_
#define BIGENDIAN_CPU
#define NO_STRIPPING
#define EEPROM
#define __SOURCEFILE__
#define assert(condition)
#define __delay_cycles(x)
#define DEBUG_LEVEL
#define halResetWatchdog()
Functions
• XAP2B_PAGEZERO_ON void halInternalAssertFailed (const char ∗filename, int linenumber)
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
Global Interrupt Manipulation Macros
•
•
•
•
•
•
•
•
•
#define START_ATOMIC_CLOCK()
#define STOP_ATOMIC_CLOCK()
#define DECLARE_INTERRUPT_STATE
#define DECLARE_INTERRUPT_STATE_LITE
#define DISABLE_INTERRUPTS()
#define DISABLE_INTERRUPTS_LITE()
#define RESTORE_INTERRUPTS()
#define RESTORE_INTERRUPTS_LITE()
#define INTERRUPTS_ON()
EmberZNet 4.7.2 API EM250
120-3016-000-4720
503
•
•
•
•
•
•
#define INTERRUPTS_OFF()
#define INTERRUPTS_WERE_ON()
#define INTERRUPTS_ARE_OFF()
#define ATOMIC(code)
#define ATOMIC_LITE(code)
#define HANDLE_PENDING_INTERRUPTS()
Miscellaneous Macros
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
#define MAIN_FUNCTION_PARAMETERS
#define MAIN_FUNCTION_ARGUMENTS
#define __attribute__(nothing)
#define UNUSED
#define SIGNED_ENUM
#define simulatedTimePasses()
#define simulatedTimePassesMs(x)
#define simulatedSerialTimePasses()
#define halCommonUDiv32By16(x, y)
#define halCommonSDiv32By16(x, y)
#define halCommonUMod32By16(x, y)
#define halCommonSMod32By16(x, y)
unsigned int __udivx2 (unsigned long a, unsigned int b)
int __divx2 (long a, int b)
unsigned int __uremx2 (unsigned long a, unsigned int b)
int __remx2 (long a, int b)
C Standard Library Memory Utilities
These should be used in place of the standard library functions.
These functions have the same parameters and expected results as their C Standard Library equivalents but
may take advantage of certain implementation optimizations.
Unless otherwise noted, these functions are utilized by the EmberStack and are therefore required to be
implemented in the HAL. Additionally, unless otherwise noted, applications that find these functions useful
may utilize them.
•
•
•
•
•
•
•
•
•
#define MEMSET(d, v, l)
#define MEMCOPY(d, s, l)
#define MEMFASTCOPY(d, s, l)
#define MEMCOMPARE(s0, s1, l)
#define MEMPGMCOMPARE(s0, s1, l)
XAP2B_PAGEZERO_OFF void void ∗ src
XAP2B_PAGEZERO_OFF void void int16u bytes
XAP2B_PAGEZERO_ON void halCommonMemCopy (void ∗dest, const void ∗src, int16u bytes)
XAP2B_PAGEZERO_OFF void halCommonMemPGMCopy (void ∗dest, void const ∗source, int16u
bytes) void halCommonBC(void ∗dest
• void halCommonMemSet (void ∗dest, int8u val, int16u bytes)
• XAP2B_PAGEZERO_ON int8s halCommonMemCompare (const void ∗source0, const void ∗source1,
int16u bytes)
• XAP2B_PAGEZERO_OFF int8s halCommonMemPGMCompare (const void ∗source0, void const
∗source1, int16u bytes)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
504
External Declarations
These are routines that are defined in certain header files that we don’t want to include, e.g. stdlib.h
• #define PLATCOMMONOKTOINCLUDE
• int abs (int I)
8.75.1
Detailed Description
See MCC PLATFORM_HEADER Configuration for detailed documentation.
Note
This file should be included first in all source files by setting the preprocessor macro PLATFORM_HEADER to point to it
Definition in file mcc.h.
8.76
00001
00017
00018
00019
00020
00021
00022
00023
00024
00025
00026
00027
00028
00029
00030
00031
00032
00033
00034
00035
00036
00037
00038
00039
00040
00041
00042
00049
00050
00051
00052
00053
00054
00055
00056
00059
00060
00061
00066
00067
00068
00074
00075
00076
00082
00083
00084
mcc.h
#ifndef __MCC_H__
#define __MCC_H__
#ifndef __MCCXAP2B__
#error Improper PLATFORM_HEADER
#endif
#ifndef WALL // build with WALL defined to re-enable all warnings
#pragma warn -83
// disable warning about unused parameters
#pragma warn -180
#endif
#ifndef DOXYGEN_SHOULD_SKIP_THIS
#include <stdarg.h>
#include "xap2b.h"
// For nop(), sif(), etc.
//TODO: figure out how to not include this here
#include "micro/xap2b/em250/regs.h"
#include <string.h>
#endif // DOXYGEN_SHOULD_SKIP_THIS
//Used for placement in zero-page memory. platform-common.h defines these
//to nothing on all other platforms.
#define _HAL_USING_XAP2B_PRAGMAS_
#define XAP2B_PAGEZERO_ON #pragma pagezero_on
#define XAP2B_PAGEZERO_OFF #pragma pagezero_off
typedef
typedef
typedef
typedef
typedef
typedef
typedef
typedef
#define
unsigned char boolean;
unsigned char int8u;
signed
char int8s;
unsigned int
int16u;
signed
int
int16s;
unsigned long int32u;
signed
long int32s;
unsigned int PointerType;
_HAL_USE_COMMON_PGM_
#define BIGENDIAN_CPU
#define NO_STRIPPING
TRUE
errorerror
#define EEPROM errorerror
EmberZNet 4.7.2 API EM250
120-3016-000-4720
505
00085
00086
00093
00094
00095
00096
00097
00098
00099
00100
00101
00102
00103
00104
00108
00109
#ifndef __SOURCEFILE__
#ifdef __BASENAME__
// __BASENAME__ This is just the filename of the source file
#define __SOURCEFILE__ __BASENAME__
#else
// Since we don’t have a basename use the whole filename and path
#define __SOURCEFILE__ __FILE__
#endif
#endif
#undef assert
XAP2B_PAGEZERO_ON
void halInternalAssertFailed(const char *filename, int
linenumber);
00110 XAP2B_PAGEZERO_OFF
00111
00117 #define assert(condition) \
00118
do { if (! (condition)) \
00119
halInternalAssertFailed(__SOURCEFILE__, __LINE__); } while(0)
00120
00121
00122 #ifndef BOOTLOADER
00123
#undef __delay_cycles
00124
00130
#define __delay_cycles(x)
please_use_halCommonDelayMicroseconds_instead_of_delay_cycles
00131 #endif
00132
00136 #ifndef DEBUG_LEVEL
00137
#if defined(DEBUG) && defined(DEBUG_OFF)
00138
#error "DEBUG and DEBUG_OFF cannot be both be defined!"
00139
#elif defined(DEBUG)
00140
#define DEBUG_LEVEL FULL_DEBUG
00141
#elif defined(DEBUG_OFF)
00142
#define DEBUG_LEVEL NO_DEBUG
00143
#else
00144
#define DEBUG_LEVEL BASIC_DEBUG
00145
#endif
00146 #endif
00147
00152 #define halResetWatchdog() halInternalResetWatchDog()
00153
00154
00156
00159
00160 #ifdef BOOTLOADER
00161
#ifndef DOXYGEN_SHOULD_SKIP_THIS
00162
// The bootloader does not use interrupts
00163
#define DECLARE_INTERRUPT_STATE
00164
#define DECLARE_INTERRUPT_STATE_LITE
00165
#define DISABLE_INTERRUPTS() do { } while(0)
00166
#define DISABLE_INTERRUPTS_LITE() do { } while(0)
00167
#define RESTORE_INTERRUPTS() do { } while(0)
00168
#define RESTORE_INTERRUPTS_LITE() do { } while(0)
00169
#define INTERRUPTS_ON() do { } while(0)
00170
#define INTERRUPTS_OFF() do { } while(0)
00171
#define INTERRUPTS_ARE_OFF() (FALSE)
00172
#define ATOMIC(blah) { blah }
00173
#define ATOMIC_LITE(blah) { blah }
00174
#define HANDLE_PENDING_INTERRUPTS() do { } while(0)
00175
#endif // DOXYGEN_SHOULD_SKIP_THIS
00176 #else // BOOTLOADER
00177
00178
#ifndef DOXYGEN_SHOULD_SKIP_THIS
00179
// A series of macros for the diagnostics of the global interrupt state.
00180
// These macros either enable or disable the debugging code in the
00181
// Interrupt Manipulation Macros as well as define the two pins used for
00182
// indicating the entry and exit of critical sections.
00183
00184
//#define INTERRUPT_DEBUGGING
00185
#ifdef INTERRUPT_DEBUGGING
00186
#define INT_DEBUG(x) x
00187
#define I_PIN
BIT(11/*GPIO11*/)
// interrupts are enabled
00188
// ^^^^^^^^^^^^^^^^^ SHOULD MATCH I_PIN in
cstartup.xap
00189
#define I_OUT(pin)
(GPIO_DIRL |= (pin))
00190
#define I_SET(pin)
(GPIO_SETL = (pin))
EmberZNet 4.7.2 API EM250
120-3016-000-4720
506
00191
00192
00193
00194
00195
00196
00197
00198
00199
00200
00201
00202
00203
00204
00205
00206
00207
00208
00209
00210
00211
00212
00213
00214
00215
00216
00217
00218
00219
00220
00221
00222
00223
00224
00225
00226
00227
00228
00229
00230
00231
00232
00238
00239
00240
00241
00250
00251
00252
00253
00254
00255
00256
00257
00258
00259
00260
00261
00262
00263
00264
00265
00266
00267
00277
00278
00279
00280
00281
00282
00283
00284
00285
00286
00287
00288
00289
#define I_CLR(pin)
(GPIO_CLRL = (pin))
#else
#define INT_DEBUG(x)
#define I_OUT(pin)
0
#define I_SET(pin)
0
#define I_CLR(pin)
0
#endif//INTERRUPT_DEBUGGING
#ifdef INTCONTEXT_DEBUGGING
#define C_PIN
BIT(12/*GPIO12*/)
// interrupts are enabled
// ^^^^^^^^^^^^^^^^^ SHOULD MATCH C_PIN in
cstartup.xap
#define M_PIN
BIT(13/*GPIO13*/)
// interrupts are enabled
// ^^^^^^^^^^^^^^^^^ SHOULD MATCH M_PIN in
cstartup.xap
#define A_PIN
BIT(14/*GPIO14*/)
// interrupts are enabled
// ^^^^^^^^^^^^^^^^^ SHOULD MATCH A_PIN in
cstartup.xap
#endif//INTCONTEXT_DEBUGGING
//UNCOMMENT the below #define to enable timing diabled interrupt blocks,
// except for "LITE" blocks that are never timed.
//#define ENABLE_ATOMIC_CLOCK
#endif
// DOXYGEN_SHOULD_SKIP_THIS
//The core Global Interrupt Manipulation Macros start here.
//The core Global Interrupt Manipulation Macros start here.
#ifdef ENABLE_ATOMIC_CLOCK
#define START_ATOMIC_CLOCK()
do {
halStartAtomicClock(_emIsrState);
}
while(0)
#define STOP_ATOMIC_CLOCK()
do {
halStopAtomicClock(_emIsrState);
}
while(0)
#else
#define START_ATOMIC_CLOCK()
#define STOP_ATOMIC_CLOCK()
#endif
\
\
\
\
\
\
\
\
#define DECLARE_INTERRUPT_STATE int16u _emIsrState
#define DECLARE_INTERRUPT_STATE_LITE int16u _emIsrState
#define DISABLE_INTERRUPTS()
_emIsrState = halInternalDisableInterrupts();
do {
INT_DEBUG(
I_SET(I_PIN);
)
START_ATOMIC_CLOCK();
} while(0)
\
\
\
\
\
\
\
#define DISABLE_INTERRUPTS_LITE()
_emIsrState = halInternalDisableInterrupts();
do {
INT_DEBUG(
I_SET(I_PIN);
)
} while(0)
\
\
\
\
\
\
#define RESTORE_INTERRUPTS()
do {
STOP_ATOMIC_CLOCK();
INT_DEBUG(
if (INTERRUPTS_WERE_ON())
I_CLR(I_PIN);
)
INT_EN = _emIsrState;
} while(0)
\
\
\
\
\
\
\
\
#define RESTORE_INTERRUPTS_LITE() \
do {
\
INT_DEBUG(
\
EmberZNet 4.7.2 API EM250
120-3016-000-4720
507
00290
00291
00292
00293
00294
00295
00296
00301
00302
00303
00304
00305
00306
00307
00308
00309
00310
00315
00316
00317
00318
00319
00320
00321
00322
00323
00328
00329
00333
00334
00335
00342
00343
00344
00345
00346
00347
00348
00349
00350
00351
00352
00353
00354
00355
00356
00357
00358
00370
00371
00372
00373
00374
00375
00376
00377
00378
00379
00380
00381
00382
00383
00384
00385
00387
00390
00391
00396
00397
00398
00399
00403
00404
00405
00410
00411
00412
00416
00417
00418
\
\
\
\
if (INTERRUPTS_WERE_ON())
I_CLR(I_PIN);
)
INT_EN = _emIsrState;
} while(0)
#define INTERRUPTS_ON()
do {
INT_DEBUG(
I_OUT(I_PIN);
I_CLR(I_PIN);
)
INT_EN = 0xFFFF;
} while(0)
#define INTERRUPTS_OFF()
do {
INT_EN = 0;
INT_DEBUG(
I_SET(I_PIN);
)
} while(0)
\
\
\
\
\
\
\
\
\
\
\
\
\
#define INTERRUPTS_WERE_ON() (_emIsrState)
#define INTERRUPTS_ARE_OFF() (! INT_EN)
#define ATOMIC(code)
{
DECLARE_INTERRUPT_STATE;
DISABLE_INTERRUPTS();
{ code }
RESTORE_INTERRUPTS();
}
\
\
\
\
\
\
#define ATOMIC_LITE(code)
{
DECLARE_INTERRUPT_STATE_LITE;
DISABLE_INTERRUPTS_LITE();
{ code }
RESTORE_INTERRUPTS_LITE();
}
\
\
\
\
\
\
#define HANDLE_PENDING_INTERRUPTS()
do {
if (INTERRUPTS_ARE_OFF()) {
INTERRUPTS_ON();
sif();
sif();
INTERRUPTS_OFF();
}
} while (0)
\
\
\
\
\
\
\
\
#endif // BOOTLOADER
#define MAIN_FUNCTION_PARAMETERS void
#define MAIN_FUNCTION_ARGUMENTS
#define __attribute__(nothing)
#define UNUSED
#define SIGNED_ENUM (signed int)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
508
00422
00423
00424
00425
00426
00427
00442
00443
00444
00445
00446
00452
00453
00459
00460
00466
00467
00473
00474
00476
00477
00478
00479
00480
00482
00494
00495
00499
00500
#define simulatedTimePasses()
#define simulatedTimePassesMs(x)
#define simulatedSerialTimePasses()
// xap2b uses custom DIVMOD functions
unsigned int __udivx2(unsigned long a, unsigned int b);
int __divx2(long a, int b);
unsigned int __uremx2(unsigned long a, unsigned int b);
int __remx2(long a, int b);
#define halCommonUDiv32By16(x, y) __udivx2(x, y)
#define halCommonSDiv32By16(x, y) __divx2(x, y)
#define halCommonUMod32By16(x, y) __uremx2(x, y)
#define halCommonSMod32By16(x, y) __remx2(x, y)
// xap2b uses custom MEMUTILS
XAP2B_PAGEZERO_ON
void halCommonMemCopy(void *dest, const void *src, int16u
bytes);
00501 XAP2B_PAGEZERO_OFF
00502
00503
00504 #if defined DOXYGEN_SHOULD_SKIP_THIS
00505
00509
void halCommonMemPGMCopy(void* dest, void const *source,
int16u bytes)
00510 #else
00511
#define halCommonMemPGMCopy(d,s,l) halCommonMemCopy((d),(s),(l))
00512 #endif
00513
00517 void halCommonBC(void *dest, void *src, int16u bytes);
00518
00522 void halCommonMemSet(void *dest, int8u val, int16u
bytes);
00523
00527 XAP2B_PAGEZERO_ON
00528 int8s halCommonMemCompare(const void *source0, const
void *source1, int16u bytes);
00529 XAP2B_PAGEZERO_OFF
00530
00531 #if defined DOXYGEN_SHOULD_SKIP_THIS
00532
00536
int8s halCommonMemPGMCompare(const void *source0,
void const *source1, int16u bytes);
00537 #else
00538
#define halCommonMemPGMCompare(s1,s2,l) halCommonMemCompare((s1),(s2),(l))
00539 #endif
00540
00544 #define MEMSET(d,v,l) halCommonMemSet(d,v,l)
00545 #define MEMCOPY(d,s,l) halCommonMemCopy(d,s,l)
00546 #define MEMFASTCOPY(d,s,l) halCommonBC(d,s,l)
00547 #define MEMCOMPARE(s0,s1,l) halCommonMemCompare(s0, s1, l)
00548 #define MEMPGMCOMPARE(s0,s1,l) halCommonMemPGMCompare(s0, s1, l)
00549
00551
00552
00553
00555
00559
00560
00561 int abs(int I);
00562
00563 // Include platform-common last to pick up defaults and common definitions
00564 #define PLATCOMMONOKTOINCLUDE
00565
#include "hal/micro/generic/compiler/platform-common.h"
00566 #undef PLATCOMMONOKTOINCLUDE
00567
00568 #endif // __MCC_H__
00569
EmberZNet 4.7.2 API EM250
120-3016-000-4720
509
8.77
message.h File Reference
Macros
• #define EMBER_APSC_MAX_ACK_WAIT_HOPS_MULTIPLIER_MS
• #define EMBER_APSC_MAX_ACK_WAIT_TERMINAL_SECURITY_MS
Functions
• int8u emberMaximumApsPayloadLength (void)
• EmberStatus emberSendMulticast (EmberApsFrame ∗apsFrame, int8u radius, int8u nonmemberRadius, EmberMessageBuffer message)
• EmberStatus emberSendUnicast (EmberOutgoingMessageType type, int16u indexOrDestination, EmberApsFrame ∗apsFrame, EmberMessageBuffer message)
• EmberStatus emberSendBroadcast (EmberNodeId destination, EmberApsFrame ∗apsFrame, int8u
radius, EmberMessageBuffer message)
• EmberStatus emberProxyBroadcast (EmberNodeId source, EmberNodeId destination, int8u sequence,
EmberApsFrame ∗apsFrame, int8u radius, EmberMessageBuffer message)
• EmberStatus emberSendManyToOneRouteRequest (int16u concentratorType, int8u radius)
• int8u emberAppendSourceRouteHandler (EmberNodeId destination, EmberMessageBuffer header)
• void emberIncomingRouteRecordHandler (EmberNodeId source, EmberEUI64 sourceEui, int8u relayCount, EmberMessageBuffer header, int8u relayListIndex)
• void emberIncomingManyToOneRouteRequestHandler (EmberNodeId source, EmberEUI64 longId, int8u cost)
• void emberIncomingRouteErrorHandler (EmberStatus status, EmberNodeId target)
• EmberStatus emberCancelMessage (EmberMessageBuffer message)
• void emberMessageSentHandler (EmberOutgoingMessageType type, int16u indexOrDestination, EmberApsFrame ∗apsFrame, EmberMessageBuffer message, EmberStatus status)
• void emberIncomingMessageHandler (EmberIncomingMessageType type, EmberApsFrame ∗apsFrame, EmberMessageBuffer message)
• EmberStatus emberGetLastHopLqi (int8u ∗lastHopLqi)
• EmberStatus emberGetLastHopRssi (int8s ∗lastHopRssi)
• EmberNodeId emberGetSender (void)
• EmberStatus emberGetSenderEui64 (EmberEUI64 senderEui64)
• EmberStatus emberSendReply (int16u clusterId, EmberMessageBuffer reply)
• void emberSetReplyFragmentData (int16u fragmentData)
• boolean emberAddressTableEntryIsActive (int8u addressTableIndex)
• EmberStatus emberSetAddressTableRemoteEui64 (int8u addressTableIndex, EmberEUI64 eui64)
• void emberSetAddressTableRemoteNodeId (int8u addressTableIndex, EmberNodeId id)
• void emberGetAddressTableRemoteEui64 (int8u addressTableIndex, EmberEUI64 eui64)
• EmberNodeId emberGetAddressTableRemoteNodeId (int8u addressTableIndex)
• void emberSetExtendedTimeout (EmberEUI64 remoteEui64, boolean extendedTimeout)
• boolean emberGetExtendedTimeout (EmberEUI64 remoteEui64)
• void emberIdConflictHandler (EmberNodeId conflictingId)
• boolean emberPendingAckedMessages (void)
Variables
• int16u emberApsAckTimeoutMs
• EmberMulticastTableEntry ∗ emberMulticastTable
• int8u emberMulticastTableSize
EmberZNet 4.7.2 API EM250
120-3016-000-4720
510
8.77.1
Detailed Description
EmberZNet API for sending and receiving messages. See Sending and Receiving Messages for documentation.
Definition in file message.h.
8.78
00001
00024
00025
00032
00033
00037
00038
00048
00049
00079
message.h
int8u emberMaximumApsPayloadLength(void);
#define EMBER_APSC_MAX_ACK_WAIT_HOPS_MULTIPLIER_MS
#define EMBER_APSC_MAX_ACK_WAIT_TERMINAL_SECURITY_MS
50
100
extern int16u emberApsAckTimeoutMs;
EmberStatus emberSendMulticast(EmberApsFrame
*apsFrame,
00080
int8u radius,
00081
int8u nonmemberRadius,
00082
EmberMessageBuffer message);
00083
00141 EmberStatus emberSendUnicast(
EmberOutgoingMessageType type,
00142
int16u indexOrDestination,
00143
EmberApsFrame *apsFrame,
00144
EmberMessageBuffer message);
00145
00162 EmberStatus emberSendBroadcast(EmberNodeId
destination,
00163
EmberApsFrame *apsFrame,
00164
int8u radius,
00165
EmberMessageBuffer message);
00166
00187 EmberStatus emberProxyBroadcast(EmberNodeId
source,
00188
EmberNodeId destination,
00189
int8u sequence,
00190
EmberApsFrame *apsFrame,
00191
int8u radius,
00192
EmberMessageBuffer message);
00193
00246 EmberStatus emberSendManyToOneRouteRequest
(int16u concentratorType,
00247
int8u radius);
00248
00273 int8u emberAppendSourceRouteHandler(
EmberNodeId destination,
00274
EmberMessageBuffer header
);
00275
00295 void emberIncomingRouteRecordHandler(EmberNodeId
source,
00296
EmberEUI64 sourceEui,
00297
int8u relayCount,
00298
EmberMessageBuffer
header,
00299
int8u relayListIndex);
00300
00314 void emberIncomingManyToOneRouteRequestHandler
(EmberNodeId source,
00315
EmberEUI64 longId,
00316
int8u cost);
00317
00363 void emberIncomingRouteErrorHandler(EmberStatus
status,
00364
EmberNodeId target);
00365
00372 EmberStatus emberCancelMessage(EmberMessageBuffer
message);
00373
00391 void emberMessageSentHandler(EmberOutgoingMessageType
EmberZNet 4.7.2 API EM250
120-3016-000-4720
511
type,
00392
int16u indexOrDestination,
00393
EmberApsFrame *apsFrame,
00394
EmberMessageBuffer message,
00395
EmberStatus status);
00396
00422 void emberIncomingMessageHandler(
EmberIncomingMessageType type,
00423
EmberApsFrame *apsFrame,
00424
EmberMessageBuffer message);
00425
00456 EmberStatus emberGetLastHopLqi(int8u *
lastHopLqi);
00457
00491 EmberStatus emberGetLastHopRssi(int8s *
lastHopRssi);
00492
00500 EmberNodeId emberGetSender(void);
00501
00520 EmberStatus emberGetSenderEui64(EmberEUI64
senderEui64);
00521
00548 EmberStatus emberSendReply(int16u clusterId,
EmberMessageBuffer reply);
00549
00558 void emberSetReplyFragmentData(int16u
fragmentData);
00559
00560
00575 boolean emberAddressTableEntryIsActive(int8u
addressTableIndex);
00576
00591 EmberStatus emberSetAddressTableRemoteEui64
(int8u addressTableIndex,
00592
EmberEUI64 eui64);
00593
00609 void emberSetAddressTableRemoteNodeId(int8u
addressTableIndex,
00610
EmberNodeId id);
00611
00619 void emberGetAddressTableRemoteEui64(int8u
addressTableIndex,
00620
EmberEUI64 eui64);
00621
00638 EmberNodeId emberGetAddressTableRemoteNodeId
(int8u addressTableIndex);
00639
00660 void emberSetExtendedTimeout(EmberEUI64
remoteEui64, boolean extendedTimeout);
00661
00673 boolean emberGetExtendedTimeout(EmberEUI64
remoteEui64);
00674
00689 void emberIdConflictHandler(EmberNodeId
conflictingId);
00690
00696 boolean emberPendingAckedMessages(void);
00697
00708 extern EmberMulticastTableEntry *emberMulticastTable
;
00709
00712 extern int8u emberMulticastTableSize;
00713
8.79
mfglib.h File Reference
Functions
•
•
•
•
EmberStatus mfglibStart (void(∗mfglibRxCallback)(int8u ∗packet, int8u linkQuality, int8s rssi))
EmberStatus mfglibEnd (void)
EmberStatus mfglibStartTone (void)
EmberStatus mfglibStopTone (void)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
512
•
•
•
•
•
•
•
•
•
•
EmberStatus mfglibStartStream (void)
EmberStatus mfglibStopStream (void)
EmberStatus mfglibSendPacket (int8u ∗packet, int16u repeat)
EmberStatus mfglibSetChannel (int8u chan)
int8u mfglibGetChannel (void)
EmberStatus mfglibSetPower (int16u txPowerMode, int8s power)
int8s mfglibGetPower (void)
void mfglibSetSynOffset (int8s synOffset)
int8s mfglibGetSynOffset (void)
void mfglibTestContModCal (int8u channel, int32u duration)
8.79.1
Detailed Description
See Manufacturing and Functional Test Library for documentation.
Definition in file mfglib.h.
8.80
mfglib.h
00001
00030 #ifndef __MFGLIB_H__
00031 #define __MFGLIB_H__
00032
00055 EmberStatus mfglibStart(void (*mfglibRxCallback)(int8u
*packet, int8u linkQuality, int8s rssi));
00056
00070 EmberStatus mfglibEnd(void);
00071
00086 EmberStatus mfglibStartTone(void);
00087
00095 EmberStatus mfglibStopTone(void);
00096
00106 EmberStatus mfglibStartStream(void);
00107
00117 EmberStatus mfglibStopStream(void);
00118
00143 EmberStatus mfglibSendPacket(int8u * packet,
int16u repeat);
00144
00158 EmberStatus mfglibSetChannel(int8u chan);
00159
00166 int8u mfglibGetChannel(void);
00167
00186 EmberStatus mfglibSetPower(int16u txPowerMode,
int8s power);
00187
00194 int8s mfglibGetPower(void);
00195
00212 void mfglibSetSynOffset(int8s synOffset);
00213
00218 int8s mfglibGetSynOffset(void);
00219
00235 void mfglibTestContModCal(int8u channel, int32u
duration);
00236
00237 #endif // __MFGLIB_H__
00238
8.81
micro.h File Reference
#include "hal/micro/generic/em2xx-reset-defs.h"
EmberZNet 4.7.2 API EM250
120-3016-000-4720
513
Macros
• #define halGetEm2xxResetInfo()
Functions
•
•
•
•
void halStackProcessBootCount (void)
int8u halGetResetInfo (void)
PGM_P halGetResetString (void)
void halInternalAssertFailed (PGM_P filename, int linenumber)
8.81.1
Detailed Description
Full HAL functions common across all microcontroller-specific files. See Common Microcontroller Functions for documentation. Some functions in this file return an EmberStatus value. See error-def.h for
definitions of all EmberStatus return values.
Definition in file micro.h.
8.82
00001
00020
00021
00022
00023
00024
00025
00026
00027
00028
00029
00030
00031
00032
00033
00034
00035
00036
00037
00038
00039
00040
00041
00042
00043
00044
00045
00046
00047
00048
00049
00050
00051
00052
00053
00054
00055
00056
00057
00058
00059
00060
00061
00062
00063
micro.h
#ifndef __MICRO_H__
#define __MICRO_H__
#include "hal/micro/generic/em2xx-reset-defs.h"
#ifndef DOXYGEN_SHOULD_SKIP_THIS
#if ((! defined(EZSP_HOST)) && (! defined(UNIX_HOST)))
// If we are not a Host processor, Define distinct literal values for
// each platform and micro. The Host processor is not tied to a
// specific platform or micro since it uses EZSP. These values are
// used in ebl headers and the bootloader query response message.
// Some values may reserved for future use.
//
//
//
//
PLAT 1 was the AVR ATMega,
for PLAT 1, MICRO 1 is the
for PLAT 1, MICRO 2 is the
for PLAT 1, MICRO 3 is the
no longer supported
AVR ATMega 64
AVR ATMega 128
AVR ATMega 32
// PLAT 2 is the XAP2b
// for PLAT 2, MICRO 1 is the em250
// for PLAT 2, MICRO 2 is the em260
//
//
//
//
//
//
//
//
PLAT 4 is the Cortex-M3
for PLAT 4, MICRO 1 is the
for PLAT 4, MICRO 2 is the
for PLAT 4, MICRO 3 is the
for PLAT 4, MICRO 4 is the
for PLAT 4, MICRO 5 is the
for PLAT 4, MICRO 6 is the
for PLAT 4, MICRO 7 is the
em350
em360
em357
em367
em351
em35x
stm32w108
#if defined( EMBER_TEST )
#define PLAT 1
#define MICRO 2
#elif defined (AVR_ATMEGA)
#define PLAT 1
#if defined (AVR_ATMEGA_64)
#define MICRO 1
#elif defined (AVR_ATMEGA_128)
#define MICRO 2
#elif defined (AVR_ATMEGA_32)
#define MICRO 3
#endif
EmberZNet 4.7.2 API EM250
120-3016-000-4720
514
00064
00065
00066
00067
00068
00069
00070
00071
00072
00073
00074
00075
00076
00077
00078
00079
00080
00081
00082
00083
00084
00085
00086
00087
00088
00089
00090
00091
00092
00093
00094
00095
00096
00097
00098
00099
00100
00101
00102
00103
00104
00105
00106
00107
00108
00109
00110
00111
00112
00113
00114
00115
00116
00117
00118
00119
00120
00121
00122
00123
00124
00125
00139
00140
00145
00146
00154
00155
00164
00165
00166
00167
00168
00169
00170
00180
#elif defined (XAP2B)
#define PLAT 2
#if defined (XAP2B_EM250)
#define MICRO 1
#elif defined (XAP2B_EM260)
#define MICRO 2
#endif
#elif defined (MSP430)
#define PLAT 3
#if defined (MSP430_1612)
#define MICRO 1
#elif defined (MSP430_1471)
#define MICRO 2
#endif
#elif defined (CORTEXM3)
#define PLAT 4
#if defined (CORTEXM3_EM350)
#define MICRO 1
#elif defined (CORTEXM3_EM360)
#define MICRO 2
#elif defined (CORTEXM3_EM357)
#define MICRO 3
#elif defined (CORTEXM3_EM367)
#define MICRO 4
#elif defined (CORTEXM3_EM351)
#define MICRO 5
#elif defined (CORTEXM3_EM35X)
#define MICRO 6
#elif defined (CORTEXM3_STM32W108)
#define MICRO 7
#endif
#else
#error no platform defined, or unsupported
#endif
#ifndef MICRO
#error no micro defined, or unsupported
#endif
#endif // ((! defined(EZSP_HOST)) && (! defined(UNIX_HOST)))
//
//
//
//
//
//
Define distinct literal values for each phy.
These values are used in the bootloader query response message.
PHY 0 is a null phy
PHY 1 is the em2420 (no longer supported)
PHY 2 is the em250
PHY 3 is the em3xx
#if defined (PHY_EM2420) || defined (PHY_EM2420B)
#error EM2420 is no longer supported.
#elif defined (PHY_EM250) || defined (PHY_EM250B)
#define PHY 2
#elif defined (PHY_EM3XX)
#define PHY 3
#elif defined (PHY_NULL)
#define PHY 0
#else
#error no phy defined, or unsupported
#endif
#endif // DOXYGEN_SHOULD_SKIP_THIS
void halStackProcessBootCount(void);
int8u halGetResetInfo(void);
PGM_P halGetResetString(void);
#ifdef CORTEXM3
int8u halGetEm2xxResetInfo(void);
#else
#define halGetEm2xxResetInfo() halGetResetInfo()
#endif
void halInternalAssertFailed(PGM_P filename, int
linenumber);
00181
00182
00183 #ifndef DOXYGEN_SHOULD_SKIP_THIS
EmberZNet 4.7.2 API EM250
120-3016-000-4720
515
00184
00185
00186
00187
00188
00189
00190
00191
00192
00193
00194
00195
00196
00197
00198
00199
00200
00201
00202
00203
00204
00205
00206
00207
00208
00209
00210
00211
00212
00213
00214
00215
00216
00217
00218
00219
00220
00221
00222
00223
00224
00225
00226
00227
00228
00229
#include "micro-common.h"
#if defined( EMBER_TEST )
#include "hal/micro/unix/simulation/micro.h"
#include "hal/micro/unix/simulation/bootloader.h"
#elif defined(AVR_ATMEGA)
#if defined(AVR_ATMEGA_64) || defined(AVR_ATMEGA_128)
#include "avr-atmega/128/micro.h"
#include "avr-atmega/128/bootloader.h"
#elif defined(AVR_ATMEGA_32)
#include "avr-atmega/32/micro.h"
#else
// default, assume 128
#include "avr-atmega/128/micro.h"
#include "avr-atmega/128/bootloader.h"
#endif
#elif defined(MSP430_1612)
#include "msp430/1612/micro.h"
#include "msp430/1612/bootloader.h"
#elif defined(MSP430_1471)
#include "msp430/1471/micro.h"
#include "msp430/1471/bootloader.h"
#elif defined(XAP2B)
#include "xap2b/em250/micro.h"
#elif defined(CORTEXM3)
#include "cortexm3/micro.h"
#elif ((defined(EZSP_HOST) || defined(UNIX_HOST)))
#include "hal/micro/unix/host/micro.h"
#else
#error no platform or micro defined
#endif
// the number of ticks (as returned from halCommonGetInt32uMillisecondTick)
// that represent an actual second. This can vary on different platforms.
// It must be defined by the host system.
#ifndef MILLISECOND_TICKS_PER_SECOND
#define MILLISECOND_TICKS_PER_SECOND 1024UL
// See bug 10232
// #error "MILLISECOND_TICKS_PER_SECOND is not defined in micro.h!"
#endif
#endif // DOXYGEN_SHOULD_SKIP_THIS
#endif //__MICRO_H__
8.83
micro.h File Reference
Macros
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
#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
EmberZNet 4.7.2 API EM250
120-3016-000-4720
516
• #define RESET_BOOTLOADER_IMG_BAD
• #define MILLISECOND_TICKS_PER_SECOND
Functions
•
•
•
•
•
•
•
•
void halInternalResetWatchDog (void)
boolean halInternalWatchDogEnabled (void)
void rcSetCalibration (int16u value)
int16u rcGetCalibration (void)
void halInternalCalibrateRc (void)
int16u halInternalStackUsed (boolean lastReBoot)
int32u halGetWakeInfo (void)
void halCommonDelayMilliseconds (int16u ms)
8.83.1
Detailed Description
Utility and convenience functions for the EM250 microcontroller. See Common Microcontroller Functions
for documentation.
Definition in file xap2b/em250/micro.h.
8.84
00001
00013
00014
00015
00016
00017
00018
00019
00020
00021
00022
00023
00024
00025
00026
00027
00028
00029
00036
00037
00043
00044
00049
00050
00055
00056
00060
00061
00068
00069
00078
00079
00084
00085
00086
00087
00088
00089
00090
00091
xap2b/em250/micro.h
#ifndef __EM250_MICRO_H__
#define __EM250_MICRO_H__
#ifndef DOXYGEN_SHOULD_SKIP_THIS
#ifndef __MICRO_H__
#error do not include this file directly - include micro/micro.h
#endif
// Micro specific serial defines
#define EM_NUM_SERIAL_PORTS 2
#define EMBER_SPI_MASTER 4
#define EMBER_SPI_SLAVE 5
#define EMBER_I2C 6
#endif // DOXYGEN_SHOULD_SKIP_THIS
void halInternalResetWatchDog( void );
boolean halInternalWatchDogEnabled( void );
void rcSetCalibration( int16u value );
int16u rcGetCalibration( void );
void halInternalCalibrateRc( void );
int16u halInternalStackUsed( boolean lastReBoot );
int32u halGetWakeInfo(void);
#define RESET_UNKNOWN
#define RESET_EXTERNAL
#define RESET_POWERON
threshold
#define RESET_WATCHDOG
#define RESET_BROWNOUT
#define RESET_JTAG
#define RESET_ASSERT
#define RESET_RSTACK
EmberZNet 4.7.2 API EM250
0
1
2
// cause not known
// n/a (poweron reset instead)
// supply voltage was < power-on
3
4
5
6
7
//
//
//
//
//
watchdog timed out
n/a (no hardware support)
reset by debugger
a self-check within the code failed
n/a (memory fault instead)
120-3016-000-4720
517
00092
00093
00094
00095
00096
00097
00098
00099
00100
00101
00102
00103
00104
00105
00106
#define
#define
#define
#define
#define
#define
#define
#define
RESET_CSTACK
RESET_BOOTLOADER
RESET_PC_ROLLOVER
RESET_SOFTWARE
RESET_PROTFAULT
RESET_FLASH_VERIFY_FAIL
RESET_FLASH_WRITE_INHIBIT
RESET_BOOTLOADER_IMG_BAD
8
9
10
11
12
13
14
15
//
//
//
//
//
//
//
//
n/a (memory fault instead)
requested by bootloader
n/a (memory fault instead)
reset requested by software
n/a (memory fault instead)
flash write verify failure
flash write inhibited: already written
app BTL: bad EEPROM upgrade image
#ifndef DOXYGEN_SHOULD_SKIP_THIS
XAP2B_PAGEZERO_ON
extern int16u halInternalDisableInterrupts(void); // ncc.h &
DISABLE_INTERRUPTS()
00107 XAP2B_PAGEZERO_OFF
00108
00109 extern int8u *halInternalGetSp( void );
// cstartup.xap
00110
00111 #ifdef DEBUG
00112 //------------- WatchPoint mechanism
00113
00114 typedef struct watchPoint_s {
00115
int8u
wpAction;
// see WP_TRIG_ actions below
00116
int8u
wpType;
// see WP_TYPE_ types below
00117
int16u *wpAddr;
// address to watch
00118
int16u wpData;
// data pattern
00119
int16u wpMask;
// mask of data pattern (0=disabled
watchpoint)
00120
int16u wpCount;
// disable after count occurrences
(0=never)
00121
int16u wpPrevData;
// previous data pattern seen
00122
int16u wpPc;
// last PC of triggering write
00123 } watchPoint_t;
00124
00125 #define WP_TRIG_SLEEP
0x01
// Sleep (because brk won’t work)
00126 #define WP_TRIG_FATAL
0x02
// Force system reset
00127 #define WP_TRIG_VERBOSE
0x80
// Attempt verbose debug printf
00128
00129 #define WP_TYPE_DISABLED
0
00130 #define WP_TYPE_ANY_CHANGE
1
00131 #define WP_TYPE_DATA_MATCH
2
00132 #define WP_TYPE_DATA_MISMATCH
3
00133
00134 extern void halInternalSetFlags( int16u flagsMask );
// cstartup.xap
00135 extern void halInternalClrFlags( int16u flagsMask );
// cstartup.xap
00136 extern int16u halInternalGetFlags( void );
// cstartup.xap
00137 extern int16u microGetPc( void );
// cstartup.xap
00138 extern int8s halInternalSetWatchPoint(watchPoint_t *newWp);
00139 extern void halInternalClearWatchPoint(int8u index);
00140
00141 #include "xap2.h"
// For FLAGS definitions
00142
00143 #define SUSPEND_DEBUGGER(blah)
00144 {
00145
int16u _emFlags = (halInternalGetFlags() & (FLAGS_B_MASK | FLAGS_T_MASK));
00146
if (_emFlags) halInternalClrFlags(_emFlags);
00147
{ blah }
00148
if (_emFlags) halInternalSetFlags(_emFlags);
00149 }
00150 #else
00151 #define SUSPEND_DEBUGGER(blah) blah
00152 #endif//DEBUG
00153
00154 #ifndef offsetof
00155 #define offsetof(type, field) ( (int) &((type *) 0)->field )
00156 #endif//offsetof
00157
00158 #endif // DOXYGEN_SHOULD_SKIP_THIS
00159
00160 // the number of ticks (as returned from halCommonGetInt32uMillisecondTick)
00161 // that represent an actual second. This can vary on different platforms.
00162 #define MILLISECOND_TICKS_PER_SECOND 1024UL
00163
00164 void halCommonDelayMilliseconds(int16u ms);
00165
00166 #endif //__EM250_MICRO_H__
00167
EmberZNet 4.7.2 API EM250
120-3016-000-4720
\
\
\
\
\
\
518
8.85
network-formation.h File Reference
Functions
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
EmberStatus emberInit (void)
void emberTick (void)
EmberStatus emberNetworkInit (void)
EmberStatus emberNetworkInitExtended (EmberNetworkInitStruct ∗networkInitStruct)
EmberStatus emberFormNetwork (EmberNetworkParameters ∗parameters)
EmberStatus emberPermitJoining (int8u duration)
EmberStatus emberJoinNetwork (EmberNodeType nodeType, EmberNetworkParameters ∗parameters)
EmberStatus emberLeaveNetwork (void)
EmberStatus emberSendZigbeeLeave (EmberNodeId destination, EmberLeaveRequestFlags flags)
EmberStatus emberFindAndRejoinNetworkWithReason (boolean haveCurrentNetworkKey, int32u
channelMask, EmberRejoinReason reason)
EmberStatus emberFindAndRejoinNetwork (boolean haveCurrentNetworkKey, int32u channelMask)
EmberRejoinReason emberGetLastRejoinReason (void)
EmberStatus emberRejoinNetwork (boolean haveCurrentNetworkKey)
EmberStatus emberStartScan (EmberNetworkScanType scanType, int32u channelMask, int8u duration)
EmberStatus emberStopScan (void)
void emberScanCompleteHandler (int8u channel, EmberStatus status)
void emberEnergyScanResultHandler (int8u channel, int8s maxRssiValue)
void emberNetworkFoundHandler (EmberZigbeeNetwork ∗networkFound)
boolean emberStackIsPerformingRejoin (void)
EmberLeaveReason emberGetLastLeaveReason (EmberNodeId ∗returnNodeIdThatSentLeave)
8.85.1
Detailed Description
See Network Formation for documentation.
Definition in file network-formation.h.
8.86
00001
00032
00033
00039
00040
00059
00060
00069
network-formation.h
EmberStatus emberInit(void);
void emberTick(void);
EmberStatus emberNetworkInit(void);
EmberStatus emberNetworkInitExtended(
EmberNetworkInitStruct* networkInitStruct);
00070
00082 EmberStatus emberFormNetwork(EmberNetworkParameters
*parameters);
00083
00093 EmberStatus emberPermitJoining(int8u duration
);
00094
00115 EmberStatus emberJoinNetwork(EmberNodeType
nodeType,
00116
EmberNetworkParameters *
parameters);
00117
00127 EmberStatus emberLeaveNetwork(void);
EmberZNet 4.7.2 API EM250
120-3016-000-4720
519
00128
00143 EmberStatus emberSendZigbeeLeave(EmberNodeId
destination,
00144
EmberLeaveRequestFlags
flags);
00145
00146
00189 EmberStatus emberFindAndRejoinNetworkWithReason
(boolean haveCurrentNetworkKey,
00190
int32u channelMask,
00191
EmberRejoinReason reason);
00192
00196 EmberStatus emberFindAndRejoinNetwork(
boolean haveCurrentNetworkKey,
00197
int32u channelMask);
00198
00201 EmberRejoinReason emberGetLastRejoinReason(void);
00202
00207 #ifdef DOXYGEN_SHOULD_SKIP_THIS
00208 EmberStatus emberRejoinNetwork(boolean
haveCurrentNetworkKey);
00209 #else
00210 #define emberRejoinNetwork(haveKey) emberFindAndRejoinNetwork((haveKey), 0)
00211 #endif
00212
00247 EmberStatus emberStartScan(EmberNetworkScanType
scanType,
00248
int32u channelMask,
00249
int8u duration);
00250
00255 EmberStatus emberStopScan(void);
00256
00271 void emberScanCompleteHandler( int8u channel,
EmberStatus status );
00272
00281 void emberEnergyScanResultHandler(int8u
channel, int8s maxRssiValue);
00282
00290 void emberNetworkFoundHandler(EmberZigbeeNetwork
*networkFound);
00291
00298 boolean emberStackIsPerformingRejoin(void);
00299
00300
00314 EmberLeaveReason emberGetLastLeaveReason
(EmberNodeId* returnNodeIdThatSentLeave);
00315
00316
8.87
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)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
520
8.87.1
Detailed Description
Utilities for use by the ZigBee network manager. See Network Manager for documentation.
Definition in file network-manager.h.
8.88
00001
00090
00091
00092
00093
00094
00095
00096
00097
00098
00099
00100
00101
00102
00103
00104
00105
00106
00107
00108
00109
00110
00111
00112
00113
00114
00115
00122
00123
00132
network-manager.h
#include CONFIGURATION_HEADER
// The application is notified via nmUtilWarningHandler
// if NM_WARNING_LIMIT unsolicited scan reports are received
// within NM_WINDOW_SIZE minutes. To save flash and RAM,
// the actual timing is approximate.
#ifndef NM_WARNING_LIMIT
#define NM_WARNING_LIMIT 16
#endif
#ifndef NM_WINDOW_SIZE
#define NM_WINDOW_SIZE 4
#endif
// The channels that should be used by the network manager.
#ifndef NM_CHANNEL_MASK
#define NM_CHANNEL_MASK EMBER_ALL_802_15_4_CHANNELS_MASK
#endif
// The number of channels used in the NM_CHANNEL_MASK.
#ifndef NM_WATCHLIST_SIZE
#define NM_WATCHLIST_SIZE 16
#endif
void nmUtilWarningHandler(void);
boolean nmUtilProcessIncoming(EmberApsFrame *
apsFrame,
00133
int8u messageLength,
00134
int8u* message);
00135
00139 EmberStatus nmUtilChangeChannelRequest(
void);
00140
8.89
packet-buffer.h File Reference
Macros
•
•
•
•
#define LOG_PACKET_BUFFER_SIZE
#define PACKET_BUFFER_SIZE
#define EMBER_NULL_MESSAGE_BUFFER
#define emberMessageBufferLength(buffer)
Functions
•
•
•
•
•
XAP2B_PAGEZERO_ON int8u ∗ emberMessageBufferContents (EmberMessageBuffer buffer)
void emberSetMessageBufferLength (EmberMessageBuffer buffer, int8u newLength)
void emberHoldMessageBuffer (EmberMessageBuffer buffer)
void emberReleaseMessageBuffer (EmberMessageBuffer buffer)
int8u emberPacketBufferFreeCount (void)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
521
Buffer Functions
•
•
•
•
•
#define emberStackBufferLink(buffer)
#define emberSetStackBufferLink(buffer, newLink)
#define emberAllocateStackBuffer()
EmberMessageBuffer emberAllocateLinkedBuffers (int8u count)
EmberMessageBuffer emberFillStackBuffer (int16u count,...)
Linked Buffer Utilities
The plural "buffers" in the names of these procedures is a reminder that they deal with linked chains of
buffers.
• EmberMessageBuffer emberFillLinkedBuffers (int8u ∗contents, int8u length)
• void emberCopyToLinkedBuffers (int8u ∗contents, EmberMessageBuffer buffer, int8u startIndex,
int8u length)
• void emberCopyFromLinkedBuffers (EmberMessageBuffer buffer, int8u startIndex, int8u ∗contents,
int8u length)
• void emberCopyBufferBytes (EmberMessageBuffer to, int16u toIndex, EmberMessageBuffer from,
int16u fromIndex, int16u count)
• EmberStatus emberAppendToLinkedBuffers (EmberMessageBuffer buffer, int8u ∗contents, int8u
length)
• EmberStatus emberAppendPgmToLinkedBuffers (EmberMessageBuffer buffer, PGM_P contents,
int8u length)
• EmberStatus emberAppendPgmStringToLinkedBuffers (EmberMessageBuffer buffer, PGM_P suffix)
• EmberStatus emberSetLinkedBuffersLength (EmberMessageBuffer buffer, int8u length)
• int8u ∗ emberGetLinkedBuffersPointer (EmberMessageBuffer buffer, int8u index)
• XAP2B_PAGEZERO_ON int8u emberGetLinkedBuffersByte (EmberMessageBuffer buffer, int8u
index)
• XAP2B_PAGEZERO_OFF void emberSetLinkedBuffersByte (EmberMessageBuffer buffer, int8u
index, int8u byte)
• int16u emberGetLinkedBuffersLowHighInt16u (EmberMessageBuffer buffer, int8u index)
• void emberSetLinkedBuffersLowHighInt16u (EmberMessageBuffer buffer, int8u index, int16u value)
• int32u emberGetLinkedBuffersLowHighInt32u (EmberMessageBuffer buffer, int8u index)
• void emberSetLinkedBuffersLowHighInt32u (EmberMessageBuffer buffer, int8u index, int32u value)
• EmberMessageBuffer emberCopyLinkedBuffers (EmberMessageBuffer buffer)
• EmberMessageBuffer emberMakeUnsharedLinkedBuffer (EmberMessageBuffer buffer, boolean isShared)
8.89.1
Detailed Description
Packet buffer allocation and management routines See Packet Buffers for documentation.
Definition in file packet-buffer.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
522
8.90
packet-buffer.h
00001
00010 // The old overview was for the wrong audience. A new overview should be
written.
00011
00032 #ifndef __PACKET_BUFFER_H__
00033 #define __PACKET_BUFFER_H__
00034
00038 #define LOG_PACKET_BUFFER_SIZE 5
00039
00042 #define PACKET_BUFFER_SIZE (1 << LOG_PACKET_BUFFER_SIZE)
00043
00045 #define EMBER_NULL_MESSAGE_BUFFER 0xFF
00046
00057 XAP2B_PAGEZERO_ON
00058 int8u *emberMessageBufferContents(
EmberMessageBuffer buffer);
00059 XAP2B_PAGEZERO_OFF
00060
00061 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00062 // An old name.
00063 #define emberLinkedBufferContents(buffer) emberMessageBufferContents(buffer)
00064 #endif
00065
00073 #define emberMessageBufferLength(buffer)
(emMessageBufferLengths[buffer])
00074
00085 void emberSetMessageBufferLength(EmberMessageBuffer
buffer, int8u newLength);
00086
00087 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00088 #ifdef EM_DEBUG_BUFFER_USE
00089 #define EM_BUFFER_DEBUG(X) X
00090 #define EM_BUFFER_FILE_LOC , __FILE__, __LINE__
00091 #define EM_BUFFER_FILE_DECL , char *file, int line
00092 #define EM_BUFFER_FILE_VALUE , file, line
00093 #else
00094 #define EM_BUFFER_DEBUG(X)
00095 #define EM_BUFFER_FILE_LOC
00096 #define EM_BUFFER_FILE_DECL
00097 #define EM_BUFFER_FILE_VALUE
00098 #endif
00099
00100 #ifdef EMBER_TEST
00101 #define EM_ASSERT_IS_NOT_FREE(buffer) \
00102 assert(emMessageBufferReferenceCounts[(buffer)] > 0)
00103 #define EM_ASSERT_IS_VALID_BUFFER(buffer) \
00104 assert(buffer < emPacketBufferCount)
00105 #else
00106 #define EM_ASSERT_IS_NOT_FREE(buffer)
00107 #define EM_ASSERT_IS_VALID_BUFFER(buffer)
00108 #endif // EMBER_TEST
00109 #endif // DOXYGEN_SHOULD_SKIP_THIS
00110
00116 #ifdef DOXYGEN_SHOULD_SKIP_THIS
00117 void emberHoldMessageBuffer(EmberMessageBuffer
buffer);
00118 #else
00119
00120 #ifdef EMBER_TEST
00121 #define emberHoldMessageBuffer(buffer)
00122 do {
00123
EmberMessageBuffer EM_HOLD_BUFFER_TEMP_XXX = (buffer);
00124
EM_ASSERT_IS_NOT_FREE(EM_HOLD_BUFFER_TEMP_XXX);
00125
EM_ASSERT_IS_VALID_BUFFER(EM_HOLD_BUFFER_TEMP_XXX);
00126
emHoldMessageBuffer(EM_HOLD_BUFFER_TEMP_XXX EM_BUFFER_FILE_LOC);
00127 } while (FALSE)
00128
00129 #else
00130 #define emberHoldMessageBuffer(buffer) emHoldMessageBuffer(buffer)
00131 #endif // EMBER_TEST
00132
00133 void emHoldMessageBuffer(EmberMessageBuffer buffer
EM_BUFFER_FILE_DECL);
00134 #endif
00135
00141 #ifdef DOXYGEN_SHOULD_SKIP_THIS
00142 void emberReleaseMessageBuffer(EmberMessageBuffer
buffer);
EmberZNet 4.7.2 API EM250
120-3016-000-4720
\
\
\
\
\
\
523
00143
00144
00145
00146
00147
00148
00149
00150
00151
00152
00153
00154
00155
00156
00157
00158
#else
#if defined(EMBER_TEST)
#define emberReleaseMessageBuffer(buffer)
do {
EmberMessageBuffer EM_RELEASE_BUFFER_TEMP_XXX = (buffer);
EM_ASSERT_IS_NOT_FREE(EM_RELEASE_BUFFER_TEMP_XXX);
EM_ASSERT_IS_VALID_BUFFER(EM_RELEASE_BUFFER_TEMP_XXX);
emReleaseMessageBuffer(EM_RELEASE_BUFFER_TEMP_XXX EM_BUFFER_FILE_LOC);
} while (FALSE)
#else
#define emberReleaseMessageBuffer(buffer) emReleaseMessageBuffer(buffer)
#endif // EMBER_TEST
\
\
\
\
\
\
XAP2B_PAGEZERO_ON
void emReleaseMessageBuffer(EmberMessageBuffer buffer
EM_BUFFER_FILE_DECL);
00159 XAP2B_PAGEZERO_OFF
00160 #endif //DOXYGEN_SHOULD_SKIP_THIS
00161
00162 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00163 extern int8u emPacketBufferCount;
00164 extern int8u *emPacketBufferData;
00165 extern int8u *emMessageBufferLengths;
00166 extern int8u *emMessageBufferReferenceCounts;
00167 extern EmberMessageBuffer *emPacketBufferLinks;
00168 extern EmberMessageBuffer *emPacketBufferQueueLinks;
00169 #endif //DOXYGEN_SHOULD_SKIP_THIS
00170
00175
00185 #define emberStackBufferLink(buffer) \
00186 (emPacketBufferLinks[(buffer)])
00187
00196 #define emberSetStackBufferLink(buffer, newLink) \
00197 (emPacketBufferLinks[(buffer)] = (newLink))
00198
00205 #define emberAllocateStackBuffer() (emberAllocateLinkedBuffers(1))
00206
00215 EmberMessageBuffer emberAllocateLinkedBuffers
(int8u count);
00216
00228 EmberMessageBuffer emberFillStackBuffer(
int16u count, ...);
00230
00237
00251 EmberMessageBuffer emberFillLinkedBuffers
(int8u *contents, int8u length);
00252
00266 #ifdef DOXYGEN_SHOULD_SKIP_THIS
00267 void
00268 emberCopyToLinkedBuffers(int8u *contents,
00269
EmberMessageBuffer buffer,
00270
int8u startIndex,
00271
int8u length);
00272 #else
00273 #define emberCopyToLinkedBuffers(contents, buffer, startIndex, length) \
00274 emReallyCopyToLinkedBuffers((PGM_P) (contents), (buffer), (startIndex),
(length), 1)
00275 XAP2B_PAGEZERO_ON
00276 void
00277 emReallyCopyToLinkedBuffers(PGM_P contents,
00278
EmberMessageBuffer buffer,
00279
int8u startIndex,
00280
int8u length,
00281
int8u direction);
00282 XAP2B_PAGEZERO_OFF
00283 #endif //DOXYGEN_SHOULD_SKIP_THIS
00284
00298 #ifdef DOXYGEN_SHOULD_SKIP_THIS
00299 // To save flash this shares an implementation with emberCopyToLinkedBuffers().
00300 void
00301 emberCopyFromLinkedBuffers(EmberMessageBuffer
buffer,
00302
int8u startIndex,
00303
int8u *contents,
00304
int8u length);
00305 #else
00306 #define emberCopyFromLinkedBuffers(buffer, startIndex, contents, length) \
00307 emReallyCopyToLinkedBuffers((PGM_P) (contents), (buffer), (startIndex),
(length), 0)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
524
00308 #endif
00309
00323 void emberCopyBufferBytes(EmberMessageBuffer
to,
00324
int16u toIndex,
00325
EmberMessageBuffer from,
00326
int16u fromIndex,
00327
int16u count);
00328
00343 EmberStatus emberAppendToLinkedBuffers(
EmberMessageBuffer buffer,
00344
int8u *contents,
00345
int8u length);
00346
00360 #ifdef DOXYGEN_SHOULD_SKIP_THIS
00361 // To save flash this shares an implementation with
00362 // emberAppendToLinkedBuffers().
00363 EmberStatus emberAppendPgmToLinkedBuffers
(EmberMessageBuffer buffer,
00364
PGM_P contents,
00365
int8u length);
00366 #else
00367 #define emberAppendPgmToLinkedBuffers(buffer, contents, length) \
00368 (emAppendToLinkedBuffers((buffer), (PGM_P) (contents), (length), 2))
00369
00370 EmberStatus emAppendToLinkedBuffers(EmberMessageBuffer
buffer,
00371
PGM_P contents,
00372
int8u length,
00373
int8u direction);
00374 #endif
00375
00385 EmberStatus emberAppendPgmStringToLinkedBuffers
(EmberMessageBuffer buffer, PGM_P suffix);
00386
00399 EmberStatus emberSetLinkedBuffersLength(
EmberMessageBuffer buffer, int8u length);
00400
00410 int8u *emberGetLinkedBuffersPointer(
EmberMessageBuffer buffer, int8u index);
00411
00421 XAP2B_PAGEZERO_ON
00422 int8u emberGetLinkedBuffersByte(
EmberMessageBuffer buffer, int8u index);
00423 XAP2B_PAGEZERO_OFF
00424
00434 void emberSetLinkedBuffersByte(EmberMessageBuffer
buffer, int8u index, int8u byte);
00435
00445 int16u emberGetLinkedBuffersLowHighInt16u
(EmberMessageBuffer buffer,
00446
int8u index);
00447
00457 void emberSetLinkedBuffersLowHighInt16u(
EmberMessageBuffer buffer,
00458
int8u index,
00459
int16u value);
00460
00470 int32u emberGetLinkedBuffersLowHighInt32u
(EmberMessageBuffer buffer,
00471
int8u index);
00472
00482 void emberSetLinkedBuffersLowHighInt32u(
EmberMessageBuffer buffer,
00483
int8u index,
00484
int32u value);
00485
00493 EmberMessageBuffer emberCopyLinkedBuffers
(EmberMessageBuffer buffer);
00494
00507 EmberMessageBuffer emberMakeUnsharedLinkedBuffer
(EmberMessageBuffer buffer, boolean isShared);
00508
00510
00516 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00517 extern int8u emPacketBufferFreeCount;
00518 #define emberPacketBufferFreeCount() (emPacketBufferFreeCount)
00519 #else
00520 int8u emberPacketBufferFreeCount(void);
00521 #endif
EmberZNet 4.7.2 API EM250
120-3016-000-4720
525
00522
00525 #endif
8.91
// __PACKET_BUFFER_H__
random.h File Reference
Functions
• void halStackSeedRandom (int32u seed)
• int16u halCommonGetRandom (void)
8.91.1
Detailed Description
See Random Number Generation for detailed documentation.
Definition in file random.h.
8.92
00001
00016
00017
00018
00026
00027
00036
00037
00038
00039
00040
00041
00042
00046
00047
00048
random.h
#ifndef __RANDOM_H__
#define __RANDOM_H__
void halStackSeedRandom(int32u seed);
#if defined( EMBER_TEST )
#define halCommonGetRandom() halCommonGetRandomTraced(__FILE__, __LINE__)
int16u halCommonGetRandomTraced(char *file, int line);
#else
int16u halCommonGetRandom(void);
#endif
#endif //__RANDOM_H__
8.93
security.h File Reference
#include "stack/include/trust-center.h"
Macros
• #define EMBER_JOIN_NO_PRECONFIG_KEY_BITMASK
• #define EMBER_JOIN_PRECONFIG_KEY_BITMASK
Functions
•
•
•
•
•
EmberStatus emberSetInitialSecurityState (EmberInitialSecurityState ∗state)
EmberStatus emberSetExtendedSecurityBitmask (EmberExtendedSecurityBitmask mask)
EmberStatus emberGetExtendedSecurityBitmask (EmberExtendedSecurityBitmask ∗mask)
EmberStatus emberGetCurrentSecurityState (EmberCurrentSecurityState ∗state)
EmberStatus emberGetKey (EmberKeyType type, EmberKeyStruct ∗keyStruct)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
526
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
boolean emberHaveLinkKey (EmberEUI64 remoteDevice)
EmberStatus emberGenerateRandomKey (EmberKeyData ∗keyAddress)
void emberSwitchNetworkKeyHandler (int8u sequenceNumber)
EmberStatus emberRequestLinkKey (EmberEUI64 partner)
void emberZigbeeKeyEstablishmentHandler (EmberEUI64 partner, EmberKeyStatus status)
EmberStatus emberGetKeyTableEntry (int8u index, EmberKeyStruct ∗result)
EmberStatus emberSetKeyTableEntry (int8u index, EmberEUI64 address, boolean linkKey, EmberKeyData ∗keyData)
EmberStatus emberAddOrUpdateKeyTableEntry (EmberEUI64 address, boolean linkKey, EmberKeyData ∗keyData)
int8u emberFindKeyTableEntry (EmberEUI64 address, boolean linkKey)
EmberStatus emberEraseKeyTableEntry (int8u index)
EmberStatus emberClearKeyTable (void)
EmberStatus emberStopWritingStackTokens (void)
EmberStatus emberStartWritingStackTokens (void)
boolean emberWritingStackTokensEnabled (void)
EmberStatus emberApsCryptMessage (boolean encrypt, EmberMessageBuffer buffer, int8u apsHeaderEndIndex, EmberEUI64 remoteEui64)
EmberStatus emberGetMfgSecurityConfig (EmberMfgSecurityStruct ∗settings)
EmberStatus emberSetMfgSecurityConfig (int32u magicNumber, const EmberMfgSecurityStruct ∗settings)
8.93.1
Detailed Description
EmberZNet security API. See Security for documentation.
Definition in file security.h.
8.94
security.h
00001
00029 #include "stack/include/trust-center.h"
00030
00067 EmberStatus emberSetInitialSecurityState
(EmberInitialSecurityState* state);
00068
00077 EmberStatus emberSetExtendedSecurityBitmask
(EmberExtendedSecurityBitmask mask);
00078
00087 EmberStatus emberGetExtendedSecurityBitmask
(EmberExtendedSecurityBitmask* mask);
00088
00089
00096 #define EMBER_JOIN_NO_PRECONFIG_KEY_BITMASK \
00097
( EMBER_STANDARD_SECURITY_MODE
\
00098
| EMBER_GET_LINK_KEY_WHEN_JOINING )
00099
00106 #define EMBER_JOIN_PRECONFIG_KEY_BITMASK \
00107
( EMBER_STANDARD_SECURITY_MODE
\
00108
| EMBER_HAVE_PRECONFIGURED_KEY
\
00109
| EMBER_REQUIRE_ENCRYPTED_KEY )
00110
00111
00121 EmberStatus emberGetCurrentSecurityState
(EmberCurrentSecurityState* state);
00122
00141 EmberStatus emberGetKey(EmberKeyType type,
00142
EmberKeyStruct* keyStruct);
00143
00144
00151 boolean emberHaveLinkKey(EmberEUI64 remoteDevice);
00152
EmberZNet 4.7.2 API EM250
120-3016-000-4720
527
00153
00154
00155
00156
00157
00171
#ifndef DOXYGEN_SHOULD_SKIP_THIS
extern int8u emberKeyTableSize;
extern int32u* emIncomingApsFrameCounters;
#endif
EmberStatus emberGenerateRandomKey(
EmberKeyData* keyAddress);
00172
00180 void emberSwitchNetworkKeyHandler(int8u
sequenceNumber);
00181
00211 EmberStatus emberRequestLinkKey(EmberEUI64
partner);
00212
00222 void emberZigbeeKeyEstablishmentHandler(
EmberEUI64 partner, EmberKeyStatus status);
00223
00224
00241 EmberStatus emberGetKeyTableEntry(int8u
index,
00242
EmberKeyStruct* result);
00243
00255 #if defined DOXYGEN_SHOULD_SKIP_THIS
00256 EmberStatus emberSetKeyTableEntry(int8u
index,
00257
EmberEUI64 address,
00258
boolean linkKey,
00259
EmberKeyData* keyData);
00260 #else
00261 EmberStatus emSetKeyTableEntry(boolean erase,
00262
int8u index,
00263
EmberEUI64 address,
00264
boolean linkKey,
00265
EmberKeyData* keyData);
00266 #define emberSetKeyTableEntry(index, address, linkKey, keyData) \
00267
emSetKeyTableEntry(FALSE, index, address, linkKey, keyData)
00268 #endif
00269
00292 EmberStatus emberAddOrUpdateKeyTableEntry
(EmberEUI64 address,
00293
boolean linkKey,
00294
EmberKeyData* keyData);
00295
00307 int8u emberFindKeyTableEntry(EmberEUI64
address,
00308
boolean linkKey);
00309
00318 #if defined DOXYGEN_SHOULD_SKIP_THIS
00319 EmberStatus emberEraseKeyTableEntry(int8u
index);
00320 #else
00321 #define emberEraseKeyTableEntry(index) \
00322
emSetKeyTableEntry(TRUE, (index), NULL, FALSE, NULL)
00323 #endif
00324
00325
00332 EmberStatus emberClearKeyTable(void);
00333
00348 EmberStatus emberStopWritingStackTokens(
void);
00349
00359 EmberStatus emberStartWritingStackTokens
(void);
00360
00369 boolean emberWritingStackTokensEnabled(void);
00370
00398 EmberStatus emberApsCryptMessage(boolean encrypt
,
00399
EmberMessageBuffer buffer,
00400
int8u apsHeaderEndIndex,
00401
EmberEUI64 remoteEui64);
00402
00403
00414 EmberStatus emberGetMfgSecurityConfig(
EmberMfgSecurityStruct* settings);
00415
00416
00461 EmberStatus emberSetMfgSecurityConfig(
int32u magicNumber,
00462
const EmberMfgSecurityStruct
EmberZNet 4.7.2 API EM250
120-3016-000-4720
528
* settings);
00463
00464
00465
00466 // @} END addtogroup
00467
8.95
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 higherlevel serial code uses these functions, so they should not be called directly. The HAL should also implement
the appropriate interrupt handlers to drain the TX queues and fill the RX FIFO queue.
•
•
•
•
•
•
•
•
#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)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
529
•
•
•
•
•
•
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)
8.95.1
Detailed Description
Serial hardware abstraction layer interfaces. See Serial UART Communication for documentation.
Definition in file hal/micro/serial.h.
8.96
00001
00023
00024
00025
00026
00027
00028
00029
00030
00031
00032
00033
00034
00035
00036
00037
00038
00039
00040
00041
00042
00055
00056
00057
00058
00059
00061
00062
00063
00064
00065
00066
hal/micro/serial.h
#ifndef __HAL_SERIAL_H__
#define __HAL_SERIAL_H__
// EM_NUM_SERIAL_PORTS is inherited from the
#if (EM_NUM_SERIAL_PORTS == 1)
#define FOR_EACH_PORT(cast,prefix,suffix)
cast(prefix##0##suffix)
#elif (EM_NUM_SERIAL_PORTS == 2)
#define FOR_EACH_PORT(cast,prefix,suffix)
cast(prefix##0##suffix),
cast(prefix##1##suffix)
#elif (EM_NUM_SERIAL_PORTS == 3)
#define FOR_EACH_PORT(cast,prefix,suffix)
cast(prefix##0##suffix),
\
cast(prefix##1##suffix),
\
cast(prefix##2##suffix)
#else
#error unsupported number of serial ports
#endif
#define
#define
#define
#define
micro specifc micro.h
\
\
\
\
EMBER_SERIAL_UNUSED 0
EMBER_SERIAL_FIFO
1
EMBER_SERIAL_BUFFER 2
EMBER_SERIAL_LOWLEVEL 3
#ifndef DOXYGEN_SHOULD_SKIP_THIS
// The following tests for setting of an invalid mode
#ifdef EMBER_SERIAL0_MODE
#if (EMBER_SERIAL0_MODE != EMBER_SERIAL_FIFO)
&& \
(EMBER_SERIAL0_MODE != EMBER_SERIAL_BUFFER) && \
EmberZNet 4.7.2 API EM250
120-3016-000-4720
530
00067
00068
00069
00070
00071
00072
00073
00074
00075
00076
00077
00078
00079
00080
00081
00082
00083
00084
00085
00086
00087
00088
00089
00090
00091
00092
00093
00094
00095
00096
00097
00098
00099
00100
00101
00102
00103
00104
00105
00106
00107
00108
00116
00118
00120
00122
00124
00125
00126
00127
00131
00133
00135
00137
00138
00139
00143
00145
00147
00149
00151
00154
00156
00158
00160
00161
00162
00172
00174
00176
00178
00180
00182
00184
00186
00187
00188
00189
00190
00191
(EMBER_SERIAL0_MODE != EMBER_SERIAL_LOWLEVEL) && \
(EMBER_SERIAL0_MODE != EMBER_SERIAL_UNUSED)
#error Invalid Serial 0 Mode
#endif
#else
#define EMBER_SERIAL0_MODE EMBER_SERIAL_UNUSED
#endif
#ifdef EMBER_SERIAL1_MODE
#if (EMBER_SERIAL1_MODE != EMBER_SERIAL_FIFO)
&& \
(EMBER_SERIAL1_MODE != EMBER_SERIAL_BUFFER) && \
(EMBER_SERIAL1_MODE != EMBER_SERIAL_LOWLEVEL) && \
(EMBER_SERIAL1_MODE != EMBER_SERIAL_UNUSED)
#error Invalid Serial 1 Mode
#endif
#else
#define EMBER_SERIAL1_MODE EMBER_SERIAL_UNUSED
#endif
#ifdef EMBER_SERIAL2_MODE
#if (EMBER_SERIAL2_MODE != EMBER_SERIAL_FIFO)
&& \
(EMBER_SERIAL2_MODE != EMBER_SERIAL_BUFFER) && \
(EMBER_SERIAL2_MODE != EMBER_SERIAL_LOWLEVEL) && \
(EMBER_SERIAL2_MODE != EMBER_SERIAL_UNUSED)
#error Invalid Serial 2 Mode
#endif
#else
#define EMBER_SERIAL2_MODE EMBER_SERIAL_UNUSED
#endif
// Determine if FIFO and/or Buffer modes are being used, so those sections of
// code may be disabled if not
#if (EMBER_SERIAL0_MODE == EMBER_SERIAL_FIFO) || \
(EMBER_SERIAL1_MODE == EMBER_SERIAL_FIFO) || \
(EMBER_SERIAL2_MODE == EMBER_SERIAL_FIFO)
#define EM_ENABLE_SERIAL_FIFO
#endif
#if (EMBER_SERIAL0_MODE == EMBER_SERIAL_BUFFER) || \
(EMBER_SERIAL1_MODE == EMBER_SERIAL_BUFFER) || \
(EMBER_SERIAL2_MODE == EMBER_SERIAL_BUFFER)
#define EM_ENABLE_SERIAL_BUFFER
#endif
typedef struct {
int16u head;
int16u tail;
volatile int16u used;
int8u fifo[];
} EmSerialFifoQueue;
typedef struct {
int8u length;
EmberMessageBuffer buffer;
int8u startIndex;
} EmSerialBufferQueueEntry;
typedef struct {
int8u head;
int8u tail;
volatile int8u used;
volatile int8u dead;
EmberMessageBuffer currentBuffer;
int8u *nextByte;
int8u *lastByte;
EmSerialBufferQueueEntry fifo[];
} EmSerialBufferQueue;
extern
extern
extern
extern
extern
extern
extern
extern
void *emSerialTxQueues[EM_NUM_SERIAL_PORTS];
EmSerialFifoQueue *emSerialRxQueues[EM_NUM_SERIAL_PORTS];
int16u PGM emSerialTxQueueMasks[EM_NUM_SERIAL_PORTS];
int16u PGM emSerialTxQueueSizes[EM_NUM_SERIAL_PORTS];
int16u PGM emSerialRxQueueSizes[EM_NUM_SERIAL_PORTS];
int8u emSerialRxError[EM_NUM_SERIAL_PORTS];
int16u emSerialRxErrorIndex[EM_NUM_SERIAL_PORTS];
int8u PGM emSerialPortModes[EM_NUM_SERIAL_PORTS];
//Compatibility code for the AVR Atmega
#ifdef AVR_ATMEGA
extern int8u PGM emSerialTxQueueWraps[EM_NUM_SERIAL_PORTS];
extern int8u PGM emSerialRxQueueWraps[EM_NUM_SERIAL_PORTS];
EmberZNet 4.7.2 API EM250
120-3016-000-4720
531
00192
00193
00194
00195
00196
00199
00200
00201
00202
00203
00204
00205
00206
00207
00224
00225
00226
00227
00228
00229
00230
00231
00232
00233
00234
00235
00236
00237
00238
00239
00240
00248
00249
00250
00251
00252
00253
00254
00255
00256
00257
00258
00259
00260
00264
00265
00269
00270
00271
00272
00273
00274
00275
00276
00277
00278
00279
00280
00281
00282
00283
00284
00285
00286
00287
00288
00289
00290
00291
00292
00293
00294
00295
00296
00297
#else
extern int16u PGM emSerialTxQueueWraps[EM_NUM_SERIAL_PORTS];
extern int16u PGM emSerialRxQueueWraps[EM_NUM_SERIAL_PORTS];
#endif
#ifdef EZSP_UART
#define HANDLE_ASH_ERROR(type) emberCounterHandler(type, 0)
#else
#define HANDLE_ASH_ERROR(type)
#endif
#endif //DOXYGEN_SHOULD_SKIP_THIS
//Compatibility code for the AVR Atmega
#ifdef AVR_ATMEGA
#define FIFO_ENQUEUE(queue,data,size) \
do {
\
queue->fifo[queue->head] = data;
\
queue->head = ((queue->head + 1) & size);
queue->used++;
\
} while(0)
#else
#define FIFO_ENQUEUE(queue,data,size) \
do {
\
queue->fifo[queue->head] = data;
\
queue->head = ((queue->head + 1) % size);
queue->used++;
\
} while(0)
#endif
//Compatibility code for the AVR Atmega
#ifdef AVR_ATMEGA
#define FIFO_DEQUEUE(queue,size) \
queue->fifo[queue->tail];
\
queue->tail = ((queue->tail + 1) & size);
queue->used-#else
#define FIFO_DEQUEUE(queue,size) \
queue->fifo[queue->tail];
\
queue->tail = ((queue->tail + 1) % size);
queue->used-#endif
\
\
\
\
#ifdef DOXYGEN_SHOULD_SKIP_THIS
enum SerialBaudRate
#else
#ifndef DEFINE_BAUD
#define DEFINE_BAUD(num) BAUD_##num
#endif
typedef int8u SerialBaudRate;
enum
#endif //DOXYGEN_SHOULD_SKIP_THIS
{
DEFINE_BAUD(300) = 0, // BAUD_300
DEFINE_BAUD(600) = 1, // BAUD_600
DEFINE_BAUD(900) = 2, // etc...
DEFINE_BAUD(1200) = 3,
DEFINE_BAUD(2400) = 4,
DEFINE_BAUD(4800) = 5,
DEFINE_BAUD(9600) = 6,
DEFINE_BAUD(14400) = 7,
DEFINE_BAUD(19200) = 8,
DEFINE_BAUD(28800) = 9,
DEFINE_BAUD(38400) = 10,
DEFINE_BAUD(50000) = 11,
DEFINE_BAUD(57600) = 12,
DEFINE_BAUD(76800) = 13,
DEFINE_BAUD(100000) = 14,
DEFINE_BAUD(115200) = 15,
#ifdef AVR_ATMEGA
DEFINE_BAUD(CUSTOM) = 16
#else
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 */
EmberZNet 4.7.2 API EM250
120-3016-000-4720
532
00300
00301
00302
00303
00304
00305
00309
00310
00311
00312
00313
00314
00315
00316
00317
00318
00319
00320
00321
00322
00348
00349
00350
00351
00352
00357
00358
00363
00364
00371
00372
00373
00379
00380
00381
00393
#endif
};
#ifdef DOXYGEN_SHOULD_SKIP_THIS
enum NameOfType
#else
#ifndef DEFINE_PARITY
#define DEFINE_PARITY(val) PARITY_##val
#endif
typedef int8u SerialParity;
enum
#endif //DOXYGEN_SHOULD_SKIP_THIS
{
DEFINE_PARITY(NONE) = 0, // PARITY_NONE
DEFINE_PARITY(ODD) = 1,
// PARITY_ODD
DEFINE_PARITY(EVEN) = 2
// PARITY_EVEN
};
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);
00394
00403 EmberStatus halInternalForceReadUartByte
(int8u port, int8u *dataByte);
00404
00410 void halInternalWaitUartTxComplete(int8u port
);
00411
00419 #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 #else
00424 #define halInternalUartFlowControl(port) do {} while(FALSE)
00425 #endif
00426
00434 #if (defined(XAP2B)&&(EMBER_SERIAL1_MODE == EMBER_SERIAL_BUFFER)) ||
defined(CORTEXM3)
00435 void halInternalUartRxPump(int8u port);
00436 #else
00437 #define halInternalUartRxPump(port) do {} while(FALSE)
00438 #endif
00439
00445 void halInternalRestartUart(void);
00446
00452 boolean halInternalUart1FlowControlRxIsEnabled
(void);
00453
00458 boolean halInternalUart1XonRefreshDone(void);
00459
00464 boolean halInternalUart1TxIsIdle(void);
00465
00481 void emSerialBufferNextMessageIsr(
EmSerialBufferQueue *q);
00482
00483
00493 void emSerialBufferNextBlockIsr(EmSerialBufferQueue *
q, int8u port);
00494
00511 void halStackReceiveVuartMessage(int8u* data,
int8u length);
00512
00515 #endif //__HAL_SERIAL_H__
00516
EmberZNet 4.7.2 API EM250
120-3016-000-4720
533
8.97
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 ∗bytesRead, 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 formatString,...)
void emberSerialBufferTick (void)
void emberSerialFlushRx (int8u port)
Printf Prototypes
These prototypes are for the internal printf implementation, in case it is desired to use it elsewhere. See the
code 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)
8.97.1
Detailed Description
High-level serial communication functions. See Serial Communication for documentation.
Definition in file app/util/serial/serial.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
534
8.98
00001
00012
00013
00014
00015
00016
00017
00018
00019
00020
00021
00022
00023
00024
00025
00026
00136
00137
00138
00139
00140
00148
00149
00167
app/util/serial/serial.h
#ifndef __SERIAL_H__
#define __SERIAL_H__
#ifndef __HAL_H__
#error hal/hal.h should be included first
#endif
#ifndef DOXYGEN_SHOULD_SKIP_THIS
#include <stdarg.h>
//Rx FIFO Full indicator
#define RX_FIFO_FULL (0xFFFF)
#endif // DOXYGEN_SHOULD_SKIP_THIS
EmberStatus emberSerialInit(int8u port,
SerialBaudRate rate,
SerialParity parity,
int8u stopBits);
int16u emberSerialReadAvailable(int8u port);
EmberStatus emberSerialReadByte(int8u port,
int8u *dataByte);
00168
00193 EmberStatus emberSerialReadData(int8u port,
00194
int8u *data,
00195
int16u length,
00196
int16u *bytesRead);
00197
00232 EmberStatus emberSerialReadDataTimeout(
int8u port,
00233
int8u *data,
00234
int16u length,
00235
int16u *bytesRead,
00236
int16u firstByteTimeout,
00237
int16u subsequentByteTimeout);
00238
00253 EmberStatus emberSerialReadLine(int8u port,
char *data, int8u max);
00254
00278 EmberStatus emberSerialReadPartialLine(
int8u port, char *data, int8u max, int8u *index);
00279
00288 int16u emberSerialWriteAvailable(int8u port
);
00289
00297 #define emberSerialWriteUsed(port) \
00298
(emSerialTxQueueSizes[port] - emberSerialWriteAvailable(port))
00299
00313 EmberStatus emberSerialWriteByte(int8u port
, int8u dataByte);
00314
00329 EmberStatus emberSerialWriteHex(int8u port,
int8u dataByte);
00330
00343 EmberStatus emberSerialWriteString(int8u
port, PGM_P string);
00344
00369 XAP2B_PAGEZERO_ON
00370 EmberStatus emberSerialPrintf(int8u port,
PGM_P formatString, ...);
00371 XAP2B_PAGEZERO_OFF
00372
00388 XAP2B_PAGEZERO_ON
00389 EmberStatus emberSerialPrintfLine(int8u
port, PGM_P formatString, ...);
00390 XAP2B_PAGEZERO_OFF
00391
00402 XAP2B_PAGEZERO_ON
00403 EmberStatus emberSerialPrintCarriageReturn
(int8u port);
00404 XAP2B_PAGEZERO_OFF
00405
00406
00419 EmberStatus emberSerialPrintfVarArg(int8u
EmberZNet 4.7.2 API EM250
120-3016-000-4720
535
port, PGM_P formatString, va_list ap);
00420
00436 EmberStatus emberSerialWriteData(int8u port
, int8u *data, int8u length);
00437
00438 //Host HALs do not use stack buffers.
00439 #ifndef HAL_HOST
00440
00458 EmberStatus emberSerialWriteBuffer(int8u
port, EmberMessageBuffer buffer, int8u start, int8u
length);
00459 #endif //HAL_HOST
00460
00473 XAP2B_PAGEZERO_ON
00474 EmberStatus emberSerialWaitSend(int8u port);
00475 XAP2B_PAGEZERO_OFF
00476
00497 EmberStatus emberSerialGuaranteedPrintf(
int8u port, PGM_P formatString, ...);
00498
00504 void emberSerialBufferTick(void);
00505
00511 void emberSerialFlushRx(int8u port);
00512
00513
00514
00515
00536 typedef EmberStatus (emPrintfFlushHandler)(int8u
flushVar,
00537
int8u *contents,
00538
int8u length);
00539
00540
00558 int8u emPrintfInternal(emPrintfFlushHandler
flushHandler,
00559
int8u port,
00560
PGM_P string,
00561
va_list args);
00562
00563
00568 #endif // __SERIAL_H__
00569
8.99
sim-eeprom.h File Reference
Functions
• void halSimEepromCallback (EmberStatus status)
• void halSimEepromErasePage (void)
• void halSimEepromStatus (int16u ∗freeWordsInCurrPage, int16u ∗totalPageUseCount)
8.99.1
Detailed Description
Simulated EEPROM system for wear leveling token storage across flash. See Simulated EEPROM for
documentation.
Definition in file sim-eeprom.h.
8.100
sim-eeprom.h
00001
00007 #ifndef __SIM_EEPROM_H__
00008 #define __SIM_EEPROM_H__
00009
00010
EmberZNet 4.7.2 API EM250
120-3016-000-4720
536
00011
00012
00013
00014
00015
00016
00017
00018
00019
00064
00065
00066
00067
00068
00069
00070
00071
00072
00073
00074
00075
00123
00124
00147
00148
00167
00168
00169
00170
00171
00172
00173
00174
00199
00200
00201
00202
00203
00204
00232
00233
00234
00235
00236
00277
00278
00279
00280
00281
00307
00308
00339
00340
00341
00342
00343
00344
00345
00346
00347
00348
00349
//pull in the platform specific information here
#if defined(XAP2B)
#include "xap2b/sim-eeprom.h"
#elif defined(CORTEXM3) || defined(EMBER_TEST)
#include "cortexm3/sim-eeprom.h"
#else
#error invalid sim-eeprom platform
#endif
#ifndef DOXYGEN_SHOULD_SKIP_THIS
//Prototype for internal Startup for the public Init and Repair macros
EmberStatus halInternalSimEeStartup(boolean forceRebuildAll);
//Properly round values when converting bytes to words
#define BYTES_TO_WORDS(x) (((x) + 1) / 2)
#endif
//application functions
void halSimEepromCallback(EmberStatus status);
void halSimEepromErasePage(void);
void halSimEepromStatus(int16u *freeWordsInCurrPage,
int16u *totalPageUseCount);
#ifndef DOXYGEN_SHOULD_SKIP_THIS
//NOTE: halInternal functions must not be called directly.
#ifdef DOXYGEN_SHOULD_SKIP_THIS
EmberStatus halInternalSimEeInit(void);
#else
#define halInternalSimEeInit() (halInternalSimEeStartup(FALSE))
#endif
void halInternalSimEeGetData(void *vdata,
int8u compileId,
int8u index,
int8u len);
void halInternalSimEeSetData(int8u compileId,
void *vdata,
int8u index,
int8u len);
void halInternalSimEeIncrementCounter(int8u compileId);
#ifdef DOXYGEN_SHOULD_SKIP_THIS
EmberStatus halInternalSimEeRepair(boolean forceRebuildAll);
#else
#define halInternalSimEeRepair(rebuild) (halInternalSimEeStartup(rebuild))
#endif
#endif //DOXYGEN_SHOULD_SKIP_THIS
#endif //__SIM_EEPROM_H__
8.101
spi-protocol.h File Reference
#include "app/util/ezsp/ezsp-enum.h"
SPI Protocol Interface
• int8u ∗ halNcpFrame
EmberZNet 4.7.2 API EM250
120-3016-000-4720
537
•
•
•
•
•
•
•
•
•
•
•
•
•
•
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)
8.101.1
Detailed Description
Example AVR SPI Protocol implementation for interfacing with EM260. See SPI Access for documentation.
Definition in file spi-protocol.h.
8.102
00001
00020
00021
00022
00023
00024
00029
00030
00038
00039
00047
00048
00052
00053
00058
00059
00063
00064
00077
00078
00093
00094
00104
00105
00117
00118
00130
00131
00140
00141
00149
00150
spi-protocol.h
#ifndef __SPI_PROTOCOL_H__
#define __SPI_PROTOCOL_H__
#include "app/util/ezsp/ezsp-enum.h"
extern int8u *halNcpFrame;
extern 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);
EmberZNet 4.7.2 API EM250
120-3016-000-4720
538
00155
00156
00157
00165
00166
00174
00175
00177
00182
00183
00203
00204
00206
00207
00208
boolean halNcpHasData(void);
boolean halNcpVerifySpiProtocolVersion(void);
boolean halNcpVerifySpiProtocolActive(void);
void spipTest(int16u test, int16u params);
#endif // __SPI_PROTOCOL_H__
8.103
spi.h File Reference
Functions
•
•
•
•
void halCommonInitSpi (void)
void halCommonSpiWrite (int8u data)
int8u halCommonSpiRead (void)
int8u halCommonSpiReadWrite (int8u data)
8.103.1
Detailed Description
Generic SPI manipulation routines. See SPI Access for documentation.
Definition in file spi.h.
8.104
00001
00026
00027
00028
00033
00034
00040
00041
00047
00048
00056
00057
00058
00059
spi.h
#ifndef __SPI_H__
#define __SPI_H__
void halCommonInitSpi(void);
void halCommonSpiWrite(int8u data);
int8u halCommonSpiRead(void);
int8u halCommonSpiReadWrite(int8u data);
#endif //__SPI_H__
8.105
stack-info.h File Reference
Data Structures
• struct EmberEndpointDescription
Endpoint information (a ZigBee Simple Descriptor).
• struct EmberEndpoint
Gives the endpoint information for a particular endpoint.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
539
Functions
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
void emberStackStatusHandler (EmberStatus status)
EmberNetworkStatus emberNetworkState (void)
boolean emberStackIsUp (void)
EmberEUI64 emberGetEui64 (void)
boolean emberIsLocalEui64 (EmberEUI64 eui64)
EmberNodeId emberGetNodeId (void)
EmberNodeId emberRadioGetNodeId (void)
void emberSetManufacturerCode (int16u code)
void emberSetPowerDescriptor (int16u descriptor)
void emberSetMaximumIncomingTransferSize (int16u size)
void emberSetMaximumOutgoingTransferSize (int16u size)
void emberSetDescriptorCapability (int8u capability)
EmberStatus emberGetNetworkParameters (EmberNetworkParameters ∗parameters)
EmberStatus emberGetNodeType (EmberNodeType ∗resultLocation)
EmberStatus emberSetRadioChannel (int8u channel)
int8u emberGetRadioChannel (void)
EmberStatus emberSetRadioPower (int8s power)
int8s emberGetRadioPower (void)
EmberPanId emberGetPanId (void)
EmberPanId emberRadioGetPanId (void)
void emberGetExtendedPanId (int8u ∗resultLocation)
int8u emberGetEndpoint (int8u index)
boolean emberGetEndpointDescription (int8u endpoint, EmberEndpointDescription ∗result)
int16u emberGetEndpointCluster (int8u endpoint, EmberClusterListId listId, int8u listIndex)
boolean emberIsNodeIdValid (EmberNodeId nodeId)
EmberNodeId emberLookupNodeIdByEui64 (EmberEUI64 eui64)
EmberStatus emberLookupEui64ByNodeId (EmberNodeId nodeId, EmberEUI64 eui64Return)
void emberCounterHandler (EmberCounterType type, int8u data)
EmberStatus emberGetNeighbor (int8u index, EmberNeighborTableEntry ∗result)
EmberStatus emberGetRouteTableEntry (int8u index, EmberRouteTableEntry ∗result)
int8u emberStackProfile (void)
int8u emberTreeDepth (void)
int8u emberNeighborCount (void)
int8u emberRouteTableSize (void)
int8u emberNextZigbeeSequenceNumber (void)
Variables
• PGM int8u emberStackProfileId [ ]
• int8u emberEndpointCount
• EmberEndpoint emberEndpoints [ ]
Radio-specific Functions
•
•
•
•
•
EmberStatus emberSetTxPowerMode (int16u txPowerMode)
int16u emberGetTxPowerMode (void)
EmberStatus emberSetNodeId (EmberNodeId nodeId)
void emberRadioNeedsCalibratingHandler (void)
void emberCalibrateCurrentChannel (void)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
540
General Functions
•
•
•
•
•
•
•
void emberReverseMemCopy (int8u ∗dest, const int8u ∗src, int8u length)
XAP2B_PAGEZERO_ON int16u emberFetchLowHighInt16u (int8u ∗contents)
XAP2B_PAGEZERO_OFF void emberStoreLowHighInt16u (int8u ∗contents, int16u value)
int32u emberFetchLowHighInt32u (int8u ∗contents)
int32u emberFetchHighLowInt32u (int8u ∗contents)
void emberStoreLowHighInt32u (int8u ∗contents, int32u value)
void emberStoreHighLowInt32u (int8u ∗contents, int32u value)
8.105.1
Detailed Description
EmberZNet API for accessing and setting stack information. See Stack Information for documentation.
Definition in file stack-info.h.
8.106
stack-info.h
00001
00051 void emberStackStatusHandler(EmberStatus
status);
00052
00060 EmberNetworkStatus emberNetworkState(void);
00061
00071 boolean emberStackIsUp(void);
00072
00073 #ifdef DOXYGEN_SHOULD_SKIP_THIS
00074
00078 EmberEUI64 emberGetEui64(void);
00079
00086 boolean emberIsLocalEui64(EmberEUI64 eui64);
00087
00093 EmberNodeId emberGetNodeId(void);
00094
00100 EmberNodeId emberRadioGetNodeId(void);
00101
00107 void emberSetManufacturerCode(int16u code);
00108
00115 void emberSetPowerDescriptor(int16u descriptor);
00116
00123 void emberSetMaximumIncomingTransferSize(
int16u size);
00124
00131 void emberSetMaximumOutgoingTransferSize(
int16u size);
00132
00137 void emberSetDescriptorCapability(int8u
capability);
00138
00139
00140 #else
// Doxygen ignores the following
00141 extern EmberEUI64 emLocalEui64;
00142 #define emberGetEui64() (emLocalEui64)
00143 #define emberIsLocalEui64(eui64)
00144 (MEMCOMPARE((eui64), emLocalEui64, EUI64_SIZE) == 0)
00145
00146 XAP2B_PAGEZERO_ON
00147 EmberNodeId emberGetNodeId(void);
00148 EmberNodeId emberRadioGetNodeId(void);
00149 XAP2B_PAGEZERO_OFF
00150
00151 extern int16u emManufacturerCode;
00152 extern int16u emPowerDescriptor;
00153 extern int16u emMaximumIncomingTransferSize;
00154 extern int16u emMaximumOutgoingTransferSize;
00155 extern int8u emDescriptorCapability;
00156 #define emberSetManufacturerCode(code)
00157 (emManufacturerCode = (code))
EmberZNet 4.7.2 API EM250
120-3016-000-4720
\
\
541
00158
00159
00160
00161
00162
00163
00164
00165
00166
00167
00177
#define emberSetPowerDescriptor(descriptor)
(emPowerDescriptor = (descriptor))
#define emberSetMaximumIncomingTransferSize(size)
(emMaximumIncomingTransferSize = (size))
#define emberSetMaximumOutgoingTransferSize(size)
(emMaximumOutgoingTransferSize = (size))
#define emberSetDescriptorCapability(capability)
(emDescriptorCapability = (capability))
#endif
\
\
\
\
EmberStatus emberGetNetworkParameters(
EmberNetworkParameters *parameters);
00178
00188 EmberStatus emberGetNodeType(EmberNodeType
*resultLocation);
00189
00203 EmberStatus emberSetRadioChannel(int8u
channel);
00204
00212 int8u emberGetRadioChannel(void);
00213
00231 EmberStatus emberSetRadioPower(int8s power);
00232
00240 int8s emberGetRadioPower(void);
00241
00246 EmberPanId emberGetPanId(void);
00247
00252 EmberPanId emberRadioGetPanId(void);
00253
00255 void emberGetExtendedPanId(int8u *resultLocation);
00256
00258 extern PGM int8u emberStackProfileId[];
00259
00267 typedef struct {
00269
int16u profileId;
00271
int16u deviceId;
00273
int8u deviceVersion;
00275
int8u inputClusterCount;
00277
int8u outputClusterCount;
00278 } EmberEndpointDescription;
00279
00283 typedef struct {
00285
int8u endpoint;
00287
EmberEndpointDescription PGM * description
;
00289
int16u PGM * inputClusterList;
00291
int16u PGM * outputClusterList;
00292 } EmberEndpoint;
00293
00295 extern int8u emberEndpointCount;
00296
00310 extern EmberEndpoint emberEndpoints[];
00311
00325 int8u emberGetEndpoint(int8u index);
00326
00342 boolean emberGetEndpointDescription(int8u
endpoint,
00343
EmberEndpointDescription
*result);
00344
00363 int16u emberGetEndpointCluster(int8u endpoint
,
00364
EmberClusterListId listId,
00365
int8u listIndex);
00366
00373 #ifdef DOXYGEN_SHOULD_SKIP_THIS
00374 boolean emberIsNodeIdValid(EmberNodeId nodeId);
00375 #else
00376 #define emberIsNodeIdValid(nodeId) ((nodeId) < EMBER_DISCOVERY_ACTIVE_NODE_ID)
00377 #endif
00378
00388 EmberNodeId emberLookupNodeIdByEui64(
EmberEUI64 eui64);
00389
00402 EmberStatus emberLookupEui64ByNodeId(
EmberNodeId nodeId,
00403
EmberEUI64 eui64Return);
00404
00418 void emberCounterHandler(EmberCounterType
type, int8u data);
EmberZNet 4.7.2 API EM250
120-3016-000-4720
542
00419
00435 EmberStatus emberGetNeighbor(int8u index,
EmberNeighborTableEntry *result);
00436
00450 EmberStatus emberGetRouteTableEntry(int8u
index, EmberRouteTableEntry *result);
00451
00452 #ifdef DOXYGEN_SHOULD_SKIP_THIS
00453
00458 int8u emberStackProfile(void);
00459
00464 int8u emberTreeDepth(void);
00465 #endif
00466
00470 int8u emberNeighborCount(void);
00471 #ifdef DOXYGEN_SHOULD_SKIP_THIS
00472
00476 int8u emberRouteTableSize(void);
00477
00478 #else
// Doxgyen ignores the following
00479 // The ’+ 0’ prevents anyone from accidentally assigning to these.
00480 #define emberStackProfile()
(emStackProfile
+ 0)
00481 #define emberTreeDepth()
(emTreeDepth
+ 0)
00482 #define emberMaxDepth()
(emMaxDepth
+ 0)
00483 #define emberRouteTableSize()
(emRouteTableSize
+ 0)
00484
00485 extern int8u emStackProfile;
00486 extern int8u emDefaultSecurityLevel;
00487 extern int8u emMaxHops;
00488 extern int8u emRouteTableSize;
00489 extern int8u emMaxDepth;
// maximum tree depth
00490 extern int8u emTreeDepth;
// our depth
00491
00492 // This was originally a #define declared here. I moved
00493 // emZigbeeNetworkSecurityLevel to the networkInfo struct.This function is now
00494 // defined in ember-stack-common.c
00495 int8u emberSecurityLevel(void);
00496 // New function (defined in ember-stack-common.c)
00497 void emberSetSecurityLevel(int8u securityLevel);
00498 #endif
00499
00504 int8u emberNextZigbeeSequenceNumber(void);
00505
00508
00542 EmberStatus emberSetTxPowerMode(int16u
txPowerMode);
00543
00549 int16u emberGetTxPowerMode(void);
00550
00558 EmberStatus emberSetNodeId(EmberNodeId
nodeId);
00559
00560
00577 void emberRadioNeedsCalibratingHandler(void);
00578
00587 void emberCalibrateCurrentChannel(void);
00589
00590
00593
00601 void emberReverseMemCopy(int8u* dest, const int8u*
src, int8u length);
00602
00603
00607 XAP2B_PAGEZERO_ON
00608 int16u emberFetchLowHighInt16u(int8u *
contents);
00609 XAP2B_PAGEZERO_OFF
00610
00614 void emberStoreLowHighInt16u(int8u *contents,
int16u value);
00615
00616 #if !defined DOXYGEN_SHOULD_SKIP_THIS
00617 int32u emFetchInt32u(boolean lowHigh, int8u* contents);
00618 #endif
00619
00624 #if defined DOXYGEN_SHOULD_SKIP_THIS
00625 int32u emberFetchLowHighInt32u(int8u *
contents);
00626 #else
00627 #define emberFetchLowHighInt32u(contents) \
EmberZNet 4.7.2 API EM250
120-3016-000-4720
543
00628
(emFetchInt32u(TRUE, contents))
00629 #endif
00630
00635 #if defined DOXYGEN_SHOULD_SKIP_THIS
00636 int32u emberFetchHighLowInt32u(int8u *
contents);
00637 #else
00638 #define emberFetchHighLowInt32u(contents) \
00639
(emFetchInt32u(FALSE, contents))
00640 #endif
00641
00642
00643
00644 #if !defined DOXYGEN_SHOULD_SKIP_THIS
00645 void emStoreInt32u(boolean lowHigh, int8u* contents, int32u value);
00646 #endif
00647
00651 #if defined DOXYGEN_SHOULD_SKIP_THIS
00652 void emberStoreLowHighInt32u(int8u *contents,
int32u value);
00653 #else
00654 #define emberStoreLowHighInt32u(contents, value) \
00655
(emStoreInt32u(TRUE, contents, value))
00656 #endif
00657
00661 #if defined DOXYGEN_SHOULD_SKIP_THIS
00662 void emberStoreHighLowInt32u(int8u *contents,
int32u value);
00663 #else
00664 #define emberStoreHighLowInt32u(contents, value) \
00665
(emStoreInt32u(FALSE, contents, value))
00666 #endif
00667
8.107
symbol-timer.h File Reference
Symbol Timer Functions
• void halInternalStartSymbolTimer (void)
• void halInternalSfdCaptureIsr (void)
• int32u halStackGetInt32uSymbolTick (void)
MAC Timer Support Functions
These functions are used for MAC layer timing.
Applications should not directly call these functions. They are used internally by the operation of the stack.
•
•
•
•
void halStackOrderInt16uSymbolDelayA (int16u symbols)
void halStackOrderNextSymbolDelayA (int16u symbols)
void halStackCancelSymbolDelayA (void)
void halStackSymbolDelayAIsr (void)
8.107.1
Detailed Description
Functions that provide access to symbol time. One symbol period is 16 microseconds. See Symbol Timer
Control for documentation.
Definition in file symbol-timer.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
544
8.108
00001
00017
00018
00019
00023
00030
00031
00035
00036
00042
00043
00054
00063
symbol-timer.h
#ifndef __SYMBOL_TIMER_H__
#define __SYMBOL_TIMER_H__
void halInternalStartSymbolTimer(void);
void halInternalSfdCaptureIsr(void);
int32u halStackGetInt32uSymbolTick(void);
void halStackOrderInt16uSymbolDelayA(int16u
symbols);
00064
00075 void halStackOrderNextSymbolDelayA(int16u
symbols);
00076
00079 void halStackCancelSymbolDelayA(void);
00080
00084 void halStackSymbolDelayAIsr(void);
00085
00088 #endif //__SYMBOL_TIMER_H__
00089
8.109
system-timer.h File Reference
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)
8.109.1
Detailed Description
See System Timer Control for documentation.
Definition in file system-timer.h.
8.110
00001
00031
00032
00033
00034
00035
00036
00037
system-timer.h
#ifndef __SYSTEM_TIMER_H__
#define __SYSTEM_TIMER_H__
#ifndef DOXYGEN_SHOULD_SKIP_THIS
#if defined( EMBER_TEST )
#include "unix/simulation/system-timer-sim.h"
EmberZNet 4.7.2 API EM250
120-3016-000-4720
545
00038
00039
00040
00041
00042
00043
00044
00045
00046
00053
00054
00055
00056
00057
00058
00059
00066
#elif defined(AVR_ATMEGA_32)
#include "avr-atmega/32/system-timer.h"
#elif defined(AVR_ATMEGA_128)
#include "avr-atmega/128/system-timer.h"
#endif
#endif // DOXYGEN_SHOULD_SKIP_THIS
int16u halInternalStartSystemTimer(void);
#ifndef DOXYGEN_SHOULD_SKIP_THIS
XAP2B_PAGEZERO_ON
#endif
int16u halCommonGetInt16uMillisecondTick
(void);
00067 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00068 XAP2B_PAGEZERO_OFF
00069 #endif
00070
00080 int32u halCommonGetInt32uMillisecondTick
(void);
00081
00091 int16u halCommonGetInt16uQuarterSecondTick
(void);
00092
00134 EmberStatus halSleepForQuarterSeconds(
int32u *duration);
00135
00177 EmberStatus halSleepForMilliseconds(int32u
*duration);
00178
00201 EmberStatus halCommonIdleForMilliseconds
(int32u *duration);
00202 // Maintain the previous API for backwards compatibility
00203 #define halIdleForMilliseconds(duration)
halCommonIdleForMilliseconds((duration))
00204
00205
00206 #endif //__SYSTEM_TIMER_H__
00207
8.111
token-manufacturing.h File Reference
Macros
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
#define CREATOR_MFG_CHIP_DATA
#define CREATOR_MFG_NVDATA_VERSION
#define CREATOR_MFG_EMBER_EUI_64
#define CREATOR_MFG_TRIM_DATA
#define CREATOR_MFG_CUSTOM_VERSION
#define CREATOR_MFG_CUSTOM_EUI_64
#define CREATOR_MFG_STRING
#define CREATOR_MFG_BOARD_NAME
#define CREATOR_MFG_OSC24M_BIAS_TRIM
#define CREATOR_MFG_EUI_64
#define CREATOR_MFG_MANUF_ID
#define CREATOR_MFG_PHY_CONFIG
#define CREATOR_MFG_BOOTLOAD_AES_KEY
#define CREATOR_MFG_EZSP_STORAGE
#define CREATOR_MFG_ASH_CONFIG
#define CREATOR_MFG_CBKE_DATA
#define CREATOR_MFG_INSTALLATION_CODE
EmberZNet 4.7.2 API EM250
120-3016-000-4720
546
• #define CREATOR_MFG_SYNTH_FREQ_OFFSET
• #define CURRENT_MFG_TOKEN_VERSION
• #define CURRENT_MFG_CUSTOM_VERSION
8.111.1
Detailed Description
Definitions for manufacturing tokens. This file should not be included directly. It is accessed by the other
token files.
Please see stack/config/token-stack.h and hal/micro/token.h for a full explanation of the tokens.
The tokens listed below are the manufacturing tokens. This token definitions file is included from the
master definitions file: stack/config/token-stack.h Please see that file for more details.
The user application can include its own manufacturing tokens in a header file similar to this one. The
macro ::APPLICATION_MFG_TOKEN_HEADER should be defined to equal the name of the header file
in which application manufacturing tokens are defined.
The macro DEFINE_MFG_TOKEN() should be used when instantiating a manufacturing token. Refer to
the list of ∗_LOCATION defines to see what memory is allocated and what memory is unused/available.
REMEMBER: By definition, manufacturing tokens exist at fixed addresses. Tokens should not overlap.
Here is a basic example of a manufacturing token header file:
#define CREATOR_MFG_EXAMPLE 0x4242
#ifdef DEFINETYPES
typedef int8u tokTypeMfgExample[8];
#endif //DEFINETYPES
#ifdef DEFINETOKENS
#define MFG_EXAMPLE_LOCATION 0x5198
DEFINE_MFG_TOKEN(MFG_EXAMPLE,
tokTypeMfgExample,
MFG_EXAMPLE_LOCATION,
{0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF})
#endif //DEFINETOKENS
Since this file contains both the typedefs and the token defs, there are two #defines used to select which
one is needed when this file is included. #define DEFINETYPES is used to select the type definitions and
#define DEFINETOKENS is used to select the token definitions. Refer to token.h and token.c to see how
these are used.
Definition in file token-manufacturing.h.
8.111.2
Macro Definition Documentation
8.111.2.1
#define CREATOR MFG CHIP DATA
Definition at line 67 of file token-manufacturing.h.
8.111.2.2
#define CREATOR MFG NVDATA VERSION
Definition at line 68 of file token-manufacturing.h.
8.111.2.3
#define CREATOR MFG EMBER EUI 64
Definition at line 69 of file token-manufacturing.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
547
8.111.2.4
#define CREATOR MFG TRIM DATA
Definition at line 70 of file token-manufacturing.h.
8.111.2.5
#define CREATOR MFG CUSTOM VERSION
Definition at line 71 of file token-manufacturing.h.
8.111.2.6
#define CREATOR MFG CUSTOM EUI 64
Definition at line 72 of file token-manufacturing.h.
8.111.2.7
#define CREATOR MFG STRING
Definition at line 73 of file token-manufacturing.h.
8.111.2.8
#define CREATOR MFG BOARD NAME
Definition at line 74 of file token-manufacturing.h.
8.111.2.9
#define CREATOR MFG OSC24M BIAS TRIM
Definition at line 75 of file token-manufacturing.h.
8.111.2.10
#define CREATOR MFG EUI 64
Definition at line 76 of file token-manufacturing.h.
8.111.2.11
#define CREATOR MFG MANUF ID
Definition at line 77 of file token-manufacturing.h.
8.111.2.12
#define CREATOR MFG PHY CONFIG
Definition at line 78 of file token-manufacturing.h.
8.111.2.13
#define CREATOR MFG BOOTLOAD AES KEY
Definition at line 79 of file token-manufacturing.h.
8.111.2.14
#define CREATOR MFG EZSP STORAGE
Definition at line 80 of file token-manufacturing.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
548
8.111.2.15
#define CREATOR MFG ASH CONFIG
Definition at line 81 of file token-manufacturing.h.
8.111.2.16
#define CREATOR MFG CBKE DATA
Definition at line 82 of file token-manufacturing.h.
8.111.2.17
#define CREATOR MFG INSTALLATION CODE
Definition at line 83 of file token-manufacturing.h.
8.111.2.18
#define CREATOR MFG SYNTH FREQ OFFSET
Definition at line 84 of file token-manufacturing.h.
8.111.2.19
#define CURRENT MFG TOKEN VERSION
Definition at line 87 of file token-manufacturing.h.
8.111.2.20
#define CURRENT MFG CUSTOM VERSION
Definition at line 88 of file token-manufacturing.h.
8.112
00001
00052
00053
00054
00055
00056
00057
00058
00059
00060
00061
00062
00063
00064
00065
00066
00067
00068
00069
00070
00071
00072
00073
00074
00075
00076
00077
00078
00079
00080
00081
00082
00083
00084
token-manufacturing.h
// MANUFACTURING DATA
// *the addresses of these tokens must not change*
// MANUFACTURING CREATORS
// The creator codes are here in one list instead of next to their token
// definitions so comparision of the codes is easier. The only requirement
// on these creator definitions is that they all must be unique. A favorite
// method for picking creator codes is to use two ASCII characters in order
// to make the codes more memorable. Also, the msb of Stack and Manufacturing
// token creator codes is always 1, while the msb of Application token creator
// codes is always 0. This distinction allows Application tokens
// to freely use the lower 15 bits for creator codes without the risk of
// duplicating a Stack or Manufacturing token creator code.
#define CREATOR_MFG_CHIP_DATA
0xC344 // msb+’C’+’D’ (Chip Data)
#define CREATOR_MFG_NVDATA_VERSION
0xFF09
#define CREATOR_MFG_EMBER_EUI_64
0xE545
#define CREATOR_MFG_TRIM_DATA
0xD444 // msb+’T’+’D’ (Trim Data)
#define CREATOR_MFG_CUSTOM_VERSION
0xC356 // msb+’C’+’V’ (Custom Version)
#define CREATOR_MFG_CUSTOM_EUI_64
0xE345 // msb+’c’+’E’ (_c_ustom Eui)
#define CREATOR_MFG_STRING
0xED73
#define CREATOR_MFG_BOARD_NAME
0xC24E // msb+’B’+’N’ (Board Name)
#define CREATOR_MFG_OSC24M_BIAS_TRIM 0xB254 // msb+’2’+’T’ (2[4mHz] Trim)
#define CREATOR_MFG_EUI_64
0xB634
#define CREATOR_MFG_MANUF_ID
0xC944 // msb+’I’+’D’ (Id)
#define CREATOR_MFG_PHY_CONFIG
0xD043 // msb+’P’+’C’ (Phy Config)
#define CREATOR_MFG_BOOTLOAD_AES_KEY 0xC24B // msb+’B’+’K’ (Bootloader Key)
#define CREATOR_MFG_EZSP_STORAGE
0xCD53
#define CREATOR_MFG_ASH_CONFIG
0xC143 // msb+’A’+’C’ (ASH Config)
#define CREATOR_MFG_CBKE_DATA
0xC342 // msb+’C’+’B’ (CBke)
#define CREATOR_MFG_INSTALLATION_CODE 0xC943 // msb+’I’+’C’ (Installation Code)
#define CREATOR_MFG_SYNTH_FREQ_OFFSET 0xD346 // msb+’S’+’F’ (Synth Freq)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
549
00085
00086 // The master defines indicating the verions number these definitions work
with.
00087 #define CURRENT_MFG_TOKEN_VERSION 0x01FE //MSB is version, LSB is complement
00088 #define CURRENT_MFG_CUSTOM_VERSION 0x01FE //MSB is version, LSB is complement
00089
00090
00091 #ifdef DEFINETYPES
00092 typedef int16u tokTypeMfgChipData[8];
00093 typedef int16u tokTypeMfgNvdataVersion;
00094 typedef int8u tokTypeMfgEmberEui64[8];
00095 typedef struct {
00096
int16u voltageCal;
00097
int16u masterBias;
00098
int16u prescalerSettings;
00099
int16u testProgramVersion;
00100
int16u adcVcoSettings;
00101
int16u checksum[2];
00102
int16u testLevelAndId;
00103
int16u data[4];
00104 } tokTypeMfgTrimData;
00105 typedef int16u tokTypeMfgCustomVersion;
00106 typedef int8u tokTypeMfgCustomEui64[8];
00107 typedef int8u tokTypeMfgString[16];
00108 typedef int8u tokTypeMfgBoardName[16];
00109 typedef int16u tokTypeMfgOsc24mBiasTrim;
00110 typedef int16u tokTypeMfgManufId;
00111 typedef int16u tokTypeMfgPhyConfig;
00112 typedef int8u tokTypeMfgBootloadAesKey[16];
00113 typedef int8u tokTypeMfgEui64[8];
00114 typedef int8u tokTypeMfgEzspStorage[8];
00115 typedef int16u tokTypeMfgAshConfig;
00116 typedef struct {
00117
int8u certificate[48];
00118
int8u caPublicKey[22];
00119
int8u privateKey[21];
00120
// The bottom flag bit is 1 for uninitialized, 0 for initialized.
00121
// The other flag bits should be set to 0 at initialization.
00122
int8u flags;
00123 } tokTypeMfgCbkeData;
00124 typedef struct {
00125
// The bottom flag bit is 1 for uninitialized, 0 for initialized.
00126
// Bits 1 and 2 give the size of the value string:
00127
// 0 = 6 bytes, 1 = 8 bytes, 2 = 12 bytes, 3 = 16 bytes.
00128
// The other flag bits should be set to 0 at initialization.
00129
// Special flags support. Due to a bug in the way some customers
00130
// had programmed the flags field, we will also examine the upper
00131
// bits 9 and 10 for the size field. Those bits are also reserved.
00132
int16u flags;
00133
int8u value[16];
00134
int16u crc;
00135 } tokTypeMfgInstallationCode;
00136 typedef int16u tokTypeMfgSynthFreqOffset;
00137 #endif //DEFINETYPES
00138
00139
00140 #ifdef DEFINETOKENS
00141 // The Manufacturing tokens need to be stored at well-defined locations
00142 // None of these addresses should ever change without extremely great care
00143 #define MFG_CHIP_DATA_LOCATION
0x5000 // 16 bytes
00144 #define MFG_NVDATA_VERSION_LOCATION
0x5010 //
2 bytes
00145 // reserved
0x5012 //
2 bytes
00146 #define MFG_EMBER_EUI_64_LOCATION
0x5014 //
8 bytes
00147 #define MFG_TRIM_DATA_LOCATION
0x501C // 24 bytes
00148 // reserved
0x5034 // 76 bytes
00149 #define MFG_CUSTOM_VERSION_LOCATION
0x5080 //
2 bytes
00150 #define MFG_CUSTOM_EUI_64_LOCATION
0x5082 //
8 bytes
00151 #define MFG_STRING_LOCATION
0x508A // 16 bytes
00152 #define MFG_BOARD_NAME_LOCATION
0x509A // 16 bytes
00153 #define MFG_OSC24M_BIAS_TRIM_LOCATION
0x50AA //
2 bytes
00154 #define MFG_MANUF_ID_LOCATION
0x50AC //
2 bytes
00155 #define MFG_PHY_CONFIG_LOCATION
0x50AE //
2 bytes
00156 #define MFG_BOOTLOAD_AES_KEY_LOCATION
0x50B0 // 16 bytes
00157 #define MFG_EZSP_STORAGE_LOCATION
0x50C0 //
8 bytes
00158 // unused
0x50C8 // 56 bytes
00159 #define MFG_ASH_CONFIG_LOCATION
0x5100 // 40 bytes
00160 #define MFG_CBKE_DATA_LOCATION
0x5128 // 92 bytes
00161 #define MFG_INSTALLATION_CODE_LOCATION 0x5184 // 20 bytes
00162 #define MFG_SYNTH_FREQ_OFFSET_LOCATION 0x5198 //
2 bytes
00163 // unused
0x519a // 614 bytes
EmberZNet 4.7.2 API EM250
120-3016-000-4720
550
00164 #define MFG_EUI_64_LOCATION
0x6000 // Special Trigger - see
token.c
00165
00166 // Define the size of indexed token array
00167 #define MFG_ASH_CONFIG_ARRAY_SIZE
20
00168
00169 // NOTE: because of their special handling, the manufacturing tokens
00170 // cannot use the convenience macros in their definitions, so the full
00171 // definitions are present here.
00172 TOKEN_NEXT_ADDRESS(MFG_CHIP_DATA_ADDR,MFG_CHIP_DATA_LOCATION)
00173 TOKEN_MFG(MFG_CHIP_DATA, CREATOR_MFG_CHIP_DATA,
00174
0, 0, tokTypeMfgChipData, 1,
00175
{0,})
00176
00177 TOKEN_NEXT_ADDRESS(MFG_NVDATA_VERSION_ADDR,
MFG_NVDATA_VERSION_LOCATION)
00178 TOKEN_MFG(MFG_NVDATA_VERSION, CREATOR_MFG_NVDATA_VERSION
,
00179
0, 0, tokTypeMfgNvdataVersion, 1,
00180
CURRENT_MFG_TOKEN_VERSION)
00181
00182 TOKEN_NEXT_ADDRESS(MFG_EMBER_EUI_64_ADDR,
MFG_EMBER_EUI_64_LOCATION)
00183 TOKEN_MFG(MFG_EMBER_EUI_64, CREATOR_MFG_EMBER_EUI_64,
00184
0, 0, tokTypeMfgEmberEui64, 1,
00185
{3,0,0,0,0,0,0,3})
00186
00187 TOKEN_NEXT_ADDRESS(MFG_TRIM_DATA_ADDR,MFG_TRIM_DATA_LOCATION)
00188 TOKEN_MFG(MFG_TRIM_DATA, CREATOR_MFG_TRIM_DATA,
00189
0, 0, tokTypeMfgTrimData, 1,
00190
{0,})
00191
00192 TOKEN_NEXT_ADDRESS(MFG_CUSTOM_VERSION_ADDR,
MFG_CUSTOM_VERSION_LOCATION)
00193 TOKEN_MFG(MFG_CUSTOM_VERSION, CREATOR_MFG_CUSTOM_VERSION
,
00194
0, 0, tokTypeMfgCustomVersion, 1,
00195
CURRENT_MFG_CUSTOM_VERSION)
00196
00197 TOKEN_NEXT_ADDRESS(MFG_CUSTOM_EUI_64_ADDR,
MFG_CUSTOM_EUI_64_LOCATION)
00198 TOKEN_MFG(MFG_CUSTOM_EUI_64, CREATOR_MFG_CUSTOM_EUI_64
,
00199
0, 0, tokTypeMfgCustomEui64, 1,
00200
{0,3,3,3,3,3,3,0})
00201
00202 TOKEN_NEXT_ADDRESS(MFG_STRING_ADDR,MFG_STRING_LOCATION)
00203 TOKEN_MFG(MFG_STRING, CREATOR_MFG_STRING,
00204
0, 0, tokTypeMfgString, 1,
00205
{0,})
00206
00207 TOKEN_NEXT_ADDRESS(MFG_BOARD_NAME_ADDR,
MFG_BOARD_NAME_LOCATION)
00208 TOKEN_MFG(MFG_BOARD_NAME, CREATOR_MFG_BOARD_NAME,
00209
0, 0, tokTypeMfgBoardName, 1,
00210
{0,})
00211
00212 TOKEN_NEXT_ADDRESS(MFG_OSC24M_BIAS_TRIM_ADDR,
MFG_OSC24M_BIAS_TRIM_LOCATION)
00213 TOKEN_MFG(MFG_OSC24M_BIAS_TRIM, CREATOR_MFG_OSC24M_BIAS_TRIM
,
00214
0, 0, tokTypeMfgOsc24mBiasTrim, 1,
00215
{0xFF,})
00216
00217 TOKEN_NEXT_ADDRESS(MFG_MANUF_ID_ADDR,MFG_MANUF_ID_LOCATION)
00218 TOKEN_MFG(MFG_MANUF_ID, CREATOR_MFG_MANUF_ID,
00219
0, 0, tokTypeMfgManufId, 1,
00220
{0x00,0x00,}) // default to 0 for ember
00221
00222 TOKEN_NEXT_ADDRESS(MFG_PHY_CONFIG_ADDR,
MFG_PHY_CONFIG_LOCATION)
00223 TOKEN_MFG(MFG_PHY_CONFIG, CREATOR_MFG_PHY_CONFIG,
00224
0, 0, tokTypeMfgPhyConfig, 1,
00225
{0x00,0x00,}) // default to non-boost mode, internal pa.
00226
00227 TOKEN_NEXT_ADDRESS(MFG_BOOTLOAD_AES_KEY_ADDR,
MFG_BOOTLOAD_AES_KEY_LOCATION)
00228 TOKEN_MFG(MFG_BOOTLOAD_AES_KEY, CREATOR_MFG_BOOTLOAD_AES_KEY
,
00229
0, 0, tokTypeMfgBootloadAesKey, 1,
EmberZNet 4.7.2 API EM250
120-3016-000-4720
551
00230
{0xFF,}) // default key is all f’s
00231
00232 TOKEN_NEXT_ADDRESS(MFG_EUI_64_ADDR,MFG_EUI_64_LOCATION)
00233 TOKEN_MFG(MFG_EUI_64, CREATOR_MFG_EUI_64,
00234
0, 0, tokTypeMfgEui64, 1,
00235
{3,3,3,3,0,0,0,0})
00236
00237 TOKEN_NEXT_ADDRESS(MFG_EZSP_STORAGE_ADDR,
MFG_EZSP_STORAGE_LOCATION)
00238 TOKEN_MFG(MFG_EZSP_STORAGE, CREATOR_MFG_EZSP_STORAGE,
00239
0, 0, tokTypeMfgEzspStorage, 1,
00240
{ 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF })
00241
00242 TOKEN_NEXT_ADDRESS(MFG_ASH_CONFIG_ADDR,
MFG_ASH_CONFIG_LOCATION)
00243 TOKEN_MFG(MFG_ASH_CONFIG, CREATOR_MFG_ASH_CONFIG,
00244
0, 1, tokTypeMfgAshConfig, MFG_ASH_CONFIG_ARRAY_SIZE,
00245
{ 0xFFFF, })
00246
00247 TOKEN_NEXT_ADDRESS(MFG_CBKE_DATA_ADDR,MFG_CBKE_DATA_LOCATION)
00248 TOKEN_MFG(MFG_CBKE_DATA, CREATOR_MFG_CBKE_DATA,
00249
0, 0, tokTypeMfgCbkeData, 1,
00250
{0xFF,})
00251
00252 TOKEN_NEXT_ADDRESS(MFG_INSTALLATION_CODE_ADDR,
MFG_INSTALLATION_CODE_LOCATION)
00253 TOKEN_MFG(MFG_INSTALLATION_CODE, CREATOR_MFG_INSTALLATION_CODE
,
00254
0, 0, tokTypeMfgInstallationCode, 1,
00255
{0xFF,})
00256
00257 TOKEN_NEXT_ADDRESS(MFG_SYNTH_FREQ_OFFSET_ADDR,
MFG_SYNTH_FREQ_OFFSET_LOCATION)
00258 TOKEN_MFG(MFG_SYNTH_FREQ_OFFSET, CREATOR_MFG_SYNTH_FREQ_OFFSET
,
00259
0, 0, tokTypeMfgSynthFreqOffset, 1,
00260
{0xFFFF,})
00261
00262 #endif //DEFINETOKENS
00263
00264
00265 #ifdef APPLICATION_MFG_TOKEN_HEADER
00266
#include APPLICATION_MFG_TOKEN_HEADER
00267 #endif
00268
8.113
token-stack.h File Reference
#include "token-phy.h"
Macros
• #define TOKEN_NEXT_ADDRESS(region, address)
• #define CURRENT_STACK_TOKEN_VERSION
Convenience Macros
The following convenience macros are used to simplify the definition process for commonly specified parameters to the basic TOKEN_DEF macro. Please see hal/micro/token.h for a more complete explanation.
•
•
•
•
#define DEFINE_BASIC_TOKEN(name, type,...)
#define DEFINE_COUNTER_TOKEN(name, type,...)
#define DEFINE_INDEXED_TOKEN(name, type, arraysize,...)
#define DEFINE_FIXED_BASIC_TOKEN(name, type, address,...)
EmberZNet 4.7.2 API EM250
120-3016-000-4720
552
• #define DEFINE_FIXED_COUNTER_TOKEN(name, type, address,...)
• #define DEFINE_FIXED_INDEXED_TOKEN(name, type, arraysize, address,...)
• #define DEFINE_MFG_TOKEN(name, type, address,...)
Creator Codes
The CREATOR is used as a distinct identifier tag for the token.
The CREATOR is necessary because the token name is defined differently depending on the hardware
platform, therefore the CREATOR makes sure that token definitions and data stay tagged and known. The
only requirement is that each creator definition must be unique. Please see hal/micro/token.h for a more
complete explanation.
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
#define CREATOR_STACK_NVDATA_VERSION
#define CREATOR_STACK_BOOT_COUNTER
#define CREATOR_STACK_NONCE_COUNTER
#define CREATOR_STACK_ANALYSIS_REBOOT
#define CREATOR_STACK_KEYS
#define CREATOR_STACK_NODE_DATA
#define CREATOR_STACK_CLASSIC_DATA
#define CREATOR_STACK_ALTERNATE_KEY
#define CREATOR_STACK_APS_FRAME_COUNTER
#define CREATOR_STACK_TRUST_CENTER
#define CREATOR_STACK_NETWORK_MANAGEMENT
#define CREATOR_STACK_PARENT_INFO
#define CREATOR_MULTI_NETWORK_STACK_KEYS
#define CREATOR_MULTI_NETWORK_STACK_NODE_DATA
#define CREATOR_MULTI_NETWORK_STACK_ALTERNATE_KEY
#define CREATOR_MULTI_NETWORK_STACK_TRUST_CENTER
#define CREATOR_MULTI_NETWORK_STACK_NETWORK_MANAGEMENT
#define CREATOR_MULTI_NETWORK_STACK_PARENT_INFO
#define CREATOR_MULTI_NETWORK_STACK_NONCE_COUNTER
#define CREATOR_STACK_BINDING_TABLE
#define CREATOR_STACK_CHILD_TABLE
#define CREATOR_STACK_KEY_TABLE
#define CREATOR_STACK_CERTIFICATE_TABLE
#define CREATOR_STACK_ZLL_DATA
#define CREATOR_STACK_ZLL_SECURITY
8.113.1
Detailed Description
Definitions for stack tokens. See Stack Tokens for documentation. The file token-stack.h should not be
included directly. It is accessed by the other token files.
Definition in file token-stack.h.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
553
8.114
00001
00046
00047
00059
00060
00061
00062
00063
00064
00065
00066
00067
00068
00069
00070
00071
00072
00073
00074
00075
00076
00077
00078
00079
00080
00081
00082
00083
00084
00085
00086
00087
00095
00096
00097
00098
00099
00100
00101
00102
00103
00104
00105
00106
00107
00108
00109
00110
00111
00112
00113
00114
00115
00116
00117
00118
00119
00123
00124
00125
00126
00127
00128
00129
00130
00131
00145
00146
00147
00148
00149
00150
00151
00152
00153
00154
00155
token-stack.h
#ifndef DEFINEADDRESSES
#define TOKEN_NEXT_ADDRESS(region, address)
#endif
// The basic TOKEN_DEF macro should not be used directly since the simplified
// definitions are safer to use. For completeness of information, the basic
// macro has the following format:
//
// TOKEN_DEF(name,creator,iscnt,isidx,type,arraysize,...)
// name - The root name used for the token
// creator - a "creator code" used to uniquely identify the token
// iscnt - a boolean flag that is set to identify a counter token
// isidx - a boolean flag that is set to identify an indexed token
// type - the basic type or typdef of the token
// arraysize - the number of elements making up an indexed token
// ... - initializers used when reseting the tokens to default values
//
//
// The following convenience macros are used to simplify the definition
// process for commonly specified parameters to the basic TOKEN_DEF macro
// DEFINE_BASIC_TOKEN(name, type, ...)
// DEFINE_INDEXED_TOKEN(name, type, arraysize, ...)
// DEFINE_COUNTER_TOKEN(name, type, ...)
// DEFINE_FIXED_BASIC_TOKEN(name, type, address, ...)
// DEFINE_FIXED_INDEXED_TOKEN(name, type, arraysize, address, ...)
// DEFINE_FIXED_COUNTER_TOKEN(name, type, address, ...)
// DEFINE_MFG_TOKEN(name, type, address, ...)
//
#define DEFINE_BASIC_TOKEN(name, type, ...) \
TOKEN_DEF(name, CREATOR_##name, 0, 0, type, 1,
__VA_ARGS__)
#define DEFINE_COUNTER_TOKEN(name, type, ...) \
TOKEN_DEF(name, CREATOR_##name, 1, 0, type, 1,
__VA_ARGS__)
#define DEFINE_INDEXED_TOKEN(name, type, arraysize, ...) \
TOKEN_DEF(name, CREATOR_##name, 0, 1, type, (arraysize), __VA_ARGS__)
#define DEFINE_FIXED_BASIC_TOKEN(name, type, address, ...) \
TOKEN_NEXT_ADDRESS(name,(address))
\
TOKEN_DEF(name, CREATOR_##name, 0, 0, type, 1, __VA_ARGS__)
#define DEFINE_FIXED_COUNTER_TOKEN(name, type, address, ...) \
TOKEN_NEXT_ADDRESS(name,(address))
\
TOKEN_DEF(name, CREATOR_##name, 1, 0, type, 1, __VA_ARGS__)
#define DEFINE_FIXED_INDEXED_TOKEN(name, type, arraysize, address, ...) \
TOKEN_NEXT_ADDRESS(name,(address))
\
TOKEN_DEF(name, CREATOR_##name, 0, 1, type, (arraysize), __VA_ARGS__)
#define DEFINE_MFG_TOKEN(name, type, address, ...) \
TOKEN_NEXT_ADDRESS(name,(address))
\
TOKEN_MFG(name, CREATOR_##name, 0, 0, type, 1, __VA_ARGS__)
// The Simulated EEPROM unit tests define all of their own tokens.
#ifndef SIM_EEPROM_TEST
//
//
//
//
//
The creator codes are here in one list instead of next to their token
definitions so comparision of the codes is easier. The only requirement
on these creator definitions is that they all must be unique. A favorite
method for picking creator codes is to use two ASCII characters inorder
to make the codes more memorable.
// STACK CREATORS
#define CREATOR_STACK_NVDATA_VERSION
#define CREATOR_STACK_BOOT_COUNTER
#define CREATOR_STACK_NONCE_COUNTER
#define CREATOR_STACK_ANALYSIS_REBOOT
#define CREATOR_STACK_KEYS
#define CREATOR_STACK_NODE_DATA
#define CREATOR_STACK_CLASSIC_DATA
#define CREATOR_STACK_ALTERNATE_KEY
#define CREATOR_STACK_APS_FRAME_COUNTER
#define CREATOR_STACK_TRUST_CENTER
EmberZNet 4.7.2 API EM250
120-3016-000-4720
0xFF01
0xE263
0xE563
0xE162
0xEB79
0xEE64
0xE364
0xE475
0xE123
0xE124
554
00156
00157
00158
00159
00160
00161
00162
00163
00164
00165
00166
00167
00168
00169
00170
00171
00172
00173
00174
00175
00176
00180
00181
00182
00183
00184
00185
00186
00187
00188
00189
00190
00191
00192
00193
00194
00195
00196
00197
00198
00200
00201
00202
00209
00210
00211
00212
00213
00214
00215
00216
00217
00218
00219
00220
00221
00222
00223
00224
00225
00226
00227
00228
00229
00230
00231
00232
00233
00234
00235
00236
00237
00238
00239
00240
00241
00242
00243
00244
#define CREATOR_STACK_NETWORK_MANAGEMENT
0xE125
#define CREATOR_STACK_PARENT_INFO
0xE126
// MULTI-NETWORK STACK CREATORS
#define CREATOR_MULTI_NETWORK_STACK_KEYS
0xE210
#define CREATOR_MULTI_NETWORK_STACK_NODE_DATA
0xE211
#define CREATOR_MULTI_NETWORK_STACK_ALTERNATE_KEY
0xE212
#define CREATOR_MULTI_NETWORK_STACK_TRUST_CENTER
0xE213
#define CREATOR_MULTI_NETWORK_STACK_NETWORK_MANAGEMENT
0xE214
#define CREATOR_MULTI_NETWORK_STACK_PARENT_INFO
0xE215
// Temporary solution for multi-network nwk counters: for now we define
// the following counter which will be used on the network with index 1.
#define CREATOR_MULTI_NETWORK_STACK_NONCE_COUNTER
0xE220
// APP CREATORS
#define CREATOR_STACK_BINDING_TABLE
#define CREATOR_STACK_CHILD_TABLE
#define CREATOR_STACK_KEY_TABLE
#define CREATOR_STACK_CERTIFICATE_TABLE
#define CREATOR_STACK_ZLL_DATA
#define CREATOR_STACK_ZLL_SECURITY
0xE274
0xFF0D
0xE456
0xE500
0xE501
0xE502
// MANUFACTURING DATA
// Since the manufacturing data is platform specific, we pull in the proper
// file here.
#if defined(AVR_ATMEGA)
#include "hal/micro/avr-atmega/token-manufacturing.h"
#elif defined(MSP430)
#include "hal/micro/msp430/token-manufacturing.h"
#elif defined(XAP2B)
#include "hal/micro/xap2b/token-manufacturing.h
"
#elif defined(CORTEXM3)
// cortexm3 handles mfg tokens seperately via mfg-token.h
#elif defined(EMBER_TEST)
#include "hal/micro/avr-atmega/token-manufacturing.h"
#else
#error no platform defined
#endif
// STACK DATA
// *the addresses of these tokens must not change*
#define CURRENT_STACK_TOKEN_VERSION 0x03FC //MSB is version, LSB is complement
#ifdef DEFINETYPES
typedef int16u tokTypeStackNvdataVersion;
#ifdef EMBER_SIMEE2
typedef int32u tokTypeStackBootCounter;
#else //EMBER_SIMEE2
typedef int16u tokTypeStackBootCounter;
#endif //EMBER_SIMEE2
typedef int16u tokTypeStackAnalysisReboot;
typedef int32u tokTypeStackNonceCounter;
typedef struct {
int8u networkKey[16];
int8u activeKeySeqNum;
} tokTypeStackKeys;
typedef struct {
int16u panId;
int8s radioTxPower;
int8u radioFreqChannel;
int8u stackProfile;
int8u nodeType;
int16u zigbeeNodeId;
int8u extendedPanId[8];
} tokTypeStackNodeData;
typedef struct {
int16u mode;
int8u eui64[8];
int8u key[16];
} tokTypeStackTrustCenter;
typedef struct {
int32u activeChannels;
int16u managerNodeId;
int8u updateId;
} tokTypeStackNetworkManagement;
typedef struct {
int8u parentEui[8];
EmberZNet 4.7.2 API EM250
120-3016-000-4720
555
00245
00246
00247
00248
00249
00250
00251
00252
00253
00254
00255
00256
00257
00258
00259
00260
00261
00262
00263
00264
00265
00266
00267
00268
00269
00270
00271
00272
00273
00274
00275
00276
00277
00278
00279
00280
00281
00282
00283
00284
00285
00286
00287
00288
00289
00290
00291
00292
00293
00294
00295
00296
00297
00298
00299
00300
00301
00302
00303
00304
00305
00306
00307
00308
00309
00310
00311
00312
00313
00314
00315
00316
00317
00318
00320
00321
00322
00324
int16u parentNodeId;
} tokTypeStackParentInfo;
#endif //DEFINETYPES
#ifdef DEFINETOKENS
// The Stack tokens also need to be stored at well-defined locations
// None of these addresses should ever change without extremely great care
#define STACK_VERSION_LOCATION
128 // 2
bytes
#define STACK_APS_NONCE_LOCATION 130 // 4
bytes
#define STACK_ALT_NWK_KEY_LOCATION 134 // 17 bytes (key + sequence number)
// reserved
151
1
bytes
#define STACK_BOOT_COUNT_LOCATION 152 // 2
bytes
// reserved
154
2
bytes
#define STACK_NONCE_LOCATION
156 // 4
bytes
// reserved
160
1
bytes
#define STACK_REBOOT_LOCATION
161 // 2
bytes
// reserved
163
7
bytes
#define STACK_KEYS_LOCATION
170 // 17 bytes
// reserved
187
5
bytes
#define STACK_NODE_DATA_LOCATION 192 // 16 bytes
#define STACK_CLASSIC_LOCATION
208 // 26 bytes
#define STACK_TRUST_CENTER_LOCATION 234 //26 bytes
// reserved
260
8
bytes
#define STACK_NETWORK_MANAGEMENT_LOCATION 268
// 7
bytes
// reserved
275
109 bytes
DEFINE_FIXED_BASIC_TOKEN(STACK_NVDATA_VERSION,
tokTypeStackNvdataVersion,
STACK_VERSION_LOCATION,
CURRENT_STACK_TOKEN_VERSION
)
DEFINE_FIXED_COUNTER_TOKEN(STACK_APS_FRAME_COUNTER,
tokTypeStackNonceCounter,
STACK_APS_NONCE_LOCATION,
0x00000000)
DEFINE_FIXED_BASIC_TOKEN(STACK_ALTERNATE_KEY,
tokTypeStackKeys,
STACK_ALT_NWK_KEY_LOCATION,
{0,})
DEFINE_FIXED_COUNTER_TOKEN(STACK_BOOT_COUNTER,
tokTypeStackBootCounter,
STACK_BOOT_COUNT_LOCATION,
0x0000)
DEFINE_FIXED_COUNTER_TOKEN(STACK_NONCE_COUNTER,
tokTypeStackNonceCounter,
STACK_NONCE_LOCATION,
0x00000000)
DEFINE_FIXED_BASIC_TOKEN(STACK_ANALYSIS_REBOOT,
tokTypeStackAnalysisReboot,
STACK_REBOOT_LOCATION,
0x0000)
DEFINE_FIXED_BASIC_TOKEN(STACK_KEYS,
tokTypeStackKeys,
STACK_KEYS_LOCATION,
{0,})
DEFINE_FIXED_BASIC_TOKEN(STACK_NODE_DATA,
tokTypeStackNodeData,
STACK_NODE_DATA_LOCATION,
{0xFFFF,-1,0,0x00,0x00,0x0000})
DEFINE_FIXED_BASIC_TOKEN(STACK_TRUST_CENTER,
tokTypeStackTrustCenter,
STACK_TRUST_CENTER_LOCATION,
{0,})
DEFINE_FIXED_BASIC_TOKEN(STACK_NETWORK_MANAGEMENT,
tokTypeStackNetworkManagement,
STACK_NETWORK_MANAGEMENT_LOCATION,
{0, 0xFFFF, 0})
DEFINE_BASIC_TOKEN(STACK_PARENT_INFO,
tokTypeStackParentInfo,
{ {0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF}, 0xFFFF}
)
#endif //DEFINETOKENS
// PHY DATA
#include "token-phy.h"
// MULTI-NETWORK STACK TOKENS: Tokens for the networks with index > 0.
EmberZNet 4.7.2 API EM250
120-3016-000-4720
556
00325
00326
00327
00328
00329
00330
00331
00332
00333
00334
00335
00336
00337
00338
00339
00340
00341
00342
00343
00344
00345
00346
00347
00348
00349
00350
00351
00352
00353
00354
00355
00356
00357
00358
00359
00360
00361
00362
00363
00365
00366
00367
00368
00369
00370
00371
00372
00373
00374
00375
00376
00377
00378
// The 0-index network info is stored in the usual tokens.
#ifdef DEFINETOKENS
#if !defined(EMBER_MULTI_NETWORK_STRIPPED)
#define EXTRA_NETWORKS_NUMBER (EMBER_SUPPORTED_NETWORKS - 1)
DEFINE_INDEXED_TOKEN(MULTI_NETWORK_STACK_KEYS,
tokTypeStackKeys,
EXTRA_NETWORKS_NUMBER,
{0,})
DEFINE_INDEXED_TOKEN(MULTI_NETWORK_STACK_NODE_DATA,
tokTypeStackNodeData,
EXTRA_NETWORKS_NUMBER,
{0,})
DEFINE_INDEXED_TOKEN(MULTI_NETWORK_STACK_ALTERNATE_KEY,
tokTypeStackKeys,
EXTRA_NETWORKS_NUMBER,
{0,})
DEFINE_INDEXED_TOKEN(MULTI_NETWORK_STACK_TRUST_CENTER,
tokTypeStackTrustCenter,
EXTRA_NETWORKS_NUMBER,
{0,})
DEFINE_INDEXED_TOKEN(MULTI_NETWORK_STACK_NETWORK_MANAGEMENT
,
tokTypeStackNetworkManagement,
EXTRA_NETWORKS_NUMBER,
{0,})
DEFINE_INDEXED_TOKEN(MULTI_NETWORK_STACK_PARENT_INFO,
tokTypeStackParentInfo,
EXTRA_NETWORKS_NUMBER,
{{0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF}, 0xFFFF}
)
// Temporary solution for NWK counter token: the following is used for 1-index
// network.
DEFINE_COUNTER_TOKEN(MULTI_NETWORK_STACK_NONCE_COUNTER,
tokTypeStackNonceCounter,
0x00000000)
#endif // EMBER_MULTI_NETWORK_STRIPPED
#endif // DEFINETOKENS
// APPLICATION DATA
// *If a fixed application token is desired, its address must be above 384.*
#ifdef DEFINETYPES
typedef int8u tokTypeStackBindingTable[13];
typedef int8u tokTypeStackChildTable[11];
typedef int8u tokTypeStackKeyTable[25];
// Certificate Table Entry
//
Certificate:
48-bytes
//
CA Public Key: 22-bytes
//
Private Key:
21-bytes
//
Flags:
1-byte
#define TOKEN_CERTIFICATE_TABLE_ENTRY_SIZE (48 + 22 + 21 + 1)
#define TOKEN_CERTIFICATE_TABLE_ENTRY_FLAGS_INDEX
(TOKEN_CERTIFICATE_TABLE_ENTRY_SIZE - 1)
00379 typedef int8u tokTypeStackCertificateTable[
TOKEN_CERTIFICATE_TABLE_ENTRY_SIZE];
00380 #endif //DEFINETYPES
00381
00382 // The following application tokens are required by the stack, but are sized by
00383
00384
00385
00386
00387
00388
00389
00390
00391
00392
00393
00394
00395
00396
00397
00398
00399
// the application via its CONFIGURATION_HEADER, which is why they are present
// within the application data section. Any special application defined
// tokens will follow.
// NOTE: changing the size of these tokens within the CONFIGURATION_HEADER
// WILL move automatically move any custom application tokens that are defined
// in the APPLICATION_TOKEN_HEADER
#ifdef DEFINETOKENS
// Application tokens start at location 384 and are automatically positioned.
TOKEN_NEXT_ADDRESS(APP,384)
DEFINE_INDEXED_TOKEN(STACK_BINDING_TABLE,
tokTypeStackBindingTable,
EMBER_BINDING_TABLE_TOKEN_SIZE
,
{0,})
DEFINE_INDEXED_TOKEN(STACK_CHILD_TABLE,
tokTypeStackChildTable,
EMBER_CHILD_TABLE_TOKEN_SIZE,
{0,})
EmberZNet 4.7.2 API EM250
120-3016-000-4720
557
00400
00401
00402
00403
00404
00405
00406
00407
00408
00409
00410
00411
00412
00413
00414
00415
00416
00417
00418
00419
00420
00421
00422
00423
00424
00425
00426
00427
00428
00429
00430
00431
00432
00433
00434
00435
00436
00437
00438
00439
00440
00441
00442
00443
00444
00445
00446
00447
00448
00449
00450
00451
00452
00453
00454
00455
00456
00457
00458
00459
00460
00461
00462
00463
00464
00465
00466
00467
00468
00469
DEFINE_INDEXED_TOKEN(STACK_KEY_TABLE,
tokTypeStackKeyTable,
EMBER_KEY_TABLE_TOKEN_SIZE,
{0,})
DEFINE_INDEXED_TOKEN(STACK_CERTIFICATE_TABLE,
tokTypeStackCertificateTable,
EMBER_CERTIFICATE_TABLE_SIZE,
{0,})
#endif //DEFINETOKENS
// This must appear before the application header so that the token
// numbering is consistent regardless of whether application tokens are
// defined.
#if defined(EMBER_ZLL_STACK)
#include "stack/zll/zll-token-config.h"
#endif
#ifdef APPLICATION_TOKEN_HEADER
#include APPLICATION_TOKEN_HEADER
#endif
//The tokens defined below are test tokens. They are normally not used by
//anything but are left here as a convenience so test tokens do not have to
//be recreated. If test code needs temporary, non-volatile storage, simply
//uncomment and alter the set below as needed.
//#define CREATOR_TT01 1
//#define CREATOR_TT02 2
//#define CREATOR_TT03 3
//#define CREATOR_TT04 4
//#define CREATOR_TT05 5
//#define CREATOR_TT06 6
//#ifdef DEFINETYPES
//typedef int32u tokTypeTT01;
//typedef int32u tokTypeTT02;
//typedef int32u tokTypeTT03;
//typedef int32u tokTypeTT04;
//typedef int16u tokTypeTT05;
//typedef int16u tokTypeTT06;
//#endif //DEFINETYPES
//#ifdef DEFINETOKENS
//#define TT01_LOCATION 1
//#define TT02_LOCATION 2
//#define TT03_LOCATION 3
//#define TT04_LOCATION 4
//#define TT05_LOCATION 5
//#define TT06_LOCATION 6
//DEFINE_FIXED_BASIC_TOKEN(TT01, tokTypeTT01, TT01_LOCATION, 0x0000)
//DEFINE_FIXED_BASIC_TOKEN(TT02, tokTypeTT02, TT02_LOCATION, 0x0000)
//DEFINE_FIXED_BASIC_TOKEN(TT03, tokTypeTT03, TT03_LOCATION, 0x0000)
//DEFINE_FIXED_BASIC_TOKEN(TT04, tokTypeTT04, TT04_LOCATION, 0x0000)
//DEFINE_FIXED_BASIC_TOKEN(TT05, tokTypeTT05, TT05_LOCATION, 0x0000)
//DEFINE_FIXED_BASIC_TOKEN(TT06, tokTypeTT06, TT06_LOCATION, 0x0000)
//#endif //DEFINETOKENS
#else //SIM_EEPROM_TEST
//The Simulated EEPROM unit tests define all of their tokens via the
//APPLICATION_TOKEN_HEADER macro.
#ifdef APPLICATION_TOKEN_HEADER
#include APPLICATION_TOKEN_HEADER
#endif
#endif //SIM_EEPROM_TEST
#ifndef DEFINEADDRESSES
#undef TOKEN_NEXT_ADDRESS
#endif
8.115
token.h File Reference
EmberZNet 4.7.2 API EM250
120-3016-000-4720
558
Macros
•
•
•
•
•
•
#define halCommonGetToken(data, token)
#define halCommonGetMfgToken(data, token)
#define halCommonGetIndexedToken(data, token, index)
#define halCommonSetToken(token, data)
#define halCommonSetIndexedToken(token, index, data)
#define halCommonIncrementCounterToken(token)
Functions
• EmberStatus halStackInitTokens (void)
8.115.1
Detailed Description
Token system for storing non-volatile information. See Tokens for documentation.
Definition in file token.h.
8.116
00001
00222
00223
00224
00225
00226
00227
00228
00229
00230
00231
00232
00233
00234
00235
00236
00237
00238
00239
00240
00241
00242
00243
00244
00252
00253
00254
00255
00256
00257
00258
00259
00260
00261
00262
00276
00277
00291
00292
00307
00308
00321
00322
00338
00339
token.h
#ifndef __TOKEN_H__
#define __TOKEN_H__
#if defined(AVR_ATMEGA)
#include "avr-atmega/token.h"
#elif defined(MSP430)
#include "msp430/token.h"
#elif defined(XAP2B)
#include "xap2b/token.h"
#elif defined(CORTEXM3)
#ifdef MINIMAL_HAL
#include "cortexm3/nvm-token.h"
#include "cortexm3/mfg-token.h"
#else //MINIMAL_HAL
#include "cortexm3/token.h"
#endif //MINIMAL_HAL
#elif defined(EMBER_TEST)
#include "generic/token-ram.h"
#else
#error invalid platform
#endif
EmberStatus halStackInitTokens(void);
//
//
//
//
//
//
NOTE:
The following API as written below is purely for doxygen
documentation purposes. The live API used in code is actually macros
defined in the platform specific token headers and provide abstraction
that can allow easy and efficient access to tokens in different
implementations.
#ifdef DOXYGEN_SHOULD_SKIP_THIS
#define halCommonGetToken( data, token )
#define halCommonGetMfgToken( data, token )
#define halCommonGetIndexedToken( data, token, index )
#define halCommonSetToken( token, data )
#define halCommonSetIndexedToken( token, index, data )
EmberZNet 4.7.2 API EM250
120-3016-000-4720
559
00351
00352
00353
00354
00355
00356
00357
00358
00359
00360
00361
00362
00363
00364
00365
00366
00367
00368
#define halCommonIncrementCounterToken( token )
#endif //DOXYGEN_SHOULD_SKIP_THIS
#ifndef DOXYGEN_SHOULD_SKIP_THIS
// These interfaces serve only as a glue layer
// to link creator codes to tokens (primarily for *test code)
#define INVALID_EE_ADDRESS 0xFFFF
int16u getTokenAddress(int16u creator);
int8u getTokenSize(int16u creator );
int8u getTokenArraySize(int16u creator);
#endif //DOXYGEN_SHOULD_SKIP_THIS
#endif // __TOKEN_H__
8.117
token.h File Reference
Functions
• XAP2B_PAGEZERO_ON void halInternalGetTokenData (void ∗data, int16u token, int8u index,
int8u len)
• XAP2B_PAGEZERO_OFF void halInternalGetMfgTokenData (void ∗data, int16u ID, int8u index,
int8u len)
• void halInternalSetTokenData (int16u token, int8u index, void ∗data, int8u len)
• void halInternalIncrementCounterToken (int8u token)
8.117.1
Detailed Description
XAP2b Token system for storing non-volatile information. See Tokens for documentation.
Definition in file xap2b/token.h.
8.118
00001
00014
00015
00016
00017
00018
00019
00020
00021
00022
00023
00024
00029
00030
00031
00032
00033
00034
00035
00036
00037
00038
00039
00040
00041
00042
xap2b/token.h
#ifndef __PLAT_TOKEN_H__
#define __PLAT_TOKEN_H__
#ifndef __TOKEN_H__
#error do not include this file directly - include micro/token.h
#endif
#ifndef DOXYGEN_SHOULD_SKIP_THIS
//-- Build structure defines
#define DEFINETYPES
#include "stack/config/token-stack.h"
#undef DEFINETYPES
//-- Build parameter links
#define DEFINETOKENS
// The manufacturing tokens live in the Flash Info Page, while all other tokens
// live in the Simulated EEPROM. This requires the token names to be defined
// as different data (mfg tokens are memory address, all others are an enum).
#undef TOKEN_MFG
#undef TOKEN_DEF
EmberZNet 4.7.2 API EM250
120-3016-000-4720
560
00043
00054
00055
00056
00057
00058
00059
00060
00061
00072
00073
00074
00075
00076
00077
00078
00079
00080
00081
00082
00091
00092
00093
00094
00095
00096
00097
00098
00099
00100
00101
00102
00112
00113
00114
00127
00128
00129
00130
00131
00132
00137
00138
00139
00140
00141
00142
00143
00144
00145
00146
00147
00148
00149
00150
00151
00161
00162
00172
00173
00182
00183
00192
00193
00207
00208
00215
00216
00217
00218
00229
00230
00231
00232
00233
00234
00235
00236
00255
00256
#define TOKEN_DEF(name,creator,iscnt,isidx,type,arraysize,...)
#define TOKEN_MFG(name,creator,iscnt,isidx,type,arraysize,...) \
extern const int16u TOKEN_##name;
#include "stack/config/token-stack.h"
#undef TOKEN_MFG
#undef TOKEN_DEF
#define TOKEN_MFG(name,creator,iscnt,isidx,type,arraysize,...)
#define TOKEN_DEF(name,creator,iscnt,isidx,type,arraysize,...) \
TOKEN_##name,
enum{
#include "stack/config/token-stack.h"
TOKEN_COUNT
};
#undef TOKEN_MFG
#undef TOKEN_DEF
#define TOKEN_MFG TOKEN_DEF
#define TOKEN_DEF(name,creator,iscnt,isidx,type,arraysize,...) \
TOKEN_##name##_SIZE = sizeof(type),
enum {
#include "stack/config/token-stack.h"
};
#undef TOKEN_MFG
#undef TOKEN_DEF
#define DEFINEADDRESSES
#define TOKEN_NEXT_ADDRESS(region, address)
\
TOKEN_##region##_NEXT_ADDRESS = ((address) - 1),
#define TOKEN_DEF(name,creator,iscnt,isidx,type,arraysize,...)
#define TOKEN_MFG(name,creator,iscnt,isidx,type,arraysize,...) \
TOKEN_##name##_ADDRESS,
\
TOKEN_##name##_END = TOKEN_##name##_ADDRESS +
\
(TOKEN_##name##_SIZE * arraysize) - 1,
enum {
#include "stack/config/token-stack.h"
TOKEN_MAXIMUM_SIZE
};
#undef TOKEN_MFG
#undef TOKEN_DEF
#undef TOKEN_NEXT_ADDRESS
#undef DEFINEADDRESSES
//From this point on, the manufacturing tokens are defined like regular tokens.
#define TOKEN_MFG TOKEN_DEF
extern int16u tokenCreators[];
extern boolean tokenIsCnt[];
extern int8u tokenSize[];
extern int8u tokenArraySize[];
extern const void * const tokenDefaults[];
#define COUNTER_TOKEN_PAD
50
#define TOKEN_DEF(name,creator,iscnt,isidx,type,arraysize,...) \
typedef type TOKEN_##name##_TYPE;
#include "stack/config/token-stack.h"
#undef TOKEN_DEF
#undef DEFINETOKENS
#endif
//DOXYGEN_SHOULD_SKIP_THIS
XAP2B_PAGEZERO_ON
void halInternalGetTokenData(void *data, int16u
EmberZNet 4.7.2 API EM250
120-3016-000-4720
561
token, int8u index, int8u len);
00257 XAP2B_PAGEZERO_OFF
00258
00273 void halInternalGetMfgTokenData(void *data, int16u
ID, int8u index, int8u len);
00274
00275
00295 void halInternalSetTokenData(int16u token, int8u
index, void *data, int8u len);
00296
00307 void halInternalIncrementCounterToken(int8u
token);
00308
00309 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00310
00311 // See hal/micro/token.h for the full explanation of the token API as
00312 // instantiated below.
00313
00314 #define halCommonGetToken( data, token )
\
00315
halInternalGetTokenData(data, token, 0x7F, token##_SIZE)
00316
00317 #define halCommonGetMfgToken( data, token )
\
00318
halInternalGetMfgTokenData(data, token, 0x7F, token##_SIZE)
00319
00320 #define halCommonGetIndexedToken( data, token, index )
\
00321
halInternalGetTokenData(data, token, index, token##_SIZE)
00322
00323 #define halCommonGetIndexedMfgToken( data, token, index )
\
00324
halInternalGetMfgTokenData(data, token, index, token##_SIZE)
00325
00326 #define halStackGetIndexedToken( data, token, index, size ) \
00327
halInternalGetTokenData(data, token, index, size)
00328
00329 #define halStackGetIdxTokenPtrOrData( data, token, index ) \
00330
halInternalGetTokenData(*data, token, index, token##_SIZE)
00331
00332 #define halCommonSetToken( token, data )
\
00333
halInternalSetTokenData(token, 0x7F, data, token##_SIZE)
00334
00335 #define halCommonSetIndexedToken( token, index, data )
\
00336
halInternalSetTokenData(token, index, data, token##_SIZE)
00337
00338 #define halStackSetIndexedToken( token, index, data, size ) \
00339
halInternalSetTokenData(token, index, data, size)
00340
00341 #define halCommonIncrementCounterToken( token )
\
00342
halInternalIncrementCounterToken(token);
00343
00344 // For use only by the EZSP UART protocol
00345 #ifdef EZSP_UART
00346
#ifdef XAP2B
00347
#define halInternalMfgIndexedToken( type, address, index ) \
00348
*((const type *)(address) + index)
00349
#endif
00350 #endif
00351
00352 #endif
//DOXYGEN_SHOULD_SKIP_THIS
00353
00354 #undef TOKEN_MFG
00355
00356 #endif // __PLAT_TOKEN_H__
00357
8.119
trust-center.h File Reference
Macros
• #define EMBER_FORM_TRUST_CENTER_NETWORK_BITMASK
• #define EMBER_FORM_DISTRIBUTED_TRUST_CENTER_NETWORk_BITMASK
EmberZNet 4.7.2 API EM250
120-3016-000-4720
562
Functions
• EmberStatus emberBroadcastNextNetworkKey (EmberKeyData ∗key)
• EmberStatus emberSendUnicastNetworkKeyUpdate (EmberNodeId targetShort, EmberEUI64 targetLong, EmberKeyData ∗newKey)
• EmberStatus emberBroadcastNetworkKeySwitch (void)
• EmberJoinDecision emberTrustCenterJoinHandler (EmberNodeId newNodeId, EmberEUI64 newNodeEui64, EmberDeviceUpdate status, EmberNodeId parentOfNewNode)
• EmberStatus emberBecomeTrustCenter (EmberKeyData ∗newNetworkKey)
• EmberStatus emberSendRemoveDevice (EmberNodeId destShort, EmberEUI64 destLong, EmberEUI64 deviceToRemoveLong)
Variables
• EmberLinkKeyRequestPolicy emberTrustCenterLinkKeyRequestPolicy
• EmberLinkKeyRequestPolicy emberAppLinkKeyRequestPolicy
8.119.1
Detailed Description
EmberZNet security API See Security for documentation.
Definition in file trust-center.h.
8.120
trust-center.h
00001
00029 #define EMBER_FORM_TRUST_CENTER_NETWORK_BITMASK \
00030
( EMBER_STANDARD_SECURITY_MODE
\
00031
| EMBER_TRUST_CENTER_GLOBAL_LINK_KEY
\
00032
| EMBER_HAVE_NETWORK_KEY
\
00033
| EMBER_HAVE_PRECONFIGURED_KEY )
00034
00042 #define EMBER_FORM_DISTRIBUTED_TRUST_CENTER_NETWORk_BITMASK
\
00043
( EMBER_STANDARD_SECURITY_MODE
\
00044
| EMBER_TRUST_CENTER_GLOBAL_LINK_KEY
\
00045
| EMBER_DISTRIBUTED_TRUST_CENTER_MODE
\
00046
| EMBER_HAVE_NETWORK_KEY
\
00047
| EMBER_HAVE_PRECONFIGURED_KEY )
00048
00071 EmberStatus emberBroadcastNextNetworkKey
(EmberKeyData* key);
00072
00100 #if defined DOXYGEN_SHOULD_SKIP_THIS
00101 EmberStatus emberSendUnicastNetworkKeyUpdate
(EmberNodeId targetShort,
00102
EmberEUI64 targetLong,
00103
EmberKeyData* newKey);
00104 #else
00105 EmberStatus emSendAlternateNetworkKeyToAddress(EmberNodeId
targetShort,
00106
EmberEUI64 targetLong,
00107
EmberKeyData* newKey
);
00108
00109 #define emberSendUnicastNetworkKeyUpdate(shortAddr, longAddr, key) \
00110
emSendAlternateNetworkKeyToAddress((shortAddr), (longAddr), (key))
00111 #endif
00112
00113
00125 #if defined DOXYGEN_SHOULD_SKIP_THIS
00126 EmberStatus emberBroadcastNetworkKeySwitch
(void);
00127 #else
00128 EmberStatus emSendNetworkKeySwitch(EmberNodeId
EmberZNet 4.7.2 API EM250
120-3016-000-4720
563
destination);
00129
00130 #define emberBroadcastNetworkKeySwitch() \
00131
emSendNetworkKeySwitch(EMBER_SLEEPY_BROADCAST_ADDRESS)
00132 #endi