The Oyster LoRaWAN provides a number of configurable parameters, to allow its behavior to be tailored to specific applications. Factors affecting the configuration you might choose include:
- How many messages per day your network will allow
- How often you intend to change the batteries, and the type of batteries in use
- How detailed a bread-crumb trail you require, or the required time between updates
- How good the GPS reception is in your installation
How The Oyster Connects (OTAA)
By default, the Oyster connects to a local LoRaWAN network using Over The Air Activation. Each Oyster is provisioned with:
- A read-only DevEUI - a 16 digit code uniquely identifying the Oyster (printed on the label)
- A configurable AppEUI - a 16 digit code uniquely identifying the website that data will be sent to
- A configurable AppKey - a 32 digit code that authenticates the Oyster to the website and network server
- The default AppEUI is 70-B3-D5-70-50-00-00-00
- Each Oyster is provisioned with a random default AppKey
- A configurable Region and Channel Mask
- The channel mask is used in the US and ANZ regions, to set the network frequencies
- Other regions don't need the channel mask, as all their networks use the same OTAA frequencies
Once the region has been configured, the Oyster will attempt to join local networks by transmitting join requests. Any network that hears the join requests and has knowledge of the Oyster's DevEUI, AppEUI and AppKey, will allow the Oyster to join the network and transmit data.
Once joined, Oyster repeats the OTAA process once a week by default. This renegotiates encryption keys for enhanced security, and ensures continued operation in the event of a network losing the keys (for instance, if the device is mistakenly deleted).
How The Oyster Connects (ABP)
The Oyster can also be configured to connect using Activation By Personalization. When using ABP, each Oyster must be configured with three additional numbers:
- A configurable DevAddr - an 8 digit code identifying the Oyster to the network
- A configurable NwkSKey - a 32 digit code that authenticates the Oyster to the network server
- A configurable AppSKey - a 32 digit code that authenticates the Oyster to the backend website and network server
ABP allows a LoRaWAN device to connect without exchanging the usual join request and join response, which can save on downlink bandwidth, and allow the device to work when downlink reception is difficult. However, in LoRaWAN 1.0, the ABP mechanism is somewhat problematic. It either suffers from a lack of security (if you configure your device to reset it's uplink frame counts when it resets), or difficulty with configuration (if you don't reset the frame counts, and are in a region requiring dynamic channel configuration). These issues are beyond the scope of this document, so we recommend that you use OTAA unless you are confident you understand the implications of ABP.
How The Oyster Locates
The Oyster uses an accelerometer to detect movement, allowing it to decide when an asset is in-trip, and when it is stationary. This allows it to schedule the battery-hungry GPS fixes and transmissions as infrequently as possible, to maximize battery life. Each time a status update is scheduled, the Oyster will attempt a GPS fix, then transmit the results (whether or not the fix succeeded). You can configure the Oyster to transmit a status update:
- Periodically (ie. 24-hour heartbeat)
- At the start of a trip
- During the trip
- At the end of the trip
- During after-hours trips
- When the 'Man Down' status changes
Since GPS fixes are very battery hungry, attempting to track an asset full-time will give a relatively short battery life. By comparison, if the Oyster is configured to ignore movement and simply transmit a status uplink once per day, a battery life of over 5 years is readily achievable. If you need lower latency updates, the next step is to enable transmissions at the end of trips. Finally, full tracking is obtained by enabling the in-trip transmissions.
How The Oyster Uses LoRaWAN Airtime
LoRaWAN devices can transmit at various data rates, usually denoted DR0, DR1, DR2, and so forth. The lowest data rate (DR0) takes the longest to transmit, but has the longest range. As the data rate goes up, the range goes down a bit, and the transmission time goes down a lot. Oysters can be configured to use a particular data rate, or a range of data rates (ie. DR2-DR4). Lower data rates will have the longest range, but also use the most battery power and airtime. When configured to use a range of data rates, the Oyster spends an equal amount of airtime using each data rate. The Oyster also has optional Adaptive Data Rate support, which allows the network server to intelligently control the data rate.
There are several factors limiting the maximum transmission rate of an Oyster:
- Radio regulations may limit the transmission time
- In Europe the law limits you to 36 seconds of transmit time per hour on most frequencies
- Whereas in Australia there is no legal limit
- Networks may limit the transmission time, to prevent congestion
- The Things Network for instance limits you to 30 seconds of transmit time per day
- At DR0, this gives you 20 messages with 100% range
- At DR1, this gives you 36 messages with 75% range
- At DR2, this gives you 80 messages with 50% range
- At DR3, this gives you 145 messages with 37% range
- At DR4, this gives you 265 messages with 28% range
- At DR5, this gives you 486 messages with 21% range
- In America, data rates are all two increments higher, so DR0 corresponds to DR2 in the above list
- Networks may limit the number of messages, for billing purposes
- Your network might require you to pay more for higher throughput
- Battery life may prove to be a limiting factor
- An Oyster can only send around 5 thousand messages at DR0 on one set of batteries, in typical asset location scenarios
- In asset tracking scenarios the GPS doesn't use as much battery per fix, so you can get around 25 thousand messages
- Using a higher data rate will use less battery per transmission, but doesn't change the battery use of the GPS
- Battery capacity required for one transmission at DR0 is 0.039 to 0.052 mAh, compared to a 1 minute GPS fix of 0.58 mAh
The radio regulations are automatically enforced by inserting delays between messages where required. It is up to the user to configure their Oyster with a low enough transmission rate to meet network and battery life requirements.
How The Oyster is Configured
The Oyster is configurable over-the-air using downlinks. Websites integrating the Oyster can find the complete protocol specification here. Initial configuration of the region and AppEUI, as well as firmware updates, are performed with a plug-in USB adapter, and a Windows configuration app. An adapter can be obtained from your Oyster distributor. The adapter plugs into the four pin connector below the battery compartment.
To read the available parameters, select your adapter from the drop-down list in the top right, and click Start. The configuration tool will read continuously, and display the existing parameters in the center column. To program new parameters and firmware, enter the desired parameters in the right hand column, and check the Program Parameters checkbox. To update the firmwares only, check the Program Firmware checkbox, and leave the Program Parameters checkbox clear.
If you click the DevEUI List button, a list of scanned DevEUIs will pop up. You can hot-plug the adapter into many Oysters in sequence to populate the list. The list is in CSV format, so it can imported into a spreadsheet easily.
The top line in the display shows the DevEUI and version string. In the screenshot above, the DevEUI is B309AFA3E3D8BC5A, the firmware version is 126.96.36.199 (product, hardware revision, major, minor). The default AppKey and the effective AppEUI and AppKey can be found in the DevEUI list on the right.
The 'Reset To Default' button in the top of the right column resets the whole right column to the default settings. The 'Existing' button copies the settings from the left column to the right column. The 'Save' and 'Load' buttons open a file dialog, to save or restore the right column to disk. There are many settings, but only a handful require customization. These are highlighted below.
When the Oyster's parameters were last changed.
This selects the radio frequencies to use according to your country. Please be sure to select the correct region, to maintain compliance with your country's radio regulations. Oysters leaving the factory are currently pre-configured for either the European 868 MHz band, or AS923, depending on their hardware type. However, this is subject to change, and in the future the region may be left unset. If the region is unset, the Oyster will not transmit until configured. Otherwise, to prevent the Oyster from transmitting before configuration (from firmware version 1.4 onwards), click the Start button on the tool, and plug the cable into the Oyster, before inserting the batteries. The region cannot be reconfigured over the air.
This chooses between the default (and recommended) Over The Air Activation, and Activation By Personalization. In OTAA, the Oyster and the network server generate the session encryption keys and device address during a join request / join response exchange. In ABP, you have to generate the encryption keys and device address beforehand, and configure them. There are two different ABP options - Reset Frame Count and Save Frame Count. Reset Frame Count will reset the uplink and downlink frame counts whenever the device is reset. This defeats the encryption entirely, but is required in LoRaWAN 1.0 so that the network server can detect the device reset, and reconfigure the device's channels. If your network doesn't need to detect the device reset and reconfigure the channels, you can select Save Frame Count. In this mode, encryption is not compromised, but there is no opportunity for the network server to reconfigure the device. Future firmwares will upgrade the Oyster to LoRaWAN 1.1, where this reconfiguration problem has been solved.
This identifies the backend website that your data should be sent to. If you leave it blank, the default for the Oyster LoRaWAN (70-B3-D5-70-50-00-00-00) will be used.
This 32 character key authenticates the Oyster with the backend website and network server. If you leave it blank, the Oyster will use a unique random key, which was written to it in the factory. This default key can be read from the DevEUI list dialog, or the label on the box. It is not printed on the Oyster's label. The AppKey cannot be reconfigured over the air.
This 32 character key authenticates the Oyster with the network server. It is only required if Activation is set to ABP.
This 32 character key authenticates the Oyster with the backend website and network server. It is only required if Activation is set to ABP.
This 8 character number identifies the Oyster with the network server. It is only required if Activation is set to ABP.
In the US and ANZ region, you must set this channel mask to select which of the 72 uplink channels your network provider uses. The parameter is one big hexadecimal number, with the lowest channels corresponding to the rightmost digits. For example:
Sub-band 1 uses channels 0-7, and channel 64, so it's mask is 0100000000000000FF
Sub-band 2 uses channels 8-15, and channel 65, so it's mask is 02000000000000FF00
Sub-band 3 uses channels 16-23, and channel 66, so it's mask is 040000000000FF0000
Sub-band 4 uses channels 24-31, and channel 67, so it's mask is 0800000000FF000000
Sub-band 5 uses channels 32-39, and channel 68, so it's mask is 10000000FF00000000
Sub-band 6 uses channels 40-47, and channel 69, so it's mask is 200000FF0000000000
Sub-band 7 uses channels 48-55, and channel 70, so it's mask is 4000FF000000000000
Sub-band 8 uses channels 56-63, and channel 71, so it's mask is 80FF00000000000000
To select all channels, you'd use FFFFFFFFFFFFFFFFFF
The configuration app default is blank, which results in the selected region's default channels being used. In both the US and ANZ region, this is the same as enabling all channels, and will lead to packet loss if your network is only using a single sub-band.
Min / Max Data Rate:
These parameters select the minimum and maximum data rates to transmit at, when ADR is not active. A '0' selects DR0, the lowest data rate with the longest range. If you set both parameters to the same value, the Oyster will always use that rate. If you choose a range, the Oyster will alternate between the allowed data rates in such a way as to spread the transmit time evenly. This means it will use the higher data rates more often. Using a range of data rates allows the network to support more devices per gateway, but reduces your guaranteed range to the range of the highest data rate. Using higher data rates may allow you to send more messages per day. Please see the section 'How The Oyster Uses LoRaWAN Airtime' above. The default is DR0-DR2.
Adaptive Data Rate:
By default, the Oyster does not request ADR when sending uplinks, choosing instead to control its data rate according to the configured range. However, you may wish to enable ADR when the tracked asset is mostly stationary, to optimize power usage and network capacity. You can also force ADR on at all times, in order to control it using a policy on the network server.
If the Oyster is configured to enable ADR when out-of-trip, it will switch to its lowest configured data rate, and highest transmit power, whenever a trip ends. Thereafter, the network server will configure it to a lower power mode if appropriate.
Please remember that the ADR adaptation rate in LoRaWAN 1.0 is extremely slow. If the device loses connectivity, it takes 96 lost transmissions before it will attempt to increase its transmit range. This adaptation rate will be adjustable in a future LoRaWAN release.
By default, the Oyster rejoins the network once a week, in case the network server has somehow forgotten the session keys. This period can be extended to up to 255 days, or disabled entirely (0). However, if a device is accidentally deleted on the network server, or the network server suffers a database failure and loses the session keys, the server will be unable to decrypt any device data until it has rejoined. Rejoining weekly generates several extra transmissions, but lowers the time spent out of service in the event of an accident. The rejoin is exactly equivalent to a device reset, and takes place even if Activation is set to ABP.
Heartbeat Fix (0-7620 mins):
The maximum time between status updates. Setting to 24x60 = 1440 mins results in at least one status update per day. If movement causes additional updates, the next heartbeat update is scheduled for 24 hours after the last movement update. The default is 24 hours.
In Trip Fix (0-7620 s):
The time between status updates when in-trip. Set to zero to disable these updates entirely. Note that in Europe, radio regulations will prevent the effective time between transmissions from dropping lower than about 140 seconds when using the lowest data rate. The default is 10 minutes, to improve the response time when testing, but a more conservative value on the order of an hour makes more sense in terms of battery life.
+ After Hours:
The time between status updates when in-trip, and after-hours. This allows you to specify different detail levels outside of normal working hours. You can use it to save battery by not tracking non-business trips, or to provide detailed tracking in the event of theft. Set to zero to disable in-trip fixes when after-hours. The default is 10 minutes.
Trip End Timeout (0-2550 s):
The time required before a trip ends, if no movement is detected. Set to zero to disable trip tracking entirely, which saves a small amount of power by disabling the accelerometer. You will still get heartbeat fixes with the trip tracking disabled. The default is 5 minutes.
GPS Coarse Timeout (0-7620 s):
The maximum time to spend waiting for the GPS to get a coarse position fix, per attempt. This limits the battery drain if there is no GPS signal. Values lower than 60 are likely to be problematic in practice, with 35 being an absolute minimum in very good signal. This setting is augmented by the GPS signal validator described in GPS Detect Time below. The default is 3 minutes. Note that the first fix attempt after battery insertion will always try for at least 10 minutes, regardless of any configured limits. If a fix times out the fix failed flag will be set and a message with the last known coordinates will be sent.
GPS Fine Timeout (0-7620 s):
The maximum time to spend waiting for the GPS accuracy to improve, after a coarse fix is achieved. Once the GPS manages to get a fix satisfying the minimum accuracy targets (Pos Acc Mask below), it waits up to GPS Acc Timeout for the accuracy to improve to GPS Acc Target. This allows you to set an opportunistic accuracy goal, and fall back to a lower accuracy if the goal can't be met. Zero disables the feature. The default is 5 seconds.
GPS Daily Budget (0-7620 s):
This setting allows you to set a daily GPS on-time budget. When non-zero, the Oyster will refuse to spend more than this number of total seconds per day trying to get GPS fixes. This prevent the battery being run down if a lot of unforeseen movement occurs. Once the budget for the day is expended, further GPS fixes and LoRaWAN transmissions are skipped. The default is zero, which disables the feature.
Fine Accuracy Target (0-255 m):
This is the target accuracy for the GPS Fine Timeout setting. The default is 20 meters. Note that values lower than about 6 are not reliably achievable with consumer GPS technology, and will lead to the full GPS Fine Timeout elapsing on each fix attempt.
Fix On Start:
When set, a status update (GPS fix and transmission) is scheduled at the start of a trip. This is usually a wasteful option, since the start position is generally already known from the end of the previous trip. The default is true.
+ After Hours:
When set, a status update is scheduled at the start of a trip when the trip is after-hours. You can use this to implement theft alerting. The default is true.
Fix On End:
When set, a status update is scheduled at the end of a trip. This lets you know where the asset is, with one caveat - if the destination is under cover, it may have no GPS signal, resulting in a transmission, but no position update. The default is true.
+ After Hours:
When set, a status update is scheduled at the end of a trip when the trip is after-hours. The default is true.
Man Down Timeout:
The Man Down indicator is a bit in the Oyster's extended uplink which shows if the device has stopped moving for a configurable time. This can be used to detect if an asset has been idle for a few weeks, a car has been stopped for a few hours, or if livestock have died. The timeout can be set from 10 minutes to 21h10m, in 10 minute increments, or from 1 day to 63 days 12 hours, in 12 hour increments. A value of 0 disables Man Down indication. Note that since the Man Down indicator bit is not present in the standard uplink (port 1), enabling Man Down causes the extended uplink (port 4) to be sent instead. The default is disabled.
+ Fix On Set:
This chooses what action to take when the Man Down indicator bit becomes set. You can choose one of:
- Do nothing - the bit will upload when the next heartbeat is sent (default)
- Transmit once, assuming the network connection is ready (join has been successful)
- Keep retrying (with backoff) until the network connection is ready, then transmit once
The current firmware only supports unconfirmed uplinks, even when retrying.
+ Fix On Clear:
This chooses what action to take when the Man Down indicator bit becomes clear, and is configured as above.
By default the Oyster will send a statistics message every 3 days. The statistics help keep track of battery usage, and diagnose GPS and vibration issues. However, you may wish to disable the statistics to minimize transmissions.
This is the timezone used for after-hours calculations. The default is UTC.
This is the amount of time that the clock shifts during daylight savings time, if applicable. It applies only to the after-hours calculations, and will usually be one hour, or zero to disable daylight savings. The default is disabled.
+ Start / End Nth / Day / Month / Time:
These parameters allow you to specify the start and end times of daylight savings, if DST Shift is nonzero. They only apply to the after-hours calculations.
Most countries use a relative specification such as 'The 1st Sunday of April, at 02:00 local time', or 'The Friday before the last Sunday of October, at 2:00 local time'.
For the first example you would choose '1st', 'Sunday', 'April', '2:00'. For the second, you'd choose 'Last', 'Sunday', 'October', '-2d 02:00'.
You can also choose a fixed date and time using for instance 'Absolute Day', 'Day 28', 'April', '02:00'.
The time is always in the current local time zone, including any daylight savings adjustment.
Mon / Tue / ... After Hour Start / End:
These parameters allow you to specify which times are after-hours, for the purpose of applying different trip tracking parameters at those times.
Set both the start and end parameters to 00:00 to disable (default).
Set the start to 00:00, and the end to 24:00, to make the entire day after-hours.
Setting a start time to before the end time makes the intervening times after-hours.
Setting the start time to after the end time makes the times between 00:00 and the end time, and between the start time and 24:00, after-hours.
Optimize for Trip Tracking:
This option enables speculative 'freshening' of the GPS satellite information. If enabled, the GPS is kept on for a bit longer than necessary after getting a position fix, downloading all outstanding satellite information. This speeds up the next GPS fix. The extra listen time is only scheduled during trips, or if Autonomous Aiding is enabled. This option should improve battery life for trip tracking applications, but should be left disabled for applications that will generate very few (< 4) position updates in-trip. The default is enabled.
Satellite Detection Margin (-16-15 dB):
This option adjusts the signal levels required for the GPS signal validator, described below. Setting it higher than 0 requires that GPS signals be stronger, setting it lower than 0 allows them to be weaker, without the signal validator giving up on a fix attempt. The default is 0 - just strong enough to work.
Nth Satellite Timeout (0-1275 s):
These four numbers are timeouts for the GPS signal validator. The signal validator augments the GPS Fix Timeout. While the Fix Timeout is a hard deadline for a fix to succeed, the signal validator looks at the signal strength, and gives up early if the signal is too weak to expect success. The validator is configured with four timeouts, which are the time allowed for the acquisition of the first four suitably powerful satellite signals. For instance, values of (60, 50, 40, 30) would require one strong satellite before the 60s mark, two strong satellites by the 60+50=110s mark, three by the 150s mark, and four by the 180s mark. Setting the first value to zero disables the feature. The defaults are all 1 minute. Setting the first value lower than 45 seconds is not recommended. Like the GPS Coarse Timeout, 35 seconds is an absolute minimum.
PDOP Mask (2.5-10):
The PDOP is a measure of how imprecise a GPS fix is, due to the satellites used being too close together to triangulate effectively. This parameter sets an upper bound on the imprecision, for a fix to be considered valid. You can safely use the default value, and specify the Coarse Accuracy Mask instead. The default is 10.
Coarse Accuracy Mask (5-100 m):
This is the required position accuracy for a position fix to be considered valid. It provides a lower bound on accuracy. Please note that it works on the estimated accuracy, and it is not uncommon for position fix errors to occasionally be two or three times larger than the mask. Also note that values lower than 20 will be difficult to achieve in practice. The default is 75 meters.
Speed Accuracy Mask (3-20 km/h):
This is the required accuracy of the speed component of a fix, before the fix is considered valid. The default is 10 km/h.
This informs the GPS module of what sort of motion to expect from the asset, allowing it to make better estimates when moving. The Automotive setting is a safe default, but the Pedestrian and Stationary settings may be useful as well. Setting the model appropriately allows the GPS to filter out noise more effectively.
Require 3D Fix:
This requires that a position fix use 4 satellites, and calculate a height as well as latitude and longitude, before being considered valid. It is recommended, as using only 3 satellites gives less redundancy in the rare event of a satellite failure, increasing the risk of a position fix giving an erroneous result. However, disabling this option can allow fixes to proceed faster, and in adverse conditions such as urban canyons. The default is false.
Discard First Fixes (0-32):
This option discards the first few valid position fixes from the GPS module. This gives the module some time to refine and cross-check its estimate, reducing the risk of an erroneous fix in the rare event of a satellite failure. We recommend the default value of 3.
This enables a GPS feature that predicts future satellite movements, so that position fixes can proceed without listening for all of the satellite information the next time the satellite is in view. It can help fixes succeed in low signal levels, but greatly decreases the accuracy of the fixes. The default is false.
Max Aiding Error (5-1000 m):
This provides a rough limit on the additional error introduced by the Autonomous Aiding feature. This error cannot be detected by the GPS module, so it can't be filtered out by the Pos Acc Mask setting. The actual error can be several times the value set here. Autonomous Aiding is unlikely to be of any use if this value is set below 50. The default is 100 meters.
Wakeup Threshold (1-8):
This sets the amount of force, in units of 63 mG, that will wake the accelerometer up. Setting it too high might result in trips being missed. Increase this value if you have a problem with small vibrations setting off spurious trips. The default is 2 (126 mG).
Wakeup Count (0-12):
This is the required time duration, in units of 80 ms, of the force that will wake the accelerometer up. Increasing this value will make the accelerometer less sensitive to short, sharp forces, but increases the chances of a trip start being missed. The default is 1 (80 ms).
Disable Wake Filter:
Set to disable the trip-start filtering, that is usually applied in addition to the Wakeup Threshold and Wakeup Count. The wake filter rejects small disturbances, requiring sustained jostling before a trip starts. This is good for battery life, but if you require higher sensitivity, or the filtering is causing too much latency for your application, you can disable it. The filter only starts a trip when it has seen 1 seconds worth of above-threshold movement in a 4 second period, or repeated short movements over several 4 second periods. This setting disables the filter during work hours only. The default is false (not disabled).
+ After Hours:
Set to disable the trip-start filtering after-hours. This can be useful for theft alerting, as it allows you to detect even minor bumps after-hours, without producing many false positives during normal work hours. The default is false (not disabled).