IQRF

DPA Framework

 

Technical Guide

 

Version v3.01

IQRF OS v4.00D

 

31. 8. 2017

 

 

 

 

 

 

 

 

 

 

 

image

Table of Contents

1       Introduction. 8

2       Basics. 8

2.1         Device types. 8

2.2         RF Modes. 8

2.3         Interfaces. 8

2.3.1      SPI 8

2.3.2      UART. 8

2.3.3      Peripherals vs. Interfaces. 10

2.3.3.1            Peripherals. 10

2.4         DPA Plug-in filename. 10

2.5         Message parameters. 10

2.6         DPA Messages. 11

2.6.1.1            Interfaces. 12

2.6.2      DPA Request 12

2.6.3      DPA Confirmation. 12

2.6.4      DPA Notification. 15

2.6.5      DPA Response. 15

2.6.6      Examples. 15

2.7         Device exploration. 16

2.7.1      Peripheral enumeration. 16

2.7.1.1            Source code support 17

2.7.2      Get peripheral information. 17

2.7.2.1            Source code support 18

2.7.3      Get information for more peripherals. 18

2.7.3.1            Source code support 18

3       Peripherals. 18

3.1         Standard operations in general 19

3.1.1      Writing to peripheral 19

3.1.1.1            Source code support 19

3.1.2      Reading from peripheral 19

3.1.2.1            Source code support 20

3.2         Coordinator 20

3.2.1      Peripheral information. 20

3.2.2      Get addressing information. 20

3.2.2.1            Source code support 20

3.2.3      Get discovered nodes. 20

3.2.4      Get bonded nodes. 20

3.2.4.1            Source code support 21

3.2.5      Clear all bonds. 21

3.2.6      Bond node. 21

3.2.6.1            Source code support 21

3.2.7      Remove bonded node. 22

3.2.7.1            Source code support 22

3.2.8      Re-bond node. 22

3.2.8.1            Source code support 23

3.2.9      Discovery. 23

3.2.9.1            Source code support 24

3.2.10        Set DPA Param.. 24

3.2.10.1          Source code support 25

3.2.11        Set Hops. 25

3.2.11.1          Source code support 25

3.2.12        Discovery data. 25

3.2.12.1          Source code support 26

3.2.13        Backup. 26

3.2.13.1          Source code support 26

3.2.14        Restore. 27

3.2.14.1          Source code support 27

3.2.15        Authorize bond. 27

3.2.15.1          Source code support 28

3.2.16        Enable remote bonding. 28

3.2.17        Read remotely bonded module ID.. 28

3.2.18        Clear remotely bonded module ID.. 28

3.3         Node. 28

3.3.1      Peripheral information. 28

3.3.2      Read. 28

3.3.2.1            Source code support 29

3.3.3      Remove bond. 29

3.3.4      Enable remote bonding. 29

3.3.4.1            Source code support 30

3.3.5      Read remotely bonded module ID.. 30

3.3.5.1            Source code support 30

3.3.6      Clear remotely bonded module ID.. 31

3.3.7      Remove bond address. 31

3.3.8      Backup. 31

3.3.9      Restore. 31

3.4         OS. 31

3.4.1      Peripheral information. 31

3.4.2      Read. 31

3.4.2.1            Source code support 32

3.4.3      Reset 32

3.4.4      Restart 32

3.4.5      Read HWP configuration. 33

3.4.5.1            Source code support 33

3.4.6      Write HWP configuration. 33

3.4.6.1            Source code support 34

3.4.7      Write HWP configuration byte. 34

3.4.7.1            Source code support 35

3.4.8      Run RFPGM.. 35

3.4.9      Sleep. 35

3.4.9.1            Source code support 36

3.4.10        Set Security. 36

3.4.10.1          Source code support 36

3.4.11        Batch. 37

3.4.12        Selective Batch. 37

3.4.12.1          Source code support 37

3.4.13        LoadCode. 38

3.4.13.1          Source code support 39

3.5         EEPROM.. 39

3.5.1      Peripheral information. 39

3.5.2      Read. 39

3.5.2.1            Source code support 40

3.5.3      Write. 40

3.5.3.1            Source code support 40

3.6         EEEPROM.. 41

3.6.1      Peripheral information. 41

3.6.2      Extended Read. 41

3.6.2.1            Source code support 41

3.6.3      Extended Write. 42

3.6.3.1            Source code support 42

3.7         RAM.. 42

3.7.1      Peripheral information. 42

3.7.2      Read & Write. 43

3.7.2.1            Source code support 43

3.8         SPI (Slave) 43

3.8.1      Peripheral information. 43

3.8.2      Write & Read. 43

3.9         LED.. 43

3.9.1      Peripheral information. 43

3.9.2      Set 43

3.9.3      Get 44

3.9.4      Pulse. 44

3.10       IO.. 44

3.10.1        Peripheral information. 44

3.10.2        Direction. 44

3.10.2.1          Source code support 45

3.10.3        Set 45

3.10.3.1          Source code support 46

3.10.4        Get 46

3.11       Thermometer 46

3.11.1        Peripheral information. 46

3.11.2        Read. 47

3.11.2.1          Source code support 47

3.12       PWM.. 47

3.12.1        Peripheral information. 47

3.12.2        Set 47

3.12.2.1          Source code support 48

3.13       UART. 48

3.13.1        Peripheral information. 49

3.13.2        Open. 49

3.13.2.1          Source code support 49

3.13.3        Close. 49

3.13.4        Write & Read. 50

3.13.4.1          Source code support 50

3.13.1        Clear & Write & Read. 51

3.14       FRC. 51

3.14.1        Peripheral information. 51

3.14.2        Send. 51

3.14.2.1          Source code support 52

3.14.3        Extra result 52

3.14.4        Send Selective. 52

3.14.4.1          Source code support 53

3.14.5        Set FRC Params. 53

3.14.5.1          Source code support 53

3.14.6        Embedded FRC Commands. 53

3.14.6.1          Prebonding. 54

3.14.6.2          UART or SPI data available. 54

3.14.6.3          Acknowledged broadcast - bits. 54

3.14.6.4          Read temperature. 54

3.14.6.5          Acknowledged broadcast - bytes. 55

3.14.6.6          Memory read. 55

3.14.6.7          Memory read plus 1. 56

3.14.6.8          FRC response time. 56

4       HWP Configuration. 58

5       Device Startup. 59

6       Autoexec. 61

7       IO Setup. 62

8       Custom DPA Handler 63

8.1         Handler Example. 64

8.2         Events Flow. 65

8.2.1      Coordinator 65

8.2.2      Node. 66

8.2.3      General events. 67

8.2.3.1            Interrupt 67

8.2.3.2            Disable Interrupts. 67

8.2.3.3            Sleep Events. 67

8.3         Events. 67

8.3.1      Interrupt 67

8.3.2      Idle. 68

8.3.3      Init 68

8.3.4      Notification. 69

8.3.5      AfterRouting. 69

8.3.6      BeforeSleep. 70

8.3.7      AfterSleep. 70

8.3.8      Reset 70

8.3.9      Disable Interrupts. 71

8.3.10        FrcValue. 71

8.3.11        FrcResponseTime. 72

8.3.12        ReceiveDpaResponse. 73

8.3.13        IFaceReceive. 73

8.3.14        ReceiveDpaRequest 73

8.3.15        BeforeSendingDpaResponse. 74

8.3.16        PeerToPeer 75

8.3.17        AuthorizePreBonding. 75

8.3.18        UserDpaValue. 76

8.3.19        BondingButton. 76

8.3.20        DPA Request 76

8.3.20.1          Enumerate Peripherals. 76

8.3.20.2          Get Peripheral Info. 77

8.3.20.3          Handle Peripheral Request 77

8.3.20.4          Alternative Event Processing. 78

8.4         DPA API 79

8.4.1      DpaApiRfTxDpaPacket 79

8.4.2      DpaApiReadConfigByte. 80

8.4.3      DpaApiSendToIFaceMaster 80

8.4.4      DpaApiRfTxDpaPacketCoordinator 80

8.4.5      DpaApiLocalRequest 81

8.4.6      DpaApiReturnPeripheralError 81

8.4.7      DpaApiSetRfDefaults. 82

8.5         DPA API Variables. 82

8.5.1      bit ProvidesRemoteBonding. 82

8.5.2      uns8 RemoteBondingCount 82

8.5.3      bit IFaceMasterNotConnected. 82

8.5.4      bit NodeWasBonded. 82

8.5.5      bit EnableIFaceNotificationOnRead. 83

8.5.6      uns16 DpaTicks. 83

8.5.7      uns8 LPtoutRF. 83

8.5.8      uns8 ResetType. 83

8.5.9      bit DSMactivated. 83

8.5.10        uns8 UserDpaValue. 83

8.5.11        uns8 NetDepth. 83

8.5.12        bit LpRxPinTerminate. 83

8.6         Examples. 83

8.6.1      Bonding. 84

8.6.2      AutoNetwork & Coordinator-AutoNetwork-Embedded. 85

8.6.3      Coordinator-FRCandSleep. 87

8.6.4      FRC-Minimalistic. 87

8.6.5      LED-MemoryMapping. 87

8.6.6      PeripheralMemoryMapping. 88

8.6.7      UserPeripheral-18B20. 88

8.6.8      UserPeripheral-18B20-Idle. 88

8.6.9      UserPeripheral-ADC. 88

8.6.10        UserPeripheral-HW-UART. 88

8.6.11        UserPeripheral-i2c. 88

8.6.12        UserPeripheral-PWM.. 88

8.6.13        UserPeripheral-SPImaster 89

9       DPA in Practice. 90

9.1         Network Deployment 90

9.2         Over The Air (OTA) upgrade of IQRF OS and DPA. 90

9.3         Code Upload. 92

9.3.1      Storing Code at External EEPROM.. 92

9.3.2      Executing Code Upload. 93

9.3.3      Executing IQRF OS Change. 94

10               Constants. 95

10.1       Peripheral Numbers. 95

10.2       Response Codes. 95

10.3       DPA Commands. 95

10.4       Peripheral Types. 97

10.5       Custom DPA Handler Events. 97

10.6       Extended Peripheral Characteristic. 97

10.7       HW Profile IDs. 97

10.8       Baud rates. 97

10.9       User FRC Codes. 98

11               Appendix. 99

11.1       CRC Calculation. 99

11.1.1        CC5X Compiler 99

11.1.2        C#. 99

11.1.3        Java. 99

11.1.4        Pascal/Delphi 100

11.2       One’s Complement Fletcher-16 Checksum Calculation. 100

11.2.1        CC5X Compiler 100

11.2.2        C#. 100

11.3       Custom DPA Handler Code at .hex File. 101

11.4       IQRF OS Change. 102

11.4.1        IQRF OS Change File. 103

11.5       Code Optimization. 104

11.5.1        W as a temporary variable. 104

11.5.2        Variable access reorder 104

11.5.3        Variable access decomposition. 104

11.5.4        Explicit MOVLB omitting. 104

11.5.5        Direct function parameter usage. 104

11.5.6        Avoiding else. 105

11.5.7        Switch instead of if 105

11.5.8        Function call before return. 105

11.5.9        Using goto to avoid redundant code. 106

11.5.10      Avoiding readFromRAM and getINDFx. 106

11.5.11      Advanced C-compiler optimized instructions. 106

11.5.12      do {} while () is preferred. 106

11.5.13      Use DECFSZ/INCFSZ. 107

11.5.14      Widening function parameter 107

11.5.15      Carry as a variable. 107

11.5.16      Limiting variable scope. 108

11.5.17      Using IQRF variables. 108

11.5.18      Parameter mapped to W.. 108

11.5.19      Pointer parameters mapped to FSRx. 109

11.5.20      FSRx as 16-bit variable. 109

11.5.21      Using FSRx to copy between buffers and variables. 109

11.5.22      Accessing 16-bit MCU registers. 109

11.5.23      Using IQRF OS offset and limit variables. 110

11.5.24      Effective is not always effective. 110

11.5.25      Assignment also have a value. 110

11.5.26      Interval detection optimization. 110

11.5.27      Optimized constants. 110

11.5.28      Equality result 110

11.5.29      One instruction at if branch. 111

11.5.30      Utilization of the preloaded W.. 111

11.5.31      == 1 is more effective than != 1. 111

11.5.32      == 0xFF is more effective than != 0xFF. 112

11.5.33      Expression modification. 112

11.5.34      Computed goto with a table limit 112

11.5.35      Default is first at switch. 112

11.5.36      Better to return from than after the loop. 113

11.5.37      Modification instead of storing value. 113

11.5.38      Assignment compares to 0. 113

11.5.39      End condition of 16-bit loop variable. 114

11.5.40      Shift for a smart comparison. 114

11.5.41      Optimized return TRUE/FALSE. 114

11.5.42      Avoiding MOVLP #1. 114

11.5.43      Avoiding MOVLP #2. 115

11.5.44      Setting zeroed variables. 115

11.5.45      Compare to zero is more effective. 115

11.5.46      setFSR01. 115

12               DPA Release Notes. 116

12.1       DPA 3.01. 116

12.2       DPA 3.00. 116

12.3       DPA 2.28. 117

12.4       DPA 2.27. 117

12.5       DPA 2.26. 117

12.6       DPA 2.24. 118

12.7       DPA 2.23. 118

12.8       DPA 2.22. 118

12.9       DPA 2.21. 119

12.10         DPA 2.20. 119

12.11         DPA 2.13. 119

12.12         DPA 2.12. 119

12.13         DPA 2.11. 120

12.14         DPA 2.10. 120

12.15         DPA 2.01. 121

12.16         DPA 2.00. 121

13               Document Revisions. 122


 

 1         Introduction

 

Direct Peripheral Access (DPA) protocol is a simple byte-oriented protocol used to control services and peripheralsof IQMESH network devices (coordinator and nodes) by SPI or UART interfaces. DPA protocol implementation is distributed in the form of IQRF plug-in.

The full version runs only at IQRF Data Controlled Transceivers (DCTR). There is a demo version that can run at ordinary IQRF Smart Transceivers (TR).

 

The demo version has the following features:

·            Some Custom DPA Handler events are not raised at demo version.

 2         Basics

 

DPA protocol uses byte structured messages to communicate at IQMESH network. Every message always contains four mandatory parameters NADR, PNUM, PCMD and HWPID (foursome from now). The message can optionally hold data (array of bytes often referred to as PData throughout the document) to be transmitted or received. They are always described next to the foursome throughout this document. Although foursome parameters are typically described next to each other in this document, they do not have to be stored at consecutive memory addresses at the real scenario. The same rule does not apply to the message data.

 

Please note that a response, confirmation, and notification (with a small exception) DPA messages always contain the same NADR, PNUM, and PCMD as the original request message except the response message is flagged by the most significant bit of PCMD.

 

All values wider than byte are coded using little-endian style.

 

Symbols, variables, structures, methods etc. mentioned in this document are defined in header files DPA.h and DPAcustomHandler.h. Please consult IQRF OS documentation whenever an IQRF OS function is referenced in this document.

 2.1     Device types

There are two device types depending on what type of network device it implements. For each device type, there is dedicated IQRF plug-in to upload.

 

[C]        IQMESH Coordinator device

[N]        IQMESH Node device

[CN]    This device implements both IQMESH Node functionality on the main network as well as Coordinator functionality in the optional subordinate network. [CN] device periodically switches between the RF channels of the main and subordinate networks. This might cause a loss of RF DPA message in one network if a DPA message of the other network is served at the same time.

 2.2     RF Modes

