Bluetooth Device Documentation MunicOS

✨ Introduction to Bluetooth Sensor Integration

In today's interconnected world, the seamless integration of sensors is becoming increasingly crucial. A novel approach to facilitate this integration involves the implementation of a cyclic scanning and advertising strategy. This innovative technique allows devices to efficiently discover and communicate with one another within a Bluetooth network, while simultaneously collecting and transmitting valuable sensor data.

By strategically alternating between scanning and advertising phases, devices can optimize resource utilization and ensure reliable data exchange. The device operates on a 30-second cycle, dividing its time between scanning and advertising phases. During the 10-second scanning phase, the device actively monitors the radio frequency spectrum for Bluetooth signals emitted by other devices. This enables the device to detect and identify nearby Bluetooth devices and sensors, expanding its connectivity options. The device diligently collects and transmits sensor telemetry data. This data may include temperature, humidity, or other relevant environmental parameters. By transmitting this data during the scanning phase, the device ensures efficient utilization of its resources and minimizes latency in data delivery.


✅ Pre-requisites for Bluetooth Connectivity

  • Software: 3.5.24.002 minimum
  • Device: Device with Bluetooth option (either OBDV8 or OBDV8+)

Bluetooth Activation

On Munic test OS, Bluetooth is activated by default.


📊 Understanding Bluetooth Sensor Tracking Data

Sensor values are reported using tracking fields BT_SENSOR_1 to BT_SENSOR_20. The tracking fields data format is the following:

ID;Sensor-Type;Value;Unit

Where:

  • ID: is the sensor ID
  • Sensor-Type: is the sensor type expressed as a string. The possible values are:
    • Acceleration
    • Alert-Event
    • Alert-Count
    • Analog-Input
    • Battery-Level
    • Battery-Voltage
    • Digital-Input
    • Digital-Input-Count
    • Humidity
    • Identifier
    • Light-Level
    • Low-Battery
    • Magnet
    • Magnet-Count
    • Motion-Event
    • Motion-Count
    • Movement-Event
    • Movement-Count
    • Proximity-Event
    • Proximity-Distance
    • Temperature
    • Touch-Event
    • Touch-Count
  • Value: the reported value, can be a decimal, integer or boolean.
  • Unit: the reported value unit

The application prioritizes consistency by assigning sensor values to specific tracking fields. This ensures that data from a particular sensor is consistently tracked in the same field, making analysis and interpretation easier. To accommodate a larger number of sensors than the maximum limit of 20 tracking fields, the application employs a strategic reuse approach. Once all 20 fields are assigned, subsequent sensors will be mapped to previously used fields, ensuring efficient data tracking without sacrificing data integrity.

To ensure precise data tracking, the application assigns tracking fields based on a combination of the sensor's unique identifier and the specific type of telemetry data it provides. This granular approach allows for accurate monitoring of multiple data points from a single sensor. For instance, if a sensor measures both temperature and humidity, two distinct tracking fields will be allocated: one for temperature readings and another for humidity readings. This level of detail enables comprehensive analysis and facilitates the identification of trends and patterns in the sensor data.


🆔 Sensor Identification and Privacy

To ensure compliance with stringent data privacy regulations like the GDPR, the device employs a privacy-preserving approach to device identification. Instead of transmitting the device's unique MAC address, which could potentially be linked to personal information, the device calculates a unique identifier from the SHA-1 hash of its MAC address. This identifier is assigned to the device for its entire lifespan and remains constant. By utilizing this method, the device safeguards user privacy while maintaining its ability to communicate and report sensor data to the cloud.

However, in regions where the GDPR does not apply, the device can be configured to transmit its MAC address for enhanced device tracking and identification purposes. This configuration option provides flexibility to adapt to different regulatory environments and specific use case requirements.


âš™ī¸ Detailed Sensor Types and Data Units

🚀 Acceleration

The device reports the read acceleration over the 3 axis in mg.

Value format

The value format is: [x,y,z]

Where x, y, and z are the acceleration for each axis expressed as an integer.

Unit

The read acceleration over the 3 axis is expressed in mg.

Example

6902cbd7f03103bce6bad82c7d9cc90039c49c77;Acceleration;[-46,-37,-18];mg;

  • Sensor ID: 6902cbd7f03103bce6bad82c7d9cc90039c49c77
  • Acceleration over x-axis: -46 mg
  • Acceleration over y-axis: -37 mg
  • Acceleration over z-axis: -18 mg

Supported protocols

It supports the following protocols:

  • ELA Innovation ANG
  • Wimoto

🚨 Alert Event

It reports an alert event. An alert can may be:

  • A magnet presence.
  • A movement detection.
  • A digital input

The sensor reports two fields Alert-Event and Alert-Count.

Alert-Event

Value format

The value format is: v. Where v is a boolean.

Unit

N/A

Example

