Skip to content

BLE – Bluetooth Low Energy

The firmware contains a dedicated real-time task that is responsible for transmitting system status and configuration data over Bluetooth Low Energy (BLE). This task continuously runs, checking for an active BLE connection and sending structured data when connected.

Functionality

BLE communication enables the base station to interact with a mobile app for configuration and monitoring. The mobile app can be used to configure the system, view system status, control the pump, and add the device to a Wi‑Fi network.

The system gathers and transmits the following key parameters:

  • Tank Level
  • Minimum and Maximum Threshold Values
  • Connectivity Status:
    • Wi‑Fi and LTE connection flags
    • RSSI value (signal strength)
  • Pump Operation Timer: increments every second while the pump is running
  • Base Station MAC Address
  • ADV_ID: A 6-byte identifier parsed from a colon-separated string
  • Access Point Name (APN) Configuration: for the internal SIM7672X LTE modem
  • IMEI: a 15-character identifier
  • Current Firmware Version
  • Sensor Type (e.g., "2bar", "10bar")
  • Raw Zero ADC Value (sensor calibration data)
  • Raw Known ADC Value (sensor calibration data)
  • BLE Payload String (Raw data from sensor)
  • Level Known (Calibrated level from sensor)
  • Tank Height (User configured)
  • Push Token (For mobile app notifications)
  • System Flags: (wifiOnly, triggers_active, rebootOnConnectivityLoss, mute)

These data are packed into a structured payload that is sent over the Pump Data Characteristic (see below) and updates the BLE client.

BLE Characteristics

The main BLE service includes the following characteristics:

Wi‑Fi Credentials Characteristic

This characteristic is used to send Wi‑Fi credentials to the device. The credentials are XOR-encrypted using the device's MAC address as the key.

  • UUID: f3b5a8d4-2b6e-4a1b-8b1e-3c4d5e6f7a94
  • Properties: Read, Write, Notify
  • Data Format (Write): Encrypted JSON object with the following fields:
    • ssid: The SSID of the Wi‑Fi network.
    • password: The password of the Wi‑Fi network.
  • Data Format (Read/Notify): Plaintext string "ssid,password". Note: This is for debugging/low-risk scenarios and may be changed for security.

Note: This replaces the need for a captive portal that was used in previous versions.

Pump Control Characteristic

This characteristic allows control over the pump and other device settings.

  • UUID: f3b5a8d4-2b6e-4a1b-8b1e-3c4d5e6f7a8b
  • Properties: Read, Write
  • Data Format (Write): A string representing a command or setting. Examples:
    • 1: Start the pump (sets ble_trigger_state to true).
    • 0: Stop the pump (sets ble_trigger_state to false).
    • apn:<apn_value>: Sets the APN.
    • min:<value>: Sets the minimum tank level.
    • max:<value>: Sets the maximum tank level.
    • restart: Restarts the device.
    • lcgt:<value>: Sets level_condition_gap_threshold.
    • rocl:<0_or_1>: Sets rebootOnConnectivityLoss.
    • cal:<sensorType>,<rawZero>,<totalHeight>: Sets sensor calibration data.
    • active:<0_or_1>: Sets triggers_active.
    • pushtoken:<token>: Sets the push notification token.
    • mute:<0_or_1>: Sets the mute state.
    • level_known:<value>: Sets the known level.
    • raw_known:<value>: Sets the known raw ADC value.
    • rawset:<adv_id>,<raw_zero>: Sets the ADV_ID and raw zero for a sensor.

Pump Data Characteristic

This characteristic encapsulates all the data shared with the BLE client (mobile app). The payload is a fixed 128-byte array formatted as follows:

Byte(s) Description
0–1 Current Tank Level – 16-bit unsigned integer (little-endian)
2–3 Minimum Level – 16-bit unsigned integer
4–5 Maximum Level – 16-bit unsigned integer
6 Connectivity Flags – Bit 0: Wi‑Fi connected; Bit 1: LTE connected
7 RSSI Value – 8-bit unsigned integer (obtained via getRSSI())
8–9 Pump Timer – 16-bit unsigned integer (increments every second while the pump is running)
10–15 Base Station MAC Address – 6 bytes
16–21 ADV_ID – current sensor 6-byte array parsed from a colon-separated string
22–32 Access Point Name (APN) – 10 characters plus a null terminator (11 bytes total)
33–47 IMEI – 15 characters (without an additional null terminator)
48-55 Current Firmware Version - 8 characters
56-61 Sensor Type - 6 characters
62-65 Raw Zero ADC Value - 32-bit unsigned integer
66-69 Raw Known ADC Value - 32-bit unsigned integer
70-73 BLE Payload String (Sensor Raw Data) - 32-bit integer from string
74-77 Level Known - 32-bit unsigned integer
78-81 Tank Height - 32-bit unsigned integer
82-111 Push Token - 30 characters
112 System Flags - Bit 0: wifiOnly; Bit 2: triggers_active; Bit 3: rebootOnConnectivityLoss; Bit 4: mute

Note: The payload structure is designed to be efficient and will be updated as new features are added.

Serial Debugging Characteristic

This characteristic sends AT commands to the device, which are then relayed to the ESP32’s serial port (Serial1) for debugging and modem testing. The response from the modem is sent back via notification.

  • UUID: f3b5a8d4-2b6e-4a1b-8b1e-3c4d5e6f7a93
  • Properties: Read, Write, Notify
  • Data Format (Write): String containing the AT command (e.g., "CGSN" for IMEI). The "AT+" prefix is added by the firmware.
  • Data Format (Read/Notify): String containing the modem's response.

Local Storage Characteristic

This characteristic is intended for interacting with local storage on the device. Currently, its functionality is limited.

  • UUID: f3b5a8d4-2b6e-4a1b-8b1e-3c4d5e6f7a95
  • Properties: Read, Write, Notify
  • Data Format (Write): Integer value. Case 1 sends a debug message via MQTT.
  • Data Format (Read): Currently returns "TODO".

Sensor MAC Characteristic

This characteristic is used to read and write the MAC address of the connected water level sensor (ADV_ID).

  • UUID: f3b5a8d4-2b6e-4a1b-8b1e-3c4d5e6f7a96
  • Properties: Read, Write, Notify
  • Data Format (Write): String representing the sensor MAC address (e.g., "00:11:22:33:44:55"). Writing to this characteristic updates the adv_id preference and restarts the device.
  • Data Format (Read): The current sensor MAC address.