There is a separate DPA implementation for each of the IQRF RF modes (STD, LP) (as well as for Device types) prepared in the form of IQRF plug-in. Only STD and LP RF modes are supported. It is not possible to mix devices running at different modes at one IQRF MESH network.

 2.3     Interfaces

The chosen interface transfers DPA message to/from the connected device. The message consists of the successively stored foursome and optional data.

 2.3.1   SPI

The SPI interface is implemented using IQRF SPI protocol described in the document "SPI Implementation in IQRF TR modules". The document specifies how to setup SPI master and the communication over the SPI. The device always plays the role of SPI slave and the externally connected device is SPI master. The DPA protocol corresponds to the DM and DS bytes of IQRF SPI protocol.

 2.3.2   UART

UART is configured 8 data bits, 1 stop bit, and no parity bit. UART baud rate is specified at HWP Configuration. The size of both RX and TX buffers is 64 bytes.

 

HDLC byte stuffing protocol is used to frame, protect and encode DPA messages. Every data frame (DPA message) starts and ends with byte 0x7e (Flag Sequence). When actual data byte (applies to 8-bit CRC value too) equals to 0x7e (Flag Sequence) or 0x7d (Control Escape) then it is replaced by two bytes: a 1st byte is 0x7d (Control Escape) and 2nd byte equals to original byte value XORed by 0x20 (Escape Bit).

 

An 8-bit CRC is used to protect data. The CRC value is appended after all data bytes and it is coded by the same HDLC byte stuffing algorithm. CRC is compatible with 1-Wire CRC with an initial value 0xFF, the polynomial is x8+x5+x4+1. See CRC Calculation for the implementations of CRC algorithm. There is also an online calculator available.

 

Example

 

The example shows encoded DPA Request “write bytes 0x7E, 0x7D at the RAM address 0 at node with address 0x2F”:

 

