homebridge-solaxcloud-api 2.3.3 → 2.4.1

package/dist/util.js

@@ -1,43 +1,43 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Util = void 0;
-/**
- * Utility class.
- */
-class Util {
-    /**
-     * Calculates 32 bit hash from a string.
-     * @param s {string} String to calculate 32 bit hash from.
-     * @returns {number} The 32 bit hash from the string.
-     */
-    static hash32(s) {
-        let hash = 0;
-        if (s.length === 0) {
-            return hash;
-        }
-        for (let i = 0; i < s.length; i++) {
-            const chr = s.charCodeAt(i);
-            hash = ((hash << 5) - hash) + chr;
-            hash |= 0; // Convert to 32bit integer
-        }
-        return hash;
-    }
-    /**
-     * Removes non-standard alphanumeric characters from string.
-     * @param {string} s The original string.
-     * @returns {string} Resulting string without any non-standard chars.
-     */
-    static normalizeName(s) {
-        return s.replace(/[^-_ a-zA-Z0-9]/gi, '');
-    }
-    /**
-     * Returns whether an array has duplicates or not.
-     * @param {unknown[]} array The array to check for duplicates.
-     * @returns {boolean} Whether the array has duplicates.
-     */
-    static arrayHasDuplicates(array) {
-        return (new Set(array)).size !== array.length;
-    }
-}
-exports.Util = Util;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Util = void 0;
+/**
+ * Utility class.
+ */
+class Util {
+    /**
+     * Calculates 32 bit hash from a string.
+     * @param s {string} String to calculate 32 bit hash from.
+     * @returns {number} The 32 bit hash from the string.
+     */
+    static hash32(s) {
+        let hash = 0;
+        if (s.length === 0) {
+            return hash;
+        }
+        for (let i = 0; i < s.length; i++) {
+            const chr = s.charCodeAt(i);
+            hash = ((hash << 5) - hash) + chr;
+            hash |= 0; // Convert to 32bit integer
+        }
+        return hash;
+    }
+    /**
+     * Removes non-standard alphanumeric characters from string.
+     * @param {string} s The original string.
+     * @returns {string} Resulting string without any non-standard chars.
+     */
+    static normalizeName(s) {
+        return s.replace(/[^-_ a-zA-Z0-9]/gi, '');
+    }
+    /**
+     * Returns whether an array has duplicates or not.
+     * @param {unknown[]} array The array to check for duplicates.
+     * @returns {boolean} Whether the array has duplicates.
+     */
+    static arrayHasDuplicates(array) {
+        return (new Set(array)).size !== array.length;
+    }
+}
+exports.Util = Util;
 //# sourceMappingURL=util.js.map

package/package.json

