IDT ZWIR451, ZWIR4512AC2, ZWIR4512, ZWIR4512AC1 Programming Manual

ZWIR451x Programming Guide

Content

1 Introduction ......................................................................................................................................................... 5

1.1. IPv6 .............................................................................................................................................................. 6

1.2. 6LoWPAN .................................................................................................................................................... 6

1.3. Organization of this Document .................................................................................................................... 6

2 Functional Description ........................................................................................................................................ 7

2.1. Requirements Notation ................................................................................................................................ 7

2.2. Terms ........................................................................................................................................................... 7

2.3. Naming Conventions ................................................................................................................................... 8

2.4. Library Architecture ..................................................................................................................................... 8

2.5. Operating Modes ......................................................................................................................................... 9

2.5.1. Device Mode ......................................................................................................................................... 9

2.5.2. Gateway Mode .................................................................................................................................... 10

2.5.3. Sniffer Mode ........................................................................................................................................ 10

2.6. Operating System ...................................................................................................................................... 11

2.6.1. Initialization ......................................................................................................................................... 11

2.6.2. Normal Operation ................................................................................................................................ 11

2.6.3. Power Modes ...................................................................................................................................... 13

2.6.4. Error Handling ..................................................................................................................................... 14

2.7. Firmware Version Information ................................................................................................................... 14

2.7.1. Vendor ID ............................................................................................................................................ 15

2.7.2. Product ID ........................................................................................................................................... 15

2.7.3. Major Firmware Version ...................................................................................................................... 15

2.7.4. Minor Firmware Version ...................................................................................................................... 15

2.7.5. Firmware Version Extension ............................................................................................................... 15

2.7.6. Library Version .................................................................................................................................... 15

2.8. Addressing ................................................................................................................................................. 15

2.8.1. Address Types .................................................................................................................................... 16

2.8.2. IPv6 Addresses ................................................................................................................................... 16

2.8.3. IPv6 Address Auto-configuration ........................................................................................................ 18

2.8.4. Validation of Address Uniqueness ...................................................................................................... 18

2.9. Data Transmission and Reception ............................................................................................................ 20

2.9.1. User Datagram Protocol ..................................................................................................................... 20

2.9.2. Data Transmission and Reception ...................................................................................................... 20

2.9.3. Address Resolution ............................................................................................................................. 22

2.9.4. Recommendations .............................................................................................................................. 23

2.10. Mesh Routing............................................................................................................................................. 23

2.10.1. Multicast Traffic ................................................................................................................................... 24

2.10.2. Unicast Traffic ..................................................................................................................................... 24

2.10.3. Mesh Routing Parameter Configuration Recommendations .............................................................. 24

2.11. Network and Device Status ....................................................................................................................... 26

ZWIR451x Programming Guide

2.12. Security ...................................................................................................................................................... 26

2.12.1. Internet Protocol Security (IPSec) ....................................................................................................... 27

2.12.2. Internet Key Exchange Version 2 (IKEv2) .......................................................................................... 28

2.12.3. Recommendations .............................................................................................................................. 28

2.13. Firmware Over-the-Air Upd ates................................................................................................................. 28

2.13.1. Functional Description ........................................................................................................................ 29

2.13.2. Firmware Constraints .......................................................................................................................... 30

2.14. Memory Considerations ............................................................................................................................. 30

2.14.1. Call Stack ............................................................................................................................................ 31

2.14.2. IDT Network Stack Dynamic RAM Requirements .............................................................................. 31

2.14.3. Using Dynamic Memory Allocation ..................................................................................................... 32

2.15. Supported Network Standards .................................................................................................................. 33

3 Core-Library Reference .................................................................................................................................... 36

3.1. Initialization ................................................................................................................................................ 36

3.2. Program Control ........................................................................................................................................ 37

3.3. Networking ................................................................................................................................................. 41

3.3.1. Address Management ......................................................................................................................... 41

3.3.2. Socket and Datagram Handling .......................................................................................................... 44

3.3.3. Radio Parameters ............................................................................................................................... 49

3.3.4. Gateway Mode Functions ................................................................................................................... 51

3.3.5. Miscellaneous ..................................................................................................................................... 52

3.4. Power Management .................................................................................................................................. 55

3.5. Firmware Version Information ................................................................................................................... 59

3.6. Properties and Parameters ........................................................................................................................ 60

3.7. Error Codes ............................................................................................................................................... 61

4 UART Library Reference .................................................................................................................................. 62

4.1. Symbol Reference ..................................................................................................................................... 62

4.2. Custom UART I/O Configuration ............................................................................................................... 64

4.3. Error Codes ............................................................................................................................................... 65

5 GPIO Library Reference ................................................................................................................................... 66

5.1. Symbol Reference ..................................................................................................................................... 66

6 IPSec Library Reference .................................................................................................................................. 71

6.1. Symbol Reference ..................................................................................................................................... 71

6.2. Error Codes ............................................................................................................................................... 74

7 IKEv2 Library Reference .................................................................................................................................. 75

7.1. Symbol Reference ..................................................................................................................................... 75

7.2. Library Parameters .................................................................................................................................... 76

8 Over-the-Air Update Library ............................................................................................................................. 77

8.1. Library Reference ...................................................................................................................................... 77

8.2. Inclusion of the OTAU Library ................................................................................................................... 79

8.3. Error Codes ............................................................................................................................................... 80

ZWIR451x Programming Guide

9 NetMA Libraries ................................................................................................................................................ 81

9.1. NetMA1 Library .......................................................................................................................................... 81

9.1.1. NetMA1 Library Symbol Reference .................................................................................................... 81

9.1.2. Inclusion of the NetMA1 library ........................................................................................................... 86

9.2. NetMA2 Libraries ....................................................................................................................................... 87

9.2.1. NetMA2 Library Symbol Reference .................................................................................................... 87

9.2.2. Inclusion of the NetMA2 Libraries ....................................................................................................... 88

10 Accessing Microcontroller Resources .............................................................................................................. 89

10.1. Internal Microcontroller Configuration ....................................................................................................... 89

10.2. Backup Data Registers .............................................................................................................................. 89

10.3. Interrupt Handlers ...................................................................................................................................... 89

10.4. Default I/O Configuration ........................................................................................................................... 92

11 Certification....................................................................................................................................................... 96

11.1. European R&TTE Directive Statements .................................................................................................... 96

11.2. Federal Communication Commission Certification Statements ................................................................ 96

11.2.1. Statements .......................................................................................................................................... 96

11.2.2. Requirements ...................................................................................................................................... 96

11.2.3. Accessing the FCC ID ......................................................................................................................... 97

11.3. Supported Antennas .................................................................................................................................. 97

12 Alphabetical Lists of Symbols........................................................................................................................... 98

12.1. Functions and Function-Like Macros ........................................................................................................ 98

12.2. Data Types ................................................................................................................................................ 99

12.3. Variables and Constants ......................................................................................................................... 101

13 Related Documents ........................................................................................................................................ 102

14 Glossary ......................................................................................................................................................... 103

15 Document Revision History ............................................................................................................................ 105

List of Figures

Figure 1.1 ZWIR451x Application Domain ............................................................................................................. 5

Figure 2.1 Library Architecture ............................................................................................................................... 9

Figure 2.2 Application Interface into the Protocol Stack in Different Operating Modes ....................................... 10

Figure 2.3 IPv6 Unicast Address Layout.............................................................................................................. 17

Figure 2.4 IPv6 Multicast Address Layout ........................................................................................................... 17

Figure 2.5 Resolving Address Conflicts in Local Networks ................................................................................. 19

Figure 2.6 Working Principle of IPSec ................................................................................................................. 27

Figure 2.7 Memory Layout of OTAU-Enabled Applications ................................................................................. 29

Figure 2.8 Heap Memory Scattering .................................................................................................................... 32

Figure 5.1 ZWIR_GPIO_ReadMultiple Result Alignment in ZWIR4512AC1 Devices ......................................... 67

Figure 5.2 ZWIR_GPIO_ReadMultiple Result Alignment in ZWIR4512AC2 Devices ......................................... 67

Figure 11.1 FCC Compliance Statement to be Printed on Equipment Incorporating ZWIR4512 Devices ............ 97

ZWIR451x Programming Guide

List of Ta ble s

Table 2.1 Naming Conventions Used in C-Code .................................................................................................. 8

Table 2.2 Event Processing Priorit y in the Main Event Loo p.............................................................................. 12

Table 2.3 Power Modes Overview ...................................................................................................................... 13

Table 2.4 Interrupts that Result in a System Reset ............................................................................................ 14

Table 2.5 Unicast Socket Examples ................................................................................................................... 21

Table 2.6 Multicast Addressing Exam ples .......................................................................................................... 22

Table 2.7 Stack Parameter Dynamic Memory Size Requriements .................................................................... 31

Table 2.8 Supported RFCs and Limitations ........................................................................................................ 33

Table 3.1 Configurable Stack Parameters and Their Default Values ................................................................. 60

Table 3.2 Error Codes Generated by the Core Library ....................................................................................... 61

Table 4.1 Error Codes Generated by the UART Libraries .................................................................................. 65

Table 6.1 Error Codes Generated by the IPsec Libraries ................................................................................... 74

Table 7.1 Overview of IKEv2 Library Parameters and Properties ...................................................................... 76

Table 8.1 Error Codes Generated by the OTAU Library .................................................................................... 80

Table 10.1 STM32 Interrupt Vector Table ............................................................................................................ 90

