homey 4.2.3 → 4.3.0

package/bin/cmds/app/driver/firmware.mjs

@@ -0,0 +1,36 @@
+'use strict';
+
+import path from 'path';
+import Log from '../../../../lib/Log.js';
+import App from '../../../../lib/App.js';
+
+export const desc = 'Add a device firmware update to a Driver';
+
+export const builder = (yargs) => {
+  return yargs
+    .option('driver', {
+      describe: 'Path to the driver to which the firmware update should be added',
+      type: 'string',
+      demandOption: true,
+    })
+    .option('firmware', {
+      describe: 'Path to a firmware file (can be specified multiple times)',
+      type: 'array',
+      demandOption: true,
+    });
+};
+export const handler = async (yargs) => {
+  try {
+    const firmwareFiles = yargs.firmware.map((f) => path.resolve(process.cwd(), f));
+
+    const app = new App(yargs.path);
+    await app.createFirmwareUpdate({
+      driverPath: yargs.driver,
+      firmwareFiles,
+    });
+    process.exit(0);
+  } catch (err) {
+    Log.error(err);
+    process.exit(1);
+  }
+};

package/lib/App.js

@@ -3020,6 +3020,158 @@ $ sudo systemctl restart docker
     Log.success(`Flow created in \`${flowPath}\``);
   }
 
