@mgurreta/homebridge-molekule 1.2.4

package/eslint.config.js

@@ -0,0 +1,45 @@
+const js = require('@eslint/js');
+const tseslint = require('@typescript-eslint/eslint-plugin');
+const tsparser = require('@typescript-eslint/parser');
+
+module.exports = [
+  js.configs.recommended,
+  {
+    files: ['**/*.ts'],
+    languageOptions: {
+      parser: tsparser,
+      parserOptions: {
+        ecmaVersion: 'latest',
+        sourceType: 'module',
+        project: './tsconfig.json',
+      },
+      globals: {
+        // Node.js globals
+        process: 'readonly',
+        __dirname: 'readonly',
+        __filename: 'readonly',
+        Buffer: 'readonly',
+        console: 'readonly',
+        global: 'readonly',
+        module: 'readonly',
+        require: 'readonly',
+        exports: 'readonly',
+        setInterval: 'readonly',
+        clearInterval: 'readonly',
+        setTimeout: 'readonly',
+        clearTimeout: 'readonly',
+        // Web APIs available in Node.js
+        fetch: 'readonly',
+        Response: 'readonly',
+        Request: 'readonly',
+      },
+    },
+    plugins: {
+      '@typescript-eslint': tseslint,
+    },
+    rules: {
+      ...tseslint.configs.recommended.rules,
+      '@typescript-eslint/no-non-null-assertion': 'off',
+    },
+  },
+];

package/package.json

@@ -0,0 +1,45 @@
+{
+  "private": false,
+  "displayName": "Homebridge Molekule",
+  "name": "@mgurreta/homebridge-molekule",
+  "version": "1.2.4",
+  "description": "A Plugin for Molekule Air Purifiers for use with Homebridge.",
+  "license": "Unlicense",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:mgurreta/homebridge-molekule.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mgurreta/homebridge-molekule/issues"
+  },
+  "engines": {
+    "node": "^18.20.4 || ^20.15.1 || ^22",
+    "homebridge": "^1.6.0 || ^2.0.0-beta.0"
+  },
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "scripts": {
+    "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-plugin"
+  ],
+  "dependencies": {
+    "amazon-cognito-identity-js": "^6.3.16"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.3.0",
+    "@typescript-eslint/eslint-plugin": "^8.56.0",
+    "@typescript-eslint/parser": "^8.56.0",
+    "eslint": "^10.0.1",
+    "homebridge": "^1.8.0 || ^2.0.0-beta.0",
+    "nodemon": "^3.1.14",
+    "rimraf": "^6.1.3",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  }
+}

package/src/cognito.ts

