The Oyster3-Bluetooth has a 5.2 Bluetooth® Low Energy (BLE) module. This enables a large number of flexible solutions to be implemented using the Oyster3-Bluetooth + 3rd party BLE Tags or Sensors. 

See Bluetooth Asset Tracking for an overview.

This guide covers how to configure the device to scan periodically for BLE Tags and sensors.

Setting the Bluetooth® Firmware

If you have just booted the device for the first time, it is likely that it has production level Bluetooth® firmware installed and you'll need to upgrade the firmware.

1. First select the device in the device grid,
2. Open the Device Operations drop down menu
3. Select ‘set Bluetooth® firmware’

To check which hardware revision you have, consult the device grid under the 'Product' column which will show a number and a decimal, the decimal is the hardware revision. I.e. 96.1 is revision 1. Set the latest Bluetooth® firmware version.

It is also worth setting the main device firmware at the same time.

Configure Scanning Parameters

Add the BLE Tag Scanning tab.

BLE scanning is disabled until we set a Scan Period (in trip or out of trip)

We can control scan periods and upload behaviour when the device is in/out of trip. We may want to scan more often while the device is on the move if we are more likely to encounter tags during a trip. It could then be scaled back when the asset is parked overnight. 

Choosing a Scan Length

When choosing the scan length for your Bluetooth® tag you are balancing the power usage and accuracy. If the scan is too short you may miss nearby tags but if it is too long you are wasting power.

In our testing, we have found it is best to configure the scan length to 3 times the tag beacon interval. So if our tags beacon every 5 seconds, we should set the scan length to at least 15 seconds. 

Upload on Tag List Empty/Populated

Firmware 1.5+ for the Oyster3 Bluetooth allows you to configure when the device will upload after a scan, if Upload on In-Trip/Out-of-Trip scan is enabled. The parameters will apply to both In-Trip and Out-of-Trip scans, depending on what is enabled. The parameters for this are as follows:

Upload on Empty Tag List Scan allows for the device to only upload after a scan if the tag list was empty, i.e. no tags were found within the applied filters during the scan. Upload on Populated Tag List Scan does the opposite, wherein the device will only upload after a scan if a tag has appeared in the tag list.

This can be useful for a variety of applications, such as allowing for live separation alerts between the device and the nearby tags, while also saving battery life by not forcing the device to upload after every scan. 

Example Configuration

Below shows parameters for:

• Scanning for iBeacon Tags
• Scanning every 15 minutes during trip (and on the start/end)
• Scanning and uploading every 2 hours out of trip
• If Upload on Scan is set to No - When a scan is conducted, the device will simply scan for BLE tags. The GPS coordinate that is sent in the payload with the scan data is the previously logged position
• If Upload on Scan is set to Yes, the following occurs instead
  1. The scan is logged
  2. A GPS fix is attempted
  3. An upload is attempted
     4. If the firmware of the device is 1.5+, the upload condition parameters must be specified. 
• If we are already uploading and getting regular fixes during a trip - we don't also need to configure Upload on In Trip Scan
  • Data will be upload along with the "In Trip Upload" period
  • The regular fixes will ensure we have current GPS positions associated with tag scan data.

With this in mind, if the above scanning parameters were configured in addition to the default tracking parameters:

The behaviour is as follows:

• Device sitting stationary
  • Scan, GPS fix and upload every 2 hours
• Device is on move
  • Trip starts
    • Scan, fix + upload (trip start upload)
  • In Trip
    • GPS fixes for position every 2 min
    • BLE Scan every 15 min
    • The results uploaded every 30 min (In Trip Uploads period = 1800 sec)
  • Trip Ends
    • Scan, fix + upload (trip end upload)

There is no need to configure specific in-trip BLE uploads.

Testing/Troubleshooting Notes

When setting up a new tag type for the first time, take note of the following:

1. It generally makes sense to set a short Heartbeat and In-Trip/Out of Trip Scan Periods - say about 10 minutes - so we get lots of regular scans for testing. We can extend these intervals back to what we will deploy in the field once we have confirmed the tag is being read.
2. If tags are not being read, we can troubleshoot as follows:
   1. Double check all parameters. Ensure we have set a reasonable Scan Length
   2. Scan for the tag with your mobile phone - to double check that it is in-fact working and transmitting.
   3. Turn on Data Capturing on OEM. This will display the results of the tag scans in the logs in OEM - in case they're being filtered out by the end server.
   4. Contact support if we still cannot get it running.