🔘
Flic smart button bridge
^{_{a balena and Docker container 🐳}}

Turn a Raspberry Pi or many single-board computers into a plug-in appliance to bridge your Bluetooth Flic smart buttons to your home automation system of choice, like Home Assistant.

Useful if your Flic buttons are located too far from your home automation hub, or if you need to use your hub's bluetooth antenna for something else.

• balena Dockerfile for ARM architecture based on Alpine Linux that weighs less than 40 MiB on a Raspberry Pi. ⚖️
• Regular Dockerfiles are available for traditional Docker stacks. 🐳
• Pre-built Docker images with multi-platform support are automatically kept updated on Docker Hub: ARM ones are Alpine-based while x86 ones are using Debian.

The Love Pi equation.

Why use the balena ecosystem? All the goodness of Docker, plus security handling, IoT hardware optimized images, read-only rootFS, a build pipeline, a device management interface, and continuous deployment, for free (well, first 10 devices on balenaCloud …or unlimited if you run your own OpenBalena platform).

Of course you could do all of this on your own, but do you really want to micro-manage, keep secure, always perform clean shutdowns, and generally baby something that should really be just plug-in, set-and-forget hardware? 🤔 I surely don't! 😅

🔝

Table of contents 📑

1. Prerequisites
2. balena
   1. Preparation
   2. Installation
   3. Pairing
   4. Unpairing
3. Docker
   1. Hub images
   2. Build and run
4. Alternatives
5. Contributing
6. Thanks

🔝

Prerequisites ✅

1. At least one Flic smart button.
2. Your favourite Internet of Things (IoT) device that offers both Bluetooth Low Energy (BLE) and network access, like the inexpensive Raspberry Pi Zero W.
3. Working access to an MQTT broker, either a public one, your own hosted Mosquitto instance or the Home Assistant addon.
4. (Recommended) A free-tier account on balenaCloud along with a properly set SSH public key into your account.
5. (Recommended) The balena command-line tools. Do read up on their friendly development guidelines.

Let's play! 🤠

🔝

balena 📦

Follow these simple steps to quickly get your app running on a dedicated device using balenaCloud. If you want more control, try the Docker solution instead.

For reference, the balena framework will build the container using the ./Dockerfile.template which employs placeholders so that the correct system architecture is picked for you during installation. Easy! 😃

Preparation 🍔

1. Create a new application on balenaCloud dashboard and select the appropriate IoT hardware.

2. Add a new device to your app. Start with development mode for local testing, or go directly for production mode if you know what you're doing.

3. (Optionally) Configure the downloaded image to give your device a custom hostname instead of the generic balena:

   sudo balena local configure /path/to/downloaded/image.img

4. Burn the image to a disk and boot your IoT device.

Your hardware is ready; it's now time to install the project! ⬇️

🔝

Installation 💻

1. Git clone this project's repository:

   git clone [email protected]:renemarc/balena-flic.git

2. Add your balena application as a secondary remote to the cloned repo:

   git remote add balena <username>@git.balena-cloud.com:<username>/<appname>.git

3. Push the code to balenaCloud and wait for it to build and provision your device:

   git push balena master

Great! You are now ready to pair your button. ⬇️

🔝

Pairing 💑

Since only one controller can be paired at a time, do make sure that your Flic button is unpaired from your mobile device by using the Flic mobile app to remove the button from its interface.

The easy way: Automatic pairing 🤖

Configure your Home Assistant (or other automation system) by pointing it to your device, say flic.local or 192.168.0.4, reload your configuration/restart the system, and let its auto-discovery system locate your button by pressing it for 7 seconds.

# Example Home Assistant configuration.yaml entry
binary_sensor:
  - platform: flic
    host: flic.local
    port: 5551
    discovery: true

The easy way.

🔝

The harder way: Manual pairing 🔩

Use this manual approach to pair your button if your home automation solution requires a more hands-on configuration.

1. SSH into your device's main container or use the balenaCloud dashboard terminal by starting the configuration tool:

   simpleclient localhost

2. Start the manual pairing procedure by issuing the following command to simpleclient and pressing on your Flic button for 7 seconds (or until something positive comes up on screen).

   startScanWizard

3. Take note of the MAC address shown to help you differentiate your various Flic buttons, then quit simpleclient by using CTRL+C then you are done.

4. Restart your home automation hub to have the changes be recognized.

The harder way.

🔝

Unpairing 💔

All buttons paired to your bridge have their configuration stored in the SQLite database found at /data/flic.sqlite. To unpair a button requires those entries to be removed and the changes be recognized.

