This device is a power-efficient GPS tracker sending data via LoRaWAN. There are three key messages being sent by the device:
settings - port 3 - current device settings - only upon boot, change or requeststatus - port 2 - (legacy, not enabled in latest version anymore) device status message being sent with the specified status_interval in minutes - recommended to do this every 24hgps - port 1 - gps location - gps packet is set based on the settings and various intervals defined there.status+gps - port 12 - device status message being sent with the specified status_interval in minutes - recommended to do this every 24h, combined with last known gps position. Particularly useful if the gps fix interval is longer then the status interval.gps log - port 11 - GPS positions are stored in flash memory, last 500 locations. Theya re requested with a command and sent out as SF7 packets of 200 bytes.The magnetic REED switch is put in place to put the device in hibernation for transport purposes or prior to installation. Removing the magnet will initialize the operation in 60 seconds of removing it. Note that putting the device in hibernation performs a system reset and forces an OTAA rejoin if that mode is programmed.
The device reports on the following different ports:
These messages can be decode with the following decoder:
decoded.lat - Last stored latitude positiondecoded.lon - Last stored longitude positiondecoded.gps_resend - number of status packets sent since last updated GPS positiondecoded.gps_on_time_total - cumulative time in seconds since device reboot. This best correlated to the power consumption of the device.decoded.gps_time - linux epoch time when the last GPS position has been acquiredNote: the location reported in a port 12 message is NOT a fresh GPS fix. It contains the last known position of the device, acquired by the last GPS fix, which is reported in port 1.
decoded.lat - Latitude positiondecoded.lon - Longitude positiondecoded.alt - Altitude above sea leveldecoded.satellites - number of satellites acquired in the fix, expect >3 for 3D fix and >4 for 3D fix.decoded.hdop - horizontal dillution of precision - expect <5 for normal operation, see https://en.wikipedia.org/wiki/Dilution_of_precision_(navigation)decoded.time_to_fix - time to fix of the device, depends on configuration, signal and how ofthen the fix is acquired. <5s is expected if fix every 5min, <15s is expected for fix every hour, <60s for cold fixdecoded.epe - estimated position error, this is configured as a target for every gps fix and the result show here is what happened actually. Normally in meters or feet. 50 is a good default, 100 will be very inaccurate fix, 10 is very accurate fix. Best advice is to keep this at 50, and set gps_min_fix_time to larger value, say 30 and the fix will be very good, epe is then expected to be about <10 in hotfix conditions.decoded.snr - best satellite SNR value, good functioning device is in 40-50 range, <30 is critical, check device orientation and close by objects.decoded.motion - high if the gps position has been triggered by movement, subject to configurationdecoded.gps_time - linux epoch time when the last GPS position has been acquiredEach port 11 message contains 5 positions with the following format:
decoded.lat - Latitude positiondecoded.lon - Longtitude positiondecoded.gps_time - linux epoch time when the last GPS position has been acquiredEach port 3 contains a single message with complete current settings of the device. Please use the decoder to read all the settings and use the encoder to compose new settings. A port 3 message is always send on reset of the device.
These device can handle two different type of downlink messages:
There are a number of single-byte commands specified for critical device control mechanisms. WARNING: Commands need to be sent unfonfirmed as they may reset the device, loosing the reply.
Implemented commands to be sent as single byte to port 99:
0xaa - Sent the current settings0xab - Triggers system reset0xac - GPS system reset, restarts GPS without system reset0xde - Resets LoraWAN stored settings in EEPROM and forces a re-join0xd0 - Drop-off command for the drop-off mechanism0x11 - Request the device GPS position log - 5 positions per packet, all available positions in sequence0xf1 - Clear GPS position log - use if necessary, but log simply stores last 100 positions and overwrites itselfSettings of these devices are controlled by sending a port 3 message with the new settings. When correct and accepted, the device will respond with the new settings by sending a port 3 message containing the new settings. This can be used to ensure the correct settings have been adopted by the device.
The settings can be compose using the encoder:
01000005010000000A0AC8003C0001320514000501008005010000000A0AC8003C0001320514000501005F961027033C0100D0070000To know which version of the encoder to use, we advice to check the current settings on the device by requesting these settings with a port 99 downlink (0xaa). Then look at the port 3 message length.
- legacy = 40 bytes
- v1 = 68 byes
The GPS system is configured by defining the gps_periodic_interval - time between fixes periodically and gps_triggered_interval - time between fixes if device is in active mode based on gps_triggered_threshold and gps_triggered_duration.
gps_periodic_interval - gps periodic fix interval in minutes, 0 disables it - 240 is a good defaultgps_triggered_interval - gps triggered interval in minutes, 0 disables it - 0 is a good defaultgps_triggered_threshold - the amount of G-force of the movement to trigger a fix, assume 10 as a safe defaultgps_triggered_duration - the time in seconds that the accelerometer needs to detect motion before it triggers a fix, assume 10 as a safe defaultgps_cold_fix_timeout - cold fix timeout in seconds - 120 is a good defaultgps_hot_fix_timeout - hot fix timeout in seconds - 30 is a good defaultgps_min_fix_time - minimal fix time - 5-15 is a good defaultgps_min_ehpe - minimal ehpe to be achieved - 50 is a good defaultgps_hot_fix_retry(0-255)- number of times a hot fix is retried before failing to cold-fix - 5 is a good defaultgps_cold_fix_retry(0-255) - number of time a cold fix is retried before failing the gps module. gps_settings.hot_fix needs to be enabled for this settings to be used - 2 is a good default, 255 is a special value indicating the cold fix never times out.gps_fail_retry - number of times gps system is retried before putting it in failed state, only 0 can be used currentlygps_settings -bit 0 - 3d fix enabled - 1 is agood defaultbit 1 - linear backoff upon fail (based on interval time) - 1 is a good defaultbit 2 - hot fix enabled - 1 is a good defaultbit 3 - fully resolved required - 1 is a good defaultgps_accel_z_threshold - accelerometer threshold for z value, such that gps does not trigger on wrong orientation. Typically GPS up is a negative accel Z value, good option to set this to is -500, 0 to disable this checkTheory of operation is as follows:
gps_cold_fix_timeout duration, if successful and hot-fix is enabled in general settings, then it will try all consequent fixes for the gps_hot_fix_timeout duration. If a fix fails to be acquired for gps_hot_fix_retry number of times then it reverts to cold fix for the gps_cold_fix_timeout duration for gps_cold_fix_retry times. When that is exhausted the gps goes to gps_fail_retry, which can currently only be 0, so practically the GPS will be disabled upon the reset of the device.gps_settings allows for 3D fix to be enabled, linear backoff upon a failure of a cold or hot fix, meaning that the defined gps_periodic_interval or gps_triggered_interval will be multiplied by the number of fails that have occurred. This conserves the battery by allowing the device to get out of a bad spot. Hot fix should always be enabled unless very clearly needed otherwise, likewise for fully resolved.
gps_min_ehpe is the principal factor to configure how fast the fix can be acquired and how good it is. A general value of 50 is a good starting point, 100 makes the fix fast but very inaccurate, under 20 the fix times get very very long and drain the battery. Leave at 50 unless you know what you are doing.
gps_min_fix_time forces the fixes not to be too short, acquiring a bit more of almanach. If you can afford battery wise, 15s is a good default
gps_accel_z_threshold is the value set as accelerometer z value above which gps can trigger, meaning the tracker is pointing to the sky. Negative values are handled as well, such that the more negative number then the threshold, then the trigger occurs.
5kB of EEPROM is available for GPS logging. At 10 Byres per position, this means we can store 500 positions. Upon request, these positions are sent via LoRaWAN on port 11.
lat - 3 bytes latitudelon - 3 bytes longitudetime - 3 bytes of time - for fixes we are mostly interested in 60s precision. Timestamp is in format (linux epoch time in seconds - 1600000000 (starting date Sept 13th 2020))/60. This gives us 30 years of runtime.fix_info - 1 byteTrackers include a DTC tuning component, which can be used to tune the antenna accordingly.
Send to RF port 30 the message based on encoder_rf_settings_json.py and set type=1 to receive vswr values based on capacitor value.
Send to port 92 a single byte value of what DTC should be, this gets stored into eeprom. Use with caution.
Send to port 93 a 2 byte value with the calibration factor multiplied by 10000; For example the sensor is returning 1300 (pulse_voltage), we wish to calibrate this to 1800. Calculating from this 1.3846 factor, multiplied is 13856, convert this to hex 0x3616. Send this via downlink. To reset the values send 2 byte value 2710 (hex 0x2710) to port 93.
The pulse counting and reporting mode is built to enable interfacing an external piece of electronics, for example a camera trap and detect actions as well as to control an output.
Pulse input does the following:
pulse_countpulse_count is greater then pulse_threshold, send status packet and reset the field. Set to 0 to send data on every pulse.pulse_min_interval in seconds, maximal value 255s.Pulse output does the following:
pulse_on_timeout seconds.Configuration variables controlling this:
pulse_threshold - how many pulses must be received to send a status packetpulse_on_timeout - how long is the pulse output on after threshold reachedpulse_min_interval - how often at maximum can a device send a packet on pulse eventThe use-case of above implementation is somewhat universal, however tailored at monitoring SD card activity in camera traps and similar devices and turning on these SD cards if they have WiFi capability.
The device provisioning is done with a separate sketch that uploads the keys to the EEPROM. Then the device gets the actual firmware. This is implemented such that the same firmware build can be distributed publicly and does not contain any key information.
If the keys are incorrect or not provisioned on the device, then the device fill revert to the fallback provisioning specified in the firmware. Note this is not secure and you can modify it per project, so no devices should be ever using this. If you see a device responding as fallback you can try to remotely reset it and that is as much as you can do, otherwise you need to reprogram.
Default fallback:
devAddr = "26011D63"nwkSKey = "9518E9E68D1476BC3386409B76476208"appSKey = "7972E2A484F76EF7B579D641D0BFEBD5"