NADR=0x002F(Node address), PNUM=0x05(RAM peripheral), PCMD=0x01(RAM write), HWPID=0xFFFF, PData={00(address), {7E, 7D}(bytes to write)

 

CRC from bytes {0x2f, 0x00, 0x05, 0x01, 0xff, 0xff, 0x00, 0x7e, 0x7d} = 0x7e

 

Data in index

 

0

1

2

3

4

5

6

7

8

CRC

 

Data in

0x2f

0x00

0x05

0x01

0xff

0xff

0x00

0x7e

0x7d

0x7e

Data out index

0

1

2

3

4

5

6

7

8

9

10

11

12

13

14

Data out

0x7e

0x2f

0x00

0x05

0x01

0xff

0xff

0x00

0x7d

0x5e

0x7d

0x5d

0x7d

0x5e

0x7e

Note

Flag Sequence

original byte

original byte

original byte

original byte

original byte

original byte

original byte

Control Escape

0x7e XOR 0x20

Control Escape

0x7d XOR 0x20

Control Escape

0x7e XOR 0x20

Flag Sequence


 

 2.3.3   Peripherals vs. Interfaces

SPI or UART peripherals differ from SPI or UART interfaces. In general, the peripheral is just byte oriented data channel used to exchange data between the network and external deviceswhile the interface is used to control network device from an external device using DPA messages. In the case of SPI, the external device must be an SPI master as the DPA network device is always an SPI slave.

 2.3.3.1               Peripherals

Peripherals are typically used to control an external device connected to the [N] or [CN] device via SPI or UART interface. The following picture shows an example where the [C] writes by UART Write & Read DPA request a text “Hello” to the UART peripheral at [N]. There is a terminal (external device) connected using UART to the [N]. Text “Hello” is then displayed at the terminal and text “Hi” (at this example the terminal automatically answers “Hi” to “Hello”) is read back to the [C] at the corresponding DPA response.

 

 image

 2.4     DPA Plug-in filename

DPA protocol implementation is distributed in the form of IQRF plug-in. The plug-in filename has the following format:

 

HWP-[device]-[rfmode]-[interface]-[dctr]-[version]-[date].iqrf

 

Item

Value

Description

[device]

Coordinator

Coordinator device [C]

Node

Node device [N]

[rfmode]

STD

STD RF mode

LP

LP RF mode

[interface]

SPI

SPI interface

UART

UART interface

<empty>

No interface supported (e.g. [N] at LP RF mode)

[dctr]

7xD

For (DC)TRs of 7xD series

[version]

Vabc

DPA version a.bc (e.g. V213 stands for version 2.13)

[date]

yymmdd

Release date (e.g. 140602 stands for June 2nd, 2014)

 2.5     Message parameters

All numbers are in hexadecimal format unless otherwise noted.

 

Parameter

Value [hex]

Description

NADR
[2B]

00                    IQMESH Coordinator

01-EF               IQMESH Node address
F0-FB               Reserved

FC                    Local (over interface) device
FD                   Reserved
FE                   IQMESH temporary address

FF                    IQMESH broadcast address

100-FFFF         Reserved

Network device address. Although it is 2 bytes wide, the 2B addressing is not supported (a higher byte is ignored).

PNUM
[1B]

00                    COORDINATOR

01                    NODE

02                    OS

03                    EEPROM

04                    EEEPROM

05                    RAM

06                    LEDR

07                    LEDG

08                    SPI

09                    IO

0A                    Thermometer

0B                    PWM [*]

0C                    UART

0D                    FRC

0E-1F               Reserved

20-3E               User peripherals

3F                    Not available

40-7F               Reserved

80-FF               Not available

Peripheral number

(0x00 – 0x1F reserved for embedded peripherals)

(0x40 – 0x7F reserved for IQRF standard peripherals)

 

PCMD
[1B]

0-3E                 Command value

3F                    Not available

40-7F               Command value

80-FF               Not available

Command specifying an action to be taken. Actually allowed value range depends on the peripheral type.

The most significant bit is reserved for indication of DPA response message.

HWPID

[2B]

0000                 Default HW Profile

0001-xxxE        Certified HW Profiles

xxxF                User HW Profiles

FFFF                Reserved

HW profile ID (HWPID from now) uniquely specifies the functionality of the device, the user peripherals it implements, its behavior etc. The only device having the same HWPID as the DPA request will execute the request. When 0xFFFF is specified then the device with any HW profile ID will execute the request. Note – HWPID numbers used throughout this document are fictitious ones.

PData

[0-56B]

An array of bytes. The maximum length is limited to 56 bytes (decimal).

Optional message data.

[*] Available at Demo version [N] device only. See source code at UserPeripheral-PWM.

 2.6     DPA Messages

DPA protocol (messages) is transferred over an interface that connects (DC)TR module (“slave”) to a superordinate system (”master”).

·         Master sends DPA request.

·         If addressee (NADR) is a (remote) IQMESH Node, not a local over the interface connected device (applies only to coordinator), then:

·         The device immediately sends DPA confirmation back to the interface master.

·         Node processes the DPA message.

·         If the DPA message does not have a read-only (can be configured by EnableSPInotificationOnRead) side-effect and the interface is configured for the DPA communication at the node side, then the node sends DPA notification to its SPI master.

·         If the DPA message was not sent using the broadcast address.

·         Node returns DPA response back to coordinator via RF.

·         Coordinator receives the DPA response and re-sends it to the interface master.

·         In case of a local device

·         The device processes the DPA request. In this case, the both sender and addressee addresses of the request are equal to 0xFC (local address).

·         The device returns DPA response back to interface master.

 2.6.1.1               Interfaces

The interface connects any ([C] or [N] or [CN]) network device to the external autonomous device and allows the external device to control the network and/or network device. By default the interface is always enabled at [C] device because it gives an external device means to control the [C] as well as the rest of the network. The interface at [CN] or [N] devices must be explicitly enabled at HWP Configuration. See DPA Messages for details of the messages exchanged over the interface. Next table shows some differences in the interface behavior at different network devices:

 

Topic / Device

[C]

[CN] and [N]

DPA Messages

DPA Request (in)
DPA Confirmation (out)
DPA Response (out)

DPA Request (in)
DPA Response (out)
DPA Notification (out)
Bridge command is not notified by DPA Notification at [CN] device.

NADR at DPA Request

See NADR at General message parameters. Invalid value generates an ERROR_NADR error code. Both values 0x0000 and 0x00FC address the [C] device itself.

Only value 0x00FC is allowed and it addresses the [CN] or [N] device itself. Other values are silently ignored. There is no way to directly control [C] device coupled to [CN] or [N].

 

See Examples of the interface usage.

 2.6.2   DPA Request

DPA request consists of a foursome with optional data, depending on the actual request. DPA request is executed only if the specified HW profile ID matches the HW profile ID of the device unless HW profile ID in the foursome equals to 0xFFFF (HWPID_DoNotCheck). In some scenarios, the request can be asynchronously sent from node to coordinator. Then it is marked as asynchronous the same way as asynchronous DPA Response.

 2.6.3   DPA Confirmation

DPA confirmation confirms a reception of DPA request by interface slave to interface master at the coordinator. It consists of the same foursome that was part of the original DPA request plus following 5 additional data bytes. The Confirmation is not returned if the Request is incorrect (e.g. if request NADR is not valid). In this case, Response with an error code is returned.

 

The format of the Confirmation data bytes is the following

 

0

1

2

3

4

STATUS_CONFIRMATION

DPA Value

Hops

Timeslot length in 10 ms units

 

Hops Response

 

DPA Value                   DPA value of the device.

Hops                            Number of hops used to deliver the DPA request to the addressed node. A hop represents any sending of a packet including sending from the sender as well as from any routing node.

Timeslot length             Timeslot length used to deliver the DPA request to the addressed node. Please note that the timeslot used to deliver the response message from node to coordinator can have a different length.

Hops Response            Number of hops used to deliver the DPA response from the addressed node back to the coordinator. In the case of broadcast, this parameter is 0 as there is no response sent back to the coordinator.


 

IQMESH timeslot length depends on the PData length of the DPA messages (the values may change in the future depending on the version of the DPA protocol and IQRF OS version) and the RF mode (STD, LP).

 

PData length [bytes]

Timeslot length [ms]

STD

LP

STD

LP

< 16

< 11

40

80

16 – 39

11 – 33

50

90

> 39

34 – 56

60

100

 

> 56

 

110

 

This information can be used to implement a precise timing of the control system (master) connected to the coordinator device by the interface in order to prevent data collision (e.g. when another DPA request is sent to the network before a routing of the previous communication is finished) at the network.

 

1.     Wait till the previous IQMESH routing is finished (see step 7).

2.     Make sure the interface is ready (e.g. SPI status is ReadyCommunication) and no data remained for reading from the interface.

3.     Send DPA request via the interface.

4.     Receive DPA confirmation via the interface. Remember the time when the confirmation was received (to be used later at step 7).

5.     Now, wait ( Hops + 1 ) × Timeslot length × 10 ms till the DPA Request routing is finished.
Note: if it takes some extra time to prepare and send the response back at the node side then, this time, must be considered (added) to the total routing time.

6.     Read DPA response from the interface within the time ( Hops Response + 1 ) × Estimated response timeslot length × 10 ms + Safety timeout. Estimated response timeslot length is the value based on expected length of data returned within the DPA response or it can be the worst case (e.g. 6 = 60 ms at STD mode). If the Timeslot length from the step 5 equals to the diagnostic long timeslot (20 = 200 ms), then use the same value for the estimated response timeslot length.

7.     Find out the Actual response timeslot length from the PData length of the actual DPA response. Now the earliest time to send something to the IQMESH network equals to: Time the DPA confirmation was received + ( Hops + 1 ) × Timeslot length × 10 ms + ( Hops Response + 1 ) × Actual response timeslot length × 10 ms. This time is used for waiting at step 1.

 

Using this technique ensures reliable and optimal speed data delivery at the IQMESH network. Pay attention to the DPA requests that produce an intentional delay at the addressed device side (e.g. UART Write& Read, SPI Write & Read, IO Set, OS Sleep, OS Reset). Such delay (time) must be added to the total response time. Also, the response time for Discovery and Bond node requests is not predictable at all.

 

Please note that OS Read command returns the shortest and the longest timeslot length.

 

Example

Next figure shows processing UART Write & Read request. The request is marked Request 1. It writes 5 bytes of data to node [Nn] UART peripheral, waits 20 ms and then reads a number (unknown in advance) of bytes back from UART peripheral. The network is operated at STD mode and 200 ms diagnostic time slot is not used.

 

After sending Request 1 to the coordinator [C] the [C] replies by Confirmation 1. The confirmation reports q hops to deliver a request from [C] to [Nn] with a timeslot of 40 ms and also r hops to deliver response back from [Nn] to [C]. After the confirmation is sent the [C] transmits RF packet to the network (1st hop). The packet is received by [N1] and [N1] routes the packet further (2nd hop). The routed packet is received by [N2] as expected. The routing continues. Last but one node [Nn-1] receives the routed packet and because of positive RF conditions and network topology the routed packet is also early received by the addressed node [Nn]. Then [Nn-1] makes very last routing but [Nn] does not receive the packet again.

 

Then DPA writes 5 bytes of data to the UART, waits another 20 ms and reads data from UART. In our example totally 20 bytes is read which results in the real timeslot of 50 ms to be used to deliver response back from [N3] to [C].

 

Then [Nn] waits for the still running routing to finish. After that [Nn] transmits the response packet to the network (1st hop). The packet is received by [Nn-1] which routes the packet further (2nd hop). The routing continues. The routed packet is received by [N2]. [N2] routes the packet to [N1]. The packet is also received also by [C]. [C] immediately delivers Response 1 to its interface. In the same time [N1] finally routes the packet to the [C] which receives it but identifies it as the already received response thus [C] does not report it to the interface again.

 

The optimistic response time is:

( ( q + 1 ) × 40 ms ) + 20 ms + ( ( r + 1 ) × 40 ms )

 

The pessimistic response time is:

( ( q + 1 ) × 40 ms ) + 20 ms + ( ( r + 1 ) × 60 ms )

 

But the real response time was:

( ( q + 1 ) × 40 ms ) + 20 ms + ( ( r + 1 ) × 50 ms )

 

An optimistic response routing scenario is represented by dotted green arrows (potential 40 ms timeslot) and a pessimistic scenario is shown by dotted red arrows (potential 60 ms timeslot).

 

The next Request 2 cannot be sent to the network immediately after the Response 1 is received. The RF collision would occur. Request 2 can be issued after the actual routing finishes (end of the dotted blue arrow) the soonest. Another approach is to send next request to the [C] after the pessimistic (using the longest 60 ms response timeslot) is finished. For many applications that do not have to be time optimized this is the reasonable and easy to compute way of timing.

image

 

Throughout the document in the following examples of the DPA communication, the DPA Confirmation is not usually stated as the emphasis is put on DPA request-response pair messages.

 2.6.4   DPA Notification

DPA notification notifies a connected master device at the node side that there was a DPA request without a read-only (can be configured by EnableIFacenotificationOnRead) side-effect processed by the node. It consists of the same foursome that was part of the original DPA request except for NADR that stores the address of the sender, not the addressee, and the HWPID that contains actual HW Profile ID of the device. DPA notification is therefore always 6 bytes long.

 

DPA notification is issued to the connected master interface when DPA request is sent from the coordinator or when the DPA request is part of the FRC acknowledged broadcast (see Acknowledged broadcast - bits and Acknowledged broadcast - bytes).

 

DPA notification is not issued in the case of DPA request invoked from a local interface, from DpaApiLocalRequest or from predefined FRCs Memory read and Memory read plus 1.

 2.6.5   DPA Response

DPA response is an actual answer to the DPA request. DPA response consists of the same foursome that was part of the original DPA request except the response message is flagged by the most significant bit of PCMD and HWPID contains actual HW profile ID of the addressed device. Then come 2 bytes containing the Response code and DPA Value. In the case of error (response code is NOT equal to STATUS_NO_ERROR), no additional data is present. In the case of a STATUS_NO_ERROR response code, the presence of the additional data depends on the DPA response type. If the response is asynchronous, i.e. it is not a response to the previously sent request, then the response code is marked by the highest bit set (STATUS_ASYNC_RESPONSE).

 

When composing DPA response in the Custom DPA Handler there is sometimes a need to signalize an error response with certain Response Code. The way how to return such response is described at chapter Handle Peripheral Request.

 2.6.6   Examples

Note: DPA Value, HWPID, and data read from the memory shown in the following examples may differ in the real scenario.

 

Example 1

 

Switching on a red LED at coordinator:

·         DPA request(master slave)

NADR=0x0000, PNUM=0x06, PCMD=0x01, HWPID=0xFFFF

 

·         DPA response(slave master)

NADR=0x0000, PNUM=0x06, PCMD=0x81, HWPID=0xABCD, PData={0x00}(No error), {0x07}(DPA Value)

 

Notes:

·         NADR        0x0000 Specifies coordinator address (0x00FC can be used too)

·         PNUM        0x06     Specifies red LED peripheral

·         PCMD        0x01     Set LED On command

·         DPA Value             Coordinator’s value

 

Example 2

 

Reading 2 bytes from RAM at address 1 of the local node:

·         DPA request (master slave)

NADR=0x00FC, PNUM=0x05, PCMD=0x00, HWPID=0xFFFF, PData={0x01}(Address), {0x02}(Length)

·         DPA response (slave master)

NADR=0x00FC, PNUM=0x05, PCMD=0x80, HWPID=0xABCD
PData={0x00}
(No error), {0x07}(DPA Value), {0xAB,0xCD}(Read data)

 

Notes:

·         NADR        0x00FC             Specifies local device address

·         PNUM        0x05                 Specifies RAM peripheral

·         PCMD        0x00                 Read command

·         DPA Value                         Local node’s value

 

Example 3

 

Switching on a green LED at remote IQMESH node with address 0x0A:

 

·         DPA request (master slave)

NADR=0x000A, PNUM=0x07, PCMD=0x01, HWPID=0xFFFF

·         DPA confirmation(slave master)

NADR=0x000A, PNUM=0x07, PCMD=0x01, HWPID=0xFFFF, PData={0xFF}(Confirmation), {0x07}(DPA Value), {0x06,0x04,0x06}(Hops, Timeslot length, Hops response)

·         DPA notification (slave master) at remote node side

NADR=0x0000, PNUM=0x07, PCMD=0x01, HWPID=0xABCD

·         DPA response (slave master)

NADR=0x000A, PNUM=0x07, PCMD=0x81, HWPID=0xABCD, PData={0x00}(No error), {0x06}(DPA Value)

 

Notes:

·         PNUM                0x07         Specifies green LED peripheral

·         NADR                0x0000      At DPA notification specifies that the Coordinator sent the original        request

·         DPA Value         DPA confirmation: Coordinator’s value

                               DPA response: remote node’s value

 2.7     Device exploration

Device exploration is used to obtain information about individual devices and their implemented peripherals.

 2.7.1   Peripheral enumeration

Request

 

NADR

PNUM

PCMD

HWPID

NADR

0xFF

0x3F

?

 

The HWPID value is ignored at this command.

 

Response

 

NADR

PNUM

PCMD

HWPID

ErrN

DpaValue

0…1

2

3…6

7…8

9…10

11

(12…23)

NADR

0xFF

0xBF

?

0

?

DpaVer

PerNr

EmbeddedPers

HWPID

HWPIDver

Flags

UserPer

 

DpaVer            DPA protocol version

·         1st byte: bits 0-6 = minor version, bit 7 = demo version

·         2nd byte: major version

                      BCD coding is used, e.g. version 12.34 is coded as 0x1234, i.e. 1st byte 0x34, 2nd byte 0x12

PerNr                Number of all non-embedded peripherals implemented by Custom DPA Handler. Implemented peripherals are flagged at the UserPer variable-size bitmap array.

EmbeddedPers Bits array (starting from LSb of the 1st byte) specifying which of 32 embedded peripherals are enabled in the HWP Configuration (it is a copy of first 4 bytes of the configuration area). If a peripheral is enabled in the configuration although it is not supported by the device, then calling Get peripheral information or Get information for more peripherals will return PERIPHERAL_TYPE_DUMMY peripheral type for this peripheral thus indicating that the peripheral is actually not available.

                        Bit values for Coordinator (bit 0) and Node (bit 1) peripherals are set according to the device support of these peripherals regardless of actual bit values stored at HWP Configuration. The bit value for OS is always set.

HWPID             Hardware profile ID, 0x0000 if default.

HWPIDver        Hardware profile version, 1st byte = minor version, 2nd byte = major version

Flags                Various flags:

·         bit 0           STD IQMESH RF Mode supported

·         bit 1           LP IQMESH RF Mode supported

·         bit 2-7        Reserved

UserPer            Bits array (starting from LSb of the 1st byte) specifying which of non-embedded peripherals are implemented. 1st bit corresponds to the peripheral 0x20 = PNUM_USER. The corresponding bits must be set at Enumerate Peripherals event. The length of this array can be from 0 to 12 bytes depending on the last implemented user peripheral number. A number of bits set in the bitmap must equal to the PerNr.

 

Example

 

·         Request

NADR=0x0000, PNUM=0xFF, PCMD=0x3F, HWPID=0xFFFF

·         Response

NADR=0x0000, PNUM=0xFF, PCMD=0xBF, HWPID=0xABCD, PData={0x00}(No error), {0x07}(DPA Value),{12,02}(DpaVer 2.12), {02}(PerNr), {E6,06,00,00}(StdPers), {CD,AB}(HWPID), {01,00}(HWPIDver), {41}(Flags), {02,01}(UserPer)

 

Coordinator (NADR=0x0000) having 2 user defined peripheral, Hardware profile ID of type 0xABCD (version 0x0001), DPA version 2.12 (not a demo version).

The following embedded peripherals are enabled:

·         0x01           NODE

·         0x02           OS

·         0x05           RAM

·         0x06           LEDR

·         0x07           LEDG

·         0x09           IO

·         0x0A          Thermometer
bit array (E6,06,00,00):
11100110.00000110.00000000.00000000

 

The following user peripherals are implemented:

·         0x21

·         0x28
bit array (02,01):
00000010.00000001

 2.7.1.1               Source code support

typedef struct

{

  uns16      DpaVersion;

  uns8        UserPerNr;

  uns8        EmbeddedPers[ PNUM_USER / 8 ];

  uns16      HWPID;

  uns16      HWPIDver;

  uns8        Flags;

  uns8       UserPer[ ( PNUM_MAX - PNUM_USER + 1 + 7 ) / 8 ];

} TEnumPeripheralsAnswer;

 

TEnumPeripheralsAnswer     _DpaMessage.EnumPeripheralsAnswer;

 

 2.7.2   Get peripheral information

Returns detailed information about the peripheral.

 

Request

 

NADR

PNUM

PCMD

HWPID

NADR

PNUM

0x3F

?

 

The HWPID value is ignored at this command.

 

Response

 

NADR

PNUM

PCMD

HWPID

ErrN

DpaValue

0

1

2

3

NADR

PNUM

0xBF

?

0

?

PerTE

PerT

Par1

Par2

 

PerTE               Extended peripheral characteristic. See Extended Peripheral Characteristicconstants.

PerT                 Peripheral type. If the peripheral is not supported or enabled,

                        then PerTx = PERIPHERAL_TYPE_DUMMY. See Peripheral Types constants.

Par1                 Optional peripheral specific information.

Par2                 Optional peripheral specific information.

 2.7.2.1               Source code support

typedef struct

{

  uns8 PerTE;

  uns8 PerT;

  uns8 Par1;

  uns8 Par2;

} TPeripheralInfoAnswer;

 

TPeripheralInfoAnswer      _DpaMessage.TPeripheralInfoAnswer;

 2.7.3   Get information for more peripherals

Returns the same information as Get peripheral information but for up to 14 peripherals of consecutive indexes starting with the specified PCMD.

 

Request

 

NADR

PNUM

PCMD

HWPID

NADR

0xFF

Per

?

 

Per                   Number of the first peripheral from the list to get the information about. The parameter value cannot be 0x3F because it would collide with Peripheral enumeration command.

 

The HWPID value is ignored at this command.

 

Response

 

NADR

PNUM

PCMD

HWPID

ErrN

DpaValue

0

1

2

3

4×(n-1)

4×(n-1)+1

4×(n-1)+2

4×(n-1)+3

NADR

0xFF

RPer

?

0

?

PerTE1

PerT1

Par11

Par21

PerTEn

PerTn

Par1n

Par2n

 

RPer                Same as Per at request but with most significant bit set to indicate response message

n                      Number of peripherals the information was returned about.

 

If the peripheral at index x is not supported or enabled, then PerTx = PERIPHERAL_TYPE_DUMMY. The response data is always right-trimmed to the last supported or enabled peripheral that can fit in the data array i.e. the data never ends with one or more peripheral information with PerTx = PERIPHERAL_TYPE_DUMMY.

 2.7.3.1               Source code support

TPeripheralInfoAnswer _DpaMessage.PeripheralInfoAnswers[MAX_PERIPHERALS_PER_BLOCK_INFO];

 3         Peripherals

This (the longest) chapter documents all available embedded peripherals and their commands. Nested chapters named Source code support show prepared C code types and variables to access the peripheral command from the code. This is done typically at Custom DPA Handler code.

 3.1     Standard operations in general

Commands marked [sync] are executed after IQMESH routing is finished thus this event is synchronized among all devices that handled the original DPA request. This applies to the DPA request being sent using the broadcast address.

 

Commands marked [comdown] wait for maximum 100 ms to flush output buffers of SPI/UART Peripheral/Interface and then shuts it down. This is to prevent raising HW interrupts or to release OS bufferCOM variable that has to be used internally. After the command is finished the object is restarted.

 

DPA requests may return the following error codes:

 

ERROR_PCMD      The PNUM does not support the specified PCMD.

ERROR_PNUM      The specified PNUM is not supported or the PNUM does not support the specified PCMD.

 

ERROR_DATA_LEN A number of bytes at PData message parameter is not appropriate for the specified PNUM/PCMD pair.

 

ERROR_HWPID     The specified HWPID does not correspond to an HWPID of the device.

ERROR_NADR      The NADR specifies the non-bonded device or its value is above the address limit in case of the DPA demo version.

 3.1.1   Writing to peripheral

Request

 

NADR

PNUM

PCMD

HWPID

0

n - 1

NADR

PNUM

PCMD

?

PData0

PDatan-1

 

n                      Data length

 

Response

 

NADR

PNUM

PCMD

HWPID

ErrN

DpaValue

NADR

PNUM

PCMD

?

0

?

 

PCMD              Same as PCMD at request but with most significant bit set to indicate response message.

 3.1.1.1               Source code support

uns8   _DpaMessage.Request.PData[DPA_MAX_DATA_LENGTH];

 3.1.2   Reading from peripheral

Request

 

NADR

PNUM

PCMD

HWPID

NADR

PNUM

PCMD

?

 

Response

 

NADR

PNUM

PCMD

HWPID

ErrN

DpaValue

0

n - 1

NADR

PNUM

PCMD

?

0

?

PData0

PDatan-1

 

PCMD              Same as PCMD at request but with most significant bit set to indicate response message.

n                      Data length

 3.1.2.1               Source code support

uns8   _DpaMessage.Response.PData[DPA_MAX_DATA_LENGTH];

 3.2     Coordinator

PNUM = 0x00

 

This peripheral is implemented at [C] and [CN] devices and it is always enabled there regardless of the configuration settings.

 

General note: bond state of the node is not synchronized between the node and coordinator. There are separate requests concerning the bonding for node and coordinator.

 3.2.1   Peripheral information

PerT                 PERIPHERAL_TYPE_IQMESH_COORDINATOR

PerTE               PERIPHERAL_TYPE_EXTENDED_READ_WRITE

Par1                 Maximum number of data (PData) bytes that can be sent in the DPA messages

Par2                 Undocumented

 3.2.2   Get addressing information

Returns basic network information.

 

Request

 

NADR

PNUM

PCMD

HWPID

NADR

0x00

0x00

?

 

Response

 

NADR

PNUM

PCMD

HWPID

ErrN

DpaValue

0

1

NADR

0x00

0x80

?

0

?

DevNr

DID

 

DevNr               Number of bonded network nodes

DID                  Discovery ID of the network

 3.2.2.1               Source code support

typedef struct

{

  uns8 DevNr;

  uns8 DID;

} TPerCoordinatorAddrInfo_Response;

 

TPerCoordinatorAddrInfo_Response _DpaMessage.PerCoordinatorAddrInfo_Response;

 3.2.3   Get discovered nodes

Returns a bit map of discovered nodes.

 

Same as Get bonded nodes but PCMD = 0x01.

 3.2.4   Get bonded nodes

Returns a bitmap of bonded nodes.

 

Request

 

NADR

PNUM

PCMD

HWPID

NADR

0x00

0x02

?

 

Response

 

NADR

PNUM

PCMD

HWPID

ErrN

DpaValue

0

31

NADR

0x00

0x82

?

0

?

PData0

PData31

 

PData0-31           Bit array indicating bonded nodes (addresses). Address 0 at bit0 of PData0, Address 1 at bit1 of PData0 etc.

 3.2.4.1               Source code support

uns8   _DpaMessage.Response.PData[DPA_MAX_DATA_LENGTH];

 3.2.5   Clear all bonds

The command removes all nodes from the list of bonded nodes at coordinator memory. It actually destroys the network from the coordinator point of view.

 

Request

 

NADR

PNUM

PCMD

HWPID

NADR

0x00

0x03

?

 

Response: General response to writing request with STATUS_NO_ERRORError code

 3.2.6   Bond node

This command bonds a new node by the coordinator. There is a maximum approx. 10 s blocking delay when this function is called.

 

Request

 

NADR

PNUM

PCMD

HWPID

0

1

NADR

0x00

0x04

?

ReqAddr

Bonding mask

 

ReqAddr           A requested address for the bonded node. The address must not be used (bonded) yet. If this parameter equals to 0, then the 1st free address is assigned to the node.

Bonding mask  See IQRF OS User's and Reference guides (remote bonding, function bondNewNode).

 

Response

NADR

PNUM

PCMD

HWPID

ErrN

DpaValue

0

1

NADR

0x00

0x84

?

0

?

BondAddr

DevNr

 

 

 

 

 

BondAddr        Address of the node newly bonded to the network

DevNr               Number of bonded network nodes

 

Error codes

ERROR_FAIL      a. Nonzero ReqAddr is already used.
b. No free address is available when ReqAddr equals to 0.
c. ReqAddr or assigned free address is above the address limit in case of the DPA demo version.
d. Internal call to bondNewNode failed.

 3.2.6.1               Source code support

typedef struct

{

  uns8 ReqAddr;

  uns8 BondingMask;

} TPerCoordinatorBondNode_Request;

 

TPerCoordinatorBondNode_Request _DpaMessage.PerCoordinatorBondNode_Request;

 

typedef struct

{

  uns8 BondAddr;

  uns8 DevNr;

} TPerCoordinatorBondNode_Response;

 

TPerCoordinatorBondNode_Response _DpaMessage.PerCoordinatorBondNode_Response;

 3.2.7   Remove bonded node

Removes already bonded node from the list of bonded nodes at coordinator memory.

Request

NADR

PNUM

PCMD

HWPID

0

NADR

0x00

0x05

?

BondAddr

 

 

 

 

 

BondAddr        Address of the node to remove the bond to

 

Response

 

NADR

PNUM

PCMD

HWPID

ErrN

DpaValue

0

NADR

0x00

0x85

?

0

?

DevNr

 

DevNr               Number of bonded network nodes

 

Error codes

ERROR_FAIL      BondAddr does not specify a bonded node.

 3.2.7.1               Source code support

typedef struct

{

  uns8 BondAddr;

} TPerCoordinatorRemoveRebondBond_Request;

 

TPerCoordinatorRemoveRebondBond_Request

_DpaMessage.PerCoordinatorRemoveRebondBond_Request;

 

typedef struct

{

  uns8 DevNr;

} TPerCoordinatorRemoveRebondBond_Response;

 

TPerCoordinatorRemoveRebondBond_Response

       _DpaMessage.PerCoordinatorRemoveRebondBond_Response;

 3.2.8   Re-bond node

Puts specified node back to the list of bonded nodes in the coordinator memory.

 

Request

 

NADR

PNUM

PCMD

HWPID

0

NADR

0x00

0x06

?

BondAddr

 

BondAddr        Address of the node to be re-bonded

 

Response

 

NADR

PNUM

PCMD

HWPID

ErrN

DpaValue

0

NADR

0x00

0x86

?

0

?

DevNr

 

DevNr               Number of bonded network nodes

 

Error codes

ERROR_FAIL      a. BondAddr is already bonded.
b. BondAddr is above the address limit in case of the DPA demo version.

 3.2.8.1               Source code support

typedef struct

{

  uns8 BondAddr;

} TPerCoordinatorRemoveRebondBond_Request;

 

TPerCoordinatorRemoveRebondBond_Request

_DpaMessage.PerCoordinatorRemoveRebondBond_Request;

 

typedef struct

{

  uns8 DevNr;

} TPerCoordinatorRemoveRebondBond_Response;

 

TPerCoordinatorRemoveRebondBond_Response

_DpaMessage.PerCoordinatorRemoveRebondBond_Response;

 3.2.9   Discovery

[comdown] Runs IQMESH discovery process. The time when the response is delivered depends highly on the number of network devices, the network topology, and RF mode, thus, it is not predictable. It can take from a few seconds to many minutes.

 

Request

 

NADR

PNUM

PCMD

HWPID

0

1

NADR

0x00

0x07

?

TxPower

MaxAddr

 

TxPower           TX Power used for discovery.

MaxAddr          Nonzero value specifies maximum node address to be part of the discovery process. This feature allows splitting all node devices into two parts: [1] devices having an address from 1 to MaxAddr will be part of the discovery process thus they become routers, [2] devices having an address from MaxAddr+1 to 239 will not be routers. See IQRF OS documentation for more information.

                        The value of this parameter is ignored at demo version. A value 5 is always used instead.

 

Response

 

NADR

PNUM

PCMD

HWPID

ErrN

DpaValue

0

NADR

0x00

0x87

?

0

?

DiscNr

 

DiscNr              Number of discovered network nodes

 

Error codes

ERROR_FAIL      When the internal call of discovery fails.

 3.2.9.1               Source code support

typedef struct

{

  uns8 TxPower;

  uns8 MaxAddr;

} TPerCoordinatorDiscovery_Request;

 

TPerCoordinatorDiscovery_Request _DpaMessage.PerCoordinatorDiscovery_Request;

 

typedef struct

{

  uns8 DiscNr;

} TPerCoordinatorDiscovery_Response;

 

TPerCoordinatorDiscovery_Response _DpaMessage.PerCoordinatorDiscovery_Response;

 3.2.10                Set DPA Param

Sets DPA Param. DPA Param (DPA Parameter) is a one-byte parameter stored at the coordinator RAM that configures network behavior. Default value 0x00 is set upon coordinator reset. The default value can be changed using Autoexec feature.

 

Bit

Description

0-1

Specifies which type of DPA Value is returned in every DPA response or DPA confirmation messages:

 00

lastRSSI: IQRF OS variable (*). In the case of the [C] device, the value is 0 until some RF packet is received.

 01

voltage: Value returned by getSupplyVoltage IQRF OS call (*)

 10

system:

  bit 0:              Equals to bit DSMactivated.

  bits 1-6:          Reserved

  bit 7:              (*)

 11

user specified DPA Value. See UserDpaValue.

2

If 1, it allows easily diagnosing the network behavior based on following LED activities. Please note that this feature might collide with LED peripheral when used simultaneously giving undesirable effects.

 Red LED flashes

When Node or Coordinator receives network message.

 Green LED flashes

When Coordinator sends network message or when Node routes network message.

3

If 1, then instead of using ideal timeslot length, a long fixed 200 ms timeslot is used. It allows easier tracking of network behavior.

4-7

Reserved

 

(*) The highest 7th bit indicates, that the node, that returned the DPA response, provided a remote pre-bonding to another node. Then Node peripheral commands can be used to find out its module ID and proceed with node authorization using Coordinator peripheral.

 

DPA Param is transparently sent with every DPA message from the coordinator and thus, it controls the network behavior “on the fly”. It is not permanently stored at nodes.

 

Request

 

NADR

PNUM

PCMD

HWPID

0

NADR

0x00

0x08

?

DPA Param

 

DPA Param      DPA Param to set.

 

Response

 

NADR

PNUM

PCMD

HWPID

ErrN

DpaValue

0

NADR

0x00

0x88

?

0

?

DPA Param

 

DPA Param      Previous value

 3.2.10.1             Source code support

typedef struct

{

  uns8 DpaParam;

} TPerCoordinatorSetDpaParams_Request_Response;

 

TPerCoordinatorSetDpaParams_Request_Response

_DpaMessage.PerCoordinatorSetDpaParams_Request_Response;

 3.2.11                Set Hops

Allows the specifying fixed number of hops used to send the DPA request/response or to specify an optimization algorithm to compute a number of hops. The default value 0xFF is set upon device reset.

 

Request

 

NADR

PNUM

PCMD

HWPID

0

1

NADR

0x00

0x09

?

Request Hops

Response Hops

 

Hops values:

0x00, 0xFF:      See a description of the parameter of function optimizeHops in the IQRF OS documentation. 0x00 does not make sense for Response Hops parameter.

0x01 – 0xEF:    Sets number of hops to the value Request/ResponseHops - 1.
The result of
Discovery data command can be used to find out an optimal number of hops based on destination node logical address or virtual routing number respectively.

 

Response

 

NADR

PNUM

PCMD

HWPID

ErrN

DpaValue

0

1

NADR

0x00

0x89

?

0

?

Request Hops

Response Hops

 

Request/Response Hops                      Previous values

 3.2.11.1             Source code support

typedef struct

{

  uns8 RequestHops;

  uns8 ResponseHops;

} TPerCoordinatorSetHops_Request_Response;

 

TPerCoordinatorSetHops_Request_Response

_DpaMessage.PerCoordinatorSetHops_Request_Response;

 3.2.12                Discovery data

Allows reading of coordinator internal discovery data. Discovery data can be used for instance for IQMESH network visualization and traffic optimization. Discovery data structure is documented at IQRF OS Operating System User's Guide, Appendix “Coordinator Bonding and Discovery Data”.

 

Request

 

NADR

PNUM

PCMD

HWPID

0 … 1

NADR

0x00

0x0A

?

Address

 

Address           Address of the discovery data to read. See IQRF OS documentation for details.

 

Response

 

NADR

PNUM

PCMD

HWPID

ErrN

DpaValue

0 47

NADR

0x00

0x8A

?

0

?

Discovery data

 

DiscoveryData  Discovery data read from the coordinator private external EEPROM storage

 

Error codes

ERROR_FAIL      Error accessing serial EEPROM chip.

 3.2.12.1             Source code support

typedef struct

{

  uns16      Addr;

} TPerCoordinatorDiscoveryData_Request;

 

TPerCoordinatorDiscoveryData_Request _DpaMessage.PerCoordinatorDiscoveryData_Request;

 

typedef struct

{

  uns8 DiscoveryData[48];

} TPerCoordinatorDiscoveryData_Response;

 

TPerCoordinatorDiscoveryData_Response

_DpaMessage.PerCoordinatorDiscoveryData_Response;

 3.2.13                Backup

This command reads coordinator network information data that can be then restored to another coordinator in order to make a clone of the original coordinator. The backup data structure is not public and it is encrypted (except the very last byte) by an AES-128 algorithm using access password as a key. The command is not implemented at [CN] device.

 

Request

 

NADR

PNUM

PCMD

HWPID

0

NADR

0x00

0x0B

?

Index

 

Index                Index of the block of data

 

Response

 

NADR

PNUM

PCMD

HWPID

ErrN

DpaValue

0 … 48

NADR

0x00

0x8B

?

0

?

Network data

 

Network data    One block of the coordinator network info data

 

To read all data blocks just start with Index = 0 and execute the Backup request. Then store received data block from the response. The last of the read data specifies how many data blocks remains to be read. So, if this byte is not 0 just increment Index (0, 1, …) and execute another Backup request.

 

Error codes

ERROR_DATA      Index is out of range.

ERROR_FAIL      Error accessing serial EEPROM chip.

 3.2.13.1             Source code support

typedef struct

{

  uns8 Index;

} TPerCoordinatorNodeBackup_Request;

 

TPerCoordinatorNodeBackup_Request _DpaMessage.PerCoordinatorNodeBackup_Request;

 

typedef struct

{

  uns8 NetworkData[49];

} TPerCoordinatorNodeBackup_Response;

 

TPerCoordinatorNodeBackup_Response _DpaMessage.PerCoordinatorNodeBackup_Response;

 3.2.14                Restore

The command allows writing previously backed up coordinator network data to the same or another coordinator device. To execute the full restore all data blocks (in any order) obtained by Backup commands must be written to the device. Because the data to restore is encrypted by an AES-128 algorithm using access password as a key, the access password at the device must be same as the access password at the device that was originally backed up. The command is not implemented at [CN] device.

 

The following conditions must be met to make the coordinator backup fully functional:

·           Backed up and restored devices have the same access password.

·           No network traffic comes from/to restored coordinator during the restore process.

·           Coordinator device is reset or restarted after the whole restore is finished.

·           It is recommended to run Discovery command before the network is used after restore because of possible RF differences between new and previous coordinator device HW.

 

Request

NADR

PNUM

PCMD

HWPID

0 … 48

NADR

0x00

0x0C

?

NetworkData

 

 

 

 

NetworkData     One block of the coordinator network info data previously obtained by Backup command.

 

Response: General response to writing request with STATUS_NO_ERROR Error code

 

Error codes

ERROR_DATA      Invalid (access password does not match) or inappropriate (e.g. coordinator data used to restore node or vice versa) NetworkData content.

ERROR_FAIL      Error accessing serial EEPROM chip.

 3.2.14.1             Source code support

typedef struct

{

  uns8 NetworkData[49];

} TPerCoordinatorNodeRestore_Request;

 

TPerCoordinatorNodeRestore_Request _DpaMessage.PerCoordinatorNodeRestore_Request;

 3.2.15                Authorize bond

Authorizes previously remotely pre-bonded node. This assigns the node the final network address. See IQRF OS documentation for more information about remote bonding concept.

 

Request

 

NADR

PNUM

PCMD

HWPID

0

1 4

NADR

0x00

0x0D

?

ReqAddr

MID

 

ReqAddr           See Bond noderequest. If 0xFF is specified then the pre-bonded node is unbonded and then reset.

MID                  Module ID of the node to be authorized. Module ID is obtained by calling Read remotely bonded module ID.

 

Response: see response of Bond node command (except PCMD is 0x8D).

 

Error codes

ERROR_FAIL      a. Nonzero ReqAddr is already used.
b. No free address is available when ReqAddr equals to 0.
c. ReqAddr or assigned free address is above the address limit in case of the DPA demo version.
d. Internal call to nodeAuthorization failed.

 3.2.15.1             Source code support

typedef struct

{

  uns8        ReqAddr;

  uns8        MID[4];

} TPerCoordinatorAuthorizeBond_Request;

 

TPerCoordinatorAuthorizeBond_Request _DpaMessage.PerCoordinatorAuthorizeBond_Request;

 

typedef struct

{

  uns8 BondAddr;

  uns8 DevNr;

} TPerCoordinatorAuthorizeBond_Response;

 

TPerCoordinatorAuthorizeBond_Response

_DpaMessage.PerCoordinatorAuthorizeBond_Response;

 3.2.16                Enable remote bonding

Implemented at [C] devices. Has the same behavior as Enable remote bonding except PNUM = 0x00 and PCMD = 0x11.

 3.2.17                Read remotely bonded module ID

Implemented at [C] devices. Has the same behavior as Read remotely bonded module ID except PNUM = 0x00 and PCMD = 0x0F.

 3.2.18                Clear remotely bonded module ID

Implemented at [C] devices. Has the same behavior as Clear remotely bonded module ID except PNUM = 0x00 and PCMD = 0x10.

 3.3     Node

PNUM = 0x01

 

This peripheral is implemented at [N] and [CN] devices and it is always enabled there regardless of the configuration settings.

 

General note: Bond state of the node is not synchronized between the node and coordinator. There are separated requests for node and coordinator concerning the bonding.

 3.3.1   Peripheral information

PerT                 PERIPHERAL_TYPE_IQMESH_NODE

PerTE               PERIPHERAL_TYPE_EXTENDED_READ_WRITE

Par1                 Maximum number of data (PData) bytes that can be sent in the DPA messages

Par2                 Undocumented

 3.3.2   Read

Returns IQMESH specific node information.

 

Request

 

NADR

PNUM

PCMD

HWPID

NADR

0x01

0x00

?

 

Response

 

NADR

PNUM

PCMD

HWPID

ErrN

DpaValue

0 10

11

NADR

0x01

0x80

?

0

?

ntwADDR … ntwCFG

Flags

 

ntwADDR … ntwCFG    Block of all ntw* IQRF OS variables (ntwADDR, ntwVRN, ntwZIN, ntwDID, ntwPVRN, ntwUSERADDRESS, ntwID, ntwVRNFNZ, ntwCFG) in the same order and size as located in the IQRF OS memory. See IQRF OS documentation for more information.

Flags                           bit 0     Indicates whether the Node device is bonded.

                                   bit 1-7   Reserved

 3.3.2.1               Source code support

typedef struct

{

  uns8  ntwADDR;

  uns8  ntwVRN;

  uns8  ntwZIN;

  uns8  ntwDID;

  uns8  ntwPVRN;

  uns16 ntwUSERADDRESS;

  uns16 ntwID;

  uns8  ntwVRNFNZ;

  uns8  ntwCFG;

  uns8  Flags;

} TPerNodeRead_Response;

 

TPerNodeRead_Response _DpaMessage.PerNodeRead_Response;

 3.3.3   Remove bond

[sync]   The node is marked as unbonded (removed from network) using removeBond() IQRF OS function. Bonding state of the node on the coordinator side is not affected at all. Please note, that the node will not receive messages anymore from the network after this command. Therefore this command is often combined with a subsequent Restart command inside one Batch command.

 

Request

 

NADR

PNUM

PCMD

HWPID

NADR

0x01

0x01

?

 

Response

 

The general response to writing request with STATUS_NO_ERROR Error code.

 3.3.4   Enable remote bonding

Puts node into a mode that provides a remote bonding of up to 7 new nodes. Remote bonding gives the new node temporary network address (0xFE). This process is called pre-bonding. A final logical network address is provided to the node using Authorize bond command. Then the node can be discovered and its virtual routing number is assigned. See IQRF OS documentation for more information about remote bonding concept.

 

Node stays in the remote bonding mode even if all 7 nodes were pre-bonded. It allows to the already pre-bonded node to be pre-bonded again, pre-bonding of another node is rejected. This gives possibility the new node to try pre-bonding again in the case when it did not receive pre-bonding confirmation after the previous bonding requests. Also, see bit ProvidesRemoteBonding.

 

Request

 

NADR

PNUM

PCMD

HWPID

0

1

2 5

NADR

0x01

0x04

?

BondingMask

Control

UserData

 

BondingMask   See IQRF OS User's and Reference guides (remote bonding, function bondNewNode).

Control             bit 0     Enables remote bonding mode. If enabled then previously bonded nodes         are forgotten.

                        bit 1-7  Reserved

UserData          Optional data that can be used at Reset Custom DPA Handler event.

 

Response

 

The general response to writing request with STATUS_NO_ERROR Error code.

 3.3.4.1               Source code support

typedef struct

{

  uns8        BondingMask;

  uns8        Control;

  uns8        UserData[4];

} TPerCoordinatorNodeEnableRemoteBonding_Request;

 

TPerCoordinatorNodeEnableRemoteBonding_Request

_DpaMessage.PerCoordinatorNodeEnableRemoteBonding_Request;

 3.3.5   Read remotely bonded module ID

This command returns module IDs and user data of the remotely pre-bonded nodes. Non-user DPA Values also indicate if anynode was pre-bonded. See Set DPA Param and RemoteBondingCount.

 

Request

 

NADR

PNUM

PCMD

HWPID

NADR

0x01

0x02

?

 

Response

 

NADR

PNUM

PCMD

HWPID

ErrN

DpaValue

0 3

4 7

8×(n-1)

8×n-1

NADR

0x01

0x82

?

0

?

MID

UserData

 

MID

UserData

 

The responsecontains a list of MID/UserData pairs of pre-bonded nodes. If no node was pre-bonded no data is returned.

 

MID                  Module ID of the remotely pre-bonded node. It can be used later for bonding authorization later. See Authorize bond.

UserData          Optional bonding user data specified at Reset Custom DPA Handler event.

 3.3.5.1               Source code support

typedef struct

{

  uns8 MID[4];

  uns8 UserData[4];

} TPrebondedNode;

 

typedef struct

{

  TPrebondedNode  PrebondedNodes[ DPA_MAX_DATA_LENGTH / sizeof(TPrebondedNode) ];

} TPerCoordinatorNodeReadRemotelyBondedMID_Response;

 

TPerCoordinatorNodeReadRemotelyBondedMID_Response

_DpaMessage.PerCoordinatorNodeReadRemotelyBondedMID_Response;

 3.3.6   Clear remotely bonded module ID

This call makes a node forget of the nodes that were previously remotely pre-bonded. After calling this command calling of Read remotely bonded module ID returns no data. This command does not affect remote bonding mode enable/disable state.

 

Request

 

NADR

PNUM

PCMD

HWPID

NADR

0x01

0x03

?

 

Response

 

The general response to writing request with STATUS_NO_ERROR Error code.

 3.3.7   Remove bond address

[sync]   The node stays in the IQMESH network (it is not unbonded) but a temporary address 0xFE is assigned to it. This allows to address it (them) or to authorize it later by AuthorizeBond. It is highly recommended to read the device's Module ID before removing bond address to be able to authorize it later.

 

Request

NADR

PNUM

PCMD

HWPID

NADR

0x01

0x05

?

 

 

 

 

Response

 

The general response to writing request with STATUS_NO_ERROR Error code.

 3.3.8   Backup

Same as coordinator Backup except PNUM = 0x01 and PCMD = 0x06.

 3.3.9   Restore

Same as coordinator Restore except PNUM = 0x01 and PCMD = 0x07.

 3.4     OS

PNUM = 0x02

 

This peripheral is always enabled regardless of the configuration settings.

 3.4.1   Peripheral information

PerT                 PERIPHERAL_TYPE_OS

PerTE               PERIPHERAL_TYPE_EXTENDED_READ_WRITE

Par1                 Date of the DPA build coded using BCD.

Par2                 Lower nibble contains month of the date of the DPA build, higher nibble contains year above 2010.

 

Example: Par1=0x31, Par2=4A => build date is 31.10.2014.

 3.4.2   Read

Returns some useful system information about the device.

 

Request

 

NADR

PNUM

PCMD

HWPID

NADR

0x02

0x00

?

 

Response

 

NADR

PNUM

PCMD

HWPID

ErrN

DpaValue

0 … 3

4

5

6 … 7

8

9

10

11

NADR

0x02

0x80

?

0

?

ModuleID

OSVersion

TR&McuType

OsBuild

Rssi

SupplyVoltage

Flags

SlotLimits

 

ModuleID,
OSVersion,
TR&McuType,
OsBuild                          See moduleInfo at IQRF OS Reference Guide.

Rssi                               See lastRSSI at IQRF OS Reference Guide. In the case of the [C] device, the value is 0 until some RF packet is received.

SupplyVoltage                See getSupplyVoltage at IQRF OS Reference Guide.

Flags                              bit.0 is 1 if there is an insufficient OsBuild for the used DPA version.

                                      bit.1 is 0 if SPI interface is supported; 1 if UART interface is supported. This bit is valid only if bit.4 is 0.

                                      bit.2 is 1 if Custom DPA Handler was detected.

                                      bit.3 is 1 if Custom DPA Handler is not detected but enabled at HWP Configuration. See details of the handling of this erroneous state.

                                      bit.4 is 1 if no interface is supported.

                                      bit.5-7 are reserved.

SlotLimits                       Lower nibble stores shortest timeslot length in 10 ms units, upper nibble stores the longest timeslot respectively. The stored length value is lowered by 3. So a value 0x31 specifies the shortest timeslot of 40 ms and the longest of 60 ms.

 3.4.2.1               Source code support

typedef struct

{

  uns8        ModuleId[4];

  uns8        OsVersion;

  uns8        McuType;

  uns16      OsBuild;

  uns8        Rssi;

  uns8        SupplyVoltage;

  uns8        Flags;

  uns8       SlotLimits;

} TPerOSRead_Response;

 

TPerOSRead_Response _DpaMessage.PerOSRead_Response;

 3.4.3   Reset

[sync] [comdown]          Forces (DC)TR transceiver module to carry out reset.

 

Request

NADR

PNUM

PCMD

HWPID

NADR

0x02

0x01

?

 

 

 

 

Response

 

The general response to writing request with STATUS_NO_ERROR Error code.

 3.4.4   Restart

[sync] [comdown]          Forces (DC)TR transceiver module to restart. It is similar to reset (the device starts, RAM, and global variables are cleared) except MCU is not reset from the HW point of view (MCU peripherals are not initialized) and RFPGM on reset (when it is enabled) is always skipped.

 

Request

NADR

PNUM

PCMD

HWPID

NADR

0x02

0x08

?

 

 

 

 

Response

 

The general response to writing request with STATUS_NO_ERROR Error code.

 3.4.5   Read HWP configuration

Reads a raw HWP configuration memory. Bit values for Coordinator (bit 0) and Node (bit 1) peripheral stored at HWP configuration are set the same way as at Peripheral enumeration.

 

Request

 

NADR

PNUM

PCMD

HWPID

NADR

0x02

0x02

?

Response

 

NADR

PNUM

PCMD

HWPID

ErrN

DpaValue

0

1 … 31

32

33 … n

NADR

0x02

0x82

?

0

?

Checksum

Configuration

RFPGM

Undocumented

 

Checksum                      Checksum of the Configuration part.

Configuration                  Content the configuration memory block from address 0x01 to 0x1F.

RFPGM                          See parameter of setupRFPGM IQRF OS function.

 

This command returns all bytes both from Checksum and Configuration sections being XORed by byte value 0x34 (other bytes are not XORed). The Checksum byte XORed with all Configuration bytes gives 0x5F.

 3.4.5.1               Source code support

typedef struct

{

  uns8 Checksum;

  uns8 Configuration[31];

  uns8 RFPGM;

  uns8 Undocumented[1];

} TPerOSReadCfg_Response;

 

TPerOSReadCfg_Response _DpaMessage.PerOSReadCfg_Response;

 3.4.6   Write HWP configuration

Writes HWP configuration memory. It is a programmer's responsibility to prepare correct configuration block including checksum byte. This command is for advanced users only. Please note that the device should be restarted for all configuration changes to take effect. See HWP configuration for details.

 

Request

 

NADR

PNUM

PCMD

HWPID

0

1 31

32

NADR

0x02

0x0F

?

Checksum

Configuration

RFPGM

 

Checksum                      Checksum of the Configuration part. The Checksum byte XORed with all Configuration bytes gives 0x5F.

Configuration                  Content the configuration memory block from address 0x01 to 0x1F.

RFPGM                          See parameter of setupRFPGM IQRF OS function.

 

Response

 

The general response to writing request with STATUS_NO_ERROR Error code.

 

Example

 

Following example shows writing RF output power value to the configuration in the Custom DPA Handler code.

 

// Read configuration

_PNUM = PNUM_OS;

_PCMD = CMD_OS_READ_CFG;

_DpaDataLength = 0;

DpaApiLocalRequest();

 

// Decode configuration

FSR0 = _DpaMessage.Response.PData + sizeof( _DpaMessage.PerOSWriteCfg_Request.Checksum ) + sizeof( _DpaMessage.PerOSWriteCfg_Request.Configuration );

do

{

  setINDF0( *--FSR0 ^ 0x34 );

} while ( FSR0.low8 != ( _DpaMessage.Response.PData & 0xff ) );

 

// Update checksum

_DpaMessage.PerOSWriteCfg_Request.Checksum ^= _DpaMessage.PerOSWriteCfg_Request.Configuration[CFGIND_TXPOWER - sizeof(_DpaMessage.PerOSWriteCfg_Request.Checksum)] ^ txPowerToSet;

// Update TX power

_DpaMessage.PerOSWriteCfg_Request.Configuration[CFGIND_TXPOWER - sizeof(_DpaMessage.PerOSWriteCfg_Request.Checksum)] = txPowerToSet;

 

// Write configuration

_PCMD = CMD_OS_WRITE_CFG;

_DpaDataLength = sizeof( TPerOSWriteCfg_Request );

DpaApiLocalRequest();

 3.4.6.1               Source code support

typedef struct

{

  uns8 Checksum;

  uns8 Configuration[31];

  uns8 RFPGM;

} TPerOSWriteCfg_Request;

 

TPerOSWriteCfg_Request _DpaMessage.PerOSWriteCfg_Request;

 3.4.7   Write HWP configuration byte

Writes multiple bytes to the HWP configuration memory. This command is for advanced users only. The Acknowledged broadcast is recommended for writing configuration values to all or selected nodes as it also confirms which nodes actually performed the configuration write. The command is not implemented at [CN] devices.Please note that the device should be restarted for some configuration changes to take effect. See HWP configuration for details.

 

Request

 

NADR

PNUM

PCMD

HWPID

0

1

2

n × 3

n × 3 + 1

n × 3 + 2

NADR

0x02

0x09

?

Address0

Value0

Mask0

Addressn

Valuen

Maskn

 

Address           Address of the item at configuration memory block. The valid address range is 0x01-0x1F for configuration values. Also, address 0x20 is a valid value for RFPGM settings. See parameter of setupRFPGM IQRF OS function.

Value                Value of the configuration item to write.

Mask                Specifies bits of the configuration byte to be modified by the corresponding bits of the Value parameter. Only bits that are set at the Mask will be written to the configuration byte i.e. when Mask equals to 0xFF then the whole Value will be written to the configuration byte. For example, when Mask equals to 0x12 then only bit.1 and bit.4 from Value will be written to the configuration byte.

 

Response

 

The general response to writing request with STATUS_NO_ERROR Error code.

 

Error codes

ERROR_DATA      Address is out of range.

 3.4.7.1               Source code support

typedef struct

{

  uns8 Address;

  uns8 Value;

  uns8 Mask;

} TPerOSWriteCfgByteTriplet;

 

typedef struct

{

  TPerOSWriteCfgByteTriplet

Triplets[DPA_MAX_DATA_LENGTH / sizeof( TPerOSWriteCfgByteTriplet )];

} TPerOSWriteCfgByte_Request;

      

TPerOSWriteCfgByte_Request _DpaMessage.PerOSWriteCfgByte_Request;

 3.4.8   Run RFPGM

[sync] [comdown]          Puts device into RFPGM mode configured at HWP Configuration. The device is reset when RFPGM process is finished. RFPGM runs at same channels (configured at HWP configuration) the network is using.

 

Request

 

NADR

PNUM

PCMD

HWPID

NADR

0x02

0x03

?

 

Response

 

The general response to writing request with STATUS_NO_ERROR Error code.

 3.4.9   Sleep

Puts the device into sleep (power saving) mode.

 

[sync] [comdown]          This command is implemented at the [N] device only.

 

The (in)accuracy of the real sleep time depends on the PIC LFINTOSC oscillator that runs watchdog timer. The oscillator frequency is mainly influenced by the device supply voltage and temperature volatility. See PIC MCU datasheet for more details.

 

If the interface is used then it is disabled before going to sleep and enabled after device wakes up.

 

Before going to sleep both SPI and UART DPA peripherals or DPA interfaces are automatically shut down and later restarted when device wakes up. Please consider implementing BeforeSleep and AfterSleepevents to handle MCU peripherals and pins to obtain the lowest possible device consumption.

 

Request

 

NADR

PNUM

PCMD

HWPID

0

1

2

NADR

0x02

0x04

?

Time

Control

 

Time                             Sleep time in 2.097 s or 32.768 ms units. See Control.bit.4. Maximum sleep time is 38 hours 10 minutes 38.95 seconds or 35 minutes 47.48 seconds respectively. 0 specifies endless sleep (except Control.bit1 is set to run calibration process without performing sleep).

 

Control             • bit 0   Wake up on PORTB.4 pin negative edge change. See iqrfSleep IQRF OS function for more information.

                        • bit 1   Runs calibration process before going to sleep. Calibration takes approximately 16 ms and this time is subtracted from the requested sleep time. Calibration time deviation may produce an absolute sleep time error at short sleep times. But it is worth to run the calibration always before a longer sleep because the calibration time deviation then accounts for a very small total relative error. The calibration is always run before a first sleep with nonzero Time after the module reset if calibration was not already initiated by Time=0 and Control.bit.1=1.

                        • bit 2   If set, then if the device wakes up after the sleep period, a green LED once shortly flashes. It is useful for diagnostic purposes.

                        • bit 3   Wake up on PORTB.4 pin positive edge change. See iqrfSleep IQRF OS function for more information.

                        • bit 4   If set then the unit is 32.768 ms instead of default 2.097 s (i.e. 2048 × 1.024 ms).

                        • bit 5   iqrfDeepSleep instead of iqrfSleep is used. See IQRF OS documentation for more information.

                        • bit 6-7            Reserved.

 

Response

 

The general response to writing request with STATUS_NO_ERROR Error code.

 3.4.9.1               Source code support

typedef struct

{

  uns16      Time;

  uns8        Control;

} TPerOSSleep_Request;

 

TPerOSSleep_Request _DpaMessage.PerOSSleep_Request;

 3.4.10                Set Security

This command allows setting various security parameters.

 

Request

 

NADR

PNUM

PCMD

HWPID

0

1 … 16

NADR

0x02

0x06

?

Type

Data

 

Type                        0               Sets access password stored at Data using setAccessPassword. IQRF OS function

1               Sets user key stored at Data using setUserKey IQRF OS function.

other         Reserved

Data                        See Type above.

 

Response

 

The general response to writing request with STATUS_NO_ERROR Error code.

 

Error codes

ERROR_DATA      Invalid Type value.

 3.4.10.1             Source code support

typedef struct

{

  uns8 Type;

  uns8 Data[16];

} TPerOSSetSecurity_Request;

 

TPerOSSetSecurity_Request  _DpaMessage.PerOSSetSecurity_Request;

 3.4.11                Batch

[sync]   Batch command allows executing more individual DPA requests within one original DPA request. Both sender’s and addressee’s addresses of each embedded request equal to the corresponding addresses of the original Batch DPA request. It is not allowed to embed Batch command itself within series of individual DPA requests. Using neither Run discovery nor Bridge is not allowed inside batch command list. Batch command is useful not only to group commands but also to execute the asynchronous command(s) synchronously (after the Batch response is sent).

 

Request

 

NADR

PNUM

PCMD

HWPID

0

n

NADR

0x02

0x05

?

Requests

0

 

Requests                 Contains more DPA requests to be executed. The format at which the DPA requests are stored is the same as the format of Autoexec DPA requests. See Autoexec for more information.

 

Example

 

The following example runs a simple broadcast set of 5 DPA requests. It switches on the red LED at devices with HW profile ID 0x1234 or green LED at devices with HW profile ID 0x5678 respectively, then waits for 200 ms (using I/O peripheral) and finally switches the same LEDs off.

 

NADR=0x00FF, PNUM=0x02, PCMD=0x05, HWPID=0xFFFF, PData=
[1st command] {0x05
(length), 0x06(PNUM=LEDR), 0x01(PCMD=LED on), 0x1234(HWPID)},
[2nd command] {0x05
(length), 0x07(PNUM=LEDG), 0x01(PCMD=LED on), 0x5678(HWPID)},
[3rd command] {0x08
(length), 0x09(PNUM=I/O), 0x01(PCMD=Set),0xFFFF(HWPID),0xFF(Delay command),0x00C8(200 ms)}
[4th command] {0x05
(length), 0x06(PNUM=LEDR), 0x00(PCMD=LED off),0x1234HWPID)},
[5th command] {0x05
(length), 0x07(PNUM=LEDG), 0x00(PCMD=LED off),0x5678HWPID)},
{0x00
(end of batch)}

 

