Measuring Your Beacon

  • This document outlines a systematic methodology for collecting, processing, and analyzing proximity data using Bluetooth Low Energy (BLE) beacons to characterize their performance across varying distances and transmission power (TxPower) settings. The procedure involves configuring physical beacons with specific UUID, Major, and TxPower parameters within a controlled study environment, utilizing a researcher interface to manage data collection.
  • Mobile applications (iOS/Android) facilitate user registration and real-time distance reporting (in feet) relative to stationary beacons, with data recorded over extended periods (>24 hours).
  • A Python-based script processes the collected data, extracting it into a structured format, validating received signal strength indicator (RSSI) measurements, and filtering outliers based on distance-RSSI inconsistencies. The script generates organized outputs, including per-coupon CSV files, visualizations, and an input table aggregating all readings.
  • Optional simulations augment the dataset by modeling potential scenarios, pairing near and far distances across platforms while excluding invalid configurations. Post-processing further refines the analysis by identifying optimal beacon parameters (TxPower, thresholds) for user-specified near and far distances, producing graphical representations to guide parameter selection.

The methodology aims to provide a robust framework for evaluating BLE beacon performance, enabling precise configuration for proximity-based applications.

Collecting Beacon Data

Steps:
1) Import this study into your Researcher UI and change its phase to In Progress (it is important that you begin with a clean study)

BeaconPowerTest.json
13KB, Uploaded 2 months ago
2) Configure your physical Beacons Major, UUID and TxPower by setting the following details  ⁠⁠Configuring Your beacon⁠ 

The UUID and Major can be found on the sensors page of the study you imported (For more info follow this documentation:  ⁠⁠Creating A Study with Beacon Sensor Enabled⁠ )

3) Geneare a coupon and register to it through one of ODIN's apps depending on your platform:
a) iOS App:  https://apps.apple.com/ar/app/odin-study/id1568172293?l=en-GB b) Android App:  https://play.google.com/store/apps/details?id=edu.unl.snrg.odin 

4) After registration, go to the report events page and click on the button that says : "ONLY ANSWER THIS ONCE". It will prompt you to input the current TxPower of the beacon you are ranging.

5) Set your beacon at a specific distance and report the distance in the app (in feet). Every time you change the distance report the new distance.
Make sure to move your phone and not the beacon.
Moreover, when you are done collecting data report the distance as 0. That is required by the script to correctly process the data.
After answering 0, go to Investigator Access and push your readings. Confirm on the researcher UI that the latest data is there.

6) Collect data for a substantial amount of time, preferably >24 Hours

7) Download the study data and the pull the script from the this  Git  repo. Extract the data into the data folder and run the script. Once done, the processed data should be in the output folder and sorted by coupon.
(Note: script uses python3 not python)


Processing Your Data

Open terminal and navigate to the location of the python script. Input the following:
python3 run_me.py

If you already downloaded the data and extracted it to your data folder as specified in step 7 above then you should receive the following message.
(Note that if you don't have the data locally this script would allow you to download the data through the API provided on the Researcher UI, contact support for help on this)

After the data is checked, you will be asked to name your beacon as follows (in this example it is name BlueCharm):

Data is then read into memory and checked to make sure that the data is correct. Some cases might be singled out and not used if the mean RSSI at farther distances is less than the mean RSSI at shorter distance, the data at that reading setting might be incorrect. The script will notify you about that.

The script at this point has created an "output" folder with an inner folder with the name of your beacon:

Navigating to your Beacon you will now find a bit of processed data, firstly the CSVs with the processed data per coupon, the plots of this data for each coupon and the input table with all the readings from your coupons.

At this point, the script will ask you if you want to run simulations using your data. This will augment your data and create potential scenarios that match the readings that you have collected. You also have the option to exit with no simulation.

If you run the simulation, the data in the input table will be used to simulate. Each distance will be chosen as a Near and will be matched with every available far distance that is greater than it, with respect to each platform. (Illegal scenarios singled out in the previous step will not be simulated)

At this point you will find 4 new files in your directory.
File 1: results-unsorted.csv is a file that has all the results on the simulations as is and not sorted.
File 2: results-sorted.csv is a file that sorts the simulations by Near, Far, TxPower and Threshold
File 3: readings-missing.csv is a file the contains readings that were missing from your data collection on a specific platform
File 4: results-matched.csv is a file that combines Android and iOS data into one table with matching near, far, txpower and threshold

The script then prompts you to run a post processing step. This post processing script will prompt you to choose your near and far and will then check and graph the best possible configuration at each TxPower for the chosen near and far.

At the end of the script you will get an output for the best possible solution found at each power state

It will also graph out these readings and save them in a PNG file in output/{beacon}/plots/postsimulation/{power}.png and this graph could be used to choose the best parameters for your beacon.



I have collected data from my Beacon, what should I do next?

Once you have collected the data for your beacon you must now set up your study. The following documentation will guide you through the process:  ⁠⁠Creating A Study with Beacon Sensor Enabled⁠