Table 10.2 STM32 Default I/O Configuration........................................................................................................ 93

ZWIR451x Programming Guide

Cloud /

Internet

ZWIR45xx Device

Computer

ZWIR45

Gateway

LAN Router

Handheld Device

Specific Devices:

Off

the-Shelf

Components:

LAN

WANPAN

1 Introduction

This guide describes the u sage of the 6LoWPAN app lication programming interface ( API) for application development using ZWIR451x modules. These modules provide bidirectional IPv6 communication over an IEEE

802.15.4 wireless n etwork. Using IPv6 as the ne twork layer protocol allows easy integration of sensor or actor nodes into an existing Int ernet Protocol (IP) infrastructure with out the need for additional hard ware. Refer to the data sheet for the ZWIR451x module for detailed information about the module, including pin assignments.

Figure 1.1 ZWIR451x Application Domain

Figure 1.1 shows a t ypical network conf iguration. The Personal Are a Network (PAN) is built from a set of various ZWIR451x m odules. T he network is c onnected via a border router to the local are a net work (LAN) and from there to a wide area network (WAN) such as the Internet. With this setup, each module can be accessed from anywhere in the world with just its unique IPv6 address.

The radio nodes are t ypically organized in a m esh topology. Routing of IP packets over this topology is handled by the software stack tr ansparently for the user. T he network allows dr opping in new nodes or removing existing nodes without requiring manual reconfiguration. Routes to new nodes will be found automatically by the stack.

Application software runs on an STM32F103RC ARM® Cortex™ M3 ZWIR451x API. The MCU is clocked with up to 64 MHz and provides 256 kB yte flash memory and 48 kByte RAM, which allows the implementation of memory and computationally intensive applications. The API provides functions to communicate with remote devices, access different I/O interfaces, and support power-saving modes.

* The ARM® and Cortex™ trademarks are owned by ARM, Ltd.

microcontroller (MCU) on top of the

ZWIR451x Programming Guide

1.1. IPv6

IPv6 is the successor of the IPv4 protocol, which has been the major network protocol used for Internet communication over the p ast decades. One of the main advantag es of IPv6 over IPv4 is its huge addres s area, which provides 2

128

(about 3.4 x 1 038) unique address es. This enormous addres s space allows assignm ent of a globally unique IP address to every imaginable device that c o uld be connected to the Internet. Another a dv an tage with respect to sensor network s is the stateless address auto-configur ation m echanism, allow ing nodes to obtain a unique local or global IP address without requiring a specific server or manual configuration.

The use of IPv6 makes it possible t o connect sensor networks directly to the In ternet. Basically this is possible with other network protocols, too, but thos e require a dedicated gateway that translates n etwork addresses to IP addresses and vice versa. Usually this translation requires application knowledge and maintenance of the application state in the b order router, and therefore changing the border rout er software might be required with each application update. The protocol gateway might also introduce an additional point of attack if secure communication between devices inside and outside of the PAN is required.

IDT’s 6LoWPAN implem entation supports IPSec, which is the m andated standard for secur e communicatio n over IPv6. The use of IPv6 throughout the whole network allows real end-to-end security.

1.2. 6LoWPAN

IPv6 has been designed for high bandwidth internet infras tructure, which does not put significant co nstraints on the underlying net work protocols due to the vas t amount of mem ory, computing power, and energy. In contras t, the IEEE 802.15.4 stand ard is intended f or lo w data-r ate com m unication of de vices with ver y lim ited availability of all these resources. In order to make both standards work together, the 6LoWPAN standard (RFC 4944) has been developed by the Internet Engineering Task Force (IETF) to carry IP packets over IEEE 802.15.4 networks.

6LoWPAN adds an adaptio n layer betw een the link layer and network layer of the Open Systems Interc onnection (OSI) reference model. This layer performs compression of IPv6 and higher layer headers as well as fragmentation to get large IPv6 packets transmitted over IEEE 802.15.4 networks. The 6LoWPAN layer is transparent for the us er, and therefor e on 6LoW PAN devices, the IPv6 pro tocol is used i n exactly the sam e way as on native IPv6 dev ices. The presence of the 6LoWPAN adaption la yer does not restrict IP function ality. The user of a 6LoWPAN system does not recognize the existence of the 6LoWPAN layer.

1.3. Organization of this Document

Sections 2 to 7 cover the A PI documentatio n, which is divided into two parts. T he first part, c overed b y section 2 provides a functional descr iption of t he network s tack. It explains the cor relation of the different API func tions and provides background information about s tack internals . The second par t is the function ref erence and is co vered by sections 3 to 7. If familiar with the general stack functionality, the reader can simply use these sections to look up function signatures or basic usage information.

Section 8 explains how user applications can use the resources provided by the microcontroller and which resources are blocked by the operating system.

Terms set in bold monospace font can be clicked, activating a hyperlink to the section where a detailed definition of this term can be found.

ZWIR451x Programming Guide

2 Functional Description

The following subsecti ons give a generic overview of the different func tionalities of the firmware delivered with ZWIR451x modules. Background information is provided if required for proper use of the libraries. Usage recommendations are gi ve n f or optimal performance in cert ain app lic at ion configurations. A de tai le d des cr ip tion of the functions, types, and variables available for application programming is given in sections 3 through 7.

2.1. Requirements Notation

This document uses s everal words to i ndicate the requirements of IDT’s 6LoWPAN stack implem entation. The key words M

PTIONAL, set in italic small caps letters denote requirements as described below

UST, SHALL, REQUIRED These words denote an a bsolute requirem ent of the im plem entation. Disregardi ng these

requirements will cause erroneous function of the system.

UST NOT, SHALL NOT These phrases mean that something is absolutely prohibited by the implementation.

Disregarding these requirements will cause erroneous function of the system.

HOULD, RECOMMENDED These words descr ibe best practice, b ut there might be reasons to disregard it. Before

ignoring this, the implications of ignoring the recommendation must be fully understood.

UST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY and

HOULD NOT, NOT RECOMMENDED These words describe items that can impair proper behavior of the system

when implemented. H owever, there might be reasons to ch oose to implement the item anyway. Implications of doing so must be fully understood.

AY, OPTIONAL T hese words describe items which ar e optional. No misbehavior is to be expected when these

items are ignored.

2.2. Terms

This document distingu ishes between t hree types of functions: h ooks, callbacks , and API functions. Basically, all three types are def ined as normal f unctions in the pro gramming language C, b ut they differ in the way that they are used.

API Functions are functions which are defined and implemented by IDT’s 6LoWPAN stack. They provide a functionality that can be ac cessed b y the user code. T he declarations of API func tions are provi ded in the he ader file belonging to the library in which the function is implemented.

Hooks are functions that provide the user the abil ity to extend the default behavi or of the stack . They are called from the operating system (OS) to give the application the op portunity to im plement custom features or reactions to events. The oper ating s ystem provides a defau lt implem entation of the h ook that is cal led if no c ustom hook is defined. The protot ypes of all available h ooks are defined in the header file b elonging to the libr ary in which the default implementation is loc ated. ZWIR_AppInitNetwork and ZWIR_Error are examples of hooks.

Callbacks are also called from the operating system, but they must be registered explicitly at the OS. The function may have a custom name, but the signature m ust be matching. Cal lback functions are register ed at the OS using API functions. O ne example for a function expecting a cal lback is ZWIR_OpenSocket. In contrast to hooks, callbacks do not have default implementations. For each callback function, there is a type declaration declaring how the signature of the user function should look.

ZWIR451x Programming Guide

variableName, functionArgument

FunctionName

TypeName_t

PREPROCESSOR_MACRO

2.3. Naming Conventions

For better readability of the code, all user accessible func tions and types of the API comply with a set of nam ing conventions. Each identif ier that is an element of the API is prefixed with “ZWIR_.” Function, variable, function argument and type identifiers are defined using “CamelCase” style. This means that each single word of a multiple word identifier star ts with a capit al letter. The rem aining letters of the wor d are lower case. Prepr ocessor macros are defined using all capital letters.

Different style rules apply to func tions, variables , and types definitions . Function-name and type-name identifiers start with a capital le tter in the first word, while variab le identifiers start with a l ower case letter in the first wor d. Type names have an add itional “_t” suffix. Varia ble names and function ar guments are not diff erentiated in the naming conventions.

Table 2.1 Naming Conventions Used in C-Code

Identifier Type Style

First word starts with lower case, all other words with capital letters. All words start with capital letters (“CamelCase”). All words start with capital letters and name ends with “_t” s uffix. All letters are capitalized.

2.4. Library Architecture

ZWIR451x modules are f reely programmable by means of an API that is im plemented in a set of libraries. The libraries provide different functionality and can be linked into the user program. The use of the core library is mandatory, as it pro vides t he operat ing s ystem and a ll gener ic comm unication functional ity. All other l ibraries are optional and can be link ed depending on the requ irements of the target ap plicatio n. Each libr ary exposes a set of functions and types that are required to im plem ent the desired func tionalit y. The librar y architectur e is depic ted in Figure 2.1.

To make programm ing as easy as poss ible, t he librari es m ake use of an event and c omm and approac h wher ever possible. Using th is approa ch, applic ation code is not required t o poll f or data o n the dif ferent inter faces. Ins tead, newl y available data is pas sed to user-defined callback functions automatically. Timer hooks and callbacks are available, and they are automatically executed periodically or after expiration of a user-defined time interval.