Response

 

The general response to writing request with STATUS_NO_ERROR Error code.

 3.4.12                Selective Batch

[sync]   This command is similar to the Batch but in addition it allows specifying nodes that execute the batch. This implies that the command is typically used at broadcast. This command is not implemented at the [C] device.

 

Request

 

NADR

PNUM

PCMD

HWPID

0 … 29

30

n

NADR

0x02

0x0B

?

SelectedNodes

Requests

0

 

SelectedNodes        See identically named field at Send Selective command.

Requests                 See identically named field at Batch command.

 

Response

 

The general response to writing request with STATUS_NO_ERROR Error code.

 3.4.12.1             Source code support

typedef struct

{

  uns8 SelectedNodes[30];

  uns8 Requests[DPA_MAX_DATA_LENGTH - 30];

} STRUCTATTR TPerOSSelectiveBatch_Request;

 

TPerOSSelectiveBatch_Request      _DpaMessage.PerOSSelectiveBatch_Request;

 3.4.13                LoadCode

[sync] [comdown] Implemented at [C] and [N] devices. This advanced command loads a code previously stored at external EEPROM to the MCU Flash memory. Then the device is reset. External EEPROM can actually store more code images at one time. When storing the code for upload at the external EEPROM make sure you do not overwrite another stored code, Autoexec or IO Setup.

 

