Our website is under construction. Please stay tuned!

API Operation

---

GPIO notification for status change

Rather than the host device initiating the SPI/UART communication, the DWM module can send notifications of status changes by toggling the dedicated GPIO pin (P0.26) to the HIGH level, as illustrated below. To enable this feature, the host device needs to use the dwm_int_cfg_set command. On detecting the HIGH level, the host device can initiate a dwm_status_get command to get the status from the DWM1001 device. Both dwm_int_cfg and dwm_status_get commands can be sent through SPI or UART schemes introduced in the previous sections.

DWM1001 notifies the host device of status changes, using a data ready GPIO pin

This GPIO pin level change will be postponed if the status change happens during the SPI TLV request/response procedure described above to avoid conflict. In detail, when the SPI is in status: “SPI: Wait for call_back”, “SPI: Wait for Read SIZE”, and “SPI: Wait for Read DATA/ERR”, the GPIO scheme will surrender the control of the GPIO pin. After the SPI communication, when the SPI is in the status “SPI: Idle”, the GPIO scheme will regain control of the GPIO pin.

---

API for on-module C code user application

Users can add their code and make use of the C code API functions in certain entry files provided in the onboard pack of pre-build firmware. In this way, users can add their own functions inside the module firmware and may not need to add an external host controller device.

Here are a few points the C code users should note when using the onboard firmware:

• User application is based on eCos RTOS and DWM libraries.

• Files used for linking with the user applications:

  • dwm.h - header file - wrapper for all header files necessary for building the user application

  • libdwm.a - static library

  • extras.o, vectors.o, libtarget.a - eCos static library

  • target_s132_fw1.ld - linker script for firmware section 1

  • target_s132_fw2.ld - linker script for firmware section 2

• The API provides functions and defines to the user application

  • Common functions on operating systems like thread creation, memory allocation, access to interfaces (e.g. GPIO, SPI, ..), and synchronization (mutex, signal).

  • Initialization, configuration, and maintenance of the DWM communication stack

  • Register of callbacks for incoming data and measurements.

  • The API will protect for the user application against incorrect settings that could influence system performance.

---

System specifications

Maximum user threads: 5

• RAM for the end user: cca TBD kB (TBD after D12, expected > 5KB)

• FLASH for the end user: cca TBD kB (TBD after D12, expected >= 40KB)

---

Peripheral used by PANS

The table below indicates the usage of all the peripherals used by the module. Note that the ones marked as blocked or restricted are being used by the firmware. Users can only make use of the “open” ones.

Interrupt vector	Peripheral	Instance	Description	Access
0	CLOCK	CLOCK	Clock control	restricted if BLE is enabled (can be accessed by SD API)
	POWER	POWER	Power control
	BPROT	BPROT	Block Protect
1	RADIO	RADIO	2.4 GHz	Blocked if BLE is enabled
2	UARTE	UARTE0	Universal Asynchronous Receiver/ Transmitter with EasyDMA	blocked if UART API is compiled
	UART	UART0	Universal Asynchronous Receiver/ Transmitter
3	SPIM	SPIM0	SPI master 0	open
	SPIS	SPIS0	SPI slave 0
	TWIM	TWIM0	Two-wire interface master 0
	TWI	TWI0	Two-wire interface master 0
	SPI	SPI0	SPI master 0
	TWIS	TWIS0	Two-wire interface slave 0
4	SPIM	SPIM1	SPI master 1	blocked
	TWI	TWI1	Two-wire interface master 1
	SPIS	SPIS1	SPI slave 1
	TWIS	TWIS1	Two-wire interface slave 1
	TWIM	TWIM1	Two-wire interface master 1
	SPI	SPI1	SPI master 1
5	NFCT	NFCT	Near Field Communication Tag	open
6	GPIOTE	GPIOTE	GPIO Tasks and CEvents	blocked
7	SAADC	SAADC	Analog to digital converter	open
8	TIMER	TIMER0	Timer 0	blocked
9	TIMER	TIMER1	Timer 1	blocked
10	TIMER	TIMER2	Timer 2	open
11	RTC	RTC0	Real-time counter 0	blocked
12	TEMP	TEMP	Temperature sensor	blocked
13	RNG	RNG	Random number generator	blocked
14	ECB	ECB	AES Electronic Code Book (ECB) mode block encryption	blocked
15	CCM	CCM	AES CCM Mode Encryption	restricted if BLE is enabled (can be accessed by SD API)
	AAR	AAR	Accelerated Address Resolver
