Complete docs

This commit is contained in:
Ariel Sosnovsky committed 2023-11-02 10:43:39 -04:00
1 parent 2a1efb2aff
commit edb64063ba
11 files changed
+155 -37

No files matched your search

+65 -4
View File
@@ -1,6 +1,25 @@
# flic2hass
# Flic2Hass
A Flic SDK utility to publish all of your Flic buttons to Home Assistant via MQTT as well control the onboard IR module.
This is a complete refactor of various previous versions of flic2hass. This version provides more features and even supports the onboard IR module!
## Features
### Complete Overview of Buttons
![Alt text](images/btn.png)
* Show connectivity state
* Show click action types: `click` `hold` `double_click`
* Detect presses: `released` `pressed`
* Battery Logging
* Extract firmware & sofware version numbers
### IR Module Support
* Record remote signals
* Send remote signals
![Alt text](images/ir.png)
Requirements:
@@ -34,7 +53,6 @@ Requirements:
require("./lib").start(
require("buttons"),
require("ir"),
"0",
{
mqtt: {
host: "set-this-to-yours",
@@ -84,7 +102,50 @@ The setup example contains just the bare minimum changes, if you wish to play ar
},
"flicIR": {
"disabled": false, // Do not publish IR events
"debug": false // Enable debug logging for IR related things
"debug": false, // Enable debug logging for IR related things
"uniqueId": "0", // Special identifier for your IR module (only change this value if you have more than 1 FlicHub or your hub somehow supports more than 1 IR modules)
},
}
```
## How to record & send IR messages
### Record Signal
1. Toggle the "Record Signal Entity" to `on`
![Alt text](images/ir-on.png)
2. Point the remote at your recievet dongle and press the button you want to use
3. The signal should show up in the "Signal Textbox Entity" and the "Record Signal Entity" will be automatically switched off
![Alt text](images/ir-recorded.png)
4. Copy the content of the "Signal Textbox Entity" to use during replaying of the signal
*Tip*: if nothing gets recorded, please check the logs in the flichubsdk
### Play Signal
1. Copy the signal you want to play into the "Signal Textbox Entity"
![Alt text](images/ir-recorded.png)
2. Press the "Play Signal" button
*Tip*: if nothing happens when you play, check that the signal you copied is correctly showing in the logs in the flichubsdk
### FAQ
* Why is the battery always 100%?
I found that with some of my buttons as well the battery is reported to always be 100%, this seems to me like an issue with either the hub itself or the buttons. Will need to open a ticket to have Flic Inc to explain to us why.
* Will you support the Twist?
I don't have a twist to test yet, though it seems that the [SDK does not support](https://community.flic.io/topic/18319/update-sdk-to-use-the-flictwist/15?_=1698935936114&lang=en-US) this yet, so I won't be able to support it either. I will contemplate buying one once the support is there!
* Can you add support for audio?
It seems that the SDK does not have support to control the onboard audio. I did post this on the [community board so +1](https://community.flic.io/topic/18350/add-support-for-playing-sounds) and maybe it will get there!
BIN
View File
Binary file not shown.

After

Width:  |  Height:  |  Size: 148 KiB

BIN
View File
Binary file not shown.

After

Width:  |  Height:  |  Size: 67 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 65 KiB

BIN
View File
Binary file not shown.

After

Width:  |  Height:  |  Size: 140 KiB

+57 -18
View File
@@ -87,7 +87,8 @@ var ENTITIES = {
action: [
"sensor",
{
icon: "mdi:gesture-tap-button"
icon: "mdi:gesture-tap-button",
name: "Click Action"
}
],
state: [
@@ -103,16 +104,38 @@ var ENTITIES = {
device_class: "battery"
}
],
batteryLastUpdate: [
"sensor",
{
name: "Battery Last Update Time",
device_class: "duration",
unit_of_measurement: "s"
}
],
connected: [
"binary_sensor",
{
device_class: "connectivity"
device_class: "connectivity",
name: "Connection Established"
}
],
ready: [
"binary_sensor",
{
device_class: "running"
device_class: "connectivity",
name: "Connection Verified"
}
],
activeDisconnect: [
"binary_sensor",
{
name: "User Active Disconnect"
}
],
passive: [
"binary_sensor",
{
name: "Passive Mode"
}
]
};
@@ -147,11 +170,6 @@ function makeButtonController(ha, buttonModule) {
payload_available: "ON",
payload_not_available: "OFF",
topic: ha.genFlicPrefix(genButtonUniqueId(button.bdaddr), "ready")
},
{
payload_available: "ON",
payload_not_available: "OFF",
topic: ha.genFlicPrefix(genButtonUniqueId(button.bdaddr), "connected")
}
],
availability_mode: "all"
@@ -172,8 +190,11 @@ function makeButtonController(ha, buttonModule) {
};
var publishButtonMeta = function(button) {
ha.publishState(genButtonUniqueId(button.bdaddr), "battery", button.batteryStatus);
ha.publishState(genButtonUniqueId(button.bdaddr), "batteryLastUpdate", button.batteryTimestamp ? "".concat(Math.round((Date.now() - button.batteryTimestamp) / 1000)) : "unknown");
ha.publishState(genButtonUniqueId(button.bdaddr), "connected", button.connected ? "ON" : "OFF");
ha.publishState(genButtonUniqueId(button.bdaddr), "ready", button.ready ? "ON" : "OFF");
ha.publishState(genButtonUniqueId(button.bdaddr), "activeDisconnect", button.activeDisconnect ? "ON" : "OFF");
ha.publishState(genButtonUniqueId(button.bdaddr), "passive", button.activeDisconnect ? "ON" : "OFF");
};
var addBtn = function(eventName) {
return function(obj) {
@@ -184,9 +205,15 @@ function makeButtonController(ha, buttonModule) {
};
var start = function() {
logger.info("Starting...");
var resetActiontInv = null;
buttonModule.on("buttonAdded", addBtn("buttonAdded"));
buttonModule.on("buttonConnected", addBtn("buttonConnected"));
buttonModule.on("buttonReady", addBtn("buttonReady"));
buttonModule.on("buttonReady", function(btn) {
addBtn("buttonReady")(btn);
var button = buttonModule.getButton(btn.bdaddr);
publishButtonState(button, "released");
publishButtonAction(button, "none");
});
buttonModule.on("buttonUpdated", addBtn("buttonUpdated"));
buttonModule.on("buttonDeleted", function(btn) {
logger.debug("buttonDeleted", JSON.stringify(btn, null, 4));
@@ -210,9 +237,15 @@ function makeButtonController(ha, buttonModule) {
publishButtonMeta(btn);
});
buttonModule.on("buttonSingleOrDoubleClickOrHold", function(obj) {
if (resetActiontInv !== null) {
clearTimeout(resetActiontInv);
}
var btn = buttonModule.getButton(obj.bdaddr);
publishButtonAction(btn, obj.isSingleClick ? "click" : obj.isDoubleClick ? "double_click" : "hold");
publishButtonMeta(btn);
resetActiontInv = setTimeout(function() {
publishButtonAction(btn, "none");
}, 500);
});
logger.info("Registering all buttons...");
buttonModule.getButtons().forEach(registerButton);
@@ -311,8 +344,9 @@ function makeHAmqtt(mqttServer) {
var registerEntity = function(name, component, nodeId, objectId, device) {
var additionalProps = arguments.length > 5 && arguments[5] !== void 0 ? arguments[5] : {};
var configtopic = genHAPrefix(component, nodeId, objectId) + "/config";
var configObj = _object_spread_props$1(_object_spread$2({}, additionalProps), {
name: name,
var configObj = _object_spread_props$1(_object_spread$2({
name: name
}, additionalProps), {
state_topic: genFlicPrefix(nodeId, objectId),
unique_id: "Flic_".concat(nodeId, "_").concat(objectId),
device: device
@@ -381,22 +415,23 @@ var convertStr2Uint32Array = function(s) {
};
var makeOptions = function(opt) {
return _object_spread$1({
debug: false
debug: false,
uniqueId: "0"
}, opt);
};
var makeIRController = function(ir, ha, mqtt, uniqueId) {
var options = arguments.length > 4 && arguments[4] !== void 0 ? arguments[4] : {};
var makeIRController = function(ir, ha, mqtt) {
var options = arguments.length > 3 && arguments[3] !== void 0 ? arguments[3] : {};
options = makeOptions(options);
var logger = makeLogger("ir", options.debug);
var haDevice = {
name: "IR",
manufacturer: "Flic",
model: "".concat(NODE_ID).concat(uniqueId),
model: "".concat(NODE_ID).concat(options.uniqueId),
identifiers: [
"FlicHubIR"
]
};
var nodeId = "".concat(NODE_ID).concat(uniqueId);
var nodeId = "".concat(NODE_ID).concat(options.uniqueId);
var RECORD_SIGNAL_SET = ha.genFlicPrefix(nodeId, "record/set");
var VALUE_SIGNAL_SET = ha.genFlicPrefix(nodeId, "signal/set");
var VALUE_SIGNAL_STATE = ha.genFlicPrefix(nodeId, "signal");
@@ -1126,7 +1161,7 @@ function _object_spread_props(target, source) {
}
return target;
}
var start = function(buttonModule, irModule, uniqueId, options) {
var start = function(buttonModule, irModule, options) {
var mqttServer = create(options.mqtt.host, _object_spread_props(_object_spread({}, options.mqtt), {
keep_alive: true
}));
@@ -1136,10 +1171,14 @@ var start = function(buttonModule, irModule, uniqueId, options) {
options.ha = (_options_ha = options.ha) !== null && _options_ha !== void 0 ? _options_ha : {};
var _options_flicBtns;
options.flicBtns = (_options_flicBtns = options.flicBtns) !== null && _options_flicBtns !== void 0 ? _options_flicBtns : {};
var _options_flicIR;
options.flicIR = (_options_flicIR = options.flicIR) !== null && _options_flicIR !== void 0 ? _options_flicIR : {};
var _options_ha_debug, _ref;
options.ha.debug = (_ref = (_options_ha_debug = options.ha.debug) !== null && _options_ha_debug !== void 0 ? _options_ha_debug : options.debug) !== null && _ref !== void 0 ? _ref : false;
var _options_flicBtns_debug, _ref1;
options.flicBtns.debug = (_ref1 = (_options_flicBtns_debug = options.flicBtns.debug) !== null && _options_flicBtns_debug !== void 0 ? _options_flicBtns_debug : options.debug) !== null && _ref1 !== void 0 ? _ref1 : false;
var _options_flicBtns_debug1, _ref2;
options.flicIR.debug = (_ref2 = (_options_flicBtns_debug1 = options.flicBtns.debug) !== null && _options_flicBtns_debug1 !== void 0 ? _options_flicBtns_debug1 : options.debug) !== null && _ref2 !== void 0 ? _ref2 : false;
var ha = makeHAmqtt(mqttServer, options.ha);
mqttServer.on("connected", function() {
var _options_flicBtns, _options_flicIR;
@@ -1148,7 +1187,7 @@ var start = function(buttonModule, irModule, uniqueId, options) {
makeButtonController(ha, buttonModule, options.flicBtns).start();
}
if (!((_options_flicIR = options.flicIR) === null || _options_flicIR === void 0 ? void 0 : _options_flicIR.disabled)) {
makeIRController(irModule, ha, mqttServer, uniqueId, options.flicIR).start();
makeIRController(irModule, ha, mqttServer, options.flicIR).start();
}
logger.info("all services up!");
});
+25 -9
View File
@@ -2,6 +2,9 @@ import { HAComponent, HADevice, HAmqtt } from "./HAmqtt";
import { makeLogger } from "./Logger";
import { Button, ButtonModule } from "./flicTypes";
const ms2ISO8601 = (ms: number): string =>
(new Date(ms)).toISOString().slice(0, 19).replace('T', ' ')
export type ButtonControllerOpt = {
debug: boolean;
}
@@ -10,11 +13,14 @@ export const makeOptions = (opt: Partial<ButtonControllerOpt>): ButtonController
...opt,
})
const ENTITIES: Record<string, [HAComponent, Record<string, any>]> = {
"action": ['sensor', { icon: 'mdi:gesture-tap-button' }],
"action": ['sensor', { icon: 'mdi:gesture-tap-button', name: "Click Action" }],
"state": ['sensor', { icon: 'mdi:radiobox-indeterminate-variant' }],
"battery": ['sensor', { unit_of_measurement: '%', device_class: 'battery' }],
"connected": ['binary_sensor', { device_class: 'connectivity' }],
"ready": ['binary_sensor', { device_class: 'running' }],
"batteryLastUpdate": ['sensor', { name: "Battery Last Update Time", device_class: "duration", unit_of_measurement: "s" }],
"connected": ['binary_sensor', { device_class: 'connectivity', name: "Connection Established" }],
"ready": ['binary_sensor', { device_class: 'connectivity', name: "Connection Verified" }],
"activeDisconnect": ['binary_sensor', { name: "User Active Disconnect" }],
"passive": ['binary_sensor', { name: "Passive Mode" }],
}
export type ButtonController = ReturnType<typeof makeButtonController>;
export function makeButtonController(
@@ -55,11 +61,6 @@ export function makeButtonController(
payload_not_available: 'OFF',
topic: ha.genFlicPrefix(genButtonUniqueId(button.bdaddr), 'ready')
},
{
payload_available: 'ON',
payload_not_available: 'OFF',
topic: ha.genFlicPrefix(genButtonUniqueId(button.bdaddr), 'connected')
}
],
availability_mode: 'all',
},
@@ -84,8 +85,11 @@ export function makeButtonController(
}
const publishButtonMeta = (button: Button) => {
ha.publishState(genButtonUniqueId(button.bdaddr), 'battery', button.batteryStatus);
ha.publishState(genButtonUniqueId(button.bdaddr), 'batteryLastUpdate', button.batteryTimestamp ? `${Math.round((Date.now() - button.batteryTimestamp) / 1000)}` : 'unknown');
ha.publishState(genButtonUniqueId(button.bdaddr), 'connected', button.connected ? 'ON' : "OFF");
ha.publishState(genButtonUniqueId(button.bdaddr), 'ready', button.ready ? 'ON' : "OFF");
ha.publishState(genButtonUniqueId(button.bdaddr), 'activeDisconnect', button.activeDisconnect ? 'ON' : "OFF");
ha.publishState(genButtonUniqueId(button.bdaddr), 'passive', button.activeDisconnect ? 'ON' : "OFF");
}
const addBtn = (eventName: string) => (obj: { bdaddr: string }) => {
const button = buttonModule.getButton(obj.bdaddr);
@@ -94,9 +98,15 @@ export function makeButtonController(
}
const start = () => {
logger.info("Starting...")
let resetActiontInv: null | any = null;
buttonModule.on('buttonAdded', addBtn('buttonAdded'));
buttonModule.on('buttonConnected', addBtn('buttonConnected'));
buttonModule.on('buttonReady', addBtn('buttonReady'));
buttonModule.on('buttonReady', (btn) => {
addBtn('buttonReady')(btn);
const button = buttonModule.getButton(btn.bdaddr);
publishButtonState(button, 'released')
publishButtonAction(button, 'none')
});
buttonModule.on('buttonUpdated', addBtn('buttonUpdated'));
buttonModule.on('buttonDeleted', (btn) => {
logger.debug('buttonDeleted', JSON.stringify(btn, null, 4))
@@ -117,12 +127,18 @@ export function makeButtonController(
publishButtonMeta(btn);
});
buttonModule.on('buttonSingleOrDoubleClickOrHold', obj => {
if (resetActiontInv !== null) {
clearTimeout(resetActiontInv);
}
const btn = buttonModule.getButton(obj.bdaddr);
publishButtonAction(
btn,
obj.isSingleClick ? "click" : obj.isDoubleClick ? "double_click" : "hold",
);
publishButtonMeta(btn);
resetActiontInv = setTimeout(() => {
publishButtonAction(btn, 'none');
}, 500)
});
logger.info("Registering all buttons...")
buttonModule.getButtons().forEach(registerButton);
+1 -1
View File
@@ -62,8 +62,8 @@ export function makeHAmqtt(
) => {
const configtopic = genHAPrefix(component, nodeId, objectId) + "/config"
const configObj = {
...additionalProps,
name,
...additionalProps,
state_topic: genFlicPrefix(nodeId, objectId),
unique_id: `Flic_${nodeId}_${objectId}`,
device,
+4 -3
View File
@@ -16,17 +16,18 @@ const convertStr2Uint32Array = (s: string): Uint32Array => {
return new Uint32Array(a.slice(0, a.length - 2).map(v => parseInt(v, 32)))
}
export type IRControllerOpt = {
uniqueId: string,
debug: boolean;
}
export const makeOptions = (opt: Partial<IRControllerOpt>): IRControllerOpt => ({
debug: false,
uniqueId: "0",
...opt,
})
export const makeIRController = (
ir: IRModule,
ha: HAmqtt,
mqtt: MQTT,
uniqueId: string,
options: Partial<IRControllerOpt> = {},
) => {
options = makeOptions(options);
@@ -34,10 +35,10 @@ export const makeIRController = (
const haDevice: HADevice = {
name: 'IR',
manufacturer: 'Flic',
model: `${NODE_ID}${uniqueId}`,
model: `${NODE_ID}${options.uniqueId}`,
identifiers: ['FlicHubIR']
}
const nodeId = `${NODE_ID}${uniqueId}`;
const nodeId = `${NODE_ID}${options.uniqueId}`;
const RECORD_SIGNAL_SET = ha.genFlicPrefix(nodeId, 'record/set');
const VALUE_SIGNAL_SET = ha.genFlicPrefix(nodeId, 'signal/set');
const VALUE_SIGNAL_STATE = ha.genFlicPrefix(nodeId, 'signal');
+1
View File
@@ -9,6 +9,7 @@ export type Button = {
connected: boolean // The connection to the button is currently established
ready: boolean // The connection is verified (see buttonReady)
batteryStatus: number | null // Battery level in percent (0-100), or null if unknown
batteryTimestamp: number | null // Last time the battery was updated
firmwareVersion: number | null // Firmware version of button, or null if unknown
flicVersion: number | null // Flic version (1 or 2)
uuid: string // A 32 characters long hex string, unique for every button
+2 -2
View File
@@ -23,7 +23,6 @@ export type Options = {
export const start = (
buttonModule: ButtonModule,
irModule: IRModule,
uniqueId: string,
options: Options,
) => {
const mqttServer = mqtt.create(
@@ -33,8 +32,10 @@ export const start = (
const logger = makeLogger('root', options.debug ?? false);
options.ha = options.ha ?? {}
options.flicBtns = options.flicBtns ?? {}
options.flicIR = options.flicIR ?? {}
options.ha.debug = options.ha.debug ?? options.debug ?? false
options.flicBtns.debug = options.flicBtns.debug ?? options.debug ?? false
options.flicIR.debug = options.flicBtns.debug ?? options.debug ?? false
const ha = makeHAmqtt(mqttServer, options.ha);
mqttServer.on('connected', () => {
logger.info("connected to mqtt")
@@ -48,7 +49,6 @@ export const start = (
irModule,
ha,
mqttServer,
uniqueId,
options.flicIR,
).start();
}