Abeeway Micro Tracker, Reference Manual

Page 1: ...Micro Tracker Reference Guide Micro Tracker Firmware V1 7 ABEEWAY SAS contact abeeway com www abeeway com ...

Page 2: ...rategies 18 5 Uplink messages 24 5 1 LoRa uplink transmission 24 5 2 Encoded form 25 5 3 Common message header 25 5 4 Heartbeat messages 26 5 5 Position messages 26 5 6 Energy Status messages 29 5 7 Activity status messages 29 5 8 Configuration messages 30 5 9 Frame pending messages 30 6 Downlink messages 31 6 1 Acknowledge token 31 6 2 Operational mode configuration 32 6 3 Position on demand 32 6...

Page 3: ...1 Page 3 of 39 11th october 2018 Restricted distribution 7 3 Tracking in low power mode beginning and end of motions only 37 7 4 Indoor only position 37 7 5 Fixed frequency positioning 37 7 6 Activity tracking 38 8 Hardware Specifications 39 ...

Page 4: ...ication and location when device is moving Geofencing applications 2 Features Multiple operating modes Motion tracking Get the tracker position at a given cycle when motion is detected Permanent tracking Get permanently a position of the tracker Start End motion tracking Get position messages during motion start and end events Activity tracking Monitor activity rate with embedded sensors OFF devic...

Page 5: ...and APPKEY for each device the most used ABP Activation by personalization that requires the following keys to connect to the network DEVEUI DEVADDR and NWKSKEY for each device Depending on your operator some actions need to be done to activate the transfer of the data through Abeeway servers Please refer to your vendor for more information 3 2 Fixation The device can be attached with the provided...

Page 6: ... policy the first position is always a WIFI one sent immediately after the beginning of the motion Permanent tracking mode The device reports its positions at ul_period frequency regardless the motion It uses the geoloc_sensor geolocation technology Heartbeat messages are sent if there are no uplink message during lora_period seconds Note 1 Having regular position can also be obtained using standb...

Page 7: ...on requests are done via LoRa downlink message The device answers with its current position The geolocation strategy chosen for geoloc_method is used to have this position 4 2 3 Alert position After a double short press on the button The tracker sends its position using geoloc_method geolocation strategy LoRa messages is tagged with an alert flag see uplink description for more detail Once done th...

Page 8: ...tising and not bonded to not disturb bonding process Terminology used WRITE_CMD ATT write command No answer expected WRITE_REQ ATT request command An answer is expected WRITE_RESP ATT response command NOTIFICATION ATT notification SCAN_REQ ATT scan request SCAN_RESP ATT scan response ERROR_RSP ATT error response READ_REQ ATT read request command An answer is expected READ_RESP ATT read response 4 ...

Page 9: ... switched off If the bonding fails the device must be switched off then on to restart the bonding procedure 4 3 3 BLE Secured connection A secured connection is established when a known Central device initiates a connection request and bounded information are present Security keys are stored in both tracker and Central device The connection is encrypted When the tracker communicates with the Clien...

Page 10: ... the central device and switches to its configured operational mode The bonding procedure restarts 4 3 4 Retrieve data from the tracker 4 3 4 1 Device Information The tracker exposes the Device Information Service allowing a bonded Client application to read information summarized in the table below Device Information Service UUID 0x180A UUID Value Perm Content 0x2a24 Model Number String READ Micr...

Page 11: ... every state change More details can be found here 4 3 4 4 Temperature The tracker exposes Environmental Sensing Service allowing bonded Client application to retrieve the current temperature in Degree Celsius Environmental Sensing UUID 0x181A UUID Value Perm Content 0x2A1F Temperature READ Current temperature More details can be found here 4 3 4 5 System Event At any time the client application m...

Page 12: ... Alert 1 Alert Medium not used 2 Alert High triggered with a short button press It is up to the Client application to decide how it reacts according to the level of alert received 4 3 5 2 Immediate Alerts received by the tracker The Client application is allowed to send immediate alerts to the tracker Immediate Alert Service UUID 0x1802 UUID Value Perm Content 0x2a06 Alert Level WRITE_CMD 0x00 No ...

Page 13: ...bcd123 On every write command on its characteristic value the tracker sends back the operation result through a NOTIFICATION Before receiving a notification the Client application must subscribe to the notification handler This is done by writing 0x01 to its related Client Characteristic Configuration Descriptor cccd Once done the Client application can receive such notifications The diagram below...

Page 14: ...lid Parameter ID or value 0x03 Example To set the parameter having the identifier 0x05 with the value 0x01 the write command WRITE_CMD 0x010500000001 should be sent A NOTIFICATION will be received in response with 0x00 if the write operation is a success 4 3 6 3 Read parameters Once the notification has been enabled the Client application can read a parameter value by sending a write command WRITE...