@@ -1,54 +1,55 @@
-{
-  "private": false,
-  "displayName": "Homebridge Solax Cloud API",
-  "name": "homebridge-solaxcloud-api",
-  "version": "2.3.3",
-  "description": "Integrates solar production info using public Solax/QCells Cloud API into Homebridge accessories.",
-  "license": "Apache-2.0",
-  "repository": {
-    "type": "git",
-    "url": "git://github.com/AllMightySauron/homebride-solaxcloud-api.git"
-  },
-  "bugs": {
-    "url": "https://github.com/AllMightySauron/homebride-solaxcloud-api/issues"
-  },
-  "engines": {
-    "node": ">=14.18.1",
-    "homebridge": ">=1.3.8"
-  },
-  "main": "dist/index.js",
-  "scripts": {
-    "test": "mocha --require ts-node/register test/**/*.test.ts",
-    "lint": "eslint src/**.ts --max-warnings=0",
-    "watch": "npm run build && npm link && nodemon",
-    "build": "rimraf ./dist && tsc",
-    "prepublishOnly": "npm run lint && npm run build"
-  },
-  "keywords": [
-    "homebridge",
-    "homebridge-plugin",
-    "solax",
-    "qcells",
-    "solaxcloud"
-  ],
-  "dependencies": {
-    "fakegato-history": "^0.6.4",
-    "homebridge-lib": "^5.7.2",
-    "jshint": "^2.13.6",
-    "string-hash-64": "^1.0.3",
-    "sync-fetch": "^0.3.1"
-  },
-  "devDependencies": {
-    "@types/mocha": "^9.0.0",
-    "@types/node": "^16.10.9",
-    "@typescript-eslint/eslint-plugin": "^5.0.0",
-    "@typescript-eslint/parser": "^5.0.0",
-    "eslint": "^8.0.1",
-    "homebridge": "^1.7.0",
-    "mocha": "^9.2.2",
-    "nodemon": "^3.1.0",
-    "rimraf": "^3.0.2",
-    "ts-node": "^10.3.0",
-    "typescript": "^4.4.4"
-  }
-}
+{
+  "private": false,
+  "displayName": "Homebridge Solax Cloud API",
+  "name": "homebridge-solaxcloud-api",
+  "version": "2.4.1",
+  "description": "Integrates solar production info using public Solax/QCells Cloud API into Homebridge accessories.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/AllMightySauron/homebride-solaxcloud-api.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AllMightySauron/homebride-solaxcloud-api/issues"
+  },
+  "engines": {
+    "node": ">=14.18.1",
+    "homebridge": ">=1.3.8"
+  },
+  "main": "dist/index.js",
+  "scripts": {
+    "test": "mocha --exit --require ts-node/register test/**/*.test.ts",
+    "lint": "eslint src/**.ts --max-warnings=0",
+    "watch": "npm run build && npm link && nodemon",
+    "build": "rimraf ./dist && tsc",
+    "prepublishOnly": "npm run lint && npm run build"
+  },
+  "keywords": [
+    "homebridge",
+    "homebridge-plugin",
+    "solax",
+    "qcells",
+    "solaxcloud"
+  ],
+  "dependencies": {
+    "fakegato-history": "^0.6.7",
+    "homebridge-lib": "^5.7.2",
+    "jshint": "^2.13.6",
+    "string-hash-64": "^1.0.3",
+    "sync-fetch": "^0.3.1",
+    "solax-cloud-api": "^0.2.0"
+  },
+  "devDependencies": {
+    "@types/mocha": "^9.0.0",
+    "@types/node": "^16.10.9",
+    "@typescript-eslint/eslint-plugin": "^5.0.0",
+    "@typescript-eslint/parser": "^5.0.0",
+    "eslint": "^8.0.1",
+    "homebridge": "^1.7.0",
+    "mocha": "^11.0.1",
+    "nodemon": "^3.1.0",
+    "rimraf": "^3.0.2",
+    "ts-node": "^10.3.0",
+    "typescript": "^4.4.4"
+  }
+}

package/test/batteryAccessory.test.ts

@@ -0,0 +1,16 @@
+import assert = require('assert');
+
+import { BATTERY_CHARGING_STATE, SolaxBatteryAccessory } from '../src/batteryAccessory';
+import { createApi, createLog } from './helpers';
+
+describe('SolaxBatteryAccessory', () => {
+  it('keeps charge state getter in sync after updates', () => {
+    const battery = new SolaxBatteryAccessory(createLog(), createApi(), 'Battery', 'bat-test', 'Test Model');
+
+    battery.setChargeState(BATTERY_CHARGING_STATE.CHARGING);
+    assert.equal(battery.getChargeStateValue(), BATTERY_CHARGING_STATE.CHARGING);
+
+    battery.setChargeState(BATTERY_CHARGING_STATE.NOT_CHARGEABLE);
+    assert.equal(battery.getChargeStateValue(), BATTERY_CHARGING_STATE.NOT_CHARGEABLE);
+  });
+});

package/test/helpers.ts

@@ -0,0 +1,36 @@
+import { API, Logging } from 'homebridge';
+import { Characteristic, Service } from 'hap-nodejs';
+import os from 'os';
+import path from 'path';
+
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const { CharacteristicEventTypes, Formats, Perms } = require('hap-nodejs');
+
+export function createLog(): Logging {
+  const noop = () => undefined;
+
+  return Object.assign(noop, {
+    debug: noop,
+    error: noop,
+    info: noop,
+    warn: noop,
+    log: noop,
+    prefix: '',
+  }) as unknown as Logging;
+}
+
+export function createApi(): API {
+  return {
+    hap: {
+      Characteristic,
+      CharacteristicEventTypes,
+      Formats,
+      Perms,
+      Service,
+    },
+    on: () => undefined,
+    user: {
+      storagePath: () => path.join(os.tmpdir(), 'homebridge-solaxcloud-api-test'),
+    },
+  } as unknown as API;
+}