Please note, that there might be a considerable delay before a response is ready because the command needs to read a larger amount of external EEPROM memory and compute the checksum.

 

The command can load two types of code:

1.     Custom DPA Handler code from the .hex file.


Custom DPA Handler code (but not the optional content of EEPROM and/or external EEPROM required by the handler) can be uploaded, updated or just “switched” “over the air” without the need to reprogram the device using a hardware programmer.


It is necessary to read output .hex file containing compiled Custom DPA Handler code to obtain the code before it can be stored as an image at external EEPROM. The continuous code block starts from the PIC address
CUSTOM_HANDLER_ADDRESS = 0x3A20 and is located up to address CUSTOM_HANDLER_ADDRESS_END - 1 = 0x3D7F. Because each MCU instruction takes 2 bytes the address inside .hex file is doubled so the code starts from address 0x7440 at the .hex file. Please read Custom DPA Handler Code from .hex File for more details.

 

The length of the image stored in the external EEPROM must be a multiple of 64 (used Flash memory page of MCU is 32 words long) otherwise the result is undefined. The checksum value is calculated from all the code bytes including unused trailing bytes that fill in last 64-byte block. We recommend filling in unused trailing bytes by value 0x34FF in order to get the same checksum value as IQRF IDE. The initial value of the Fletcher-16 checksum is 0x0001.

 

