homebridge-tekmar 0.1.0

package/CLAUDE.md

@@ -0,0 +1,50 @@
+# CLAUDE.md
+
+## Project Overview
+
+Homebridge dynamic platform plugin for Tekmar tN4 WiFi thermostats (models 561-564) controlled via the Watts Home cloud API.
+
+## Architecture
+
+- **TypeScript** dynamic platform plugin (ES2022, nodenext modules)
+- **No runtime dependencies** — uses Node 20+ native `fetch`
+- **Polling architecture** — platform polls API on interval, pushes updates via `updateCharacteristic()`. GET handlers return cached data instantly to prevent HomeKit "Not Responding" errors.
+- **Heat-only** — Tekmar 561 is heating-only. TargetHeatingCoolingState: OFF, HEAT, AUTO (schedule).
+
+## Key Files
+
+- `src/index.ts` — Entry point, registers platform
+- `src/settings.ts` — API constants (Azure B2C URLs, client IDs)
+- `src/platform.ts` — DynamicPlatformPlugin: discovery, polling, accessory lifecycle
+- `src/platformAccessory.ts` — HomeKit Thermostat service characteristics
+- `src/api/types.ts` — TypeScript interfaces for API responses
+- `src/api/wattsApi.ts` — API client: Azure B2C auth, REST calls, temp conversion
+
+## API Details
+
+- **API Base**: `https://home.watts.com/api`
+- **Auth**: Azure AD B2C PKCE OAuth2 at `login.watts.io`
+- **Temperatures**: Plain integers in Fahrenheit from the API; HomeKit uses Celsius internally
+- **Modes**: String values `"Heat"` / `"Off"` (not integer codes)
+- **Control**: `PATCH /api/Device/{id}` with `{"Settings":{...}}`
+
+## Build & Test
+
+```bash
+npm install     # Install dev dependencies
+npm run build   # Compile TypeScript to dist/
+npm run watch   # Compile with file watcher
+npm run dev     # nodemon auto-restart
+```
+
+### Standalone auth test:
+```bash
+WATTS_USERNAME="you@email.com" WATTS_PASSWORD="yourpass" npx tsx test-auth.ts
+```
+
+## Important Notes
+
+- Azure B2C `tx` query parameter must have literal `StateProperties=` (not URL-encoded `%3D`)
+- B2C SelfAsserted endpoint returns HTTP 200 with error in JSON body `{"status":"400",...}`
+- Auth flow requires manual redirect following with cookie jar accumulation
+- `URLSearchParams` over-encodes some characters for B2C — query strings for SelfAsserted/confirmed are built manually

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Schmelkin
+
+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,176 @@
+# homebridge-tekmar
+
+[![npm version](https://badge.fury.io/js/homebridge-tekmar.svg)](https://badge.fury.io/js/homebridge-tekmar)
+[![npm downloads](https://img.shields.io/npm/dt/homebridge-tekmar.svg)](https://www.npmjs.com/package/homebridge-tekmar)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A [Homebridge](https://homebridge.io) plugin for [Tekmar](https://www.watts.com/products/heating-cooling-comfort/smart-home/thermostats) tN4 WiFi thermostats (561/562/563/564). Control your Tekmar radiant floor heating thermostat through Apple HomeKit via the Watts Home cloud API.
+
+## Features
+
+- **Current Temperature** — Room, floor, and outdoor sensor readings
+- **Target Temperature** — Set your heating setpoint from the Home app or Siri
+- **Mode Control** — Off, Heat, and Auto (scheduled program) modes
+- **Automatic Polling** — Keeps HomeKit in sync with your thermostat state
+- **Easy Configuration** — Set up through Homebridge Config UI X
+- **No Runtime Dependencies** — Uses Node.js native `fetch`, no extra packages needed
+- **Child Bridge Support** — Run as an isolated child bridge for stability
+
+## Supported Hardware
+
+| Model | Name | Type |
+|-------|------|------|
+| 561 | tN4 Smart Thermostat | WiFi radiant floor heating |
+| 562 | tN4 Smart Thermostat | WiFi radiant floor heating |
+| 563 | tN4 Smart Thermostat | WiFi radiant floor heating |
+| 564 | tN4 Smart Thermostat | WiFi radiant floor heating |
+
+These thermostats are controlled via the **Watts Home** mobile app ([iOS](https://apps.apple.com/app/watts-home/id1452498498) / [Android](https://play.google.com/store/apps/details?id=com.watts.mobileapp)). You must have a Watts Home account with your thermostat(s) configured before using this plugin.
+
+## Installation
+
+### Option 1: Via Homebridge Config UI X (Recommended)
+
+1. Search for `homebridge-tekmar` in the Homebridge Config UI X plugins tab
+2. Click **Install**
+3. Configure with your Watts Home account credentials
+
+### Option 2: Via npm
+
+```bash
+npm install -g homebridge-tekmar
+```
+
+## Configuration
+
+Configure the plugin through the Homebridge Config UI X interface, or manually edit your `config.json`:
+
+```json
+{
+  "platforms": [
+    {
+      "platform": "TekmarThermostat",
+      "name": "Tekmar Thermostat",
+      "username": "your@email.com",
+      "password": "your-password"
+    }
+  ]
+}
+```
+
+### Configuration Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `username` | *required* | Your Watts Home app email address |
+| `password` | *required* | Your Watts Home app password |
+| `pollingInterval` | `60` | Polling interval in seconds (10-300) |
+| `temperatureUnit` | `fahrenheit` | Display unit: `fahrenheit` or `celsius` |
+
+## How It Works
+
+1. Authenticates with the Watts Home cloud API (Azure AD B2C OAuth2)
+2. Discovers all Tekmar thermostats across your locations
+3. Exposes each thermostat as a HomeKit Thermostat accessory
+4. Polls the API at a configurable interval to keep state in sync
+5. SET commands (temperature, mode) are sent immediately to the API
+
+### HomeKit Mode Mapping
+
+The Tekmar 561 is a **heat-only** thermostat. HomeKit modes are mapped as:
+
+| HomeKit Mode | Tekmar Behavior |
+|-------------|-----------------|
+| **Off** | Thermostat off |
+| **Heat** | Manual heating to target temperature |
+| **Auto** | Scheduled program mode enabled |
+
+> **Note:** Cool mode is not available — the Tekmar tN4 series does not support cooling.
+
+## Supported Features
+
+- Set and read target temperature
+- Read current room temperature
+- Switch between Off / Heat / Auto modes
+- Current heating state (actively heating or idle)
+- Temperature display unit preference
+- Multiple thermostats across multiple locations
+
+## Known Limitations
+
+- **Cloud API only** — Requires internet connectivity (no local control)
+- **Heat only** — No cooling support (hardware limitation)
+- **No humidity sensor** — The thermostat does not report humidity
+- **Floor/outdoor temps** — Floor and outdoor sensor readings are fetched but not yet exposed as separate HomeKit sensors
+
+## Development
+
+### Local Development
+
+```bash
+# Clone the repository
+git clone https://github.com/apumapho/homebridge-tekmar.git
+cd homebridge-tekmar
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Link for local testing
+npm link
+
+# Run Homebridge in debug mode
+homebridge -D
+```
+
+### Standalone API Test
+
+```bash
+WATTS_USERNAME="you@email.com" WATTS_PASSWORD="yourpass" npx tsx test-auth.ts
+```
+
+## Troubleshooting
+
+### Thermostat not appearing in HomeKit
+
+1. Check Homebridge logs for authentication errors
+2. Verify your Watts Home credentials are correct
+3. Ensure your thermostat is set up in the Watts Home app
+4. Try restarting Homebridge
+
+### "Not Responding" in Home app
+
+- Check your internet connection
+- Verify the Watts Home cloud service is operational
+- Increase `pollingInterval` if you're hitting rate limits
+
+### Authentication failures
+
+- Ensure your email and password match what you use in the Watts Home app
+- Check if your account has been locked (too many failed attempts)
+- The plugin uses the same authentication flow as the mobile app
+
+## About Tekmar / Watts
+
+[Tekmar](https://www.watts.com/brands/tekmar) is a Watts brand specializing in radiant heating controls. The tN4 WiFi thermostat series connects to the Watts Home cloud platform for remote control. This plugin uses the Watts Home cloud API to integrate with HomeKit.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Acknowledgments
+
+- Thanks to the [Homebridge](https://homebridge.io) team for the excellent platform
+- Built with [Claude Code](https://claude.com/claude-code)
+
+## Support
+
+- [Report Issues](https://github.com/apumapho/homebridge-tekmar/issues)
+- [Homebridge Discord](https://discord.gg/homebridge)
+- [Homebridge Wiki](https://github.com/homebridge/homebridge/wiki)

package/config.schema.json

@@ -0,0 +1,66 @@
+{
+  "pluginAlias": "TekmarThermostat",
+  "pluginType": "platform",
+  "singular": true,
+  "headerDisplay": "Homebridge plugin for [Tekmar tN4 WiFi thermostats](https://www.watts.com/products/heating-cooling-comfort/smart-home/thermostats) (561/562/563/564) via the Watts Home cloud API.",
+  "footerDisplay": "For help, visit the [GitHub repository](https://github.com/apumapho/homebridge-tekmar).",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "title": "Name",
+        "type": "string",
+        "default": "Tekmar Thermostat",
+        "required": true
+      },
+      "username": {
+        "title": "Email",
+        "type": "string",
+        "format": "email",
+        "description": "Your Watts Home app email address.",
+        "required": true
+      },
+      "password": {
+        "title": "Password",
+        "type": "string",
+        "description": "Your Watts Home app password.",
+        "required": true
+      },
+      "pollingInterval": {
+        "title": "Polling Interval (seconds)",
+        "type": "integer",
+        "default": 60,
+        "minimum": 10,
+        "maximum": 300,
+        "description": "How often to poll the Watts Home API for thermostat state updates."
+      },
+      "temperatureUnit": {
+        "title": "Temperature Display Unit",
+        "type": "string",
+        "default": "fahrenheit",
+        "oneOf": [
+          { "title": "Fahrenheit", "enum": ["fahrenheit"] },
+          { "title": "Celsius", "enum": ["celsius"] }
+        ],
+        "description": "Preferred temperature display unit in the Home app."
+      }
+    }
+  },
+  "layout": [
+    "name",
+    "username",
+    {
+      "key": "password",
+      "type": "password"
+    },
+    {
+      "type": "fieldset",
+      "title": "Advanced Settings",
+      "expandable": true,
+      "items": [
+        "pollingInterval",
+        "temperatureUnit"
+      ]
+    }
+  ]
+}

package/dist/api/types.d.ts

@@ -0,0 +1,144 @@
+import type { PlatformConfig } from 'homebridge';
+export interface TekmarPlatformConfig extends PlatformConfig {
+    username: string;
+    password: string;
+    pollingInterval?: number;
+    temperatureUnit?: 'fahrenheit' | 'celsius';
+}
+export interface WattsApiResponse<T> {
+    errorNumber: number;
+    errorMessage: string | null;
+    body: T;
+}
+export interface WattsLocation {
+    locationId: string;
+    ownerId: string;
+    name: string;
+    address: {
+        address: string;
+        address2: string;
+        city: string;
+        state_province: string;
+        zipcode: string;
+        country: string;
+    };
+    awayState: number;
+    isDefault: boolean;
+    isShared: boolean;
+    userType: number;
+    supportsAway: boolean;
+    usersCount: number;
+    devicesCount: number;
+}
+export interface WattsDeviceData {
+    Sensors: {
+        Room: {
+            Val: number;
+            Status: string;
+        };
+        Floor: {
+            Val: number;
+            Status: string;
+        };
+        Outdoor: {
+            Val: number;
+            Status: string;
+        };
+    };
+    State: {
+        Op: string;
+        Sub: string;
+    };
+    Mode: {
+        Active: number;
+        Val: string;
+        Enum: string[];
+    };
+    Target: {
+        Active: number;
+        Sensor: string;
+        Hold: number;
+        Heat: number;
+        Cool: number | null;
+        Min: number;
+        Max: number;
+        Steps: number;
+    };
+    TempUnits: {
+        Active: number;
+        Val: string;
+        Enum: string[];
+    };
+    Units: string;
+    SchedEnable: {
+        Active: number;
+        Val: string;
+        Enum: string[];
+    };
+    Schedule: Record<string, unknown>;
+    Energy: Record<string, unknown>;
+    DateTime: string;
+    TZOffset: number;
+}
+export interface WattsDevice {
+    data: WattsDeviceData;
+    isConnected: boolean;
+    requestingUser: string;
+    deviceId: string;
+    name: string;
+    modelId: number;
+    modelNumber: string;
+    deviceType: string;
+    deviceTypeId: number;
+    location: {
+        locationId: string;
+        name: string;
+        address: unknown;
+        awayState: number;
+        userType: number;
+    };
+    imageUrl: string | null;
+    isShared: boolean;
+}
+export interface ThermostatDevice {
+    id: string;
+    name: string;
+    /** Current room temperature in °F */
+    currentTemperature: number;
+    /** Current floor temperature in °F */
+    floorTemperature: number;
+    /** Current outdoor temperature in °F */
+    outdoorTemperature: number;
+    /** Target/setpoint temperature in °F */
+    targetTemperature: number;
+    /** Operating mode: "Heat" | "Off" */
+    mode: string;
+    /** Whether the thermostat is currently calling for heat */
+    isHeating: boolean;
+    /** Whether the location is in Away mode */
+    isAway: boolean;
+    /** Whether schedule is enabled */
+    scheduleEnabled: boolean;
+    /** Whether the device is connected */
+    isConnected: boolean;
+    /** Model number */
+    modelNumber: string;
+    /** Min/Max setpoint range in °F */
+    minSetpoint: number;
+    maxSetpoint: number;
+    /** Location ID (needed for away mode) */
+    locationId: string;
+}
+export interface B2CTokenResponse {
+    access_token: string;
+    id_token: string;
+    token_type: string;
+    not_before: number;
+    expires_in: number;
+    expires_on: number;
+    resource: string;
+    id_token_expires_in: number;
+    profile_info: string;
+    refresh_token: string;
+    refresh_token_expires_in: number;
+}

package/dist/api/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/api/wattsApi.d.ts

@@ -0,0 +1,83 @@
+import type { Logger } from 'homebridge';
+import type { TekmarPlatformConfig, ThermostatDevice, WattsDevice, WattsLocation } from './types.js';
+/** Convert Fahrenheit to Celsius (HomeKit uses Celsius internally). */
+export declare function fahrenheitToCelsius(f: number): number;
+/** Convert Celsius (from HomeKit) to Fahrenheit for the API. */
+export declare function celsiusToFahrenheit(c: number): number;
+export declare class WattsApi {
+    private readonly config;
+    private readonly log;
+    private accessToken;
+    private refreshToken;
+    private tokenExpiresAt;
+    /** Cookie jar — accumulated across all auth requests. */
+    private cookieJar;
+    constructor(config: TekmarPlatformConfig, log: Logger);
+    /**
+     * Full Azure AD B2C authentication flow:
+     * 1. GET /authorize → follow redirects, load login page, extract CSRF & cookies
+     * 2. POST /SelfAsserted → submit credentials
+     * 3. GET /confirmed → get redirect with auth code
+     * 4. POST /token → exchange code for tokens
+     */
+    authenticate(): Promise<void>;
+    /**
+     * Refresh the access token using the refresh token.
+     */
+    refreshAccessToken(): Promise<void>;
+    /**
+     * Ensure we have a valid access token before making API calls.
+     */
+    ensureAuthenticated(): Promise<void>;
+    apiRequest<T>(url: string, options?: RequestInit): Promise<T>;
+    /**
+     * Get all locations for the user.
+     */
+    getLocations(): Promise<WattsLocation[]>;
+    /**
+     * Get all devices for a location.
+     */
+    getLocationDevices(locationId: string): Promise<WattsDevice[]>;
+    /**
+     * Get a single device with fresh data.
+     */
+    getDevice(deviceId: string): Promise<WattsDevice>;
+    /**
+     * Fetch all thermostat devices across all locations.
+     * Returns normalized ThermostatDevice[].
+     */
+    getDevices(): Promise<ThermostatDevice[]>;
+    /**
+     * Normalize a WattsDevice into our simplified ThermostatDevice.
+     */
+    normalizeDevice(device: WattsDevice): ThermostatDevice;
+    /**
+     * Set the target temperature for a thermostat.
+     * @param deviceId - The device ID
+     * @param celsius - Target temperature in Celsius (from HomeKit)
+     */
+    setTargetTemperature(deviceId: string, celsius: number): Promise<void>;
+    /**
+     * Set the operating mode for a thermostat.
+     * @param deviceId - The device ID
+     * @param mode - "Heat" or "Off"
+     */
+    setMode(deviceId: string, mode: string): Promise<void>;
+    /**
+     * Set the schedule enable/disable.
+     * @param deviceId - The device ID
+     * @param enabled - Whether to enable the schedule
+     */
+    setScheduleEnabled(deviceId: string, enabled: boolean): Promise<void>;
+    /**
+     * Set the away state for a location.
+     * @param locationId - The location ID
+     * @param away - true for Away, false for Home
+     */
+    setAwayState(locationId: string, away: boolean): Promise<void>;
+    private setTokens;
+    /** Collect Set-Cookie headers from a response into the cookie jar. */
+    private collectCookies;
+    /** Format the cookie jar as a Cookie header string. */
+    private getCookieHeader;
+}