Contact Sales User Login
Plugin Reference Manuals

Plugins Documentation

Browse configuration schemas, route definitions, and integration guides for all official Uniflow dynamic plugins.

Bluetooth BLE

Bluetooth BLE

ID: uniflow.plugin.bluetoothble • Category: Network & Communication Protocols • Version: v1.3.0 • Min Uniflow Version: Uniflow ≥ v1.4.0

Bluetooth BLE Plugin Reference Manual

1. Overview

Plugin Name: Bluetooth BLE

Type: Generic Protocol

Identifier: uniflow.plugin.bluetoothble

Description

Integration with Bluetooth Low Energy (BLE) peripheral devices. Enables active device scanning, automatic GATT service/characteristic discovery, subscription to characteristic notification streams (CCCD), sub-payload byte offset parsing, and telemetry publishing into the Uniflow catalog.

2. Technical Architecture

The Bluetooth BLE plugin operates as a cross-platform Bluetooth Low Energy (BLE) GATT client stack. It performs active advertisement scanning with real-time RSSI signal tracking, establishes GATT connections to peripheral MAC addresses, enumerates GATT services and characteristics, and subscribes to Client Characteristic Configuration Descriptors (CCCD) for Notify and Indicate telemetry streams. Received byte buffers are parsed at configurable zero-indexed byte offsets to extract structured numerical or string data types.

System Interaction & Exposed Catalog Routes

The Bluetooth BLE plugin operates as a cross-platform GATT client. It scans for BLE advertisement packets, tracks RSSI signal levels, connects to peripheral MAC addresses, subscribes to characteristic notifications (CCCD), and parses payload byte offsets into structured telemetry.

Catalog Routes & Node Integration