Linking the library without any additional code will result in a valid binary that can be programmed on a radio module. Such binaries will not provide user-specific functionality. However, the nodes relay packets in mesh networks and respond to ping requests . In order to add functionality, several functions that have empty default implementations can be defined by the user.

ZWIR451x Programming Guide

Figure 2.1 Library Architecture

2.5. Operating Modes

The API provides thr ee operating modes: Devic e Mode, Gateway Mode and S niffer Mode. The modes di ffer in how many of the protocol layers are pr oces s ed b y the net work s tack. All other API functionalit y rem ains the s ame. Setting the operatin g m ode of a n ode must be done b efore an y ini tiali zation of th e API and th e hard ware. F or th is purpose, the ZWIR_SetOperatingMode function is provided. Figure 2.2 shows how applicat ion code interfac es into the network stack in diff erent operating modes. A description of the three different modes is provided i n the next subsections.

2.5.1. Device Mode

The Device Mode is preconf igured since this is the most commonly used mode for ZWIR451x modules. Each node with sensing or acti ng f unc tiona lity should use this operati ng mode. Full protocol proces s ing is p er f orm ed for incoming and outgoing data. This means that all header inform ation is removed from incoming Us er Datagram Protocol (UDP) pac kets and onl y payload dat a is passed to the applicat ion. Accor dingly, the ap plication on ly has to provide payload da ta tha t should be s ent ov er the net work. T he stack automaticall y adds all necess ary header information.

Device-configured devices behave as normal IPv6 devices. Theref ore address auto-configura tion and neighbordiscovery is performed as defined by the IPv6 standard. Data are sent and received over UDP sockets. The functions ZWIR_SendUDP and ZWIR_SendUDP2 serve as an interface to the network stack. Incoming data is passed to an application callback that must be registered when a socket is opened using ZWIR_OpenSocket.

ZWIR451x Programming Guide

April 12, 2016

ZWIR_SendUDP(2)

ZWIR_Send6LoWPAN ZWIR_OpenSocket

ZWIR_SetOperatingMode

Figure 2.2 Application Interface into the Protocol Stack in Different Operating Modes

2.5.2. Gateway Mode

The Gateway Mode is i ntended for use with modules that should work as protocol gate ways. Protocol gat eways change the physical media used for IPv6 pack et tr ans mission. This enables the i ntegration of 6LoWPAN networ ks into Ethernet-based IPv6 networks for example.

In contrast to the Device Mode, not all ne twork layers are pr ocessed in Gateway Mode . For any IPv6 pack et that is received via the air interface, o nly the 6LoWPAN-s pec ific m odif icatio ns of the h eader s are r emoved, resulting in a packet containing all IPv6 and higher layer headers. This packet is passed to the receive callback function. Accordingly, all data that need to be sent over the network are assumed to have valid IPv6 and higher layer headers. Only 6LoWPAN-specific modifications will be applied to outgoing packets.

Gateway-configured device s do n ot per form addres s auto-configuration and neighbor-disc over y as d efined b y the IPv6 standard. Moreover no router solicitation and router advertisement messages are generated automatically.

To enter the Gatewa y Mode, ZWIR_SetOperatingMode must be called from ZWIR_AppInitHardware. It is not possible to call ZWIR_SetOperatingMode from any other loc ation in the cod e. ZWIR_SetOperatingMode accepts a callback f unction that is called u pon reception of data in the gat eway. Sending data is accom plished using the function ZWIR_Send6LoWPAN.

2.5.3. Sniffer Mode

The Sniffer Mode is provided to al low observation of raw network traff ic. No protocol processing is perform ed. Thus the data passed to the application layer includes all header information. In contrast to the two other operating modes, all packets received over the air interface are passed to the application, regardless of the address to which the packet has been sent. This also includes MAC layer packets.

ZWIR451x Programming Guide

April 12, 2016

Sniffer Mode is useful for debugging purposes. It can be used to find out which devices in the network are transferring packets and which are not. Sniffer Mode devices do not generate any network traffic—not autonomously or user trig gered. That is why there is onl y an interfac e from the s tack to the app lication co de, but not vice versa.

To enter Sniffer Mode , call ZWIR_SetOperatingMode ( ZWIR_omSniffer, YourCallbackFunction ) f rom ZWIR_AppInitHardware. The functions ZWIR_Send6LoWPAN, ZWIR_SendUDP and ZWIR_SendUDP2 do not function in this mode. However, it is sti ll possible to chang e the physical chan nel and the modulati on scheme of the transceiver by calling ZWIR_SetChannel and ZWIR_SetModulation.

2.6. Operating System

The operating system is ve r y light-wei ght and does not pro vide m ulti-threading. This means that any user-defined function that is called from the operating system is completely executed before control is passed back to the operating system. Therefore, the user is re quired to write cooper ative code. User s must be aware that f unctions requiring long execution t ime will bloc k the operating system kernel and m ight cause the kernel to m iss incoming data, regardless of whet her they are received over the air or any wired interface.

2.6.1. Initialization

During the operating system initialization phase, the different libraries and the MCU peripherals required for system operation are initialized. Startup initialization is done in two phases, each with its own hook for user application code. During the firs t phase, the internal clocks and the periphera ls used by the stack are initialized and the random number generator is seeded. Also peripherals requ ired by certain libraries are initia lized if the corresponding librar y is link ed int o the proj ect. Af ter thi s, the ZWIR_AppInitHardware hook is call ed if present, enabling application code to initialize any additional hardware. The application can initialize its I/Os and peripherals in this function. ZWIR_SetOperatingMode must be called from here if the Gateway Mode is required. Sending data ov er the network or initiali zing network sock ets is not possible from here, as the network stack is not in itialized. However, func tions controlling t he physical parameters of the network (e.g. , output power or physical channel)

SHOULD be called from here.

During the second phase, the transceiver and the net work stack are initialized. If the Norm al Mode is selected, duplicate address detec tion (DAD) is also started and r outer information is solicited. DAD chec ks if the address given to the m odule is uni que on t he link . After finishing network init ializa tion, ZWIR_AppInitNetwork is called. Application code can do its r emaining initializati on tasks such as setting up sockets at this po int. Since DAD and router solicitation are started before the call to ZWIR_AppInitNetwork, it is recommended that physical parameters of the network are set up first in ZWIR_AppInitHardware. This ensures that DAD and RS are performed on the correct channel with correct settings.

2.6.2. Normal Operation

During normal operation, t he operating system collects events f rom the different peripherals an d the application and handles them acc ording to their priorit y. Event pro cessing prior ities are f ixed and cann ot be change d. Events are processed highest prior ity first; the lowest num ber represents the highest priority. Table 2.2 lists all even ts with their priorities and triggered actions.

ZWIR451x Programming Guide

April 12, 2016

ZWIR_Main10ms

ZWIR_Main100ms

ZWIR_Main1000ms

Table 2.2 Event Processing Priority in the Main Event Loop

Priority Event Triggered By Effect

0 Application Event 0 Application Code Call user-defined callback function 1 Transceiver Event Transceiver Interrupt Request Process transceiver request 2 Application Event 1 Application Code Call user-defined callback fun c tion 3 Callback Timer Expired SysTick Controlled Software Timer Call user-defined cal lba ck fun c tion 4 Sleep Requested Software Sleep for the requested time 5 Received Data on UART1 UART1 Interrupt Call user-defined callback fun c tion 6 Application Event 2 Application Code Call user-defined callback function 7 10ms Timer Expired SysTick Controlled Software Timer

Call 8 100ms Timer Expired SysTick Controlled Software Timer 9 1000ms Timer Expired SysTick Controlled Software Timer

10 Application Event 3 Application Code Call user-defined callback fun c tion 11 Received Data on UART2 UART2 Interrupt Call user-defined callback function 12 Sending Data Failed due to

Resource Conflict

13 Application Event 4 Application Code Call user-defined callback func tion

Network Stack Retry sending

Call

The operating system provides five application eve nt handlers that can be used to process applicat ion events in the context of the operating system scheduler. Application event handlers

SHOULD be used to react to

asynchronous events requiring computationally intensive processing. Interrupts are a typical example for such events. If an interrupt occurs, the int errupt servic e routine (ISR) c an trigger an e vent and de lay the process ing to an appropriate time. This ensures that multiple asynchronous events are handled in the order of their priority, without blocking interrupts.

Application events are triggered by calling ZWIR_TriggerAppEvent with the corresponding event number (0 through 4). When the OS scheduler reaches the user-triggered event, an application callback function is executed. Multiple cal ls to this function before the cor responding application callback is invok ed will not cause multiple invocations of the application callback.

For each application event, an event handler callback function must be registered using ZWIR_RegisterAppEventHandler. If no event handler is registered f or a certain event, triggering this event has no effect. In order to change an ev ent handler, ZWIR_RegisterAppEventHandler must be called agai n with the new handler. Unregistering event hand lers can be performed by calling the r egistration function with a NULL callback argument.

ZWIR451x Programming Guide

April 12, 2016

2.6.3. Power Modes

The stack support s different modes to r educe the power c onsumption of the de vice. In Active Mode, all module features are available. The Sleep, Stop, and Standby Modes reduc e the power consum pt ion by disabli ng dif fer ent module functionalit ies. Eac h of the power-saving modes affec ts the behav ior of the M CU and t he transc eiver and supports different wake-up conditions.

Table 2.3 Power Modes Overview

Mode Wakeup Clock Context1) I/O Transceiver

