homebridge-bt-volume-sensor

• Characteristic.BatteryLevel
• Characteristic.StatusLowBattery

Preparation, Homebridge, Bluetooth and Serialport

This plugin is written to support Bluetooth Low Energy (BLE) communication in combination of homebridge. The plugin use the functionality of Bluetooth and SerialPort tested on a Raspberry Pi Zero W. The sensor should send HAP conform json data on a bluetooth serial interface. The plugin work 'silence' at this time to save sensor battery capacity, just transfer data if received from the sensor. It means, the measuring and data sending/updating interval should set (ex. by the sensor RTC) by the sensor itself.
It seems, the serial port library, required by this plugin, is written to support external USB bluetooth dongle and load USB libraries in the background. Because of lower ARM6l processor on Raspberry Pi Zero W, not all library versions might without errors. They have to work with node version 9.9, the last supported node version for Pi Zero. In my case i got an additionally node-gyp error too, because of missing serialport bindings. It could be solved by stepping into the node module sub directory .../homebridge-bt-volume-sensor/node_modules/@serialport/bindings and 'sudo node-gyp configure build'.

To use the serial port, the homebridge user need rights to access the serial port (/dev/refcomm). The /dev/rfcommX is a virtual device created if needed. If you like to get the whole system runs automatically, the rfcommX device must runs automatically too - AND before the homebrige comes up. I realized that by systemctl services. A possible way is:

bluetooth.service--> rfcomm.service--> homebridge.service, bind together with EXECStartPost/Pre, After or Required statements.

The virual rfcomm device normally will be created under user group dailout. To communicate over that virtual refcomm device, the homebrigde user needs the right do do this. I realized that by /etc/udev/rules.d/99-com.rules (SUBSYSTEM=="rfcomm0", GROUP="dailout", MODE="0660") to make the device accessible and sudo adduser homebridge dialout.

With that, bluetooth, rfcomm and homebridge comes up and the homebridge is able to communicate along the SerialPort library. The plugin needed to be setup with the rfcomm device you like to use, ex. rfcomm0.

What is this plugin doing?

This plugin is motivated by the idea of automated garden care, using rainwater for watering the garden. If you use a cistern below the earth surface to collecting rainwater, it could difficult to estimate, how much water is in the cistern. Combined with a soil moisture sensor, you can create an automatic watering systems. Mostly cisterns are geometric cylinder or cuboid, so they have a footprint and a height. The plugin should receive distance values in 'cm' produced - as an example - by a ultrasonic sensor. It takes that as "height difference" and calculate the amount of water in percent. If needed, some parameter can be left blank and the result of the plugin is just the measured distance.
The use case is to measure the volume periodically, the sensor itself decided the time laps for measuring and sending data (ex. triggered by the device RTC). That behavior should help to save battery life of battery powered sensors. Send the sensor data, the values will be overwritten immediately and cached until the next data will be received. The plugin use the homekit characteristic of a battery: "BatteryLevel" to calculate the volume in percent and "StatusLowBattery" to inform about the status of the sensor battery. The plugin except json data in the form of:

{"BatteryLevel": value, "StatusLowBattery": value }

The BatteryLevel represents the sensor measured distance, the StatusLowBattery represents the sensor battery voltage.

Installation

1. Install homebridge by using: npm install -g homebridge (maybe --unsafe-perm, see documentation of homebridge)
2. Prepare the homebridge config script with footprint and height, that gives the max volume of the cistern/container for calculation
3. Install the bluetooth volume plugin by using: npm install -g homebridge-bt-volume-sensor.
4. Prepare the sensor to send correct json data

Example config.json

{
    "accessories": [
        {
          "accessory": "BluetoothVolumeSensor",
          "name": "my Sensor",
          "footprint": 10000,
          "height": 100    

        }   
           ]
 }

• accessory (mandatory) "BluetoothVolumeSensor" (type: string)
• name (mandatory) It will appear in the Home app (type: string)
• footprint and height (optional) if not given, the result is the measured distance in centimeter. footprint should be set as square centimeter, height should be set as centimeter, to get the correct measuring results in percent. (type: integer)