homebridge-la-marzocco 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Matt Weiden
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# Homebridge plugin for La Marzocco
+[![Tests](https://github.com/mweiden/lm-homebridge/actions/workflows/tests.yml/badge.svg)](https://github.com/mweiden/lm-homebridge/actions/workflows/tests.yml)
+[![codecov](https://codecov.io/gh/mweiden/lm-homebridge/branch/main/graph/badge.svg)](https://codecov.io/gh/mweiden/lm-homebridge)
+
+[Homebridge](https://homebridge.io/) plugin for La Marzocco espresso machines. Enables turning your La Marzocco IoT-enabled espresso machine (i.e. a Linea Micra or Linea Mini) on and off with [Apple HomeKit](https://en.wikipedia.org/wiki/Apple_Home).
+
+<img height="600" alt="IMG_2168" src="https://github.com/user-attachments/assets/b8f2e146-a8cb-42f2-9bc0-d658649d067d" />
+
+## Configure
+Add the platform in your Homebridge `config.json`:
+
+```json
+{
+  "platforms": [
+    {
+      "platform": "LaMarzocco",
+      "name": "La Marzocco",
+      "serial": "YOUR_SERIAL",
+      "username": "YOUR_USERNAME",
+      "password": "YOUR_PASSWORD",
+      "pollIntervalSeconds": 30
+    }
+  ]
+}
+```
+
+The plugin stores the installation key under the Homebridge storage path by
+default. Override with `installationKeyPath` if needed. Set
+`pollIntervalSeconds` to `0` to disable polling.
+
+## Development
+
+### Install for development
+
+Using the `homebridge` terminal copy the repo into your machine and
+
+```bash
+npm install --prefix /var/lib/homebridge <path_to_homebridge_repo> 
+```
+
+You will then have to put homebridge into Debug mode and restart homebridge.
+
+### Prerequisites
+- Node.js 18+ (for built-in `fetch` and crypto support).
+
+### Unit Tests
+Run unit tests with:
+
+```bash
+npx jest
+```
+
+### Manual integration test
+This repo includes a Node.js script that exercises the LM cloud API flow using
+the local client library.
+
+Set environment variables and run the script:
+
+```bash
+export LM_SERIAL="YOUR_SERIAL"
+export LM_USERNAME="YOUR_USERNAME"
+export LM_PASSWORD="YOUR_PASSWORD"
+node scripts/lm_manual_test.js
+```
+
+To toggle power:
+
+```bash
+node scripts/lm_manual_test.js --power on
+node scripts/lm_manual_test.js --power off
+```
+
+The script stores the installation key in `installation_key.json` by default and
+will auto-register it on first run. Override the location with `LM_KEY_PATH`.
+
+## Acknowledgements
+
+Full props to @zweckj for figuring out the LM API. The client code here is based on https://github.com/zweckj/pylamarzocco.

package/config.schema.json

@@ -0,0 +1,43 @@
+{
+  "pluginAlias": "LaMarzocco",
+  "pluginType": "platform",
+  "singular": true,
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "title": "Platform Name",
+        "type": "string",
+        "default": "La Marzocco"
+      },
+      "serial": {
+        "title": "Machine Serial Number",
+        "type": "string"
+      },
+      "username": {
+        "title": "LM Cloud Username",
+        "type": "string"
+      },
+      "password": {
+        "title": "LM Cloud Password",
+        "type": "string",
+        "format": "password"
+      },
+      "installationKeyPath": {
+        "title": "Installation Key Path",
+        "type": "string"
+      },
+      "pollIntervalSeconds": {
+        "title": "Polling Interval (seconds)",
+        "type": "integer",
+        "default": 30,
+        "minimum": 0
+      }
+    },
+    "required": [
+      "serial",
+      "username",
+      "password"
+    ]
+  }
+}

package/lib/lm_client.js

@@ -0,0 +1,310 @@
+"use strict";
+
+const crypto = require("crypto");
+
+const BASE_URL = "https://lion.lamarzocco.io";
+const CUSTOMER_APP_URL = `${BASE_URL}/api/customer-app`;
+const TOKEN_TIME_TO_REFRESH_MS = 10 * 60 * 1000;
+const TOKEN_EXPIRATION_MS = 60 * 60 * 1000;
+
+function b64(buf) {
+  return Buffer.from(buf).toString("base64");
+}
+
+function sha256(buf) {
+  return crypto.createHash("sha256").update(buf).digest();
+}
+
+function generateRequestProof(baseString, secret32) {
+  if (!Buffer.isBuffer(secret32) || secret32.length !== 32) {
+    throw new Error("secret must be 32 bytes");
+  }
+
+  const work = Buffer.from(secret32);
+  const input = Buffer.from(baseString, "utf8");
+
+  for (const byteVal of input) {
+    const idx = byteVal % 32;
+    const shiftIdx = (idx + 1) % 32;
+    const shiftAmount = work[shiftIdx] & 7;
+
+    const xorResult = byteVal ^ work[idx];
+    const rotated = ((xorResult << shiftAmount) | (xorResult >> (8 - shiftAmount))) & 0xff;
+    work[idx] = rotated;
+  }
+
+  return b64(sha256(work));
+}
+
+function generateInstallationKey(installationId) {
+  const { privateKey } = crypto.generateKeyPairSync("ec", {
+    namedCurve: "prime256v1",
+  });
+
+  const privateKeyDer = privateKey.export({ format: "der", type: "pkcs8" });
+  const publicKeyDer = crypto.createPublicKey(privateKey).export({ format: "der", type: "spki" });
+
+  const pubB64 = b64(publicKeyDer);
+  const instHashB64 = b64(sha256(Buffer.from(installationId, "utf8")));
+  const secret = sha256(Buffer.from(`${installationId}.${pubB64}.${instHashB64}`, "utf8"));
+
+  return {
+    installation_id: installationId,
+    secret: b64(secret),
+    private_key: b64(privateKeyDer),
+  };
+}
+
+function parseInstallationKey(raw) {
+  if (!raw || !raw.installation_id || !raw.secret || !raw.private_key) {
+    throw new Error("Invalid installation key data");
+  }
+
+  return {
+    installation_id: raw.installation_id,
+    secret: Buffer.from(raw.secret, "base64"),
+    private_key: raw.private_key,
+  };
+}
+
+function loadPrivateKey(installationKey) {
+  return crypto.createPrivateKey({
+    key: Buffer.from(installationKey.private_key, "base64"),
+    format: "der",
+    type: "pkcs8",
+  });
+}
+
+function publicKeyBase64(installationKey) {
+  const privateKey = loadPrivateKey(installationKey);
+  const publicDer = crypto.createPublicKey(privateKey).export({ format: "der", type: "spki" });
+  return b64(publicDer);
+}
+
+function baseStringForRegistration(installationKey) {
+  const privateKey = loadPrivateKey(installationKey);
+  const publicDer = crypto.createPublicKey(privateKey).export({ format: "der", type: "spki" });
+  const pubHashB64 = b64(sha256(publicDer));
+  return `${installationKey.installation_id}.${pubHashB64}`;
+}
+
+function generateExtraRequestHeaders(installationKey) {
+  const nonce = crypto.randomUUID().toLowerCase();
+  const timestamp = Date.now().toString();
+  const proofInput = `${installationKey.installation_id}.${nonce}.${timestamp}`;
+  const proof = generateRequestProof(proofInput, installationKey.secret);
+  const signatureData = `${proofInput}.${proof}`;
+
+  const signer = crypto.createSign("SHA256");
+  signer.update(signatureData, "utf8");
+  signer.end();
+
+  const privateKey = loadPrivateKey(installationKey);
+  const signature = signer.sign(privateKey);
+
+  return {
+    "X-App-Installation-Id": installationKey.installation_id,
+    "X-Timestamp": timestamp,
+    "X-Nonce": nonce,
+    "X-Request-Signature": b64(signature),
+  };
+}
+
+const DEFAULT_TIMEOUT_MS = 10000;
+
+async function jsonRequest(url, options) {
+  const timeoutMs =
+    typeof options.timeoutMs === "number" ? options.timeoutMs : DEFAULT_TIMEOUT_MS;
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+  const { timeoutMs: _timeoutMs, ...fetchOptions } = options;
+
+  let response;
+  try {
+    response = await fetch(url, { ...fetchOptions, signal: controller.signal });
+  } catch (err) {
+    if (err && err.name === "AbortError") {
+      const timeoutError = new Error(`Request timed out after ${timeoutMs}ms`);
+      timeoutError.code = "ETIMEDOUT";
+      throw timeoutError;
+    }
+    throw err;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+  const text = await response.text();
+  let data;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch (err) {
+    data = text;
+  }
+
+  if (!response.ok) {
+    const error = new Error(`Request failed: ${response.status} ${response.statusText}`);
+    error.status = response.status;
+    error.payload = data;
+    throw error;
+  }
+
+  return data;
+}
+
+class LaMarzoccoCloudClient {
+  constructor({ username, password, installationKey }) {
+    this.username = username;
+    this.password = password;
+    this.installationKey = parseInstallationKey(installationKey);
+    this.token = null;
+  }
+
+  async registerClient() {
+    const baseString = baseStringForRegistration(this.installationKey);
+    const proof = generateRequestProof(baseString, this.installationKey.secret);
+
+    const headers = {
+      "X-App-Installation-Id": this.installationKey.installation_id,
+      "X-Request-Proof": proof,
+    };
+
+    const body = {
+      pk: publicKeyBase64(this.installationKey),
+    };
+
+    await jsonRequest(`${CUSTOMER_APP_URL}/auth/init`, {
+      method: "POST",
+      headers: {
+        ...headers,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(body),
+    });
+  }
+
+  async getAccessToken() {
+    if (!this.token) {
+      this.token = await this.signIn();
+      return this.token.access_token;
+    }
+
+    const now = Date.now();
+    if (this.token.expires_at <= now) {
+      this.token = await this.signIn();
+      return this.token.access_token;
+    }
+
+    if (this.token.expires_at <= now + TOKEN_TIME_TO_REFRESH_MS) {
+      this.token = await this.refreshToken();
+      return this.token.access_token;
+    }
+
+    return this.token.access_token;
+  }
+
+  async signIn() {
+    const headers = generateExtraRequestHeaders(this.installationKey);
+    const data = await jsonRequest(`${CUSTOMER_APP_URL}/auth/signin`, {
+      method: "POST",
+      headers: {
+        ...headers,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        username: this.username,
+        password: this.password,
+      }),
+    });
+
+    return {
+      access_token: data.accessToken,
+      refresh_token: data.refreshToken,
+      expires_at: Date.now() + TOKEN_EXPIRATION_MS,
+    };
+  }
+
+  async refreshToken() {
+    if (!this.token) {
+      return this.signIn();
+    }
+
+    const headers = generateExtraRequestHeaders(this.installationKey);
+    const data = await jsonRequest(`${CUSTOMER_APP_URL}/auth/refreshtoken`, {
+      method: "POST",
+      headers: {
+        ...headers,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        username: this.username,
+        refreshToken: this.token.refresh_token,
+      }),
+    });
+
+    return {
+      access_token: data.accessToken,
+      refresh_token: data.refreshToken,
+      expires_at: Date.now() + TOKEN_EXPIRATION_MS,
+    };
+  }
+
+  async apiCall({ url, method, body }) {
+    const token = await this.getAccessToken();
+    const headers = {
+      ...generateExtraRequestHeaders(this.installationKey),
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+    };
+
+    return jsonRequest(url, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+  }
+
+  async getDashboard(serialNumber) {
+    return this.apiCall({
+      url: `${CUSTOMER_APP_URL}/things/${serialNumber}/dashboard`,
+      method: "GET",
+    });
+  }
+
+  async setPower(serialNumber, enabled) {
+    const mode = enabled ? "BrewingMode" : "StandBy";
+    const response = await this.apiCall({
+      url: `${CUSTOMER_APP_URL}/things/${serialNumber}/command/CoffeeMachineChangeMode`,
+      method: "POST",
+      body: { mode },
+    });
+
+    return response;
+  }
+}
+
+function extractPowerFromDashboard(dashboard) {
+  if (!dashboard || !Array.isArray(dashboard.widgets)) {
+    return null;
+  }
+
+  const statusWidget = dashboard.widgets.find(
+    (widget) => widget && widget.code === "CMMachineStatus"
+  );
+  if (!statusWidget || !statusWidget.output || !statusWidget.output.mode) {
+    return null;
+  }
+
+  return statusWidget.output.mode === "BrewingMode";
+}
+
+module.exports = {
+  LaMarzoccoCloudClient,
+  generateInstallationKey,
+  extractPowerFromDashboard,
+  _test:
+    process.env.NODE_ENV === "test"
+      ? {
+          generateRequestProof,
+          parseInstallationKey,
+        }
+      : undefined,
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "homebridge-la-marzocco",
+  "version": "0.1.0",
+  "description": "Homebridge integration for La Marzocco espresso machines",
+  "displayName": "La Marzocco",
+  "main": "src/index.js",
+  "license": "MIT",
+  "keywords": [
+    "homebridge-plugin",
+    "homebridge",
+    "lamarzocco",
+    "espresso"
+  ],
+  "scripts": {
+    "test": "NODE_ENV=test npx jest --coverage test/*.test.js",
+    "integration-test": "node scripts/lm_manual_test.js"
+  },
+  "engines": {
+    "node": ">=18.0.0",
+    "homebridge": "^1.8.0 || ^2.0.0-beta.0"
+  },
+  "author": "",
+  "files": [
+    "src",
+    "lib",
+    "config.schema.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "homebridge": {
+    "platforms": [
+      "LaMarzocco"
+    ]
+  },
+  "devDependencies": {
+    "jest": "^30.2.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,8 @@
+"use strict";
+
+const { PLUGIN_NAME, PLATFORM_NAME } = require("./settings");
+const { LaMarzoccoPlatform } = require("./platform");
+
+module.exports = (api) => {
+  api.registerPlatform(PLUGIN_NAME, PLATFORM_NAME, LaMarzoccoPlatform);
+};

package/src/platform.js

@@ -0,0 +1,128 @@
+"use strict";
+
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+const {
+  LaMarzoccoCloudClient,
+  generateInstallationKey,
+} = require("../lib/lm_client");
+const { LaMarzoccoPlatformAccessory } = require("./platformAccessory");
+const { PLUGIN_NAME, PLATFORM_NAME } = require("./settings");
+
+class LaMarzoccoPlatform {
+  constructor(log, config, api) {
+    this.log = log;
+    this.config = config || {};
+    this.api = api;
+    this.accessories = [];
+
+    this.Service = this.api.hap.Service;
+    this.Characteristic = this.api.hap.Characteristic;
+
+    if (!config) {
+      this.log.warn("No config supplied. Skipping plugin setup.");
+      return;
+    }
+
+    this.name = this.config.name || "La Marzocco";
+    this.serial = this.config.serial;
+    this.username = this.config.username;
+    this.password = this.config.password;
+    this.pollIntervalSeconds = Number(this.config.pollIntervalSeconds || 30);
+
+    if (!this.serial || !this.username || !this.password) {
+      this.log.error(
+        "Missing required config. Please set serial, username, and password."
+      );
+      return;
+    }
+
+    const storageRoot = this.api.user.storagePath();
+    const defaultKeyPath = path.join(
+      storageRoot,
+      "lm-homebridge",
+      "installation_key.json"
+    );
+    this.installationKeyPath =
+      this.config.installationKeyPath || defaultKeyPath;
+    this.ensureKeyDir();
+
+    const { key, created } = this.loadOrCreateInstallationKey();
+    this.client = new LaMarzoccoCloudClient({
+      username: this.username,
+      password: this.password,
+      installationKey: key,
+    });
+
+    if (created) {
+      this.registerInstallationKey().catch((err) => {
+        this.log.error("Failed to register installation key: %s", err.message);
+      });
+    }
+
+    this.api.on("didFinishLaunching", () => {
+      this.discoverDevices();
+    });
+  }
+
+  configureAccessory(accessory) {
+    this.log.info("Loading accessory from cache: %s", accessory.displayName);
+    this.accessories.push(accessory);
+  }
+
+  ensureKeyDir() {
+    const dir = path.dirname(this.installationKeyPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+  }
+
+  loadOrCreateInstallationKey() {
+    if (fs.existsSync(this.installationKeyPath)) {
+      const raw = fs.readFileSync(this.installationKeyPath, "utf8");
+      return { key: JSON.parse(raw), created: false };
+    }
+
+    const installationId = crypto.randomUUID().toLowerCase();
+    const key = generateInstallationKey(installationId);
+    fs.writeFileSync(this.installationKeyPath, JSON.stringify(key, null, 2), {
+      mode: 0o600,
+    });
+    return { key, created: true };
+  }
+
+  async registerInstallationKey() {
+    this.log.info("Registering installation key with LM cloud...");
+    await this.client.registerClient();
+    this.log.info("Installation key registration complete.");
+  }
+
+  discoverDevices() {
+    const uuid = this.api.hap.uuid.generate(this.serial);
+    const existingAccessory = this.accessories.find(
+      (accessory) => accessory.UUID === uuid
+    );
+
+    if (existingAccessory) {
+      existingAccessory.context.device = {
+        name: this.name,
+        serial: this.serial,
+      };
+      new LaMarzoccoPlatformAccessory(this, existingAccessory);
+      this.api.updatePlatformAccessories([existingAccessory]);
+      return;
+    }
+
+    const accessory = new this.api.platformAccessory(this.name, uuid);
+    accessory.context.device = {
+      name: this.name,
+      serial: this.serial,
+    };
+
+    new LaMarzoccoPlatformAccessory(this, accessory);
+    this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [accessory]);
+  }
+}
+
+module.exports = { LaMarzoccoPlatform };

package/src/platformAccessory.js

@@ -0,0 +1,90 @@
+"use strict";
+
+const { extractPowerFromDashboard } = require("../lib/lm_client");
+
+class LaMarzoccoPlatformAccessory {
+  constructor(platform, accessory) {
+    this.platform = platform;
+    this.accessory = accessory;
+    this.cachedPower = false;
+
+    this.service =
+      this.accessory.getService(this.platform.Service.Switch) ||
+      this.accessory.addService(
+        this.platform.Service.Switch,
+        this.accessory.displayName
+      );
+
+    this.service
+      .getCharacteristic(this.platform.Characteristic.On)
+      .onGet(this.handleGet.bind(this))
+      .onSet(this.handleSet.bind(this));
+
+    const pollIntervalSeconds = this.platform.pollIntervalSeconds;
+    if (pollIntervalSeconds > 0) {
+      this.startPolling(pollIntervalSeconds);
+    }
+  }
+
+  async handleGet() {
+    if (!this.platform.client) {
+      return this.cachedPower;
+    }
+
+    try {
+      const dashboard = await this.platform.client.getDashboard(
+        this.platform.serial
+      );
+      const power = extractPowerFromDashboard(dashboard);
+      if (power === null) {
+        this.platform.log.warn(
+          "Unable to determine machine power from dashboard."
+        );
+        return this.cachedPower;
+      }
+      this.cachedPower = power;
+      return power;
+    } catch (err) {
+      this.platform.log.error(
+        "Failed to fetch dashboard: %s",
+        err.message || err
+      );
+      return this.cachedPower;
+    }
+  }
+
+  async handleSet(value) {
+    if (!this.platform.client) {
+      throw new Error("Accessory not configured.");
+    }
+
+    const enabled = value === true;
+    try {
+      await this.platform.client.setPower(this.platform.serial, enabled);
+      this.cachedPower = enabled;
+    } catch (err) {
+      this.platform.log.error(
+        "Failed to set power: %s",
+        err.message || err
+      );
+      throw err;
+    }
+  }
+
+  startPolling(intervalSeconds) {
+    const intervalMs = intervalSeconds * 1000;
+    setInterval(async () => {
+      try {
+        const power = await this.handleGet();
+        this.service.updateCharacteristic(
+          this.platform.Characteristic.On,
+          power
+        );
+      } catch (err) {
+        this.platform.log.debug("Polling error: %s", err.message || err);
+      }
+    }, intervalMs);
+  }
+}
+
+module.exports = { LaMarzoccoPlatformAccessory };

package/src/settings.js

@@ -0,0 +1,9 @@
+"use strict";
+
+const PLUGIN_NAME = "homebridge-lm-homebridge";
+const PLATFORM_NAME = "LaMarzocco";
+
+module.exports = {
+  PLUGIN_NAME,
+  PLATFORM_NAME,
+};