Source Time MCU Core Peripherals

Active On On 2) Retained As configured On 3)

Sleep Any IRQ 1.8 µs Off On 2) Retained As configured Off 4)

Stop

Standby

Refers to the status of the RAM and peripheral register contents after wakeup – the backup registers of the MCU are always

Clock is enabled for all peripherals that have been enabled by application code and all peripherals that are used by the library.

Can be powered off by application code.

Remains on if peripheral/transc eiver is sel ect ed as wakeup source.

RTC IRQ External IRQ

RTC IRQ Wakeup P in

available.

5.4 µs Off Off Retained As configured Off

50 µs Off Off Lost Analog input Off

Active Mode is entered autom atically after startup. In this mode, the MCU core and all p eripherals used by the application are run ning and all functionality is a vailable. The transceiver is t ypically on but can be switched off explicitly by a call to ZWIR_TransceiverOff. This mode has the highest power consumption.

In Sleep Mode, the MCU core is disa bled bu t the MC U perip hera ls are stil l functioning if required. The trans c eiver can be switched on or off. Mem ory contents and I/O s ettings remain in the stat e that was active at the activa tion of the Sleep Mode. Waking up from Sleep Mode is possible on an y MCU interrupt. After the wakeup event, the stack continues executio n at the position it had been s topped. The power consu mption in Sleep Mode is slightl y reduced compared to Active Mode. If more signific an t r eductio n of the power consumption is required, the Stop or Standby Modes should be considered.

Stop Mode provides significant reduction of power consumption while still providing a short wakeup time and context saving. Dependi ng on the application’s requirements , the transceiver could rem ain enabled to wake up the module when a packet comes in (set the trans ceiver as the wak eup source). By default, the tra nsceiver is disabled in Stop-Mode. The MCU core and al l periph er als of the MC U are dis able d in Stop Mode. Wakeup is onl y possible by the built-in real-time clock (RTC) or an external interrupt, triggered at any GPIO l ine. For that, the external interrupt must be configured appropriately.

Standby Mode is the lo wes t po wer mode. In this mode, the MCU is po were d of f and the tr ans ce iv er is on s tan db y. Only the MCU’s internal RT C is running, serving as a wakeup source. Additionall y, the external wakeup pin can be used to wake up the module. Aft er wakeup, the memory contents of the MCU ar e l ost and must be rei nit i alize d the same as after normal power-on.

ZWIR451x Programming Guide

April 12, 2016

Any of the low power modes is entered by calling the function ZWIR_PowerDown. It can be chosen whether power-down is delayed until all pending events are processed or not. If delayed power down is chosen, the power-down procedure can be aborted by a call to ZWIR_AbortPowerDown. The wakeup sources for the different power modes are configured by ZWIR_SetWakeupSource.

2.6.4. Error Handling

The stack performs error handling in two dif ferent ways. The firs t is simply to reset the ch ip if an unrecoverable MCU exception occurs that caused an interrupt. For errors that ar e not caused by MCU exceptions, the stack provides a default handling, which may be overwritten by the application code.

The error handlers perfor ming a system reset are trigg ered by one of the interrupts listed i n Table 2.4. The reason for resetting the whol e system is that in the case of no rmal operat ion, none of the liste d interrupts s hould ap pear. However, if different beh avior is desired, it is possible to overwrite the d efault implementation by providing the user’s own interrupt service routines. See section 10.3 for details.

Table 2.4 Interrupts that Result in a System Reset

Resetting Interrupts

Non-maskable Interrupt Hard Fault Memory Management Bus Fault Usage Fault Programmable Voltage Detector

In the case of a r ecoverable error , the ZWIR_Error hook is called by the opera ting system . The error num ber is passed as a function argument. In order to provide custom error handling, the application

MUST provide an

implementation of ZWIR_Error. T he return value of the func tion determ ines whether th e error has been handl ed by the application (return true) or if the default handler will be executed (return false).

2.7. Firmware Version Information

The ZWIR451x API provide s the capability of includin g firm ware version inf ormation in the s tack. This information can be requested remotel y af ter wards an d is required by the F irmware Over-the-Air Update Library. The complete firmware version cons ists of the Vendor ID, the Firm ware ID, the Major Firmware Versi on, the Minor Firmware Version, and the Firmware Version Ex te ns io n. T hes e c omponents are defined in t he ap plication code using g lob al variables. The role of the different components is explained in the following subsections.

In addition to t he firm ware versio n inf ormation m entio ned abo ve, the s tack provides addit ional ver sion i nformation for the library t o whic h the application was link ed. This vers ion inform ation consist s of Major Stack Version, Min or Stack Version, and Stack Version Extension field.

ZWIR451x Programming Guide

April 12, 2016

2.7.1. Vendor ID

The Vendor ID is a 32-bit num ber that identifies the c ompany that developed the device firm ware. A Vendor ID must be requested from IDT. Each company must obtain its own Vendor ID before placing products on the market. The Vendor ID is set using the global varia ble ZWIR_vendorID. If this variable is not set, the firmware will use the Vendor ID E966 firmware.

, which is reserved for ex perim ental purpos es and mus t not be used f or production

HEX

2.7.2. Product ID

The Product ID is a 16-bit num ber identifying the pro duct firmware. It is espec ially important for the Ov er-the-Air Update functionality but could also serve for remote identification of the device type. Refer to the ZWIR451x Application Note – Enabling Firmwar e Over -the-Air U pdates for more inf ormation about th e role of the Produc t ID in IDT’s Over-the-Air Update Library.

The Product ID is set by defining the global variable ZWIR_productID. If this variable is not def ined, the value will be read as zero.

2.7.3. Major Firmware Version

The Major Firmware Vers io n is a version inform ation f i el d that is freely us ab le f or app lic at ion pur pos es . It is s et by defining the global vari able ZWIR_firmwareMajorVersion. If this variab le is no t def ined, the value will be read as zero.

2.7.4. Minor Firmware Version

The Minor Firm ware Ver sio n is a vers ion i nf ormation field that is freely usable f or application purposes. It is set by defining the global vari able ZWIR_firmwareMinorVersion. If this variab le is no t def ined, the value will be read as zero.

2.7.5. Firmware Version Extension

The Firmware Version Ext ension is a version information fie ld that is freely usable for application purposes. It is set by defining the glo bal var iable ZWIR_firmwareVersionExtension. I f this vari able is n ot d efined, the value will be read as zero.

2.7.6. Library Version

IDT’s firmware stack libraries have their own vers ion information included. This inf ormation is compiled into the binary libraries and can be requested by the application c ode using the function ZWIR_GetRevision. Like the firmware version, the library version consists of the major and minor versions as well as extension information.

2.8. Addressing

Each module has t hree types of addresses : a PAN id entifier, link layer address, and network layer address. This section describes the different address types and explains how they are used in the stack.

ZWIR451x Programming Guide

April 12, 2016

2.8.1. Address Types

The PAN identifier (PANId) is a 16-bit-wide number carrying an identifier of the network. Each device in the same network must have the same PANId. Nodes wit h differ ent PANIds cannot comm unicate. A defau lt PANId is preprogrammed in the network stack. The current PANId can be requested or changed using the functions ZWIR_GetPANId and ZWIR_SetPANId, respectively. The default value is ACCA

The link la yer address is also ref erred to as the M AC address or P AN address. This addres s is used by the lower communication la yers and does not need to be handled directl y b y the user. The link layer addr ess must be unique in the network . Each ZWIR451x module has a predefined, hardw are program med address that is globally unique. The PAN address is 64-bits-wide. It can be requested and changed by the functions ZWIR_GetPANAddress and ZWIR_SetPANAddress. Changing the PAN address is not recommended as thi s could cause problems as described in section 2.8.4.

The third address t ype is the net wo rk layer add ress, which is equiv alent t o the I Pv6 Addres s. T hese addr esses are 128-bit-wide. They are us ed by the applicat ion to determ ine the destin ation that pack ets should be sen t to or the source packets should be received from. Each device needs at least one IPv6 address to be reachable. However, multiple a ddresses can be ass igned to each no de. IPv6 ad dresses assigned to a node m ust be unique on the network. However, typically users do not need to handle IPv6 address assignment. IPv6 provides a mechanism that performs automatic address configuration. This mechanism is explained in section 2.8.3.

HEX

2.8.2. IPv6 Addresses

IPv6 addresses are 128-bit and therefore 16-bytes wide. As it woul d be impractical to us e the byte-wise notation known from IPv4, IP v6 introduces a new nota tion. IPv6 addr esses are represented b y eight 16-bit hexadecim al segments that are separated by colons. An example for such address is

2001:0db8:0000:0000:1b00:0000:0ae8:52f1

The leading zeros of segm ents can be omitted as they do not car ry information. Furthermore the IPv6 not ation allows om itting a sequence of zero segment s and representing it as double c olon. With these rules, the above address can be written as

2001:db8::1b00:0:ae8:52f1 or 2001:db8:0:0:1b00::ae8:52f1

However, replacing multiple zero segments is not allowed, so the following address is invalid:

2001:db8::1b00::ae8:52f1

An IPv6 addres s consist s of two components: a prefix and an int erface iden tifier. T he prefix s pecifies the network that a device is part of; the interface ide ntifier specifies the interf ace of a device. A node with multiple ne twork interfaces has multip le interface identifiers. The si ze of the prefix varies f or different address types. In the IPv 6 address notation, t he prefix length can be appe nded t o the addres s w ith a slas h f ollowed b y the num ber of pr efix bits. For example, th e notation 2001:db8::/64 re presents a network c ontaining the addresses from 2001:db8:: to 2001:db8::ffff:ffff:ffff:ffff.

