Pozyx Arduino Library Documentation

84 Pages·2017·0.28 MB·English

Pozyx Arduino Library Documentation
Release 1.2.2
Samuel Van de Velde, Vadim Vermeiren, Laurent Van Acker
Jun 24, 2020

CONTENTS:
1 ArduinoPozyx 1
1.1 About . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.3 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.4 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
2 Gettingstarted 3
2.1 Arduino . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2 Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.3 Requiredheaders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.4 ConnectingtothePozyx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.5 Generalphilosophy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.6 Readingdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.7 Writingdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.8 Performingfunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.9 Remote . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.10 Savingwritableregisterdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.11 Findingouttheerror . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3 Troubleshooting 9
3.1 FAQ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.2 Lostadevice? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.3 Contactingsupport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4 PozyxClassFull 11
4.1 Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.2 Systemfunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.3 Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.4 Devicelist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
4.5 Positioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
4.6 SensorData. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
5 PozyxClassFull 43
5.1 Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
5.2 Protected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
5.3 Private . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
5.4 Undocumented... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Index 77
i
ii
CHAPTER
ONE
ARDUINO POZYX
1.1 About
ArduinoPozyxisanArduinolibraryprovidingahigh-levelinterfacetoaPozyxshieldattachedtotheArduino,making
thePozyxshieldcompatiblewithArduinoUno,ArduinoMega,andArduinoNano.
1.2 Features
• Easytouse,allowingbothhigh-levelandlow-levelinterfacingwiththePozyxdevice.
• StraightforwardAPI
• SpecializedstructsforallimportantPozyxdata.
• CompatiblewithArduinoUno,Mega,andNano.
1.3 Requirements
• ArduinoWebIDEorArduinoIDE1.6+
1.4 Installation
1.4.1 Web IDE
Whenyou’reusingtheWebIDE,ArduinoPozyxshouldinstallautomagicallywhenyouinclude<Pozyx.h>.
1.4.2 Arduino Library Manager
Currently,theArduinoPozyxlibraryiseasilyinstallablefromtheArduinoLibrarymanager.
1
PozyxArduinoLibraryDocumentation,Release1.2.2
1.4.3 From source
Toinstallfromsource,you’llhavetodownloadthesourcefilesfirstandputtheminyourArduinosketchbooklibraries
folder. Youcandothiseitherby:
• git clone https://github.com/pozyxLabs/Pozyx-Arduino-library and move the folder
toyoursketchbooklibraries
• Downloaditfromtherepositoryandextractingit.
• Downloadingthezipfiledirectly,andextractingit.
2 Chapter1. ArduinoPozyx
CHAPTER
TWO
GETTING STARTED
Note: Inthistext,thewordtagandshieldwillbeusedinterchangeably.
2.1 Arduino
Ifyou’renotfamiliarwiththeArduinoplatformasawhole,thisisagoodplacetogetstartedandsetupwithtesting
yourArduino’sbasicfunctionality.
2.2 Setup
2.2.1 Role of Arduino
TheArduinocommunicatestothePozyxdeviceusingtheI2Cprotocol.
SomethingthathasbeenconfusingtoalotofpeopleishowtosetupthePozyxonArduino,especiallywhenmultiple
devicescomeintoplay.
AndwiththeadditionalexistenceofthePythonlibrarythatprovidesdirectUSBaccesstothePozyx, wehaveeven
seenpeopletryingtousethePythonlibrarywithanArduinowhichhadaPozyxshieldattached,whichofcoursedid
notwork.
Inthissection,weintendtogiveyouinsightofthehardwareyouneed!
2.2.2 Pozyx on Arduino
The only Pozyx device that needs an Arduino is the one you’re running the positioning/ranging sketches on. This
deviceiscalledthemasterdevice,asthiswillalsodirecttheoperationofotherPozyxdevicesthroughUWBcommu-
nication.
3
PozyxArduinoLibraryDocumentation,Release1.2.2
2.2.3 Remote Pozyx devices on Arduino
RemotePozyxtagsdon’tneedtohaveanArduinoattached! Thisisanimportantpoint. Theyjustneedtobepowered.
PhonepowerbanksplaywellwiththemicroUSBportonthetags!
Onlyperformpositioningandrangingfunctionsonyourmasterdevice.
Note: YoumightwanttohaveanArduinoonremoteshieldsifyouwanttoreadtheirsensordatalocally. However,
donotusefunctionslikepositioningandrangingonmultipledevicesatthesametime!
AnexampleistheCloudexamplewhereanArduinoisusedtoreadthetag’sposition. Inthisexample,thepositioning
isdirectedbythePozyxattachedtotheserver,andtheArduinochecksthetag’sstatustoseewhetheranewposition
hasbeencalculated.
2.2.4 Pozyx via USB
InsteadofusinganArduinolocally,youcanskiptheArduinoanduseanUSBcabledirectly.
Thishasadvantageslike:
• Verycrossplatformserialprotocol.
• EasytousePythonprogramminglanguageforflexiblefunctionality(andextendability).
• Computercanbeaspowerfulasyouwant.
• Youcanimplementtheserialcommunicationinanyotherprogramminglanguage.
Butdisadvantagestoo:
• Arduinoisverycheapandsmallstandalonehardware,comparedtoaRaspberryPiorregularPC.
• ThenewArduinoWebIDEisamazing.
• You’recomfortablewithArduinoprogrammingbutnotwithPython.
Ultimately,thedecisionwhichyouwanttousedependsonyourapplicationandyouravailablehardware.
ThedocumentationforusingUSBdirectlycanbefoundhere.
2.3 Required headers
TousethePozyxlibrary,youhavetoincludethefollowingheaders:
#include <Pozyx.h>
#include <Pozyx_definitions.h>
4 Chapter2. Gettingstarted
PozyxArduinoLibraryDocumentation,Release1.2.2
2.4 Connecting to the Pozyx
ConnectingwiththePozyxisverystraightforward. Asafewayispresentedhere:
void setup(){
Serial.begin(115200);
if(Pozyx.begin() == POZYX_FAILURE){
Serial.println(F("ERROR: Unable to connect to POZYX shield"));
Serial.println(F("Reset required"));
delay(100);
abort();
}
}
Withthis,youinitializethePozyxandcanusetheentireAPIintherestofyourscript!
2.5 General philosophy
Essentially,youcandothreethingswithPozyx:
1. Readingregisterdata,whichincludessensorsandthedevice’sconfiguration
2. Writing data to registers, making it possible to change the device’s configuration ranging from its positioning
algorithmtoitsveryID.
3. PerformingPozyxfunctionslikeranging,positioning,savingthedevice’sconfigurationtoitsflashmemory...
AllthesethingsarepossibletodoontheshieldconnectedtoyourArduino,andpoweredremotedevicesaswell. In
thissectionwe’llgooverallofthese.
2.6 Reading data
ToreaddatafromthePozyx,asimplepatternisfollowed. Thispatterncanbeusedwithalmostallmethodsstarting
withthewords‘get’:
1. Initializetheappropriatecontainerforyourdataread.
2. Passthiscontaineralongwiththegetfunctions.
3. Checkthestatustoseeiftheoperationwassuccessfulandthusthedatatrustworthy.
YoucanseethesamepatterninactionabovewhenreadingtheUWBdata.
// initialize the data container
uint8_t who_am_i;
uint8_t status = Pozyx.getWhoAmI(&whoami);
// check the status to see if the read was successful. Handling failure is covered
later.
˓→
if (status == POZYX_SUCCESS) {
// print the container. Note how a SingleRegister will print as a hex string by
default.
˓→
Serial.println(who_am_i); // will print '0x43'
}
(continuesonnextpage)
2.4. ConnectingtothePozyx 5
PozyxArduinoLibraryDocumentation,Release1.2.2
(continuedfrompreviouspage)
# and repeat
# initialize the data container
acceleration_t acceleration;
# get the data, passing along the container
Pozyx.getAcceleration_mg(&acceleration);
# initialize the data container
euler_angles_t euler_angles;
# get the data, passing along the container
Pozyx.getEulerAngles_deg(&euler_angles)
2.7 Writing data
Writingdatafollowsasimilarpatternasreading,butmakingacontainerforthedataisoptional. Thispatterncanbe
usedwithallmethodsstartingwiththewords‘set’:
1. (Optional)Initializetheappropriatecontainerwiththerightcontentsforyourdatawrite.
2. Passthiscontainerortherightvaluealongwiththesetfunctions.
3. Checkthestatustoseeiftheoperationwassuccessfulandthusthedatawritten.
Sometypicalwriteoperations
# initialize Pozyx as above
uint8_t status = Pozyx.setPositionAlgorithm(POZYX_POS_ALG_UWB_ONLY);
// Note: this shouldn't ever happen when writing locally.
if (status == POZYX_FAILURE) {
Serial.println("Settings the positioning algorithm failed");
}
Pozyx.setPositioningFilter(FILTER_TYPE_MOVING_AVERAGE, 10);
2.8 Performing functions
Positioning,ranging,configuringtheanchorsforatagtouse... Whilethelineissometimesthin,thesearen’tperse
writesorreadsastheyareimplementedasfunctionsonthePozyx.
A Pozyx device function typically can take a container object for storing the function’s return data, and a container
objectforthefunctionparameters.
Forexample,whenaddingananchortoatag’sdevicelist,theanchor’sIDandpositionarethefunction’sparameters,
but there is no return data. Thus, the function addDevice only needs a container object containing the anchor’s
properties.
Inthelibrary,functionwrappersarewritteninsuchawaythatwhennoparametersarerequired,theyarehiddenfrom
theuser,andthesamegoesforreturndata.
// assume an anchor 0x6038 that we want to add to the device list and
// immediately save the device list after.
device_coordinates_t anchor;
anchor.network_id = 0x6038;
(continuesonnextpage)
6 Chapter2. Gettingstarted