16	WDT	WDT	Watchdog timer	blocked (timeout is 10 seconds)
17	RTC	RTC1	Real-time counter 1	blocked
18	QDEC	QDEC	Quadrature decoder	open
19	LPCOMP	LPCOMP	low-power comparator	open
	COMP	COMP	General purpose comparator	open
20	SWI	SWI0	Software interrupt 0	open
	EGU	EGU0	Event Generator Unit 0
21	EGU	EGU1	Event Generator Unit 1	blocked if BLE is enabled
	SWI	SWI1	Software interrupt 1
22	SWI	SWI2	Software interrupt 2	blocked if BLE is enabled
	EGU	EGU2	Event Generator Unit 2
23	SWI	SWI3	Software interrupt 3	open
	EGU	EGU3	Event Generator Unit 3
24	EGU	EGU4	Event Generator Unit 4
	SWI	SWI4	Software interrupt 4
25	SWI	SWI5	Software interrupt 5
	EGU	EGU5	Event Generator Unit 5
26	TIMER	TIMER3	Timer 3	open
27	TIMER	TIMER4	Timer 4	open
28	PWM	PWM0	Pulse Width Modulation Unit 0	open
29	PDM	PDM	Pulse Density Modulation (Digital Microphone Interface)	open
30	NVMC	NVMC	Non-Volatile Memory Controller	blocked
31	PPI	PPI	Programmable Peripheral Interconnect	blocked
32	MWU	MWU	Memory Watch Unit	restricted if BLE is enabled (can be accessed by SD API)
33	PWM	PWM1	Pulse Width Modulation Unit 1	open
34	PWM	PWM2	Pulse Width Modulation Unit 2	open
35	SPI	SPI2	SPI master 2	blocked if SPI API is compiled
	SPIS	SPIS2	SPI slave 2
	SPIM	SPIM2	SPI master 2
36	RTC	RTC2	Real-time counter 2	blocked
37	I2S	I2S	Inter-IC Sound Interface	open
38	FPU	FPU	FPU interrupt	open
0	GPIO	P0	General purpose input and output	blocked, users can access application pins via API
N/A	FICR	FICR	Factory Information Configuration	blocked
N/A	UICR	UICR	User Information Configuration	blocked

---

Onboard application use cases

1. Location engine improvements - is possible to retrieve distances between TN and ANs using user implemented location engine to compute position. Data offload is possible only via IoT data.

2. Sensor fusion - is possible to connect another sensor via SPI/I2C and improve location accuracy via sensor fusion (i.e. Kalman, etc…)

3. Sensor stations - reads some sensors (temperature, humidity, ect…) and reports their value via IoT.

4. Remote controller - sends a command via IoT to the node, which will respond with some activity (PWM change, LED blink, GPIO state change).

5. Data bridge - adds IoT/location services for externally attached MCU (i.e. robotic platform).

---

DWM1001 threads

In the DWM1001 firmware system, there are many threads, including SPI, BLE, UART, Generic API, User App and other threads. Each thread deals with specific tasks. The SPI, BLE, and UART threads control the data transmission with external devices. They don’t parse the requests they’ve received. All received requests are sent to the Generic API thread. The Generic API thread is a parser of the received requests. It judges whether the incoming request is valid. If valid, the firmware goes on to prepare the corresponding data as a response; if invalid, the firmware uses an error message as a response. Then, the Generic API thread runs the call_back() function, which sends the prepared response message back to the thread where the request comes from. The onboard user application thread is an independent thread for the users to add their own functionalities. The entrance is provided in the dwm\examples\ folder in the DWM1001 onboard package. An example project is given in dwmexamplesdwm-simplefolder.

---

Position Representation

In presenting locations and distances in a Real-Time Positioning System, there are two things to consider:

• Accuracy

• Precision

Accuracy is the error between the position reported by the nodes and the real position. Currently, the DW1000 used in this design provides approximately 10 cm accuracy. Precision is the value a least-significant bit (LSB) represents. In the onboard firmware of this system, the precision is 1 mm, i.e. 0.001 meter. The positions are presented in 3-dimensional coordinates (X, Y, Z), where X, Y, and Z are a 32-bit integer (4 bytes). Each LSB represents 1 mm. This is for easier interpretation of the value and easier mathematics over the reported values.

When deciding the precision, it is important to choose it with respect to accuracy to get a meaningful result. It is useless to show the user precise values if accuracy is low. The 1mm precision is too fine-grained with respect to the current 10 cm accuracy. Therefore, in presenting the location, a precision of 1 cm, i.e. 0.01 meter, is used. The updated value will be presented only when the coordinate/distance has changed over 1 cm. It is similar to rounding float/double values to a meaningful number of decimal places.