Brewblox

# Tilt Hydrometer

The Tilt (opens new window) is a floating hydrometer and thermometer that publishes its values over Bluetooth.

The Tilt service listens to Bluetooth events, and pushes values to the Brewblox history database and UI.

Tilt widgets

# Installation

You can use the brewblox-ctl tool to add a new Tilt service to your system. This will create the ./tilt directory, and edit your docker-compose.yml file. The Tilt service will appear automatically in the UI.

brewblox-ctl add-tilt

# Configure ports

By default, the Tilt services uses MQTT over WSS (HTTPS websockets).

If you are using a non-default HTTPS port (e.g. if you run brewblox on a NAS), you'll also want to add --mqtt-port=<port> to the command.

# Device names

Whenever a Tilt is detected, it is assigned a unique name. The first Tilt of a given color will be named after the color. If you have more than one Tilt of a single color, the name will be incremented. For example, if you have three red Tilt devices, the names will be:

  • Tilt
  • Tilt-2
  • Tilt-3

Device names can be edited in the Brewblox UI, or in the ./tilt/devices.yml file. In the ./tilt/devices.yml file, device names are stored under names. The key is the device MAC address in uppercase without : separators, and the value is the name. If you edit the file, you must restart the service for the changes to take effect.

Example ./tilt/devices.yml:

names:
  DD7F97FC141E: Purple
  AA7F97FC141E: Red

Device names must:

  • Consist of at least 1, and at most 100 characters.
  • Contain only alphanumerical characters, spaces, and _-()|.

If device names do not meet these criteria, they will be sanitized on startup.

# Sensor synchronization

Measured values can be pushed to Spark Temp Sensor (External) blocks. To set this up, create the block, and add an entry under sync to the ./tilt/devices.yml file

names:
  DD7F97FC141E: Purple
  AA7F97FC141E: Red
sync:
  - type: TempSensorExternal
    tilt: Purple
    service: spark-one
    block: Purple Tilt Sensor

sync is a list of objects. Each object should have the following fields:

  • type is a constant value.
  • service is the Service ID of your Spark service.
  • block is the block ID of your Temp Sensor (External) block.

# Calibration

Calibration is optional. While the Tilt provides a good indication of fermentation progress without calibration, it's values can be less accurate than a traditional hydrometer. With calibration its accuracy is approximately that of a traditional hydrometer. If you wish to use your Tilt for anything beyond simple tracking of fermentation progress (e.g. stepping temperatures at a given SG value) it is recommended you calibrate your Tilt.

Calibration is available for SG and temperature values. For both, calibration data should be provided in a CSV file, with the syntax:

<device identifer>, <uncalibrated_value>, <calibrated_value>

The device identifier is either the Tilt MAC address without : separators (eg. DD7F97FC141E), or the device name (described above).

Device identifiers are case insensitive: black will match the device names black, Black, BLACK, etc.

SG Calibration

If you wish to calibrate your Specific Gravity readings, create a file called SGCal.csv in the ./tilt directory.

The uncalibrated values are the raw values from the Tilt. The calibrated values are those from a known good hydrometer or calculated when creating your calibration solution. Calibration solutions can be made by adding sugar/DME to water a little at a time to increase the SG of the solution. You can take readings using a hydrometer and the Tilt app as you go. You can include calibration values for multiple colours of Tilt in the calibration file.

Example ./tilt/SGCal.csv:

Black, 1.000, 1.001
Black, 1.001, 1.002
Black, 1.002, 1.003
Black, 1.003, 1.004
Red, 1.000, 1.010
Red, 1.001, 1.011
Red, 1.002, 1.012
Red, 1.003, 1.013
Red, 1.004, 1.014

You will need multiple calibration points. We recommend at least 6 distributed evenly across your typical gravity range for each Tilt. For example, if you usually brew with a starting gravity of 1.050, you may choose to calibrate at the values 1.000, 1.010, 1.020, 1.030, 1.040, 1.050, and 1.060. The more calibration points you have, the more accurate the calibrated values the service creates will be. Strange calibrated values from the service are an indication you have used too few or poorly distributed calibration values.

Temperature calibration

Calibration values for temperature are placed in a file called tempCal.csv in the ./tilt directory. Temperature values in the calibration file MUST be in Fahrenheit. The tempCal file can also contain calibration values for multiple Tilts. Again, it should contain at least 6 points distributed evenly across your typical range.

Example ./tilt/tempCal.csv:

Black,39,40
Black,46,48
Black,54,55
Black,60,62
Black,68,70
Black,75,76

Calibrated values will be logged in Brewblox separately to uncalibrated values. If you don't provide calibration values for a given colour of Tilt, only uncalibrated values will be logged. You don't need to calibrate both temperature and SG. If you only want to provide calibration values for SG, that works fine. Calibrated temp values would not be generated in this case but calibrated SG values would be.

