ZWIR451x Programming Guide
© 2016 Integrated Device Technology, Inc.
1
April 12, 2016
Content
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
Page 1: ...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...
Page 2: ...lization 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...
Page 3: ...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 His...
Page 4: ...amples 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...
Page 5: ...re 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...
Page 6: ...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 limite...
Page 7: ...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 Th...
Page 8: ...REPROCESSOR_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 diffe...
Page 9: ...gured 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 an...
Page 10: ...pecific 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...
Page 11: ...used by the stack are initialized and the random number generator is seeded Also peripherals required by certain libraries are initialized if the corresponding library is linked into the project After...
Page 12: ...de Call user defined callback function The operating system provides five application event handlers that can be used to process application events in the context of the operating system scheduler App...
Page 13: ...by a call to ZWIR_TransceiverOff This mode has the highest power consumption In Sleep Mode the MCU core is disabled but the MCU peripherals are still functioning if required The transceiver can be sw...
Page 14: ...t 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 recoverable error the ZWIR_Erro...
Page 15: ...a version information field that is freely usable for application purposes It is set by defining the global variable ZWIR_firmwareMajorVersion If this variable is not defined the value will be read a...
Page 16: ...ignment IPv6 provides a mechanism that performs automatic address configuration This mechanism is explained in section 2 8 3 2 8 2 IPv6 Addresses IPv6 addresses are 128 bit and therefore 16 bytes wide...
Page 17: ...with the most significant 8 bits set to FFHEX followed by two 4 bit fields for flags and the scope of the multicast packet The remaining bits specify the multicast group ID Figure 2 4 IPv6 Multicast A...
Page 18: ...me way as for the link local address Router solicitation is done automatically during the startup phase If there is no router on the link no global address will be assigned and only link local communi...
Page 19: ...and the network initialization must be restarted This is done by calling ZWIR_ResetNetwork The procedure can be repeated for an arbitrary number of times until a unique address is found Note that a d...
Page 20: ...and Reception Data transmission is requested by calling ZWIR_SendUDP or ZWIR_SendUDP2 Both functions send a single UDP packet to a remote host ZWIR_SendUDP2 accepts the address and port of the remote...
Page 21: ...whether communication is possible or not Table 2 5 Unicast Socket Examples A fe80 1 1 1 1 Rem Addr fe80 2 2 2 2 Rem Port 55555 Local Port 44444 B fe80 2 2 2 2 Rem Addr fe80 1 1 1 1 Rem Port 44444 Loc...
Page 22: ...Rem Addr ff12 x x x x x x x Rem Port 55555 Local Port 44444 D fe80 x x x x Rem Addr fe80 1 1 1 1 Rem Port x Local Port 55555 E fe80 x x x x Rem Addr Rem Port x Local Port 55555 Sender Recipients A D a...
Page 23: ...the header compression mechanism is capable of eliding link local IPv6 addresses completely from the compressed header Therefore using manually assigned IPv6 addresses is NOT RECOMMENDED Instead the I...
Page 24: ...is queued and the route discovery process is started A Route Request RReq is broadcasted into the network requesting a route to the destination address of the unicast packet Nodes receiving an RReq c...
Page 25: ...oints and relays On endpoints the table size should be equal to or larger than the number of remote nodes that the device is intended to communicate with On relays this number should be increased by t...
Page 26: ...any link is less likely to drop below the sensitivity level of the module 2 11 Network and Device Status The API provides functions for discovering the network and requesting the device status Network...
Page 27: ...the stack the libZWIR45xx IPSec a library must be included in the project and must be configured appropriately IPSec maintains a Security Policy Database SPD that contains rules for how outgoing and i...
Page 28: ...xchange algorithm Both communicating parties use a Pre Shared Key PSK for mutual authentication The PSK is registered using the ZWIRSEC_AddIKEAuthenticationEntry function After setup of the secure cha...
Page 29: ...The application code is located after the update_code and status_seg sections Optionally the OTAU memory layout can incorporate a section for the storage of permanent parameters This section MUST be...
Page 30: ...these sections In order to allow the OTAU from a firmware version A to a firmware version B the firmware versions MUST share the following properties The call stack of A and B must be located at the...
Page 31: ...IDT Network Stack Dynamic RAM Requirements IDT s network stack has a number of configurable parameters that require allocation of memory at runtime During system startup and after reset memory for th...
Page 32: ...r the application developers must be aware of the limited availability of RAM on the device Each allocated block consumes an additional 32 byte block on the heap for the allocation record Due to memor...
Page 33: ...ets received with this extension header are silently dropped o Specification requirement of receiving 1500 byte packets is not supported However use of fragmentation is discouraged by the RFC Destinat...
Page 34: ...selection is not performed in a round robin manner as proposed by the standard instead the first entry found is taken However reachable routers still have precedence over routers whose reachability is...
Page 35: ...group cannot be changed Only one initial exchange can occur at the same time Only one pair of child SAs can be negotiated with one IKE SA Windowing is not supported Timeouts are defined by user The cr...
Page 36: ...e further network parameters if required However it must not be used for sending out data as the node has not completed Duplicate Address Detection DAD refer to section 2 8 4 for further details at th...
Page 37: ...w watchdog has triggered ZWIR_rLowPowerReset Reason The supply voltage dropped below the specified threshold 3 2 Program Control The API does not provide the concept of a central main function as is t...
Page 38: ...eives or transmits data the packet will be lost void ZWIR_ResetNetwork void This function resets the radio transceiver and reinitializes the network stack After a call to this function IPv6 address au...
Page 39: ...ng callback timer If no timer is running nothing will happen void ZWIR_TriggerAppEvent uint8_t eventId This function allows the processing of application events with a certain operating system priorit...
Page 40: ...on 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 The event type is passed in the...
Page 41: ...producible application behavior for debug purposes Using non zero seed values in pro duction code is not recommended 3 3 Networking A ZWIR451x node can join any IPv6 network Each device automatically...
Page 42: ...ss allow reading and writing the PAN address ZWIR_PANAddress_t const ZWIR_GetPANAddress void Reads and returns the link layer address of the module void ZWIR_SetPANAddress ZWIR_PANAddress_t const panA...
Page 43: ...network interface The function returns true if the operation was successful or false otherwise The function fails if the maximum number of IPv6 addresses is assigned to the interface already uint8_t...
Page 44: ...4 ZWIR_IPv6Address_t Data type for representation of IPv6 addresses Bytes are stored in network byte order which is big endian i e the highest order byte is stored first Therefore using the u16 or u32...
Page 45: ...tHandle_t socket Open sockets are closed using this function If a socket is invalid or has already been closed the function has no effect Closing a socket has no effect on any previously sent packets...
Page 46: ...d After a zero result control must always be passed to the operating system Otherwise the output buffers will never be freed and this function continues to fail resulting in a deadlock Note This funct...
Page 47: ...rns the source PAN address of the latest received packet Note Using this function outside the receive callback might cause unreliable results ZWIR_PANAddress_t ZWIR_GetDestinationPANAddress void Retur...
Page 48: ...et Instead it is passed directly to the 6LoWPAN processing layer The data argument must point to the first header byte of the IPv6 UDP packet length specifies the size including all headers This is us...
Page 49: ...loss of the packet To verify the transceiver parameter the corresponding get function ZWIR_GetChannel ZWIR_GetModulation or ZWIR_GetTransmitPower can be called void ZWIR_SetChannel ZWIR_RadioChannel_t...
Page 50: ...are too low or too high are automatically adjusted to the closest valid value Note If this is done while a transmission is ongoing the transmitted packet is very likely to be lost For that reason it i...
Page 51: ...ble or configuration parameters should be set remotely it would be desirable to have the opportunity of performing higher layer processing of incoming packets that are addressed to the bridge For this...
Page 52: ...nable sending broadcast packets that will be rebroadcasted by nodes with existing multi hop routes repeater only If enabled all broadcast packets will only be rebroadcast from devices with existing mu...
Page 53: ...neighbor discovery The dutyCycle filed contains the ratio of time spent sending and the time elapsed since the occurrence of one of the above events In order to obtain the actual duty cycle percentage...
Page 54: ...tiveAddress ZWIR_PANAddress_t address ZWIR_AlternativeAddressType_t type This function adds a PAN address to the alternative address list The address argument specifies the address to be added and the...
Page 55: ...AControl_t pacontrol The ZWIR module provides two pins to control an external power amplifier These pins are toggled depending on RX or TX This function will enable or disable the PA pins and adjust t...
Page 56: ...transceiver interrupt or event is masked the transceiver will be switched off automatically All three power modes can be executed immediately or delayed to send out all buffered packets After entering...
Page 57: ...wer 64 interrupts to be selected as a wakeup source The bits correspond to the interrupt position according to the Nested Vectored Interrupt Controller NVIC documentation in the STM32 Reference Manual...
Page 58: ...dUDP ZWIR_SendUDP2 and ZWIR_Send6LoWPAN while the transceiver is switched off will fail and the sent data will be lost To turn the transceiver on the functions ZWIR_TransceiverOn or ZWIR_ResetNetwork...
Page 59: ...ation Each productive firmware version MUST include a valid set of version information The complete set consists of major and minor version number version extension vendor ID and product ID For more d...
Page 60: ...ation changes are effective immediately when this function is called from ZWIR_AppInitHardware Otherwise the new value is buffered until ZWIR_ResetNetwork is called int64_t ZWIR_GetParameter ZWIR_Syst...
Page 61: ...efer to section 2 9 3 ZWIR_spDoAddressAutoConfiguration 1 1 Refer to section 2 8 3 3 7 Error Codes The error codes listed in Table 3 2 are generated by the core library and passed to the ZWIR_Error ho...
Page 62: ...e UART interface data are kept in the buffer until read by ZWIR_UART _ReadByte If the buffer is full and more data are received ZWIR_Error is called with ZWIR_UART1_eOvfl as the argument The UART libr...
Page 63: ...the stop bit generation and controls whether flow control is used or not The parameters argument is generated from a binary OR combination of one constant from each block described below Default value...
Page 64: ...ike printf are used an appropriate low level function must be provided that can output characters to a device This macro defines a low level output function writing to the UART interface This macro mu...
Page 65: ...emented in the application code Table 4 1 Error Codes Generated by the UART Libraries C Identifier Code Default Handling libZWIR451x UART1 a ZWIR_UART1_eOvfl 210HEX Ignore ZWIR_UART1_eParity 211HEX Ig...
Page 66: ...gured If multiple pins are to be configured provide a binary OR ed combination of the enumeration values corresponding to the pins The driver argument determines the driving strength of the pin the mo...
Page 67: ...with the ZWIR_GPIO_Pin_t enumeration values Figure 5 1 ZWIR_GPIO_ReadMultiple Result Alignment in ZWIR4512AC1 Devices Figure 5 2 ZWIR_GPIO_ReadMultiple Result Alignment in ZWIR4512AC2 Devices Pin 17 P...
Page 68: ...ll up or pull down input writing to the output register of this pin can change the pull up pull down config uration accidentally void ZWIR_GPIO_Remap ZWIR_GPIO_RemapFunction_t function int32_t value T...
Page 69: ...This enumeration value specifies the driving strength of GPIO output pins ZWIR_GPIO_dsLow Low driving strength ZWIR_GPIO_dsMedium Medium driving strength ZWIR_GPIO_dsHigh High driving strength typede...
Page 70: ...n Pull down input typedef enum ZWIR_GPIO_RemapFunction_t This enumeration type is used to specify which remapping is to be changed with ZWIR_GPIO_Remap ZWIR_GPIO_rfSWJ Configure remapping of the JTAG...
Page 71: ...arguments specify the traffic that is affected by this policy See section 2 12 and the ZWIR451x Application Note Using IPSec and IKEv2 in 6LoWPANs for more details The function returns the security po...
Page 72: ...ccessfully If there is an error the function returns NULL void ZWIRSEC_RemoveSecurityAssociation ZWIRSEC_SecurityAssociation_t sa This function removes the security association pointed to by sa typede...
Page 73: ...pass authentication information to ZWIRSEC_AddSecurityAssociation typedef void ZWIRSEC_SecurityAssociation_t Objects of this type are returned by ZWIRSEC_AddSecurityAssociation They are passed to ZWI...
Page 74: ...scarded due to an IPsec rule ZWIRSEC_eUnknownSPI indicates that an IPsec packet was received but no associated security association was found With active replay check ZWIRSEC_eReplayedPacket indicates...
Page 75: ...Pv6 address of the remote device prefixLength contains the prefix length of remoteAddress The device identifier is given in id Its length is specified in idLength The presharedKey argument carries a p...
Page 76: ...s 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...
Page 77: ...o the list of possible ZWIR_OTAU_StatusCode_t values for more detailed information about event indicators typedef enum ZWIR_OTAU_StatusCode_t This enumeration defines event indicators that are supplie...
Page 78: ...en to flash ZWIR_sInvalidExecutePacket OTAU packet does not belong to the same firmware version as the ongoing OTAU or the packet contains an invalid page count ZWIR_sFirmwareImageVerifyFailed Integri...
Page 79: ...he following sections update_code interface_seg and status_seg The location order and contents of these sections in the linker script MUST NOT be changed The update_code section contains the code for...
Page 80: ...functionality is disabled The error code ZWIR_eInvalidVID is reported if the Vendor ID assigned in the firmware is invalid Refer to the sections 2 13 and 3 5 for further information The error code ZWI...
Page 81: ...ation of routes through the network The full functionality can be used from a computer that is connected to the network or directly from PAN nodes For the use with PAN nodes the NetMA1 library provide...
Page 82: ...h options are available flags limits the scope of the request which is especially useful in conjunction with multicast addressing For example it is possible to send requests only to devices configured...
Page 83: ...he application through the function defined by callback If callback is NULL the trace request will not be executed Returned route information contains the list of all hops to routeDestination together...
Page 84: ...must be included in the response The values can be binary OR ed to request multiple sets of information at the same time The following values are available ZWIR_NetMA_rprfMACAddress 0x0100 include ZW...
Page 85: ...hould be set in the response Fields that have not been requested result in a NULL pointer of the corresponding structure element typedef struct uint16_t panID ZWIR_PANAddress_t panAddr ZWIR_NetMA_Remo...
Page 86: ...device typedef ZWIR_TRXStatistic_t ZWIR_NetMA_RemoteStatus_t This type defines the remote status as being equal to the transceiver statistics type typedef struct uint32_t vendorID uint16_t productID u...
Page 87: ...ZWIR_DiscoverNetwork ZWIR_DiscoveryCallback_t callback uint8_t responseInterval This function initiates network discovery A network discovery request is broadcasted to all nodes in the network The cal...
Page 88: ...ers If no custom handling of NetMA2 requests is provided by the application this function does not need to be called as the NetMA2 request default handlers call this function automatically 9 2 2 Inclu...
Page 89: ...equency is always 8MHz Important recommendation The frequencies of APB1 and APB2 SHOULD NOT be changed Doing so would result in improper timing behavior of the operating system and could result in sys...
Page 90: ...IR_ISR_DebugMonitor 4 No NULL 8 PendSV ZWIR_ISR_PendSV 5 No NULL 9 SysTick ZWIR_ISR_SysTick 6 Yes Used as operating system timer 10 WWDG ZWIR_ISR_WWDG 7 No NULL 11 PVD ZWIR_ISR_PVD 8 No Perform system...
Page 91: ...1 I2C1_EV ZWIR_ISR_I2C1_EV 38 No NULL 42 I2C1_ER ZWIR_ISR_I2C1_ER 39 No NULL 43 I2C2_EV ZWIR_ISR_I2C2_EV 40 No NULL 44 I2C2_ER ZWIR_ISR_I2C2_ER 41 No NULL 45 SPI1 ZWIR_ISR_SPI1 42 No NULL 46 SPI2 ZWIR...
Page 92: ...ISR_TIM7 62 No NULL 66 DMA2_Channel1 ZWIR_ISR_DMA2_Channel1 63 No NULL 67 DMA2_Channel2 ZWIR_ISR_DMA2_Channel2 64 No NULL 68 DMA2_Channel3 ZWIR_ISR_DMA2_Channel3 65 No NULL 69 DMA2_Channel4_5 ZWIR_ISR...
Page 93: ...nput With libZWIR451x UART2 a A4 4 4 Analog Input Freely configurable by application A5 3 3 Analog Input Freely configurable by application A6 2 2 Analog Input Freely configurable by application A7 1...
Page 94: ...apping is enabled B4 Floating Input Configuration locked B5 Floating Input Configuration locked B6 24 26 Floating Input Freely configurable by application B7 23 25 Floating Input Freely configurable b...
Page 95: ...Analog Input Configuration locked C8 Analog Input Configuration locked C9 Analog Input Configuration locked C10 Analog Input Configuration locked C11 Analog Input Configuration locked C12 Analog Input...
Page 96: ...ween the equipment and receiver Connect the equipment into an outlet on a circuit different from where the receiver is connected Consult the dealer or an experienced radio TV technician for help This...
Page 97: ...their FCC ID electronically C API applications can read the module s FCC ID through the function ZWIR_GetFCCID Due to space constraints the FCC ID is not printed on the module Host devices incorporati...
Page 98: ...R_GPIO_ConfigureAsOutput 67 ZWIR_GPIO_Read 68 ZWIR_GPIO_ReadMultiple 68 ZWIR_GPIO_Remap 69 ZWIR_GPIO_Write 69 ZWIR_IsAlternativeAddress 55 ZWIR_LocalBroadcast 52 ZWIR_Main1000ms 39 ZWIR_Main100ms 39 Z...
Page 99: ...d 62 ZWIR_eRouteFailed 62 ZWIR_GatewayOutputFunction_t 52 ZWIR_GPIO_DriverStrength_t 71 ZWIR_GPIO_dsHigh 71 ZWIR_GPIO_dsLow 71 ZWIR_GPIO_dsMedium 71 ZWIR_GPIO_InputMode_t 71 ZWIR_GPIO_imAnalog 71 ZWIR...
Page 100: ...R_paOff 56 ZWIR_PANAddress_t 43 ZWIR_PowerDownState_t 59 ZWIR_pSleep 59 ZWIR_pSleepAfterActivities 59 ZWIR_pStandby 59 ZWIR_pStandbyAfterActivities 59 ZWIR_pStop 59 ZWIR_pStopAfterActivities 59 ZWIR_P...
Page 101: ...T1_ErrorCode_t ZWIR_UART1_eFrame 66 ZWIR_UART1_eNoise 66 ZWIR_UART1_eOvfl 66 ZWIR_UART1_eParity 66 ZWIR_UART2_ErrorCode_t ZWIR_UART2_eFrame 66 ZWIR_UART2_eNoise 66 ZWIR_UART2_eOvfl 66 ZWIR_UART2_ePari...
Page 102: ...P 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...
Page 103: ...ncapsulating Security Payload GPIO General Purpose Input Output ICMP Internet Control Message Protocol IETF Internet Engineering Task Force IKEv2 Internet Key Exchange version 2 IPSec Internet Protoco...
Page 104: ...s a type of technical document maintained by the Internet Engineering Task Force RS Router Solicitation RSSI Receive Signal Strength Indicator RTC Real Time Clock SA Security Association SAD Security...
Page 105: ...DT com go support DISCLAIMER Integrated Device Technology Inc IDT reserves the right to modify the products and or specifications described herein at any time without notice at IDT s sole discretion P...
