DWM1001 API Guide

dwm1001-api-guide

dwm1001-api-guide%20

dwm1001-api-guide

User Manual:

Open the PDF directly: View PDF .
Page Count: 74

Download
Open PDF In Browser	View PDF

DWM1001 FIRMWARE API GUIDE

DWM1001 FIRMWARE
APPLICATION
PROGRAMMING
INTERFACE (API) GUIDE
USING API FUNCTIONS TO
CONFIGURE AND PROGRAMME
DWM1001 MODULE

This document is subject to change without notice

SW-DWM1001-API-Guide-1.0

Page 1 of 74

DW1001 Firmware API Guide

TABLE OF CONTENTS
DISCLAIMER ................................................................................................................................................ 7
1

INTRODUCTION AND OVERVIEW ........................................................................................................... 10
1.1
1.2

DWM1001 MODULE AND THE FIRMWARE ................................................................................................... 10
API AND ITS GUIDE ................................................................................................................................... 10

GENERAL API DESCRIPTIONS ................................................................................................................. 11
2.1
EXTERNAL INTERFACE USAGE ...................................................................................................................... 11
2.2
LOW POWER MODE WAKE-UP MECHANISM ................................................................................................... 11
2.3
TLV FORMAT........................................................................................................................................... 11
2.4
DWM1001 THREADS .............................................................................................................................. 11
2.5
API VIA BLE INTERFACE............................................................................................................................. 12
2.6
API VIA SPI INTERFACE ............................................................................................................................. 12
2.6.1 DWM1001 SPI overview .................................................................................................................. 12
2.6.2 SPI Scheme: normal TLV communication ........................................................................................ 15
2.6.3 SPI Example: normal TLV communication - dwm_gpio_cfg_output .............................................. 16
2.6.4 SPI Scheme: TLV communication using data ready pin................................................................... 17
2.6.5 SPI error recovery mechanism ........................................................................................................ 18
2.7
API VIA UART INTERFACE ......................................................................................................................... 19
2.7.1 DWM1001 UART overview.............................................................................................................. 19
2.7.2 UART TLV Mode .............................................................................................................................. 19
2.7.3 UART scheme: TLV mode communication ...................................................................................... 20
2.7.4 UART example: TLV mode communication ..................................................................................... 21
2.7.5 UART scheme: Shell mode communication ..................................................................................... 21
2.7.6 UART example: Shell Mode communication ................................................................................... 22
2.8
GPIO SCHEME: DWM1001 NOTIFIES FOR STATUS CHANGE ............................................................................ 22
2.9
API FOR ON-BOARD C CODE DEVELOPERS ..................................................................................................... 23

GENERIC API INFORMATION .................................................................................................................. 24
3.1
USED TERMINOLOGY ................................................................................................................................. 24
3.2
LITTLE ENDIAN ......................................................................................................................................... 24
3.3
FIRMWARE UPDATE .................................................................................................................................. 24
3.4
FREQUENTLY USED TLV VALUES .................................................................................................................. 25
3.4.1 err_code .......................................................................................................................................... 25
3.4.2 position ........................................................................................................................................... 25
3.4.3 gpio_idx .......................................................................................................................................... 25
3.4.4 gpio_value ...................................................................................................................................... 25
3.4.5 gpio_pull ......................................................................................................................................... 26
3.4.6 fw_version....................................................................................................................................... 26
3.4.7 cfg_tag ............................................................................................................................................ 26
3.4.8 cfg_anchor ...................................................................................................................................... 26
3.4.9 cfg_node ......................................................................................................................................... 27

API FUNCTION DESCRIPTIONS ............................................................................................................... 28
4.1
4.2
4.3

LIST OF API FUNCTIONS ............................................................................................................................. 28
USAGE OF THE APIS ................................................................................................................................. 29
DETAILS OF THE API FUNCTIONS ................................................................................................................. 29

SW-DWM1001-API-Guide-1.0

Page 2 of 74

DW1001 Firmware API Guide
4.3.1
4.3.2
4.3.3
4.3.4
4.3.5
4.3.6
4.3.7
4.3.8
4.3.9
4.3.10
4.3.11
4.3.12
4.3.13
4.3.14
4.3.15
4.3.16
4.3.17
4.3.18
4.3.19
4.3.20
4.3.21
4.3.22
4.3.23
4.3.24
4.3.25
5

dwm_pos_set .................................................................................................................................. 30
dwm_pos_get ................................................................................................................................. 31
dwm_upd_rate_set ......................................................................................................................... 32
dwm_upd_rate_get ........................................................................................................................ 33
dwm_cfg_tag_set ........................................................................................................................... 34
dwm_cfg_anchor_set ..................................................................................................................... 36
dwm_cfg_get .................................................................................................................................. 37
dwm_sleep ...................................................................................................................................... 39
dwm_loc_get .................................................................................................................................. 40
dwm_baddr_set.......................................................................................................................... 42
dwm_baddr_get ......................................................................................................................... 43
dwm_reset .................................................................................................................................. 44
dwm_ver_get.............................................................................................................................. 45
dwm_gpio_cfg_output ............................................................................................................... 46
dwm_gpio_cfg_input.................................................................................................................. 47
dwm_gpio_value_set ................................................................................................................. 48
dwm_gpio_value_get ................................................................................................................. 49
dwm_gpio_value_toggle ............................................................................................................ 50
dwm_status_get ......................................................................................................................... 51
dwm_int_cfg ............................................................................................................................... 52
dwm_gpio_irq_cfg ...................................................................................................................... 53
dwm_gpio_irq_dis ...................................................................................................................... 54
dwm_i2c_read ............................................................................................................................ 55
dwm_i2c_write ........................................................................................................................... 56
dwm_evt_cb_register ................................................................................................................. 57

SHELL COMMANDS ................................................................................................................................ 59
5.1
5.2
5.3
5.4
5.5
5.6
5.7
5.8
5.9
5.10
5.11
5.12
5.13
5.14
5.15
5.16
5.17
5.18
5.19
5.20
5.21
5.22
5.23

USAGE OF UART SHELL MODE ................................................................................................................... 59
? ........................................................................................................................................................... 59
HELP ...................................................................................................................................................... 60
QUIT ...................................................................................................................................................... 60
GC ......................................................................................................................................................... 60
GG ........................................................................................................................................................ 61
GS ......................................................................................................................................................... 61
GT ......................................................................................................................................................... 61
F ........................................................................................................................................................... 61
PS ......................................................................................................................................................... 61
PMS ....................................................................................................................................................... 62
RESET ..................................................................................................................................................... 62
UT ......................................................................................................................................................... 62
FRST ...................................................................................................................................................... 62
TWI ....................................................................................................................................................... 62
AID ........................................................................................................................................................ 63
AV ......................................................................................................................................................... 63
LES ........................................................................................................................................................ 63
LEC ........................................................................................................................................................ 63
LEP ........................................................................................................................................................ 63
SI .......................................................................................................................................................... 64
NMG ...................................................................................................................................................... 64
NMO...................................................................................................................................................... 64

SW-DWM1001-API-Guide-1.0

Page 3 of 74

DW1001 Firmware API Guide
5.24
5.25
5.26
5.27
5.28
5.29
5.30
5.31
5.32
5.33
5.34
5.35
5.36
5.37
5.38
5.39

NMP ...................................................................................................................................................... 65
NMA ...................................................................................................................................................... 65
NMI ....................................................................................................................................................... 66
NMT ...................................................................................................................................................... 66
NMTL ..................................................................................................................................................... 67
BPC ....................................................................................................................................................... 67
LA ......................................................................................................................................................... 67
STG ....................................................................................................................................................... 68
STC ........................................................................................................................................................ 69
TLV ........................................................................................................................................................ 69
AURS ..................................................................................................................................................... 69
AURG ..................................................................................................................................................... 69
APG ....................................................................................................................................................... 70
APS........................................................................................................................................................ 70
ACAS ...................................................................................................................................................... 70
ACTS ...................................................................................................................................................... 70

APPENDIX A – TLV TYPE LIST .................................................................................................................. 71

APPENDIX B – BIBLIOGRAPHY................................................................................................................ 72

DOCUMENT HISTORY ............................................................................................................................ 73

ABOUT DECAWAVE ............................................................................................................................... 74

SW-DWM1001-API-Guide-1.0

Page 4 of 74

DW1001 Firmware API Guide

List of Tables
TABLE 1 TLV FORMAT DATA EXAMPLE ........................................................................................................................... 11
TABLE 2 API REQUEST FUNCTION LIST ............................................................................................................................ 28
TABLE 3 API EXAMPLES LOCATION ................................................................................................................................ 29
TABLE 4 DWM1001 TLV TYPE LIST ............................................................................................................................. 71
TABLE 5: DOCUMENT HISTORY..................................................................................................................................... 73

List of Figures
FIGURE 1 DWM1001 SPI WORK FLOW ........................................................................................................................ 13
FIGURE 2 SPI SCHEME: NORMAL TLV COMMUNICATION ................................................................................................... 15
FIGURE 3 SPI EXAMPLE: NORMAL TLV COMMUNICATION .................................................................................................. 16
FIGURE 4 SPI SCHEME: TLV COMMUNICATION USING DATA READY PIN ................................................................................ 17
FIGURE 5 DWM1001 UART WORK FLOW .................................................................................................................... 19
FIGURE 6 UART SCHEME: TLV MODE COMMUNICATION .................................................................................................. 20
FIGURE 7 UART EXAMPLE: TLV MODE COMMUNICATION ................................................................................................. 21
FIGURE 8 UART SCHEME: SHELL MODE COMMUNICATION ................................................................................................ 22
FIGURE 9 UART EXAMPLE: SHELL MODE COMMUNICATION ............................................................................................... 22
FIGURE 10 GPIO SCHEME: DWM1001 NOTIFIES HOST DEVICE OF STATUS CHANGE, USING GPIO............................................ 23

SW-DWM1001-API-Guide-1.0

Page 5 of 74

DW1001 Firmware API Guide
DOCUMENT INFORMATION
Disclaimer
Decawave reserves the right to change product specifications without notice. As far as possible changes to
functionality and specifications will be issued in product specific errata sheets or in new versions of this
document. Customers are advised to check the Decawave website for the most recent updates on this
product
Copyright © 2017 Decawave Ltd

LIFE SUPPORT POLICY
Decawave products are not authorized for use in safety-critical applications (such as life support) where a
failure of the Decawave product would reasonably be expected to cause severe personal injury or death.
Decawave customers using or selling Decawave products in such a manner do so entirely at their own risk
and agree to fully indemnify Decawave and its representatives against any damages arising out of the use of
Decawave products in such safety-critical applications.
Caution! ESD sensitive device.
Precaution should be used when handling the device in order to prevent permanent damage

SW-DWM1001-API-Guide-1.0

Page 6 of 74

DW1001 Firmware API Guide

DISCLAIMER
(1)

This Disclaimer applies to the software provided by Decawave Ltd. (“Decawave”) in
support of its DWM1001 module product (“Module”) all as set out at clause 3 herein
(“Decawave Software”).

(2)

Decawave Software is provided in two ways as follows: (a)
pre-loaded onto the Module at time of manufacture by Decawave (“Firmware”);
(b)
supplied separately by Decawave (“Software Bundle”).

(3)

Decawave Software consists of the following components (a) to (d) inclusive:

(4)

(a)

The Decawave Positioning and Networking Stack (“PANS”), available as a
library accompanied by source code that allows a level of user customisation.
The PANS software is pre-installed and runs on the Module as supplied, and
enables mobile “tags”, fixed “anchors” and “gateways” that together deliver the
DWM1001 Two-Way-Ranging Real Time Location System (“DRTLS”)
Network.

(b)

The Decawave DRTLS Manager which is an Android™ application for
configuration of DRTLS nodes (nodes based on the Module) over Bluetooth™.

(c)

The Decawave DRTLS Gateway Application which supplies a gateway
function (on a Raspberry Pi ®) routing DRTLS location and sensor data traffic
onto an IP based network (e.g. LAN), and consists of the following components:
 DRTLS Gateway Linux Kernel Module
 DRTLS Gateway Daemon
 DRTLS Gateway MQTT Broker
 DRTLS Gateway Web Manager

(d)

Example Host API functions, also designed to run on a Raspberry Pi, which
show how to drive the Module from an external host microprocessor.

The following third party components are used by Decawave Software and are
incorporated in the Firmware or included in the Software Bundle as the case may be: (a)

The PANS software incorporates the Nordic SoftDevice S132-SD-v3 version
3.0.0 (production) which is included in the Firmware and is also included in the
Software Bundle;

(b)

The PANS software uses the eCos RTOS which is included in the Software
Bundle. The eCos RTOS is provided under the terms of an open source licence
which may be found at: http://ecos.sourceware.org/license-overview.html;

(c)

The PANS software uses an open source CRC-32 function from FreeBSD which
is included in the Software Bundle. This CRC-32 function is provided under the
terms
of
the
BSD
licence
which
may
be
found
at:
https://github.com/freebsd/freebsd/blob/386ddae58459341ec56760470780581
4a2128a57/COPYRIGHT;

SW-DWM1001-API-Guide-1.0

Page 7 of 74

DW1001 Firmware API Guide

(d)

The Decawave DRTLS Manager application uses open source software which
is provided as source code in the Software Bundle. This open source software
is provided under the terms of the Apache Licence v2.0 which may be found at
http://www.apache.org/licenses/LICENSE-2.0;

(e)

