Table of Contents
Advertisement
Quick Links
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
© 2016 Integrated Device Technology, Inc.
ZWIR451x Programming Guide
1
April 12, 2016
Advertisement
Table of Contents
Related Manuals for IDT ZWIR451 Series
Summary of Contents for IDT ZWIR451 Series
-
Page 1: Table Of Contents
ZWIR451x Programming Guide Content Introduction ................................. 5 1.1. IPv6 ................................6 1.2. 6LoWPAN ..............................6 1.3. Organization of this Document ........................6 Functional Description ............................7 2.1. Requirements Notation ..........................7 2.2. Terms ................................7 2.3. Naming Conventions ........................... 8 2.4. - Page 2 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 Core-Library Reference ............................ 36 3.1.
- Page 3 ZWIR451x Programming Guide 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 .......................
- Page 4 ZWIR451x Programming Guide 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 ........................
-
Page 5: Introduction
ZWIR451x Programming Guide 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. -
Page 6: Ipv6
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. -
Page 7: Functional Description
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. -
Page 8: Naming Conventions
ZWIR451x Programming Guide 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”... -
Page 9: Operating Modes
ZWIR451x Programming Guide 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. -
Page 10: Gateway Mode
ZWIR451x Programming Guide Figure 2.2 Application Interface into the Protocol Stack in Different Operating Modes ZWIR_SendUDP(2) ZWIR_Send6LoWPAN ZWIR_OpenSocket ZWIR_SetOperatingMode 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. -
Page 11: Operating System
ZWIR451x Programming Guide 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 triggered. That is why there is only an interface from the stack to the application code, but not vice versa. -
Page 12: Table 2.2 Event Processing Priority In The Main Event Loop
ZWIR451x Programming Guide Table 2.2 Event Processing Priority in the Main Event Loop Priority Event Triggered By Effect Application Event 0 Application Code Call user-defined callback function Transceiver Event Transceiver Interrupt Request Process transceiver request Application Event 1 Application Code Call user-defined callback function Callback Timer Expired SysTick Controlled Software Timer... -
Page 13: Power Modes
ZWIR451x Programming Guide 2.6.3. Power Modes The stack supports different modes to reduce the power consumption of the device. In Active Mode, all module features are available. The Sleep, Stop, and Standby Modes reduce the power consumption by disabling different module functionalities. -
Page 14: Error Handling
ZWIR451x Programming Guide 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. -
Page 15: Vendor Id
The Vendor ID is a 32-bit number that identifies the company that developed the device firmware. 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 variable ZWIR_vendorID. If this variable is not set, the firmware... -
Page 16: Address Types
ZWIR451x Programming Guide 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 with different PANIds cannot communicate. A default PANId is preprogrammed in the network stack. -
Page 17: Figure 2.3 Ipv6 Unicast Address Layout
ZWIR451x Programming Guide Unicast addresses are shown in Figure 2.3 and use 64 bits each for the prefix and the interface identifier. Unicast addresses exactly identify one single interface in a network. The prefix of the address determines the scope of the unicast address. -
Page 18: Ipv6 Address Auto-Configuration
The local information used for auto-configuration is the interface EUI-64 address. The EUI-64 address is a factory programmed link-layer address that IDT guarantees to be unique for each module. 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 prefix fe80::/64 in front of the EUI-64 address with bit 1 of the most significant EUI-64 byte inverted. -
Page 19: Figure 2.5 Resolving Address Conflicts In Local Networks
ZWIR451x Programming Guide The default implementation provided in the library only removes the failing address 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 Local Networks Start Assign link-address... -
Page 20: Data Transmission And Reception
In IDT’s 6LoWPAN stack, services that provide the callback functions to which network packets are passed are running in the application code. Each service has its own callback function. -
Page 21: Table 2.5 Unicast Socket Examples
ZWIR451x Programming Guide few packets to a remote device without expecting a response from the target device. The function accepts the remote address and UDP port together with the data to be sent. Internally the function will open a temporary socket that is immediately closed after sending out the packet, so a slight overhead is added. -
Page 22: Address Resolution
Note that a socket with a multicast remote address cannot be used for 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 multicast address, the hook function ZWIR_CheckMulticastGroup is called by the network stack. -
Page 23: Recommendations
SHOULD 2.10. Mesh Routing IDT’s 6LoWPAN stack enables devices to work in a mesh network topology. If the distance between two communicating devices is too wide for direct radio transmission, packets are routed over intermediate devices – known as “hops” – automatically. Routes through the mesh are detected transparently for the application. Nodes can take two roles in a mesh network scenario: they can act as endpoints only, or they can provide relaying service. -
Page 24: Multicast Traffic
ZWIR451x Programming Guide 2.10.1. Multicast Traffic Network layer multicast traffic is handled by broadcast messages on the mesh and lower layers. Receivers of a mesh broadcast message can forward it depending on their configuration. The decision of whether the message is forwarded is determined based on the configuration parameter ZWIR_spMaxHopCount. - Page 25 ZWIR451x Programming Guide ZWIR_spMaxHopCount This parameter determines whether a node acts as endpoint or as a relay and constrains the forwarding of multicast packets. With ZWIR_spMaxHopCount set to zero, the node acts as a communication endpoint. 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 be set to a value...
-
Page 26: Network And Device Status
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 data, while IKEv2 is used to manage the keys used for encryption and authentication. -
Page 27: Internet Protocol Security (Ipsec)
ZWIR451x Programming Guide 2.12.1. Internet Protocol Security (IPSec) IDT provides an IPSec implementation in conjunction with its communication libraries. IPSec is a protocol suite for encryption and authentication of data sent over an IP network. IPSec is supported by virtually all modern operating systems. -
Page 28: Internet Key Exchange Version 2 (Ikev2)
2.12.3. Recommendations IDT strongly recommends using the security features provided by the network stack. Security is not only required to prevent data from being visible for third parties—more critical is active attacks on a network. Most applications will suffer from such attacks. -
Page 29: Functional Description
ZWIR451x Programming Guide 2.13.1. Functional Description Integrating the firmware over-the-air update (OTAU) adds two components into the user application. The first one is a service for the reception and processing of OTAU-related network traffic. 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. -
Page 30: Firmware Constraints
The RAM size reserved for the call stack can be configured in the 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 application, the default stack size configured in the linker script is 5kB. The call stack resides at the lower end of the RAM area. -
Page 31: Call Stack
2.14.1. Call Stack IDT’s network stack places the call stack of the application at the lower end of the RAM. This is enables detection of stack overflows. The stack grows downwards from its topmost address towards the beginning of the RAM. If a stack overflow occurs, the MCU tries to access an address that is not in the RAM area and the MCU will generate a Bus-Fault interrupt. -
Page 32: Using Dynamic Memory Allocation
ZWIR451x Programming Guide Application developers must always ensure that the parameter settings allow proper allocation of all quasi-static memory. If parameters are chosen too large, stack initialization will fail and report the failure as error ZWIR_eMemoryExhaustion. The default handling of this error is a system reset. Thus, if the parameters causing the memory exhaustion are set during system startup, this will result in an infinitive loop. -
Page 33: Supported Network Standards
ZWIR451x Programming Guide 2.15. Supported Network Standards Table 2.8 lists RFCs that are supported by IDT’s network stack, and it specifies the limitations that apply with respect to these RFCs. Table 2.8 Supported RFCs and Limitations Limitations Internet Protocol Version 6 (IPv6) Specification •... - Page 34 ZWIR451x Programming Guide Limitations IP Encapsulating Security Payload (ESP) • 4303 SPI 0 to 255 are not reserved. • Anti-replay service is not active. • The sequence number will cycle. • ESN is not supported. • Dummy packets are not supported. •...
- Page 35 Transmission of IPv6 Packets over IEEE 802.15.4 Networks • 4944 IDT’s implementation does not support one of the specified header compression algorithms proposed by the RFC. Instead, it implements the RFC draft-hui-6lowapn-hc version 01 (see “6LoWPAN Compression of IPv6 Datagrams” below).
-
Page 36: Core-Library Reference
ZWIR451x Programming Guide Core-Library Reference 3.1. Initialization The core library provides two different hooks that can be used to initialize the application during system startup. The first hook, named ZWIR_AppInitHardware, is called before network initialization. The second one, named ZWIR_AppInitNetwork, is called afterwards. void ZWIR_AppInitHardware ( ZWIR_ResetReason_t resetReason ) -
Page 37: Program Control
ZWIR451x Programming Guide typedef enum { ... } ZWIR_OperatingMode_t Type enumerating the different operating modes of the device. Possible values include: Device Mode ZWIR_omNormal Gateway Mode ZWIR_omGateway Sniffer Mode ZWIR_omSniffer typedef enum { ... } ZWIR_ResetReason_t Type enumerating the different reasons for system reset. Possible values include: ZWIR_rPowerOnReset Reason: The device has been powered on after being switched off. - Page 38 ZWIR451x Programming Guide In addition to the fixed period main functions, the API also provides a freely configurable callback timer. The timer is started using the ZWIR_StartCallbackTimer function. It is possible to provide a data pointer to this function, which is passed to the callback when the timer expires. This allows for delayed data processing. Whether the timer is triggered just once or periodically can be selected.
- Page 39 ZWIR451x Programming Guide void ZWIR_StartCallbackTimer ( uint32_t timeout, ZWIR_TimeoutCallback_t callback, void* data, bool periodic ) If this function is called, the freely programmable timer is initialized and started. The function provided with the callback argument will be called about timeout ms after the call to ZWIR_StartCallbackTimer. The value provided with data will be passed to callback when it is called.
- Page 40 } ZWIR_RevisionInfo_t Type for objects carrying version information. If problems are encountered while using the stack, request this structure using ZWIR_GetRevision and provide the information obtained to IDT with an error report. void ZWIR_NetEventCallback ( ZWIR_NetEvent_t event ) This function is called when a network event occurs.
-
Page 41: Networking
ZWIR451x Programming Guide bool ZWIR_Error ( int32_t errorCode ) This function is called when a recoverable library error is encountered. The error-code is passed in the errorCode argument. If true is returned, the error is assumed to be processed and no action will be taken by the stack. - Page 42 Note: Changing the link-layer address of a device during normal operation will typically cause a loss of all incoming packets for a period of time. The standard allows sending unsolicited neighbor advertisements as an option if the link-layer address changes. This feature is not included in IDT’s 6LoWPAN stack. typedef uint8_t ZWIR_PANAddress_t [8] Data type for representation of link-layer addresses.
- Page 43 ZWIR451x Programming Guide 3.3.1.3. IPv6 Addresses Although manual assignment of IPv6 addresses is not required by most applications, the API provides the function ZWIR_SetIPv6Address. This function can be used to assign additional IPv6 addresses to an interface. Up to three addresses can be assigned in total, but the first address is always allocated by the automatically configured link-local address.
-
Page 44: Socket And Datagram Handling
ZWIR451x Programming Guide void ZWIR_ResetDestinationPANId ( void ) This function resets the PAN identifier of the device to the last value that had been configured before it was changed using ZWIR_SetDestinationPANId. bool ZWIR_CheckMulticastGroup ( ZWIR_IPv6Address_t const* ipv6 ) This hook is called whenever a multicast packet is received that contains a multicast group that is not known by the network stack. - Page 45 ZWIR451x Programming Guide ZWIR_SocketHandle_t ZWIR_OpenSocket ( ZWIR_IPv6Address_t const* remoteAddr uint16_t remotePort, uint16_t localPort, ZWIR_RadioReceiveCallback_t rxHandler ) This function opens a new socket to a remote host. The remoteAddr and remotePort arguments specify the IPv6 address and the UDP port of the remote host, respectively. The localPort argument specifies the port on which incoming data is accepted.
- Page 46 ZWIR451x Programming Guide bool ZWIR_SendUDP2 ( uint8_t* data, uint16_t size, ZWIR_IPv6Address_t* remoteAddress, uint16_t remotePort ) This function sends an UDP packet without the need for opening a socket. The destination address and destination port are provided in the remoteAddress and remotePort arguments. The local UDP port is selected arbitrarily by the network stack.
- Page 47 ZWIR451x Programming Guide uint8_t ZWIR_GetPacketHopCount ( void ) Returns the number of hops the last received packet has taken. Note: Using this function outside of the RX callback function might cause unreliable results. int32_t ZWIR_GetLastRSSI ( void ) Returns the receive signal strength indicator (RSSI). The value approximately corresponds to the receive power level in dBm.
- Page 48 ZWIR451x Programming Guide bool ZWIR_Send6LoWPAN ( ZWIR_PANAddress_t const* remoteAddr, uint16_t const* data, uint8_t const length ) This function is used to send complete IPv6/UDP packets to the remote host with the link-local address remoteAddr. No UDP or IPv6 header processing is performed on the packet. Instead it is passed directly to the 6LoWPAN processing layer.
-
Page 49: Radio Parameters
ZWIR451x Programming Guide typedef void ( * ZWIR_RadioReceiveCallback_t ) ( uint8_t* data, uint16_t length ) Function pointer type for the callback function that should be called on reception of data over an UDP socket. typedef void* ZWIR_SocketHandle_t Type representing a socket. 3.3.3. - Page 50 ZWIR451x Programming Guide Note: If this is done while a transmission or reception is ongoing, the transmitted or received packet will be lost. It is recommended that this function be called from ZWIR_AppInitHardware. ZWIR_Modulation_t ZWIR_GetModulation ( ) Returns the current ZWIR_Modulation_t modulation void ZWIR_SetTransmitPower ( int power )
-
Page 51: Gateway Mode Functions
ZWIR451x Programming Guide US Band, 924 MHz ZWIR_channel10, ZWIR_us924 EU Band, 865.3 MHz ZWIR_channel100, ZWIR_eu865 EU Band, 866.3 MHz ZWIR_channel101, ZWIR_eu866 EU Band, 867.3 MHz ZWIR_channel102, ZWIR_eu867 typedef enum { ... } ZWIR_Modulation_t Enumeration of modulation schemes accepted by ZWIR_SetModulation. Possible values include Binary Phase Shift Keying ZWIR_mBPSK Offset Quadrature Phase Shift Keying... -
Page 52: Miscellaneous
ZWIR451x Programming Guide typedef uint8_t ( *ZWIR_GatewayOutputFunction_t ) ( uint8_t* data, uint16_t size, ZWIR_PANAddress_t* address ); This type defines the signature of functions to be used as the output function in Gateway Mode. The task of this function is determining to which interface an outgoing packet must be sent and calling the corresponding output function for this interface. - Page 53 ZWIR451x Programming Guide Note: All values in the structure might be higher than expected. This is due to the overhead communication that is required for address resolution and route discovery. Refer to section 2.10 to determine if it is possible to optimize constant settings in order to reduce overhead traffic to a minimum. void ZWIR_ResetTRXStatistic ( void ) This function resets all values of the transceiver statistics to 0.
- Page 54 ZWIR451x Programming Guide void ZWIR_SetPromiscuousMode ( bool enable ) This command puts the device into Promiscuous Reception Mode. This means that on the MAC layer, all packet filtering is disabled. In Promiscuous Mode, the device receives packets sent to all PAN identifiers and all PAN addresses, regardless of its own PAN identifier and PAN address configuration.
-
Page 55: Power Management
ZWIR451x Programming Guide 0x01 Address is a EUI64 address ZWIR_aatEUI64 0x02 Address is a EUI48 address ZWIR_aatEUI48 0x03 Only to be used as a filter in ZWIR_IsAlternativeAddress ZWIR_aatAny bool ZWIR_ExternalClockEnable ( bool enable ) This function is used to select whether the external or the internal clock is used as the system clock. The external clock is much more precise, but it is not possible to use Sleep Mode or turn off the transceiver when the external clock is used. - Page 56 ZWIR451x Programming Guide In addition to the clock speed modification, the API provides the function ZWIR_SetRTC to set and ZWIR_GetRTC to get the RTC counter. Furthermore the function ZWIR_SelectRTCSource selects the RTC clock source. The RTC clock interval is 1s and is suitable for UNIX time. Due to the inaccuracy of the internal RC oscillator, an external crystal should be used for RTC applications.
- Page 57 ZWIR451x Programming Guide void ZWIR_PowerDown ( ZWIR_PowerDownState_t powerDownMode, uint32_t time ) This function changes the power mode of the system immediately or after sending all buffered fragments. The powerDownMode argument defines the next power down mode. The time parameter specifies the power down time.
- Page 58 ZWIR451x Programming Guide void ZWIR_Standby ( uint32_t standbyTime ) This function puts the system into Standby Mode. The standbyTime argument controls the duration of Standby Mode and is given in seconds. In order to consume minimal power, almost all power domains of the MCU are disconnected.
-
Page 59: Firmware Version Information
Version information is included in the firmware by global definition of the variables listed below. If these variables are not defined by the application code, they will contain default values. uint32_t ZWIR_vendorID = 0xe966 This variable defines the Vendor ID. A vendor ID is assigned by IDT. It be defined appropriately in MUST production code! -
Page 60: Properties And Parameters
ZWIR451x Programming Guide uint8_t ZWIR_firmwareMajorVersion = 0 This variable defines the major version number of the firmware. uint8_t ZWIR_firmwareMinorVersion = 0 This variable defines the minor version number of the firmware. uint16_t ZWIR_firmwareVersionExtension = 0 This defines version extension information of the firmware. 3.6. -
Page 61: Error Codes
ZWIR451x Programming Guide Enumerator Size Default Description ZWIR_spMaxSocketCount Refer to section 2.9.2. ZWIR_spRouteTimeout 3600 (s) Refer to section 2.10.3. ZWIR_spNeighborReachableTime 3600 (s) Refer to section 2.9.3. ZWIR_spMaxHopCount Refer to section 2.10.3. ZWIR_spRouteMaxFailCount Refer to section 2.10.3. ZWIR_spRouteRequestMinLinkRSSI -128 (dBm) Refer to section 2.10.3. ZWIR_spRouteRequestMinLinkRSSIReduction 0 (dB) Refer to section 2.10.3. -
Page 62: Uart Library Reference
The libZWIR451x-UART1.a and libZWIR451x-UART2.a libraries provide functions for easy access to the UART interfaces provided by the microcontroller. Each ZWIR451x module has two UART interfaces. IDT provides two separate libraries, one for each UART interface. Both libraries expose exactly the same interface. Symbol names only differ in the number after “UART,”... - Page 63 ZWIR451x Programming Guide bool ZWIR_UART?_ReadByte ( uint8_t* data ) This function reads a single byte from the receive buffer. The read byte is stored to the location to which data points. The function returns true if a byte is successfully read and false otherwise. void ZWIR_UART?_SetRXCallback ( ZWIR_UART_RXCallback_t callback )
-
Page 64: Custom Uart I/O Configuration
ZWIR451x Programming Guide Note: When flow control is enabled, the configuration of the CTS and RTS pins of the corresponding UART interface are configured as input and alternative push/pull output, respectively. This configuration overwrites the existing configuration of these pins. When flow control changes from enabled to disabled, the pin con- figuration of the CTS and RTS pins is not changed. -
Page 65: Error Codes
ZWIR451x Programming Guide 4.3. Error Codes The error codes listed in Table 4.1 are generated by the UART libraries and passed to the ZWIR_Error hook if it is implemented in the application code. Table 4.1 Error Codes Generated by the UART Libraries C –... -
Page 66: Gpio Library Reference
ZWIR451x Programming Guide GPIO Library Reference The GPIO library provides a convenient interface for accessing and controlling the GPIO ports of the module. It allows configuring GPIOs to be used as application programmable inputs or outputs, and it is possible to enable or disable special functions of certain ports such as the JTAG ports. -
Page 67: Figure 5.1 Zwir_Gpio_Readmultiple Result Alignment In Zwir4512Ac1 Devices
ZWIR451x Programming Guide uint32_t ZWIR_GPIO_ReadMultiple ( ZWIR_GPIO_Pin_t pins ) This function reads the input value of multiple pins. For this function, it does not matter if the pins are configured as inputs or outputs. If a pin is configured as an analog input, the return value at the corresponding bit is undefined. - Page 68 ZWIR451x Programming Guide Note: Only pins from the same GPIO bank are read at the same time. If pins do not share the same GPIO bank, there will be a time difference between the accesses to their input registers. All pins belonging to the same GPIO bank are highlighted with the same color in Figure 5.1 and Figure 5.2.
- Page 69 ZWIR451x Programming Guide ZWIR_Pin12 ZWIR_Pin13 ZWIR_Pin14 ZWIR_Pin16 ZWIR_Pin17 ZWIR_Pin18 ZWIR_Pin19 ZWIR_Pin20 ZWIR_Pin21 ZWIR_Pin22 ZWIR_Pin23 ZWIR_Pin24 ZWIR_Pin25 ZWIR_Pin26 typedef enum { ... } ZWIR_GPIO_DriverStrength_t This enumeration value specifies the driving strength of GPIO output pins. Low driving strength ZWIR_GPIO_dsLow Medium driving strength ZWIR_GPIO_dsMedium High driving strength ZWIR_GPIO_dsHigh...
- Page 70 ZWIR451x Programming Guide typedef enum { ... } ZWIR_GPIO_InputMode_t This enumeration value specifies the mode of GPIO input pins. Analog input (default configuration) ZWIR_GPIO_imAnalog Floating input ZWIR_GPIO_imFloating Pull-up input ZWIR_GPIO_imPullUp Pull-down input ZWIR_GPIO_imPullDown typedef enum { ... } ZWIR_GPIO_RemapFunction_t This enumeration type is used to specify which remapping is to be changed with ZWIR_GPIO_Remap. Configure remapping of the JTAG/SWD pins (Pin19 –...
-
Page 71: Ipsec Library Reference
ZWIR451x Programming Guide IPSec Library Reference The IPSec library provides functions to manage security policies and security associations. A security policy is added using ZWIRSEC_AddSecurityPolicy. Security Associations can be added using the function ZWIRSEC_AddSecurityAssociation. For more detailed information about security policies and security associations, refer to the ZWIR451x Application Note –... - Page 72 ZWIR451x Programming Guide The securityParamIdx argument is a unique number identifying the security association. The encSuite and authSuite parameters specify the encryption and authentication algorithms and keys. The replayCheck parameter determines if replay checks are performed for this security association. The internal replay check counter can only be reset by re-creating the specific security association.
- Page 73 ZWIR451x Programming Guide typedef struct { ZWIRSEC_EncryptionoAlgorithm_t algorithm uint8_t [ 16 ] uint8_t nonce [ } ZWIRSEC_EncryptionSuite_t This structure carries all encryption related information. It is used to pass encryption information to ZWIRSEC_AddSecurityAssociation. typedef struct { ZWIRSEC_AuthenticationAlgorithm_t algorithm uint8_t key [ 16 ] } ZWIRSEC_AuthenticationSuite_t This structure carries all authentication related information.
-
Page 74: Error Codes
ZWIR451x Programming Guide 6.2. Error Codes The error codes listed in Table 6.1 are generated by the IPsec libraries and passed to the ZWIR_Error hook if it is implemented in the application code. ZWIRSEC_eDroppedICMP indicates that an ICMP packet was dropped due to an IPsec rule and ZWIRSEC_eDroppedPacket indicates that any other (non-ICMP) packet was discarded due to an IPsec rule. -
Page 75: Ikev2 Library Reference
ZWIR451x Programming Guide IKEv2 Library Reference IKEv2 is used for IPSec key management. Using IKEv2, it is possible to limit the lifetime of a security association and automatically regenerate it with new keys. In order to add IKEv2 functionality to an application, the IKEv2 library must be linked into the project. -
Page 76: Library Parameters
The default setting corresponds to one day. In order to change this value, the variable ZWIRSEC_ikeSARekeyTime must be defined with an appropriate value in the application code. 7.2. Library Parameters Table 7.1 shows a summary of IDT’s IKEv2 library parameters and properties. Table 7.1 Overview of IKEv2 Library Parameters and Properties... -
Page 77: Over-The-Air Update Library
ZWIR451x Programming Guide Over-the-Air Update Library This library implements the Firmware Over-the-Air Update functionality. The only function exported from this library is used to register the Over-the-Air Update daemon in the system. 8.1. Library Reference void ZWIR_OTAU_Register ( uint16_t localPort ) Register the Over-the-Air Update daemon and configure the UDP port on which the daemon is listening. - Page 78 ZWIR451x Programming Guide ZWIR_sInvalidDataPacket OTAU packet does not belong to the same firmware version as the ongoing OTAU, or fragment is not inside the update segment. ZWIR_sFragmentWriteError Fragment could not be written to flash. ZWIR_sInvalidCRCPacket OTAU packet does not belong to the same firmware version as the ongoing OTAU, or fragment is not inside the CRC segment.
-
Page 79: Inclusion Of The Otau Library
ZWIR451x Programming Guide 8.2. Inclusion of the OTAU Library Including the OTAU library requires special care to ensure that the OTAU will remain functional with different firmware versions, which might be compiled with different compiler versions. The compiled binary program is divided into two sections: the first section that replaces the old firmware with the new one and a second section that handles the OTAU packet processing and storing the received data in the device’s flash memory. -
Page 80: Error Codes
ZWIR451x Programming Guide 8.3. Error Codes During module startup, the OTAU library performs different checks to verify whether the firmware is configured and linked appropriately. If one of these checks fails, the corresponding error is reported through ZWIR_Error and the OTAU functionality is disabled. The error code ZWIR_eInvalidVID is reported if the Vendor ID assigned in the firmware is invalid. -
Page 81: Netma Libraries
ZWIR451x Programming Guide NetMA Libraries IDT provides a protocol called Network Monitoring and Administration (NetMA) protocol, providing different functionalities to analyze the network. As of network stack version 1.9, there are two versions of this protocol available: NetMA1 and NetMA2. NetMA1 is deprecated and replaced with NetMA2. However, NetMA1 it is still available to keep compatibility with older stack releases. - Page 82 ZWIR451x Programming Guide void ZWIR_NetMA_RemoteParameterRequest ( ZWIR_IPv6Address_t* address, ZWIR_NetMA_RPRCallback_t callback, ZWIR_NetMA_RPRFields_t fields = 0, ZWIR_NetMA_Flags_t flags = 0, uint8_t respInterval = 3, uint8_t queryId = 0, uint8_t hopLimit = 0 ) Use this function to obtain configuration data remotely. Data can be requested from a single device or from multiple devices.
- Page 83 Selecting a different starting point is required for requests coming from nodes not implementing IDT’s network stack, e.g. computers in a network. Responses to route requests are received by the application through the function defined by callback. If callback is NULL, the trace request will not be executed.
- Page 84 ZWIR451x Programming Guide typedef struct { ZWIR_PANAddress_t address; int16_t linkRSSI; } ZWIR_NetMA_HopInfo_t Objects of this type are passed to the trace route callback function. Each object contains the address of a hop and the RSSI value of the forward path from the previous hop/source node to this node. Note that the RSSI of the return path might be slightly different.
- Page 85 ZWIR451x Programming Guide 0x20 ZWIR_NetMA_fHopCountLimitation typedef struct { ZWIR_NetMA_RemoteMACAddr_t* macAddr; ZWIR_NetMA_RemoteIPv6Addr_t* ipv6Addr; ZWIR_NetMA_RemoteConfig_t* config; ZWIR_NetMA_RemoteVersion_t* version; ZWIR_NetMA_RemoteStatus_t* status; } ZWIR_NetMA_RemoteData_t This structure contains pointers to the remote parameters received in response to a remote parameter request. The fields correlate with the ZWIR_NetMA_RPRFields_t enumerators. For each requested field, the corresponding pointer should be set in the response.
-
Page 86: Inclusion Of The Netma1 Library
ZWIR451x Programming Guide typedef struct { uint16_t routeTimeout; uint16_t routingTableSize; uint16_t neighborReachableTime; uint8_t neighborCacheSize; uint8_t maxNetfloodHopCount; uint8_t maxSocketCount; uint8_t routeMaxFailCount; int8_t routeRequestMinLinkRSSI; uint8_t routeRequestMinLinkRSSIReduction; uint8_t routeRequestAttempts; uint8_t channel; uint8_t power; uint8_t modulation; uint8_t doDuplicateAddressDetection; uint8_t doRouterSolicitation; } ZWIR_NetMA_RemoteConfig_t Objects of this type are used to report the configuration of the remote device. typedef ZWIR_TRXStatistic_t ZWIR_NetMA_RemoteStatus_t... -
Page 87: Netma2 Libraries
ZWIR451x Programming Guide 9.2. NetMA2 Libraries NetMA2 is an advancement of the NetMA1 protocol that is not downward compatible. It provides extended functionality including network discovery, topology discovery, remote parameter readout and modification, param- eter storage, route tracing and routing table readout. In addition to the extended functionality, NetMA2 provides advanced filtering, allowing restriction of the scope of multicast requests sent into the network. -
Page 88: Inclusion Of The Netma2 Libraries
ZWIR451x Programming Guide Note: This function is called for any packet received on the configured NetMA2 port. Thus, NetMA2 requests will trigger the execution of this function as well. In order to keep NetMA2 fully functional, the application must return false for each NetMA2 request that has not been handled. bool ZWIR_NetMA_Filter ( uint8_t* data,... -
Page 89: Accessing Microcontroller Resources
ZWIR451x Programming Guide 10 Accessing Microcontroller Resources Many applications can be optimized by using the rich internal resources provided by the ZWIR451x module’s STM32 microcontroller. Typically, this does not cause problems, but some caution must be taken when this is considered. -
Page 90: Table 10.1 Stm32 Interrupt Vector Table
ZWIR451x Programming Guide Table 10.1 lists the interrupts for the STM32. For each interrupt, the handler name, the default priority, and the default behavior is shown and whether or not the interrupt can be overwritten. Table 10.1 STM32 Interrupt Vector Table Interrupt Implementation Name... - Page 91 ZWIR451x Programming Guide Interrupt Implementation Name Handler Priority Default Behavior USB_HP_CAN_TX ZWIR_ISR_USB_HP_CAN1_TX NULL USB_LP_CAN_RX0 ZWIR_ISR_USB_LP_CAN1_RX0 NULL CAN_RX1 ZWIR_ISR_CAN1_RX1 NULL CAN_SCE ZWIR_ISR_CAN1_SCE NULL EXTI9_5 ZWIR_ISR_EXTI9_5 NULL TIM1_BRK ZWIR_ISR_TIM1_BRK NULL TIM1_UP ZWIR_ISR_TIM1_UP NULL TIM1_TRG_COM ZWIR_ISR_TIM1_TRG_COM NULL TIM1_CC ZWIR_ISR_TIM1_CC NULL TIM2 ZWIR_ISR_TIM2 NULL TIM3 ZWIR_ISR_TIM3 NULL...
-
Page 92: Default I/O Configuration
ZWIR451x Programming Guide Interrupt Implementation Name Handler Priority Default Behavior FSMC ZWIR_ISR_FSMC NULL SDIO ZWIR_ISR_SDIO NULL TIM5 ZWIR_ISR_TIM5 NULL SPI3 ZWIR_ISR_SPI3 NULL UART4 ZWIR_ISR_UART4 NULL UART5 ZWIR_ISR_UART5 NULL TIM6 ZWIR_ISR_TIM6 NULL TIM7 ZWIR_ISR_TIM7 NULL DMA2_Channel1 ZWIR_ISR_DMA2_Channel1 NULL DMA2_Channel2 ZWIR_ISR_DMA2_Channel2 NULL DMA2_Channel3 ZWIR_ISR_DMA2_Channel3 NULL... -
Page 93: Table 10.2 Stm32 Default I/O Configuration
ZWIR451x Programming Guide Table 10.2 STM32 Default I/O Configuration Port Configuration Drive Comment Analog Input Freely configurable by application, but not to be used as external interrupt source Floating Input With libZWIR451x-UART2.a with flow control enabled Analog Input Freely configurable by application 2 MHz Push/Pull Alternative Output With libZWIR451x-UART2.a with flow control enabled... - Page 94 ZWIR451x Programming Guide Port Configuration Drive Comment Pull-down Input Initially configured as JTAG pin Freely configurable by application when remapping is enabled Pull-up Input Initially configured as JTAG pin Freely configurable by application when remapping is enabled Pull-up Input Configuration locked, application MUST NOT modify the output data register Floating Input...
- Page 95 ZWIR451x Programming Guide Port Configuration Drive Comment Analog Input Configuration locked Analog Input Configuration locked Analog Input Configuration locked Analog Input Configuration locked Analog Input Configuration locked Analog Input Configuration locked Analog Input Configuration locked Analog Input Freely configurable by application Analog Input Freely configurable by application Analog Input...
-
Page 96: Certification
ZWIR451x Programming Guide 11 Certification 11.1. European R&TTE Directive Statements The ZWIR4512 module has been tested and found to comply with Annex IV of the R&TTE Directive 1999/5/EC and is subject of a notified body opinion. The module has been approved for Antennas with gains of 4 dBi or less. 11.2. -
Page 97: Accessing The Fcc Id
ZWIR451x Programming Guide Figure 11.1 FCC Compliance Statement to be Printed on Equipment Incorporating ZWIR4512 Devices Contains FCC ID: COR-ZWIR4512AC1 This device complies with part 15 of the FCC Rules. Operation is subject to the following two conditions: (1) This device may not cause harmful interference, and (2) this device must accept any interference received, including interference that may cause undesired operation. -
Page 98: Alphabetical Lists Of Symbols
ZWIR451x Programming Guide 12 Alphabetical Lists of Symbols 12.1. Functions and Function-Like Macros ZWIR_AbortPowerDown ........57 ZWIR_MulticastPreferExistingRepeater ....52 ZWIR_AddAlternativeAddress ........ 54 ZWIR_NetEventCallback ........41 ZWIR_AppInitHardware .......... 37 ZWIR_NetMA_Filter ..........87 ZWIR_AppInitNetwork ..........37 ZWIR_NetMA_RemoteParameterRequest .... 81 ZWIR_AppInitNetworkDone ........37 ZWIR_NetMA_ResponseHandler ...... -
Page 99: Data Types
ZWIR451x Programming Guide ZWIR_TriggerAppEvent ......... 40 ZWIR_UART2_PRINTF ......... 65 ZWIR_UART1_GetAvailableTXBuffer ....65 ZWIR_UART2_ReadByte ........64 ZWIR_UART1_IsTXEmpty ........65 ZWIR_UART2_Send..........63 ZWIR_UART1_PRINTF .......... 65 ZWIR_UART2_SendByte ........63 ZWIR_UART1_ReadByte ........64 ZWIR_UART2_SetRXCallback ......64 ZWIR_UART1_Send ..........63 ZWIR_UART2_Setup ..........64 ZWIR_UART1_SendByte ........63 ZWIRSEC_AddIKEAuthenticationEntry .... - Page 100 ZWIR451x Programming Guide ZWIR_NetMA_RemoteStatus_t ......85 ZWIR_protoTCP ..........73 ZWIR_NetMA_RemoteVersion_t ......86 ZWIR_protoUDP ..........73 ZWIR_NetMA_RPRFields_t ........83 ZWIR_RadioChannel_t .......... 50 ZWIR_NetMA_rprfConfig ........84 ZWIR_channel0..........50 ZWIR_NetMA_rprfFirmwareVersion ....83 ZWIR_channel1..........50 ZWIR_NetMA_rprfIPv6Addresses ...... 84 ZWIR_channel10..........51 ZWIR_NetMA_rprfMACAddress ......83 ZWIR_channel100..........51 ZWIR_NetMA_rprfTRXStatistics ......
-
Page 101: Variables And Constants
ZWIR451x Programming Guide ZWIR_spHeaderCompressionContext2....62 ZWIR_UART1_eOvfl .......... 66 ZWIR_spHeaderCompressionContext3....62 ZWIR_UART1_eParity ........66 ZWIR_spMaxHopCount ........61 ZWIR_UART2_ErrorCode_t ZWIR_spMaxSocketCount ........61 ZWIR_UART2_eFrame ........66 ZWIR_spNeighborCacheSize ......61 ZWIR_UART2_eNoise ........66 ZWIR_spNeighborReachableTime ..... 61 ZWIR_UART2_eOvfl .......... 66 ZWIR_spNeighborRetransTime ......62 ZWIR_UART2_eParity ........66 ZWIR_spRouteMaxFailCount ...... -
Page 102: Related Documents
Neighbor Discovery for IP Version 6 (IPv6) IPv6 Stateless Address Autoconfiguration Transmission of IPv6 Packets over IEEE 802.15.4 Networks IDT Documents ZWIR4512 Data Sheet ZWIR451x Application Note – Using IPSec and IKEv2 in 6LoWPANs* ZWIR451x Application Note – Enabling Firmware Over-the-Air Updates* ZWIR45xx Application Note –... -
Page 103: Glossary
ZWIR451x Programming Guide 14 Glossary Term Description 6LoWPAN IPv6 over Low Power Wireless Personal Area Networks Advanced Encryption Standard Authentication Header Application Programming Interface Address Resolution Protocol BPSK Binary Phase Shift Keying Cyclic Block Cipher Duplicate Address Detection DHCP Dynamic Host Configuration Protocol Extensible Authentication Protocol Encapsulating Security Payload GPIO... - Page 104 ZWIR451x Programming Guide Term Description Personal Area Network Phase-Locked Loop Pre Shared Key QPSK Quadrature Phase Shift Keying Router Advertisement Resistive Capacitive Request for Comments (a type of technical document maintained by the Internet Engineering Task Force) Router Solicitation RSSI Receive Signal Strength Indicator Real-Time Clock Security Association...
-
Page 105: Document Revision History
IDT's products are not intended for use in applications involving extreme environmental conditions or in life support systems or similar devices where the failure or malfunction of an IDT product can be reasonably expected to significantly affect the health or safety of users. Anyone using an IDT product in such a manner does so at their own risk, absent an express, written agreement by IDT.
Need help?
Do you have a question about the ZWIR451 Series and is the answer not in the manual?
Questions and answers