IPv6 supports three kinds of addressing methodologies: unicast addres sing, multicast addressing, and anycast addressing. Unicast and multicast addresses differ in how the pref ix is formed. Anycast addres s es can be used as target addresses and are handled like unicast addresses.

ZWIR451x Programming Guide

April 12, 2016

Prefix

Interface-Identifier

127 64 63 0

Prefix

Multicast Group ID

127

111 0

0xff

Scope

Flags

Unicast addresses are s hown in Figure 2.3 and use 64 bits each f or the pref ix a nd the inter face ide ntifier. Unicas t addresses exactly ide ntify one single interface in a net wor k . T he prefix of the address determines the s cope of the unicast address. If the pr efix equals fe80::/64 this is a link-local unicas t address. Link local addresses are valid only on the single link a node is c onnec te d to. The prefix of global unicast addr es ses is rec eived via ad dres s autoconfiguration from a r outer that is conn ected to the Int ernet. Ther e are addition al prefix configuratio ns with lim ited scope that are not covered by this documentation.

Figure 2.3 IPv6 Unicast Address Layout

Multicast addressing allows sending out a single packet to multiple receivers. For this purpose, IPv6 provides multicast addresses. A multicast address can only be used as the destination address, never as the source address of a pack et. The la yout of a m ulticast addres s is shown in Figure 2.4. Multicast a ddresses h ave a 16-bit prefix with the most significant 8 bits set to FF

, followed by two 4-bit fields for flags and the scope of the

HEX

multicast packet. The remaining bits specify the multicast group ID.

Figure 2.4 IPv6 Multicast Address Layout

In this document, it is assumed that the f lags field is a lways either 0000 multicast address is a wel l-known address . 0001

m arks the address as a tem porarily assigned ad dress that is

BIN

or 0001

BIN

. 0000

specifies that the

BIN

not specified by Internet s tandards. These addr esses must be used for custom multicast addres sing. The scope field is always assum ed to be 0010

, representing the link-local scope. Other scopes are us able but must be

BIN

supported by routers. Two specific addresses shoul d be noted as these are used very often. M ore information about their us e can be

found in section 2.9.2.

1. The unspecified address :: All segments of this address are zero. It is used by receivers to listen to any sender. This address must never be used as destination address.

2. The link-local all nodes multicast address ff02::1 Packets sent to this address are received by all nodes in the network, so this multicast address is equivalent to broadcasting.

For more detailed information about IPv6 addressing refer to RFC 4291

– “IP Version 6 Addressing Architecture.”

ZWIR451x Programming Guide

April 12, 2016

2.8.3. IPv6 Address Auto-configuration

IPv6 provides a stateless address auto-configuration mechanism. This mechanism allows the configuration of node addresses from information that is statically available on the node and information provided by routers. Router information is only require d if global communication is required . Addresses for link-local comm unication can be derived from the link-layer address. This removes the need for manual configuration of addresses or dynamic host configuration protocol (DHCP) servers in the network.

The local information used f or auto-configuration is the interf ace EUI-64 address. T he EUI-64 address is a factor y programmed link-layer address that IDT guarantees to be unique for each m odule. The EUI-64 address is often referred to as the MAC address. During network initialization, each node generates a unique link-local IPv6 address by putting the pref ix fe80::/64 in f ront of the EUI -64 address with bit 1 of the most significant EUI -64 byte inverted. Assuming a link -layer address of 00:11:7d:00:12:34:56:78, the gen erated link-local IPv6 a ddress would be fe80::211:7d00:1234:5678.

It is possible to switch off the link-local address generation by setting the stack parameter ZWIR_spDoAddressAutoConfiguration to zero before the stack initialization.

In addition to link-local address generation, nodes request router information during startup seeking a global prefix for building a glo ba ll y va lid addr es s. Those requests ar e cal le d r ou ter s o lici tat ions . Routers present on t he link will respond to router solicitation messages of the node with router advertisements containing global prefix information. Taking this prefix and the EUI-64 address of the node, a global address is generated in the same way as for the link-local address. Router solicitation is done automatically during the startup phase.

If there is no router o n the link, no global address will be ass igned and onl y link -local communicatio n is poss ible. In this case, the router solicitation messages can be suppressed by setting the stack parameter ZWIR_spDoRouterSolicitation to zero.

A host cannot rely on a generated address being unique, as there might be manually configured EUI-64 addresses on its link . Therefore, it must perf orm “duplicated address detec tion” (DAD) to be sure the gener ated address is unique. Duplica te address detection is mandatory for each ad dress being attached to a node and is performed automatic ally b y the networ k s tack. It is des cribed i n m ore detail i n the f ollowing sec tion. Each ad dress being assigned to an interf ace is subject to duplicat e address detection. Addresses are not vali d until duplicate address detection (DAD) is completed. Devices are not ab le to send or receive pac kets using a unicast ad dress that has not been v alidated to be unique. After devic e startup (and therefore after assignm ent of the link-local unicast address), the net work s tack calls the hook ZWIR_AppInitNetworkDone, s igna ling that D AD on th e link local address has been c ompleted and the addres s can be used. Applicati ons should use this hook to send out initial packets.

2.8.4. Validation of Address Uniqueness

After a node has configur ed its own addr ess , it per forms Duplicate Address Detection (DAD) to check if the ne wly configured IPv6 address is unique on the link . For this purpose, the no de starts to s end neighbor s olicitation (NS) messages to the address to be checked (to its own address). If another node rep l ies to one of those messages or if another node also se nds neighbor solicitation m essages to this address, the assigne d address is not unique and must not be used. In this case, the error handler hook ZWIR_Error is called with the error code ZWIR_eDADFailed. It is up to users to provide their own error handling mechanism for such cases.

ZWIR451x Programming Guide

April 12, 2016

Assign

link-

address

Perform network

initialization

& DAD

DAD failed?

yes

Start

Normal Operation

The default implem entatio n prov ide d in t he library only r em oves t he f ai ling ad dr ess from the interface. If the failing address was the only address of the module, the module will not be reachable.

Figure 2.5 Resolving Address Conflicts in L o cal Networks

Application code ca n try to resolve the address conflict. One possible solution is t o manually change the l ink-layer address of the node, using random numbers or a dedicate d algorithm. ZWIR_SetPANAddress m ust be called with the new address and the network initialization must be restarted. This is done by calling ZWIR_ResetNetwork. The procedure can b e repeat ed f or an arbit rar y number of tim es until a un ique a ddr ess is found.

Note that a duplicate address problem should not appear if each module in the network uses the factory programmed link-layer address. In this case, the link-layer address is guaranteed to be globally unique. Therefore, using the user’s own addresses is not recommended. For some applications, the user knows that there are no duplicate a ddresses in the network. In such cases, the duplicate address detection mechanism can be disabled by setting the stack parameter ZWIR_spDoDuplicateAddressDetection to zero. This has the positive side effec t of the immediate abilit y to send and receive pack ets using the user’s own IPv6 address(es ). Furthermore, less traffic is generated on the network.

ZWIR451x Programming Guide

April 12, 2016

2.9. Data Transmission and Reception

Data are transmitted us ing the User Datagr am Protocol (U DP). If a destination node is not directl y reacha ble f rom the source node, pack ets ar e routed ov er inter m ediate nodes autom atical ly. Rout e setup is done tr anspar entl y for the user. The following subsections describe the different aspects of data transmission and reception.

2.9.1. User Datagram Protocol

The User Datagram Pr otocol is used for data communication. UDP is a connectionless and lightweight protocol with the benefit of m inimal communication and pr ocessing overhead. No conn ection has to be created, and no network traffic is required before data transmission between nodes can be started. Instead, communication is possible immediately. However, UDP does not guarantee that packets that have been sent are reaching the receiver. It is also possible that a single UDP p acket is rec eived multiple tim es. Furtherm ore, it is not guara nteed that the receiving order of packets at the des ti nat io n is the s ame as the sending order at th e s ourc e. This must be considered by the application programmer.

UDP uses the concept of ports to distinguish different data streams to a node. 65535 different ports can be distinguished in UDP. A port can be seen as the address of a service running on a node. Depending on the destination port of a pac ket, the network s tack dec ides to which service th e packet is routed on the receiver n ode. In IDT’s 6LoWPAN stack, services that provide the callback f unctions to which network packets are passed are running in the application code. Each service has its own callback function.

2.9.2. Data Transmission and Reception

Data transmission is requested by calling ZWIR_SendUDP or ZWIR_SendUDP2. Both functions send a single UDP packet to a remote hos t. ZWIR_SendUDP2 accepts the address an d port of the remote device as a parameter, while ZWIR_SendUDP requires a socket handle specifying the des tination parameters. For reception of d ata, a socket is required as well.

A socket is an object that stores the addres s of a remote device and the rem ote and local UDP ports used for communication. It can be seen as an en dp oin t of a uni dir ecti ona l or bi dir ecti on al c om munication flow. Additionally, it is possible to spec ify a callback that is called when data is received over the socket. Soc kets are opened and closed using the API func tions ZWIR_OpenSocket and ZWIR_CloseSocket. The maximum number of sockets that can be open in parallel is defined by the stack parameter ZWIR_spMaxSocketCount.

