Homebridge 2 - Flicd Gateway

Homebridge 2 platform plugin for Flic buttons paired directly to a Linux host through flicd.

NPM package name: homebridge-flicd-gateway

Author: Peter C. Glade

This plugin is intended for setups where the Flic button is connected to the same machine that runs Homebridge, for example a Raspberry Pi with Bluetooth. It does not require a Flic Hub. It does not pair buttons itself; pairing remains the job of flicd.

What It Does

homebridge-flicd-gateway connects to the local Flic daemon, reads the list of verified buttons, and exposes each button to HomeKit as a StatelessProgrammableSwitch.

Supported HomeKit button events:

• Single press
• Double press
• Long press

Typical flow:

Flic button -> Bluetooth -> flicd -> homebridge-flicd-gateway -> HomeKit automation

Requirements

• Homebridge 2.x
• Node.js 20 or newer
• Linux host with Bluetooth support
• flicd running and reachable from Homebridge
• At least one Flic button already paired/verified with flicd
• An Apple Home hub if you want HomeKit automations to run reliably while your phone is away

This plugin has been tested with Homebridge 2.2.1, Node.js 24, and flicd listening on localhost:5551.

Install

Install from the Homebridge UI after the package is published, or from the command line in your Homebridge storage directory:

npm install homebridge-flicd-gateway

For a local tarball during development:

npm install /path/to/homebridge-flicd-gateway-0.2.0.tgz

Then restart Homebridge.

Pair A Flic Button

Pairing is handled outside Homebridge. A common setup is the Linux flicd daemon from fliclib-linux-hci.

The exact commands depend on how flicd is installed on your system, but the process is:

1. Start flicd.
2. Run the Flic scan wizard/tool for your flicd installation.
3. Press the Flic button when prompted.
4. Confirm that flicd lists the button as verified.

This plugin can only expose buttons that flicd already knows about.

Configuration

Minimal configuration:

{
  "platform": "FlicdPlatform",
  "name": "Homebridge 2 - Flicd Gateway",
  "host": "localhost",
  "port": 5551,
  "autoDiscover": true,
  "ignoreQueued": true
}

With explicit names:

{
  "platform": "FlicdPlatform",
  "name": "Homebridge 2 - Flicd Gateway",
  "host": "localhost",
  "port": 5551,
  "autoDiscover": true,
  "ignoreQueued": true,
  "buttons": [
    {
      "bdAddr": "80:e4:da:76:ee:14",
      "name": "Desk Flic"
    }
  ]
}

If autoDiscover is enabled, every verified button reported by flicd is exposed. The buttons list is still useful for assigning stable, human-readable names.

If autoDiscover is disabled, only buttons listed in buttons are exposed.

Options

| Option | Type | Default | Description | | --- | --- | --- | --- | | platform | string | required | Must be FlicdPlatform. | | name | string | Homebridge 2 - Flicd Gateway | Name shown in Homebridge logs and UI. | | host | string | localhost | Hostname or IP address where flicd is listening. | | port | number | 5551 | TCP port for flicd. | | autoDiscover | boolean | true | Expose all verified buttons reported by flicd. | | ignoreQueued | boolean | false | Ignore queued Flic events delivered after reconnects. Recommended for HomeKit automations. | | buttons | array | [] | Optional button definitions with Bluetooth address and display name. |

Button definition:

| Option | Type | Description | | --- | --- | --- | | bdAddr | string | Flic Bluetooth address. Colons are optional; 80:e4:da:76:ee:14 and 80e4da76ee14 are both accepted. | | name | string | HomeKit accessory name for this button. |

Create HomeKit Automations

The plugin only exposes button events. The actions are configured in Apple Home.

In the Home app:

1. Open Automation.
2. Add a new automation.
3. Choose the Flic button as the trigger.
4. Select Single Press, Double Press, or Long Press.
5. Choose the HomeKit accessories or scenes to control.

Examples:

• Single press: toggle a light strip.
• Double press: set a scene.
• Long press: turn off all lights in a room.

Apple Home may not always show stateless buttons as prominent room tiles. If you do not see the button on the main screen, look for it while creating an automation.

Logs

On successful startup you should see log lines similar to:

[Flicd] Connecting to flicd at localhost:5551.
[Flicd] Connected to flicd.
[Flicd] flicd reports Bluetooth controller Attached and 1 verified button(s).
[Flicd] Added Flic button accessory: Flic 76ee14 (80:e4:da:76:ee:14).

When pressing a button:

[Flicd] Flic 76ee14 - ButtonSingleClick.
[Flicd] Flic 76ee14 - ButtonDoubleClick.
[Flicd] Flic 76ee14 - ButtonHold.

Troubleshooting

No Button Appears In HomeKit

Check the Homebridge log for:

[Flicd] flicd reports Bluetooth controller Attached and 0 verified button(s).

If it reports zero buttons, pair the button with flicd first. Homebridge cannot discover unpaired Flic buttons on its own.

Cannot Connect To flicd

Check that flicd is running and listening on the configured host and port:

nc -z localhost 5551

If Homebridge runs in a container or on another host, localhost may point to the wrong machine. Set host to the address where flicd is reachable.

Button Appears But Automations Do Not Run

Verify that Homebridge logs button events when you press the Flic. If the log events appear, the plugin is working and the issue is in Apple Home automation setup.

Also check that you have a Home hub if you expect automations to run when your iPhone is not present.

Automations Fire After A Restart

Flic can deliver queued events after reconnecting. Set:

"ignoreQueued": true

This is recommended for most HomeKit automation setups.

Button Name Changed But Home Still Shows The Old Name

HomeKit can cache accessory names. Rename the accessory in Apple Home, or remove and re-add the cached accessory from Homebridge if you need a clean reset.

Development

Install dependencies:

npm install

Run the syntax check:

npm test

Build a local package:

npm pack

Install the resulting tarball into a Homebridge instance:

cd /var/lib/homebridge
npm install /path/to/homebridge-flicd-gateway-0.2.0.tgz

Limitations

• Pairing is not implemented by this plugin.
• Battery level is not exposed yet.
• Button removal from flicd is not automatically reflected when autoDiscover is enabled.
• This plugin depends on flicd and the fliclib-daemon-client protocol.

License

MIT