3/21/2018 Pozyx - centimeter positioning for arduino

Pozyx
Accurate positioning

Home (https://www.pozyx.io/) > Documentation (https://www.pozyx.io/Documentation) >

Tutorials (https://www.pozyx.io/Documentation) > Tutorial 1: Ready to range

Tutorial 1: Ready to range

Go to Python version (https://www.pozyx.io/Documentation/Tutorials/ready_to_range/Python)

Ready to range
This is the first general Pozyx tutorial. If you haven’t read the getting started
(https://www.pozyx.io/Documentation/Tutorials/getting_started/Arduino), please do so and
install the necessary tools and libraries.

This example requires two Pozyx devices and one supported Arduino device. Remember that
we recommend the Arduino Uno Rev. 3. If all tools are installed, open up the ready to range
example in the Arduino IDE under File > Examples > Pozyx > ready_to_range.

In this example, the distance between the two devices is measured and the onboard LEDs will
show in which range the devices are to each other. The destination Pozyx's LEDs will be
doing the same, commanded by our local Pozyx. The LEDs' changes with respect to the
distance is sketched in the figure below:

https://www.pozyx.io/Documentation/Tutorials/ready_to_range/Arduino 1/8
3/21/2018 Pozyx - centimeter positioning for arduino

Plug and play

To see the tutorial in action before we delve into the code, the parameters will need to be
changed to match your destination device's ID.

You also have to set the Arduino IDE’s serial monitor’s baudrate to 115200. At the top of the
Arduino sketch, we find the sketch’s parameters:

21. uint16_t destination_id = 0x6670; // the network ID of the ranging destination

22. signed int range_step_mm = 1000; // distance between each LED lighting up.
23.
24. uint8_t ranging_protocol = POZYX_RANGE_PROTOCOL_PRECISION; // the ranging protocol
to use.
25.
26. uint16_t remote_id = 0x605D; // the network ID of the remote device
27. bool remote = false; // whether to use the given remote device for ra
nging

You’ll have to change the destination_id parameter to the ID of your destination Pozyx.
Optionally, you can change the range_step_mm as well, which will make the distance range
indicated by the LEDs either higher or lower depending on your change. remote_id and
remote will allow measuring the distance between two remote Pozyx devices, and will be
explained at the end of this tutorial, so don't change those for now.

The ranging_protocol is a new feature that allows changing between two ranging protocols:
POZYX_RANGE_PROTOCOL_FAST and POZYX_RANGE_PROTOCOL_PRECISION.
Precision is slower, but more precise and can be used on longer ranges. The fast protocol
needs to warm up for about 100ms before. If this has piqued your interest, definitely check the
system performance section in the datasheet!

If you’ve correctly changed your device ID, run the example! You should see that the LEDs of
your two Pozyx devices now burn identically, and change when you move them closer or
further apart. The output you’re receiving will look like this:

16691ms, 7564mm, -93dBm

16753ms, 7718mm, -91dBm
16830ms, 7779mm, -92dBm
etc...

The first value is the device’s timestamp of the range measurement. The second value then is
the measured distance between both devices. The third value, expressed in dBm, signifies
the signal strength, varying between -79 and -103 dB typically. You might be reading either:

0ms, 0mm, 0dB

or
ERROR: ranging

https://www.pozyx.io/Documentation/Tutorials/ready_to_range/Arduino 2/8
3/21/2018 Pozyx - centimeter positioning for arduino

If this is the case, you probably miswrote the ID (did you write it with the 0x prefix?) or your
device is not in range currently. As the LEDs will only indicate differences of a meter by
default, keeping the distance between a couple of meters for this first try is recommended. If
the error persists despite having put in everything correctly, check out the troubleshooting
guide (https://www.pozyx.io/Documentation/Tutorials/troubleshoot_basics/Arduino).

If you’re getting gibberish, you probably forgot to set your serial monitor’s baudrate to 115200.

The code explained

Now that you’ve had a taste of what exactly this example provides, let’s look at the code that
provides this functionality. We’ll begin with the imports and the setup functions, and then go
into the continuous loop.

Imports

13. #include <Pozyx.h>

14. #include <Pozyx_definitions.h>
15. #include <Wire.h>

We can see that the sketch requires both “Pozyx.h” and “Pozyx_definitions.h”, and the
"Wire.h" file for the I2C.. “Pozyx.h” provides the library’s functionality, “while
Pozyx_definitions.h” provides constants such as POZYX_SUCCESS and POZYX_FAILURE , register
addresses… these are useful to keep your code working with both current, previous, and
future versions of the library.

Setup

This function will run only once, when the Arduino is powered on or reset. It sets up the serial
communication at 115200 baud, so be sure to set your Serial Monitor to this same baudrate if
you hadn’t already. The Pozyx is then initialized by calling Pozyx.begin
(https://www.pozyx.io/Documentation/Datasheet/Arduino#begin)(), which checks whether the
Pozyx is connected and working properly.

https://www.pozyx.io/Documentation/Tutorials/ready_to_range/Arduino 3/8
3/21/2018 Pozyx - centimeter positioning for arduino

29. void setup(){

30. Serial.begin(115200);
31.
32. if(Pozyx.begin (https://www.pozyx.io/Documentation/Datasheet/Arduino#begin)() ==
POZYX_FAILURE){
33. Serial.println("ERROR: Unable to connect to POZYX shield");
34. Serial.println("Reset required");
35. delay(100);
36. abort();
37. }
38. // setting the remote_id back to NULL will use the local Pozyx
39. if (!remote){
40. remote_id = NULL;
41. }
42. Serial.println("------------POZYX RANGING V1.0------------");
43. Serial.println("NOTES:");
44. Serial.println("- Change the parameters:");
45. Serial.println("\tdestination_id (target device)");
46. Serial.println("\trange_step (mm)");
47. Serial.println();
48. Serial.println("- Approach target device to see range and");
49. Serial.println("led control");
50. Serial.println("------------POZYX RANGING V1.0------------");
51. Serial.println();
52. Serial.println("START Ranging:");
53.
54. // make sure the pozyx system has no control over the LEDs, we're the boss
55. uint8_t led_config = 0x0;
56. Pozyx.setLedConfig (https://www.pozyx.io/Documentation/Datasheet/Arduino#setLedC
onfig)(led_config);
57. // do the same with the remote device
58. Pozyx.setLedConfig (https://www.pozyx.io/Documentation/Datasheet/Arduino#setLedC
onfig)(led_config, destination_id);
59. }

Depending on the value of the remote parameters, we set the remote_id to use either the
local or a remote Pozyx. After initializing the Pozyx, we configure both the local and
destination Pozyx’s LEDs to be in our control instead of displaying system status, which is
their default behavior. This is done by setting the POZYX_CONFIG_LEDS register’s value to
0b00000000 on both devices. While the library’s functionality hides away a lot of low-level
functionality, it’s important to know how to access registers directly low-level and to find your
way in the register overview
(https://www.pozyx.io/Documentation/Datasheet/RegisterOverview) for your own personal
goals. These core low-level functions are:

static int regRead(uint8_t reg_address, uint8_t *pData, int size);

static int regWrite(uint8_t reg_address, const uint8_t *pData, int size);
static int regFunction(uint8_t reg_address, uint8_t *params, int param_size,
uint8_t *pData, int size);

and the remote equivalents

https://www.pozyx.io/Documentation/Tutorials/ready_to_range/Arduino 4/8
3/21/2018 Pozyx - centimeter positioning for arduino

static int remoteRegWrite(uint16_t destination, uint8_t reg_address, uint8_t

*pData, int size);
static int remoteRegRead(uint16_t destination, uint8_t reg_address, uint8_t
*pData, int size);
static int remoteRegFunction(uint16_t destination, uint8_t reg_address, uint8_t
*params, int param_size, uint8_t *pData, int size);

Loop

Let’s move on to the loop function, which will run continuously and executes the ranging
functionality.

61. void loop(){

62. device_range_t range;
63. int status = 0;
64.
65. // let's perform ranging with the destination
66. if(!remote)
67. status = Pozyx.doRanging (https://www.pozyx.io/Documentation/Datasheet/Arduino
#doRanging)(destination_id, &range);
68. else
69. status = Pozyx.doRemoteRanging (https://www.pozyx.io/Documentation/Datasheet/A
rduino#doRemoteRanging)(remote_id, destination_id, &range);
70.
71. if (status == POZYX_SUCCESS){
72. Serial.print(range.timestamp);
73. Serial.print("ms, ");
74. Serial.print(range.distance);
75. Serial.print("mm, ");
76. Serial.print(range.RSS);
77. Serial.println("dB");
78.
79. // now control some LEDs; the closer the two devices are, the more LEDs will b
e lit
80. if (ledControl(range.distance) == POZYX_FAILURE){
81. Serial.println("ERROR: setting (remote) leds");
82. }
83. }
84. else{
85. Serial.println("ERROR: ranging");
86. }
87. }

In the loop function, ranging is performed with the Pozyx library’s doRanging function. The
range information will be contained in device_range .

When we want to perform ranging on a remote Pozyx, we use doRemoteRanging instead. The
device_range variable is an instance of the device_range_t structure. Looking at its
definition (in Pozyx.h) we can see that the device range consists of three variables providing
information about the measurement. By using the __attribute__((packed)) attribute, the
struct’s bytes are packed together.

https://www.pozyx.io/Documentation/Tutorials/ready_to_range/Arduino 5/8
3/21/2018 Pozyx - centimeter positioning for arduino

typedef struct __attribute__((packed))_device_range {

uint32_t timestamp;
uint32_t distance;
int8_t RSS;
}device_range_t;

In a wireless system, we don’t want to waste transmission time on unused padding bytes,
after all. The library provides similar structures for all relevant data structures related to
Pozyx, which you'll encounter if you follow the other tutorials and get into further reading. The
measurement consists of the timestamp in milliseconds, the measured distance in mm and
the RSS-value (the received signal strength) expressed in dBm. Depending on the UWB
settings, -103 dBm is more or less the lowest RSS at which reception is possible, and -80 is a
normal value for devices close to each other. Upon a successful measurement, these three
variables are printed and the LEDs are updated with the ledControl function.

ledControl

89. int ledControl(uint32_t range){

90. int status = POZYX_SUCCESS;
91. // set the LEDs of the pozyx device
92. status &= Pozyx.setLed (https://www.pozyx.io/Documentation/Datasheet/Arduino#set
Led)(4, (range < range_step_mm), remote_id);
93. status &= Pozyx.setLed (https://www.pozyx.io/Documentation/Datasheet/Arduino#set
Led)(3, (range < 2*range_step_mm), remote_id);
94. status &= Pozyx.setLed (https://www.pozyx.io/Documentation/Datasheet/Arduino#set
Led)(2, (range < 3*range_step_mm), remote_id);
95. status &= Pozyx.setLed (https://www.pozyx.io/Documentation/Datasheet/Arduino#set
Led)(1, (range < 4*range_step_mm), remote_id);
96.
97. // set the LEDs of the destination pozyx device
98. status &= Pozyx.setLed (https://www.pozyx.io/Documentation/Datasheet/Arduino#set
Led)(4, (range < range_step_mm), destination_id);
99. status &= Pozyx.setLed (https://www.pozyx.io/Documentation/Datasheet/Arduino#set
Led)(3, (range < 2*range_step_mm), destination_id);
100. status &= Pozyx.setLed (https://www.pozyx.io/Documentation/Datasheet/Arduino#set
Led)(2, (range < 3*range_step_mm), destination_id);
101. status &= Pozyx.setLed (https://www.pozyx.io/Documentation/Datasheet/Arduino#set
Led)(1, (range < 4*range_step_mm), destination_id);
102.
103. // status will be zero if setting the LEDs failed somewhere along the way
104. return status;
105. }

The ledControl function turns the LEDs on or off if they fall within a certain range, using a
simple boolean expression, for example range < 3*range_step_mm , which returns true if the
distance is within three times the range_step_mm parameter.
Nothing is stopping you from designing your own ledControl function, where you can use
other indexes or, as a challenge, even use the four LEDs as 4 bits indicating up to sixteen
range_step_mm differences instead of four.

Remote operation
https://www.pozyx.io/Documentation/Tutorials/ready_to_range/Arduino 6/8
3/21/2018 Pozyx - centimeter positioning for arduino

As you have probably seen when looking at the code and the register functions, Pozyx is
capable of communicating with remote Pozyx devices: thanks to UWB communication, we can
perform every local functionality on a remote device as well. In this tutorial, this can be done
by changing the remote_id and remote parameters. Setting remote = true; will perform all
the functionality on a device with ID remote_id , so you will need to set that ID correctly as
well and own three devices to perform remote ranging.

A general rule with the Pozyx API is that almost every function has remote_id as a keyword
argument, which allows the writing of code that can easily switch between being executed
locally or remotely, as seen in this example. When remote_id is uninitialized, the function will
be executed locally.

The disadvantages of working remotely need to be kept in mind, however. The possibility of
losing connection, something that is much harder with a cable. A delay, as the UWB
communication between both devices is not instantaneous. And you need a local controller,
which is an extra device in your setup. In turn, you gain a lot of mobility, as the remote device
only needs to be powered, not needing a controller.

This concludes the first Pozyx example. In the next example

(https://www.pozyx.io/Documentation/Tutorials/ready_to_localize/Arduino), we’ll cover
positioning and the necessary setup to perform positioning successfully.

Home (https://www.pozyx.io/) > Documentation (https://www.pozyx.io/Documentation) >

Tutorials (https://www.pozyx.io/Documentation) > Tutorial 1: Ready to range

POZYX CONTACT
Home () Info: [email protected]
Company information Sales: [email protected]
(https://www.pozyx.io/welcome/pozyxLabs) Support: [email protected]
Kickstarter Facebook (https://www.facebook.com/pozyx)
(https://www.kickstarter.com/projects/pozyx/pozyx-
accurate-indoor-positioning-for-arduino)
STAY INFORMED
Subscribe to our newsletter

https://www.pozyx.io/Documentation/Tutorials/ready_to_range/Arduino 7/8
3/21/2018 Pozyx - centimeter positioning for arduino

Email Address *
Subscribe

SHARE
665 Tweet Share
Like

https://www.pozyx.io/Documentation/Tutorials/ready_to_range/Arduino 8/8