@uncaught/gpio-shutter-bridge 1.0.0

package/README.md

@@ -0,0 +1,115 @@
+# MQTT shutter bridge for home assistant or alike
+
+This is an implementation of a bridge between shutter controls and home assistant.
+
+In particular I have connected one Velux KLF 150 gateway and one Schellenberg shutter remote to my Raspberry Pi using the GPIO pins.
+
+But you can use this for Velux only, of course. You will need 3 GPIO pins for each Velux shutter and you can use up to 5 shutters with the KLF 150 in this setup.
+
+**No soldering** required if you stick with Velux only - everything is just screws.
+
+## Features
+
+- Supports Velux KLF 150 or any 3-button remote control
+- MQTT interface with auto-discovery for home assistant
+- Positioning of the Velux shutters (time-based)
+
+## Flow chart
+
+```mermaid
+flowchart LR
+    HA[Home Assistant/MQTT] <--> Bridge[THIS LIBRARY]
+    Bridge <--> GPIO[Raspberry Pi GPIOs]
+    GPIO --> Relays[Relay Modules]
+    Relays --> KLF[Velux KLF 150]
+    Relays --> Remote[Schellenberg Remote]
+    KLF <--> Velux[Velux Shutters]
+    KLF --> GPIO
+    Remote --> Balcony[Balcony Shutter]
+
+    style Bridge fill:#ff9900,stroke:#333,stroke-width:2px,color:#fff
+```
+
+# Hardware
+
+## Before unboxing
+
+This is how everything looks before "unboxing" it into a more permanent shape:
+
+![finished cabling](docs/cable-sallad.png)
+
+## My hardware
+
+Just to give you an insight, you can pobably use this project with any other hardware. It could make sense to buy a complete ESP32 GPIO board instead of using a Raspberry Pi.
+
+- 1 Schellenberg shutter motor in my balcony door
+- 1 Schellenberg remote control
+  - Which I opened up and soldered contacts to all three buttons (up/stop/down) as well as the power supply.
+  - This way I can supply power directly via the 3V GPIO output of the raspberry pi without needing batteries.
+  - I'm trusting you with this [definitely professional piece of art](docs/schellenberg.png).
+- 3 Velux covers/shutters on my roof windows
+- Velux KLF 150 gateway
+  - See https://www.velux.com/klf150
+  - Before buying this, I also tried soldering contacts to the Velux remotes (model 3UR B01 WW), but I broke the first...
+- 9 relay modules
+  - If you use a Raspberry PI, you need relays that work with 3V and it helps if they already have a pull-up resistor because the GPIO pins can have a floating voltage when the PI boots and they are not yet assigned as outputs, triggering the relay when it shouldn't.
+  - I bought [this 10 pack on amazon](https://www.amazon.de/dp/B0F53QDMXG) 
+  - You will need 2 relays per Velux shutter, so for my three windows I needed 6 relays.
+  - Additionally I needed 3 relays for my Schellenberg remote control.
+  - If you find a board with multiple 3V relays on it, go ahead. I just screwed mine together on a wooden board.
+- Raspberry Pi Model B
+  - Yes, the first version of the Raspberry Pi with the single armv6 CPU!
+  - Still had this lying around, so why waste it.
+  - I got node 21 running on it for this project.
+- One USB power supply for the Raspberry Pi
+  - I used one of my many 2A supplies, not the 1.4A one that comes with the Velux KLF 150.
+  - The Pi then powers the relays, the KLF 150 and the Schellenberg remote.
+
+## Wiring GPIOs to the relays
+
+![Relay boards](docs/relay-boards.png)
+
+- Connect all **VCC** pins of the relays to a 3V GPIO pin of the Raspberry Pi.
+  - I have daisy chained them together. Only the most left relay is connected to the Pi.
+- Connect all **GND** pins of the relays to a GND pin of the Raspberry Pi.
+  - Again daisy chained.
+- Connect each **IN** pin of the relays to one GPIO pin of the Raspberry Pi.
+  - If you use all 10 relays, for all 5 shutters, I'm [suggesting](./example.ts) pins [2, 3, 4, 17, 27, 22, 10, 9, 11, 8](https://pinout.xyz/).
+
+## Wiring the Velux KLF 150 to the rest
+
+![Velux KLF 150 sockets](docs/velux-klf150-sockets.png)
+
+This is for the default configuration as described in the Velux KLF 150 manual. Meaning: You have 2 output pins and 4 input pins per shutter (A, B, C, D, E). For each shutter, the first input pin makes the shutter open, the second input pin makes it close, and both together make the shutter stop. The output pins for each shutter should close on success (also the default behavior).
+
+### Outputs
+
+- Connect all 5 bottom pins of the output (A-E) together and to GND.
+- Connect all 5 top pins of the output (A-E) to any GPIO pin.
+  - I'm [suggesting](./example.ts) pins [14, 15, 18, 23, 24](https://pinout.xyz/).
+
+### Inputs
+
+- The bottom line of all input pins are for GND. However, since the cabling comes in pairs anyway and you need to connect them each to one of the relays, I just used all the existing cables.
+- So connect all 10 inputs to the 10 relays, the top one to **NO** (normally open) and the bottom one to **COM** (common). 
+
+# Software
+
+- Create a javascript file, require my library and call it with your shutter-pin-layout:
+
+```js
+import {createVeluxShutters, initRuntime, initMqtt} from '@uncaught/gpio-shutter-bridge';
+
+const {onDispose} = initRuntime();
+
+onDispose(initMqtt(createVeluxShutters([
+  {ident: 'Velux_A', up: 2, down: 3, input: 14},
+  {ident: 'Velux_B', up: 4, down: 17, input: 15},
+  {ident: 'Velux_C', up: 27, down: 22, input: 18},
+  {ident: 'Velux_D', up: 10, down: 9, input: 23},
+  {ident: 'Velux_E', up: 11, down: 8, input: 24}, //same row!
+], onDispose), {url: 'mqtt://your-mqtt-or-home-assistant'}));
+```
+
+- The ident should match `/[a-zA-Z][a-zA-Z0-9_-]*/`.
+- See [my personal example](./example.ts) for a few more details.

package/dist/example.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/example.js

@@ -0,0 +1,33 @@
+import { createVeluxShutters, initRuntime, initMqtt, createThreeButtonShutter } from './src/index.js';
+/**
+ * This is an example for connecting to a Velux KLF150 with up to 5 shutters.
+ * The up/down pins are all aligned on the left GPIO column and the inputs are on the right, except for shutter e.
+ */
+const veluxKlf150 = [
+    { ident: 'Velux_A', up: 2, down: 3, input: 14 },
+    { ident: 'Velux_B', up: 4, down: 17, input: 15 },
+    { ident: 'Velux_C', up: 27, down: 22, input: 18 },
+    { ident: 'Velux_D', up: 10, down: 9, input: 23 },
+    { ident: 'Velux_E', up: 11, down: 8, input: 24 }, //same row!
+];
+/**
+ * When using exactly 3 shutters, using the CDE socket with the 6x2 plug makes more sense:
+ */
+const veluxKlf150CDE = [
+    { ...veluxKlf150[0], ident: 'Velux_C' },
+    { ...veluxKlf150[1], ident: 'Velux_D' },
+    { ...veluxKlf150[2], ident: 'Velux_E' },
+];
+/**
+ * This runtime implementation is also just an example - you can use your own implementation if you want.
+ */
+const { onDispose } = initRuntime();
+/**
+ * For my personal use, I have 3 shutters tied to the Velux KLF150 and another shutter controlled with
+ * a 3-button remote, which I hacked and connected to the GPIO-pins 10/9/11:
+ */
+const shutters = [
+    ...createVeluxShutters(veluxKlf150CDE, onDispose),
+    createThreeButtonShutter('Balkon', 10, 9, 11, onDispose),
+];
+onDispose(initMqtt(shutters, { url: 'mqtts://mosquitto.local.correnz.net', rejectUnauthorized: false }));

package/dist/src/Gpio.d.ts

@@ -0,0 +1,5 @@
+import { Gpio } from 'onoff';
+import type { OnDispose } from './runtime.js';
+export declare function press(...outputs: readonly Gpio[]): Promise<void>;
+export declare function mkOutput(pin: number, onDispose: OnDispose): Gpio;
+export declare function mkInput(pin: number, onDispose: OnDispose): Gpio;

package/dist/src/Gpio.js

@@ -0,0 +1,32 @@
+import { Gpio } from 'onoff';
+import { execSync } from 'child_process';
+async function sleep(wait) {
+    await new Promise(resolve => setTimeout(resolve, wait));
+}
+export async function press(...outputs) {
+    outputs.forEach(output => output.writeSync(1));
+    await sleep(200);
+    outputs.forEach(output => output.writeSync(0));
+}
+export function mkOutput(pin, onDispose) {
+    const gpio = new Gpio(pin, 'out');
+    onDispose(() => {
+        gpio.writeSync(0);
+        gpio.unexport();
+    });
+    return gpio;
+}
+export function mkInput(pin, onDispose) {
+    //Setting to pull-up - the `onoff`-library doesn't do that.
+    // I'm doing this because the inputs were floating high without any pull, so I just stick with it.
+    // We assume the input pin is closed to ground, causing it to change to low.
+    execSync(`raspi-gpio set ${pin} pu`);
+    const gpio = new Gpio(pin, 'in', 'both');
+    onDispose(() => gpio.unexport());
+    //Double check that the input is high:
+    const value = gpio.readSync();
+    if (value !== Gpio.HIGH) {
+        console.error(`Expected GPIO ${pin} to be high, but it was ${value}`);
+    }
+    return gpio;
+}

package/dist/src/Shutter/Shutter.d.ts

@@ -0,0 +1,25 @@
+export declare const shutterPositions: readonly ["open", "closed", "in-between", "unknown"];
+export type ShutterPosition = typeof shutterPositions[number];
+export declare const shutterActions: readonly ["opening", "closing", "stopping"];
+export type ShutterAction = typeof shutterActions[number];
+export declare const shutterStates: readonly ["open", "closed", "in-between", "unknown", "opening", "closing", "stopping"];
+export type ShutterState = typeof shutterStates[number];
+export declare function isShutterPosition(state: unknown): state is ShutterPosition;
+export declare function isShutterAction(state: unknown): state is ShutterAction;
+export interface ShutterInterface {
+    ident: string;
+    open(): void;
+    stop(): void;
+    close(): void;
+}
+export interface ShutterInterfaceWithState extends ShutterInterface {
+    getState(): ShutterState;
+    onStateChange(cb: (state: ShutterState) => void): () => void;
+}
+export interface ShutterInterfaceWithPosition extends ShutterInterface {
+    getPosition(): number;
+    setPosition(position: number): void;
+    onPositionChange(cb: (position: number) => void): () => void;
+}
+export declare function isShutterWithState(shutter: ShutterInterface): shutter is ShutterInterfaceWithState;
+export declare function isShutterWithPosition(shutter: ShutterInterface): shutter is ShutterInterfaceWithPosition;

package/dist/src/Shutter/Shutter.js

@@ -0,0 +1,15 @@
+export const shutterPositions = ['open', 'closed', 'in-between', 'unknown'];
+export const shutterActions = ['opening', 'closing', 'stopping'];
+export const shutterStates = [...shutterPositions, ...shutterActions];
+export function isShutterPosition(state) {
+    return !!state && shutterPositions.includes(state);
+}
+export function isShutterAction(state) {
+    return !!state && shutterActions.includes(state);
+}
+export function isShutterWithState(shutter) {
+    return 'getState' in shutter && 'onStateChange' in shutter;
+}
+export function isShutterWithPosition(shutter) {
+    return 'getPosition' in shutter && 'setPosition' in shutter && 'onPositionChange' in shutter;
+}

package/dist/src/Shutter/ThreeButtonShutter.d.ts

@@ -0,0 +1,14 @@
+import { Gpio } from 'onoff';
+import { ShutterInterface } from './Shutter.js';
+import type { OnDispose } from '../runtime.js';
+export declare class ThreeButtonShutter implements ShutterInterface {
+    readonly ident: string;
+    private readonly openButton;
+    private readonly stopButton;
+    private readonly closeButton;
+    constructor(ident: string, openButton: Gpio, stopButton: Gpio, closeButton: Gpio);
+    open(): void;
+    stop(): void;
+    close(): void;
+}
+export declare function createThreeButtonShutter(ident: string, up: number, stop: number, down: number, onDispose: OnDispose): ThreeButtonShutter;

package/dist/src/Shutter/ThreeButtonShutter.js

@@ -0,0 +1,25 @@
+import { press, mkOutput } from '../Gpio.js';
+export class ThreeButtonShutter {
+    ident;
+    openButton;
+    stopButton;
+    closeButton;
+    constructor(ident, openButton, stopButton, closeButton) {
+        this.ident = ident;
+        this.openButton = openButton;
+        this.stopButton = stopButton;
+        this.closeButton = closeButton;
+    }
+    open() {
+        press(this.openButton);
+    }
+    stop() {
+        press(this.stopButton);
+    }
+    close() {
+        press(this.closeButton);
+    }
+}
+export function createThreeButtonShutter(ident, up, stop, down, onDispose) {
+    return new ThreeButtonShutter(ident, mkOutput(up, onDispose), mkOutput(stop, onDispose), mkOutput(down, onDispose));
+}

package/dist/src/Shutter/VeluxShutter.d.ts

@@ -0,0 +1,46 @@
+import { Gpio } from 'onoff';
+import { ShutterState, ShutterInterfaceWithState, ShutterInterfaceWithPosition, ShutterPosition } from './Shutter.js';
+export interface Persistence {
+    lastFullCloseDurations?: number[];
+    lastFullOpenDurations?: number[];
+    position?: number;
+    state?: ShutterPosition;
+}
+interface Store {
+    get: () => Persistence;
+    set: (value: Partial<Persistence>) => void;
+}
+export declare class VeluxShutter implements ShutterInterfaceWithState, ShutterInterfaceWithPosition {
+    readonly ident: string;
+    private readonly up;
+    private readonly down;
+    private readonly input;
+    private readonly store;
+    private lastActionStartTime;
+    private prevPositionState;
+    private positioningTimeout;
+    private position;
+    private positionListeners;
+    private prevState;
+    private preStopState;
+    private state;
+    private stateListeners;
+    constructor(ident: string, up: Gpio, down: Gpio, input: Gpio, store: Store);
+    private notifyStateChange;
+    private notifyPositionChange;
+    private storeDuration;
+    private getAverageDuration;
+    private getPositionDelta;
+    private setState;
+    private clearPositioningTimeout;
+    open(): void;
+    stop(): void;
+    close(): void;
+    setPosition(position: number): void;
+    getPosition(): number;
+    getState(): "open" | "closed" | "in-between" | "unknown" | "opening" | "closing" | "stopping";
+    onPositionChange(cb: (position: number) => void): () => void;
+    onStateChange(cb: (state: ShutterState) => void): () => void;
+    destroy(): void;
+}
+export {};

package/dist/src/Shutter/VeluxShutter.js

@@ -0,0 +1,210 @@
+import { Gpio } from 'onoff';
+import { isShutterPosition, isShutterAction, } from './Shutter.js';
+import { press } from '../Gpio.js';
+const lastDurationsToKeep = 10;
+function minMaxPercentage(num) {
+    return Math.min(Math.max(num, 0), 100);
+}
+export class VeluxShutter {
+    ident;
+    up;
+    down;
+    input;
+    store;
+    lastActionStartTime = 0;
+    prevPositionState = 'unknown';
+    positioningTimeout = null;
+    position = 42; //unknown initially
+    positionListeners = new Set();
+    prevState = 'unknown';
+    preStopState = 'unknown';
+    state = 'unknown';
+    stateListeners = new Set();
+    constructor(ident, up, down, input, store) {
+        this.ident = ident;
+        this.up = up;
+        this.down = down;
+        this.input = input;
+        this.store = store;
+        const persistence = this.store.get();
+        if (typeof persistence.position === 'number' && (persistence.position <= 100 && persistence.position >= 0)) {
+            this.position = +persistence.position; //"+" makes sure we have integers only
+        }
+        if (persistence.state && isShutterPosition(persistence.state)) {
+            this.state = persistence.state;
+            this.prevPositionState = this.state;
+        }
+        this.input.watch((err, value) => {
+            if (err) {
+                console.error('Error watching input', err);
+            }
+            else if (value === Gpio.LOW) {
+                if (this.state === 'opening') {
+                    this.setState('open');
+                }
+                else if (this.state === 'closing') {
+                    this.setState('closed');
+                }
+                else if (this.state === 'stopping') {
+                    this.setState('in-between');
+                }
+            }
+        });
+    }
+    notifyStateChange() {
+        this.stateListeners.forEach(listener => {
+            try {
+                listener(this.state);
+            }
+            catch (err) {
+                console.error('Error in state listener', err);
+            }
+        });
+    }
+    notifyPositionChange() {
+        this.positionListeners.forEach(listener => {
+            try {
+                listener(this.position);
+            }
+            catch (err) {
+                console.error('Error in position listener', err);
+            }
+        });
+    }
+    storeDuration(key, duration) {
+        if (duration > 0) {
+            let array = this.store.get()[key] ?? [];
+            array.unshift(duration);
+            array = array.slice(0, lastDurationsToKeep);
+            this.store.set({ [key]: array });
+        }
+    }
+    getAverageDuration(action) {
+        let lastDurations = [];
+        if (action === 'opening') {
+            lastDurations = this.store.get().lastFullOpenDurations ?? [];
+        }
+        if (action === 'closing') {
+            lastDurations = this.store.get().lastFullCloseDurations ?? [];
+        }
+        if (lastDurations.length) {
+            const sum = lastDurations.reduce((a, b) => a + b, 0);
+            return sum / lastDurations.length;
+        }
+        return 0;
+    }
+    getPositionDelta(prevState, duration) {
+        if (isShutterAction(prevState) && duration > 0) {
+            const avg = this.getAverageDuration(prevState);
+            if (avg > 0) {
+                return minMaxPercentage(Math.round(duration / avg * 100));
+            }
+        }
+        return 0;
+    }
+    setState(state) {
+        this.prevState = this.state;
+        this.state = state;
+        this.notifyStateChange();
+        if (state === 'stopping') {
+            this.preStopState = this.prevState;
+        }
+        if (state === 'opening' || state === 'closing') {
+            this.lastActionStartTime = Date.now();
+            //If we apply another action while already running one, we can no longer determine the full duration:
+            if (isShutterAction(this.prevState)) {
+                this.lastActionStartTime = 0;
+            }
+        }
+        if (isShutterPosition(state)) {
+            const duration = this.lastActionStartTime ? (Date.now() - this.lastActionStartTime) : 0;
+            if (state === 'closed') {
+                this.position = 0;
+            }
+            else if (state === 'open') {
+                this.position = 100;
+            }
+            else if (state === 'in-between') {
+                const prevPosition = this.position;
+                const delta = this.getPositionDelta(this.preStopState, duration);
+                if (this.preStopState === 'opening') {
+                    this.position = minMaxPercentage(this.position + delta);
+                }
+                else if (this.preStopState === 'closing') {
+                    this.position = minMaxPercentage(this.position - delta);
+                }
+            }
+            this.notifyPositionChange();
+            this.store.set({ state, position: this.position });
+            let prevPositionState = this.prevPositionState;
+            this.prevPositionState = state;
+            if (prevPositionState === 'open' && state === 'closed') {
+                this.storeDuration('lastFullCloseDurations', duration);
+            }
+            if (prevPositionState === 'closed' && state === 'open') {
+                this.storeDuration('lastFullOpenDurations', duration);
+            }
+        }
+    }
+    clearPositioningTimeout() {
+        if (this.positioningTimeout) {
+            clearTimeout(this.positioningTimeout);
+            this.positioningTimeout = null;
+        }
+    }
+    open() {
+        this.clearPositioningTimeout();
+        this.setState('opening');
+        press(this.up);
+    }
+    stop() {
+        this.clearPositioningTimeout();
+        this.setState('stopping');
+        press(this.up, this.down);
+    }
+    close() {
+        this.clearPositioningTimeout();
+        this.setState('closing');
+        press(this.down);
+    }
+    setPosition(position) {
+        this.clearPositioningTimeout();
+        if (position === 0) {
+            this.close();
+        }
+        else if (position === 100) {
+            this.open();
+        }
+        else if (position > 0 && position < 100) {
+            let timeout = 0;
+            if (position > this.position) {
+                timeout = this.getAverageDuration('opening') * (position - this.position) / 100;
+                this.open();
+            }
+            else {
+                timeout = this.getAverageDuration('closing') * (this.position - position) / 100;
+                this.close();
+            }
+            if (timeout) {
+                this.positioningTimeout = setTimeout(() => this.stop(), timeout);
+            }
+        }
+    }
+    getPosition() {
+        return this.position;
+    }
+    getState() {
+        return this.state;
+    }
+    onPositionChange(cb) {
+        this.positionListeners.add(cb);
+        return () => this.positionListeners.delete(cb);
+    }
+    onStateChange(cb) {
+        this.stateListeners.add(cb);
+        return () => this.stateListeners.delete(cb);
+    }
+    destroy() {
+        this.clearPositioningTimeout();
+    }
+}

package/dist/src/Shutter/VeluxShutterFactory.d.ts

@@ -0,0 +1,9 @@
+import type { OnDispose } from '../runtime.js';
+import { VeluxShutter } from './VeluxShutter.js';
+export interface VeluxConfig {
+    ident: string;
+    up: number;
+    down: number;
+    input: number;
+}
+export declare function createVeluxShutters(shutters: readonly VeluxConfig[], onDispose: OnDispose): readonly VeluxShutter[];

package/dist/src/Shutter/VeluxShutterFactory.js

@@ -0,0 +1,37 @@
+import { readFileSync } from 'fs';
+import { existsSync, writeFile } from 'node:fs';
+import { VeluxShutter } from './VeluxShutter.js';
+import { mkInput, mkOutput } from '../Gpio.js';
+import debounce from 'lodash.debounce';
+export function createVeluxShutters(shutters, onDispose) {
+    const persistenceFile = '/tmp/velux-shutter-state.json';
+    let storage = {};
+    if (existsSync(persistenceFile)) {
+        const file = readFileSync(persistenceFile).toString();
+        try {
+            storage = JSON.parse(file);
+        }
+        catch (e) {
+            console.error('Error parsing persistence file', e);
+        }
+    }
+    const save = debounce(() => {
+        writeFile(persistenceFile, JSON.stringify(storage), (err) => {
+            if (err) {
+                console.error('Error writing persistence file', err);
+            }
+        });
+    }, 200);
+    return shutters.map((cfg) => {
+        const { ident, up, down, input } = cfg;
+        const shutter = new VeluxShutter(ident, mkOutput(up, onDispose), mkOutput(down, onDispose), mkInput(input, onDispose), {
+            get: () => storage[ident] ?? {},
+            set: (obj) => {
+                storage[ident] = { ...storage[ident], ...obj };
+                save();
+            },
+        });
+        onDispose(() => shutter.destroy());
+        return shutter;
+    });
+}

package/dist/src/index.d.ts

@@ -0,0 +1,5 @@
+export { createVeluxShutters, type VeluxConfig } from './Shutter/VeluxShutterFactory.js';
+export { initRuntime, type OnDispose } from './runtime.js';
+export { initMqtt } from './mqtt/mqtt.js';
+export { createThreeButtonShutter } from './Shutter/ThreeButtonShutter.js';
+export * from './Shutter/Shutter.js';

package/dist/src/index.js

@@ -0,0 +1,5 @@
+export { createVeluxShutters } from './Shutter/VeluxShutterFactory.js';
+export { initRuntime } from './runtime.js';
+export { initMqtt } from './mqtt/mqtt.js';
+export { createThreeButtonShutter } from './Shutter/ThreeButtonShutter.js';
+export * from './Shutter/Shutter.js';

package/dist/src/mqtt/interfaces.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Device information for MQTT discovery
+ */
+export interface MqttDevice {
+    /** List of identifiers for the device */
+    identifiers: string | string[];
+    /** Name of the device */
+    name?: string;
+    /** Manufacturer of the device */
+    manufacturer?: string;
+    /** Model of the device */
+    model?: string;
+    /** Serial number of the device */
+    serial_number?: string;
+    /** Software version of the device */
+    sw_version?: string;
+    /** Hardware version of the device */
+    hw_version?: string;
+    /** Configuration URL for the device */
+    configuration_url?: string;
+    /** Connections of the device (e.g., [["mac", "02:5b:26:a8:dc:12"]]) */
+    connections?: [string, string][];
+    /** Suggested area for the device */
+    suggested_area?: string;
+    /** URL to a webpage that can manage the device */
+    via_device?: string;
+}
+/**
+ * Origin information for MQTT discovery
+ */
+export interface MqttOrigin {
+    /** Name of the origin */
+    name: string;
+    /** Software version */
+    sw_version?: string;
+    /** Support URL */
+    support_url?: string;
+}
+/**
+ * Availability configuration for MQTT entities
+ */
+export interface MqttAvailability {
+    /** MQTT topic subscribed to receive availability (online/offline) updates */
+    topic: string;
+    /** Payload that represents the available state */
+    payload_available?: string;
+    /** Payload that represents the unavailable state */
+    payload_not_available?: string;
+    /** Template to extract value from availability topic */
+    value_template?: string;
+}
+/**
+ * MQTT Cover component configuration for auto-discovery
+ * @see https://www.home-assistant.io/integrations/cover.mqtt/
+ */
+export interface MqttCoverConfig {
+    platform: 'cover';
+    /** Name of the cover entity */
+    name?: string;
+    /** Unique ID for the entity (required for discovery) */
+    unique_id: string;
+    /** Device information */
+    device?: MqttDevice;
+    /** Origin information */
+    origin?: MqttOrigin;
+    /** Single availability topic or array of availability configurations */
+    availability?: MqttAvailability | MqttAvailability[];
+    /** MQTT topic subscribed to receive availability (online/offline) updates */
+    availability_topic?: string;
+    /** Payload that represents the available state */
+    payload_available?: string;
+    /** Payload that represents the unavailable state */
+    payload_not_available?: string;
+    /** Availability mode (all, any, latest) */
+    availability_mode?: 'all' | 'any' | 'latest';
+    /** Template to extract value from availability topic */
+    availability_template?: string;
+    /** MQTT topic to publish commands (open/close/stop) */
+    command_topic: string;
+    /** MQTT topic to set the position */
+    set_position_topic?: string;
+    /** MQTT topic to set the tilt */
+    tilt_command_topic?: string;
+    /** MQTT topic subscribed to receive state updates */
+    state_topic?: string;
+    /** MQTT topic for position updates */
+    position_topic?: string;
+    /** MQTT topic for tilt updates */
+    tilt_status_topic?: string;
+    /** Payload to open the cover */
+    payload_open?: string;
+    /** Payload to close the cover */
+    payload_close?: string;
+    /** Payload to stop the cover */
+    payload_stop?: string;
+    /** State value for open state */
+    state_open?: string;
+    /** State value for closed state */
+    state_closed?: string;
+    /** State value for opening state */
+    state_opening?: string;
+    /** State value for closing state */
+    state_closing?: string;
+    /** State value for stopped state */
+    state_stopped?: string;
+    /** Minimum position value (default: 0) */
+    position_closed?: number;
+    /** Maximum position value (default: 100) */
+    position_open?: number;
+    /** Minimum tilt value (default: 0) */
+    tilt_min?: number;
+    /** Maximum tilt value (default: 100) */
+    tilt_max?: number;
+    /** Payload to open the tilt */
+    tilt_opened_value?: number;
+    /** Payload to close the tilt */
+    tilt_closed_value?: number;
+    /** Inverts the tilt values */
+    tilt_invert_state?: boolean;
+    /** Template to extract position from position_topic */
+    position_template?: string;
+    /** Template to extract state from state_topic */
+    value_template?: string;
+    /** Template to extract tilt from tilt_status_topic */
+    tilt_status_template?: string;
+    /** Type of cover (awning, blind, curtain, damper, door, garage, gate, shade, shutter, window) */
+    device_class?: 'awning' | 'blind' | 'curtain' | 'damper' | 'door' | 'garage' | 'gate' | 'shade' | 'shutter' | 'window';
+    /** Flag that defines if cover works in optimistic mode (default: true if no state_topic) */
+    optimistic?: boolean;
+    /** QoS level for commands */
+    qos?: 0 | 1 | 2;
+    /** If the published message should have the retain flag set */
+    retain?: boolean;
+    /** Defines the encoding of the payloads received and published messages */
+    encoding?: string;
+    /** Icon for the entity */
+    icon?: string;
+    /** Category of the entity */
+    entity_category?: 'config' | 'diagnostic';
+    /** Flag which defines if the entity should be enabled when first added */
+    enabled_by_default?: boolean;
+    /** Object ID for entity registry */
+    object_id?: string;
+}
+/**
+ * Complete MQTT Device Auto-Discovery Payload
+ * Used for homeassistant/device/<device_id>/config topic
+ */
+export interface MqttDeviceDiscoveryPayload {
+    /** Device information */
+    device: MqttDevice;
+    /** Origin information */
+    origin?: MqttOrigin;
+    /** Availability topic for the device */
+    availability_topic?: string;
+    /** Payload that represents the available state */
+    payload_available?: string;
+    /** Payload that represents the unavailable state */
+    payload_not_available?: string;
+    /** Components (entities) associated with this device */
+    components: Record<string, MqttCoverConfig>;
+}

package/dist/src/mqtt/interfaces.js

@@ -0,0 +1,2 @@
+// Generated with the help of AI based on https://www.home-assistant.io/integrations/mqtt/
+export {};

package/dist/src/mqtt/mqtt.d.ts

@@ -0,0 +1,5 @@
+import { type IClientOptions } from 'mqtt';
+import { ShutterInterface } from '../Shutter/Shutter.js';
+export declare function initMqtt(shutters: readonly ShutterInterface[], { url, ...mqttOpts }: {
+    url: string;
+} & IClientOptions, namespace?: string): () => Promise<void>;

package/dist/src/mqtt/mqtt.js

@@ -0,0 +1,134 @@
+import mqtt from 'mqtt';
+import { isShutterWithState, isShutterWithPosition } from '../Shutter/Shutter.js';
+// @see https://www.home-assistant.io/integrations/mqtt
+// @see https://www.home-assistant.io/integrations/cover.mqtt/
+// @see https://www.home-assistant.io/integrations/cover/
+const ns0 = 'uncaught-gpio-shutter-bridge';
+function validateNamespacePart(str) {
+    if (!/[a-zA-Z][a-zA-Z0-9_-]*/.test(str)) {
+        throw new Error(`Invalid string for namespace: ${str}`);
+    }
+}
+export function initMqtt(shutters, { url, ...mqttOpts }, namespace = 'shutter') {
+    const shuttersById = new Map(shutters.map((s) => [s.ident, s]));
+    validateNamespacePart(namespace);
+    const ns1 = namespace;
+    const fullNs = `${ns0}/${ns1}`;
+    const deviceId = `${ns0}-${ns1}`;
+    const deviceAvailabilityTopic = `${fullNs}/-/availability`;
+    const client = mqtt.connect(url, { ...mqttOpts, clientId: fullNs });
+    const publish = (topic, message, opts) => {
+        console.log('MQTT publish', topic, message, opts);
+        client.publish(topic, message, opts);
+    };
+    client.on('error', (err) => {
+        console.error(err);
+    });
+    client.on('message', (topic, payloadBuffer) => {
+        const parts = topic.split('/');
+        const payload = payloadBuffer.toString();
+        console.log('MQTT message', topic, payload);
+        if (parts[0] === ns0 && parts[1] === ns1) {
+            const ident = parts[2];
+            const shutter = shuttersById.get(ident ?? '');
+            if (!shutter) {
+                return;
+            }
+            const subTopic = parts[3];
+            if (subTopic === 'set') {
+                if (payload === 'open') {
+                    shutter.open();
+                }
+                else if (payload === 'close') {
+                    shutter.close();
+                }
+                else if (payload === 'stop') {
+                    shutter.stop();
+                }
+            }
+            else if (subTopic === 'set-position' && isShutterWithPosition(shutter)) {
+                shutter.setPosition(parseInt(payload));
+            }
+        }
+    });
+    client.on('connect', () => {
+        console.log('MQTT connected');
+        client.subscribe(`${fullNs}/+/set`);
+        client.subscribe(`${fullNs}/+/set-position`);
+        const autoDiscoveryPayload = {
+            availability_topic: deviceAvailabilityTopic,
+            components: {},
+            device: {
+                identifiers: deviceId,
+                name: 'GPIO Shutter Bridge',
+                manufacturer: 'uncaught',
+                model: 'GPIO Shutter',
+            },
+            origin: {
+                name: ns0,
+                sw_version: '1.0.0',
+                support_url: 'https://github.com/uncaught/gpio-shutter-bridge',
+            },
+            payload_available: 'online',
+            payload_not_available: 'offline',
+        };
+        for (const shutter of shutters) {
+            validateNamespacePart(shutter.ident);
+            const shutterNs = `${fullNs}/${shutter.ident}`;
+            //Auto-discovery:
+            const objectId = `${deviceId}-${shutter.ident}`;
+            const autoDiscoveryComponent = {
+                command_topic: `${shutterNs}/set`,
+                device_class: 'shutter', //see https://www.home-assistant.io/integrations/cover/#device-class
+                name: `Shutter ${shutter.ident.replaceAll(/_/g, ' ')}`,
+                optimistic: true,
+                payload_close: 'close',
+                payload_open: 'open',
+                payload_stop: 'stop',
+                platform: 'cover',
+                unique_id: objectId,
+            };
+            autoDiscoveryPayload.components[objectId] = autoDiscoveryComponent;
+            if (isShutterWithState(shutter)) {
+                const publishState = (state) => {
+                    if (state !== 'stopping' && state !== 'unknown') {
+                        publish(`${shutterNs}/state`, {
+                            'closed': 'closed',
+                            'closing': 'closing',
+                            'in-between': 'stopped',
+                            'open': 'open',
+                            'opening': 'opening',
+                        }[state], { retain: true });
+                    }
+                };
+                publishState(shutter.getState());
+                shutter.onStateChange(publishState);
+                autoDiscoveryComponent.optimistic = false;
+                autoDiscoveryComponent.state_closed = 'closed';
+                autoDiscoveryComponent.state_closing = 'closing';
+                autoDiscoveryComponent.state_open = 'open';
+                autoDiscoveryComponent.state_opening = 'opening';
+                autoDiscoveryComponent.state_stopped = 'stopped';
+                autoDiscoveryComponent.state_topic = `${shutterNs}/state`;
+            }
+            if (isShutterWithPosition(shutter)) {
+                const publishPosition = (position) => {
+                    publish(`${shutterNs}/position`, position.toString(), { retain: true });
+                };
+                publishPosition(shutter.getPosition());
+                shutter.onPositionChange(publishPosition);
+                autoDiscoveryComponent.optimistic = false;
+                autoDiscoveryComponent.position_open = 100;
+                autoDiscoveryComponent.position_closed = 0;
+                autoDiscoveryComponent.position_topic = `${shutterNs}/position`;
+                autoDiscoveryComponent.set_position_topic = `${shutterNs}/set-position`;
+            }
+        }
+        publish(`homeassistant/device/${deviceId}/config`, JSON.stringify(autoDiscoveryPayload), { retain: true });
+        publish(deviceAvailabilityTopic, 'online', { retain: true });
+    });
+    return async () => {
+        publish(deviceAvailabilityTopic, 'offline', { retain: true });
+        await client.endAsync();
+    };
+}

package/dist/src/runtime.d.ts

@@ -0,0 +1,5 @@
+export type OnDispose = (disposable: () => void | Promise<void>) => () => void;
+export declare function initRuntime(): {
+    exit: (err?: Error | unknown) => Promise<void>;
+    onDispose: OnDispose;
+};

package/dist/src/runtime.js

@@ -0,0 +1,29 @@
+export function initRuntime() {
+    const disposables = new Set();
+    const onDispose = (cb) => {
+        disposables.add(cb);
+        return () => disposables.delete(cb);
+    };
+    async function exit(err) {
+        for (const disposable of disposables) {
+            try {
+                await disposable();
+            }
+            catch (e) {
+                console.error('Error in disposable', e);
+            }
+        }
+        if (err) {
+            console.error(err);
+            process.exit(1);
+        }
+        else {
+            process.exit(0);
+        }
+    }
+    process.on('SIGINT', () => exit());
+    process.on('SIGTERM', () => exit());
+    process.on('uncaughtException', (err) => exit(err));
+    process.on('unhandledRejection', (err) => exit(err));
+    return { exit, onDispose };
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@uncaught/gpio-shutter-bridge",
+  "author": "uncaught <uncaught42@gmail.com>",
+  "license": "MIT",
+  "version": "1.0.0",
+  "description": "MQTT shutter bridge for home assistant with Velux KLF 150 support",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/uncaught/gpio-shutter-bridge.git"
+  },
+  "bugs": {
+    "url": "https://github.com/uncaught/gpio-shutter-bridge/issues"
+  },
+  "homepage": "https://github.com/uncaught/gpio-shutter-bridge#readme",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "lodash.debounce": "^4.0.8",
+    "mqtt": "^5.14.1",
+    "onoff": "^6.0.3"
+  },
+  "devDependencies": {
+    "@tsconfig/node20": "^20.1.6",
+    "@types/lodash.debounce": "^4.0.9",
+    "@types/node": "^20",
+    "typescript": "^5.9.3"
+  },
+  "sideEffects": [
+    "./example.ts"
+  ],
+  "keywords": [
+    "mqtt",
+    "home-assistant",
+    "velux",
+    "klf150",
+    "shutter",
+    "gpio",
+    "raspberry-pi"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}