Four parameters must be provided when a socket is opened:

• IPv6 address of the remote communic ation endpoint: This is the addres s that data should be sent to a nd/or received from. Data r eception is only possi ble if the remote addres s is a unicast address or the unspec ified address. If a multicast address is provided, only data transmission is possible.

• Remote UDP port: This is the UDP port that data are sent to. For reception of data, this port is ignored.

• Local UDP port: This is the UDP port that data are rec eived on. Onl y packets that are sent to this po rt wil l be

handled in the callback function. If this number is 0, no data is received.

• Receive callback function: This is a pointer to a function that is called when data from a remote device is received. If no data should be received, this pointer can be set to NULL.

The choice of whether ZWIR_SendUDP or ZWIR_SendUDP2 should be used for communication de pends on the characteristics of the ne twork traffic between t he comm unicating dev ices. ZWIR_SendUDP2 is intend ed to send a

ZWIR451x Programming Guide

April 12, 2016

few packets to a rem ote device without expecting a r esponse from the target device. The func tion accepts the remote address and UDP port together with the data to be sent. Internally the function will open a temporary socket that is imm ediately closed after sending out the pac ket, so a slight overhead is ad ded. ZWIR_SendUDP2 functions even if the maximum number of sockets is open. ZWIR_SendUDP must be used in cases where responses are expected from the remote device or data must be transmitted frequently.

The following subsecti ons will explain unicast an d multicast communication in m ore detail and give exampl es of how to use the IPv6 addresses and ports appropriately.

2.9.2.1. Unicast

Traffic that has only a single dest ination node is called unicast traff ic. In order to send data unicast, t he sender must open a sock et with the rem ote address set to the IPv6 addr ess of the intended receiver. The receiver must open a socket with the remote address f ield set to the s ender’s IPv6 addr ess or to the uns pecified addr ess. The sender socket rem ote port field must match the receiver socket local port field in both cases. Table 2.5 shows some example socket configurations and notes whether communication is possible or not.

Table 2.5 Unicast Socket Examples

fe80::1:1:1:1

Rem. Addr.: fe80::2:2:2:2 Rem. Port: 55555 Local Port 44444

Rem. Addr.: fe80::1:1:1:1 Rem. Port: 44444 Local Port 55555

fe80::2:2:2:2

Rem. Addr.: fe80::1:1:1:1 Rem. Port: 44444 Local Port 33333

fe80::2:2:2:2

Rem. Addr.: Rem. Port: 44444 Local Port 55555

fe80::3:3:3:3

Rem. Addr.: fe80::1:1:1:1 Rem. Port: 44444 Local Port 55555

Sender Recipients

A B receives packet. (Remote address and remote port of A match interface address and local port of B.)

C does not receive packet. (Remote port of A does not match local port of C.) D receives packet. (Remote address of D matches all addresses; local port of D matches remote port of A.) E does not receive packet. (Remote address of A does not match interface address of E.)

B A receives packet. (Remote address and remote port of B match interface address and local port of A.)

No other socket receives packet. (Interface addresses do not match remote address field of B; local ports do not match remote port of B.)

C A receives packet. (Remote address and remote port of C match interface address and local port of A.)

No other socket receives packet. (Interface addresses do not match remote address field of C.)

D E

No socket receives packet. (Sending is not possible with an unspecified address as the destination.) No socket receives packet. (Remote addresses of sockets A, B, and C do not match interface address of E;

local port of D does not match remote port of E.)

ZWIR451x Programming Guide

April 12, 2016

02:x:x:x:x:x:x:x

55555

44444

12:x:x:x:x:x:x:x

2.9.2.2. Multicast

Multicast is used t o send data to multipl e nodes at the same tim e. For a multicast transmis sion, the sender must open a socket with the r em ote addres s s et to a m ulticas t IPv6 a ddress. The s emantic s of ports is the sam e as for unicast comm unication. The receiver must open a sock et with the r emote addres s set to the I Pv6 address of the sender or to the unspec if ied ad dress . Note that a sock et with a m ulticast r em ote address cannot be used f or data reception.

IDT’s implementation of the IPv6 multicast feature does not support explicit assignment of multicast groups to single nodes. Instead, if a packet is received that was sent to a temporary multi cast address, the hook function ZWIR_CheckMulticastGroup is called by the network stack. This function must be implemented by the application code in order to use the multicast feature. The application can check the multicast group of the destination address and decide if it is part of it. This mechanism allows very flexible and application-tailored multicast addressing schemes. If the application does not pro vi de th e ZWIR_CheckMulticastGroup, tem por ary multicast addresses are rejected by the stack.

Table 2.6 Multicast Addressing Examples

fe80::1:1:1:1

Rem. Addr.: ff02::1 Rem. Port: 55555 Local Port 44444

Rem. Addr.: ff Rem. Port: Local Port

fe80::1:1:1:1

Rem. Addr.: ff Rem. Port: 55555 Local Port 44444

fe80::x:x:x:x

Rem. Addr.: fe80::1:1:1:1 Rem. Port: x Local Port 55555

fe80::x:x:x:x

Rem. Addr.: Rem. Port: x Local Port 55555

Sender Recipients

D and E receive packet. (Remote address matches interface address of A; local port of D and E matches remote port of A.)

No socket receives packet. (If multicast group ID is not 1, packets are dropped by the receiver as wellknown addresses must not be used by applications.)

D and E receive packet if multicast group ID resolution is implemented in user code and returns “true.” (Remote address of C is temporary link-local multicast group; local ports of D and E match remote port of C.)

2.9.3. Address Resolution

Before unicast data can be tr ansmitted from one device to another, the sending node must determine the linklayer address of the rec eiver. T his is c alled address resolutio n and is done auto maticall y by the sender ’s n etwork stack, using the neighbor d iscovery protocol (NDP). NDP repl aces the address resolutio n protocol (ARP), which was used in IPv4 networks. Address resolution starts on demand and is transparent to the user.

If a data packet is to be sent to a receiver for which the link-layer a ddress is not known, the s ender performs address resolution to f in d t he link-layer address of the rec ei ver. The result is add ed to t h e n eig hb or c ac he a nd the data packet is sent out. The maximum size of the neighbor cache is configurable using the stack parameter ZWIR_spNeighborCacheSize. Note that changing this parameter at runtime will res ult in the loss of all cache entries, regardless of whet her the neighbor cache size is increased or decreased.

ZWIR451x Programming Guide

April 12, 2016

Neighbor cache entries are valid only for a lim ited time. After this tim e, the accessibility of the neighbor must be verified. This is also automatically done by the NDP and is beyond the scope of this document. The NDP’s NeighborRetransTim e parameter can be adjusted w ith the stack parameter ZWIR_spNeighborRetransTime. This time defines the tim eout in m s between r etransm itted N DP packets. T he lifeti m e of neighbor cac he entr ies is defined by routers attac hed to the network . If the network does not have any routers, a defau lt reachable time is used. IDT’s net work stack provides t he stac k par am eter ZWIR_spNeighborReachableTime for conf iguring this time. In c ases where routers advertise lifetime information, this information is given prec edence over the stack parameter.

Note that the default value f or this c onstant (see Table 3.1) significantly diff ers fr om the Ethernet def ault sett ing of 30 seconds. This is to reduce communication overhead generated by neighbor reachability detection messages. It is possible to disable the timeout completely. This is done by setting ZWIR_spNeighborReachableTime to zero.

The exact specification of the neighbor discover y protoc ol can b e found in RFC 4861

– “Neighbor D isc overy for IP

version 6 (IPv6)”.

2.9.4. Recommendations

The 6LoWPAN protocol performs IPv6 header compression to make the transmission of IPv6 packets more efficient over IEEE 802.15 .4 based networks. The header com pression mechanism assumes that the interface identifier (i.e., the lower 64 bits of the IPv6 address) is generated from the link-layer address of the device. In such situations, the header c om pr es sion mechanism is capable of eliding link-local IPv 6 addr ess es c ompletely from the compressed header. T herefore, us ing manually assign ed IPv6 address es is addresses generated by addres s auto-configuration after device startup

NOT RECOMMENDED. Instead the IPv6

SHOULD be used.

In order to achieve maxim um com pression of global IP v6 addres ses , it is possible to define compr ession con texts using the parameters ZWIR_spHeaderCompressionContext1, ZWIR_spHeaderCompressionContext2 and ZWIR_spHeaderCompressionContext3. These parameters define frequently occurring prefixes that should be compr ess ed by the 6LoWPAN hea der c ompression mechanism. If such prefixes are d ef ined , it must be ensured that each device in the network uses the same configuration of these parameters!

In addition to IPv6 header c ompression, the 6LoWPAN layer can als o compr ess the UDP hea der. T his is done if the source and/or des tination port is in the range of 6161 6 to 61631. Thus, if the a pplication does not explicitly require another port range, these ports

SHOULD be used to maximize the data transmission efficiency.

2.10. Mesh Routing

IDT’s 6LoWPAN stack enables devices to work in a mesh network topology. If the distance between two communicating devic es is too wide for direct radio transm ission, packets are r outed over interm ediate devices – known as “hops” – automatically. Routes through the mesh are detected tra nsparently for the app lication. Nodes can take two roles in a mesh network scenario: they can act as endpoints only, or they can provide relaying service. In this documentation, devices are named endpoints or relays depending on their configuration. If the stack configuration is not changed by the app lication, each node is conf igured as a relay with a max imum hop count of four.

