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