It is also recommended that you re-calibrate SG whenever you change your battery. Different batteries and different placements of the sled inside the Tilt can affect the calibration.

# Installation on a remote machine

The Tilt service does not have to be installed on the same server as the rest of Brewblox. This is useful if it is not convenient to place the main Brewblox server within Bluetooth range of all your Tilts.

On the remote machine in the directory you wish to install the service, create a docker-compose.yml file like this with the relevant IP address for the brewblox host.

version: '3.7'
services:
  tilt:
    image: ghcr.io/brewblox/brewblox-tilt:${BREWBLOX_RELEASE:-edge}
    restart: unless-stopped
    privileged: true
    network_mode: host
    volumes: ['./tilt:/share']
    command: --mqtt-host=<brewblox_hostname/IP>

Create the directory for the tilt files

mkdir ./tilt

Start the service with the following command

docker-compose up -d

# Debugging

You have a Tilt, installed the service, and yet, no devices show up in the UI. This can have a variety of causes, but we'll focus on the most common.

A very important tool here is the Tilt service log. You can access it by running:

brewblox-ctl follow tilt

This will show new messages as they appear. Press Ctrl-C to exit.

Example output:

pi@raspberrypi:~/brewblox$ brewblox-ctl follow tilt
Attaching to brewblox_tilt_1
tilt_1            | 2022/01/18 15:07:24 INFO     brewblox_tilt.names             Device names loaded from `/share/devices.yml`: {'DD7F97FC141E': 'Purple'}
tilt_1            | 2022/01/18 15:07:24 INFO     brewblox_tilt.parser            Calibration values loaded from `/share/SGCal.csv`: keys=()
tilt_1            | 2022/01/18 15:07:24 INFO     brewblox_tilt.parser            Calibration values loaded from `/share/tempCal.csv`: keys=()
tilt_1            | 2022/01/18 15:07:24 INFO     brewblox_service.service        Service name: tilt
tilt_1            | 2022/01/18 15:07:24 INFO     brewblox_service.service        Service info:  @ Tue Jan 18 14:56:02 UTC 2022
tilt_1            | 2022/01/18 15:07:24 INFO     brewblox_service.service        Service config: {'host': '0.0.0.0', 'port': 5000, 'name': 'tilt', 'debug': False, 'mqtt_protocol': 'wss', 'mqtt_host': '172.17.0.1', 'mqtt_port': None, 'mqtt_path': '/eventbus', 'history_topic': 'brewcast/history', 'state_topic': 'brewcast/state', 'lower_bound': 0.5, 'upper_bound': 2, 'inactive_scan_interval': 5, 'active_scan_interval': 10, 'simulate': None}
tilt_1            | 2022/01/18 15:07:24 INFO     brewblox_service.mqtt           Starting <EventHandler for wss://172.17.0.1:443/eventbus>
tilt_1            | 2022/01/18 15:07:24 INFO     brewblox_service.mqtt           listen(brewcast/tilt/tilt/names)
tilt_1            | 2022/01/18 15:07:24 INFO     brewblox_service.mqtt           subscribe(brewcast/tilt/tilt/names)
tilt_1            | 2022/01/18 15:07:24 INFO     brewblox_tilt.broadcaster       Looking for Bluetooth adapter...
tilt_1            | 2022/01/18 15:07:24 INFO     brewblox_tilt.broadcaster       Found Bluetooth adapter hci0
tilt_1            | 2022/01/18 15:07:24 INFO     brewblox_tilt.broadcaster       HCI Version native = <HCIVersion.BT_CORE_SPEC_5_0: 9>
tilt_1            | 2022/01/18 15:07:24 INFO     brewblox_tilt.broadcaster       HCI Version env = None
tilt_1            | 2022/01/18 15:07:24 INFO     brewblox_tilt.broadcaster       HCI Version max = <HCIVersion.BT_CORE_SPEC_4_2: 8>
tilt_1            | 2022/01/18 15:07:24 INFO     brewblox_tilt.broadcaster       HCI Version used = <HCIVersion.BT_CORE_SPEC_4_2: 8>
tilt_1            | 2022/01/18 15:07:24 INFO     brewblox_service.mqtt           <EventHandler for wss://172.17.0.1:443/eventbus> connected
tilt_1            | 2022/01/18 15:07:30 INFO     brewblox_tilt.parser            Tilt detected: mac='DD7F97FC141E', color='Purple', name='Purple'

Hardware

  • Does the server have a working Bluetooth adapter?
  • Is the Tilt in range?

The first question can be checked in the service log. The service will wait idle until a Bluetooth adapter is found.