@@ -0,0 +1,145 @@
+import {
+  AuthenticationDetails,
+  CognitoRefreshToken,
+  CognitoUser,
+  CognitoUserPool,
+} from 'amazon-cognito-identity-js';
+import { Logger, PlatformConfig } from 'homebridge';
+
+let token = '';
+let refreshToken: CognitoRefreshToken;
+let authError: boolean;
+// Molekule API settings
+const ClientId = '1ec4fa3oriciupg94ugoi84kkk';
+const PoolId = 'us-west-2_KqrEZKC6r';
+const url = 'https://api.molekule.com/users/me/devices/';
+
+export class HttpAJAX {
+  private readonly log: Logger;
+  email: string;
+  pass: string;
+  authenticationData;
+  userData;
+  userPool;
+  authenticationDetails;
+  cognitoUser;
+  userPoolData;
+  constructor(log: Logger, config: PlatformConfig) {
+    this.log = log;
+    this.email = config.email;
+    this.pass = config.password;
+    this.authenticationData = {
+      Username: this.email,
+      Password: this.pass,
+    };
+    this.userPoolData = {
+      UserPoolId: PoolId,
+      ClientId,
+    };
+    this.userPool = new CognitoUserPool(this.userPoolData);
+    this.userData = {
+      Username: this.email,
+      Pool: this.userPool,
+    };
+    this.authenticationDetails = new AuthenticationDetails(
+      this.authenticationData
+    );
+    this.cognitoUser = new CognitoUser(this.userData);
+  }
+  refreshAuthToken() {
+    return new Promise((resolve, reject) =>
+      this.cognitoUser.refreshSession(refreshToken, (err, session) => {
+        if (err) {
+          this.log.info(
+            'Auth token fetch using refresh token failed. Fallback to username/password'
+          );
+          this.log.debug(err);
+          reject(err);
+        } else {
+          this.log.info('✓ Token refresh successful');
+          authError = false;
+          token = session.getAccessToken().getJwtToken();
+          resolve(session);
+        }
+      })
+    );
+  }
+  initiateAuth() {
+    this.log.debug('email: ' + this.email);
+    this.log.debug('password: ' + this.pass);
+    return new Promise((resolve, reject) =>
+      this.cognitoUser.authenticateUser(this.authenticationDetails, {
+        onSuccess: (result) => {
+          token = result.getAccessToken().getJwtToken();
+          refreshToken = result.getRefreshToken();
+          this.log.info('✓ Valid Login Credentials');
+          authError = false;
+          resolve(result.getAccessToken().getJwtToken());
+        },
+        onFailure: (err) => {
+          this.log.error(
+            'API Authentication Failure, possibly a password/username error.'
+          );
+          reject(err);
+        },
+      })
+    );
+  }
+  async httpCall(
+    method: string,
+    extraUrl: string,
+    send: string,
+    retry: number
+  ): Promise<Response> {
+    let response: Response;
+    if (authError)
+      await this.refreshAuthToken().catch((e) => {
+        this.initiateAuth().catch((e) => {
+          this.log.error(e);
+          return;
+        });
+        this.log.debug(e);
+      });
+    if (token === '' || authError)
+      await this.initiateAuth().catch((err) => {
+        this.log.error(err);
+        return;
+      });
+    if (method === 'GET') {
+      const contents = {
+        method,
+        headers: {
+          authorization: token,
+          'x-api-version': '1.0',
+          'content-type': 'application/json',
+        },
+      };
+      response = await fetch(url + extraUrl, contents);
+      this.log.debug('HTTP GET STATUS: ' + response.status);
+      this.log.debug('HTTP GET CONTENTS: ' + JSON.stringify(response));
+      if (response.status === 401 && retry > 0) {
+        authError = true;
+        return await this.httpCall(method, extraUrl, send, retry - 1);
+      } else return response;
+    } else {
+      const contents = {
+        method,
+        body: send,
+        headers: {
+          authorization: token,
+          'x-api-version': '1.0',
+          'content-type': 'application/json',
+        },
+      };
+      response = await fetch(url + extraUrl, contents);
+      this.log.debug(
+        'HTTP POST STATUS: ' + response.status + ' With contents: ' + send
+      );
+      if (response.status === 401 && retry > 0) {
+        authError = true;
+        return await this.httpCall(method, extraUrl, send, retry - 1);
+      }
+    }
+    return response;
+  }
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+import { API } from 'homebridge'
+
+import { PLATFORM_NAME } from './settings'
+import { MolekuleHomebridgePlatform } from './platform'
+
+/**
+ * This method registers the platform with Homebridge
+ */
+export = (api: API) => {
+  api.registerPlatform(PLATFORM_NAME, MolekuleHomebridgePlatform)
+};

package/src/platform.ts

@@ -0,0 +1,119 @@
+import { API, DynamicPlatformPlugin, Logger, PlatformAccessory, PlatformConfig, Service, Characteristic } from 'homebridge'
+import { PLATFORM_NAME, PLUGIN_NAME } from './settings'
+import { MolekulePlatformAccessory } from './platformAccessory'
+import { HttpAJAX } from './cognito'
+interface deviceData {
+  name: string
+  serialNumber: string
+}
+let intervalID: ReturnType<typeof setInterval>
+const refreshInterval = 60 //token refresh interval in minutes
+/**
+ * HomebridgePlatform
+ * This class is the main constructor for your plugin, this is where you should
+ * parse the user config and discover/register accessories with Homebridge.
+ */
+export class MolekuleHomebridgePlatform implements DynamicPlatformPlugin {
+  public readonly Service: typeof Service
+  public readonly Characteristic: typeof Characteristic
+
+  // this is used to track restored cached accessories
+  public readonly accessories: PlatformAccessory[] = []
+
+  constructor (
+    public readonly log: Logger,
+    public readonly config: PlatformConfig,
+    public readonly api: API,
+    private caller = new HttpAJAX(log, config),
+  ) {
+    this.Service = this.api.hap.Service
+    this.Characteristic = this.api.hap.Characteristic
+    // When this event is fired it means Homebridge has restored all cached accessories from disk.
+    // Dynamic Platform plugins should only register new accessories after this event was fired,
+    // in order to ensure they weren't added to homebridge already. This event can also be used
+    // to start discovery of new accessories.
+    this.api.on('didFinishLaunching', () => {
+      log.debug('Executed didFinishLaunching callback')
+      // run the method to discover / register your devices as accessories
+      this.discoverDevices()
+      if (!intervalID) intervalID = setInterval(() => this.caller.refreshAuthToken(), refreshInterval*60*1000)
+    })
+    this.log.debug('Finished initializing platform ', PLATFORM_NAME)
+  }
+
+  /**
+   * This function is invoked when homebridge restores cached accessories from disk at startup.
+   * It should be used to setup event handlers for characteristics and update respective values.
+   */
+
+  configureAccessory (accessory: PlatformAccessory) {
+    this.log.info('Loading accessory from cache:', accessory.displayName)
+
+    // add the restored accessory to the accessories cache so we can track if it has already been registered
+    this.accessories.push(accessory)
+  }
+
+  /**
+   * This is an example method showing how to register discovered accessories.
+   * Accessories must only be registered once, previously created accessories
+   * must not be registered again to prevent "duplicate UUID" errors.
+   */
+  async discoverDevices () {
+    this.log.debug('Discover Devices Called')
+    const response = this.caller.httpCall('GET', '', '', 1);
+    const devices = await (await response).json() as { content: deviceData[] };
+    // loop over the discovered devices and register each one if it has not already been registered
+    if ((await response).status !== 200) 
+    {
+      this.log.error('Fatal error, discover devices failed. Try running homebridge in debug mode to see HTTP status code.')
+      return; //prevent crashes
+    }
+    devices.content.forEach((device : deviceData) => {
+      // generate a unique id for the accessory this should be generated from
+      // something globally unique, but constant, for example, the device serial
+      // number or MAC address
+      this.log.debug('found device from API: ' + JSON.stringify(device))
+      const uuid = this.api.hap.uuid.generate(device.serialNumber)
+
+      // see if an accessory with the same uuid has already been registered and restored from
+      // the cached devices we stored in the `configureAccessory` method above
+      const existingAccessory = this.accessories.find(accessory => accessory.UUID === uuid)
+
+      if (existingAccessory) {
+        // the accessory already exists
+        this.log.info('Restoring existing accessory from cache:', existingAccessory.displayName)
+
+        // if you need to update the accessory.context then you should run `api.updatePlatformAccessories`. eg.:
+        // existingAccessory.context.device = device;
+        // this.api.updatePlatformAccessories([existingAccessory]);
+
+        // create the accessory handler for the restored accessory
+        // this is imported from `platformAccessory.ts`
+        new MolekulePlatformAccessory(this, existingAccessory, this.config, this.log)
+
+        // it is possible to remove platform accessories at any time using `api.unregisterPlatformAccessories`, eg.:
+        // remove platform accessories when no longer present
+        // this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [existingAccessory]);
+        // this.log.info('Removing existing accessory from cache:', existingAccessory.displayName);
+      } else {
+        // the accessory does not yet exist, so we need to create it
+        this.log.info('Adding new accessory:', device.name)
+
+        // create a new accessory
+        const accessory = new this.api.platformAccessory(device.name, uuid)
+
+        // store a copy of the device object in the `accessory.context`
+        // the `context` property can be used to store any data about the accessory you may need
+        accessory.context.device = device
+
+        // create the accessory handler for the newly create accessory
+        // this is imported from `platformAccessory.ts`
+        new MolekulePlatformAccessory(this, accessory, this.config, this.log)
+
+        // link the accessory to your platform
+        this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [accessory])
+      }
+    }
+    )
+  }
+}