If loaded Custom DPA Handler code needs to use the certain content of EEPROM and/or external EEEPROM memory, then EEPROM and/or EEEPROM peripherals can be used to prepare the content before the handler is loaded. Disabling former Custom DPA Handler using Write HWP configuration byte (configuration byte at index 0x5, bit 0) and Restart is highly recommended (both commands might be the content of one Batch or Acknowledged broadcast - bits) if old or a new handler use EEPROM and/or EEEPROMperipherals. After new handler is loaded it must be then enabled back.

 

2.     IQRF plug-in containing DPA protocol implementation (to perform DPA version change on the fly), Custom DPA Handler or IQRF OS patch. The feature is supported starting from IQRF OS version 3.08D and the corresponding DPA version.


IQRF plug-in file is a text file containing an encrypted code. Only lines of the file that do not start with character # contain the code. Such lines contain 20 bytes stored by 2 hexadecimal characters (thus every line contains 40 characters in total). To create a code image for the external EEPROM from IQRF plug-in file just read all the consequential hexadecimal bytes from all code lines from the beginning to end of the file, convert them to the real bytes and store them in the external EEPROM.

 

The length of the image stored in the external EEPROM must be multiple of 20. The initial value of the Fletcher-16 checksum is 0x0003.


Please note that only DPA IQRF plug-in version 2.26 or higher can be loaded. Also, do not upload [CN] version of the DPA as it does not support this command and, therefore, the feature of uploading code will be irreversibly gone.

 

Request

 

NADR

PNUM

PCMD

HWPID

0

1 … 2

3 … 4

5 … 6

NADR

0x02

0x0A

?

Flags

Address

Length

CheckSum

 

Flags                bit 0     Action:

0  Computes and matches the checksum only without loading code.

1  Same as above plus loads the code into Flash if the checksum matches.

bit 1     Code type:

0  Loads Custom DPA Handler.
1  Loads IQRF plug-in.

bits 2-7 Reserved, must equal to 0.

Address           A physical address at external EEPROM memory to load the code image from. The address value is recommended to be a multiple of 64 because it allows more effective writingthe code image to the memory.

Length              Length of the code image in bytes at the external EEPROM. See text above.

CheckSum        One’s complement Fletcher-16 checksum of the code image. If the checksum does not match a checksum of the code stored in external EEPROM then writing the code to the Flash memory is not performed. See source code examples of the checksum calculation. For an initial checksum value see text above. Different initial checksum values for both types of upload code ensure that code types cannot be confused.

 

Response

 

NADR

PNUM

PCMD

HWPID

ErrN

DpaValue

0

NADR

0x02

0x8A

?

0

?

Result

 

imageResult               bit 0     1  The checksum matches a checksum of a code at the external EEPROM.

The code will be loaded if Flags.0=1 was specified at the request.
            0  The checksum does not match.

                        bit 1-7   Unused, equals to 0.

 3.4.13.1             Source code support

typedef struct

{

  uns8       Flags;

  uns16      Address;

  uns16      Length;

  uns16      CheckSum;

} TPerOSLoadCode_Request;

 

TPerOSLoadCode_Request _DpaMessage.TPerOSLoadCode_Request;

 3.5     EEPROM

PNUM = 0x03

 

This peripheral controls internal MCU EEPROM memory.

 3.5.1   Peripheral information

PerT                 PERIPHERAL_TYPE_EEPROM

PerTE               PERIPHERAL_TYPE_EXTENDED_READ_WRITE

Par1                 Size in bytes. In the current version of DPA it equals to 192 at [N] device or 64 at [C] respectivelyor [CN] devices.

Par2                 Maximum data block length. In the current version of DPA it equals to 55 bytes.

 

Actual EEPROM address space starts at address 0x00 at [N] device or at 0x80 at [C] or [CN] devices. There is a predefined symbol PERIPHERAL_EEPROM_START that equals to the actual starting address.

 3.5.2   Read

Reads data from the memory.

 

Request

 

NADR

PNUM

PCMD

HWPID

0

1

NADR

0x03

0x00

?

Address

Len

 

Address           An address to read data from.

Len                  Length of the data in bytes.

 

Response

 

NADR

PNUM

PCMD

HWPID

ErrN

DpaValue

0

Len-1

NADR

0x03

0x80

?

0

?

PData0

PDataLen-1

 

imageLen                  Read data length.

 

Error codes

ERROR_ADDR      Address is out of range.

 3.5.2.1               Source code support

typedef struct

{

  uns8 Address;

 

  union

  {

       struct

       {

         uns8 Length;

       } Read;

  } ReadWrite;

} TPerMemoryRequest;

 

TPerMemoryRequest _DpaMessage.MemoryRequest;

 3.5.3   Write

Writes data to the memory.

 

Request

 

NADR

PNUM

PCMD

HWPID

0

1

n+1

NADR

0x03

0x01

?

Address

PData0

PDatan-1

 

Address           An address to write data to.

PData              Actual data to be written to the memory.

n                      Written data length.

 

Response

 

The general response to writing request with STATUS_NO_ERROR Error code.

 

Error codes

ERROR_ADDR      Address is out of range.

 3.5.3.1               Source code support

typedef struct

{

  uns8 Address;

 

  union

  {

#define      MEMORY_WRITE_REQUEST_OVERHEAD     ( sizeof( uns8 ) )

       struct

       {

         uns8 PData[DPA_MAX_DATA_LENGTH - MEMORY_WRITE_REQUEST_OVERHEAD];

       } Write;

 

  } ReadWrite;

} TPerMemoryRequest;

 

TPerMemoryRequest _DpaMessage.MemoryRequest;

 3.6     EEEPROM

PNUM = 0x04

 

This peripheral controls external serial EEPROM memory. If the external serial EEPROM memory is not present ERROR_FAIL code is returned. Please note that the part of the external EEPROM memory space can be used for Autoexec and/or IO Setup.

 3.6.1   Peripheral information

PerT                 PERIPHERAL_TYPE_BLOCK_EEPROM

PerTE               PERIPHERAL_TYPE_EXTENDED_READ_WRITE

Par1                 Memory size in 256 bytes blocks. In the current version of DPA, it equals to 0x80.

Par2                 Data block size (equals to 16). The parameter is used by Read & Writecommands.

 3.6.2   Extended Read

This command allows reading data from the whole physical address space of the external EEPROM.

 

Request

 

NADR

PNUM

PCMD

HWPID

0 … 1

2

NADR

0x04

0x02

?

Address

Len

 

Address           A physical address to read data from.

Len                   Length of the data to read in bytes. Allowed range is 0-54 bytes. Reading behind maximum address range is undefined.

 

Response

 

NADR

PNUM

PCMD

HWPID

ErrN

DpaValue

0

Len-1

NADR

0x04

0x82

?

0

?

PData0

PDataLen-1

 

imageLen                  Read data length.

 

Error codes

ERROR_ADDR      Address is out of range.

ERROR_FAIL      Error accessing serial EEPROM chip.

 3.6.2.1               Source code support

typedef struct

{

  uns16      Address;

 

  union

  {

       struct

       {

         uns8 Length;

       } Read;

  } ReadWrite;

} STRUCTATTR TPerXMemoryRequest;

 

TPerXMemoryRequest _DpaMessage.XMemoryRequest;

 3.6.3   Extended Write

This command allows writing data to the address space of the external EEPROM.

 

Request

 

NADR

PNUM

PCMD

HWPID

0 … 1

2

n+2

NADR

0x04

0x03

?

Address

Data0

Datan-1

 

Address           The allowed address range is 0x0000-0x3FFF.

Data                 Actual data to be written to the memory.

n                      Length of the data to write in bytes. Allowed range is 1-54 bytes. Writing to multiple adjacent 64-byte pages of the EEPROM chip or behind maximum address range by one extended write command is unsupported and undefined. Please see IQRF OS documentation for eeeWriteData function details.

 

Response

 

The general response to writing request with STATUS_NO_ERROR Error code.

 

Error codes

ERROR_ADDR      Address is out of range.

ERROR_FAIL      Error accessing serial EEPROM chip.

 3.6.3.1               Source code support

typedef struct

{

  uns16      Address;

 

  union

  {

#define      XMEMORY_WRITE_REQUEST_OVERHEAD    ( sizeof( uns16 ) )

 

       struct

       {

         uns8 PData[DPA_MAX_DATA_LENGTH - XMEMORY_WRITE_REQUEST_OVERHEAD];

       } Write;

 

  } ReadWrite;

} STRUCTATTR TPerXMemoryRequest;

 

TPerXMemoryRequest _DpaMessage.XMemoryRequest;

 3.7     RAM

PNUM = 0x05

 

This peripheral controls block of internal MCU RAM memory. The address space of the peripheral occupies the whole bank 12 of the MCU RAM and can be accessed by an array variable PeripheralRam from Custom DPA Handler code.

 3.7.1   Peripheral information

PerT                 PERIPHERAL_TYPE_RAM

PerTE               PERIPHERAL_TYPE_EXTENDED_READ_WRITE

Par1                 Size in bytes. In the current version of DPA equals to 48.

Par2                 Maximum data block length. In the current version of DPA equals to 48.

 3.7.2   Read & Write

See EEPROM.

 3.7.2.1               Source code support

#pragma rambank = 12

uns8  PeripheralRam[PERIPHERAL_RAM_LENGTH];

 3.8     SPI (Slave)

PNUM = 0x08

 

The peripheral is not available at the Coordinator [C] device. The peripheral is not available at [N] or [CN] devices supporting UART interface too.

 

The usage of the peripheral is limited at LP mode because the device regularly sleeps in its main receiving loop. The peripheral works only when the device does not sleep or during a time defined by a ReadTimeout parameter of a Write & Read command. Please see details below.

 3.8.1   Peripheral information

PerT                 PERIPHERAL_TYPE_SPI

PerTE               PERIPHERAL_TYPE_EXTENDED_READ_WRITE

Par1                 Maximum data block length

Par2                 Not used

 3.8.2   Write & Read

Writes and/or reads data to/from SPI peripheral. See UART Write & Read which uses the same read & write logic except PNUM = 0x08 and PCMD = 0x00.

 3.9     LED

PNUM = 0x06 or 0x07 for standard red respectively green LED at IQRF (DC)TR module.

 

Please note that at LP mode the device regularly enters a sleep mode when waiting for a packet so the LED is switched off. To keep LED on for some time use LED request together with IO Set request with a delay. Both requests can be stored in one Batch request so the packet will not be received after the LED command.

 3.9.1   Peripheral information

PerT                 PERIPHERAL_TYPE_LED

PerTE               PERIPHERAL_TYPE_EXTENDED_READ_WRITE

Par1                 LED_COLOR_* where * specifies one of the predefined color constant.

Par2                 Not used

 3.9.2   Set

Controls the state of the LED peripheral.

 

Request

 

NADR

PNUM

PCMD

HWPID

NADR

0x06 or 0x07

