IDT ZWIR451 Series Mode d'emploi

ZWIR451x Programming Guide

April 12, 2016

Content

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

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

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

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

2Functional 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

April 12, 2016

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 Updates.................................................................................................................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

3Core-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

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

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

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

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

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

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

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

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

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

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

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

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

8Over-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

April 12, 2016

9NetMA 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

April 12, 2016

List of Tables

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

Table 2.2 Event Processing Priority in the Main Event Loop..............................................................................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 Examples..........................................................................................................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

April 12, 2016

1 Introduction

This guide describes the usage of the 6LoWPAN application programming interface (API) for application devel-

opment using ZWIR451x modules. These modules provide bidirectional IPv6 communication over an IEEE

802.15.4 wireless network. Using IPv6 as the network layer protocol allows easy integration of sensor or actor

nodes into an existing Internet Protocol (IP) infrastructure without the need for additional hardware. 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 typical network configuration. The Personal Area Network (PAN) is built from a set of various

ZWIR451x modules. The network is connected via a border router to the local area network (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 typically organized in a mesh topology. Routing of IP packets over this topology is handled

by the software stack transparently for the user. The network allows dropping 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*microcontroller (MCU) on top of the

ZWIR451x API. The MCU is clocked with up to 64 MHz and provides 256 kByte 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.

Cloud /

Internet

ZWIR45xx

Device

Computer

ZWIR45xx

Gateway

LAN

Router

Handheld

Device

Specific Devices:

Off-the-Shelf

Components:

LAN

WANPAN

ZWIR451x Programming Guide

April 12, 2016

1.1. IPv6

IPv6 is the successor of the IPv4 protocol, which has been the major network protocol used for Internet

communication over the past decades. One of the main advantages of IPv6 over IPv4 is its huge address area,

which provides 2128 (about 3.4 x 1038) unique addresses. This enormous address space allows assignment of a

globally unique IP address to every imaginable device that could be connected to the Internet. Another advantage

with respect to sensor networks is the stateless address auto-configuration mechanism, allowing 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 to connect sensor networks directly to the Internet. Basically this is possible

with other network protocols, too, but those require a dedicated gateway that translates network addresses to IP

addresses and vice versa. Usually this translation requires application knowledge and maintenance of the

application state in the border router, and therefore changing the border router 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 implementation supports IPSec, which is the mandated standard for secure communication 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 infrastructure, which does not put significant constraints on

the underlying network protocols due to the vast amount of memory, computing power, and energy. In contrast,

the IEEE 802.15.4 standard is intended for low data-rate communication of devices with very limited 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 adaption layer between the link layer and network layer of the Open Systems Interconnection

(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 user, and therefore on 6LoWPAN devices, the IPv6 protocol is used in exactly the same way

as on native IPv6 devices. The presence of the 6LoWPAN adaption layer does not restrict IP functionality. 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 API documentation, which is divided into two parts. The first part, covered by section 2

provides a functional description of the network stack. It explains the correlation of the different API functions and

provides background information about stack internals. The second part is the function reference and is covered

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

April 12, 2016

2 Functional Description

The following subsections give a generic overview of the different functionalities of the firmware delivered with

ZWIR451x modules. Background information is provided if required for proper use of the libraries. Usage

recommendations are given for optimal performance in certain application configurations. A detailed description of

the functions, types, and variables available for application programming is given in sections 3 through 7.

2.1. Requirements Notation

This document uses several words to indicate the requirements of IDT’s 6LoWPAN stack implementation. The

key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY and

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

MUST, SHALL, REQUIRED These words denote an absolute requirement of the implementation. Disregarding these

requirements will cause erroneous function of the system.

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

Disregarding these requirements will cause erroneous function of the system.

SHOULD, RECOMMENDED These words describe best practice, but there might be reasons to disregard it. Before

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

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

when implemented. However, there might be reasons to choose to implement the item anyway. Implications of

doing so must be fully understood.

MAY, OPTIONAL These words describe items which are optional. No misbehavior is to be expected when these

items are ignored.

2.2. Terms

This document distinguishes between three types of functions: hooks, callbacks, and API functions. Basically, all

three types are defined as normal functions in the programming language C, but 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 accessed by the user code. The declarations of API functions are provided in the header

file belonging to the library in which the function is implemented.

Hooksare functions that provide the user the ability to extend the default behavior of the stack. They are called

from the operating system (OS) to give the application the opportunity to implement custom features or reactions

to events. The operating system provides a default implementation of the hook that is called if no custom hook is

defined. The prototypes of all available hooks are defined in the header file belonging to the library in which the

default implementation is located. 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 must be matching. Callback functions are registered at the

OS using API functions. One example for a function expecting a callback 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

April 12, 2016

2.3. Naming Conventions

For better readability of the code, all user accessible functions and types of the API comply with a set of naming

conventions. Each identifier 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 starts with a capital letter. The remaining letters of the word are lower case. Preprocessor

macros are defined using all capital letters.

Different style rules apply to functions, variables, and types definitions. Function-name and type-name identifiers

start with a capital letter in the first word, while variable identifiers start with a lower case letter in the first word.

Type names have an additional “_t” suffix. Variable names and function arguments are not differentiated in the

naming conventions.

Table 2.1 Naming Conventions Used in C-Code

Identifier Type Style

variableName, functionArgument

First word starts with lower case, all other words with capital letters.

FunctionName

All words start with capital letters (“CamelCase”).

TypeName_t

All words start with capital letters and name ends with “_t” suffix.

PREPROCESSOR_MACRO

All letters are capitalized.

2.4. Library Architecture

ZWIR451x modules are freely programmable by means of an API that is implemented 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 provides the operating system and all generic communication functionality. All other libraries are

optional and can be linked depending on the requirements of the target application. Each library exposes a set of

functions and types that are required to implement the desired functionality. The library architecture is depicted in

Figure 2.1.

To make programming as easy as possible, the libraries make use of an event and command approach wherever

possible. Using this approach, application code is not required to poll for data on the different interfaces. Instead,

newly available data is passed 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

April 12, 2016

Figure 2.1 Library Architecture

2.5. Operating Modes

The API provides three operating modes: Device Mode, Gateway Mode and Sniffer Mode. The modes differ in

how many of the protocol layers are processed by the network stack. All other API functionality remains the same.

Setting the operating mode of a node must be done before any initialization of the API and the hardware. For this

purpose, the ZWIR_SetOperatingMode function is provided. Figure 2.2 shows how application code interfaces

into the network stack in different operating modes. A description of the three different modes is provided in the

next subsections.

2.5.1. Device Mode

The Device Mode is preconfigured since this is the most commonly used mode for ZWIR451x modules. Each

node with sensing or acting functionality should use this operating mode. Full protocol processing is performed for

incoming and outgoing data. This means that all header information is removed from incoming User Datagram

Protocol (UDP) packets and only payload data is passed to the application. Accordingly, the application only has

to provide payload data that should be sent over the network. The stack automatically adds all necessary header

information.

Device-configured devices behave as normal IPv6 devices. Therefore address auto-configuration and neighbor-

discovery 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

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

2.5.2. Gateway Mode

The Gateway Mode is intended for use with modules that should work as protocol gateways. Protocol gateways

change the physical media used for IPv6 packet transmission. This enables the integration of 6LoWPAN networks

into Ethernet-based IPv6 networks for example.

In contrast to the Device Mode, not all network layers are processed in Gateway Mode. For any IPv6 packet that

is received via the air interface, only the 6LoWPAN-specific modifications of the headers are removed, 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 devices do not perform address auto-configuration and neighbor-discovery as defined by the

IPv6 standard. Moreover no router solicitation and router advertisement messages are generated automatically.

To enter the Gateway Mode, ZWIR_SetOperatingMode must be called from ZWIR_AppInitHardware. It is

not possible to call ZWIR_SetOperatingMode from any other location in the code. ZWIR_SetOperatingMode

accepts a callback function that is called upon reception of data in the gateway. Sending data is accomplished

using the function ZWIR_Send6LoWPAN.

2.5.3. Sniffer Mode

The Sniffer Mode is provided to allow observation of raw network traffic. No protocol processing is performed.

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.

ZWIR_SendUDP(2)

ZWIR_Send6LoWPAN

ZWIR_OpenSocket

ZWIR_SetOperatingMode

Ce manuel convient aux modèles suivants

Table des matières

Autres manuels IDT Unité de contrôle

IDT

IDT VersaClock 6E Mode d'emploi

Manuels Unité de contrôle populaires d'autres marques

Festo

Festo Compact Performance CP-FB6-E Manuel de la liste des pièces

Elo TouchSystems

Elo TouchSystems DMS-SA19P-EXTME Manuel utilisateur

JS Automation

JS Automation MPC3034A Manuel utilisateur

JAUDT

JAUDT SW GII 6406 Series Guide rapide

Spektrum

Spektrum Air Module System Manuel utilisateur

BOC Edwards

BOC Edwards Q Series Manuel utilisateur

KHADAS

KHADAS BT Magic Manuel utilisateur

Etherma

Etherma eNEXHO-IL Manuel utilisateur

PMFoundations

PMFoundations Attenuverter Manuel utilisateur

GEA

GEA VARIVENT Manuel utilisateur

Walther Systemtechnik

Walther Systemtechnik VMS-05 Manuel utilisateur

Altronix

Altronix LINQ8PD Instructions de montage

Eaton

Eaton Powerware Series Manuel utilisateur

WAGO

WAGO 750-407/040-000 Manuel utilisateur

Sony

Sony CCU-590 Manuel utilisateur

Graco

Graco 25D614 Manuel utilisateur

Task Force Tips

Task Force Tips YE-RF-900 Manuel de programmation

Shini

Shini SPV-U Series Manuel utilisateur