IDT’s mesh routing protocol functions on top of the MAC layer, immediately below the network layer.

ZWIR451x Programming Guide

April 12, 2016

2.10.1. Multicast Traffic

Network layer multicast tr affic is handled by broadcas t messages on the mesh and lo wer layers. Receivers of a mesh broadcast mes sage can forwar d it depending on th eir configurat ion. The decision of whether the m essage is forwarded is determined based on the configur ation param eter ZWIR_spMaxHopCount. T his value determines the upper limit of hops that a broadcast packet can take through the network . Each broadcast packet car ries its hop count in its m esh routing headers. This field is incr emented each time the packet is for warded by a relay. When a node receives a packet with a hop count that i s equal to or higher than ZWIR_spMaxHopCount, the node does not forward the packet. Other wise, the hop count is incremented and th e packet is forward ed. Thus nodes can be forced to function as endpoints b y setting ZWIR_spMaxHopCount to zero. An y other configurat ion m akes a node function as a mesh network relay.

2.10.2. Unicast Traffic

For unicast traffic all no des, hence endpoints and relays, m aintain a routing table. The routing table stor es the MAC address of the next h op to be t aken to a specific destination MAC addr ess . Af ter po wer on, res et, or network reset, the ro uting t able does not conta in an y entr ies. A node r equir ing u nicast c om munication must set up a rout e to each of its unicast destination nodes. This is done on demand and transparent for the application.

When the transmission of a unicast packet is requested and there is no matching routing table entry for the destination, the pack et to be s ent is queue d and the r oute dis covery pr ocess is s tarted. A Route Re quest ( RReq) is broadcasted into the network, requesting a route to the destination address of the unicast packet. Nodes receiving an RReq check whether the requested addr ess matches their own addres s or not. If not, the packet is retransmitted by rela ys and ign ored by endpoints, respectively. If the node’s ow n address is matched, a Route Reply (RRep) message is sent to the source hop of the RReq packet. Nodes receiving an RRep packet create/update a recor d in their routing tabl es, storing the source address of the RRep packet as the next hop to the requested destination.

Unicast packets always ta ke the same route through the network as long as the r oute is not removed from the routing tables. Routing table entries are removed if one of the following conditions occurs:

• The route has not been used for ZWIR_spRouteTimeout seconds.

• The route has been failing for ZWIR_spRouteMaxFailCount times.

• The route was oldest when creation of a new route was required but the routing table was full.

If a hop fails for ZWIR_spRouteMaxFailCount times (no acknowledge is sent by the ho p) , the sender considers the route as broken and se nds an i nform ative pac ket to t he origi nator of the pack et. T he originat or then r einit iates the route discovery process, searching for an alternative route.

2.10.3. Mesh Routing Parameter Configuration Recommendations

In order to maximize the network performance f or different application sc enarios while mainta ining a high leve l of stability and without wasting resources, the different routing param eters should be configured according to the application’s characteristics. All parameters are listed below with explanations of the basic function of the parameter and recommendations for their setting in different application scenarios.

ZWIR451x Programming Guide

April 12, 2016

ZWIR_spMaxHopCount

This parameter determines whether a node acts as endpoint or as a relay and constrains the forwarding of multicast pac kets. With ZWIR_spMaxHopCount set to zero, the node acts as a communication endpo int. Note that the node is still able to communicate with remote nodes over multiple hops. Only the ability to forward packets is constrained by this parameter!

In order to make a node function as a mesh network relay, ZWIR_spMaxHopCount greater than zero. However, the value

SHOULD NOT be chosen arbitrarily, but it SHOULD reflect the actual size of the

MUST be set to a value

network. The optimal value is the num ber of hops required to reach th e farthes t remote c ommunication par tner. If no mesh routing is required, setting ZWIR_spMaxHopCount to zero will improve the performanc e.

Limiting the number of nodes working as a r elay in the network is strongly recomm ended. As a rule of thum b, a relay should not have more than ten other r elays within direct reachability. Otherwise, the network latency and th e packet loss are ver y likel y to increas e.

If a large number of relays is desired, using the ZWIR_spRouteRequestMinRSSI parameter should be considered for limiting the amount of traffic generated during the route discovery process.

ZWIR_spRoutingTableSize

This parameter c onfigures how many routes can be kept “alive” c oncurrently. Thus, this param eter defines the number of nodes that the device can communicate with before needing to drop and reestablish routes. The routing table is required in endp oi nts and rel a ys! On endpoints, the table s i ze should be e qua l to or lar ger th a n the number of remote nodes that the device is intended to communicate with. On relays, this number should be increased by the number of nodes for which the relay service is provided.

The routing table is stor ed in the RAM and therefore limited by the RAM size. T he RAM for the routing table is quasi-statically allocated before the ZWIR_AppInitNetwork hook is called. Therefore it is recommended to define the size of the rou ting-table in ZWIR_AppInitHardware. Otherwise a networ k res et has to b e perfor med in order to get the change into effect.

ZWIR_spRouteTimeout

This parameter defines how m any seconds an idle route is kept in the routing table. T he default value is 3600 seconds. The idle tim e counter is restarted each time the route is used. Typically the route timeout param eter does not explicitly affect memory consumption or application performance. However, in frequently changing network configurat ions, r eduction of the timeout value m ay be advantageous, as old routes do not have t o be tested and found to be defective before a new route is established.

ZWIR_spRouteMaxFailCount

This parameter contr ols how often a route can fail before it is considered to be dead. Depending on the ne twork characteristics, this value shou ld be set to a rath er low va lue bet ween zero an d f ive. The hig her the pro babilit y of unreachability of a relay or endpoint, the lower th is val ue s hou ld b e configured. In networks with fr equ ent c ha nges of positions of nodes or a rapidl y chan ging enviro nm ent, the pro babil it y of unreachab ility is hig h and ther ef ore this variable should be low. In contrast, fixed installations of nodes and relays can select a higher value, as the unreachability of a node/rel a y is very likel y to be temporary.

ZWIR451x Programming Guide

April 12, 2016

ZWIR_spRouteRequestAttempts

This parameter conf igures how many attem pts are made to set u p a route to a rem ote device. By reducing th is number, the application can reduce the network load caused by failing route discovery attempts. However, reducing this number will increase the chance of a failing route discovery when it would be physically possible.

ZWIR_spRouteRequestMinLinkRSSI and ZWIR_spRouteRequestMinLinkRSSIReduction

Propagation of electromagnetic waves is influenced by a multitude of external parameters. As a result, radio transmission som etimes appears to behave r andomly. T ypically this is caused by subtle ch anges in the external environment. The occurrence of random behavior might increase noticeably in mesh network topolog ies. Fo r one logical connection of two nodes, there are typically multiple physical links included, all of which have an independent failure probability.

In order to mak e links more robust against los s of connection due to en vironmental variations, the parameters ZWIR_spRouteRequestMinLinkRSSI and ZWIR_spRouteRequestMinLinkRSSIReduction are provided. These parameters allow specifying link quality constraints on each physical link of the whole route. With such constraints in place, sm aller env ironmental c hanges will impair th e routes less, as the signal qualit y on any li nk is less likely to drop below the sensitivity level of the module.

2.11. Network and Device Status

The API provides f unctions for discovering the net work and requesting the device st atus. Network discovery is performed using the ZWIR_DiscoverNetwork function. This func tion broadc asts a message to all devices in t he PAN and makes the ans wers available to the user. For each device, t he hop-distance, the link-quality, and all assigned IPv6 addresses are returned.

The node status is returned by ZWIR_GetTRXStatistic. The returned data s tr ucture c ontai ns infor m ation such as sent and received pac ket and b yte count an d failing transm iss ion attem pts. Howev er, the m ost impor tant value is the sender duty cycle. This value is important, as frequency regulations require nodes to keep their transmission duty c ycle low er than 1% . It is the respons ibilit y of the app licati on code t o ens ure t hat this n um ber is not exceeded.

2.12. Security

Most applications require secure communication in order to protect sensitive data and to protect actors from unauthorized accesses through attackers. For that reason, IDT provides an implementation of the Internet Protocol Security Suite (IPSec) and the Internet Key Exchange protocol version 2 (IKEv2). IPSec is used to encrypt and authenticate d ata, while IKEv2 is used to m anage the keys used for encryption and authentication. IPSec and IKEv2 are stan dardized by the Internet Engineering Task Force (IETF). Both protoco ls are mandated to be used for encr yption and key managem ent in IPv6. The implem entation of the protocols is pr ovided in two separate libraries.

ZWIR451x Programming Guide

April 12, 2016

2.12.1. Internet Protocol Security (IPSec)

IDT provides an IPS ec implementation in conjunc tion with its communication libr a r ies. IPS ec is a pr otocol suite for encryption and authentication of data sent over an IP network. IPSec is supported by virtually all modern operating systems. The encapsulating security payload (ESP) and authentication header (AH) protocols are supported for data encryption and authentication, respectively. Data encryption ensures confidentiality of information transm itted over the network . Authenticatio n is applied to ensur e that data are not m odified along the way and that the sender is the entity that it claims to be.

In order to use th e securit y features of the s tack, the libZWIR45xx-IPSec.a library must be included in the proj ect and must be configured ap propriately. IPSec m aintains a Securit y Policy Database (SPD) that contains rules for how outgoing and incoming traffic must be handled. For each incom ing an d out go i ng pac ket, the stack c hecks the SPD for a matchin g rule that contai ns inf ormation on how the pack et should b e hand led. The r ules ca n dire ct the network stack to either drop, b ypass or pr oc ess the pac ket in the security module. Bypassin g a pac ket means that no security processing is applied. Rules can be applied to single addresses or complete subnets.