Page 15: ...odes 4 3 7 1 Introduction The Client application can change and retrieve the tracker operational mode by sending either a WRITE_REQ or a READ_REQ using the following Abeeway primary service Abeeway Primary Service UUID 00008A45 1212 efde 1523 785feabcd123 Operational mode Characteristic UUID Permission 00002741 1212 efde 1523 785feabcd123 WRITE_REQ READ The Client application should first discover...

Page 16: ...rror Response ERROR_RSP shown below Operational mode response from Error Response byte 0 Error code 0x81 Invalid operational mode 4 3 7 3 Read the operational mode The Client application can read the current operational mode by sending a Read request READ_REQ The Read Response READ_RSP associated to this command is shown below Read the operational mode value response Bytes 0 3 Current operational ...

Page 17: ...nagement When the battery level goes below 3 2V the device is automatically move to the off mode no more payload sent and a shutdown payload with the reason low battery is sent While the battery is not charged the device stays in this mode and after any button press the Low battery melody is played except if the battery level goes below 2 8V When the battery level is above 3 2V a long button press...

Page 18: ...er in not bound Waiting for a bond BLE bond failure Bond process unsuccessful BLE bond success Bond process successful BLE alert Alert activated from connected device using BLE Note 1 A zip file containing the different sounds can be found in the same folder than this document 4 6 Geolocation strategies 4 6 1 Main operating modes The following geolocation policies geoloc_sensor parameter are used ...

Page 19: ... used to compute a position 4 6 3 Geolocation technology description 4 6 3 1 GPS When doing a cold start the tracker uses systematically a timeout of 5 minutes instead of the configured one To complete a position the GPS module expects one of the two following conditions to be achieved The GPS_convergence timeout time let to the GPS module to have a more precise position The gps_ehpe value is belo...

Page 20: ...t parameter Once the scan is done BSSID are sent via LoRa with the related RSSI and the position calculation is done in our server In a multi technology geolocation strategy a WIFI scan with less than 3 BSSID triggers a technology switch Regardless the number of BSSID including 0 a WIFI position is sent In the case where the communication fails with the WIFI module the device sends either a WIFI f...

Page 21: ...ered as successful at least three BSSID triggers a WIFI position message Otherwise the tracker tries immediately the next geolocation technology GPS or LP GPS in the same geolocation cycle That way two geolocation technologies are used if needed before sending a given position uplink Geoloc_timeout gps_timeout or agps_timeout depending on the used technology If geoloc_timeout wifi_time 8 seconds i...

Page 22: ...Micro Tracker Reference Guide FW 1 7 V1 1 Page 22 of 39 11th october 2018 Restricted distribution ...

Page 23: ...Micro Tracker Reference Guide FW 1 7 V1 1 Page 23 of 39 11th october 2018 Restricted distribution In multimode WIFI LPGPS WIFI GPS geoloc_strategy 9 ...

Page 24: ...he partial or whole configuration of the trackers Shutdown message 0x09 sent when the tracker is set off Debug message 0xFF Internal use only Note 1 Activity status message and configuration message share the same identifier They are differentiated by another field 5 1 LoRa uplink transmission 5 1 1 Strategy used The tracker follows the LoRa requirements regarding the transmission like duty cycle ...

Page 25: ...the following algorithms static float _step_size float lo float hi unsigned nbits unsigned nresv return 1 0 1 nbits 1 nresv hi lo float mt_value_decode uint32_t value float lo float hi unsigned nbits unsigned nresv return value nresv 2 _step_size lo hi nbits nresv lo Where nbits number of bits used to encode lo min value that can be encoded hi max value that can be encoded nresv number of reserved...

Page 26: ...ing on the message type Decoding of the encoded form is detailed in the Encoded form section 5 4 Heartbeat messages Byte 0 4 Byte 5 Byte 6 8 optional Header Cause FW version Cause Last reset cause FW version Firmware version on the device it is sent only twice a day 5 5 Position messages Common header Data Byte 0 3 Byte 4 1 Header Ack opt Position Information Note 1 The size of data part depends o...

Page 27: ... lo 0 hi 1000 nbits 8 nresv 0 The step is 5 9 meters Encoded form is detailed in the Encoded form section 5 5 2 GPS timeout payload Common header Data Byte 0 4 Byte 5 Byte 6 Byte 7 Byte 8 Byte 9 Header Cause C N 0 C N 1 C N 2 C N 3 Cause Timeout cause 0 User timeout cause C N 0 Carrier over noise dBm for the first satellite seen C N 1 Carrier over noise dBm for the second satellite seen C N 2 Carr...