The Decawave DRTLS Gateway Application uses the following third party
components: (i)
The Linux Kernel which is provided as source code in the Software
Bundle. The Linux Kernel is provided under the terms of the GPLv2
licence which may be found at: https://www.gnu.org/licenses/oldlicenses/gpl-2.0.en.html and as such the DWM1001 driver component
of the DRTLS Gateway Application is provided under the same license
terms;
(ii)
The three.js JavaScript library, the downloadable version of which is
available here https://threejs.org/, is provided under the terms of the MIT
Licence which may be found at https://opensource.org/licenses/MIT.

Items (a), (b), (c), (d) and (e) in this section 4 are collectively referred to as the “Third
Party Software”
(5)

Decawave Software incorporates source code licensed to Decawave by Leaps s.r.o., a
supplier to Decawave, which is included in the Firmware and the Software Bundle in
binary and/or source code forms as the case may be, under the terms of a license
agreement entered into between Decawave and Leaps s.r.o.

(6)

Decawave hereby grants you a free, non-exclusive, non-transferable, worldwide license
without the right to sub-license to design, make, have made, market, sell, have sold or
otherwise dispose of products incorporating Decawave Software, to modify Decawave
Software or incorporate Decawave Software in other software and to design, make,
have made, market, sell, have sold or otherwise dispose of products incorporating such
modified or incorporated software PROVIDED ALWAYS that the use by you of Third
Party Software as supplied by Decawave is subject to the terms and conditions of the
respective license agreements as set out at clause 4 herein AND PROVIDED ALWAYS
that Decawave Software is used only in systems and products based on Decawave
semiconductor products. NO OTHER LICENSE, EXPRESS OR IMPLIED, BY
ESTOPPEL OR OTHERWISE TO ANY OTHER DECAWAVE INTELLECTUAL
PROPERTY RIGHT, AND NO LICENSE TO ANY THIRD PARTY TECHNOLOGY
OR INTELLECTUAL PROPERTY RIGHT, IS GRANTED HEREIN, including but
not limited to any patent right, copyright, mask work right, or other intellectual property
right relating to any combination, machine, or process in which Decawave
semiconductor products or Decawave Software are used.

(7)

Downloading, accepting delivery of or using Decawave Software indicates your
agreement to the terms of (i) the license grated at clause 6 herein, (ii) the terms of this
Disclaimer and (iii) the terms attaching to the Third Party Software. If you do not agree
with all of these terms do not download, accept delivery of or use Decawave Software.

(8)

Decawave Software is solely intended to assist you in developing systems that
incorporate Decawave semiconductor products. You understand and agree that you
remain responsible for using your independent analysis, evaluation and judgment in

SW-DWM1001-API-Guide-1.0

Page 8 of 74

DW1001 Firmware API Guide

designing your systems and products. THE DECISION TO USE DECAWAVE
SOFTWARE IN WHOLE OR IN PART IN YOUR SYSTEMS AND PRODUCTS
RESTS ENTIRELY WITH YOU AND DECAWAVE ACCEPTS NO LIABILTY
WHATSOEVER FOR SUCH DECISION.
(9)

DECAWAVE SOFTWARE IS PROVIDED "AS IS". DECAWAVE MAKES NO
WARRANTIES OR REPRESENTATIONS WITH REGARD TO DECAWAVE
SOFTWARE OR USE OF DECAWAVE SOFTWARE, EXPRESS, IMPLIED OR
STATUTORY, INCLUDING ACCURACY OR COMPLETENESS. DECAWAVE
DISCLAIMS ANY WARRANTY OF TITLE AND ANY IMPLIED WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF ANY THIRD PARTY INTELLECTUAL PROPERTY
RIGHTS WITH REGARD TO DECAWAVE SOFTWARE OR THE USE THEREOF.

(10)

DECAWAVE SHALL NOT BE LIABLE FOR AND SHALL NOT DEFEND OR
INDEMNIFY YOU AGAINST ANY THIRD PARTY INFRINGEMENT CLAIM
THAT RELATES TO OR IS BASED ON DECAWAVE SOFTWARE OR THE USE
OF DECAWAVE SOFTWARE. IN NO EVENT SHALL DECAWAVE BE LIABLE
FOR ANY ACTUAL, SPECIAL, INCIDENTAL, CONSEQUENTIAL OR
INDIRECT DAMAGES, HOWEVER CAUSED, INCLUDING WITHOUT
LIMITATION TO THE GENERALITY OF THE FOREGOING, LOSS OF
ANTICIPATED PROFITS, GOODWILL, REPUTATION, BUSINESS RECEIPTS
OR CONTRACTS, COSTS OF PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION), LOSSES OR EXPENSES RESULTING FROM THIRD PARTY
CLAIMS. THESE LIMITATIONS WILL APPLY REGARDLESS OF THE FORM
OF ACTION, WHETHER UNDER STATUTE, IN CONTRACT OR TORT
INCLUDING NEGLIGENCE OR ANY OTHER FORM OF ACTION AND
WHETHER OR NOT DECAWAVE HAS BEEN ADVISED OF THE POSSIBILITY
OF SUCH DAMAGES, ARISING IN ANY WAY OUT OF DECAWAVE
SOFTWARE OR THE USE OF DECAWAVE SOFTWARE.

(11)

You acknowledge and agree that you are solely responsible for compliance with all
legal, regulatory and safety-related requirements concerning your products, and any use
of Decawave Software in your applications, notwithstanding any applications-related
information or support that may be provided by Decawave.

(12)

Decawave reserves the right to make corrections, enhancements, improvements and
other changes to its software, including Decawave Software, at any time.

Mailing address:

Decawave Ltd.,
Adelaide Chambers,
Peter Street,
Dublin D08 T6YA
IRELAND.

Copyright (c) 15 November 2017 by Decawave Limited. All rights reserved. All trademarks
are the property of their respective owners.

SW-DWM1001-API-Guide-1.0

Page 9 of 74

DW1001 Firmware API Guide

1 INTRODUCTION AND OVERVIEW
1.1

DWM1001 module and the firmware

The DWM1001 module is a radio transceiver module integrating the Nordic Semiconductor nRF52
MCU and Decawave’s DW1000 IC. The nRF52 MCU, which has Bluetooth v4.2 protocol stack
implemented [1], is acting as the main processor of the DWM1001 module. The DW1000 IC part,
which has the UWB physical layer defined in IEEE 802.15.4-2011 standard [2], is acting as the UWB
radio module controlled by the nRF52 MCU.
Decawave provides a pre-built firmware library, the “Positioning and Networking stack” (PANS) library,
in the DWM1001 module which runs on the nRF52 MCU. The firmware provides the Application
Programming Interface (API) for users to use their own host devices to communicate with the
DWM1001 module, namely the PANS API. The PANS API essentially is a set of functions providing a
means to communicate with the nRF52 MCU to drive the module through the PANS library on
application level without having to deal with the details of accessing the DW1000 IC part and other
peripherals directly through its SPI/I2C interface register set. The detailed information of the firmware
is introduced in the DWM1001 Firmware User Guide [3].

1.2

API and its guide

The PANS APIs are a set of functions. Each individual API function may be accessed through various
communication interfaces providing flexibility to developers in using the DWM1001 module and
integrating it into their systems. The API accesses mainly come in as two types:
1) External access API: via UART, SPI and BLE.
2) Integrated access API: via on-board user app (C code).
The detailed introduction to the flow with examples of how the API can be used is introduced in [3].
This document, “DWM1001 API Guide”, specifies the PANS API functions themselves, providing
descriptions of each of the API functions in detail in terms of its parameters, functionality and utility.
Users can use the PANS API to configure each individual DWM1001 module. To setup a location
system with multiple DWM1001 modules, users should refer to the DWM1001 System Guide [4].
This document relates to:

"DWM1001 PANS Library Version 1.1.5"

SW-DWM1001-API-Guide-1.0

Page 10 of 74

DW1001 Firmware API Guide

2 GENERAL API DESCRIPTIONS
2.1

External Interface usage

The external interfaces, including the UART, the SPI and the BLE, are used by the external APIs in the
PANS library for Host connection. The on-board user application through C code API cannot make
use of the external interfaces due to compatibility reasons.

2.2

Low power mode wake-up mechanism

As provided in the PANS library, the DWM1001 module can work in a low power mode. In the low
power mode, the module puts the API related threads into “sleep” state when the API is not
currently being communicated by host devices. In this case, the host device needs to wake up the
module through external interfaces before the real communication can start.
For UART interface, the host device needs to send a single byte first to wake up the module.
For SPI interface, putting the chip select pin to low level wakes up the module, i.e. no extra
transmission is needed.
After the API transmission has finished, the host device needs to put the module back to “sleep”
state to save power, as introduced in section 4.3.8 and section 5.4.

2.3

TLV format

TLV format, the Type-Length-Value encoding, is used in the DWM1001 module API. Data in TLV
format always begins with the type byte, followed by the length byte, and then followed by a
variable number of value bytes [0 to 253] as specified by the length byte. Table 1 shows an example
of TLV format data, in which the type byte is 0x28, the length byte is 0x02, and as declared by the
length byte, the value field is of two bytes: 0x0D and 0x01.
In DWM1001 firmware, both SPI and UART APIs use TLV format for data transmission. Users should
refer to the type list for the meaning of type bytes (see Section 6). And for each specific command or
response, the value field is of different length to provide the corresponding information.
Table 1 TLV format data example
TLV request
Type

0x28

2.4

Length

0x02

Value
gpio_idx

gpio_value

0x0d

0x01

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:
© Decawave Ltd 2017

SW-DWM1001-API-Guide-1.0

Page 11 of 74

DW1001 Firmware API Guide
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 response; if invalid, the
firmware uses error message as 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 on-board user application thread is an independent thread for the users to add their own
functionalities. The entrance is provided in the dwm\example\ folder in the DWM1001 on-board
package. An example project is given in dwm\example\dwm-simple\ folder.

2.5

API via BLE interface

This is described in DWM1001-Bletooth-API document.

2.6

API via SPI interface

2.6.1

DWM1001 SPI overview

DWM1001 SPI interface uses TLV format data. Users can use an external host device in SPI master
mode to connect to the DWM1001 module SPI interface which operates in slave mode. The
maximum SPI clock frequency is 8 MHz. (This is maximum supported by the nRF52 MCU)
In the DWM1001 SPI schemes, host device communicates with the DWM1001 through TLV requests.
A full TLV request communication flow includes the following steps:
1)
2)
3)
4)

Host device sends TLV request;
DWM1001 prepares response;
Host device reads the length of total response;
Host device reads data response;

Because SPI uses full duplex communication, when the host device (as the SPI master) writes x bytes,
it actually sends x bytes to the DWM1001 module (as the slave), and receives x bytes dummy in the
same time. Similarly for reading, the host device sends x bytes of dummy, and receives x bytes data
back as response. In the DWM1001 SPI scheme, the dummy bytes are octets of value 0xFF.

SW-DWM1001-API-Guide-1.0

Page 12 of 74

DW1001 Firmware API Guide

SPI thread

Generic API thread

Init SPI as Slave
Read
DATA/ERR

API: Idle

Received
TLV request

SPI:Idle

TLV
request
TLV valid?

SPI: Wait for
Read DATA/ERR

Yes

SPI: Wait for
call_back()

Receive
any byte
Read SIZE

System status

SPI: Wait for
Read SIZE

Prepare
SIZE & DATA

call_back()

System activity

Prepare
SIZE & ERR

call_back()

User activity

Figure 1 DWM1001 SPI work flow

As shown in Figure 1, the DWM1001 SPI thread transfers between four states in serial. Each state
will transfer to its next corresponding state on certain events.
- SPI: Idle: the state after initialization and after each successful data transmission/response.
In this state, any received data is assumed to be a TLV request. Thus, on receiving any data,
the SPI thread in the firmware passes the received data to the Generic API. The Generic API
parses the TLV requests and prepares the return data.
o Waiting for event: receiving TLV requests.
o Action on event – if Type==0xFF:
 No action, stay in SPI: Idle. See Section 2.6.5 for more details.
o Action on event – if Type≠0xFF :
 Send received TLV request to Generic API thread.
 Transfer to “SPI: Wait for call_back”.
- SPI: Wait for call_back: the DWM1001 SPI is waiting for the Generic API to parse the TLV
request and prepare the response. Any data from the host side will be ignored and returned
with 0x00 in this state.
o Waiting for event: call_back() function being called by the Generic API.
o Action on event:
 Toggle data ready pin HIGH – detailed in Section 2.6.4.
 Transfer to “SPI: Wait for READ SIZE”.
- SPI: Wait for Read SIZE: the DWM1001 SPI has prepared the SIZE byte as response, which is
only one byte non-zero data indicating the size of data or error message to be responded,
and is waiting for the host device to read the SIZE byte.
o Waiting for event: host device reads one byte.
o Action on event:
 Respond with the SIZE byte.
 Transfer to “SPI: Wait for READ DATA/ERR”.
- SPI: Wait for Read DATA/ERR: the DWM1001 SPI has prepared SIZE bytes of data or error
message as response to the TLV request, and is waiting for the host device to read it.
o Waiting for event: host device reads any number of bytes.
© Decawave Ltd 2017

SW-DWM1001-API-Guide-1.0

Page 13 of 74

DW1001 Firmware API Guide
o

Action on event:
 Respond with DATA/ERR.
 Toggle data ready pin LOW – detailed in Section 2.6.4.
 Transfer to “SPI: Idle”.