[...] Looking for Bluetooth adapter...
[...] Found Bluetooth adapter hci0

The second question is harder to answer. If you can do so, put the Tilt next to the server, to remove all doubt.

Bluetooth

  • Is the adapter powered?
  • Is Bluetooth Low Energy (BLE) enabled?

Host Bluetooth may be the problem if your Tilt service starts normally, but does not detect any devices. You can check whether it detected any devices by looking for log entries like this:

[...] Tilt detected: mac='DD7F97FC141E', color='Purple', name='Purple'

This is something that must be checked manually, as these are settings on the server itself, and the Tilt service can't access them all. To check this, we use the bluetoothctl tool.

brewblox-ctl down
sudo bluetoothctl

This will open a subshell to interact with bluetooth controllers. To list controllers, use list:

[bluetooth]# list
Controller B8:27:EB:49:54:3C raspberrypi [default]

If your controller is not marked as default, use select {MAC ADDRESS}:

[bluetooth]# select B8:27:EB:49:54:3C

To show detailed info, use show:

[bluetooth]# show
Controller B8:27:EB:49:54:3C (public)
        Name: raspberrypi
        Alias: raspberrypi
        Class: 0x00000000
        Powered: yes
        Discoverable: no
        Pairable: yes
        UUID: Generic Attribute Profile (00001801-0000-1000-8000-00805f9b34fb)
        UUID: A/V Remote Control        (0000110e-0000-1000-8000-00805f9b34fb)
        UUID: PnP Information           (00001200-0000-1000-8000-00805f9b34fb)
        UUID: A/V Remote Control Target (0000110c-0000-1000-8000-00805f9b34fb)
        UUID: Generic Access Profile    (00001800-0000-1000-8000-00805f9b34fb)
        Modalias: usb:v1D6Bp0246d0532
        Discovering: no

If Powered is no, then run power on

After that, go to the scan menu, enable BLE, and clear filters (if any). Use back to return to the main menu.

menu scan
clear
transport le
back

[bluetooth]# menu scan
Menu scan:
[...]
[bluetooth]# clear
SetDiscoveryFilter success
[bluetooth]# transport le
[bluetooth]# back
Menu main:
[...]

Then use scan on to start scanning for Bluetooth devices.

[bluetooth]# scan on
SetDiscoveryFilter success
Discovery started
[CHG] Controller B8:27:EB:49:54:3C Discovering: yes
[NEW] Device 78:E5:35:78:0F:94 78-E5-35-78-0F-94
[NEW] Device C4:DD:57:66:BB:1A PROV_BREWBLOX_66BB18
[NEW] Device 7A:6D:06:DD:0A:B3 7A-6D-06-DD-0A-B3
[NEW] Device DD:7F:97:FC:14:1E DD-7F-97-FC-14-1E
[CHG] Device 78:E5:35:78:0F:94 RSSI: -77
[CHG] Device C4:DD:57:66:BB:1A RSSI: -24
[CHG] Device 7A:6D:06:DD:0A:B3 RSSI: -67
[CHG] Device C4:DD:57:66:BB:1A RSSI: -36
[CHG] Device 7A:6D:06:DD:0A:B3 RSSI: -79
[CHG] Device DD:7F:97:FC:14:1E RSSI: -77
[CHG] Device DD:7F:97:FC:14:1E ManufacturerData Key: 0x004c
[CHG] Device DD:7F:97:FC:14:1E ManufacturerData Value:
  02 15 a4 95 bb 40 c5 b1 4b 44 b5 12 13 70 f0 2d  .....@..KD...p.-
  74 de 00 44 04 1e c5

In this case, DD:7F:97:FC:14:1E is a Tilt, but pretty much as soon as devices show up, it’s fine. Exit bluetoothctl by running exit, and start brewblox again.

exit
brewblox-ctl up

Eventbus communication

The Tilt service uses MQTT to publish data. If the device is found, is publishing Bluetooth events, and yet nothing shows up, the next step is to check the eventbus.

In the service log, it should show it is connected to the eventbus:

[...] <EventHandler for wss://172.17.0.1:443/eventbus> connected

If instead, it displays errors about not being able to connect, you may need to update the connection settings.

To directly check the published messages, install https://mqtt-explorer.com/ (opens new window). Connect it to the Pi address, with protocol mqtt and port 1883 (the default).

If everything is working as intended, you should see tilt messages both under brewcast/state and brewcast/history. The brewcast/history/tilt message may take a few seconds to show up.

MQTT Explorer tilt view

Still not fixed?

If these steps did not reveal the problem, please let us know, on either the forum, or on Discord. Be sure to include the output from brewblox-ctl log.

← Plaato Digital Airlock →