package/test/lightSensorAccessory.test.ts

@@ -0,0 +1,28 @@
+import assert = require('assert');
+
+import { SolaxLightSensorAccessory } from '../src/lightSensorAccessory';
+import { createApi, createLog } from './helpers';
+
+describe('SolaxLightSensorAccessory', () => {
+  it('stores ambient light values and applies the HomeKit minimum', () => {
+    const sensor = new SolaxLightSensorAccessory(createLog(), createApi(), 'Light sensor', 'light-1', 'Model');
+
+    sensor.setAmbientLightLevel(0);
+    sensor.getAmbientLightLevel((error, value) => {
+      assert.equal(error, null);
+      assert.equal(value, 0.1);
+    });
+
+    sensor.setAmbientLightLevel(123);
+    sensor.getAmbientLightLevel((error, value) => {
+      assert.equal(error, null);
+      assert.equal(value, 123);
+    });
+  });
+
+  it('exposes information and light services', () => {
+    const sensor = new SolaxLightSensorAccessory(createLog(), createApi(), 'Light sensor', 'light-1', 'Model');
+
+    assert.equal(sensor.getServices().length, 2);
+  });
+});

package/test/motionAccessory.test.ts

@@ -0,0 +1,36 @@
+import assert = require('assert');
+
+import { SolaxMotionAccessory } from '../src/motionAccessory';
+import { createApi, createLog } from './helpers';
+
+function sleep(millis: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, millis));
+}
+
+describe('SolaxMotionAccessory', () => {
+  it('stores motion state and clears it after the configured timeout', async () => {
+    const motion = new SolaxMotionAccessory(createLog(), createApi(), 'Motion', 'motion-1', 'Model');
+
+    motion.setMotionTimeout(0);
+    assert.equal(motion.getMotionTimeout(), 0);
+
+    motion.setState(true);
+    motion.getState((error, value) => {
+      assert.equal(error, null);
+      assert.equal(value, true);
+    });
+
+    await sleep(5);
+
+    motion.getState((error, value) => {
+      assert.equal(error, null);
+      assert.equal(value, false);
+    });
+  });
+
+  it('exposes information and motion services', () => {
+    const motion = new SolaxMotionAccessory(createLog(), createApi(), 'Motion', 'motion-1', 'Model');
+
+    assert.equal(motion.getServices().length, 2);
+  });
+});

package/test/outletAccessory.test.ts

@@ -0,0 +1,75 @@
+import assert = require('assert');
+import { SolaxOutletAccessory } from '../src/outletAccessory';
+import { createApi, createLog } from './helpers';
+
+describe('SolaxOutletAccessory', () => {
+  function withOutlet(test: (outlet: SolaxOutletAccessory) => void): void {
+    const api = createApi();
+    const outlet = new SolaxOutletAccessory(createLog(), api, 'Outlet', 'outlet-1', 'Model');
+
+    try {
+      test(outlet);
+    } finally {
+      api['globalFakeGatoTimer']?.stop();
+    }
+  }
+
+  it('stores power values, clamps negative power, and tracks power series', () => {
+    withOutlet(outlet => {
+      outlet.setPowerConsumption(-10);
+      assert.equal(outlet.getPowerConsumptionValue(), 0);
+
+      outlet.getState((error, value) => {
+        assert.equal(error, null);
+        assert.equal(value, false);
+      });
+
+      outlet.setPowerConsumption(42);
+      assert.equal(outlet.getPowerConsumptionValue(), 42);
+      assert.deepEqual(outlet.getPowerSeries(), [0, 42]);
+
+      outlet.getState((error, value) => {
+        assert.equal(error, null);
+        assert.equal(value, true);
+      });
+    });
+  });
+
+  it('stores total energy consumption', () => {
+    withOutlet(outlet => {
+      outlet.setTotalEnergyConsumption(12.5);
+      assert.equal(outlet.getTotalEnergyConsumptionValue(), 12.5);
+
+      outlet.getTotalEnergyConsumption((error, value) => {
+        assert.equal(error, null);
+        assert.equal(value, 12.5);
+      });
+    });
+  });
+
+  it('calculates smoothed power from the stored power series', () => {
+    withOutlet(outlet => {
+      outlet.setPowerConsumption(10);
+      outlet.setPowerConsumption(20);
+      outlet.setPowerConsumption(30);
+
+      assert.equal(outlet.getSmoothPowerConsumption('sma', 3), 20);
+      assert.equal(outlet.getSmoothPowerConsumption('ema', 3), 15);
+    });
+  });
+
+  it('exposes information, outlet, and history services', () => {
+    withOutlet(outlet => {
+      assert.equal(outlet.getServices().length, 3);
+    });
+  });
+
+  it('does not create history service when history is disabled', () => {
+    const outlet = new SolaxOutletAccessory(createLog(), createApi(), 'Outlet', 'outlet-1', 'Model', false);
+
+    outlet.setPowerConsumption(42);
+
+    assert.equal(outlet.getPowerConsumptionValue(), 42);
+    assert.equal(outlet.getServices().length, 2);
+  });
+});