Input Event Triggers (Input Nodes):

  • ble.characteristic_notified - Fired when GATT characteristic telemetry arrives.
  • ble.device_discovered - Fired when a target BLE device is scanned.
  • ble.rssi_updated - Signal strength update event.

    • Executable Actions (Action Nodes):

  • ble.write_characteristic - Writes raw bytes or strings to a GATT characteristic.
  • ble.connect - Initiates GATT connection to MAC address.
  • ble.disconnect - Terminates active GATT session.

    • Architecture Diagram

    VISUAL ARCHITECTURE FLOW DIAGRAM
    Rendering Flow Architecture Diagram...

    3. Configuration Parameters

    The following configuration fields are available in the User Interface for this plugin:

    Configuration SettingDescription
    Device Address (MAC)Specifies the MAC address of the target BLE device (e.g., 50:65:83:A2:1A:E8).
    Device NameFriendly display name of the discovered BLE device.
    Auto ReconnectBoolean flag (True/False) indicating if Uniflow should automatically attempt reconnection if signal is lost.
    Reconnect Interval (s)Time in seconds between automatic reconnection attempts.
    Connection Timeout (s)Time in seconds to wait for GATT connection establishment before timing out.
    NotesFree-text notes or description.

    Subscribed GATT Characteristics (Points)

    Each configured BLE source maintains a list of GATT characteristic telemetry points. Points can be added automatically using the BLE Device & GATT Browser or manually created and edited via the dedicated Point Editor Dialog:

    Point ParameterDescription
    Friendly NameHuman-readable point name (e.g., Rotation, Movement, Heart Rate).
    Data TypeData conversion type: Int16, UInt16, Int32, UInt32, Float, Double, Bool, Byte, String.
    Byte OffsetZero-indexed byte offset within the raw characteristic payload buffer.
    Byte LengthLength in bytes to extract (used for strings or multi-byte payloads; set 0 for default).
    Service UUIDService UUID in 128-bit GUID format (e.g., 0000fff0-0000-1000-8000-00805f9b34fb) or 16-bit short hex (FFF0).
    Characteristic UUIDCharacteristic UUID in 128-bit GUID format (e.g., 0000fff1-0000-1000-8000-00805f9b34fb) or 16-bit short hex (FFF1).
    Access ModeSubscription mechanism: Notify (CCCD notifications), Indicate (CCCD indications), or ReadPolling.

    4. Exposed Routes & Data Types

    This plugin exposes catalog fields across the following rule graph nodes:

    Input Source

    The Input Source node reads GATT characteristic notifications and connection status.

    Human-Readable Field NameData TypeDescription
    Configured GATT Characteristic  Double` / `Int32` / `Bool` / `String
    ↳Live parsed telemetry value emitted via BLE notification or indication.
    Connection Status  Bool
    ↳Status flag indicating whether the GATT connection to the peripheral device is active (True).

    Data Source

    The Data Source node queries discovered BLE advertisement devices nearby.

    Human-Readable Collection NameData TypeExposed Fields & Data TypesDescription
    Discovered Devices  Json` (`collection`)
    ↳
    MacAddress (String)
    Name (String)
    Rssi (Int32)
    		Scanned list of nearby Bluetooth Low Energy devices broadcasting advertisement packets.

    Output Target

    The Output Target node acts as an action sink node to write binary payloads to writable GATT characteristics.

    Target NameData TypeAssociated ParametersParameter Data TypeRequiredDescription
    Configured Writable GATT Characteristic  String` / `Json
    ↳ValueString / JsonTrueRaw hex bytes or formatted string to write to peripheral characteristic.

    5. Usage Examples

    Scenario A: Reading Telemetry from a Single Characteristic

    Workflow Overview:

    A BLE wearable heart rate monitor broadcasts GATT characteristic 0x2A37 (Heart Rate Measurement) notifications. Uniflow subscribes to the characteristic via CCCD Notify, parses the incoming byte payload, and evaluates the heart rate value. When the heart rate exceeds 120 BPM, Uniflow writes a Modbus TCP holding register (HoldingRegister 50 = HeartRate) and dispatches an HTTP POST alert to the health monitoring dashboard.

    Setup Steps:

    1. Open the BLE Device Browser and start scanning for nearby BLE devices.

    2. Select your device and click Connect & Discover GATT Services.

    3. Check the desired characteristic (e.g., 0x2A37 Heart Rate Measurement) and click Import Selected Points.

    4. In the Rule Editor, add an Input Source node selecting your BLE device, and connect the characteristic output port to rule logic.

    Rule Node Configuration:

    1. Input Source Node: Bluetooth BLE

  • Characteristic: 0x2A37 Heart Rate Measurement (Int32)

    • 2. Logic Filter Node: GreaterThan

  • Expression: HeartRate > 120

    • 3. Output Target Node A: Modbus Client Writer

  • Action Target: Direct Access
  • Type: Holding Register
  • Address: 50
  • Value: HeartRate

    • 4. Output Target Node B: HTTP Client Action

  • Action Target: POST Request
  • URL: https://health.monitor.local/api/alerts

    • Logic Flow Diagram:

    VISUAL ARCHITECTURE FLOW DIAGRAM
    Rendering Flow Architecture Diagram...

    Scenario B: Multi-Value Proxy / IMU Payload

    Workflow Overview:

    When a BLE IMU device emits multiple sensor metrics packed inside a single 4-byte notification payload on Service FFF0 and Characteristic FFF1, Uniflow parses two independent telemetry values (Rotation at byte offset 0 and Movement at byte offset 2). When the Rotation value exceeds a threshold (Rotation > 500), Uniflow publishes a JSON alert payload to an MQTT broker topic sensors/imu/rotation.

    Setup Steps:

    1. Add Point 1: Name = Rotation, Service = FFF0, Characteristic = FFF1, DataType = Int16, ByteOffset = 0.

    2. Add Point 2: Name = Movement, Service = FFF0, Characteristic = FFF1, DataType = Int16, ByteOffset = 2.

    3. In the Rule Editor, both ports will emit independent stream values whenever the BLE characteristic payload updates.

    Rule Node Configuration:

    1. Input Source Node: Bluetooth BLE

  • Point: Rotation (Int16, ByteOffset 0)

    • 2. Logic Filter Node: GreaterThan

  • Expression: Rotation > 500

    • 3. Output Target Node: MQTT Client Publisher

  • Action Target: Direct Access
  • Topic: sensors/imu/rotation
  • Payload: {"rotation": ${Rotation}, "device": "IMU_01"}
  • QoS: 1

    • Logic Flow Diagram:

    VISUAL ARCHITECTURE FLOW DIAGRAM
    Rendering Flow Architecture Diagram...
    Architecture Flow Diagram — Full Preview