README.md 4.33 KB
Newer Older
1
Flic Button Home Assistant Controller
Erick Hitter's avatar
Erick Hitter committed
2 3
=====================================

4
A node.js module to control [Home Assistant](https://home-assistant.io/) entities via [Flic smart buttons](https://flic.io/).
Erick Hitter's avatar
Erick Hitter committed
5 6 7

## Prerequisties

8
* At least one Flic button (multiple are supported and can control discrete services)
Erick Hitter's avatar
Erick Hitter committed
9
* [Home Assistant](https://home-assistant.io/)
10
* The `flicd` daemon [from Flic's Linux SDK](https://github.com/50ButtonsEach/fliclib-linux-hci) running somewhere accessible to the device running this script
Erick Hitter's avatar
Erick Hitter committed
11 12 13

## Install

Erick Hitter's avatar
Erick Hitter committed
14 15
	git clone https://git.ethitter.com/open-source/flic-button-home-assistant-controller.git
	cd flic-button-home-assistant-controller
16
	git submodule update --init --recursive
Erick Hitter's avatar
Erick Hitter committed
17 18
	npm install

19
### `flicd` Preparation
Erick Hitter's avatar
Erick Hitter committed
20

21
If `flicd` and this script are not run from the same device, ensure that `flicd` is started with the `-s` flag set either to `0.0.0.0` or the IP of the device running the controller.
Erick Hitter's avatar
Erick Hitter committed
22 23 24

## Configuration

25
1. Register Flic buttons with `flicd` and note the Bluetooth MAC addresses of the various buttons
Erick Hitter's avatar
Erick Hitter committed
26
1. Rename `config-sample.json` to `config.json`. Update its values to match your configuration, including the buttons discovered in the last step.
27 28 29 30
1. Start the listener with `npm start`.

## FAQ

31
**Can I run `flicd` as a daemon/at startup?**
32

33
Yes. See https://ethitter.com/p/9738/ for a `systemd` service file.
34 35 36

**How is the `buttons` property of `config.json` structured?**

37
Each object within the `buttons` property is structured according what effect the click should have on an entity in its current state. For example, if the light is off, what should a single-click do.
38 39 40 41 42 43 44

	"mac": {
		"mac": "mac",
		"label": "Lamp",
		"status": {
			"entity_id": "switch.lamp"
		},
45 46 47 48 49 50 51 52 53 54 55
		"single": {
			"on": {
				"entity": "switch",
				"entity_id": "switch.lamp",
				"entity_action": "turn_off"
			},
			"off": {
				"entity": "switch",
				"entity_id": "switch.lamp",
				"entity_action": "turn_on"
			}
56 57 58 59 60 61 62 63 64 65 66
		}
	}

The above example simply switches a light on and off, depending on its current state. There can be any number of state entries in an individual button's object, however. A button could be configured only to respond to the "on" state by omitting the "off" entry, or if the entity returns other states, those could also be handled. An example of this comes when interacting with Smart Home Assistant, which has three states:

	"mac": {
		"mac": "mac",
		"label": "Smart Home Monitor",
		"status": {
			"entity_id": "alarm_control_panel.shm"
		},
67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106
		"single": {
			"disarmed": {
				"entity": "alarm_control_panel",
				"entity_id": "alarm_control_panel.shm",
				"entity_action": "alarm_arm_home"
			},
			"armed_home": {
				"entity": "alarm_control_panel",
				"entity_id": "alarm_control_panel.shm",
				"entity_action": "alarm_disarm"
			},
			"armed_away": {
				"entity": "switch",
				"entity_id": "switch.lamp",
				"entity_action": "turn_on"
			}
		}
	}

In this example, if the alarm isn't active, or is set to the "armed home" state, its Flic button will toggle between those states. If, however, one tried to use the button to disable the alarm when no one is home (motion sensors are active, among other changes), the button will simply turn on a light; it won't disarm the alarm, as that's something I only allow for those who have access to Home Assistant or SmartThings directly.

As three click types--`single`, `double`, and `hold`--are supported, adding responses to the new click types is a matter of updating `config.json` to define how those clicks are handled.

	"mac": {
		"mac": "mac",
		"label": "Lamp",
		"status": {
			"entity_id": "switch.lamp"
		},
		"single": {
			"on": {
				"entity": "switch",
				"entity_id": "switch.lamp",
				"entity_action": "turn_off"
			},
			"off": {
				"entity": "switch",
				"entity_id": "switch.lamp",
				"entity_action": "turn_on"
			}
107
		},
108 109 110 111 112 113 114 115 116 117 118
		"double": {
			"on": {
				"entity": "switch",
				"entity_id": "switch.lamp",
				"entity_action": "turn_off"
			},
			"off": {
				"entity": "switch",
				"entity_id": "switch.lamp",
				"entity_action": "turn_on"
			}
119
		},
120 121 122 123 124 125 126 127 128 129 130
		"hold": {
			"on": {
				"entity": "switch",
				"entity_id": "switch.lamp",
				"entity_action": "turn_off"
			},
			"off": {
				"entity": "switch",
				"entity_id": "switch.lamp",
				"entity_action": "turn_on"
			}
131 132 133
		}
	}

134
This isn't a particularly interesting example, as all three click types perform the same action, but it demonstrates what's possible.