In DWM1001, starting from “SPI: Idle”, traversing all four states listed above and returning to “SPI:
Idle” indicates a full TLV request communication flow. The user should have received the response
data or error message by the end of the communication flow.
A few different usages and examples are illustrated in the following sub-sections.

SW-DWM1001-API-Guide-1.0

Page 14 of 74

DW1001 Firmware API Guide
2.6.2

SPI Scheme: normal TLV communication

Figure 2 shows the normal communication flow of a host device writing/reading information to/from
the DWM1001 module:
1) Host device sends the request in TLV format.
2) Host device reads the SIZE byte, indicating the number of bytes ready to be read.
a. On receiving SIZE= 0, meaning the response is not ready yet, repeat step 2).
b. On receiving SIZE > 0, meaning the response is ready, go to step 3)
3) Host device reads SIZE bytes data response in TLV format.

Figure 2 SPI scheme: normal TLV communication

SW-DWM1001-API-Guide-1.0

Page 15 of 74

DW1001 Firmware API Guide
2.6.3

SPI Example: normal TLV communication - dwm_gpio_cfg_output

Figure 3 illustrates an example of host device writing the dwm_gpio_cfg_output TLV request to set
pin 13 level HIGH ([0x28, 0x02, 0x0D, 0x01] in byte array, detailed in Section 4.3.14) and reading the
response from the DWM1001 module.
The communication flow of the transmission and response includes:
1) Host device writes the dwm_gpio_cfg_output command to set pin 13 level HIGH in TLV
format, 4 bytes in total:
Type = 0x28, length = 0x02, value = 0x0D 0x01.
2) Host device reads the SIZE byte, and receives SIZE = 0: the response is not ready yet. Repeat
to read the SIZE byte.
3) Host device reads the SIZE byte again, and receives SIZE = 3: the response is ready. Proceed
to read 3 bytes response data.
4) Host device reads the 3-byte TLV format data:
Type = 0x40, Length = 0x01, value = 0x00,
where Type = 0x40 indicates this is a return message (see Section 6), Length = 0x01 indicates
that there is one byte following as data, value = 0x00 indicates the TLV request is parsed
correctly.

Figure 3 SPI example: normal TLV communication

SW-DWM1001-API-Guide-1.0

Page 16 of 74

DW1001 Firmware API Guide
2.6.4

SPI Scheme: TLV communication using data ready pin

Similar to the scheme described in Section 2.6.2, users can setup the data ready pin (GPIO P0.26)
from the DWM1001 to indicate when data is ready, instead of the master polling multiple times to
check the response status. When the data ready function is setup, the data ready pin will be set to
LOW level when there’s no data to be read; when the response SIZE and data is ready to be read, the
data ready pin will be set to HIGH level during states “SPI: Wait for Read SIZE” and “SPI: Wait for
Read DATA/ERR”. Thus, the users can use the data ready pin either as an interrupt or as a status pin.
To setup data ready pin for SPI scheme, users need to use dwm_int_cfg TLV request through SPI
Scheme: normal TLV communication introduced in Section 2.6.2. The detail of dwm_int_cfg request
is introduced in Section 4.3.14.
The communication flow of this scheme is illustrated in Figure 4.
1)
2)
3)
4)
5)

Setup the SPI interrupt.
Host device writes the request in TLV format.
Host device waits until the data ready pin on DWM1001 to go HIGH.
Host device reads the SIZE byte.
Host device reads SIZE bytes data response in TLV format

Figure 4 SPI scheme: TLV communication using data ready pin

As can be seen from the steps, this scheme is using the data ready pin on the DWM1001 to indicate
the host device when the response data is ready. This makes the host device less busy in reading
SIZE byte.

SW-DWM1001-API-Guide-1.0

Page 17 of 74

DW1001 Firmware API Guide
2.6.5

SPI error recovery mechanism

2.6.5.1 SPI data doesn’t allow partial transmission

When reading data from the DWM1001 module, if the host device doesn’t read all bytes of data in
one transmission, the reading operation will still be considered as done. The rest of the response will
be abandoned. For example, in “SPI: Wait for Read DATA/ERR” state, the DWM1001 module has
prepared SIZE bytes of response data and expects the host device to read all SIZE bytes of the
response. However, if the host device only reads part of the data, the DWM1001 module will drop
the rest of the data, and transfers to the next state: “SPI: IDLE”.
2.6.5.2 SPI state recovery: type_nop message

The DWM1001 SPI has a special Type value 0xFF, called type_nop. A TLV data message with
type_nop means no operation. In “SPI: IDLE” state, when the DWM1001 SPI receives a message and
finds the type byte is 0xFF, it will not perform any operation, including sending the TLV data message
to the Generic API thread.
The type_nop is designed for error recovery. If the host device is not sure what state the DWM1001
SPI is in, it can make use of the SPI response and the non-partial transmission mechanism, and reset
the DWM1001 SPI to “SPI: IDLE” state by sending three 0xFF dummy bytes, each in a single
transmission. After the three transmissions, the response data from the DWM1001 SPI will become
all dummy bytes of value 0xFF, indicating that the DWM1001 SPI is in “SPI: IDLE” state.

SW-DWM1001-API-Guide-1.0

Page 18 of 74

DW1001 Firmware API Guide

2.7

API via UART interface

2.7.1

DWM1001 UART overview

Users can use an external host device to connect to the DWM1001 module through UART interface
at baud rate 115200. Figure 5 shows the work flow of the DWM1001 UART interface. In the UART
Generic mode communication, the host device is acting as the initiator, while the DWM1001 module
is the responder.
DWM1001 UART provides two modes: the UART Generic mode, commands introduced in Section 4,
and the UART Shell mode, commands introduced in Section 5. The default mode of the DWM1001
UART is Generic mode. However, the two modes are transferrable:
Generic mode to Shell mode: press “Enter” twice or input two bytes [0x0D, 0x0D] within one second.
If the module is in “sleep” state in low power mode as introduced in Section 2.2, an extra byte will
be needed before the double “Enter”. E.g. pressing “Enter” three times will wake up the module and
transfer it to Shell mode.
Shell mode to Generic mode: users need to input “quit” command.
UART thread
Received
double “Enter”

Generic API thread

Received
TLV request

API:Idle
TLV request

Shell mode

UART:Receiving

UART:Finished

quit cmd

call_back()

UART:Idle

Prepare data
response

Prepare error
message

call_back()

Init UART
System status

Yes

Received
any byte

Shell cmd

TLV good?

System activity

User activity

Figure 5 DWM1001 UART work flow

2.7.2

UART TLV Mode

UART TLV mode uses TLV format data. In this mode, host device and the DWM1001 module
communicate using TLV requests/responses. A full TLV request communication flow includes the
following steps:
1) Host device sends TLV request;
2) DWM1001 responds with TLV data.
On receiving any data, the UART starts a delay timer for the following data. If there is new data
coming in within a delay period, specifically 25 clock cycles (25/32768 second ≈ 763 µs), the UART
starts the delay timer and waits for new data. If there’s no new data coming in within the delay
period, the delay timer will expire. The UART then sends the received data to the Generic API thread
and waits for it to return the response data or error message.
© Decawave Ltd 2017

SW-DWM1001-API-Guide-1.0

Page 19 of 74

DW1001 Firmware API Guide
As shown in Figure 5, the DWM1001 UART TLV mode thread transfers between three states in serial:
“UART: Idle”, “UART: Receiving” and “UART: Finished”. Each state will transfer to its next
corresponding state on certain events.
-

2.7.3

UART: Idle: is the state after initialization and after each successful TLV response. In this
state, the UART is only expecting one byte as the start of the TLV request or the double
“Enter” command.
o Waiting for event: receiving TLV requests.
o Action on event:
 Start the delay timer.
 Transfer to UART: Receiving.
UART: Receiving: is the state waiting for end of the incoming request. On receiving any data
in this state, the UART will refresh the delay timer. If the host device has finished sending
bytes, the delay timer will expire.
o Waiting for event: delay period timed out.
o Action on event - if received request is double “Enter”:
 Transfer to UART Shell mode.
o Action on event - if received request is not double “Enter”:
 Send received request to Generic API thread.
 Transfer to UART: Finished.
UART: Finished: is the state waiting for the Generic API thread to parse the incoming
request and send the response data or error message back to UART thread.
o Waiting for event: call_back() function called by the Generic API thread.
o Action on event:
 Send the response data or error message to host device.
 Transfer to UART: Idle.
UART scheme: TLV mode communication

The UART communication in TLV mode is illustrated in Figure 6, steps described as below:
1) The host device sends a request in TLV format;
2) The DWM1001 module responds with a message in TLV format.

Figure 6 UART scheme: TLV mode communication

SW-DWM1001-API-Guide-1.0

Page 20 of 74

DW1001 Firmware API Guide
2.7.4

UART example: TLV mode communication

Figure 7 illustrates an example of host device sending the dwm_gpio_cfg_output command to set
pin 13 level HIGH ([0x28, 0x02, 0x0D, 0x01] in byte array, detailed in Section 4.3.14) and receiving
the response from the DWM1001 module using the UART API in TLV mode. The steps of the
communication flow are:
1) The host device sends the dwm_gpio_cfg_output command in TLV format:
Type = 0x28, Length = 0x02, Value = 0x0D 0x01.
2) The DWM1001 module responds in TLV format:
Type = 0x40, Length = 0x01, value = 0x00,
where Type = 0x40 indicates this is a return message (see Section 6), Length = 0x01 indicates
that there is one byte following as data, value = 0x00 indicates the TLV request is parsed
correctly.

Figure 7 UART example: TLV mode communication

2.7.5

UART scheme: Shell mode communication

UART Shell mode provides prompt and uses Shell commands. The UART Shell mode intends to
provide users with human readable access to the APIs, thus, all Shell commands are strings of letters
followed by a character return, i.e. “Enter”. Users can input the string directly through keyboard and
press “Enter” to send the Shell commands. DWM1001 UART stays in the Shell mode after each Shell
commands except for the “quit” command.
As illustrated in Figure 8, a full Shell command communication flow includes the following steps:
1) Host device sends the Shell command + “Enter” to the DWM1001.
2) If there’s any message to respond, the DWM1001 sends the message to the host device.
3) If there’s nothing to respond, the DWM1001 doesn’t send anything and keeps quiet.

SW-DWM1001-API-Guide-1.0

Page 21 of 74

DW1001 Firmware API Guide

Figure 8 UART scheme: Shell mode communication

2.7.6

UART example: Shell Mode communication

Figure 9 illustrates an example of host device sending the “GPIO set” command using UART Shell to
set pin 13 level HIGH (“gs 13” in byte array, followed by “Enter” key, detailed in Section 5.7). The
steps of the communication flow are:
1) The host device sends the “GPIO set” command in Shell mode: “gs 13” + “Enter”.
2) The DWM1001 responds the host with string “gpio13: 1”.

Figure 9 UART example: Shell mode communication

2.8

GPIO Scheme: DWM1001 notifies for status change

Rather than the host device initiating the SPI/UART communication, the DWM1001 module can send
notifications of status change by toggling the dedicated GPIO pin (P0.26) to HIGH level, as illustrated
in Figure 10. To enable this feature, host device needs to use the dwm_int_cfg command, detailed in
Section 4.3.14. On detecting the HIGH level, host device can initiate a dwm_status_get command,
detailed in Section 0, 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.

SW-DWM1001-API-Guide-1.0

Page 22 of 74

DW1001 Firmware API Guide

Figure 10 GPIO scheme: DWM1001 notifies host device of status change, using GPIO

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
status “SPI: Idle”, the GPIO scheme will regain the control of the GPIO pin.

2.9

API for on-board C code developers

Decawave provides the DWM1001 source pack of the pre-built firmware. Users can add their own
code and make use of the C code API functions in certain entry files provided in the source pack. In
this way, users are able to add their own functions inside the module firmware and perhaps not
need to add an external host controller device. The detail of adding such user code is provided in
DWM1001 Firmware User Guide [3].
A few points the C code users should note when using the on-board firmware:
1) User application is based on eCos RTOS and DWM libraries.
2) Files used for linking with the user applications:
a. dwm.h - header file - wrapper for all header files necessary for building of the user
application
b. libdwm.a - static library
c. extras.o, vectors.o, libtarget.a - eCos static library
d. target_s132_fw1.ld - linker script for firmware section 1
e. target_s132_fw2.ld - linker script for firmware section 2
3) The API provides functions and defines to the user application
a. Common functions on operating systems like thread creation, memory allocation,
access to interfaces (e.g. GPIO, SPI), synchronization (e.g. mutex, signal)
b. Initialization, configuration and maintenance of the DWM communication stack
c. Register of callbacks for incoming data and measurements

SW-DWM1001-API-Guide-1.0

Page 23 of 74

DW1001 Firmware API Guide

3 GENERIC API INFORMATION
3.1

Used terminology

Anchor: has a fixed location – as a reference point to locate Tags. The module may be configured to
behave as an anchor node. An anchor initiator is an anchor with the initiator flag enabled as
introduced in section 3.4.8. It is a special anchor node that initiates the whole network, see the
system overview for more detail [4].
Tag: usually moving/changing location, determines its position dynamically with the help of the
anchors. The module may be configured to behave as a tag node.
Gateway: knows about all nodes in the network, provides status information about network nodes
(read/inspect), cache this information and provide it to gateway client, provides means to interact
with network elements (a.k.a. interaction proxy).
Node: network node (anchor, tag, gateway...)
LE: location engine – position solver function (on the tag)