OnOff

?

 

OnOff              0x01 to switch LED on, 0x00 to switch LED off

 

Response

 

The general response to writing request with STATUS_NO_ERROR Error code.

 3.9.3   Get

Returns a state of the LED.

 

Request

 

NADR

PNUM

PCMD

HWPID

NADR

0x06 or 0x07

0x02

?

 

Response

 

NADR

PNUM

PCMD

HWPID

ErrN

DpaValue

0

NADR

0x06 or 0x07

0x82

?

0

?

OnOff

 

OnOff   0x01 when LED is on, 0x00 when LED is off

 3.9.4   Pulse

Generates one LED pulse using IQRF OS function pulseLEDx.

 

Request

 

NADR

PNUM

PCMD

HWPID

NADR

0x06 or 0x07

3

?

 

Response

 

The general response to writing request with STATUS_NO_ERROR Error code.

 3.10                 IO

PNUM = 0x09

 

This peripheral controls IO pins of the MCU. Please note that the pins used by an internal IQRF (DC)TR module circuitry cannot be used and their control by this peripheral is blocked. See a corresponding IQRF (DC)TR module datasheet for the IO pins that are available.

 3.10.1                Peripheral information

PerT                 PERIPHERAL_TYPE_IO

PerTE               PERIPHERAL_TYPE_EXTENDED_READ_WRITE

Par1                 Bitmask specifying supported MCU ports (b0=PORTA, b1=PORTB, …, b7=PORTH)

Par2                 Not used

 3.10.2                Direction

This command sets the direction of the individual IO pins of the individual ports. Additionally, the same command can be used to setup weak pull-ups at the pins where available. See datasheet of the PIC MCU for a description of IO ports.

 

Request

NADR

PNUM

PCMD

HWPID

0

1

2

n × 3

n × 3 + 1

n × 3 + 2

NADR

0x09

0x00

?

Port0

Mask0

Value0

Portn

Maskn

Valuen

 

Port                  a. Specifies port to setup a direction to. 0x00=TRISA, 0x01=TRISB, …(predefined symbols PNUM_IO_TRISx) or

b. Specifies port to setup a pull-up. 0x11=WPUB, 0x14=WPUE (predefined symbols PNUM_IO_WPUx)

Mask                Masks pins of the port.

Value               a. Actual direction bits for the masked pins. 0=output, 1=input., … or

                        b. Pull-up state. 0=disabled, 1=enabled.

 

Error codes

ERROR_DATA      Invalid Port value.

 

Response

 

The general response to writing request with STATUS_NO_ERROR Error code.

 3.10.2.1             Source code support

typedef struct

{

  uns8  Port;

  uns8  Mask;

  uns8  Value;

} TPerIOTriplet;

 

typedef union

{

  TPerIOTriplet Triplets[DPA_MAX_DATA_LENGTH / sizeof( TPerIOTriplet )];

} TPerIoDirectionAndSet_Request;

 

TPerIoDirectionAndSet_Request _DpaMessage.PerIoDirectionAndSet_Request;

 3.10.3                Set

[sync]   This command sets the output state of the IO pins. It also allows inserting an active waiting delay between IO pins settings. This feature can be used to generate an arbitrary time defined signals on the IO pins of the MCU. During the active waiting, the device is blocked and any network traffic will not be processed.

 

This command is executed after the DPA response is sent back to the device that sent the original DPA IO Set request. Therefore, if an invalid port is specified an error code is not returned inside DPA response but the rest of the request execution is skipped.

 

Request

 

NADR

PNUM

PCMD

HWPID

0

1

2

n × 3

n × 3 + 1

n × 3 + 2

NADR

0x09

0x01

?

command0

commandn

 

triple     There are 2 types of 3-byte commands allowed:

a.     Setting an output value

port     Specifies the port to setup an output state. 0=PORTA, 1=PORTB, … (predefined symbols PNUM_IO_PORTx)

            mask    Masks pins of the port to setup.

            value    Actual output bit value for the masked pins.

b.    Delay

0xFF    Specifies a delay command (predefined symbol PNUM_IO_DELAY).

            delayL  Lower byte of the 2-byte delay value, unit is 1 ms.

            delayH  Higher byte of the 2-byte delay value, unit is 1 ms.

 

Response

 

The general response to writing request with STATUS_NO_ERROR Error code.

 

Example 1

 

Setting of PORTA.0 and PORTC.2 as output, PORTC.3 as input.

 

·         Request

NADR=0x0001, PNUM=0x09, PCMD=0x00, HWPID=0xFFFF, PData={0x00(PORTA), 0x01(bit0=1), 0x00(bit0=output)} {0x02(PORTC), 0x0C(bit2=1, bit3=1), 0x08(bit2=output, bit3=input)}

 

·         Response

NADR=0x0001, PNUM=0x09, PCMD=0x80, HWPID=0xABCD, PData={00}(No error), {0x07}(DPA Value)

 

Example 2

 

Setting of PORTA.0=1, PORTC.2=1, then wait for 300 ms, set PORTA.0=0.

 

·         Request

NADR=0x0001, PNUM=0x09, PCMD=0x01, HWPID=0xFFFF, PData={0x00(PORTA), 0x01(bit0=1), 0x01(bit0=1)} {0x02(PORTC), 0x04(bit2=1), 0x04(bit2=1)} {0xFF(delay), 0x2C (low byte of 300), 0x01(high byte of 300)} {0x00(PORTA), 0x01(bit0=1), 0x00(bit0=0)}

 

·         Response

NADR=0x0001, PNUM=0x09, PCMD=0x81, HWPID=0xABCD, PData={00}(No error), {0x07}(DPA Value)

 

 3.10.3.1             Source code support

typedef struct

{

  uns8  Port;

  uns8  Mask;

  uns8  Value;

} TPerIOTriplet;

 

typedef struct

{

  uns8  Header;     // == PNUM_IO_DELAY

  uns16 Delay;

} TPerIODelay;

                

typedef union

{

  TPerIOTriplet Triplets[DPA_MAX_DATA_LENGTH / sizeof( TPerIOTriplet )];

  TPerIODelay   Delays[DPA_MAX_DATA_LENGTH / sizeof( TPerIODelay )];

} TPerIoDirectionAndSet_Request;

 

TPerIoDirectionAndSet_Request _DpaMessage.PerIoDirectionAndSet_Request;

 3.10.4                Get

This command is used to read the input state of all supported the MCU ports (PORTx).

 

Request

 

NADR

PNUM

PCMD

HWPID

NADR

0x09

0x02

?

 

Response

 

NADR

PNUM

PCMD

HWPID

ErrN

DpaValue

0 n

NADR

0x09

0x82

?

0

?

Port data

 

Port data          Array of bytes representing the state of port PORTA, PORTB, …, ending with the last supported MCU port.

 3.11                 Thermometer

PNUM = 0x0A for standard on-board thermometer peripheral

 3.11.1                Peripheral information

PerT                 PERIPHERAL_TYPE_THERMOMETER

PerTE               PERIPHERAL_TYPE_READ

Par1                 Not used

Par2                 Not used

 3.11.2                Read

Reads on-board thermometer sensor value.

 

Request

NADR

PNUM

PCMD

HWPID

NADR

0x0A

0x00

?

 

Response

 

NADR

PNUM

PCMD

HWPID

ErrN

DpaValue

0

1

2

NADR

0x0A

0x80

?

0

?

TempC

Temp16

 

TempC             Temperature in °C, integer part, not rounded.
See return value of getTemperature IQRF OS function. If the temperature sensor is not installed (see
HWP Configuration) then the returned value is 0x80 = -128 °C.

Temp16            Complete 12 bit value of the temperature in 0.5 °C.
See getTemperature IQRF OS function. If the temperature sensor is not installed the value is undefined.

 3.11.2.1             Source code support

typedef struct

{

  int8  IntegerValue;

  int16 SixteenthValue;

} TPerThermometerRead_Response;

 

TPerThermometerRead_Response _DpaMessage.PerThermometerRead_Response;

 3.12                 PWM

PNUM = 0x0B for standard MCU PWM peripheral

 

The peripheral is available at Demo version, STD mode and at the [N] device only. The source code of the demo version implementation of the PWM peripheral is available among custom DPA handler examples. See CustomDpaHandler-UserPeripheral-PWM.c.

 3.12.1                Peripheral information

PerT          PERIPHERAL_TYPE_PWM

PerTE        PERIPHERAL_TYPE_WRITE

Par1                 Not used

Par2                 Not used

 3.12.2                Set

Sets PWM parameters.

 

Request

 

NADR

PNUM

PCMD

HWPID

0

1

2

NADR

0x0B

0x00

?

Prescaler

Period

Duty

 

Prescaler          bit <1:0> codes prescaler values at T6CON register:

                        • 11 = prescaler is 64

                        • 10 = prescaler is 16

                        • 01 = prescaler is 4

                        • 00 = prescaler is 1

                        bit <5:4> codes two least significant bits of 10bit Duty cycle <1:0>.

Period              Sets the PR6 register for PWM period.

Duty                 Eight most significant bits of 10bit duty cycle value <9:2>. It sets the CCPR6 register.

 

When all 3 parameters equal to 0, PWM is stopped.

 

Response

 

The general response to writing request with STATUS_NO_ERROR Error code.

 

Error codes

ERROR_DATA      Invalid Prescaler value.

 

 

Example 1

 

Set PWM for 1 kHz with 50% of duty cycle and prescaler 16:

 

·         DPA request (master > slave)

NADR=0x0001, PNUM=0x0B, PCMD=0x00, HWPID=0xFFFF, PData={0x02,0x7d,0x40}

·         DPA response (slave > master)

NADR=0x0001, PNUM=0x0B, PCMD=0x80, HWPID=0xABCD, PData={0x00}(No error)

 

Example 2

 

Set PWM for 1 kHz with 70% of duty cycle and prescaler 16:

 

Note: prescaler value is 0x02 = 0b00000010, but the duty cycle value is in this case 0x15E = 0b101011110, the bits<1:0> (0b101011110) are added into Prescaler value (0b00100010 = 0x22) to bits <5:4> and the seven most significant bits (0b101011110) are written into Duty (0b1010111 = 0x57).

 

·         DPA request (master > slave)

NADR=0x0001, PNUM=0x0B, PCMD=0x00, HWPID=0xFFFF, PData={0x22,0x7d,0x57}

·         DPA response (slave > master)

NADR=0x0001, PNUM=0x0B, PCMD=0x80, HWPID=0xABCD, PData={0x00}(No error)

 3.12.2.1             Source code support

typedef struct

{

  uns8  Prescaler;

  uns8  Period;

  uns8  Duty;

} TPerPwmSet_Request;

 

TPerPwmSet_Request _DpaMessage.PerPwmSet_Request;

 3.13                 UART

PNUM = 0x0C for embedded UART peripheral

 

The peripheral is not available at the Coordinator [C]. The peripheral is not available at [N] or [CN] devices supporting UART interface. The size of both TX and RX buffers is 64 bytes.

 

The usage of the peripheral is limited at LP mode because the device regularly sleeps in its main receiving loop. The peripheral works only when the device does not sleep or during a time defined by a ReadTimeout parameter of a Write & Read command. Please see details below.

 

PIC HW UART peripheral interrupts can be handled at the Custom DPA Handler Interrupt event unless the DPA UART peripheral is not open or DPA UART Interface is not used.

 3.13.1                Peripheral information

PerT          PERIPHERAL_TYPE_UART

PerTE        PERIPHERAL_TYPE_READ_WRITE

Par1                 Maximum data block length for reading and writing. Currently, it equals to 55 bytes.

Par2                 Not used

 3.13.2                Open

This command opens UART peripheral at specified baud rate (predefined symbols DpaBaud_xxx can be used in the code) and discards internal read and write buffers. The size of the read and write buffers is 64 bytes.

 

Request

 

NADR

PNUM

PCMD

HWPID

0

NADR

0x0C

0x00

?

BaudRate

 

BaudRate         specifies baud rate:

·         0x00             1 200 Baud

·         0x01             2 400 Baud

·         0x02             4 800 Baud

·         0x03             9 600 Baud

·         0x04            19 200 Baud

·         0x05            38 400 Baud

·         0x06            57 600 Baud

·         0x07           115 200 Baud

·         0x08           230 400 Baud

 

Response

 

The general response to writing request with STATUS_NO_ERROR Error code.

 

 

Error codes

ERROR_DATA      Invalid BaudRate value.

 

Example 1

 

Open UART for communication with 9 600 baud rate:

 

·         DPA request (master > slave)
NADR=0x0001, PNUM=0x0C, PCMD=0x00, HWPID=0xFFFF, PData={0x03}(9 600 Baud)

 

·         DPA response (slave > master)
NADR=0x0001, PNUM=0x0C, PCMD=0x80, HWPID=0xABCD, PData={0x00}(No error)

 3.13.2.1             Source code support

typedef struct

{

  uns8  BaudRate;

} TPerUartOpen_Request;

 

TPerUartOpen_Request _DpaMessage.PerUartOpen_Request;

 3.13.3                Close

Closes UART peripheral.

 

Request

           

NADR

PNUM

PCMD

HWPID

NADR

0x0C

0x01

?

 

Response

 

The general response to writing request with STATUS_NO_ERROR Error code.

 3.13.4                Write & Read

Writes and/or reads data to/from UART peripheral. If UART is not open, the request fails with ERROR_FAIL.

 

Request

 

NADR

PNUM

PCMD

HWPID

0

1 … n

NADR

0x0C

0x02

?

ReadTimeout

WrittenData

 

ReadTimeout    Specifies timeout in 10 ms unit to wait for data to be read after data is (optionally) written. 0xFF specifies that no data should be read.

WrittenData       Optional data to be written to the UART TX buffer.

 

Response

 

NADR

PNUM

PCMD

HWPID

ErrN

DpaValue

0 n-1

NADR

0x0C

0x82

?

0

?

ReadData

 

ReadData         Optional data read from UART RX buffer if the reading was requested and data is available. Please note that internal buffer limits a maximum number of bytes to PERIPHERAL_UART_MAX_DATA_LENGTH.

 

Error codes

ERROR_FAIL      UART peripheral is not open.

 

Example 1

 

Write three bytes (0x00, 0x01 and 0x02) to UART, no reading:

·         DPA request (master > slave)
NADR=0x0001, PNUM=0x0C, PCMD=0x02, HWPID=0xFFFF, PData={0xff}(No reading) {0x00,0x01,0x02}(written data)

 

·          DPA response (slave > master)
NADR=0x0001, PNUM=0x0C, PCMD=0x82, HWPID=0xABCD, PData={0x00}(No error)

 

Example 2

 

Write three bytes (0x00, 0x01 and 0x02) to UART, read 4 bytes after 10 ms:

 

·         DPA request (master > slave)
NADR=0x0001, PNUM=0x0C, PCMD=0x02, HWPID=0xFFFF, PData={0x01}(10 ms timeout) {0x00,0x01,0x02}(written data)

 

·         DPA response (slave > master)

NADR=0x0001, PNUM=0x0C, PCMD=0x82, HWPID=0xABCD,

PData={0x00}(No error){0xaa,0xbb,x0cc,0xdd}(read data)

 3.13.4.1             Source code support

typedef struct

{

  uns8 ReadTimeout;

  uns8 WrittenData[DPA_MAX_DATA_LENGTH - sizeof( uns8 )];

} TPerUartSpiWriteRead_Request;

 

TPerUartSpiWriteRead_Request _DpaMessage.PerUartSpiWriteRead_Request;

 3.13.1                Clear & Write & Read

Same as Write & Read from above except it clears UART RX buffer at the start and then it executes write and read. Also PCMD = 0x03.

 3.14                 FRC

