/
Truck to Trailer Identification Over BLE

Truck to Trailer Identification Over BLE

1. Overview

Script Name: Truck_to_Trailer_Identification_V1.0

Purpose:
This script performs Bluetooth Low Energy (BLE) scanning of advertisement packets to identify which trailer beacon is traveling together with a truck. It collects BLE advertisements, maintains per-device RSSI histories (moving average), computes RSSI-based spread metrics, and produces a confidence score to select a single trailer beacon as “hitched” to the truck.

Key idea:
Use moving averages of recent RSSI samples and a data-spread metric (how much RSSI varies) to infer proximity and consistency. The beacon with the highest confidence is assumed to be the trailer attached to the truck. The script can be enabled/disabled and tuned through device settings.

2. High-level behavior and assumptions

  • The script continuously scans and captures advertisements into an internal circular buffer.

  • For each distinct MAC seen, the script stores an array of the most recent RSSI samples (moving-average style).

  • It calculates:

    • avg_rssi — the average RSSI across stored samples for a device.

    • avg_data_spread — average spread (absolute deviations) of RSSI samples; larger spread suggests less stable or further device.

    • confidence — derived from RSSI averages and spread; the device with the maximum confidence is treated as the trailer.

  • Devices that have not been observed for a configured timeout are considered outdated and discarded.

  • Beacon that is considered to be the correct trailer beacon is saved on selected sensor in configuration.

3. Configuration (via Web Interface)

Group: Trailer identification settings

Setting

Description

Example

Setting

Description

Example

RSSI Threshold

Minimum RSSI to consider a beacon valid. Filters weak signals.

-50

Algorithm activation condition

Defines when identification runs:
GNSS Speed — active when vehicle exceeds speed threshold.
Ignition on (IN5) — active when input signal IN5 is high.

Ignition on (IN5)

GNSS Speed Threshold

Minimum speed (km/h) to start scanning (only used in GNSS mode).

15

Data reset

Clears device data when activation condition changes (optional).

☐ Unchecked / ☑ Checked

Trailer ID Sensor

Sensor onto which Trailer ID MAC address will be stored.

SENSOR_STRING_1

Configuration Example (Image 1):

image-20251007-135427.png
Image 1. Example of script settings

4. ID List (Whitelist Upload)

Users can upload a device whitelist (MAC address list) through the web UI.
Only devices in this list are tracked and evaluated by the algorithm — all others are ignored.
This improves detection reliability and reduces noise from nearby BLE devices.

In xdm go to settings → ID lists and create new ID list. In the ID list type in your beacons MAC addresses in Hexadecimal. In the example below a MAC address AC:23:3F:5A:9E:4B will be added (Image 2).

MAC address should be in hexadecimal and without ':' in between bytes:

image-20251008-081444.png
Image 2. Adding MAC address into the ID list example

Once typed in MAC address and added them into the list you will be able to see them all on the right side table (Image 3):

image-20251007-131155.png
Image 3. MAC address in ID list example

After saving ID list add it to device settings and make sure that the index is '1' as shown below (Image 4):

image-20251007-132725.png
Image 4. ID list add in device settings

5. Launch instructions

Step

Description

Step

Description

1

Create ID list which consists of MAC address of your beacons

2

Open device settings.

3

Add your ID list into the settings and set index as '1'

4

Add script to settings.

5

Fill in script settings

6

Trailer MAC will be stored on selected sensor in script settings. To publish it add selected sensor to data recording .

7

Press ‘Save’

Tips

  • Set a higher RSSI threshold to avoid distant beacons.

  • Use GNSS mode if you only want identification while driving.

  • Use IN5 mode if identification depends on ignition or external signal.

  • Upload a whitelist to lock detection to known trailers.

6. Limitations and known edge-cases

  • RSSI ambiguity: RSSI is noisy and affected by reflections, orientation, and occlusion. The spread metric helps but cannot eliminate collisions/confounding from nearby beacons.

  • Transient proximity: If two beacons are physically close and the truck is stationary, the algorithm may have difficulty selecting the correct trailer. Movement (change of GNSS speed) helps disambiguate.

  • Capacity: NUMBER_OF_DEVICES is 40. If the ID List has more active beacons than capacity, older entries with weaker RSSI are overwritten or dropped.