package/src/platformAccessory.ts

@@ -0,0 +1,299 @@
+import {
+  Service,
+  PlatformAccessory,
+  CharacteristicValue,
+  Logger,
+  PlatformConfig,
+} from 'homebridge';
+import { HttpAJAX } from './cognito';
+import { MolekuleHomebridgePlatform } from './platform';
+
+/**
+ * Platform Accessory
+ * An instance of this class is created for each accessory your platform registers
+ * Each accessory may expose multiple services of different service types.
+ */
+export class MolekulePlatformAccessory {
+  private service: Service;
+  /**
+   * These are just used to create a working example
+   * You should implement your own code to track the state of your accessory
+   */
+  private state = {
+    state: 0,
+    Speed: 0,
+    Filter: 100,
+    On: 0,
+    Auto: 0,
+  };
+
+  constructor(
+    private readonly platform: MolekuleHomebridgePlatform,
+    private readonly accessory: PlatformAccessory,
+    private readonly config: PlatformConfig,
+    private readonly log: Logger
+  ) {
+    this.caller = new HttpAJAX(this.log, this.config);
+
+    // set accessory information
+    this.accessory
+      .getService(this.platform.Service.AccessoryInformation)!
+      .setCharacteristic(this.platform.Characteristic.Manufacturer, 'Molekule')
+      .setCharacteristic(
+        this.platform.Characteristic.Model,
+        accessory.context.device.model
+      )
+      .setCharacteristic(
+        this.platform.Characteristic.SerialNumber,
+        accessory.context.device.serialNumber
+      )
+      .setCharacteristic(
+        this.platform.Characteristic.FirmwareRevision,
+        accessory.context.device.firmwareVersion
+      );
+
+    // get the AirPurifier service if it exists, otherwise create a new AirPurifier service
+    // you can create multiple services for each accessory
+    this.service =
+      this.accessory.getService(this.platform.Service.AirPurifier) ||
+      this.accessory.addService(this.platform.Service.AirPurifier);
+    // set the service name, this is what is displayed as the default name on the Home app
+    // in this example we are using the name we stored in the `accessory.context` in the `discoverDevices` method.
+    this.service.setCharacteristic(
+      this.platform.Characteristic.Name,
+      accessory.context.device.name
+    );
+    // each service must implement at-minimum the "required characteristics" for the given service type
+    // see https://developers.homebridge.io/#/service/AirPurifier
+
+    // register handlers for the On/Off Characteristic
+    this.service
+      .getCharacteristic(this.platform.Characteristic.Active)
+      .onSet(this.handleActiveSet.bind(this)) // SET - bind to the `handleActiveSet` method below
+      .onGet(this.handleActiveGet.bind(this)); // GET - bind to the `handleActiveGet` method below
+    // register handlers for the CurrentAirPurifierState Characteristic
+    this.service
+      .getCharacteristic(this.platform.Characteristic.CurrentAirPurifierState)
+      .onGet(this.getState.bind(this)); // GET - bind to the `getState` method below
+    // register handlers for the TargetAirPurifierState Characteristic
+    this.service
+      .getCharacteristic(this.platform.Characteristic.TargetAirPurifierState)
+      .onSet(this.handleAutoSet.bind(this))
+      .onGet(this.handleAutoGet.bind(this));
+    this.service
+      .getCharacteristic(this.platform.Characteristic.RotationSpeed)
+      .onSet(this.setSpeed.bind(this))
+      .onGet(this.getSpeed.bind(this));
+
+    this.service
+      .getCharacteristic(this.platform.Characteristic.FilterChangeIndication)
+      .onGet(this.getFilterChange.bind(this));
+    this.service
+      .getCharacteristic(this.platform.Characteristic.FilterLifeLevel)
+      .onGet(this.getFilterStatus.bind(this));
+    /**
+     * Creating multiple services of the same type.
+     *
+     * To avoid "Cannot add a Service with the same UUID another Service without also defining a unique 'subtype' property." error,
+     * when creating multiple services of the same type, you need to use the following syntax to specify a name and subtype id:
+     * this.accessory.getService('NAME') || this.accessory.addService(this.platform.Service.Lightbulb, 'NAME', 'USER_DEFINED_SUBTYPE_ID');
+     *
+     * The USER_DEFINED_SUBTYPE must be unique to the platform accessory (if you platform exposes multiple accessories, each accessory
+     * can use the same sub type id.)
+     */
+  }
+
+  private caller: HttpAJAX;
+  /**
+   * Handle "SET" requests from HomeKit
+   * These are sent when the user changes the state of an accessory, for example, turning on a Light bulb.
+   */
+  async handleActiveSet(value: CharacteristicValue) {
+    // implement your own code to turn your device on/off
+    let data = '"on"}';
+    if (!value) data = '"off"}';
+    const response = await this.caller.httpCall(
+      'POST',
+      this.accessory.context.device.serialNumber + '/actions/set-power-status',
+      '{"status":' + data,
+      1
+    );
+    if (response.status === 204) {
+      this.service.updateCharacteristic(
+        this.platform.Characteristic.Active,
+        value
+      );
+      if (value) {
+        this.service.updateCharacteristic(
+          this.platform.Characteristic.CurrentAirPurifierState,
+          2
+        );
+        this.state.state = 2;
+        this.state.On = 1;
+      } else {
+        this.service.updateCharacteristic(
+          this.platform.Characteristic.CurrentAirPurifierState,
+          0
+        );
+        this.state.On = 0;
+      }
+    }
+    this.platform.log.info(
+      'Attempted to set: ' +
+        value +
+        ' state on device: ' +
+        this.accessory.context.device.name +
+        ' Server Reply: ' +
+        JSON.stringify(response)
+    );
+  }
+
+  /**
+   * Handle the "GET" requests from HomeKit
+   * These are sent when HomeKit wants to know the current state of the accessory, for example, checking if a Light bulb is on.
+   *
+   * GET requests should return as fast as possbile. A long delay here will result in
+   * HomeKit being unresponsive and a bad user experience() in general.
+   *
+   * If your device takes time to respond you should update the status of your device
+   * asynchronously instead using the `updateCharacteristic` method instead.
+   * @example
+   * this.service.updateCharacteristic(this.platform.Characteristic.On, true)
+   */
+  async handleActiveGet(): Promise<CharacteristicValue> {
+    if ((await this.updateStates()) === 1)
+      throw new this.platform.api.hap.HapStatusError(
+        this.platform.api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE
+      );
+    this.log.info(
+      this.accessory.context.device.name + ' state is: ' + this.state.On
+    );
+    return this.state.On;
+    // if you need to return an error to show the device as "Not Responding" in the Home app:
+    // throw new this.platform.api.hap.HapStatusError(this.platform.api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE);
+  }
+
+  async getState(): Promise<CharacteristicValue> {
+    return this.state.state;
+  }
+
+  async handleAutoSet(value: CharacteristicValue) {
+    try {
+      if (value === 1) {
+        await this.setSpeed((100 / 3) * 2);
+      }
+    } catch {
+      throw new this.platform.api.hap.HapStatusError(
+        this.platform.api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE
+      );
+    }
+
+    this.service.updateCharacteristic(
+      this.platform.Characteristic.TargetAirPurifierState,
+      value
+    );
+  }
+
+  async handleAutoGet() {
+    if ((await this.updateStates()) === 1)
+      throw new this.platform.api.hap.HapStatusError(
+        this.platform.api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE
+      );
+    return this.state.Auto;
+  }
+
+  /**
+   * Handle "SET" requests from HomeKit
+   * These are sent when the user changes the state of an accessory, for example, changing the speed
+   */
+  async setSpeed(value: CharacteristicValue) {
+    const clamp = Math.round(
+      Math.min(Math.max((value as number) / 33.33333333, 1), 3)
+    );
+
+    const setFanSpeedRequest = await this.caller.httpCall(
+      'POST',
+      this.accessory.context.device.serialNumber + '/actions/set-fan-speed',
+      '{"fanSpeed": ' + clamp + '}',
+      1
+    );
+
+    if (setFanSpeedRequest.status === 204) {
+      this.state.Speed = clamp * 33.33333333;
+      this.state.Auto = clamp === 2 ? 1 : 0;
+    }
+
+    this.platform.log.info(
+      this.accessory.context.device.name + ' set speed -> ',
+      '{"fanSpeed":' + clamp + '}'
+    );
+    this.service.updateCharacteristic(
+      this.platform.Characteristic.RotationSpeed,
+      this.state.Speed
+    );
+    this.service.updateCharacteristic(
+      this.platform.Characteristic.TargetAirPurifierState,
+      this.state.Auto
+    );
+  }
+
+  async getSpeed(): Promise<CharacteristicValue> {
+    return this.state.Speed;
+  }
+
+  async getFilterChange(): Promise<CharacteristicValue> {
+    if (this.state.Filter > this.config.threshold) return 0;
+    else return 1;
+  }
+
+  async getFilterStatus(): Promise<CharacteristicValue> {
+    this.log.debug('Check Filter State: ' + this.state.Filter);
+    return this.state.Filter;
+  }
+
+  async updateStates() {
+    const re = await this.caller.httpCall('GET', '', '', 1);
+    const response = await re.json() as { content: { serialNumber: string; fanspeed: string; pecoFilter: number; online: string; mode: string }[] } | null;
+    if (!response) return 1;
+    for (let i = 0; i < Object.keys(response.content).length; i++) {
+      if (
+        response.content[i].serialNumber ===
+        this.accessory.context.device.serialNumber
+      ) {
+        this.platform.log.info('Get Speed ->', response.content[i].fanspeed);
+
+        this.state.Speed = Number(response.content[i].fanspeed) * 33.33333333;
+        this.state.Filter = response.content[i].pecoFilter;
+        this.state.Auto = response.content[i].fanspeed === '2' ? 1 : 0;
+
+        if (response.content[i].online === 'false') {
+          this.log.error(
+            this.accessory.context.device.name +
+              ' was reported to be offline by the Molekule API.'
+          );
+          return 1;
+        }
+        if (response.content[i].mode !== 'off') {
+          this.state.On = 1;
+          this.state.state = 2;
+        } else {
+          this.state.On = 0;
+          this.state.state = 0;
+        }
+      }
+    }
+    this.service.updateCharacteristic(
+      this.platform.Characteristic.RotationSpeed,
+      this.state.Speed
+    );
+    this.service.updateCharacteristic(
+      this.platform.Characteristic.CurrentAirPurifierState,
+      this.state.state
+    );
+    this.service.updateCharacteristic(
+      this.platform.Characteristic.Active,
+      this.state.On
+    );
+    return 0;
+  }
+}

package/src/settings.ts

@@ -0,0 +1,9 @@
+/**
+ * This is the name of the platform that users will use to register the plugin in the Homebridge config.json
+ */
+export const PLATFORM_NAME = 'Molekule'
+
+/**
+  * This must match the name of your plugin as defined the package.json
+  */
+export const PLUGIN_NAME = '@mgurreta/homebridge-molekule'

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "node16",
+    "lib": ["ES2022"],
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "sourceMap": true,
+    "rootDir": "src",
+    "outDir": "dist",
+    "noImplicitAny": false
+  },
+  "include": ["src"]
+}