Each item in the SPD requiring security processing contains a pointer into the Security Association Database (SAD). Each item of this database contains the required information for encryption and decryption of packets. This information includes keying material and the algorithm to be used for encryption and decryption.

Figure 2.6 Working Principle of IPSec

ZWIR451x Programming Guide

April 12, 2016

The SAD items can be configured manually or automatically. For automatic configuration, the Internet Key Exchange protoco l is used. This protocol is im plemented in a separate libr ary and is described in the f ollowing section. In either case, SPD entries for incom ing and outgoing traf fic must be conf igured by the applicat ion. This is done using the function ZWIRSEC_AddSecurityPolicy. If manual configuration should be used, the function ZWIRSEC_AddSecurityAssociation must be called on both communicating devices, setting the security parameters for the connection.

2.12.2. Internet Key Exchange Version 2 (IKEv2)

The Internet Key Exchang e version 2 protocol can be used for autom atic creation of keying m aterial for secured connections. This protocol is implemented in the libZWIR45xx-IKEv2.a library. If IKEv2 is used, no manual configuration of the SAD is required. Instead, keying material is negotiated automatically on demand. If application code attempts to send data to a remote node and the corresponding SPD entry requires security processing of this data , it is c hec ked to determine if a s ec urit y assoc i ation (SA) is as s igned to the SPD entry. If no entry exists, IPSec requests the establishment of a security association from the IKEv2 daemon.

IKEv2 first attempts to set up a secur e communication channel over which keying m aterial is exchanged. This channel is set up using the Diffie-Hellmann-Key-Exchange algorit hm.

Both communicating parti es use a Pre-Share d Key (PSK) for mut ual authentication. T he PSK is registered us ing the ZWIRSEC_AddIKEAuthenticationEntry function. After setup of the secure channel, k eying material for the security association to be created is exc hang ed.

2.12.3. Recommendations

IDT str ongly recomm ends using the sec urity featur es prov ided b y the network stack . Security is n ot onl y required to prevent data from being visible for third parties—more critical is active att acks on a network. Most applica tions will suffer from s uch attacks. In the best case, applications might behave erratica lly; however, in the worst case, perilous behavior of actors can be caused by an attack. Attacking possibilities are manifold: packets can be changed on their way to the destination; they can be sent again; invalid packets infiltrate into the network; or packets can be simpl y bloc ked by an attacker. IPSec can pr ot ec t aga ins t a ll of these attacks . IPSec in conj un c tion with IKEv2 further increases the security, as the keying material can be renewed on a regular basis.

2.13. Firmware Over-the-Air Updates

IDT provides an over-the-air update (OTAU) librar y. This library extends the ap plication with functiona lity for the reception and processin g of update packets, as well as f unctionality for replacing the existing code with a new version. The update mechanism incorporates recovery mechanisms, ensuring the proper recovery after occurrence of an error during the update process.

The OTAU firmware library is des igned to require minimal interaction of the firm ware programmer. However, it places some constraints on the firmware in order to ensure reliability of the OTAU function.

ZWIR451x Programming Guide

April 12, 2016

update_code

(OTAU Boot-Loader)

.status_seg

(OTAU Status Information)

.text .data

...

(Active Application Firmware)

.text* .data*

...*

(New Application Firmware Image)

Optional section for permanent

parameter storage

2.13.1. Functional Description

Integrating the firm ware over-the-air update (OTAU) adds two com ponents into the us er applic ation. The f irst one is a service for the r eception and processing of OTAU-related network tr affic. The second one is a boot -loader that replaces the old firmware image with the new one after complete reception and verification of all update traffic. The boot-loader com ponent is located in a program section called .update_code. The location of this segment

A second segment that is ded icated to OTAU-enab led code is the .status_seg. This segm ent resides directly behind the boot-loader component and stores status information about the firmware update.

Including the sections referenced abo ve, the application’s memory layout would be as shown in Figure 2.7. The application code is located after the .update_code and .status_seg sections. Optionally the OTAU m emory layout can incorporate a section for the storage of permanent parameters. This section of the flash. In contrast to non-OTAU-enab led applica tions, the amount of memory availab le for the applicat ion is limited to less than one half of the microcontroller’s total flash memory s ize. This is because the spac e for the buffering of the full new firmware image must be provided.

The OTAU network service is started through a call to the ZWIR_OTAU_Register function. The f unction takes the UDP port to be use d b y the OT AU networ k s ervice as the argument . Calling t his f unction is all that is requir ed to enable the reception and proc essing of firmware over-the-air updates. All oth er update parameters are controlled by the update server, which is typically a computer in the network.

MUST be the first flash memory page(s). During the update process, the boot-loader is not replaced!

MUST be located at the end

Figure 2.7 Memory Layout of OTAU-Enabled Applications

ZWIR451x Programming Guide

April 12, 2016

A new firmware image to be loaded into the device is typically received in small chunks of data. Whenever a chunk of data is received, the c orresponding flash location in the new applicat ion firmware image portion of the flash is updated. If this is the firs t chunk written to a flash page, the flash page i s completely erased before the chunk is written to it. All packets corresponding to the same firmware update information and the size of data chunk s

MUST be the same for all packets. Packets containing fragments of a

MUST include the same version

different size than the f irst fragment are ignored once the update is started. Packets containin g different version information trigger a complete re-initialization of the update.

2.13.2. Firmware Constraints

The OTAU network service uses a dedicated UDP port for the reception and transmiss ion of OTAU-related packets. The application application behavior is determined by the behavior of sockets being reopened with the same parameters.

The contents of the .update_code and .status_seg segm ents must not be changed in any way by the application. This means the application

MUST NOT use the same port for any other purpose. If this limitation is ignored, the

MUST NOT explicitly place functions or data in either of these sections!

In order to allow the OTAU from a firmware-version A to a firmware version B, t he firmware ver sions

MUST share

the following properties:

• The call stack of A and B must be located at the same RAM position.

• The call stack of A and B must be of the same size.

• The flash memory layout of A and B must be the same (e.g., no optional section as shown in Figure 2.7

can be added or removed).

2.14. Memory Considerations

Applications must manage their memory consumption – especially with respect to RAM (random access memory). There are basically three components that contribute to the overall RAM size requirements of the application:

1. Statically allocated memory

2. Dynamically allocated memory

3. Call stack

The call stack is required by the app lication to st ore the return ad dresses from f unction calls, func tion argum ents, and variables stored loc ally in functio ns. The RAM size res erved for the cal l stack can be configured in th e linker script. Applications utilizing IDT’s network stack need a minimum of 2kB of call stack . In order to leave some flexibility for the user ap plic atio n, th e def aul t s tac k si ze conf igur ed i n the linker script is 5kB. The call stack resides at the lower end of the RAM area.

Static memory is consumed by globally declared and local statically declared variables. IDT’s network stack requires less t han 8kB of static m em or y in a m inimal c onfigurat ion. T he stat ic m em ory consum ption ca n eas il y be determined b y exam ining the m ap file generated b y the linker. Stat ic m emory is allocate d immediately behi nd the call stack.

+ 75 hidden pages

IDT ZWIR451, ZWIR4512AC2, ZWIR4512, ZWIR4512AC1 Programming Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

1 Introduction

1.1. IPv6

1.2. 6LoWPAN

1.3. Organization of this Document

2 Functional Description

2.1. Requirements Notation

2.2. Terms

2.3. Naming Conventions

2.4. Library Architecture

2.5. Operating Modes

2.5.1. Device Mode

2.5.2. Gateway Mode

2.5.3. Sniffer Mode

2.6. Operating System

2.6.1. Initialization

2.6.2. Normal Operation

2.6.3. Power Modes

2.6.4. Error Handling

2.7. Firmware Version Information

2.7.1. Vendor ID

2.7.2. Product ID

2.7.3. Major Firmware Version

2.7.4. Minor Firmware Version

2.7.5. Firmware Version Extension

2.7.6. Library Version

2.8. Addressing

2.8.1. Address Types

2.8.2. IPv6 Addresses

2.8.3. IPv6 Address Auto-configuration

2.8.4. Validation of Address Uniqueness

2.9. Data Transmission and Reception

2.9.1. User Datagram Protocol

2.9.2. Data Transmission and Reception

2.9.2.1. Unicast

2.9.2.2. Multicast

2.9.3. Address Resolution

2.9.4. Recommendations

2.10. Mesh Routing

2.10.1. Multicast Traffic

2.10.2. Unicast Traffic

2.10.3. Mesh Routing Parameter Configuration Recommendations

ZWIR_spMaxHopCount

ZWIR_spRoutingTableSize

ZWIR_spRouteTimeout

ZWIR_spRouteMaxFailCount

ZWIR_spRouteRequestAttempts

ZWIR_spRouteRequestMinLinkRSSI and ZWIR_spRouteRequestMinLinkRSSIReduction

2.11. Network and Device Status

2.12. Security

2.12.1. Internet Protocol Security (IPSec)

2.12.2. Internet Key Exchange Version 2 (IKEv2)

2.12.3. Recommendations

2.13. Firmware Over-the-Air Updates

2.13.1. Functional Description

2.13.2. Firmware Constraints

2.14. Memory Considerations