3.2

Little endian

The integers used in the PANS API are little endian, unless otherwise stated.

3.3

Firmware update

As introduced in the DWM1001 System Overview [4], the nodes will compare their firmware version
to the network they want to join. If the firmware version is different, the nodes will try to update
their firmware before joining. This firmware update function can be enabled/disabled in the
configuration. Here lists the rules of the function that the nodes will follow.
Tag:
When enabled, the tag will always check the firmware version and try to synchronise its firmware
version with the network by sending the update request to the nearby anchor nodes in the network
before it starts ranging.
When disabled, the tag will start ranging without checking the firmware version. This can lead to
version compatibility problems and must be dealt with very carefully.
Anchor:
When enabled, before joining the network, the anchor will check the firmware version and try to
synchronise its firmware version with the network by sending the update request to the nearby
anchor nodes. After having joined the network, the anchor will respond to nearby nodes’ requests to
update their firmware.
When disabled, before joining the network, the anchor will directly send the join request and will
not check the firmware version. This can lead to version compatibility problems and must be dealt

SW-DWM1001-API-Guide-1.0

Page 24 of 74

DW1001 Firmware API Guide
with very carefully. After having joined the network, the anchor will ignore the firmware update
requests from the nearby nodes.

3.4

Frequently used TLV values

Below lists the data that are frequently used in the APIs, either as input parameters or output
parameters. These parameters are of fixed size and some have their own value ranges.
3.4.1

err_code

1-byte error code, response information to the incoming requests.
err_code : 8-bit integer, valid values:
0 : OK
1 : unknown command or broken TLV frame
2 : internal error
3 : invalid parameter
4 : busy
3.4.2

position

13-byte position information of the node (anchor or tag).
position = x, y, z, qf : bytes 0-12, position coordinates and quality factor
x : bytes 0-3, 32-bit integer, in millimeters
y : bytes 4-7, 32-bit integer, in millimeters
z : bytes 8-11, 32-bit integer, in millimeters
qf : bytes 12, 8-bit integer, position quality factor in percent
3.4.3

gpio_idx

1-byte index of GPIO pins available to the user.
gpio_idx : 8-bit integer, valid values: 2, 8, 9, 10, 12, 13, 14, 15, 22, 23, 27, 30, 31.
Note: some GPIO pins are occupied by the PANS library and can only be accessed/controlled by
through the APIs partially:
- When configured as tag and BLE function is enabled, GPIO2 is occupied.
- When LED function is enabled, GPIO 22, 30 and 31 are occupied.
- During the module reboot, the bootloader (as part of the firmware image) blinks twice the
LEDs on GPIOs 22, 30 and 31 to indicate the module has restarted. Thus these GPIOs should
be used with care during the first 1s of a reboot operation.
3.4.4

gpio_value

1-byte value of the GPIO pin.
gpio_value = 8-bit integer, valid values:
© Decawave Ltd 2017

SW-DWM1001-API-Guide-1.0

Page 25 of 74

DW1001 Firmware API Guide

0 : set the I/O port pin to a LOW voltage, logic 0 value
1 : set the I/O port pin to a HIGH voltage, logic 1 value
3.4.5

gpio_pull

1-byte status of the GPIO pin as input.
gpio_pull = 8-bit integer, valid values:
0 : DWM_GPIO_PIN_NOPULL
1 : DWM_GPIO_PIN_PULLDOWN
3 : DWM_GPIO_PIN_PULLUP
3.4.6

fw_version

4-byte value representing the version number of the firmware.
fw_version = maj, min, patch, ver: bytes 0-3, firmware version
maj : byte 0, 8-bit number, MAJOR
min : byte 1, 8-bit number, MINOR
patch : byte 2, 8-bit number, PATCH
ver : byte 3, 8-bit number, res and var
res : byte 3, bits 4-7, 4-bit number, RESERVED
var : byte 3, bits 0-3, 4-bit number, VARIANT
3.4.7

cfg_tag

2 bytes, configuration of the tag, which contains common tag configuration parameters. Each bit
represents different thing.
cfg_tag = accel_en, meas_mode, low_power_en, loc_engine_en, ble_en, uwb_mode, fw_upd_en:
tag configuration information.
accel_en: accelerometer enable.
meas_mode: measurement mode. 0 - TWR; 1, 2, 3 - reserved.
low_power_en: low-power mode enable.
loc_engine_en: internal Location Engine enable. 0 means do not use internal Location Engine, 1
means internal Location Engine.
ble_en: Bluetooth enable.
uwb_mode: UWB operation mode: 0 - offline, 1 – passive, 2 – active.
fw_upd_en: Firmware update enable.
3.4.8

cfg_anchor

1 byte, configuration of the anchor, which contains common anchor configuration parameters. Each
bit represents different thing.

SW-DWM1001-API-Guide-1.0

Page 26 of 74

DW1001 Firmware API Guide

cfg_anchor = initiator, bridge, ble_en, uwb_mode, fw_upd_en
initiator : Initiator role enable.
bridge : Bridge role enable.
ble_en : Bluetooth enable.
uwb_mode: UWB operation mode: 0 - offline, 1 – passive, 2 – active.
fw_upd_en : Firmware update enable.
3.4.9

cfg_node

2 bytes, configuration of the node, which contains common configuration parameters. Each bit
represents different thing.
cfg_anchor = err_code, mode, initiator, bridge, low_power_en, meas_mode, loc_engine_en, ble_en,
uwb_mode, fw_update_en
mode: 0 - tag, 1 - anchor.
initiator : Initiator role enable.
bridge : Bridge role enable.
accel_en: accelerometer enable.
meas_mode: measurement mode. 0 - TWR; 1, 2, 3 - reserved.
low_power_en: low-power mode enable.
loc_engine_en: internal Location Engine enable. 0 means do not use internal Location Engine, 1
means internal Location Engine is active.
ble_en: Bluetooth enable.
uwb_mode: UWB operation mode: 0 - offline, 1 – passive, 2 – active.
fw_upd_en: Firmware update enable.

SW-DWM1001-API-Guide-1.0

Page 27 of 74

DW1001 Firmware API Guide

4 API FUNCTION DESCRIPTIONS
4.1

List of API functions

The API functions for on-board user app (c code) and SPI/UART TLV commands are unified. Listed
below in Table 2, in TLV type ascending order.
Table 2 API request function list

API function name

On-board
user app
available
y
dwm_pos_set
y
dwm_pos_get
y
dwm_upd_rate_set
y
dwm_upd_rate_get
y
dwm_cfg_tag_set
y
dwm_cfg_anchor_set
y
dwm_cfg_get
y
dwm_sleep
y
dwm_loc_get
y
dwm_baddr_set
y
dwm_baddr_get
y
dwm_reset
y
dwm_ver_get
y
dwm_gpio_cfg_output
y
dwm_gpio_cfg_input
y
dwm_gpio_value_set
y
dwm_gpio_value_get
dwm_gpio_value_toggle y
n
dwm_status_get
n
dwm_int_cfg
y
dwm_gpio_irq_cfg
y
dwm_gpio_irq_dis
y
dwm_i2c_read
y
dwm_i2c_write
y
dwm_evt_cb_register

SPI/UART TLV
type
Length
0x01
0x02
0x03
0x04
0x05
0x07
0x08
0x0a
0x0c
0x0f
0x10
0x14
0x15
0x28
0x29
0x2a
0x2b
0x2c
0x32
0x34
n/a
n/a
n/a
n/a
n/a

0x0d
0x00
0x02
0x00
0x02
0x01
0x00
0x00
0x00
0x00
0x00
0x00
0x00
0x02
0x02
0x02
0x01
0x01
0x00
0x02
n/a
n/a
n/a
n/a
n/a

Ref (Section)

4.3.1
4.3.2
4.3.3
4.3.4
4.3.5
4.3.6
4.3.7
4.3.8
4.3.9
4.3.10
4.3.11
4.3.12
4.3.13
4.3.14
4.3.15
4.3.16
4.3.17
4.3.18
4.3.19
4.3.20
4.3.21
4.3.22
4.3.23
4.3.24
4.3.25

The definition and usage of the API functions are described below in individual sub-sections. In
introducing each API function, all possible accesses are described, including c code, UART/SPI TLV.
Note: Some API functions are only provided in limited accesses.
Note: There are more TLV type than listed in Table 2. The TLV types that do not relate to API
functions are not introduced here, e.g. the TLV response types. See Section 6 for the full TLV type
list.

SW-DWM1001-API-Guide-1.0

Page 28 of 74

DW1001 Firmware API Guide

4.2

Usage of the APIs

Examples of how the UART Generic, SPI and C code API can be used is introduced in the DWM1001
Firmware User Guide [3]. The examples intend to give a brief view of the API usage and only include
very simple API functions. The code in the source files of the examples can be changed to
modify/add functionalities. The full list of API functions as shown in Table 2 can also be found in the
included header files of the API source code packages. Table 3 lists the packages with examples of
the corresponding APIs, the locations of the header files and the locations of the source files.
Table 3 API examples location
API

Package with
examples

C code

DWM1001 onboard package [5]
UART
DWM1001 Host
Generic API package [6]
SPI
DWM1001 Host
API package [6]

4.3

Header file location

Example source file location

dwm\include\dwm
.h
include\dwm_api.h

dwm\examples\dwm-simple\dwm-simple.c

include\dwm_api.h

examples\ex1_TWR_2Hosts\tag\tag_cfg.c

Details of the API functions

The details of each API function listed in Table 2 are described in the below sub-sections.

SW-DWM1001-API-Guide-1.0

Page 29 of 74

DW1001 Firmware API Guide
4.3.1

dwm_pos_set

4.3.1.1 Description

This API function set the default position of the node. Default position is not used when in tag mode
but is stored anyway so the module can be configured to anchor mode and use the value previously
set by dwm_pos_set. This call does a write to internal flash in case of new value being set, hence
should not be used frequently as can take, in worst case, hundreds of milliseconds.
Parameter
Field
Input
Output

Description
Name
position
err_code

Size
13-byte array
8-bit integer

Position information, see Section 3.4.2
0, 1 or 2, see Section 3.4.1

4.3.1.2 C code

Declaration:
int dwm_pos_set(dwm_pos_t* p_pos);

Example:
dwm_pos_t pos;
pos.qf = 100;
pos.x = 121;
pos.y = 50;
pos.z = 251;
dwm_pos_set(&pos);

4.3.1.3 SPI/UART Generic

Declaration:
TLV request
Type Length
0x01 0x0D

Value
position

Example:
TLV request
Type Length

0x01

0x0D

TLV response
Type Length
0x40

0x01

Value
Position
32 bit value in 32 bit value in 32 bit value in 8 bit value is
little endian is little endian is little endian is quality factor in
x coordinate
y coordinate
z coordinate
percents (0-100)
in millimeters
in millimeters
in millimeters
0x79 0x00 0x00 0x00 0x32 0x00 0x00 0x00 0xfb 0x00 0x00 0x00 0x64

Value
err_code
0x00

SW-DWM1001-API-Guide-1.0

Page 30 of 74

DW1001 Firmware API Guide
4.3.2

dwm_pos_get

4.3.2.1 Description

This API function obtain position of the node. If the current position of the node is not available, the
default position previously set by dwm_pos_set will be returned.
Parameter
Field
Input
Output

Description
Name
none
err_code
position

Size
8-bit integer
13-byte array

0, 1 or 2, see Section 3.4.1
position information, see Section 3.4.2

4.3.2.2 C code

Declaration:
int dwm_pos_set(dwm_pos_t* p_pos);

Example:
dwm_pos_t pos;
dwm_pos_get(&pos);

4.3.2.3 SPI/UART Generic

Declaration:
TLV request
Type Length
0x02 0x00

Example:
TLV request
Type Length
0x02 0x00
TLV response
Type Length

0x40

0x01

Value
err_code

Type

Length

0x00

0x41

0x0D

Value
Position
32 bit value
32 bit value
32 bit value
8 bit value is
in little
in little
in little
quality
endian is x
endian is y
endian is z
factor in
coordinate in coordinate in coordinate in percents (0millimeters
millimeters
millimeters
100)
0x79 0x00 0x00 0x00 0x32 0x00 0x00 0x00 0xfb 0x00 0x00
0x00 0x64

SW-DWM1001-API-Guide-1.0

Page 31 of 74

DW1001 Firmware API Guide
4.3.3

dwm_upd_rate_set

4.3.3.1

Description

This API function sets the update rate and the stationary update rate of the position in unit of 100
milliseconds. Stationary update rate must be greater or equal to normal update rate. This call does a
write to the internal flash in case of new value being set, hence should not be used frequently as can
take, in worst case, hundreds of milliseconds.
Parameter
Field
Input

Output

Description
Name
update_rate

Size
16-bit integer

update_rate_stationary

16-bit integer

err_code

8-bit integer

position publication interval in multiples of 100
milliseconds
position publication interval when node is not
moving in multiples of 100 milliseconds,
maximum is 2 minutes, must be greater or
equal to normal update_rate
0, 1 or 2, see Section 3.4.1

4.3.3.2 C code

Declaration:
int dwm_upd_rate_set(uint16_t ur, uint16 urs);

Example:
dwm_upd_rate_set(10, 50); // update rate 1 second. 5 seconds stationary

4.3.3.3 SPI/UART Generic

Declaration:
TLV request
Type Length
0x03 0x04

Value
update_rate

update_rate_stationary

Example:
TLV request
Type Length

0x03