6902cbd7f03103bce6bad82c7d9cc90039c49c77;Alert-Event;true;;

  • Sensor ID: 6902cbd7f03103bce6bad82c7d9cc90039c49c77
  • Status: true

Alert-Count

Value format

The value format is: v. Where v is an integer.

Unit

N/A.

Example

6902cbd7f03103bce6bad82c7d9cc90039c49c77;Alert-Count;72;;

  • Sensor ID: 6902cbd7f03103bce6bad82c7d9cc90039c49c77
  • Event counter: 72

Supported protocols

It supports the following protocols:

  • ELA Innovation DI
  • ELA Innovation MAG
  • ELA Innovation MOV

🔌 Analog-Input

Analog input voltage measured in mV.

Value format

The value format is: v. Where v is an integer.

Unit

The read voltage is expressed in mV.

Example

6902cbd7f03103bce6bad82c7d9cc90039c49c77;Analogic-Input;4883;mV;

  • Sensor ID: 6902cbd7f03103bce6bad82c7d9cc90039c49c77
  • Analog input: 4883 mV

Supported protocols

It supports the following protocols:

  • ELA Innovation Analog IN

🔋 Battery-Level

It reports the sensor internal battery voltage level in %.

Value format

The value format is: v. Where v is an integer.

Unit

The read voltage level is expressed in %.

Example

6902cbd7f03103bce6bad82c7d9cc90039c49c77;Battery-Level;9;%;

  • Sensor ID: 6902cbd7f03103bce6bad82c7d9cc90039c49c77
  • Battery level: 9%

Supported protocols

It supports the following protocols:

  • Battery Level (Bluetooth standard)
  • Eddystone TLM
  • ELA Innovation

⚡ Battery-Voltage

It reports the sensor internal battery voltage in mV.

Value format

The value format is: v. Where v is an integer.

Unit

The read voltage is expressed in mV.

Example

6902cbd7f03103bce6bad82c7d9cc90039c49c77;Battery-Voltage;2950;mV;

  • Sensor ID: 6902cbd7f03103bce6bad82c7d9cc90039c49c77
  • Battery voltage: 2950 mV

Supported protocols

It supports the following protocols:

  • Eddystone TLM
  • Teltonika
  • ELA Innovation

🔌 Digital-Input

It reports digital input status. The sensor reports two fields Digital-Input and Digital-Input-Count.

Digital-Input

Value format

The value format is: v. Where v is a boolean.

Unit

N/A

Example

6902cbd7f03103bce6bad82c7d9cc0039c49c77;Digital-Input;true;;

  • Sensor ID: 6902cbd7f03103bce6bad82c7d9cc90039c49c77
  • Status: true

Digital-Input-Count

Value format

The value format is: v. Where v is an integer.

Unit

N/A.

Example

6902cbd7f03103bce6bad82c7d9cc90039c49c77;Digital-Input-Count;2441;;

  • Sensor ID: 6902cbd7f03103bce6bad82c7d9cc90039c49c77
  • Event counter: 2441

Supported protocols

It supports the following protocols:

  • ELA Innovation DI

💧 Humidity

The device reports the read humidity in %.

Value format

The value format is: v. Where v is an integer.

Unit

The read value is expressed in %.

Example

6902cbd7f03103bce6bad82c7d9cc90039c49c77;Humidity;32;%;

  • Sensor ID: 6902cbd7f03103bce6bad82c7d9cc90039c49c77
  • Humidity: 32%

Supported protocols

It supports the following protocols:

  • ELA Innovation RHT
  • ELA Innovation RH
  • Teltonika
  • Wimoto Climate

🆔 Identifier

The device reports the Bluetooth beacon ID.

Value format

The value format is: v. Where v is a string.

Unit

N/A.

Example

6902cbd7f03103bce6bad82c7d9cc90039c49c77;Identifier;01020304-0506-0708-090A-010203040506;;

  • Sensor ID: 6902cbd7f03103bce6bad82c7d9cc90039c49c77
  • Identifier: 01020304-0506-0708-090A-010203040506

Supported protocols

It supports the following protocols:

  • Eddystone EID
  • Eddystone UID
  • ibeacon
  • ELA Innovation ID

💡 Light-Level

The device reports the read light level in lux.

Value format

The value format is: v. Where v is an integer.

Unit

The read value is expressed in lux.

Example

6902cbd7f03103bce6bad82c7d9cc90039c49c77;Light-Level;31;lux;

  • Sensor ID: 6902cbd7f03103bce6bad82c7d9cc90039c49c77
  • Light level: 31 lux

Supported protocols

It supports the following protocols:

  • Wimoto Climate

đŸĒĢ Low-Battery

It reports the sensor internal battery low level status.

Value format

The value format is: v. Where v is a boolean.

Unit

N/A.

Example

6902cbd7f03103bce6bad82c7d9cc90039c49c77;Low-Battery;true;;

  • Sensor ID: 6902cbd7f03103bce6bad82c7d9cc90039c49c77
  • Battery voltage is low: true

Supported protocols

