TILT Hydrometer @ Carl-Wilhelms-Bräu

Log data from a TILT Hydrometer to CSV files using a Raspberry Pi 3 B+ running a client application implementend with NodeJS:

    +---------------+           +---------------+           +---------------+
    |               |           |               |           |               |
    |     Tilt      | --------> | NodeJS client | --------> |    CSV file   |
    |               |           |               |           |               |
    +---------------+           +---------------+           +---------------+

Data are received using the @abandonware/noble package and streamlined based on RxJS observables. A user push button to start/stop data recording and status LED are implemented with the onoff package.

Application design

The Tilt hydrometer uses the iBeacon data format which is documented here and used to retrieve data from the device. A measurement is done every five seconds and the updated readings are sent via Bluetooth thereafter.

Remark: During development, it seemed that data is sent nearly every second.

An implementation of the iBeacon data format for NodeJS can be found in the @abandonware/noble package which is used to communicate with the hydrometer. As the tilt device sends data wrapped in the BLE minor and major fields, parsing the incoming data is required. The data protocol can be found here. The project node-beacon-scanner contains a parser for the iBeacon format which will be adopted.

In order to make all the measuremtens available for later analysis and visualization, every reading is stored in CSV files. The discover event is used for creating a RxJs observable. To listen just for the data broadcast by the Tilt Hydrometer and reduce the data rate, any incoming BLE beacon data is filtered first and then downsampled using RxJs' filter() and throttleTime() operators. Further data processing is attached to the observable via RxJs' map() operator.

Remark: Incoming data is downsampled, so that other values are ignored and not averaged.

The GPIOs available on header J1 are used to interact with the user push button and LED, the GPIOs (available on header J1) are used. These are accessed via the NodeJS module onfoff which additionally provides button interrupts and software-debounce. The hardware connections for button and LED are:

• Button: GPIO24 (Pin 18 on header J1) and 3V3 (Pin 17 on J1), debouncing is done in software, internal pull-down resistor is activated by default (see datasheet, pp. 102/103)
• LED: Connected via 68 Ohms to GPIO27 (Pin 13 on J1) and GND (Pin 14 on J1), calculate appropiate resistor value as needed

Are general pinout diagram for a Raspberry Pi 3 B/B+ can be found here.

Installation and configuration

Install Raspbian Lite on SD card or USB drive

Download the latest release of Raspbian Lite from the Raspbian homepage. After the download is completed, flash it onto the SD card or the USB drive using balenaEtcher.

In addition to boot from SD, some of the later Raspberry Pi models support USB boot to boot form USB drives such as USB flash drives, HDDs or SSDs. This can be handy due to improved data transfer rates and improved reliability - espcially when working with data-driven applications and interfaces such as databases.

User login and credentials

Package installation and system configuration requires user login on the Raspberry Pi. This can be done locally or remotely via SSH. The default user credentials pi / raspberry can be used for this, but it is highly recommended to change these credentials. In addition any user credentials stated below are just sample values an should be changed.

Basic configuration (before and after first boot)

If you want to access the Raspberry Pi in headless mode (without connecting keyboard, mouse and monitor to the Pi), you need to enable ssh. To do so, create an empty file with name ssh on the BOOT partition of the SD card or USB drive. In addition you can create Wifi credentials (for non-enterprise grade networks) as explained in the headless docs.

DHCP-based ethernet is enabled by default. However, setting-up a static IP address requires some further work for which you need to mount the main partititon of your SD card or USB drive. For this, a Mac or a Linux computer (or Virtual Machine) is needed. Futher information can be found here.

Enterprise-grade Wifi networks (such as eduroam at TU Braunschweig) can be configured after having access to the Raspberry Pi.

Install required packages, prerequisites and dependencies

1. Update package repositories and install latest packages:

    sudo apt-get update && sudo apt-get upgrade
   

2. Install additional packages:

    sudo apt-get install bluetooth bluez libbluetooth-dev libudev-dev bluez-hcidump libcap2-bin
   

3. Install latest LTS release of NodeJS as described here

4. Allow node processes to access bluetooth devices without bein executed as root:

    sudo setcap cap_net_raw+eip $(eval readlink -f `which node`)
   

Install files and enable systemd service

Copy the project files to the Raspberry Pi via SSH/SCP, (S)FTP ... or copy/clone the projects repository into pi's user directory. You can choose an alternative user name, user group or directory name if you change tilt.service to your needs.

After the code is available on the Raspberry Pi, you can either install all the required dependencies on your own or install all dependencies automatically by calling

    npm install

In order to execute tilt.js automatically after the system is booted, a systemd service file is provided. If you want to use the service, follow these steps:

1. Copy the .service file to the appropriate location:

    sudo cp ~/tilt/tilt.service /etc/systemd/system
   

2. Enable the service to systemd:

    sudo systemctl enable tilt
   

3. Check the service status to check if it was loaded properly:

    sudo systemctl status tilt
   

4. Start the service manually (if you do not want to reboot the system):

    sudo systemctl start tilt
   

Configuration

User configurable values are defined in config.js. If you use a different user names or group to execute the client application you need to change tilt.service accordingly.

Data files

Csv files containing the sensor readings are written to the ~/tilt/export directory by default. You can access these files with your favourite SSH/SCP or (S)FTP client.

Debugging

Log files

The systemd service logs into the global syslog, which can be accessed via journalctl -t tilt-client. Some very basic diagnostics (about the systemd service) can be obtained from systemctl by using systemctl status tilt.

Bluetooth connection

For testing and debugging the Bluetooth connection to the Tilt Hydrometer, hcitool lescan and hcidump -R can be used. In addition, to check the BLE-module is working, Nordic Semiconductor's app nRF Connect for Mobile is handy.

Issues

Feel free to submit any issues and feature requests using the Issue Tracker.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. In general, we are using a "fork-and-pull" workflow:

1. Fork the repo on GitHub.
2. Clone the project to your own machine.
3. Commit changes to your own branch.
4. Push your work back up to your fork.
5. Submit a Pull request so that we can review your changes.

License Information and module dependencies

This project is published under the MIT Licencse. A copy of the license text can be found in LICENSE.md.

Direct dependencies, this project depends on, are:

Module	license	Repo	npm
noble	MIT	Link	Link
onoff	MIT	Link	Link
moment	MIT	Link	Link
rotating-file-stream	MIT	Link	Link
rxjs	Apache 2.0	Link	Link