0x04

TLV response
Type Length
0x40

0x01

Value
update_rate
16 bit value in little
endian, which is update
rate in multiples of 100 ms
(e.g. 0x0A 0x00 means 10)

0x0A 0x00

update_rate_stationary
16 bit value in little
endian, which is
stationary update rate in
multiples of 100 ms. E.g.
0x0A 0x00 means 5.0.
0x32 0x00

Value
err_code
0x00

SW-DWM1001-API-Guide-1.0

Page 32 of 74

DW1001 Firmware API Guide
4.3.4

dwm_upd_rate_get

4.3.4.1 Description

This API function gets position update rate.
Parameter
Field
Input
Output

Description
Name
none
err_code
update_rate

Size

update_rate_stationary

16-bit integer

8-bit integer
16-bit integer

0, 1 or 2, see Section 3.4.1
position update interval in multiples of 100
milliseconds,
Stationary position update interval in multiples
of 100 milliseconds

4.3.4.2 C code

Declaration:
int dwm_upd_rate_get(uint16_t* p_ur, uint16_t* p_urs);

Example:
uint16_t ur, urs;
dwm_upd_rate_get(&ur, &urs);

4.3.4.3 SPI/UART Generic

Declaration:
TLV request
Type Length
0x04 0x00

Example:
TLV request
Type Length
0x04 0x00
TLV response
Type Length

0x40

0x01

Value
err_code

Type

0x00

0x45

Length

0x04

Value
update_rate, first 2 bytes,
indicating the position
update interval in multiples
of 100 ms. E.g. 0x0A 0x00
means 1.0s interval.
0x0A 0x00

SW-DWM1001-API-Guide-1.0

update_rate_stationary,
second 2 bytes, indicating
the stationary position
update interval in multiples
of 100 ms. E.g. 0x32 0x00
means 5.0s interval.
0x32 0x00

Page 33 of 74

DW1001 Firmware API Guide
4.3.5

dwm_cfg_tag_set

4.3.5.1 Description

This API function configures the node as tag with given options. It automatically resets the DWM
module. This call does a write to internal flash in case of new value being set, hence should not be
used frequently as can take, in worst case, hundreds of milliseconds. Note that this function only
sets the configuration parameters. To make effect of the settings, users should issue a reset
command, see section 4.3.12 for more detail.
Parameter
Field
Input
Output

Description
Name
cfg_tag
err_code

Size
16-bit integer
8-bit integer

2-byte, configuration of the tag, see Section 3.4.7
0, 1 or 2, see Section 3.4.1

4.3.5.2 C code

Declaration:
int dwm_cfg_tag_set(dwm_cfg_tag_t* p_cfg);

Example:
dwm_cfg_tag_t cfg;
cfg.accel_en = 0;
cfg.low_power_en = 1;
cfg.meas_mode = DWM_MEAS_MODE_TWR;
cfg.loc_engine_en = 1;
cfg.common.ble_en = 1;
cfg.common.online = 1;
cfg.common.fw_update_en = 1;
cfg.common.uwb_mode = DWM_UWB_MODE_ACTIVE;
dwm_cfg_tag_set(&cfg);

4.3.5.3 SPI/UART Generic

Declaration:
TLV request
Type Length

0x05

0x02

Value
(* BYTE 1 *)
(bits 3-7) reserved
(bit 2) accel_en
(bits 0-1) meas_mode : 0 - TWR, 1-3 reserved
(* BYTE 0 *)
(bit 7) low_power_en
(bit 6) loc_engine_en
(bit 5) reserved
(bit 4) led_en
(bit 3) ble_en
(bit 2) fw_update_en
(bits 0-1) uwb_mode
cfg_tag

Example:
TLV request
Type Length

0x03

0x04

Value
cfg_tag: low_power_en, loc_engine_en, ble_en,
DWM_UWB_MODE_ACTIVE, fw_update_en
0xCC 0x00

TLV response
© Decawave Ltd 2017

SW-DWM1001-API-Guide-1.0

Page 34 of 74

DW1001 Firmware API Guide
Type

Length

Value
err_code

0x40

0x01

0x00

SW-DWM1001-API-Guide-1.0

Page 35 of 74

DW1001 Firmware API Guide
4.3.6

dwm_cfg_anchor_set

4.3.6.1 Description

Description
Name
cfg_anchor
err_code

Size
8-bit integer
8-bit integer

1-byte, configuration of the tag, see Section 3.4.8
0, 1 or 2, see Section 3.4.1

4.3.6.2 C code

Declaration:
int dwm_cfg_anchor_set(dwm_cfg_anchor_t* p_cfg)

Example:
dwm_cfg_anchor_t cfg;
cfg.initiator = 1;
cfg.bridge = 0;
cfg.common.ble_en = 1;
cfg.common.online = 1;
cfg.common.fw_update_en = 1;
cfg.common.uwb_mode = DWM_UWB_MODE_ACTIVE;
dwm_cfg_anchor_set(&cfg);

4.3.6.3 SPI/UART Generic

Declaration:
TLV request
Type Length

0x07

0x01

Value
(bit 7) initiator
(bit 6) bridge
(bit 5) reserved
(bit 4) led_en
(bit 3) ble_en
(bit 2) fw_update_en
(bits 0-1) uwb_mode
cfg_anchor

Example:
TLV request
Type Length

0x03

0x04

TLV response
Type Length
0x40

0x01

Value
cfg_anchor: initiator, ble_en, fw_update_en,
UWB_MODE_ACTIVE
0x8E

Value
err_code
0x00

SW-DWM1001-API-Guide-1.0

Page 36 of 74

DW1001 Firmware API Guide
4.3.7

dwm_cfg_get

4.3.7.1 Description

This API function obtains the configuration of the node.
Parameter
Field
Input
Output

Description
Name
none
err_code
cfg_node

Size
8-bit integer
16-bit integer

0, 1 or 2, see Section 3.4.1
configuration of the node, see Section 3.4.9

4.3.7.2 C code

Declaration:
int dwm_cfg_get(dwm_cfg_t* p_cfg);

Example:
dwm_cfg_t cfg;
dwm_cfg_get(&cfg);
printf(“mode %u \n”, cfg.mode);
printf(“initiator %u \n”, cfg.initiator);
printf(“bridge %u \n”, cfg.bridge);
printf(“motion detection enabled %u \n”, cfg.accel_en);
printf(“measurement mode %u \n”, cfg.meas_mode);
printf(“low power enabled %u \n”, cfg.low_power_en);
printf(“internal location engine enabled %u \n”, cfg.loc_engine_en);
printf(“LED enabled %u \n”, cfg.common.led_en);
printf(“BLE enabled %u \n”, cfg.common.ble_en);
printf(“firmware update enabled %u \n”, cfg.common.fw_update_en);
printf(“UWB mode %u \n”, cfg.common.uwb_mode);

4.3.7.3 SPI/UART Generic

Declaration:
TLV request
Type Length
0x08 0x00

Example:
TLV request
Type Length
0x08 0x00
TLV response
Type Length

Value
err_code

Type

Length

Value
cfg_node:
(* BYTE 1 *)
(bits 6-7) reserved
(bit 5) mode : 0 - tag, 1 - anchor
(bit 4) initiator
(bit 3) bridge
(bit 2) accel_en
(bits 0-1) meas_mode : 0 - TWR, 1-3 not supported
(* BYTE 0 *)
(bit 7) low_power_en
(bit 6) loc_engine_en
(bit 5) reserved
(bit 4) led_en
(bit 3) ble_en
(bit 2) fw_update_en

SW-DWM1001-API-Guide-1.0

Page 37 of 74

DW1001 Firmware API Guide

0x40

0x01

0x00

0x46

0x02

(bits 0-1) uwb_mode
0x07 0x04

SW-DWM1001-API-Guide-1.0

Page 38 of 74

DW1001 Firmware API Guide
4.3.8

dwm_sleep

4.3.8.1 Description

This API function puts the module into sleep mode. Low power option must be enabled otherwise an
error will be returned.
Parameter
Field
Input
Output

Description
Name
none
err_code

Size
8-bit integer

0, 1 or 2, see Section 3.4.1

4.3.8.2 C code

Declaration:
int dwm_sleep(void);

Example:
dwm_sleep();

4.3.8.3 SPI/UART Generic

Declaration:
TLV request
Type Length
0x0A 0x00

Example:
TLV request
Type Length
0x0A 0x00
TLV response
Type Length
0x40

0x01

Value
err_code
0x00

SW-DWM1001-API-Guide-1.0

Page 39 of 74

DW1001 Firmware API Guide
4.3.9

dwm_loc_get

4.3.9.1 Description

Get last distances to the anchors (tag is currently ranging to) and the associated position. The
interrupt is triggered when all TWR measurements have completed and the LE has finished. If the LE
is disabled, the distances will just be returned. This API works the same way in both Responsive and
Low-Power tag modes.
Parameter
Field
Input
Output

Description
Name
none
position

Size
13-byte array

Position information of the current node, see Section
3.4.2
dist.cnt
1-byte
Number of distances to the anchors, max 15.
dist.addr
8-byte/2-byte public UWB address in little endian. (1)
dist.dist
4-byte
Distances to the anchors. (1)
dist.qf
1-byte
Quality factor of distances to the anchors. (1)
an_pos.cnt
1-byte
Number of anchor positions, max 15.
an_pos
13-byte array
Anchor positions information, see Section 3.4.2. (2)
(1) This data can appear more than once according to the value of dist.cnt. This data is 8-byte long in

C code API, 8-byte long in SPI/UART response for Anchor, and 2-byte long for SPI/UART response for
Tag.
(2) This data can appear more than once according to the value of an_pos.cnt.
4.3.9.2 C code

Declaration:
int dwm_loc_get(dwm_loc_data_t* p_loc);

Example:
dwm_loc_data_t loc;
dwm_pos_t pos;
int rv, i;
loc.p_pos = &pos;
rv = dwm_loc_get(&loc);
if (0 == rv) {
PRINT("[%ld,%ld,%ld,%u] ", loc.p_pos->x, loc.p_pos->y, loc.p_pos->z,
loc.p_pos->qf);
for (i = 0; i < loc.anchors.dist.cnt; ++i) {
PRINT("%u)", i);
PRINT("0x%llx", loc.anchors.dist.addr[i]);
if (i < loc.anchors.an_pos.cnt) {
PRINT("[%ld,%ld,%ld,%u]", loc.anchors.an_pos.pos[i].x,
loc.anchors.an_pos.pos[i].y,
loc.anchors.an_pos.pos[i].z,
loc.anchors.an_pos.pos[i].qf);
}
PRINT("=%lu,%u ", loc.anchors.dist.dist[i], loc.anchors.dist.qf[i]);
}
PRINT("\n");
} else {
PRINT("err code: %d\n", rv);
}

4.3.9.3 SPI/UART Generic

Declaration:
TLV request
Type Length
© Decawave Ltd 2017

SW-DWM1001-API-Guide-1.0

Page 40 of 74

DW1001 Firmware API Guide
0x0C

0x00

Example 1 (Tag node):
TLV request
Type Length
0x0C 0x00
TLV response
Type Length

0x40

0x01

Value
err_code

0x00

Type

0x41

Length

0x0D

Value
position, 13 bytes
444byte byte byte
x
y
z

2 bytes
UWB
address

Length

0x49

0x51

1-byte
quality
factor

0x4b 0x0a 0x00 0x00 0x1f
0x04 0x00 0x00 0x9c 0x0e
0x00 0x00 0x64

TLV response (residue of the frame from previous table)
Value
2 bytes
4-byte
1-byte
position
…
UWB
distance distance in
address
quality
standard
factor
13 byte
format
position and distance AN1
AN2, AN3

Type

4-byte
distance

1-byte
distance
quality
factor

Value
1 byte,
number of
distances
encoded in
the value
0x04

position
in
standard
13 byte
format

position and distance AN4

Example 2 (Anchor node):
TLV request
Type Length
0x0C 0x00
TLV response
Type Length

0x40

0x01

Value
err_code

0x00

Type

0x41

Length

0x0D

Value
position, 13 bytes
444byte byte byte
x
y
z

Length

0x48

0xC4

1-byte
quality
factor

0x4b 0x0a 0x00 0x00 0x1f
0x04 0x00 0x00 0x9c 0x0e
0x00 0x00 0x64

TLV response (residue of the frame from previous table)
Value
8 bytes
4-byte
1-byte
…
UWB
distance distance
address
quality factor
distance AN1
AN2, …, AN14

Type

8 bytes
4-byte
UWB
distance
address
distance AN15

SW-DWM1001-API-Guide-1.0

Value
1 byte,
number of
distances
encoded in
the value
0x0F

1-byte
distance
quality factor

Page 41 of 74

DW1001 Firmware API Guide
4.3.10 dwm_baddr_set
4.3.10.1 Description

Sets the public Bluetooth address used by device. New address takes effect after reset. This call does
a write to internal flash in case of new value being set, hence should not be used frequently as can
take, in worst case, hundreds of milliseconds
Parameter
Field
Input

Name
ble_addr

Size
6-bytes

Description

Output

err_code

8-bit integer

48-bit long public BluetoothE address in little
endian.
0, 1 or 2, see Section 3.4.1

4.3.10.2 C code

Declaration:
int dwm_baddr_set(dwm_baddr_t* p_baddr);

Example:
dwm_baddr_t baddr;
baddr.byte[0] = 1;
baddr.byte[1] = 2;
baddr.byte[2] = 3;
baddr.byte[3] = 4;
baddr.byte[4] = 5;
baddr.byte[5] = 6;
dwm_baddr_set(&baddr);