It supports the following protocols:

  • Teltonika

🧲 Magnet

It reports the magnet presence. The sensor reports two fields Magnet and Magnet-Count.

Magnet

Value format

The value format is: v. Where v is a boolean.

Unit

N/A

Example

6902cbd7f03103bce6bad82c7d9cc90039c49c77;Magnet;false;;

  • Sensor ID: 6902cbd7f03103bce6bad82c7d9cc90039c49c77
  • Status: false

Magnet-Count

Value format

The value format is: v. Where v is an integer.

Unit

N/A.

Example

6902cbd7f03103bce6bad82c7d9cc90039c49c77;Magnet-Count;5;;

  • Sensor ID: 6902cbd7f03103bce6bad82c7d9cc90039c49c77
  • Event counter: 5

Supported protocols

It supports the following protocols:

  • ELA Innovation MAG
  • Teltonika

🏃 Motion-Event

It reports a motion event status. The sensor reports two fields Motion-Event and Motion-Count.

Motion-Event

Value format

The value format is: v. Where v is a boolean.

Unit

N/A

Example

6902cbd7f03103bce6bad82c7d9cc90039c49c77;Motion-Event;true;;

  • Sensor ID: 6902cbd7f03103bce6bad82c7d9cc90039c49c77
  • Status: true

Motion-Count

Value format

The value format is: v. Where v is an integer.

Unit

N/A.

Example

6902cbd7f03103bce6bad82c7d9cc90039c49c77;Motion-Count;72;;

  • Sensor ID: 6902cbd7f03103bce6bad82c7d9cc90039c49c77
  • Event counter: 72

Supported protocols

It supports the following protocols:

  • ELA Innovation PIR
  • Wimoto

đŸšļ Movement-Event

It reports a movement detection status. The sensor reports two fields Movement-Event and Movement-Count.

Movement-Event

Value format

The value format is: v. Where v is a boolean.

Unit

N/A

Example

6902cbd7f03103bce6bad82c7d9cc90039c49c77;Movement-Event;false;;

  • Sensor ID: 6902cbd7f03103bce6bad82c7d9cc90039c49c77
  • Status: false

Movement-Count

Value format

The value format is: v. Where v is an integer.

Unit

N/A.

Example

6902cbd7f03103bce6bad82c7d9cc90039c49c77;Movement-Count;35;;

  • Sensor ID: 6902cbd7f03103bce6bad82c7d9cc90039c49c77
  • Event counter: 35

Supported protocols

It supports the following protocols:

  • ELA Innovation MOV
  • Teltonika

📍 Proximity-Event

It reports a proximity event status.

Value format

The value format is: v. Where v is a boolean.

Unit

N/A

Example

6902cbd7f03103bce6bad82c7d9cc90039c49c77;Proximity-Event;true;;

  • Sensor ID: 6902cbd7f03103bce6bad82c7d9cc90039c49c77
  • Status: true

Supported protocols

It supports the following protocols:

  • ELA Innovation PROXIR

📏 Proximity-Distance

It reports a proximity event distance.

Value format

The value format is: v. Where v is an integer.

Unit

The distance is expressed in mm.

Example

6902cbd7f03103bce6bad82c7d9cc90039c49c77;Proximity-Distance;72;mm;

  • Sensor ID: 6902cbd7f03103bce6bad82c7d9cc90039c49c77
  • Distance: 72 mm

Supported protocols

It supports the following protocols:

  • ELA Innovation PROXIR

đŸŒĄī¸ Temperature

The device reports the read temperature in °C.

Value format

The value format is: v. Where v is a decimal value.

Unit

The temperature is expressed in °C.

Example

6902cbd7f03103bce6bad82c7d9cc90039c49c77;Temperature;26.84;°C;

  • Sensor ID: 6902cbd7f03103bce6bad82c7d9cc90039c49c77
  • Temperature: 26.84 °C

Supported protocols

It supports the following protocols:

  • Eddystone TLM
  • ELA Innovation T
  • ELA Innovation T EN
  • ELA Innovation T Probe
  • ELA Innovation RHT
  • Teltonika
  • Wimoto Climate

👆 Touch Event

It reports a touch event. The sensor reports two fields Touch-Event and Touch-Count.

Touch-Event

Value format

The value format is: v. Where v is a boolean.

Unit

N/A

Example

6902cbd7f03103bce6bad82c7d9cc90039c49c77;Touch-Event;true;;

  • Sensor ID: 6902cbd7f03103bce6bad82c7d9cc90039c49c77
  • Touch status: true

Touch-Count

Value format

The value format is: v. Where v is an integer.

Unit

N/A.

Example

6902cbd7f03103bce6bad82c7d9cc90039c49c77;Touch-Count;13;;

  • Sensor ID: 6902cbd7f03103bce6bad82c7d9cc90039c49c77
  • Event counter: 13

Supported protocols

It supports the following protocols:

  • ELA Innovation TOUCH