The Oyster 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 Sigfox messages per day you have on contract
- 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
The Oyster broadcasts its status updates into the air, where they will be heard by nearby Sigfox towers while in coverage. These status updates are identified by the Oyster's serial number - a six to eight digit hex string, printed on the label. If the serial has been registered with Sigfox, and is on a contract, the messages are accepted and forwarded to a front-end website such as Telematics Guru. If you are an end-user, all you need to do is add your activated Oyster on Telematics Guru to begin receiving its updates. If you are a distributor, or have a private account with Sigfox, you also need to configure your units on the Sigfox backend according to this guide.
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
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 Sigfox Airtime
Sigfox devices are provisioned on one of four monthly contracts:
- The One contract allows 2 uplinks and 0 downlinks per day
- The Silver contract allows 50 uplinks and 1 downlink per day
- The Gold contract allows 100 uplinks and 2 downlinks per day
- The Platinum contract allows 140 uplinks and 4 downlinks per day
The Oyster is configured for a particular contract by your dealer, and keeps track of the number of uplinks it uses throughout each day and throughout the monthly billing cycle. For example, using the One contract, on the 7th day of a 30 day month, the Oyster knows that it may have used up to 6 x 2 = 12 uplinks in the previous days of the month. It knows it has a budget of 2 uplinks in the current day, and 46 uplinks for the remainder of the month. If it finds that it did not use all 12 of the uplinks from the previous days, it considers them 'extra' uplinks, and may use them opportunistically to increase the detail of tracking. Once it has used them up, it is left with either the 2 uplinks allocated for that day, or with all 48 uplinks allocated for the remainder of the month, depending on how you configure the uplink budget strategy. Once it has run out of budget (for the day, or for the month), further uplinks are skipped.
How The Oyster is Configured
From firmware version 1.3, the Oyster Sigfox is configurable over-the-air through Telematics Guru. The Oyster checks for configuration messages using a downlink request. Since downlinks use more battery than uplinks, this only occurs once or twice a day. Downlink request times are randomized to minimize the chance of a device being out of coverage on every check. Since devices on the One contract cannot use downlinks, over-the-air configuration only works on the higher contracts. However, it is possible to upgrade the contract after deployment to avoid the cost of retrieving and reprogramming the device by hand.
Firmware updates (and optionally, configuration) 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. If your adapter has a red wire fitted, it will supply power to the Oyster while it is plugged in. If it doesn't, you must power the Oyster with batteries during configuration.
Warning - If your Oyster does not have a keyed connector, you must take special care to get the connector the right way round. Plugging the cable in backwards can permanently damage the Oyster or adapter! Make sure that you can see the four plastic clips of the plug!
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, enter the desired parameters in the right hand column, and check the Program Parameters button. Checking the Program Firmware button will additionally update the Oyster with the bundled firmware.
If you click the Serial List button, a list of scanned serial numbers will pop up. You can hot-plug the adapter into many Oysters in sequence to populate the serial list. When no changes are made to an Oyster, the serial is added in gray, and a chime is sounded. When the Oyster is programmed, the serial is added in black, and an alternate chime is sounded. After programming, the Oyster will take several seconds to reboot before it will be visible in the application again. It is not necessary to wait for this to occur before moving on to programming the next unit.
The top line in the display shows the serial number, version string, and PAC code. In the screenshot above, the serial is 1C86F3, the firmware version is 188.8.131.52 (product, hardware revision, major, minor), and the PAC is D756B7851DEC5C26. The PAC is used when registering the Oyster with Sigfox for the first time, and is written on the unit's label, along with the serial.
The 'Reset To Default' button in the top of the right column resets the whole right column to the default settings. There are many settings, but only a handful require customization. These are highlighted below.
When the Oyster was last programmed.
Heartbeat Fix (0-7620 mins):
The maximum time between status updates. Setting to 24x60 = 1440 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 RCZ1 devices (Europe, Middle East, South Africa) are restricted by radio regulations to transmit no more than 5 messages per hour. On these devices, settings the In Trip Fix to less than 12 minutes will result in transmission delays once the limit is reached. 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.
+ Extra Detail:
The time between status updates when in-trip, and extra uplinks are available to use. When the Oyster doesn't use all of the daily uplinks allowed by its contract, they roll over to the remaining days in the billing cycle, and are optionally used to increase the detail of tracking. Set to zero (default) to disable extra detail.
+ 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 one hour.
The time between status updates when in-trip, after-hours, and with extra uplinks available. Set to zero (default) to disable extra detail.
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. 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 5 minutes. Note that the first fix attempt after battery insertion will always try for at least 10 minutes, regardless of any configured limits.
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 Sigfox 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.
When set to Daily, status updates are sent when there is uplink budget remaining for the current day, or extra budget left over from previous days in the month. When set to monthly, updates are sent when there is any uplink budget remaining for any days in the month. The Monthly strategy may result in long periods without status updates if the whole budget is blown early in the month, but may be appropriate for some theft alerting applications. The default is Daily.
By default the Oyster will send a statistics message every 3 days (7 days, and only from 'extra' uplinks, if on the One contract). The statistics help keep track of battery usage, and diagnose GPS and vibration issues. However, in regions using the 868 MHz band, where duty cycle is severely restricted (1 uplink every 10 minutes), you may wish to disable the statistics to prevent them from delaying regular status updates.
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 use a large value, and specify the Coarse Accuracy Mask instead. The default is 5, which is conservative. Relaxing it to 10 will allow fixes with a more restricted view of the sky, at slightly increased risk of reduced accuracy.
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 50 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 true.
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. The default is false (not disabled).