Campus-level BLE Beacon Positioning System — Deployment Guide

View source on GitHub
Preset

Starter Kit

For small offices or single rooms up to 500 sqm. Positions indoors come from BLE beacons and outdoors from the tracker's own GNSS, drawn on one map, with geofence enter/exit alarms.

  • Hardware: 1 SenseCAP M2 gateway, 9 BC03 BLE beacons, 1+ SenseCAP T1000 trackers.
  • Coverage: Up to 500 sqm, 2 km LoRaWAN range (nominal).
  • Server: a computer or server with Docker to run the positioning application.

Limitation: this is not a safety-certified system. Positions can be late, wrong or missing (LoRaWAN uplinks can be lost, GNSS does not work indoors, BLE positioning degrades around metal). Do not use it as the only control where a wrong or missing position can hurt someone.

1

Deploy BLE Beacons

Place BLE beacons at fixed locations indoors as position reference points. Areas covered by GNSS only (yards, roads, parking) need no beacons.

Wiring
  1. Place at least 3 beacons per area (trilateration) or 1 beacon (room level)
  2. Install at 2.5-3 m height, 5-10 m spacing
  3. Record each beacon's MAC address and location
Troubleshooting
SymptomAction
Beacon light not onReplace the battery
Inaccurate positioningAdd beacons or reduce spacing
Tracker can't scan beaconsMove the beacon so it is not too high or obstructed
Tracker stays "outdoor" inside the buildingAdd the beacon's MAC to the map configuration; unconfigured beacons do not count as indoor
2

Setup LoRaWAN Gateway

Connect the gateway to enable wireless communication between tracker and positioning app.

Wiring
  1. Power on gateway, connect to network (Ethernet or WiFi)
  2. Use SenseCraft App to scan QR code and bind gateway
  3. Solid green LED indicates ready
Troubleshooting
SymptomAction
LED not onCheck the power adapter and cable
LED blinking redCheck the Ethernet cable or WiFi configuration
App QR scan failedMake sure the gateway is online
Tracker data not reportingConfirm gateway and tracker use the same frequency band
3

Deploy Positioning Application

Deploy the positioning application. Prepare the application image first (see the preset notes).

Deployment method

Deploy the positioning application on your local computer.

Wiring
  1. Ensure Docker Desktop is installed and running
  2. Ensure port 5173 is available
  3. For an offline basemap, put the .pmtiles map file in data/pmtiles next to the compose file before deploying
What you will be asked for(filled in the SenseCraft Solution app)
2 more with defaults you can keep
  • Outdoor basemapdefault osm
    2 options
    • · OpenStreetMap raster tiles (online)
    • · Offline PMTiles archive

    OpenStreetMap raster tiles need internet on the host. Offline (PMTiles) reads a local archive instead.

  • PMTiles archive path on the hostdefault ./data/pmtiles

    Host directory holding the .pmtiles archive, mounted read-only at /app/uploads/pmtiles. Only used when the basemap is Offline PMTiles. Leave the default unless you keep the archive elsewhere.

Troubleshooting
SymptomAction
Deployment failedStart Docker Desktop
Image not foundBuild the image from the upstream branch and tag it locally
Port occupiedClose the program using port 5173 or change the port
Webpage won't openWait a few minutes and refresh
After Deployment
  1. Visit http://localhost:5173, log in with admin / 12345678 (change the default password under Configuration → Authentication after logging in)
  2. Upload the floor plan and enter the area it covers in metres
  3. Mark beacon positions on the plan (enter MAC addresses)
  4. Point the LoRaWAN network server at this host, or configure the SenseCAP / ChirpStack integration in the dashboard
4

Configure and Activate Tracker

Set up the tracker and confirm both indoor and outdoor positions are reported.

Wiring
  1. Press power button 3 s to turn on, blinking green = joining network
  2. Use SenseCraft App to connect to the tracker
  3. Select the correct LoRaWAN region, and enable both BLE scanning and GNSS positioning
  4. Walk near beacons indoors, press the button to trigger a report, confirm the position appears on the floor plan
  5. Walk outside, wait for a GNSS fix, confirm the tracker moves to the outdoor map
Troubleshooting
SymptomAction
Keeps blinking after power onCheck the gateway is online and the frequency band matches
Tracker not visible on webpageCheck the network server / SenseCAP integration settings in the dashboard
Position not updatingPress the button to trigger a report, or adjust the reporting interval
Indoor position displayed incorrectlyCheck the beacon markers on the plan
Does not switch to outdoorNeeds 3 GNSS fixes within 20 s and 15 s without a configured beacon; near a window it can switch back and forth
5

Georeference the Floor Plan

Align the floor plan with the outdoor map so indoor and outdoor trails show in one view. Skip it if you do not need the two together.

Prerequisites
  • The floor plan is uploaded and its real-world size in metres is set
  • You are logged in as admin
  • The site is visible on the outdoor map (online OSM map, or an offline .pmtiles map)
Wiring
  1. Select the Outdoor entry in the map dropdown and pan to your site
  2. Enter registration mode and pick the floor plan
  3. Use Drag / Rotate / Scale until the plan lines up with the building
  4. Check the toolbar values: origin lat, origin lon, rotation, scale
  5. Save; the dashboard confirms with "Registration saved."

Keep the origin within about 2 km of the area you care about.

Troubleshooting
SymptomAction
Save rejected with 422Latitude must not exceed 85 degrees and scale must be above 0
Save rejected with 403Log in as admin
Parameters gone after reloadSave again and confirm "Registration saved." appears
Map jumps to blank blue after typing coordinatesPan back to the site and re-enter the numbers
Rotate/Scale handles do not appearLeave and re-enter registration mode
After Deployment

Reload the browser, re-enter registration mode and select the same plan: the four parameters are still the saved values, and trackers on that plan draw on the same map as outdoor trails.

6

Set Up a Geofence Alarm

Draw a fence on the outdoor map and alarm when a tracker enters or leaves it. No beacon is needed inside the fence.

Prerequisites
  • At least one tracker is reporting GNSS positions
  • You know which direction to alarm on: enter, exit, or both
Wiring
  1. Create the geofence: a GeoJSON polygon, or a centre point plus radius_m
  2. Create the alarm rule with location_mode: geo, point it at the fence, choose the transition
  3. Walk a tracker across the boundary. An alarm needs 3 consecutive points on the new side spanning at least 10 s
Troubleshooting
SymptomAction
No alarm at allThe crossing was shorter than 3 uplinks or 10 s; enlarge the fence or shorten the uplink interval
Alarm fires lateExpected: confirmation needs 3 consecutive points spanning at least 10 s
Alarm right after a restartCheck whether the same rule is configured twice
time_range has no effectExpected: geo mode does not use it
Beacon selector still demandedSwitch location_mode to geo
After Deployment

One enter alarm and one exit alarm appear, and loitering on the boundary produces none. The alarms show in the dashboard alarm list.

7

Open Dashboard

The positioning dashboard is live. Click below to open it in your browser.

Troubleshooting
SymptomAction
Page not loadingMake sure the previous deployment step finished successfully and the service is healthy
Wrong host/portUpdate the URL with your device's IP if you deployed to a remote machine
Outdoor entry missing from the map dropdownRedeploy with the outdoor image tag
After Deployment

The system is ready.

Quick Verification

  1. Walk a tracker near beacons indoors and confirm it appears on the floor plan
  2. Walk outside and confirm it moves to the outdoor map after a few GNSS fixes
  3. Cross a geofence boundary and confirm the alarm
  4. Double-press the tracker button and confirm the SOS alarm

Next Steps