Unpairing gracefully 🤝

Note: this method isn't currently working. Bummer. Use the manual approach below instead.

1. SSH into your device's main container or use the balenaCloud dashboard terminal and start the configuration tool:

   simpleclient localhost

2. List verified buttons:

   getInfo

3. Remove the unwanted button from the verified list, using its MAC address:

   removeButton 80:e4:da:XX:XX:XX

4. Restart your home automation hub to have the changes be recognized.

🔝

Unpairing manually 🖐️

Don't mind getting your hands a bit dirty? Dive in!

1. SSH into your device's main container or use the balenaCloud dashboard terminal and install SQLite:

   apk add sqlite

2. Open the database:

   sqlite3 /data/flic.sqlite

3. Delete your button's corresponding row from the database, using its MAC address:

   DELETE FROM buttons WHERE bdaddr = "80:e4:da:XX:XX:XX";
   .quit

4. Restart the bridge's main container.

5. Restart your home automation hub to have the changes be recognized.

🔝

Unpairing forcefully 💪

Patience, you must have. Use the Force, my young Padawan. ✨

1. Temporarily stop the main container, or turn off the bridge altogether, or walk out of range with your Flic (50+ meters).
2. Click the button once to see its light pulse red.
3. Use the Flic mobile app and follow their instructions to reclaim control.
4. Restart your home automation hub to have the button sensor removed from its list.

🔝

Docker 🐳

Want more control or wish to run this container on some multi-purpose shared hardware? Here are some useful steps.

Hub images 🖼

The project has automated builds available on Docker Hub, along with a multi-platform manifest to automatically download the appropriate image based on the detected architecture.

1. Run the Docker image as an auto-starting container:

   docker run --detach --restart=unless-stopped \
     --net=host --cap-add=NET_ADMIN \
     --name=flic \
     renemarc/balena-flic

2. Explore the container:

   docker logs flic

   docker exec -it flic bash

3. Proceed to the pairing steps above. ⬆️

See additional image instructions on Docker Hub. 👀

Docker images build pipeline details on Docker Hub.

🔝

Build and run 🏗

If you prefer more control, you sure can build your own images.

Compared to the balena solution, here there are two possible Dockerfiles:

• ./Dockerfile: Alpine-based version, used for ARM architectures. This file supports QEMU virtualization so that ARM images can be built on non-ARM hardware.

  Docker Hub uses this file to create automated builds; different architectures are supported through arguments in to the ./hooks/build Docker hook.

• ./Dockerfile-debian.Dockerfile: A Debian-based version, meant to support the x86_64 architecture as well as i386 through the same Docker build hook.

🔝

Build 👷

1. Fork or clone this project's repository.

2. Build the image:

   For a Raspberry Pi or Zero:

   docker build --tag=flic .

   For everything else, specify the ARCH_NAME argument with the relevant lowercase architecture name from balena base images.

   For a Raspberry Pi 3 for instance:

   docker build --build-arg ARCH_NAME=armv7hf \
     --tag=flic .

   To run Debian on an Intel NUC:

   docker build --build-arg ARCH_NAME=amd64 \
     --file Dockerfile-debian \
     --tag=flic .

3. Run the project as an auto-starting container:

   docker run --detach --restart=unless-stopped \
     --net=host --cap-add=NET_ADMIN \
     --name=flic \
     flic

   --net=host gives the container access to the host's network devices, including Bluetooth.
   --cap-add=NET_ADMIN gives the container network privileges.

4. Perform the pairing steps above ⬆️ while inside the container:

   docker exec -it flic bash

🔝

Alternatives 🔘

Other options exist, should you wish to try something else:

• The official Flic hub: Commercial solution, plug-n-play, supported. While it runs the same SDK as this balena project, it's likely a better solution if you have the money to spend.
• Flicd Hass.io addon by @pschmitt: for Home Assistant running on the HassOS stack. Requires exclusive access to Bluetooth antenna.
• Raspberry Pi 3 Docker image by @superkikim: based on Raspbian.
• Or this guy:

i can has nuke button?

🔝

Contributing 📝

Want to suggest some Docker improvements? Got some fringe hardware that you used to run this balena/Docker container on and had to tweak some config for it to work? Fork this repo and open a pull request so that all can benefit! 😃

🔝

Thanks 💕

This Docker container is based on the Hass.io addon by Philipp Schmitt (@pschmitt) and uses the official Flic SDK by Shortcut Labs (@50ButtonsEach).

🔝

Don't forget to ⭐️ this repo! 😃
_{Assembled with ❤️ in Montréal.}