feat: Mysa baseboard thermostats (#1)

.editorconfig

@@ -0,0 +1,18 @@
+# Top-most EditorConfig file
+root = true
+
+# Default settings for all files
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+max_line_length = 120
+
+# TypeScript and JavaScript files
+[*.{ts,tsx,js,jsx}]
+quote_type = single
+curly_bracket_next_line = false
+spaces_around_operators = true

.env

@@ -0,0 +1,10 @@
+# "silent" | "fatal" | "error" | "warn" | "info" | "debug" | "trace"
+MYSA_2_MQTT_LOG_LEVEL=info
+MYSA_2_MQTT_BROKER_HOST=localhost
+MYSA_2_MQTT_BROKER_PORT=1883
+
+# Set these variables in .env.local
+# MYSA_2_MQTT_USERNAME=your-mysa-username
+# MYSA_2_MQTT_PASSWORD=your-mysa-password
+# MYSA_2_MQTT_BROKER_USERNAME=mqtt-username
+# MYSA_2_MQTT_BROKER_PASSWORD=mqtt-password

.gitignore

@@ -1 +1,3 @@
 node_modules
+.env.local
+session.json

eslint.config.js

@@ -0,0 +1,23 @@
+import pluginJs from '@eslint/js';
+import jsdoc from 'eslint-plugin-jsdoc';
+import tsdoc from 'eslint-plugin-tsdoc';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+
+/** @type {import('eslint').Linter.Config[]} */
+export default [
+  { files: ['**/*.{js,mjs,cjs,ts}'] },
+  { languageOptions: { globals: globals.node } },
+  pluginJs.configs.recommended,
+  ...tseslint.configs.recommended,
+  jsdoc.configs['flat/recommended-typescript'],
+  {
+    plugins: { jsdoc },
+    rules: {
+      'jsdoc/tag-lines': 'off',
+      'jsdoc/check-tag-names': 'off',
+      'jsdoc/valid-types': 'off'
+    }
+  },
+  { plugins: { tsdoc }, rules: { 'tsdoc/syntax': 'warn' } }
+];

package.json

@@ -1,6 +1,28 @@
 {
+  "type": "module",
+  "scripts": {
+    "mysa2mqtt": "tsx src/main.ts",
+    "lint": "eslint --max-warnings 0 src/**/*.ts",
+    "style-lint": "prettier -c ."
+  },
   "dependencies": {
-    "mqtt2ha": "2.0.0",
+    "dotenv": "16.5.0",
-    "mysa-js-sdk": "1.0.0"
+    "mqtt2ha": "4.0.0",
+    "mysa-js-sdk": "1.1.0",
+    "pino": "9.7.0",
+    "pino-pretty": "13.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "9.27.0",
+    "@types/node": "22.15.21",
+    "eslint": "9.27.0",
+    "eslint-plugin-jsdoc": "50.6.17",
+    "eslint-plugin-tsdoc": "0.4.0",
+    "prettier": "3.5.3",
+    "prettier-plugin-jsdoc": "1.3.2",
+    "prettier-plugin-organize-imports": "4.1.0",
+    "tsx": "4.19.4",
+    "typescript": "5.8.3",
+    "typescript-eslint": "8.32.1"
   }
 }

prettier.config.cjs

@@ -0,0 +1,11 @@
+module.exports = {
+  tabWidth: 2,
+  useTabs: false,
+  printWidth: 120,
+  proseWrap: 'always',
+  singleQuote: true,
+  trailingComma: 'none',
+  arrowParens: 'always',
+  tsdoc: true,
+  plugins: ['prettier-plugin-organize-imports', 'prettier-plugin-jsdoc']
+};

src/main.ts

@@ -0,0 +1,81 @@
+import { configDotenv } from 'dotenv';
+import { readFile, rm, writeFile } from 'fs/promises';
+import { MysaApiClient, MysaSession } from 'mysa-js-sdk';
+import { pino } from 'pino';
+import { Thermostat } from './thermostat';
+
+configDotenv({
+  path: ['.env', '.env.local'],
+  override: true
+});
+
+const rootLogger = pino({
+  name: 'mysa2mqtt',
+  level: process.env.MYSA_2_MQTT_LOG_LEVEL,
+  transport: {
+    target: 'pino-pretty',
+    options: {
+      colorize: true,
+      singleLine: true,
+      ignore: 'hostname,module',
+      messageFormat: '\x1b[33m[{module}]\x1b[39m {msg}'
+    }
+  }
+}).child({ module: 'mysa2mqtt' });
+
+/** Mysa2mqtt entry-point. */
+async function main() {
+  rootLogger.info('Starting mysa2mqtt...');
+
+  let session: MysaSession | undefined;
+  try {
+    rootLogger.debug('Loading Mysa session...');
+    const sessionJson = await readFile('session.json', 'utf8');
+    session = JSON.parse(sessionJson);
+  } catch {
+    rootLogger.debug('No valid Mysa session file found.');
+  }
+  const client = new MysaApiClient(session, { logger: rootLogger.child({ module: 'mysa-js-sdk' }) });
+
+  client.emitter.on('sessionChanged', async (newSession) => {
+    if (newSession) {
+      rootLogger.debug('Saving new Mysa session...');
+      await writeFile('session.json', JSON.stringify(newSession));
+    } else {
+      try {
+        rootLogger.debug('Removing Mysa session file...');
+        await rm('session.json');
+      } catch {
+        // Ignore error if file does not exist
+      }
+    }
+  });
+
+  if (!client.isAuthenticated) {
+    rootLogger.info('Logging in...');
+    const username = process.env.MYSA_2_MQTT_USERNAME;
+    const password = process.env.MYSA_2_MQTT_PASSWORD;
+
+    if (!username || !password) {
+      throw new Error('Missing MYSA_2_MQTT_USERNAME or MYSA_2_MQTT_PASSWORD environment variables.');
+    }
+
+    await client.login(username, password);
+  }
+
+  const [devices, firmwares] = await Promise.all([client.getDevices(), client.getDeviceFirmwares()]);
+
+  const thermostats = Object.entries(devices.DevicesObj).map(
+    ([, device]) =>
+      new Thermostat(client, device, rootLogger.child({ module: 'thermostat' }), firmwares.Firmware[device.Id])
+  );
+
+  for (const thermostat of thermostats) {
+    await thermostat.start();
+  }
+}
+
+main().catch((error) => {
+  rootLogger.fatal(error, 'Unexpected error');
+  process.exit(1);
+});

src/thermostat.ts

@@ -0,0 +1,211 @@
+import { Climate, ClimateAction, DeviceConfiguration, Logger, MqttSettings, Sensor } from 'mqtt2ha';
+import { DeviceBase, FirmwareDevice, MysaApiClient, MysaDeviceMode, StateChange, Status } from 'mysa-js-sdk';
+
+export class Thermostat {
+  private isStarted = false;
+  private mqttSettings: MqttSettings;
+  private mqttDevice: DeviceConfiguration;
+  private mqttClimate: Climate;
+  private mqttPower: Sensor;
+
+  private readonly mysaStatusUpdateHandler = this.handleMysaStatusUpdate.bind(this);
+  private readonly mysaStateChangeHandler = this.handleMysaStateChange.bind(this);
+
+  constructor(
+    public client: MysaApiClient,
+    public device: DeviceBase,
+    private logger: Logger,
+    public deviceFirmware?: FirmwareDevice
+  ) {
+    this.mqttSettings = {
+      host: process.env.MYSA_2_MQTT_BROKER_HOST || 'localhost',
+      port: parseInt(process.env.MYSA_2_MQTT_BROKER_PORT || '1883'),
+      username: process.env.MYSA_2_MQTT_BROKER_USERNAME,
+      password: process.env.MYSA_2_MQTT_BROKER_PASSWORD,
+      client_name: 'mysa2mqtt',
+      state_prefix: 'mysa2mqtt'
+    };
+
+    this.mqttDevice = {
+      identifiers: device.Id,
+      name: device.Name,
+      manufacturer: 'Mysa',
+      model: device.Model,
+      sw_version: deviceFirmware?.InstalledVersion
+    };
+
+    this.mqttClimate = new Climate(
+      {
+        mqtt: this.mqttSettings,
+        logger: this.logger,
+        component: {
+          component: 'climate',
+          device: this.mqttDevice,
+          unique_id: `mysa_${device.Id}_climate`,
+          name: 'Thermostat',
+          min_temp: device.MinSetpoint,
+          max_temp: device.MaxSetpoint,
+          modes: ['off', 'heat'], // TODO: AC
+          precision: 0.1,
+          temp_step: 0.5,
+          temperature_unit: 'C', // TODO: Confirm that Mysa always works in C
+          optimistic: true
+        }
+      },
+      [
+        'action_topic',
+        'current_humidity_topic',
+        'current_temperature_topic',
+        'mode_state_topic',
+        'temperature_state_topic'
+      ],
+      async () => {},
+      ['mode_command_topic', 'power_command_topic', 'temperature_command_topic'],
+      async (topic, message) => {
+        switch (topic) {
+          case 'mode_command_topic':
+            this.client.setDeviceState(
+              this.device.Id,
+              undefined,
+              message === 'off' ? 'off' : message === 'heat' ? 'heat' : undefined
+            );
+            break;
+
+          case 'power_command_topic':
+            this.client.setDeviceState(
+              this.device.Id,
+              undefined,
+              message === 'OFF' ? 'off' : message === 'ON' ? 'heat' : undefined
+            );
+            break;
+
+          case 'temperature_command_topic':
+            if (message === '') {
+              this.client.setDeviceState(this.device.Id, undefined, undefined);
+            } else {
+              this.client.setDeviceState(this.device.Id, parseFloat(message), undefined);
+            }
+            break;
+        }
+      }
+    );
+
+    this.mqttPower = new Sensor({
+      mqtt: this.mqttSettings,
+      logger: this.logger,
+      component: {
+        component: 'sensor',
+        device: this.mqttDevice,
+        unique_id: `mysa_${device.Id}_power`,
+        device_class: 'power',
+        state_class: 'measurement',
+        unit_of_measurement: 'W',
+        suggested_display_precision: 0,
+        force_update: true
+      }
+    });
+  }
+
+  async start() {
+    if (this.isStarted) {
+      return;
+    }
+
+    this.isStarted = true;
+
+    try {
+      const deviceStates = await this.client.getDeviceStates();
+      const state = deviceStates.DeviceStatesObj[this.device.Id];
+
+      this.mqttClimate.currentTemperature = state.CorrectedTemp.v;
+      this.mqttClimate.currentHumidity = state.Humidity.v;
+      this.mqttClimate.currentMode = state.TstatMode.v === 1 ? 'off' : state.TstatMode.v === 3 ? 'heat' : undefined;
+      this.mqttClimate.currentAction = this.computeCurrentAction(undefined, state.Duty.v);
+      this.mqttClimate.targetTemperature = this.mqttClimate.currentMode !== 'off' ? state.SetPoint.v : undefined;
+
+      await this.mqttClimate.writeConfig();
+
+      // `state.Current.v` always has a non-zero value, even for thermostats that are off, so we can't use it to determine initial power state.
+      await this.mqttPower.setState('state_topic', 'None');
+      await this.mqttPower.writeConfig();
+
+      this.client.emitter.on('statusChanged', this.mysaStatusUpdateHandler);
+      this.client.emitter.on('stateChanged', this.mysaStateChangeHandler);
+
+      await this.client.startRealtimeUpdates(this.device.Id);
+    } catch (error) {
+      this.isStarted = false;
+      throw error;
+    }
+  }
+
+  async stop() {
+    if (!this.isStarted) {
+      return;
+    }
+
+    this.isStarted = false;
+
+    await this.client.stopRealtimeUpdates(this.device.Id);
+
+    this.client.emitter.off('statusChanged', this.mysaStatusUpdateHandler);
+    this.client.emitter.off('stateChanged', this.mysaStateChangeHandler);
+
+    await this.mqttPower.setState('state_topic', 'None');
+  }
+
+  private async handleMysaStatusUpdate(status: Status) {
+    if (!this.isStarted || status.deviceId !== this.device.Id) {
+      return;
+    }
+
+    this.mqttClimate.currentAction = this.computeCurrentAction(status.current, status.dutyCycle);
+    this.mqttClimate.currentTemperature = status.temperature;
+    this.mqttClimate.currentHumidity = status.humidity;
+    this.mqttClimate.targetTemperature = this.mqttClimate.currentMode !== 'off' ? status.setPoint : undefined;
+
+    if (status.current != null) {
+      const watts = this.device.Voltage * status.current;
+      await this.mqttPower.setState('state_topic', watts.toFixed(2));
+    } else {
+      await this.mqttPower.setState('state_topic', 'None');
+    }
+  }
+
+  private async handleMysaStateChange(state: StateChange) {
+    if (!this.isStarted || state.deviceId !== this.device.Id) {
+      return;
+    }
+
+    switch (state.mode) {
+      case 'off':
+        this.mqttClimate.currentMode = 'off';
+        this.mqttClimate.currentAction = 'off';
+        this.mqttClimate.targetTemperature = undefined;
+        break;
+
+      case 'heat':
+        this.mqttClimate.currentMode = 'heat';
+        break;
+    }
+  }
+
+  private computeCurrentAction(current?: number, dutyCycle?: number): ClimateAction {
+    const mode: MysaDeviceMode | undefined =
+      this.mqttClimate.currentMode === 'heat' ? 'heat' : this.mqttClimate.currentMode === 'off' ? 'off' : undefined;
+
+    switch (mode) {
+      case 'off':
+        return 'off';
+
+      case 'heat':
+        if (current != null) {
+          return current > 0 ? 'heating' : 'idle';
+        }
+        return (dutyCycle ?? 0) > 0 ? 'heating' : 'idle';
+
+      default:
+        return 'idle';
+    }
+  }
+}

tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "esModuleInterop": true,
+    "moduleResolution": "node",
+    "skipLibCheck": true,
+    "allowJs": false,
+    "strict": true,
+    "noEmit": true,
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules"]
+}