4.3.10.3 SPI/UART Generic

Declaration:
TLV request
Type Length
0x0F 0x06

Value
ble_addr

Example:
TLV request
Type Length
0x0F

0x06

TLV response
Type Length
0x40

0x01

Value
ble_addr, 6 bytes in little endian
0x01 0x23 0x45 0x67 0x89 0xab

Value
err_code
0x00

SW-DWM1001-API-Guide-1.0

Page 42 of 74

DW1001 Firmware API Guide
4.3.11 dwm_baddr_get
4.3.11.1 Description

Get Bluetooth address currently used by device.
Parameter
Field
Input
Output

Description
Name
none
ble_addr

Size
6-bytes

48-bit long public Bluetooth address in little
endian.

4.3.11.2 C code

Declaration:
int dwm_baddr_get(dwm_baddr_t* p_baddr);

Example:
dwm_baddr_t baddr;
int i;
if (DWM_OK == dwm_baddr_get(&baddr)) {
printf("addr=");
for (i = DWM_BLE_ADDR_LEN - 1; i >= 0; --i) {
printf("%02x%s", baddr.byte[i], (i > 0) ? ":" : "");
}
printf("\n");
} else {
printf("FAILED");
}

4.3.11.3 SPI/UART Generic

Declaration:
TLV request
Type Length
0x10 0x00

Example:
TLV request
Type Length
0x10 0x00
TLV response
Type Length
0x40

0x01

Value
err_code
0x00

Type

Length

0x5F

0x06

Value
ble_addr, 6 bytes in little endian
0x01 0x23 0x45 0x67 0x89 0xab

SW-DWM1001-API-Guide-1.0

Page 43 of 74

DW1001 Firmware API Guide
4.3.12 dwm_reset
4.3.12.1 Description

This API function reboots the module.
Parameter
Field
Input
Output

Description
Name
none
err_code

Size
8-bit integer

0, 1 or 2, see Section 3.4.1

4.3.12.2 C code

Declaration:
int dwm_reset(void);

Example:
dwm_reset();

4.3.12.3 SPI/UART Generic

Declaration:
TLV request
Type Length
0x14 0x00

Example:
TLV request
Type Length
0x14 0x00
TLV response
Type Length
0x40

0x01

Value
err_code
0x00

SW-DWM1001-API-Guide-1.0

Page 44 of 74

DW1001 Firmware API Guide
4.3.13 dwm_ver_get
4.3.13.1 Description

This API function obtains the firmware version of the module.
Parameter
Field
Input
Output

Description
Name
none
err_code
fw_version
cfg_version
hw_version

Size
8-bit integer
4-byte array
4-byte array
4-byte array

0, 1 or 2, see Section 3.4.1
firmware version, see Section 3.4.6
configuration version, 32-bits integer
hardware version, 32-bits integer

4.3.13.2 C code

Declaration:
int dwm_ver_get(dwm_ver_t* p_ver);

Example:
dwm_ver_t ver;
dwm_ver_get(&ver);

4.3.13.3 SPI/UART Generic

Declaration:
TLV request
Type Length
0x15 0x00

Example:
TLV request
Type Length
0x15 0x00
TLV response
Type Length

0x40

0x01

Value
err_code

Type

Length

0x00

0x50

0x04

Value
fw_version:
maj = 1
min = 2
patch = 5
var = 1
0x01 0x05 0x02 0x01

Type

Length

Value
cfg_version

0x51

0x04

0x00 0x07 0x01 0x00

TLV response (residue of the frame from previous table)
Type Length Value
hw_version
0x52

0x04

0x2a 0x00 0xca 0xde

SW-DWM1001-API-Guide-1.0

Page 45 of 74

DW1001 Firmware API Guide
4.3.14 dwm_gpio_cfg_output
4.3.14.1 Description

This API function configures a specified GPIO pin as an output and also sets its value to 1 or 0, giving
a high or low digital logic output value.
Note: During the module reboot, the bootloader (as part of the firmware image) blinks twice the
LEDs on GPIOs 22, 30 and 31 to indicate the module has restarted. Thus these GPIOs should be used
with care during the first 1s of a reboot operation.
Parameter
Field
Input

Description
Name
gpio_idx
gpio_value
err_code

Output

Size
8-bit integer
8-bit integer
8-bit integer

GPIO number, see Section 3.4.3 for valid values
0 or 1
0, 1 or 2, see Section 3.4.1

4.3.14.2 C code

Declaration:
int dwm_gpio_cfg_output(dwm_gpio_idx_t idx, bool value);

Example:
dwm_gpio_cfg_output(DWM_GPIO_IDX_13, 1); // set pin 13 as output and to 1 (high voltage)

4.3.14.3 SPI/UART Generic

Declaration:
TLV request
Type
Length
0x28
0x02

Value
gpio_idx

gpio_value

Value
gpio_idx

gpio_value

0x0d

0x01

Example:
TLV request
Type
Length
0x28

0x02

TLV response
Type
Length
0x40

0x01

Value
err_code
0x00

SW-DWM1001-API-Guide-1.0

Page 46 of 74

DW1001 Firmware API Guide
4.3.15 dwm_gpio_cfg_input
4.3.15.1 Description

This API function configure GPIO pin as input.
Note: During the module reboot, the bootloader (as part of the firmware image) blinks twice the
LEDs on GPIOs 22, 30 and 31 to indicate the module has restarted. Thus these GPIOs should be used
with care during the first 1s of a reboot operation.
Parameter
Field
Input

Output

Description
Name
gpio_idx
gpio_pull

Size
8-bit integer
8-bit integer

err_code

8-bit integer

GPIO number, see Section 3.4.3 for valid values.
GPIO pull status, see Section 3.4.53.4.3 for valid
values.
0, 1 or 2, see Section 3.4.1

4.3.15.2 C code

Declaration:
int dwm_gpio_cfg_input(dwm_gpio_idx_t idx, dwm_gpio_pin_pull_t pull_mode);

Example:
dwm_gpio_cfg_input(DWM_GPIO_IDX_13, DWM_GPIO_PIN_PULLUP);

4.3.15.3 SPI/UART Generic

Declaration:
TLV request
Type Length
0x29 0x02

Value
gpio_idx

gpio_pull

Example:
TLV request
Type Length

0x29

0x02

TLV response
Type Length
0x40

0x01

Value
gpio_idx

0x0D

gpio_pull,
0 -no pull
1 -pull down
3 -pull up
0x01

Value
err_code
0x00

SW-DWM1001-API-Guide-1.0

Page 47 of 74

DW1001 Firmware API Guide
4.3.16 dwm_gpio_value_set
4.3.16.1 Description

This API function sets the value of the GPIO pin to high or low.
Note: During the module reboot, the bootloader (as part of the firmware image) blinks twice the
LEDs on GPIOs 22, 30 and 31 to indicate the module has restarted. Thus these GPIOs should be used
with care during the first 1s of a reboot operation.
Parameter
Field
Input
Output

Description
Name
gpio_idx
gpio_value
err_code

Size
8-bit integer
8-bit integer
8-bit integer

GPIO number, see Section 3.4.3 for valid values.
GPIO value, see Section 0 for valid values.
0, 1 or 2, see Section 3.4.1

4.3.16.2 C code

Declaration:
int dwm_gpio_value_set(dwm_gpio_idx_t idx, bool value);

Example:
dwm_gpio_value_set(DWM_GPIO_IDX_13, 1);

4.3.16.3 SPI/UART Generic

Declaration:
TLV request
Type Length
0x2a 0x02

Value
gpio_idx

gpio_value

Example:
TLV request
Type Length

0x2a

0x02

TLV response
Type Length
0x40

0x01

Value
gpio_idx

0x0D

gpio_value,
0 - low
1 - high
0x01

Value
err_code
0x00

SW-DWM1001-API-Guide-1.0

Page 48 of 74

DW1001 Firmware API Guide
4.3.17 dwm_gpio_value_get
4.3.17.1 Description

This API function reads the value of the GPIO pin.
Parameter
Field
Input
Output

Description
Name
gpio_idx
gpio_value

Size
8-bit integer
8-bit integer

GPIO number, see Section 3.4.3 for valid values.
GPIO value, see Section 0 for valid values.

4.3.17.2 C code

Declaration:
int dwm_gpio_value_get(dwm_gpio_idx_t idx, bool* p_value);

Example:
uint8_t value;
dwm_gpio_value_get(DWM_GPIO_IDX_13, &value);
printf(“DWM_GPIO_IDX_13 value = %u\n”, value);

4.3.17.3 SPI/UART Generic

Declaration:
TLV request
Type Length
0x2b 0x01

Value
gpio_idx

Example:
TLV request
Type Length
0x2b

0x01

TLV response
Type Length
0x40

0x01

Value
gpio_idx
0x0D

Value
err_code

Type

Length

Value
gpio_value

0x00

0x55

0x01

SW-DWM1001-API-Guide-1.0

Page 49 of 74

DW1001 Firmware API Guide
4.3.18 dwm_gpio_value_toggle
4.3.18.1 Description

This API function toggles the value of the GPIO pin.
Note: During the module reboot, the bootloader (as part of the firmware image) blinks twice the
LEDs on GPIOs 22, 30 and 31 to indicate the module has restarted. Thus these GPIOs should be used
with care during the first 1s of a reboot operation.
Parameter
Field
Input
Output

Description
Name
gpio_idx
err_code

Size
8-bit integer
8-bit integer

GPIO number, see Section 3.4.3 for valid values.
0, 1 or 2, see Section 3.4.1

4.3.18.2 C code

Declaration:
int dwm_gpio_value_toggle(dwm_gpio_idx_t idx);

Example:
dwm_gpio_value_toggle(DWM_GPIO_IDX_13);

4.3.18.3 SPI/UART Generic

Declaration:
TLV request
Type Length
0x2c 0x01

Value
gpio_idx

Example:
TLV request
Type Length
0x2c

0x01

TLV response
Type Length
0x40

0x01

Value
gpio_idx
0x0D

Value
err_code
0x00

SW-DWM1001-API-Guide-1.0

Page 50 of 74

DW1001 Firmware API Guide
4.3.19 dwm_status_get
4.3.19.1 Description

This API function reads the system status: Location Data Ready. Location Data is the calculated result
of the LE. When the tag finished TWR with the 4 anchors, the derived distance to the LE for position
calculation. When this calculation is done, the Location Data Ready flag will be turn on. When the
data is acquired by any API function, the flag will turn off until next calculation is done.
Parameter
Field
Input
Output

Description
Name
none
status

Size
8-bit integer

Bit0: loc_ready = ‘0’ | ‘1’ (* new location data are
ready *)
Bit1: uwbmac_joined = ‘0’ | ‘1’ (* node is
connected to UWB network *)

4.3.19.2 C code

Declaration:
int dwm_status_get(dwm_status_t* p_status);

Example:
dwm_status_t status;
int rv;
rv = dwm_status_get(&status);
if (rv == DWM_OK) {
printf("New location data: %d\n", status.loc_data);
printf("UWB network joined: %d\n", status.uwbmac_joined);
} else {
printf("error\n");
}

4.3.19.3 SPI/UART Generic

Declaration:
TLV request
Type Length
0x32 0x00

Example:
TLV request
Type Length
0x32 0x00
TLV response
Type Length

0x40

0x01

Value
err_code

Type

Length

0x00

0x5A

0x01

Value
loc_ready: yes
uwbmac_joined: no
0x01

SW-DWM1001-API-Guide-1.0

Page 51 of 74

DW1001 Firmware API Guide
4.3.20 dwm_int_cfg
4.3.20.1 Description

This API function enable interrupt generation for various events. Interrupts/events are
communicated to the user by setting of dedicated GPIO pin (pin 19: READY), user can than read the
status (dwm_status_get) and react according to the new status. The status is cleared when read.
This call is available only on UART/SPI interfaces. This call does a write to internal flash in case of
new value being set, hence should not be used frequently as can take, in worst case, hundreds of
milliseconds.
Parameter
Field
Input
Output

Description
Name
none
data_ready_flag

Size
8-bit integer

Bit 0: loc_ready. Interrupt is generated when location
data are ready, 0=disable, 1=enable.
Bit 1: spi_data_ready. Interrupt is generated when
new SPI response data is available. 0=disable,
1=enable.

4.3.20.2 C code

This command is not available for on-board user application. It is used only available on external
interfaces (UART/SPI).
4.3.20.3 SPI/UART Generic

Declaration:
TLV request
Type Length
0x34 0x00

Value
data_ready_flag

Example:
TLV request
Type Length

0x34

0x01

TLV response
Type Length
0x40

0x01

Value
data_ready_flag,
bit 0: loc_ready
bit 1: spi_data_ready
0x03

Value
err_code
0x00

SW-DWM1001-API-Guide-1.0

Page 52 of 74

DW1001 Firmware API Guide
4.3.21 dwm_gpio_irq_cfg
4.3.21.1 Description

This API function registers GPIO pin interrupt call back functions.
Parameter
Field
Input

Output

Description
Name
gpio_idx
Irq_type

Size
8-bit integer
8-bit integer

p_cb
p_data
err_code

Function pointer
Data pointer
8-bit integer

GPIO number, see Section 3.4.3 for valid values.
interrupt type,
1 = rising,
2 = falling,
3 = both.
Pointer to the callback function on the interrupt.
Pointer to data passed to the callback function.
0, 1 or 2, see Section 3.4.1