Page 28: ... Scan failure 2 Antenna unavailable 3 WIFI not supported on this device Notes 1 Most of time a WIFI timeout occurs due to a low battery condition 2 v_bat encoding uses lo 2 8 hi 4 2 nbits 8 nresv 2 It is expressed in volt with a step of 5 5mV 3 Encoded form is detailed in the Encoded form section 5 5 5 WIFI BSSID payload Common header Data Byte 0 4 Byte5 B 6 11 Byte12 B 13 18 Byte19 B 20 25 Byte26...

Page 29: ...es 1 The payload contains the listened BLE beacon up to 4 it is configurable using ble_beacon_count parameter during ble_beacon_timeout delay 2 If less than 4 BLE beacons are listened the payload will be reduced 5 5 7 BLE failure payload Common header Data Byte 0 4 Byte 5 Header Error Error 0 BLE is not responding 1 internal error 2 shared antenna not available 3 scan already on going 4 No beacon ...

Page 30: ...rameter x coded on 5 bytes as follow First byte Parameter identifier Refer to the parameter identifier in the section Parameters configuration Next 4 bytes Parameter value Unsigned 32 bits value in big endian format MSB first 5 9 Frame pending messages Byte 0 Byte 1 Type 0 Acknowledge token When additional messages are available on a gateway this uplink message is sent to trigger the gateway sendi...

Page 31: ...e unknown message type bad length is discarded However the ack token is updated even if the message is discarded if the payload is at least 2 bytes long 2 The LoRa port to be used for downlink is 2 6 1 Acknowledge token It provides a way to indicate to the application that a given message has been received by the tracker The acknowledge token is transmitted in every uplink message and it is update...

Page 32: ...ample Position on demand message with ack token of 2 0x0102 The tracker will answer with a position message 6 4 Request device configuration Byte 0 Byte 1 Byte 2 21 0x03 ACK Parameter ID list optional Parameter ID list List of requested parameters identifiers Each single byte contains a single identifier The list can have up to 20 parameters Parameter IDs are the one used to configure the device s...

Page 33: ...ID New value2 31 00 The parameters identifier and the values are given in the following tables 6 6 1 Parameters for operational modes Parameter ID Unit Range Description ul_period 0x00 second 60 86400 min 30 for US Period of position or activity messages in motion start end activity or permanent operating mode lora_period 0x01 second 300 86400 Period of LoRa heartbeat messages geoloc_sensor 0x05 n...

Page 34: ...before sending a GPS timeout message gps_ehpe 0x0B meter 0 100 Acceptable GPS horizontal error for GPS geolocation gps_convergence 0x0C second 0 300 Time let to the GPS module to refine the calculated position gps_standby_timeout 0x11 second 10 7200 Duration of the GPS standby mode before going OFF Low power GPS agps_timeout 0x0A second 30 250 Timeout for LPGPS scans before sending the timeout mes...

Page 35: ... of the Energy status report When 0 no energy status report is transmitted Not used for micro trackers config_flags 0x0D none Configuration flags bit 0 Frame pending mechanism bit 1 Activate long button press to switch to off mode bit 2 Double short press configuration Alert 0 vs SOS 1 bit 3 Send a configuration uplink message in response to a configuration modification downlink Used to confirm th...

Page 36: ...e motion tracking ul_period 300 5 minutes geoloc_sensor 1 GPS only gps_timeout 290s gps_ehpe 3m gps_convergence 120s gps_standby_timeout 3600s 1 hour transmit_strat 2 Results Accurate GPS positions are obtained each five minutes under good condition weather 7 2 Low power configuration Case description Long battery life time with position only when desired Single position on request High position c...

Page 37: ...ast tracking of an asset inside buildings or in dense urban area Proposal configuration Operational mode Motion tracking ul_period 120 2 minutes geoloc_sensor 0 WIFI only geoloc_method 0 WIFI only transmit_strat 4 Results The device sends its position once every 2 minutes when moving using WIFI mode only Medium power consumption due to the fast tracking 7 5 Fixed frequency positioning Case descrip...

Page 38: ...eolocation needed The focus is the activity measure of an asset Proposed configuration Operational mode Activity tracking ul_period 1600 30 minutes transmit_strat 2 Results When moving the device sends an activity message every 30 minutes containing a counter which is incremented on each motion detection Note 1 To locate the tracker the position on demand downlink can be used In this case the conf...

Page 39: ...Micro Tracker Reference Guide FW 1 7 V1 1 Page 39 of 39 11th october 2018 Restricted distribution 8 Hardware Specifications Refer to the related datasheet ...