+  async createFirmwareUpdate({ driverPath, firmwareFiles } = {}) {
+    if (App.hasHomeyCompose({ appPath: this.path }) === false) {
+      // Note: this checks that we are in a valid homey app folder
+      App.getManifest({ appPath: this.path });
+
+      if (await this._askComposeMigration()) {
+        await this.migrateToCompose();
+      } else {
+        throw new Error('This command requires Homey compose, run `homey app compose` to migrate!');
+      }
+    }
+
+    // Load driver
+    if (!driverPath) {
+      throw new Error('A driver path is required. Use --driver to specify the path to the driver.');
+    }
+
+    driverPath = path.isAbsolute(driverPath) ? driverPath : path.resolve(this.path, driverPath);
+    const selectedDriverId = path.basename(driverPath);
+
+    const driverJsonPath = path.join(driverPath, 'driver.compose.json');
+    let driverJson;
+    try {
+      const driverJsonString = await readFileAsync(driverJsonPath, 'utf8');
+      driverJson = JSON.parse(driverJsonString);
+    } catch (err) {
+      throw new Error(`Failed to load driver from \`${driverJsonPath}\`: ${err.message}`);
+    }
+
+    const isZigbeeDriver =
+      driverJson.zigbee && typeof driverJson.zigbee === 'object' && driverJson.zigbee !== null;
+    const isZwaveDriver =
+      driverJson.zwave && typeof driverJson.zwave === 'object' && driverJson.zwave !== null;
+
+    if (!isZigbeeDriver && !isZwaveDriver) {
+      throw new Error(
+        `Driver \`${selectedDriverId}\` is not a Zigbee or Z-Wave driver. Firmware updates are only supported for Zigbee or Z-Wave drivers.`,
+      );
+    }
+
+    // Dynamic import required: CJS cannot require() an ESM (.mjs) module
+    const { default: DeviceFirmwareUpdatesHelper } =
+      await import('./DeviceFirmwareUpdatesHelper.mjs');
+
+    // Validate firmware files
+    if (!firmwareFiles || firmwareFiles.length === 0) {
+      throw new Error(
+        'At least one firmware file path is required. Use --firmware to specify the path to the firmware file.',
+      );
+    }
+    for (const firmwareFile of firmwareFiles) {
+      await DeviceFirmwareUpdatesHelper.validateFirmwareFile({ firmwareFile, isZigbeeDriver });
+    }
+
+    // Collect changelog and version constraints
+    const { changelog, requireSpecificVersion } =
+      await DeviceFirmwareUpdatesHelper.collectChangelog();
+
+    // Collect per-update Z-Wave constraints
+    let applicableTo;
+    if (requireSpecificVersion && isZwaveDriver) {
+      applicableTo = await DeviceFirmwareUpdatesHelper.collectZwaveApplicableTo();
+    }
+
+    // Collect device targeting (once per update)
+    let device;
+    if (isZigbeeDriver) {
+      device = await DeviceFirmwareUpdatesHelper.collectZigbeeDevice({ driverJson });
+    } else if (isZwaveDriver) {
+      device = await DeviceFirmwareUpdatesHelper.collectZwaveDevice({ driverJson });
+    }
+
+    // Collect Z-Wave version (once per update)
+    let zwaveVersion;
+    if (isZwaveDriver) {
+      zwaveVersion = await DeviceFirmwareUpdatesHelper.collectZwaveVersion();
+    }
+
+    const files = [];
+    for (const firmwareFile of firmwareFiles) {
+      if (isZwaveDriver) {
+        Log.info(`\nEntering details for: ${path.basename(firmwareFile)}`);
+      }
+      await DeviceFirmwareUpdatesHelper.copyFirmwareFile({
+        firmwarePath: firmwareFile,
+        appPath: this.path,
+        selectedDriverId,
+      });
+
+      let fileEntry;
+      if (isZigbeeDriver) {
+        // Collect per-file Zigbee version constraints
+        let minFileVersion;
+        let maxFileVersion;
+        if (requireSpecificVersion) {
+          ({ minFileVersion, maxFileVersion } =
+            await DeviceFirmwareUpdatesHelper.collectZigbeeVersionConstraints());
+        }
+        fileEntry = await DeviceFirmwareUpdatesHelper.collectZigbeeFileMetadata({
+          firmwarePath: firmwareFile,
+          minFileVersion,
+          maxFileVersion,
+        });
+      } else {
+        fileEntry = await DeviceFirmwareUpdatesHelper.collectZwaveFileMetadata({
+          firmwarePath: firmwareFile,
+        });
+      }
+      files.push(fileEntry);
+    }
+
+    // Build update JSON
+    const updateJson = {
+      changelog: { en: changelog },
+      device,
+      files,
+    };
+
+    if (isZwaveDriver) {
+      updateJson.version = zwaveVersion;
+      updateJson.applicableTo = applicableTo;
+    }
+
+    // Write to driver.firmware.compose.json
+    const updatesFilePath = path.join(
+      this.path,
+      'drivers',
+      selectedDriverId,
+      'driver.firmware.compose.json',
+    );
+
+    const isNewFile = !fs.existsSync(updatesFilePath);
+    const firmwareUpdatesJson = await DeviceFirmwareUpdatesHelper.readFirmwareUpdatesJson({
+      updatesFilePath,
+    });
+
+    if (isNewFile) {
+      const { wakeUpInstruction } = await DeviceFirmwareUpdatesHelper.collectSleepMode();
+      if (wakeUpInstruction) {
+        firmwareUpdatesJson.wakeInstruction = { en: wakeUpInstruction };
+      }
+    }
+
+    firmwareUpdatesJson.updates.push(updateJson);
+    await DeviceFirmwareUpdatesHelper.writeFirmwareUpdatesJson({
+      updatesFilePath,
+      firmwareUpdatesJson,
+    });
+
+    Log.success(`Firmware update created in \`${updatesFilePath}\``);
+  }
+
   async createWidget() {
     if (App.hasHomeyCompose({ appPath: this.path }) === false) {
       // Note: this checks that we are in a valid homey app folder

package/lib/DeviceFirmwareUpdatesHelper.mjs

@@ -0,0 +1,387 @@
+import fs from 'fs';
+import path from 'path';
+import { promisify } from 'util';
+
+import fse from 'fs-extra';
+import inquirer from 'inquirer';
+import semver from 'semver';
+import homeyLib from 'homey-lib';
+
+const HomeyLibUtil = homeyLib.Util;
+
+const readFileAsync = promisify(fs.readFile);
+const writeFileAsync = promisify(fs.writeFile);
+const copyFileAsync = promisify(fs.copyFile);
+
+export default class DeviceFirmwareUpdatesHelper {
+  static async validateFirmwareFile({ firmwareFile, isZigbeeDriver }) {
+    if (!fs.existsSync(firmwareFile)) {
+      throw new Error(`Firmware file \`${firmwareFile}\` does not exist!`);
+    }
+
+    if (isZigbeeDriver) {
+      try {
+        await HomeyLibUtil.validateZigbeeOTAHeader({ filePath: firmwareFile });
+      } catch (err) {
+        throw new Error(`Invalid Zigbee OTA file: ${err.message}`);
+      }
+    }
+
+    return firmwareFile;
+  }
+
+  static async collectChangelog() {
+    return inquirer.prompt([
+      {
+        type: 'string',
+        name: 'changelog',
+        message: 'What is the changelog for this firmware update?',
+        validate: (input) => input.length > 0,
+      },
+      {
+        type: 'confirm',
+        name: 'requireSpecificVersion',
+        message:
+          'Should this update only apply to devices within a certain firmware version range?',
+        default: false,
+      },
+    ]);
+  }
+
+  static async collectZigbeeVersionConstraints() {
+    const versions = await inquirer.prompt([
+      {
+        type: 'string',
+        name: 'minFileVersion',
+        message: 'What is the minimum file version required on the device to perform the update?',
+        validate: (input) => {
+          input = Number(input);
+
+          if (Number.isNaN(input)) {
+            return 'Minimum file version must be a number';
+          }
+
+          if (!Number.isInteger(input)) {
+            return 'Minimum file version must be an integer';
+          }
+
+          if (input < 0 || input > 0xffff_ffff) {
+            return 'Minimum file version must be a 32-bit unsigned integer';
+          }
+
+          return true;
+        },
+      },
+      {
+        type: 'string',
+        name: 'maxFileVersion',
+        message: 'What is the maximum file version required on the device to perform the update?',
+        validate: (input) => {
+          input = Number(input);
+
+          if (Number.isNaN(input)) {
+            return 'Maximum file version must be a number';
+          }
+
+          if (!Number.isInteger(input)) {
+            return 'Maximum file version must be an integer';
+          }
+
+          if (input < 0 || input > 0xffff_ffff) {
+            return 'Maximum file version must be a 32-bit unsigned integer';
+          }
+
+          return true;
+        },
+      },
+    ]);
+
+    return {
+      minFileVersion: Number(versions.minFileVersion),
+      maxFileVersion: Number(versions.maxFileVersion),
+    };
+  }
+
+  static async collectZwaveApplicableTo() {
+    const { applicableTo } = await inquirer.prompt([
+      {
+        type: 'string',
+        name: 'applicableTo',
+        message:
+          'Enter a semver constraint to specify which device firmware versions this update should apply to (e.g. <2.0.0)',
+        validate: (input) => {
+          const validated = semver.validRange(input);
+          return validated ? true : 'Please enter a valid semver constraint';
+        },
+      },
+    ]);
+    return applicableTo;
+  }
+
+  static async collectZigbeeDevice({ driverJson }) {
+    const manufacturerNames = Array.isArray(driverJson.zigbee.manufacturerName)
+      ? driverJson.zigbee.manufacturerName
+      : [driverJson.zigbee.manufacturerName];
+    const productIds = Array.isArray(driverJson.zigbee.productId)
+      ? driverJson.zigbee.productId
+      : [driverJson.zigbee.productId];
+
+    const { selectedManufacturerNames, selectedProductIds } = await inquirer.prompt([
+      {
+        type: 'checkbox',
+        name: 'selectedManufacturerNames',
+        message: 'Which manufacturer names should this firmware update apply to?',
+        choices: manufacturerNames,
+        default: manufacturerNames,
+        validate: (input) => {
+          return input.length > 0 || 'Select at least one manufacturer name';
+        },
+      },
+      {
+        type: 'checkbox',
+        name: 'selectedProductIds',
+        message: 'Which product IDs should this firmware update apply to?',
+        choices: productIds,
+        default: productIds,
+        validate: (input) => {
+          return input.length > 0 || 'Select at least one product ID';
+        },
+      },
+    ]);
+
+    return {
+      manufacturerName:
+        selectedManufacturerNames.length === 1
+          ? selectedManufacturerNames[0]
+          : selectedManufacturerNames,
+      productId: selectedProductIds.length === 1 ? selectedProductIds[0] : selectedProductIds,
+    };
+  }
+
+  static async collectZwaveDevice({ driverJson }) {
+    const toArray = (value) => {
+      if (Array.isArray(value)) {
+        return value;
+      } else if (value !== undefined) {
+        return [value];
+      } else {
+        return [];
+      }
+    };
+
+    const manufacturerIds = toArray(driverJson.zwave.manufacturerId);
+    const productTypeIds = toArray(driverJson.zwave.productTypeId);
+    const productIds = toArray(driverJson.zwave.productId);
+
+    const { selectedManufacturerIds, selectedProductTypeIds, selectedProductIds } =
+      await inquirer.prompt([
+        {
+          type: 'checkbox',
+          name: 'selectedManufacturerIds',
+          message: 'Which manufacturer IDs should this firmware update apply to?',
+          choices: manufacturerIds,
+          default: manufacturerIds,
+          validate: (input) => {
+            return input.length > 0 || 'Select at least one manufacturer ID';
+          },
+        },
+        {
+          type: 'checkbox',
+          name: 'selectedProductTypeIds',
+          message: 'Which product type IDs should this firmware update apply to?',
+          choices: productTypeIds,
+          default: productTypeIds,
+          validate: (input) => {
+            return input.length > 0 || 'Select at least one product type ID';
+          },
+        },
+        {
+          type: 'checkbox',
+          name: 'selectedProductIds',
+          message: 'Which product IDs should this firmware update apply to?',
+          choices: productIds,
+          default: productIds,
+          validate: (input) => {
+            return input.length > 0 || 'Select at least one product ID';
+          },
+        },
+      ]);
+
+    return {
+      manufacturerId:
+        selectedManufacturerIds.length === 1 ? selectedManufacturerIds[0] : selectedManufacturerIds,
+      productTypeId:
+        selectedProductTypeIds.length === 1 ? selectedProductTypeIds[0] : selectedProductTypeIds,
+      productId: selectedProductIds.length === 1 ? selectedProductIds[0] : selectedProductIds,
+    };
+  }
+
+  static async collectZigbeeFileMetadata({ firmwarePath, minFileVersion, maxFileVersion }) {
+    const header = await HomeyLibUtil.parseZigbeeOTAHeader(firmwarePath);
+    const integrity = await HomeyLibUtil.getIntegrity(firmwarePath, 'sha256');
+    const fileName = path.basename(firmwarePath);
+
+    return {
+      fileVersion: header.fileVersion,
+      imageType: header.imageType,
+      manufacturerCode: header.manufacturerCode,
+      minFileVersion,
+      maxFileVersion,
+      maxHardwareVersion: header.maximumHardwareVersion,
+      minHardwareVersion: header.minimumHardwareVersion,
+      size: header.totalImageSize,
+      name: fileName,
+      integrity,
+    };
+  }
+
+  static async collectZwaveFileMetadata({ firmwarePath }) {
+    const { targetId, region } = await inquirer.prompt([
+      {
+        type: 'number',
+        name: 'targetId',
+        message: 'What is the chip target ID for this file?',
+        default: 0,
+        validate: (input) => {
+          if (Number.isNaN(input)) {
+            return 'Target ID must be a number';
+          }
+
+          if (!Number.isInteger(input)) {
+            return 'Target ID must be an integer';
+          }
+
+          if (input < 0 || input > 255) {
+            return 'Target ID must be between 0 and 255';
+          }
+
+          return true;
+        },
+      },
+      {
+        type: 'list',
+        name: 'region',
+        message: 'What is the region for this file?',
+        choices: [
+          { name: 'None/Global', value: null },
+          { name: 'ANZ - Australia/New Zealand (919.8 MHz / 921.4 MHz)', value: 'ANZ' },
+          { name: 'CN - China (868.4 MHz)', value: 'CN' },
+          { name: 'EU - Europe (868.4 MHz / 869.85 MHz)', value: 'EU' },
+          { name: 'HK - Hong Kong (919.8 MHz)', value: 'HK' },
+          { name: 'IL - Israel (916 MHz)', value: 'IL' },
+          { name: 'IN - India (865.2 MHz)', value: 'IN' },
+          { name: 'JP - Japan (922.5 MHz / 923.9 MHz / 926.3 MHz)', value: 'JP' },
+          { name: 'KR - Korea (920.9 MHz / 921.7 MHz / 923.1 MHz)', value: 'KR' },
+          { name: 'RU - Russia (869 MHz)', value: 'RU' },
+          // { name: 'US_LR - United States of America (Z-Wave & Long Range)', value: 'US_LR' },
+          { name: 'US - United States of America (908.4 MHz / 916 MHz)', value: 'US' },
+        ],
+        default: null,
+      },
+    ]);
+
+    const integrity = await HomeyLibUtil.getIntegrity(firmwarePath, 'sha256');
+    const fileName = path.basename(firmwarePath);
+    const { size } = await fs.promises.stat(firmwarePath);
+
+    return {
+      name: fileName,
+      integrity,
+      size,
+      targetId,
+      region: region !== null ? region : undefined,
+    };
+  }
+
+  static async collectZwaveVersion() {
+    const { version } = await inquirer.prompt([
+      {
+        type: 'string',
+        name: 'version',
+        message: 'What is the version of the firmware update?',
+        validate: (input) => {
+          if (input.length === 0) {
+            return 'Version cannot be empty';
+          }
+
+          if (!semver.valid(input)) {
+            return 'Please enter a valid semver version';
+          }
+
+          return true;
+        },
+      },
+    ]);
+    return version;
+  }
+
+  static async copyFirmwareFile({ firmwarePath, appPath, selectedDriverId }) {
+    const fileName = path.basename(firmwarePath);
+    const firmwareDestPath = path.join(
+      appPath,
+      'drivers',
+      selectedDriverId,
+      'assets',
+      'firmware',
+      fileName,
+    );
+
+    await fse.ensureDir(path.dirname(firmwareDestPath));
+    await copyFileAsync(firmwarePath, firmwareDestPath);
+  }
+
+  static async collectSleepMode() {
+    const { hasSleepMode } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'hasSleepMode',
+        message: 'Does this device go into a sleep mode?',
+        default: false,
+      },
+    ]);
+
+    if (!hasSleepMode) {
+      return { hasSleepMode };
+    }
+
+    const { wakeUpInstruction } = await inquirer.prompt([
+      {
+        type: 'string',
+        name: 'wakeUpInstruction',
+        message: 'Enter a short description on how to wake the device from sleep mode.',
+        validate: (input) => input.length > 0,
+      },
+    ]);
+
+    return { hasSleepMode, wakeUpInstruction };
+  }
+
+  static async readFirmwareUpdatesJson({ updatesFilePath }) {
+    try {
+      const content = await readFileAsync(updatesFilePath, 'utf8');
+      const json = JSON.parse(content);
+
+      if (
+        typeof json !== 'object' ||
+        json === null ||
+        !json.updates ||
+        !Array.isArray(json.updates)
+      ) {
+        throw new Error('Invalid firmware updates JSON: missing "updates" array');
+      }
+
+      return json;
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        return { updates: [] };
+      }
+      throw new Error(
+        `Error in \`driver.firmware.compose.json\` at \`${updatesFilePath}\`: ${err.message}`,
+      );
+    }
+  }
+
+  static async writeFirmwareUpdatesJson({ updatesFilePath, firmwareUpdatesJson }) {
+    await writeFileAsync(updatesFilePath, JSON.stringify(firmwareUpdatesJson, null, 2));
+  }
+}