PNUM = 0x0D for embedded FRC peripheral.

 

The peripheral is implemented at the [C] and [CN] devices only.

 3.14.1                Peripheral information

PerT          PERIPHERAL_TYPE_FRC

PerTE        PERIPHERAL_TYPE_READ_WRITE

Par1                 Length of FRC data returned by Send command.

Par2                 Not used

 3.14.2                Send

This command starts Fast Response Command (FRC) process supported by IQRF OS. It allows quick and using only one request to collect the same type of information (data length) from multiple nodes in the network. Type of the collected information is specified by a byte called FRC command. Currently, IQRF OS allows collecting either 2 bits from all (up to 239) nodes, 1 byte from up to 63 nodes (having logical addresses 1-63) or 2 bytes from up to 31 nodes (having logical addresses 1-31). Type of collected data is specified by FRC command value:

 

Type of collected data

FRC Command interval

Reserved interval

User interval

2 bits

0x00 – 0x7F

0x00 – 0x3F

0x40 – 0x7F

1 byte

0x80 – 0xDF

0x80 – 0xBF

0xC0 – 0xDF

2 bytes

0xE0 – 0xFF

0xE0 – 0xEF

0xF0 – 0xFF

 

When 2 bits are collected, then the 1st bits from the nodes are stored in the bytes of index 0-29 of the output buffer, 2nd bits from the nodes are stored in the bytes of index 32-61.

 

When 1 byte is collected then bytes from each node (1-63) are stored in bytes 1-63 of the output buffer.

 

When 2 bytes are collected then byte pairs for each node (1-31) are stored in bytes 2-63 of the output buffer.

 

For more information see IQRF OS manuals. If the node does not return an FRC value for some reason, then either returned bits or bytes are equal to 0. This is why it is necessary to code the zero return value into a non-zero one.

 

The time when the response is delivered depends on the type of the FRC command and used RF mode. Consult IQRF OS guides for the response time calculation.

 

Request

           

NADR

PNUM

PCMD

HWPID

0

1 … n

NADR

0x0D

0x00

?

FRC Command

UserData

 

FRC Command             Specifies data to be collected.

UserData                      User data that are available at IQRF OS array variable DataOutBeforeResponseFRC at FRC Value event. The length n is from 2 to 30 bytes.

Response

 

NADR

PNUM

PCMD

HWPID

ErrN

DpaValue

0

1 n

NADR

0x0D

0x80

?

0

?

Status

FRC data

 

Status              Return code of the sendFRC IQRF OS function. See IQRF OS documentation for more information.

FRC data          Data collected from the nodes. Because the current version of DPA cannot transfer the whole FRC output buffer at once (currently only up to 55 bytes), the remaining bytes of the buffer can be read by the next described Extra result command.

 3.14.2.1             Source code support

typedef struct

{

  uns8 FrcCommand;

  uns8 UserData[30];

} TPerFrcSend_Request;

 

TPerFrcSend_Request _DpaMessage.PerFrcSend_Request;

 

typedef struct

{

  uns8  Status;

  uns8 FrcData[DPA_MAX_DATA_LENGTH - sizeof( uns8 )];

} TPerFrcSend_Response;

 

TPerFrcSend_Response _DpaMessage.PerFrcSend_Response;

 3.14.3                Extra result

Reads remaining bytes of the FRC result, so the total number of bytes obtained by both commands will be total 64. It is needed to call this command immediately after the FRC Send command to preserve previously collected FRC data.

 

Request

           

NADR

PNUM

PCMD

HWPID

NADR

0x0D

0x01

?

 

Response

 

NADR

PNUM

PCMD

HWPID

ErrN

DpaValue

0 n

NADR

0x0D

0x81

?

0

?

FRC data

 

FRC data          Remaining FRC data that could not be read by FRC Send command because DPA data buffer size limitations.

 3.14.4                Send Selective

Similar to Send but allows to specify a set of nodes that will receive the FRC command and return FRC data. Together with Acknowledged broadcast - bits it can be then used to execute DPA request at selected nodes only and get the confirmation plus one data bit from selected nodes. Both request and response have the same structure as Send except SelectedNodes field. Also, the length of UserData field is limited to 25 bytes. When 1 byte or 2 bytes are collected then results from all selected nodes are adjacent, so there are no gaps filled with 0s for unselected nodes (unlike Send command).

 

Request

           

NADR

PNUM

PCMD

HWPID

0

1 … 30

31 … n

NADR

0x0D

0x02

?

FRC Command

SelectedNodes

UserData

 

FRC Command             Specifies data to be collected.

SelectedNodes             Specifies a bitmap with selected nodes. Bit1 of the 1st byte of the bitmap represents node with address 1, bit2 of the 1st byte of the bitmap represents node with address 2, …, bit7 of the 30th byte of the bitmaps represents nodes with address 239.

UserData                      User data that are available at IQRF OS array variable DataOutBeforeResponseFRC at FRC Value event. The length of data is from 2 to 25 bytes.

 

Response

 

See Send DPA response.

 3.14.4.1             Source code support

typedef struct

{

  uns8 FrcCommand;

  uns8 SelectedNodes[30];

  uns8 UserData[25];

} TPerFrcSendSelective_Request;

 

TPerFrcSendSelective_Request _DpaMessage.PerFrcSendSelective_Request;

 3.14.5                Set FRC Params

Sets global FRC parameters.

 

Request

 

NADR

PNUM

PCMD

HWPID

0

NADR

0x0D

0x03

?

FRCresponseTime

 

FRCresponseTime         Value corresponding to one of the constants _FRC_RESPONSE_TIME_??_MS (see IQRF-macros.h) to set maximum time reserved for preparing return FRC value. See IQRF OS documentation for more details.

 

Response

 

NADR

PNUM

PCMD

HWPID

ErrN

DpaValue

0

NADR

0x0D

0x83

?

0

?

FRCresponseTime

 

FRCresponseTime         Previous FRCresponseTime value.

 

 3.14.5.1             Source code support

typedef struct

{

  uns8 FRCresponseTime;

} TPerFrcSetParams_RequestResponse;

 

TPerFrcSetParams_RequestResponse _DpaMessage.PerFrcSetParams_RequestResponse;

 3.14.6                Embedded FRC Commands

There are a few embedded FRC commands. The user can implement custom FRC command too. See User FRC Codes intervals for allowed custom FRC command values and FrcValue event.

 

All embedded FRC commands prepare returned FRC value within the shortest predefined FRC response time of 40 ms (corresponds to _FRC_RESPONSE_TIME_40_MS constant). Only in the case of Memory read and Memory read plus 1 commands the FRC response time depends on the DPA request that is specified by the user and executed before the FRC value is returned. Event FrcResponseTime is not implemented for embedded FRC commands, therefore, FRC response time returns 0xFF for them.

 3.14.6.1             Prebonding

FRC_Prebonding = 0x00

 

Collects bits. Gives detail information about the state of pre-bonding. Bit 0 is 1 when a node is accessible; bit1 is 1 if the node provided pre-bonding to a new node. If bit 0 of the 1st user data byte sent with FRC command is set, the remote bonding at node device is also disabled. Subsequently, detail information can be read using Read remotely bonded module ID from the node.

 3.14.6.2             UART or SPI data available

FRC_UART_SPI_data = 0x01

 

Collects bits. Bit 0 is 1 when a node is accessible; bit1 is 1 when there is some data available for reading from UART or SPI peripheral.

 3.14.6.3             Acknowledged broadcast - bits

FRC_AcknowledgedBroadcastBits = 0x02

 

This command except for collecting bits allows executing DPA Request stored at FRC user data after the FRC result is sent back [sync]. When the Send Selective request is used, then the DPA request is executed at selected nodes only.

 

FCR user data has the following content. Please note that DPA does not check the correct content or length of FRC user data (except maximum FRC user data length 30 bytes).

 

0

1

2

3 … 4

5 … length - 1

Length

PNUM

PCMD

HWPID

PData

 

Length              Total length of FRC user data containing the DPA Request.

PNUM              Peripheral number of executing DPA Request at.

PCMD              Peripheral command.

HWPID             HWPD of the DPA Request.

PData               Optional DPA Request Data.

 

DPA Request is executed only when HWPID matches the HWPID of the device or HWPID_DoNotCheckis specified. In this case, also, FrcValue event is raised to allow setting resulting Bit.1 by the user. The sender address of the embedded DPA request equals to 0x00 (coordinator address) and the addressee addresses is 0xFF (broadcast address).

 

Returned bits:

bit 0

bit 1

Description

0

0

Node device did not respond to FRC at all.

0

1

HWPID did not match HWPID of the device.

1

x

HWPID matches HWPID of the device. Bit.1 can be set by FrcValue event. At the end, DPA Request is executed.

 

Exampleof FRC user data:

 

This example will pulse both LEDs after the FRC is collected. To pulse both LEDs by one request a Batch request is used to package individual 2 LED pulse requests into one request.

 

16{Length}, 2{PNUM=OS}, 5{PCMD=Batch}, 0xffff{HWPID}, [5{LED Request length},7{PNUM=LEDG},3{PCMD=PulseLED}, 0xffff{HWPID}, 5{ LED Request length },6{ PNUM=LEDR},3{ PCMD=PulseLED }, 0xffff{HWPID}, 0{End of Batch}] {PData=Batch PData}

 3.14.6.4             Read temperature

FRC_Temperature = 0x80

 

Collects bytes. Resulting byte equals to the temperature value read by getTemperature IQRF OS method. If resulting temperature is 0°C, which would normally equal to value 0, then a fixed value 0x7F is returned instead. This value substitution makes it possible to distinguish between devices reporting 0°C and devices not reporting at all. The device would normally never return a temperature corresponding to the value 0x7F because +127°C is out of working temperature range.

 3.14.6.5             Acknowledged broadcast - bytes

FRC_AcknowledgedBroadcastBytes = 0x81

 

Collects bytes. Resulting byte equals normally to the same temperature value as Read temperaturecommand, but if this FRC command is caught by FrcValue event and a nonzero value is stored at responseFRCvalue then this value is returned instead of temperature. FRC user data also stores DPA request to execute after data bytes are collected in the same way as Acknowledged broadcast - bits FRC command does.

 3.14.6.6             Memory read

FRC_MemoryRead = 0x82

 

Collects bytes. A resulting byte is read from the specified memory address after provided DPA Request is executed. This allows getting one byte from any memory location (RAM, EEPROM and EEEPROM peripherals, Flash, MCU register, etc.). As the returned byte cannot equal to 0 there is also Memory read plus 1 FRC command available.

 

FCR user data has the following content. Please note that DPA does not check the correct content or length of FRC user data. A batch request is not allowed to be a DPA request being executed. Specified DPA Request is executed with an HWPID the node has.

 

0 … 1

2

3

4

5 … 6 - Length

Memory address

PNUM

PCMD

Length

PData

Memory address          Memory address to read the byte from.

PNUM                          Peripheral number of executing DPA Request at.

PCMD                          Peripheral command.

Length                         Length of the optional DPA Request data.

PData                          Optional DPA Request Data.

 

Example 1

 

This example reads OS version. OS Read DPA Request will be executed and then a byte from _DpaMessage.PerOSRead_Response.OsVersion variable (the request stores the result/response there) will be returned. The actual address of this byte is 0x4A4. See .h or .var files for details.

 

FRC command = FRC_MemoryRead = 0x82

Memory address = 0x4A4

PNUM = PNUM_OS = 0x02

CMD = CMD_OS_READ = 0x00

Length = 0 = No data bytes

PData   none

 

Example 2

 

This example reads the value of IQRF OS lastRSSI variable. Dummy LED Get DPA Request will be executed and then a byte from lastRSSI variable will be returned. The actual address of this variable is 0x5B6. Open a generated .var file of any IQRF compiled project to find out an address of a system variable.

 

FRC command = FRC_MemoryRead = 0x82

Memory address = 0x5B6

PNUM = PNUM_LEDR = 0x06

CMD = CMD_LED_GET = 0x02

Length = 0 = No data bytes

PData   none

 

Example 3

 

This example reads a lower byte of HWPID version from more nodes at once. Peripheral enumeration DPA Request is executed and result byte is read. Address 0x4A9 points to lower byte of HWPID. Use an address from range 0x4A7 to 0x4AA to read any byte of HWPID or HWPID version respectively.

 

FRC command = FRC_MemoryRead = 0x82

Memory address = 0x4A9

PNUM = PNUM_ENUMERATION = 0xFF

CMD = CMD_GET_PER_INFO = 0x3F

Length = 0 = No data bytes

PData   none

 

Example 4

 

This example return supply voltage level using embedded OS Read command. See getSupplyVoltage at IQRF OS Reference Guide for the format of the return value.

 

FRC command = FRC_MemoryRead = 0x82

Memory address = 0x4A9

PNUM = PNUM_OS = 0x02

CMD = CMD_OS_READ = 0x00

Length = 0 = No data bytes

PData   none

 3.14.6.7             Memory read plus 1

FRC_MemoryReadPlus1 = 0x83

 

Same as Memory read but 1 is added to the returned byte in order to prevent returning 0. This means that this FRC command cannot return 0xFF value.

 

Example 1

 

This example returns byte+1 being read from EEPROM peripheral at address 3. EEPROM Read DPA request will be executed and then a byte from _DpaMessage.Response.PData[0] (the request stores the result/response there) will be returned. The actual address of this byte is 0x4A0. See .h or .var files for details.

 

FRC command = FRC_MemoryReadPlus1 = 0x83

Memory address = 0x4A0

PNUM = PNUM_EEPROM = 0x03

CMD = CMD_EEPROM_READ = 0x00

Length = 2 = Two data bytes

PData[0] = 3 = Read from EEPROM address 3

PData[1] = 1 = Read one byte from EEPROM

 3.14.6.8             FRC response time

FRC_FrcResponseTime = 0x84

 

Collects bytes. This embedded FRC command is used to find out FRC response time of the specified user FRC command. This is useful when a network consists of devices with different hardware profiles implementing the same user FRC command but a different way that might result in different FRC response times. In this case, it is necessary to specify the maximum FRC response time that has any node from the set of nodes that will receive the specified FRC command. This FRC command actually raises FrcResponseTime event where a user code returns the time. The returned time value equals to the value of the corresponding _FRC_RESPONSE_TIME_??_MS constant (see IQRF-macros.h) with the lowest bit set (internally by DPA) in order to prevent returning zero value. If the specified FRC command is not supported (i.e. FrcResponseTime event is not handled) returned value is 0xFF.

 

FRC user data has the following format:

 

0

1

FRCcommand

0

 

FRCcommand  Value of the user FRC command to read FRC response time of.


 

 4         HWP Configuration

HWP (hardware profile) configuration is stored in the MCU Flash memory. It is necessary to correctly configure the device before DPA is used for the first time. The configuration can be modified by IQRF IDE using SPI or RFPGM programming, by DPA Service Mode or by Read HWP configuration/Write HWP configuration/Write HWP configuration byte commands. There are predefined symbols CFGIND_??? having the address of each configuration item.

 

The following table depicts documented configuration items. Other items are reserved. The total size of the configuration block is 32 bytes.

 

Address

Description

0x00

The checksum of HWP Configuration block. See Write HWP configuration for details.

0x01 [**]

An array of 32 bits. Each bit enables/disables one of the embedded 32 predefined peripherals. Peripheral #0 (Coordinator) is controlled by bit 0.0, peripheral #31 (currently not used, but reserved) is controlled by bit 3.7. It does not make sense to enable the peripheral that is not implemented in the currently used device (see Peripheral enumeration).

0x02 [**]