Skip to content

πŸ”˜ Flic smart button bridge for single-board computers: a balena and Docker container. 🐳

License

Notifications You must be signed in to change notification settings

renemarc/balena-flic

Repository files navigation

πŸ”˜
Flic smart button bridge
a balena and Docker container 🐳

Price License GitHub Release Flic SDK Version Docker Travis CI balena.io PRs Welcome Tweet

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.

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
Easy button

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.

Homer Simpson pressing a button

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.

Containers being moved in a yard

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. πŸ‘€

πŸ”

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:

πŸ”

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
Buzz Lightyear saying Containers everywhere!

πŸ”

Alternatives πŸ”˜

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

Cat pressing a nuclear button

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.

About

πŸ”˜ Flic smart button bridge for single-board computers: a balena and Docker container. 🐳

Topics

Resources

License

Code of conduct

Stars

Watchers

Forks

Packages

No packages published