package/test/platformAccessory.test.ts

@@ -0,0 +1,24 @@
+import assert = require('assert');
+
+import { SolaxPlatformAccessory } from '../src/platformAccessory';
+import { createApi, createLog } from './helpers';
+
+describe('SolaxPlatformAccessory', () => {
+  it('exposes normalized model and stable hashed serial information', () => {
+    const accessory = new SolaxPlatformAccessory(createLog(), createApi(), 'Base accessory', 'serial-1', 'Model / 1!');
+
+    assert.equal(accessory.getModel(), 'Model  1');
+    assert.notEqual(accessory.getSerial(), 'serial-1');
+    assert.equal(accessory.getServices().length, 1);
+  });
+
+  it('updates model and serial characteristics', () => {
+    const accessory = new SolaxPlatformAccessory(createLog(), createApi(), 'Base accessory', 'serial-1', 'Model');
+
+    accessory.setModel('Updated Model');
+    accessory.setSerial('updated-serial');
+
+    assert.equal(accessory.getModel(), 'Updated Model');
+    assert.equal(accessory.getSerial(), 'updated-serial');
+  });
+});

package/test/platformConfig.test.ts

@@ -0,0 +1,188 @@
+import { Logging, PlatformConfig } from 'homebridge';
+
+import assert = require('assert');
+
+import { SolaxCloudAPIPlatform } from '../src/platform';
+
+interface TestLog extends Logging {
+  errors: string[];
+}
+
+function createLog(): TestLog {
+  const noop = () => undefined;
+  const log = Object.assign(noop, {
+    debug: noop,
+    info: noop,
+    warn: noop,
+    log: noop,
+    prefix: '',
+    errors: [] as string[],
+    error(message: string) {
+      this.errors.push(message);
+    },
+  }) as unknown as TestLog;
+
+  return log;
+}
+
+function createConfig(pollingFrequency = 300): PlatformConfig {
+  return {
+    platform: 'SolaxCloudAPI',
+    inverters: [
+      {
+        brand: 'solax',
+        tokenId: '20200722185111234567890',
+        name: 'Test inverter',
+        sn: 'ABCDEFGHIJ',
+      },
+    ],
+    pollingFrequency,
+  };
+}
+
+function createPlatformForConfigCheck(log: Logging): SolaxCloudAPIPlatform {
+  const platform = Object.create(SolaxCloudAPIPlatform.prototype);
+
+  platform.log = log;
+
+  return platform as SolaxCloudAPIPlatform;
+}
+
+describe('SolaxCloudAPIPlatform config checks', () => {
+  [
+    {
+      name: 'missing inverters',
+      config: { platform: 'SolaxCloudAPI' } as PlatformConfig,
+      error: 'mandatory parameter "inverters"',
+    },
+    {
+      name: 'non-array inverters',
+      config: { ...createConfig(), inverters: 'invalid' },
+      error: 'Incorrect type for mandatory parameter "inverters"',
+    },
+    {
+      name: 'inverter missing mandatory fields',
+      config: { ...createConfig(), inverters: [{ brand: 'solax', name: 'Test inverter', sn: 'ABCDEFGHIJ' }] },
+      error: 'Invalid type for inverter under "inverters"',
+    },
+    {
+      name: 'null inverter entry',
+      config: { ...createConfig(), inverters: [null] },
+      error: 'Invalid type for inverter under "inverters"',
+    },
+    {
+      name: 'unsupported inverter brand',
+      config: {
+        ...createConfig(),
+        inverters: [
+          {
+            brand: 'unsupported',
+            tokenId: '20200722185111234567890',
+            name: 'Test inverter',
+            sn: 'ABCDEFGHIJ',
+          },
+        ],
+      },
+      error: 'Invalid type for inverter under "inverters"',
+    },
+    {
+      name: 'duplicate inverter names',
+      config: {
+        ...createConfig(),
+        inverters: [
+          {
+            brand: 'solax',
+            tokenId: '20200722185111234567890',
+            name: 'Test inverter',
+            sn: 'ABCDEFGHIJ',
+          },
+          {
+            brand: 'qcells',
+            tokenId: '20200722185111234567891',
+            name: 'Test inverter',
+            sn: 'KLMNOPQRST',
+          },
+        ],
+      },
+      error: 'Duplicate inverter names',
+    },
+    {
+      name: 'duplicate inverter serial numbers',
+      config: {
+        ...createConfig(),
+        inverters: [
+          {
+            brand: 'solax',
+            tokenId: '20200722185111234567890',
+            name: 'Test inverter 1',
+            sn: 'ABCDEFGHIJ',
+          },
+          {
+            brand: 'qcells',
+            tokenId: '20200722185111234567891',
+            name: 'Test inverter 2',
+            sn: 'ABCDEFGHIJ',
+          },
+        ],
+      },
+      error: 'Duplicate inverter SNs',
+    },
+  ].forEach(testCase => {
+    it(`rejects invalid config: ${testCase.name}`, () => {
+      const log = createLog();
+      const platform = createPlatformForConfigCheck(log);
+
+      assert.equal(platform['checkConfig'](testCase.config as PlatformConfig), false);
+      assert.equal(log.errors.length, 1);
+      assert.match(log.errors[0], new RegExp(testCase.error));
+    });
+  });
+
+  it('rejects polling frequencies that would produce an empty smoothing window', () => {
+    const log = createLog();
+    const platform = createPlatformForConfigCheck(log);
+    const config = createConfig(901);
+
+    assert.throws(
+      () => platform['checkConfig'](config),
+      /Polling frequency cannot be higher than 900 seconds/,
+    );
+    assert.equal(log.errors.length, 1);
+  });
+
+  it('accepts the largest polling frequency that keeps one smoothing period', () => {
+    const log = createLog();
+    const platform = createPlatformForConfigCheck(log);
+    const config = createConfig(900);
+
+    assert.equal(platform['checkConfig'](config), true);
+    assert.equal(config.pollingFrequency, 900);
+  });
+
+  it('defaults history to enabled when not configured', () => {
+    const log = createLog();
+    const platform = createPlatformForConfigCheck(log);
+    const config = createConfig();
+
+    assert.equal(platform['checkConfig'](config), true);
+    assert.equal(config.enableHistory, true);
+  });
+
+  it('keeps history disabled when configured', () => {
+    const log = createLog();
+    const platform = createPlatformForConfigCheck(log);
+    const config = { ...createConfig(), enableHistory: false };
+
+    assert.equal(platform['checkConfig'](config), true);
+    assert.equal(config.enableHistory, false);
+  });
+
+  it('defaults invalid history config to enabled', () => {
+    const log = createLog();
+    const platform = createPlatformForConfigCheck(log);
+    const config = { ...createConfig(), enableHistory: 'invalid' };
+
+    assert.equal(platform['checkConfig'](config), true);
+    assert.equal(config.enableHistory, true);
+  });
+});