4.3.21.2 C code

Declaration:
int dwm_gpio_irq_cfg(dwm_gpio_idx_t idx, dwm_gpio_irq_type_t irq_type, dwm_gpio_cb_t* p_cb,
void* p_data);

Example:
void gpio_cb(void* p_data)
{
/* callback routine */
}
dwm_gpio_irq_cfg(DWM_GPIO_IDX_13, DWM_IRQ_TYPE_EDGE_RISING, &gpio_cb, NULL);

4.3.21.3 SPI/UART Generic

This command is not available on external interfaces (UART/SPI).

SW-DWM1001-API-Guide-1.0

Page 53 of 74

DW1001 Firmware API Guide
4.3.22 dwm_gpio_irq_dis
4.3.22.1 Description

This API function disables GPIO pin interrupt on the selected pin.
Parameter
Field
Input
Output

Description
Name
gpio_idx
err_code

Size
8-bit integer
8-bit integer

GPIO number, see Section 3.4.3 for valid values.
0, 1 or 2, see Section 3.4.1

4.3.22.2 C code

Declaration:
int dwm_gpio_irq_dis(dwm_gpio_idx_t idx);

Example:
dwm_gpio_irq_dis(DWM_GPIO_IDX_13);

4.3.22.3 SPI/UART Generic

This command is not available on external interfaces (UART/SPI).

SW-DWM1001-API-Guide-1.0

Page 54 of 74

DW1001 Firmware API Guide
4.3.23 dwm_i2c_read
4.3.23.1 Description

This API function read data from I2C slave.
Parameter
Field
Input

Output

Description
Name
addr
p_data
len
err_code

Size
8-bit integer
8-bit integer
8-bit integer
8-bit integer

Address of a slave device (only 7 LSB)
Pointer to a receive data buffer
Number of bytes to be received
0, 1 or 2, see Section 3.4.1

4.3.23.2 C code

Declaration:
int dwm_i2c_read(uint8_t addr, uint8_t* p_data, uint8_t len);

Example:
uint8_t data[2];
const uint8_t addr = 0x33; // some address of the slave device
dwm_i2c_read(addr, data, 2);

4.3.23.3 SPI/UART Generic

This command is not available on external interfaces (UART/SPI).

SW-DWM1001-API-Guide-1.0

Page 55 of 74

DW1001 Firmware API Guide
4.3.24 dwm_i2c_write
4.3.24.1 Description

This API function writes data to I2C slave.
Parameter
Field
Input

Output

Description
Name
addr
p_data
len
no_stop

Size
8-bit integer
8-bit integer
8-bit integer
8-bit integer

err_code

8-bit integer

Address of a slave device (only 7 LSB)
Pointer to a receive data buffer
Number of bytes to be received
0 or 1. If set to 1, the stop condition is not generated
on the bus after the transfer has completed (allowing
for a repeated start in the next transfer)
0, 1 or 2, see Section 3.4.1

4.3.24.2 C code

Declaration:
int dwm_i2c_write(uint8_t addr, uint8_t* p_data, uint8_t len, bool no_stop);

Example:
uint8_t data[2];
const uint8_t addr = 1; // some address of the slave device
data[0] = 0xAA;
data[1] = 0xBB;
dwm_i2c_write(addr, data, 2, true);

4.3.24.3 SPI/UART Generic

This command is not available on external interfaces (UART/SPI).

SW-DWM1001-API-Guide-1.0

Page 56 of 74

DW1001 Firmware API Guide
4.3.25 dwm_evt_cb_register
4.3.25.1 Description

This API function registers event callback function. The callback function is called in case of any event
that is intended for the user application. The user application decides whether to process the event
and the data passed as input or if it ignores the event. This function applies only to on-board c code
user application. Cannot be used with SPI or UART interface.
Parameter
Field
Input

Name
p_cb

Size
Function pointer

Description

Output

p_data
err_code

Data pointer
8-bit integer

Pointer to the callback function on the event, input
and output described below.
Pointer to data passed to the callback function.
0, 1 or 2, see Section 3.4.1

Input and output data of event callback function. Input data is passed to the user in the callback
function. The user can get data for actual event using event_id, see example in subsection 4.3.25.2.
Parameter
Field
Input

Output

Description
Name

event_id

Size
8-bit integer

loc_data

location data

Event ID to indicate the type of current event.
0 : new location data event,
1 : accelerometer event
Location data available in new location data event.
cnt, 8-bit integer: number of distances to the anchors.
addr, 64-bit integer: UWB address/id of the particular
anchor.
distance, 32-bit integer: distance to particular anchor
in millimetres.
pqf, 8-bit integer: quality factor.

none

4.3.25.2 C code

Declaration:
void dwm_evt_cb_register(dwm_evt_cb_t* p_cb, void* p_data);

Example:
void on_dwm_evt(dwm_evt_t* p_evt, void* p_data)
{
int i;
switch (p_evt->header.id) {
case DWM_EVT_NEW_LOC_DATA:
printf("\nt:%lu ", dwm_systime_us_get());
/* process the data here */
if (0 == p_evt->data.loc.p_pos) {
/* location engine is turned off */
} else {
printf("[%ld,%ld,%ld,%u] ", p_evt->data.loc.p_pos->x,
p_evt->data.loc.p_pos->y, p_evt->data.loc.p_pos->z,
p_evt->data.loc.p_pos->qf);
}
for (i = 0; i < p_evt->data.loc.anchors.dist.cnt; ++i) {
printf("%u)", i);
printf("0x%llx", p_evt->data.loc.anchors.dist.addr[i]);
if (i < p_evt->data.loc.anchors.an_pos.cnt) {
printf("[%ld,%ld,%ld,%u]",
p_evt->data.loc.anchors.an_pos.pos[i].x,
p_evt->data.loc.anchors.an_pos.pos[i].y,
p_evt->data.loc.anchors.an_pos.pos[i].z,

SW-DWM1001-API-Guide-1.0

Page 57 of 74

DW1001 Firmware API Guide
p_evt->data.loc.anchors.an_pos.pos[i].qf);
}
printf("=%lu,%u ", p_evt->data.loc.anchors.dist.dist[i],
p_evt->data.loc.anchors.dist.qf[i]);
}
printf("\n");
break;
default:
break;
}
}
…
int* p_user_data;
p_user_data = (int*)malloc(100);
dwm_evt_cb_register(on_dwm_evt, p_user_data);
…
/* if no user data are required */
dwm_evt_cb_register(on_dwm_evt, NULL);

4.3.25.3 SPI/UART Generic

This command is not available on external interfaces (UART/SPI).

SW-DWM1001-API-Guide-1.0

Page 58 of 74

DW1001 Firmware API Guide

5 SHELL COMMANDS
5.1

Usage of UART Shell Mode

Shell mode shares UART interface with Generic mode. DWM1001 starts by default in UART Generic
mode after reset. The Shell mode can be switched to by pressing ENTER twice within 1 second. The
Generic mode can be switched to by executing command “quit” when in Shell mode. Shell mode and
Generic mode can be switched back and forth.
Enter the Shell command and press “Enter” to execute the command. Press “Enter” without any
command in Shell mode to repeat the last command. The following sub-sections provides overview
of the Shell commands.

5.2

Displays help.
Example:
dwm> ?
Usage: [arg0] [arg1]
Build-in commands:
** Command group: Base **
?: this help
help: this help
quit: quit
** Command group: GPIO **
gc: GPIO clear
gg: GPIO get
gs: GPIO set
gt: GPIO toggle
** Command group: SYS **
f: Show free memory on the heap
ps: Show running threads
pms: Show PM tasks
reset: Reboot the system
si: System info
ut: Show device uptime
frst: Factory reset
** Command group: SENS **
twi: General purpose TWI read
aid: Read ACC device ID
av: Read ACC values
** Command group: LE **
les: Show meas. and pos.
lec: Show meas. and pos. in CSV
lep: Show pos. in CSV
© Decawave Ltd 2017

SW-DWM1001-API-Guide-1.0

Page 59 of 74

DW1001 Firmware API Guide

** Command group: UWBMAC **
nmg: Get node mode
nmp: Set mode to PN (passive)
nmo: Set mode to PN (off)
nma: Set mode to AN
nmi: Set mode to AIN
nmt: Set mode to TN
nmtl: Set mode to TN-LP
bpc: Toggle BW/TxPWR comp
la: Show AN list
stg: Get stats
stc: Clear stats
** Command group: API **
tlv: Send TLV frame
aurs: Set upd rate
aurg: Get upd rate
apg: Get pos
aps: Set pos
acas: Set anchor config
acts: Set tag config
** Tips **
Press Enter to repeat the last command

5.3

help

Displays help, same as command “?”.
Example:
dwm> help
… /*same output as command ? */

5.4

quit

Quit shell and switch UART into API mode.
Example:
dwm> quit
/* press enter twice to switch to shell mode again*/

5.5

Clears GPIO pin. See section 3.4.3 for valid GPIO number.
Example:
dwm> gc
Usage: gc
dwm> gc 13
gpio13: 0

SW-DWM1001-API-Guide-1.0

Page 60 of 74

DW1001 Firmware API Guide

5.6

Reads GPIO pin level. See section 3.4.3 for valid GPIO number.
Example:
dwm> gg
Usage: gg
dwm> gg 13
gpio13: 0

5.7

Sets GPIO as output and sets its value. See section 3.4.3 for valid GPIO number.
Example:
dwm> gs
Usage: gs
dwm> gs 13
gpio13: 1

5.8

Toggles GPIO pin (must be output). See section 3.4.3 for valid GPIO number.
Example:
dwm> gt
Usage: gt
dwm> gt 13
gpio13: 0

5.9

Show free memory on the heap.
Example:
dwm> f
[000014.560 INF] mem: free=3888 alloc=9184 tot=13072

5.10

Show info about running threads.
Example:
dwm> ps
ID NAME
1 idle
2 ser
3 svc
4 uwb
5 api
6 sd
7 ble
8 le

PRIO STACK USED
31 512 304
13 768 360
15 1024 512
5 2560 760
10 2048 1180
6 1024 352
7 1024 392
14 2048 688

SW-DWM1001-API-Guide-1.0

Page 61 of 74

DW1001 Firmware API Guide
9 pm
10 sh

5.11

17 512 304
16 2048 1096

pms

Show power managements tasks. IDL means that task is idle. USE means that task is allocated in the
power management.
Example:
dwm> pms
ID NAME
USE IDL ALM
0 ble
1 0 0
1 le
1 1 0
2 sh
1 0 0
3 -0 0 0
4 -0 0 0

5.12

reset

Reboot the system.
Example:
dwm> reset
/* node resets and boots in binary mode */

5.13

Show device uptime.
Example:
dwm> ut
[000003.680 INF] uptime: 00:07:49.210 0 days (469210 ms)

5.14

frst

Factory reset.
Example:
dwm> frst

5.15

twi

General purpose I2C/TWI read.
Example: use twi to read accelerometer id. This should return the same value as using “aid”
command. See section 5.16.
dwm> twi
Usage: twi [bytes to read (1 or 2)]
dwm> twi 0x33 0x0f 1

twi: addr=0x33, reg[0x0f]=0x33

SW-DWM1001-API-Guide-1.0

Page 62 of 74

DW1001 Firmware API Guide

5.16

aid

Read ACC device ID
Example:
dwm> aid
acc: 0x33

5.17

Read ACC values.
Example:
dwm> av
acc: x = 240, y = -3792, z = 16240
dwm> av
acc: x = 32, y = -3504, z = 15872
dwm> av
acc: x = 160, y = -3600, z = 16144

5.18

les

Show distances to ranging anchors and the position if location engine is enabled. Sending this
command multiple times will turn on/off this functionality.
Example:
dwm> les
1151[5.00,8.00,2.25]=6.48 0CA8[0.00,8.00,2.25]=6.51 111C[5.00,0.00,2.25]=3.18
1150[0.00,0.00,2.25]=3.16 le_us=2576 est[2.57,1.98,1.68,100]

5.19

lec

Show distances to ranging anchors and the position if location engine is enabled in CSV format.
Sending this command multiple times will turn on/off this functionality.
Example:
dwm> lec
DIST,4,AN0,1151,5.00,8.00,2.25,6.44,AN1,0CA8,0.00,8.00,2.25,6.50,AN2,111C,5.00,0.00,2.25,3.24,A
N3,1150,0.00,0.00,2.25,3.19,POS,2.55,2.01,1.71,98

5.20

lep

Show position in CSV format. Sending this command multiple times will turn on/off this functionality.
Example:
dwm> lep
POS,2.57,2.00,1.67,97

SW-DWM1001-API-Guide-1.0

Page 63 of 74

DW1001 Firmware API Guide

5.21