package/lib/HomeyCompose.js

@@ -19,6 +19,7 @@
   /drivers/<id>/driver.compose.json (extend with "$extends": [ "<template_id>" ])
   /drivers/<id>/driver.settings.compose.json
     (array with driver settings, extend with "$extends": "<template_id>"))
+  /drivers/<id>/driver.firmware.compose.json
   /drivers/<id>/driver.flow.compose.json (object with flow cards, device arg is added automatically)
   /drivers/<id>/driver.pair.compose.json (object with pair views)
   /drivers/<id>/driver.repair.compose.json (object with repair views)
@@ -220,6 +221,15 @@ class HomeyCompose {
         if (err.code !== 'ENOENT') throw new Error(err);
       }
 
+      // merge firmware updates
+      try {
+        driverJson.firmwareUpdates = await this._getJsonFile(
+          path.join(this._appPath, 'drivers', driverId, 'driver.firmware.compose.json'),
+        );
+      } catch (err) {
+        if (err.code !== 'ENOENT') throw new Error(err);
+      }
+
       // merge template settings
       try {
         const settingsTemplates = await this._getJsonFiles(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homey",
-  "version": "4.2.3",
+  "version": "4.3.0",
   "description": "Command-line interface and type declarations for Homey Apps",
   "main": "bin/homey.js",
   "files": [