System info
Example:
dwm> si
[000077.340 INF] cfg:
[000077.340 INF] >fw1=x00022000
[000077.340 INF] board=DM1_A1
[000077.340 INF] cfg_ver=x00010500
[000077.350 INF] fw_ver=x01010200
[000077.350 INF] hw_ver=xDE410100
[000077.350 INF] opt=x03C10900
[000077.360 INF] fw_size[0]=x0001F000
[000077.360 INF] fw_size[1]=x0002F000
[000077.360 INF] fw_size[2]=x0002F000
[000077.370 INF] fw_csum[0]=x9445F89E
[000077.370 INF] fw_csum[1]=xF49DBF2A
[000077.370 INF] fw_csum[2]=xEB65F61F
[000077.380 INF] opt: LEDS LP UWB0 BLE I2C SPI UART
[000077.380 INF] mcu: temp=29.2 hfclk=rc:on lfclk=xtal:on
[000077.390 INF] uptime: 00:01:17.390 0 days (77390 ms)
[000077.390 INF] mem: free=2128 alloc=7224 tot=9352
[000077.400 INF] uwb: ch5 prf64 plen128 pac8 txcode9 rxcode9 sfd0 baud1
[000077.410 INF] uwb: tx_pwr=xC0/x25456585 125:250:500:norm[ms]=17:14:]
[000077.410 INF] uwb0: lna=0 xtaltrim=15 tx_delay=16472 rx_delay=16472
[000077.420 INF] uwb0: ID dev=xDECA0130 part=x1000113B lot=x10205EE9
[000077.430 INF] uwb0: panid=x0000 addr=xDECA7B1782D0113B
[000077.430 INF] mode: tn (act,twr,lp,nole)
[000077.440 INF] uwbmac: disconnected
[000077.440 INF] tn: upd_per=100000 upd_per_stat=100000 us
[000077.440 INF] tn: cnt=0 rtc:hrclk:devt dri=0.000000:0.000000:0.00000

5.22

nmg

Get node mode info.
Example:
dwm> nmg
mode: tn (act,twr,np,nole)

5.23

nmo

SW-DWM1001-API-Guide-1.0

Page 64 of 74

DW1001 Firmware API Guide
/* press enter twice to switch to shell mode after reset*/
DWM1001 TWR Real Time Location System

Copyright : 2016-2017 LEAPS and Decawave
License : Please visit https://decawave.com/dwm1001_license
Compiled : Jul 3 2017 12:33:40

Help

: ? or help

dwm> nmg
mode: tn (off,twr,np,nole)

5.24

nmp

Enable active offline option and resets the node.
Example:
dwm> nmp
/* press enter twice to switch to shell mode after reset*/
DWM1001 TWR Real Time Location System

Copyright : 2016-2017 LEAPS and Decawave
License : Please visit https://decawave.com/dwm1001_license
Compiled : Jul 3 2017 12:33:40

Help

: ? or help

dwm> nmg
mode: tn (pasv,twr,np,nole)

5.25

nma

Configures node to as anchor, active and reset the node.
Example:
dwm> nma
/* press Enter twice */

DWM1001 TWR Real Time Location System

SW-DWM1001-API-Guide-1.0

Page 65 of 74

DW1001 Firmware API Guide
License : Please visit https://decawave.com/dwm1001_license
Compiled : Jul 3 2017 12:33:40

Help

: ? or help

dwm> nmg
mode: an (act,-,-)

5.26

nmi

Configures node to as anchor - initiator, active and reset the node.
Example:
dwm> nmi
/* press enter twice */

DWM1001 TWR Real Time Location System

Copyright : 2016-2017 LEAPS and Decawave
License : Please visit https://decawave.com/dwm1001_license
Compiled : Jul 3 2017 12:33:40

Help

: ? or help

dwm> nmg
mode: ain (act,real,-)

5.27

nmt

Configures node to as tag, active and reset the node.
Example:
dwm> nmt
/* press enter twice */
DWM1001 TWR Real Time Location System

Copyright : 2016-2017 LEAPS and Decawave
License : Please visit https://decawave.com/dwm1001_license
Compiled : Jul 3 2017 12:33:40

Help

: ? or help

SW-DWM1001-API-Guide-1.0

Page 66 of 74

DW1001 Firmware API Guide

dwm> nmg
mode: tn (act,twr,np,le)

5.28

nmtl

Configures node to as tag, active, low power and resets the node.
Example:
dwm> nmtl
/* press enter twice */
DWM1001 TWR Real Time Location System

Copyright : 2016-2017 LEAPS and Decawave
License : Please visit https://decawave.com/dwm1001_license
Compiled : Jul 3 2017 12:33:40

Help

: ? or help

dwm> nmg
mode: tn (act,twr,lp,le)

5.29

bpc

Toggle UWB bandwidth / tx power compensation.
Example:
dwm> bpc
BW/TxPwr comp off
dwm> bpc
BW/TxPwr comp on

5.30

Show anchor list.
Example:
dwm> la
[003452.590 INF] AN: cnt=4 seq=x03
[003452.590 INF] 0) id=DECA5419E2E01151 seat=0 idl=0 seens=0 col=0 cl=000F nbr=000F fl=4002
opt=03C1B046 hw=DE41010
0 fw=01010101 fwc=7B033F01
[003452.600 INF] 1) id=DECA78A55EB00CA8 seat=1 idl=1 seens=119 col=0 cl=000F nbr=0000
fl=0000 opt=03C1B042 hw=DE410
© Decawave Ltd 2017

SW-DWM1001-API-Guide-1.0

Page 67 of 74

DW1001 Firmware API Guide
100 fw=01010101 fwc=7B033F01
[003452.620 INF] 2) id=DECAFCED8D50111C seat=2 idl=1 seens=103 col=0 cl=000F nbr=0000
fl=0000 opt=03C1B042 hw=DE410
100 fw=01010101 fwc=7B033F01
[003452.640 INF] 3) id=DECA51421A901150 seat=3 idl=0 seens=81 col=0 cl=000F nbr=0000 fl=0000
opt=03C1B042 hw=DE4101
00 fw=01010101 fwc=7B033F01

5.31

stg

Displays statistics.
Example:
dwm> stg
uptime: 0
memfree: 0
mcu_temp: 0
rtc_drift: 0.000000
ble_con_ok: 0
ble_dis_ok: 0
ble_err: 0
uwb0_intr: 0
uwb0_rst: 0
rx_ok: 56454
rx_err: 0
tx_err: 0
tx_errx: 0
bcn_tx_ok: 1661
bcn_tx_err: 0
bcn_rx_ok: 0
alma_tx_ok: 51
alma_tx_err: 0
alma_rx_ok: 0
cl_tx_ok: 0
cl_tx_err: 0
cl_rx_ok: 0
cl_coll: 0
fwup_tx_ok: 0
fwup_tx_err: 0
fwup_rx_ok: 0
svc_tx_ok: 0
svc_tx_err: 0
svc_rx_ok: 0
clk_sync: 0
twr_ok: 0
twr_err: 0
© Decawave Ltd 2017

SW-DWM1001-API-Guide-1.0

Page 68 of 74

DW1001 Firmware API Guide
res[0]: 0
res[1]: 0
res[2]: 0
res[3]: 0
res[4]: 0
res[5]: 0
res[6]: 0
res[7]: 0
tot_err: 0

5.32

stc

Clears statistics.
Example:
dwm> stc

5.33

tlv

Parses given TLV frame. See Section 4 for valid TLV commands.
Example: read node configuration
dwm> tlv 8 0
OUTPUT FRAME:
40 01 00 46 02 b0 00
Example: toggles GPIO pin 13
dwm> tlv 44 1 13
OUTPUT FRAME:
40 01 00

5.34

aurs

Set position update rate. See section 4.3.3 for more detail.
Example:
dwm> aurs
Usage aurs
dwm> aurs 10 20
err code: 0

5.35

aurg

Get position update rate. See section 4.3.4 for more detail.
Example:
dwm> aurg
err code: 0, upd rate: 10, 20(stat)
© Decawave Ltd 2017

SW-DWM1001-API-Guide-1.0

Page 69 of 74

DW1001 Firmware API Guide

5.36

apg

Get position of the node. See section 3.4.2 for more detail.
Example:
dwm> apg
x:100 y:120 z:2500 qf:100

5.37

aps

Set position of the node. See section 3.4.2 for more detail.
Example:
dwm> aps
Usage aps
dwm> aps 100 120 2500
err code: 0

5.38

acas

Configures node as anchor with given options. See section 3.4.8 for more detail. Note that this
command only sets the configuration parameters. To make effect of the settings, users should issue
s reset command, see section 5.12 for more detail.
Example:
dwm> acas
Usage acas
dwm> acas 0 0 1 1 2 0
err code: 0

5.39

acts

Configures node as tag with given options. See section 3.4.7 for more detail. Note that this
command only sets the configuration parameters. To make effect of the settings, users should issue
s reset command, see section 5.12 for more detail.
Example:
dwm> acts
Usage acts
dwm> acts 0 1 0 1 1 0 0 0
err code: 0

SW-DWM1001-API-Guide-1.0

Page 70 of 74

DW1001 Firmware API Guide

6 APPENDIX A – TLV TYPE LIST
Table 4 DWM1001 TLV type list

Comment

Type
Name
TYPE_CMD_POS_SET
TYPE_CMD_POS_GET
TYPE_CMD_UR_SET
TYPE_CMD_UR_GET
TYPE_CMD_CFG_TN_SET
TYPE_CMD_CFG_AN_SET
TYPE_CMD_CFG_GET
TYPE_CMD_CFG_SAVE
TYPE_CMD_SLEEP
TYPE_CMD_LOC_GET
TYPE_CMD_BLE_ADDR_SET
TYPE_CMD_BLE_ADDR_GET
TYPE_CMD_RESET
TYPE_CMD_VER_GET
TYPE_CMD_GPIO_CFG_OUTPUT
TYPE_CMD_GPIO_CFG_INPUT
TYPE_CMD_GPIO_VAL_SET
TYPE_CMD_GPIO_VAL_GET
TYPE_CMD_GPIO_VAL_TOGGLE
TYPE_CMD_STATUS_GET
TYPE_CMD_INT_CFG
TYPE_RET_VAL
TYPE_POS_XYZ
TYPE_POS_X
TYPE_POS_Y
TYPE_POS_Z
TYPE_UR
TYPE_CFG
TYPE_DIST
TYPE_RNG_AN_POS_DIST
TYPE_FW_VER
TYPE_CFG_VER
TYPE_HW_VER
TYPE_PIN_VAL
TYPE_STATUS
TYPE_CMD_N_POS_SET
TYPE_CMD_N_LOC_GET
TYPE_DUMMY

Value
1
2
3
4
5
7
8
9
10
12
15
16
20
21
40
41
42
43
44
50
52
64
65
66
67
68
69
70
72
73
80
81
82
85
90
128
130
0

Request: set position coordinates XYZ
Request: get position coordinates XYZ
Request: set position update rate
Request: get position update rate
Request: set configuration for the tag
Request: set configuration for the anchor
Request: get configuration data
Request: save configuration data
Request: sleep
Request: location get
Request: BLE address set
Request: BLE address get
Request: reset
Request: get FW version
Request: configure output pin and set
Request: configure input pin
Request: set pin value
Request: get pin value
Request: toggle pin value
Request: get status
Request: configure interrupts
Response: the previous request is ok or error
Response: position coordinates x,y,z
Response: position coordinate x
Response: position coordinate y
Response: position coordinate z
Response: update rate
Response: configuration data
Response: distances
Response: ranging anchor distances and positions
Response: firmware version
Response: configuration version
Response: hardware version
Response: pin value
Response: status
Request: nested command set position
Request: nested command location get
Reserved for SPI dummy byte

SW-DWM1001-API-Guide-1.0

Page 71 of 74

DW1001 Firmware API Guide

7 APPENDIX B – BIBLIOGRAPHY
1. nRF5 Getting Started, available from www.nordicsemi.com
2. IEEE 802.15.4‐2011 or “IEEE Std 802.15.4™‐2011” (Revision of IEEE Std 802.15.4-2006). IEEE
Standard for Local and metropolitan area networks— Part 15.4: Low-Rate Wireless Personal
Area Networks (LR-WPANs). IEEE Computer Society Sponsored by the LAN/MAN Standards
Committee. Available from http://standards.ieee.org/
3. DWM1001 Firmware User Guide, available from www.decawave.com
4. DWM1001 System Overview, available from www.decawave.com
5. DWM1001 on-board package, available from www.decawave.com
6. DWM1001 Host API package, available from www.decawave.com

SW-DWM1001-API-Guide-1.0

Page 72 of 74

DW1001 Firmware API Guide

8 DOCUMENT HISTORY
Table 5: Document History

Revision

Date

1.0

18-Dec-2017

Description
Initial release.

SW-DWM1001-API-Guide-1.0

Page 73 of 74

DW1001 Firmware API Guide

9 ABOUT DECAWAVE
Decawave is a pioneering fabless semiconductor company whose flagship product, the DW1000, is a
complete, single chip CMOS Ultra-Wideband IC based on the IEEE 802.15.4 standard UWB PHY. This
device is the first in a family of parts.
The resulting silicon has a wide range of standards-based applications for both Real Time Location
Systems (RTLS) and Ultra Low Power Wireless Transceivers in areas as diverse as manufacturing,
healthcare, lighting, security, transport, and inventory and supply-chain management.
For further information on this or any other Decawave product contact a sales representative as
follows: Decawave Ltd,
Adelaide Chambers,
Peter Street,
Dublin 8,
D08 T6YA,
Ireland.
mailto:sales@decawave.com
http://www.decawave.com/

SW-DWM1001-API-Guide-1.0

Page 74 of 74

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.5
Linearized                      : No
Page Count                      : 74
Language                        : en-IE
Tagged PDF                      : Yes
Author                          : bverso
Creator                         : Microsoft® Word 2013
Create Date                     : 2017:12:18 15:14:41+00:00
Modify Date                     : 2017:12:18 15:14:41+00:00
Producer                        : Microsoft® Word 2013

EXIF Metadata provided by EXIF.tools

DWM1001 API Guide