homebridge-sensus 1.0.0

package/config.schema.json

@@ -0,0 +1,69 @@
+{
+  "pluginAlias": "SensusAnalytics",
+  "pluginType": "platform",
+  "singular": false,
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "title": "Name",
+        "type": "string",
+        "default": "Sensus Water Meter",
+        "required": true
+      },
+      "baseUrl": {
+        "title": "Base URL",
+        "type": "string",
+        "placeholder": "https://yourcity.sensus-analytics.com",
+        "description": "The base URL of your Sensus Analytics portal (no trailing slash).",
+        "required": true
+      },
+      "username": {
+        "title": "Username",
+        "type": "string",
+        "required": true
+      },
+      "password": {
+        "title": "Password",
+        "type": "string",
+        "required": true
+      },
+      "accountNumber": {
+        "title": "Account Number",
+        "type": "string",
+        "required": true
+      },
+      "meterNumber": {
+        "title": "Meter Number",
+        "type": "string",
+        "required": true
+      },
+      "leakThreshold": {
+        "title": "Leak Alert Threshold (gallons)",
+        "type": "number",
+        "default": 150,
+        "description": "Daily usage (in gallons) above which a leak alert is triggered in HomeKit. Default: 150."
+      },
+      "pollInterval": {
+        "title": "Poll Interval (minutes)",
+        "type": "number",
+        "default": 30,
+        "description": "How often to fetch new data from Sensus Analytics, in minutes. Default: 30."
+      }
+    }
+  },
+  "layout": [
+    "name",
+    "baseUrl",
+    "username",
+    "password",
+    "accountNumber",
+    "meterNumber",
+    {
+      "type": "fieldset",
+      "title": "Advanced Options",
+      "expandable": true,
+      "items": ["leakThreshold", "pollInterval"]
+    }
+  ]
+}

package/dist/accessory.d.ts

@@ -0,0 +1,25 @@
+import { PlatformAccessory } from 'homebridge';
+import { SensusAnalyticsPlatform } from './platform';
+import { SensusAnalyticsApi } from './sensusApi';
+export declare class SensusWaterMeterAccessory {
+    private readonly platform;
+    private readonly accessory;
+    private readonly apiClient;
+    private readonly leakService;
+    private readonly leakThreshold;
+    private readonly pollIntervalMs;
+    private readonly eveConsumptionChar;
+    private readonly eveTotalChar;
+    private lastData;
+    constructor(platform: SensusAnalyticsPlatform, accessory: PlatformAccessory, apiClient: SensusAnalyticsApi);
+    /**
+     * Creates and registers a custom Characteristic on the LeakSensor service.
+     * If the characteristic already exists (restored from cache), it is returned as-is.
+     */
+    private addEveCharacteristic;
+    /** Called by HomeKit to read the current leak state. */
+    private handleLeakDetectedGet;
+    /** Fetch latest data from Sensus Analytics and push updates to HomeKit. */
+    private poll;
+}
+//# sourceMappingURL=accessory.d.ts.map

package/dist/accessory.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SensusWaterMeterAccessory = void 0;
+// Eve for HomeKit custom characteristic UUIDs for water meters
+const EVE_UUID_WATER_CONSUMPTION = 'E863F10D-079E-48FF-8F27-9C2605A29F52'; // daily usage
+const EVE_UUID_TOTAL_WATER = 'E863F10C-079E-48FF-8F27-9C2605A29F52'; // odometer / total
+const DEFAULT_POLL_INTERVAL_MINUTES = 30;
+class SensusWaterMeterAccessory {
+    constructor(platform, accessory, apiClient) {
+        this.platform = platform;
+        this.accessory = accessory;
+        this.apiClient = apiClient;
+        this.lastData = null;
+        const { hap } = platform.api;
+        const { Service: Svc, Characteristic: Char } = platform;
+        this.leakThreshold = platform.config.leakThreshold ?? 150;
+        this.pollIntervalMs =
+            (platform.config.pollInterval ?? DEFAULT_POLL_INTERVAL_MINUTES) *
+                60 *
+                1000;
+        // ── Accessory Information ─────────────────────────────────────────────
+        this.accessory
+            .getService(Svc.AccessoryInformation)
+            .setCharacteristic(Char.Manufacturer, 'Sensus')
+            .setCharacteristic(Char.Model, 'Smart Water Meter')
+            .setCharacteristic(Char.SerialNumber, accessory.context.meterNumber ?? 'Unknown');
+        // ── Leak Sensor (primary HomeKit service) ─────────────────────────────
+        // Visible in Apple Home app as a leak sensor tile with alert notifications
+        this.leakService =
+            this.accessory.getService(Svc.LeakSensor) ?? this.accessory.addService(Svc.LeakSensor);
+        this.leakService.setCharacteristic(Char.Name, accessory.displayName);
+        this.leakService
+            .getCharacteristic(Char.LeakDetected)
+            .onGet(this.handleLeakDetectedGet.bind(this));
+        this.leakService
+            .getCharacteristic(Char.StatusActive)
+            .onGet(() => true);
+        // ── Eve Custom Characteristics ────────────────────────────────────────
+        // These are shown in the Eve for HomeKit app as consumption graphs.
+        // They are attached to the LeakSensor service so they share one accessory tile.
+        this.eveConsumptionChar = this.addEveCharacteristic('Water Consumption', EVE_UUID_WATER_CONSUMPTION, "float" /* hap.Formats.FLOAT */, ["ev" /* hap.Perms.NOTIFY */, "pr" /* hap.Perms.PAIRED_READ */], 0, 1000000, 0.001);
+        this.eveTotalChar = this.addEveCharacteristic('Total Water Consumption', EVE_UUID_TOTAL_WATER, "float" /* hap.Formats.FLOAT */, ["ev" /* hap.Perms.NOTIFY */, "pr" /* hap.Perms.PAIRED_READ */], 0, 1000000000, 0.001);
+        // ── Start polling ─────────────────────────────────────────────────────
+        this.poll();
+        setInterval(() => this.poll(), this.pollIntervalMs);
+    }
+    /**
+     * Creates and registers a custom Characteristic on the LeakSensor service.
+     * If the characteristic already exists (restored from cache), it is returned as-is.
+     */
+    addEveCharacteristic(displayName, uuid, format, perms, minValue, maxValue, minStep) {
+        const { hap } = this.platform.api;
+        const existing = this.leakService.characteristics.find((c) => c.UUID === uuid);
+        if (existing) {
+            return existing;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const props = { format, unit: 'gal', minValue, maxValue, minStep, perms };
+        const char = new hap.Characteristic(displayName, uuid, props);
+        char.setValue(0);
+        this.leakService.addCharacteristic(char);
+        return char;
+    }
+    /** Called by HomeKit to read the current leak state. */
+    handleLeakDetectedGet() {
+        const { LEAK_DETECTED, LEAK_NOT_DETECTED } = this.platform.Characteristic.LeakDetected;
+        if (!this.lastData) {
+            return LEAK_NOT_DETECTED;
+        }
+        return this.lastData.daily.dailyUsage > this.leakThreshold
+            ? LEAK_DETECTED
+            : LEAK_NOT_DETECTED;
+    }
+    /** Fetch latest data from Sensus Analytics and push updates to HomeKit. */
+    async poll() {
+        this.platform.log.debug('Sensus Analytics: polling for new data...');
+        const data = await this.apiClient.fetchData();
+        if (!data) {
+            this.platform.log.warn('Sensus Analytics: no data returned, will retry next interval');
+            return;
+        }
+        this.lastData = data;
+        const { daily, hourly } = data;
+        const { LEAK_DETECTED, LEAK_NOT_DETECTED } = this.platform.Characteristic.LeakDetected;
+        const isLeaking = daily.dailyUsage > this.leakThreshold;
+        // Push updates to HomeKit
+        this.leakService.updateCharacteristic(this.platform.Characteristic.LeakDetected, isLeaking ? LEAK_DETECTED : LEAK_NOT_DETECTED);
+        // Eve consumption characteristics
+        this.eveConsumptionChar.updateValue(daily.dailyUsage);
+        this.eveTotalChar.updateValue(daily.odometer);
+        // Log a summary
+        const lastHour = hourly.at(-1);
+        this.platform.log.info(`[${this.accessory.displayName}] ` +
+            `daily=${daily.dailyUsage} ${daily.usageUnit} | ` +
+            `odometer=${daily.odometer} ${daily.usageUnit} | ` +
+            `billing=${daily.billingUsage} ${daily.usageUnit} | ` +
+            `leak=${isLeaking}` +
+            (lastHour ? ` | lastHourUsage=${lastHour.usage} | temp=${lastHour.temp}°F` : ''));
+    }
+}
+exports.SensusWaterMeterAccessory = SensusWaterMeterAccessory;
+//# sourceMappingURL=accessory.js.map

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { API } from 'homebridge';
+declare const _default: (api: API) => void;
+export = _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+const platform_1 = require("./platform");
+const settings_1 = require("./settings");
+module.exports = (api) => {
+    api.registerPlatform(settings_1.PLATFORM_NAME, platform_1.SensusAnalyticsPlatform);
+};
+//# sourceMappingURL=index.js.map

package/dist/platform.d.ts

@@ -0,0 +1,14 @@
+import { API, Characteristic, DynamicPlatformPlugin, Logger, PlatformAccessory, PlatformConfig, Service } from 'homebridge';
+export declare class SensusAnalyticsPlatform implements DynamicPlatformPlugin {
+    readonly log: Logger;
+    readonly config: PlatformConfig;
+    readonly api: API;
+    readonly Service: typeof Service;
+    readonly Characteristic: typeof Characteristic;
+    readonly cachedAccessories: PlatformAccessory[];
+    constructor(log: Logger, config: PlatformConfig, api: API);
+    /** Called by Homebridge to restore cached accessories on startup. */
+    configureAccessory(accessory: PlatformAccessory): void;
+    private discoverDevices;
+}
+//# sourceMappingURL=platform.d.ts.map

package/dist/platform.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SensusAnalyticsPlatform = void 0;
+const settings_1 = require("./settings");
+const accessory_1 = require("./accessory");
+const sensusApi_1 = require("./sensusApi");
+class SensusAnalyticsPlatform {
+    constructor(log, config, api) {
+        this.log = log;
+        this.config = config;
+        this.api = api;
+        // Restored cached accessories from disk
+        this.cachedAccessories = [];
+        this.Service = this.api.hap.Service;
+        this.Characteristic = this.api.hap.Characteristic;
+        this.log.debug('Sensus Analytics platform initialising');
+        this.api.on('didFinishLaunching', () => {
+            this.discoverDevices();
+        });
+    }
+    /** Called by Homebridge to restore cached accessories on startup. */
+    configureAccessory(accessory) {
+        this.log.info('Restoring cached accessory:', accessory.displayName);
+        this.cachedAccessories.push(accessory);
+    }
+    discoverDevices() {
+        const { baseUrl, username, password, accountNumber, meterNumber } = this.config;
+        if (!baseUrl || !username || !password || !accountNumber || !meterNumber) {
+            this.log.error('Sensus Analytics: missing required config fields ' +
+                '(baseUrl, username, password, accountNumber, meterNumber)');
+            return;
+        }
+        const apiClient = new sensusApi_1.SensusAnalyticsApi(baseUrl, username, password, accountNumber, meterNumber, this.log);
+        const displayName = this.config.name || 'Sensus Water Meter';
+        const uuid = this.api.hap.uuid.generate(`sensus-${meterNumber}`);
+        const existing = this.cachedAccessories.find((a) => a.UUID === uuid);
+        if (existing) {
+            this.log.info('Restoring water meter accessory:', existing.displayName);
+            new accessory_1.SensusWaterMeterAccessory(this, existing, apiClient);
+        }
+        else {
+            this.log.info('Adding new water meter accessory:', displayName);
+            const accessory = new this.api.platformAccessory(displayName, uuid);
+            accessory.context.meterNumber = meterNumber;
+            new accessory_1.SensusWaterMeterAccessory(this, accessory, apiClient);
+            this.api.registerPlatformAccessories(settings_1.PLUGIN_NAME, settings_1.PLATFORM_NAME, [accessory]);
+        }
+    }
+}
+exports.SensusAnalyticsPlatform = SensusAnalyticsPlatform;
+//# sourceMappingURL=platform.js.map

package/dist/sensusApi.d.ts

@@ -0,0 +1,42 @@
+import { Logger } from 'homebridge';
+export interface DailyData {
+    dailyUsage: number;
+    usageUnit: string;
+    meterAddress: string;
+    lastRead: string;
+    meterId: string;
+    meterLat: number;
+    meterLong: number;
+    odometer: number;
+    billingUsage: number;
+}
+export interface HourlyEntry {
+    timestamp: number;
+    usage: number;
+    rain: number;
+    temp: number;
+    usageUnit: string;
+    rainUnit: string;
+    tempUnit: string;
+}
+export interface SensusData {
+    daily: DailyData;
+    hourly: HourlyEntry[];
+}
+export declare class SensusAnalyticsApi {
+    private readonly baseUrl;
+    private readonly username;
+    private readonly password;
+    private readonly accountNumber;
+    private readonly meterNumber;
+    private readonly log;
+    private readonly client;
+    private readonly jar;
+    private loggedIn;
+    constructor(baseUrl: string, username: string, password: string, accountNumber: string, meterNumber: string, log: Logger);
+    login(): Promise<boolean>;
+    fetchData(): Promise<SensusData | null>;
+    private fetchDailyData;
+    private fetchHourlyData;
+}
+//# sourceMappingURL=sensusApi.d.ts.map

package/dist/sensusApi.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SensusAnalyticsApi = void 0;
+const axios_1 = require("axios");
+const axios_cookiejar_support_1 = require("axios-cookiejar-support");
+const tough_cookie_1 = require("tough-cookie");
+class SensusAnalyticsApi {
+    constructor(baseUrl, username, password, accountNumber, meterNumber, log) {
+        this.baseUrl = baseUrl;
+        this.username = username;
+        this.password = password;
+        this.accountNumber = accountNumber;
+        this.meterNumber = meterNumber;
+        this.log = log;
+        this.loggedIn = false;
+        this.jar = new tough_cookie_1.CookieJar();
+        this.client = (0, axios_cookiejar_support_1.wrapper)(axios_1.default.create({
+            baseURL: baseUrl.replace(/\/$/, ''),
+            jar: this.jar,
+            withCredentials: true,
+            // Follow redirects but treat 302 as success for login
+            maxRedirects: 5,
+            timeout: 15000,
+        }));
+    }
+    async login() {
+        try {
+            this.log.debug('Sensus Analytics: attempting login...');
+            await this.client.post('/j_spring_security_check', new URLSearchParams({
+                j_username: this.username,
+                j_password: this.password,
+            }).toString(), {
+                headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+                // A 302 redirect means login was processed; axios follows it automatically
+                validateStatus: (s) => s < 400,
+            });
+            this.loggedIn = true;
+            this.log.debug('Sensus Analytics: login successful');
+            return true;
+        }
+        catch (err) {
+            this.loggedIn = false;
+            this.log.error('Sensus Analytics: login failed:', err.message);
+            return false;
+        }
+    }
+    async fetchData() {
+        if (!this.loggedIn) {
+            const ok = await this.login();
+            if (!ok) {
+                return null;
+            }
+        }
+        try {
+            const [daily, hourly] = await Promise.all([
+                this.fetchDailyData(),
+                this.fetchHourlyData(),
+            ]);
+            if (!daily) {
+                // Session may have expired — clear and retry once
+                this.loggedIn = false;
+                const ok = await this.login();
+                if (!ok) {
+                    return null;
+                }
+                const retried = await this.fetchDailyData();
+                if (!retried) {
+                    return null;
+                }
+                return { daily: retried, hourly: hourly ?? [] };
+            }
+            return { daily, hourly: hourly ?? [] };
+        }
+        catch (err) {
+            this.loggedIn = false;
+            this.log.error('Sensus Analytics: error fetching data:', err.message);
+            return null;
+        }
+    }
+    async fetchDailyData() {
+        const response = await this.client.post('/water/widget/byPage', {
+            group: 'meters',
+            accountNumber: this.accountNumber,
+            deviceId: this.meterNumber,
+        });
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const device = response.data?.widgetList?.[0]?.data?.devices?.[0];
+        if (!device) {
+            this.log.warn('Sensus Analytics: unexpected daily data structure');
+            return null;
+        }
+        return {
+            dailyUsage: parseFloat(device.dailyUsage) || 0,
+            usageUnit: device.usageUnit || 'CCF',
+            meterAddress: device.meterAddress1 || '',
+            lastRead: device.lastRead || '',
+            meterId: String(device.meterId || ''),
+            meterLat: parseFloat(device.meterLat) || 0,
+            meterLong: parseFloat(device.meterLong) || 0,
+            odometer: parseFloat(device.latestReadUsage) || 0,
+            billingUsage: parseFloat(device.billingUsage) || 0,
+        };
+    }
+    async fetchHourlyData() {
+        // Fetch the previous day's data (Sensus updates at midnight)
+        const yesterday = new Date();
+        yesterday.setDate(yesterday.getDate() - 1);
+        const startOfDay = new Date(yesterday.getFullYear(), yesterday.getMonth(), yesterday.getDate());
+        const endOfDay = new Date(startOfDay.getTime() + 86400000 - 1);
+        const response = await this.client.get(`/water/usage/${this.accountNumber}/${this.meterNumber}`, {
+            params: {
+                start: startOfDay.getTime(),
+                end: endOfDay.getTime(),
+                zoom: 'day',
+                page: 'null',
+                weather: '1',
+            },
+        });
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const data = response.data;
+        if (!data?.operationSuccess) {
+            this.log.warn('Sensus Analytics: hourly data fetch unsuccessful');
+            return null;
+        }
+        const usageArray = data?.data?.usage;
+        if (!Array.isArray(usageArray) || usageArray.length < 2) {
+            return [];
+        }
+        // First element is units row: [usageUnit, rainUnit, tempUnit, altUnit]
+        const [usageUnit, rainUnit, tempUnit] = usageArray[0];
+        const rows = usageArray.slice(1);
+        return rows.map((row) => ({
+            timestamp: row[0],
+            usage: row[1] ?? 0,
+            rain: row[2] ?? 0,
+            temp: row[3] ?? 0,
+            usageUnit: usageUnit ?? 'CCF',
+            rainUnit: rainUnit ?? 'INCHES',
+            tempUnit: tempUnit ?? 'FAHRENHEIT',
+        }));
+    }
+}
+exports.SensusAnalyticsApi = SensusAnalyticsApi;
+//# sourceMappingURL=sensusApi.js.map

package/dist/settings.d.ts

@@ -0,0 +1,3 @@
+export declare const PLATFORM_NAME = "SensusAnalytics";
+export declare const PLUGIN_NAME = "homebridge-sensus";
+//# sourceMappingURL=settings.d.ts.map

package/dist/settings.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLUGIN_NAME = exports.PLATFORM_NAME = void 0;
+exports.PLATFORM_NAME = 'SensusAnalytics';
+exports.PLUGIN_NAME = 'homebridge-sensus';
+//# sourceMappingURL=settings.js.map

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "homebridge-sensus",
+  "version": "1.0.0",
+  "description": "Homebridge plugin for Sensus Analytics water meters",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "homebridge-plugin",
+    "sensus",
+    "water",
+    "meter",
+    "homekit"
+  ],
+  "engines": {
+    "node": ">=18.0.0",
+    "homebridge": ">=1.6.0"
+  },
+  "dependencies": {
+    "axios": "^1.6.0",
+    "axios-cookiejar-support": "^4.0.7",
+    "tough-cookie": "^4.1.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/tough-cookie": "^4.0.5",
+    "homebridge": "^1.8.0",
+    "typescript": "^5.3.0"
+  },
+  "peerDependencies": {
+    "homebridge": ">=1.6.0"
+  }
+}

package/src/accessory.ts

@@ -0,0 +1,164 @@
+import { PlatformAccessory, CharacteristicValue, Service, Characteristic } from 'homebridge';
+import { SensusAnalyticsPlatform } from './platform';
+import { SensusAnalyticsApi, SensusData } from './sensusApi';
+
+// Eve for HomeKit custom characteristic UUIDs for water meters
+const EVE_UUID_WATER_CONSUMPTION = 'E863F10D-079E-48FF-8F27-9C2605A29F52'; // daily usage
+const EVE_UUID_TOTAL_WATER = 'E863F10C-079E-48FF-8F27-9C2605A29F52';       // odometer / total
+
+const DEFAULT_POLL_INTERVAL_MINUTES = 30;
+
+export class SensusWaterMeterAccessory {
+  private readonly leakService: Service;
+  private readonly leakThreshold: number;
+  private readonly pollIntervalMs: number;
+
+  // Direct references to Eve custom characteristics to avoid UUID lookups on update
+  private readonly eveConsumptionChar: Characteristic;
+  private readonly eveTotalChar: Characteristic;
+
+  private lastData: SensusData | null = null;
+
+  constructor(
+    private readonly platform: SensusAnalyticsPlatform,
+    private readonly accessory: PlatformAccessory,
+    private readonly apiClient: SensusAnalyticsApi,
+  ) {
+    const { hap } = platform.api;
+    const { Service: Svc, Characteristic: Char } = platform;
+
+    this.leakThreshold = (platform.config.leakThreshold as number | undefined) ?? 150;
+    this.pollIntervalMs =
+      ((platform.config.pollInterval as number | undefined) ?? DEFAULT_POLL_INTERVAL_MINUTES) *
+      60 *
+      1000;
+
+    // ── Accessory Information ─────────────────────────────────────────────
+    this.accessory
+      .getService(Svc.AccessoryInformation)!
+      .setCharacteristic(Char.Manufacturer, 'Sensus')
+      .setCharacteristic(Char.Model, 'Smart Water Meter')
+      .setCharacteristic(
+        Char.SerialNumber,
+        (accessory.context.meterNumber as string | undefined) ?? 'Unknown',
+      );
+
+    // ── Leak Sensor (primary HomeKit service) ─────────────────────────────
+    // Visible in Apple Home app as a leak sensor tile with alert notifications
+    this.leakService =
+      this.accessory.getService(Svc.LeakSensor) ?? this.accessory.addService(Svc.LeakSensor);
+
+    this.leakService.setCharacteristic(Char.Name, accessory.displayName);
+
+    this.leakService
+      .getCharacteristic(Char.LeakDetected)
+      .onGet(this.handleLeakDetectedGet.bind(this));
+
+    this.leakService
+      .getCharacteristic(Char.StatusActive)
+      .onGet(() => true);
+
+    // ── Eve Custom Characteristics ────────────────────────────────────────
+    // These are shown in the Eve for HomeKit app as consumption graphs.
+    // They are attached to the LeakSensor service so they share one accessory tile.
+
+    this.eveConsumptionChar = this.addEveCharacteristic(
+      'Water Consumption',
+      EVE_UUID_WATER_CONSUMPTION,
+      hap.Formats.FLOAT,
+      [hap.Perms.NOTIFY, hap.Perms.PAIRED_READ],
+      0, 1_000_000, 0.001,
+    );
+
+    this.eveTotalChar = this.addEveCharacteristic(
+      'Total Water Consumption',
+      EVE_UUID_TOTAL_WATER,
+      hap.Formats.FLOAT,
+      [hap.Perms.NOTIFY, hap.Perms.PAIRED_READ],
+      0, 1_000_000_000, 0.001,
+    );
+
+    // ── Start polling ─────────────────────────────────────────────────────
+    this.poll();
+    setInterval(() => this.poll(), this.pollIntervalMs);
+  }
+
+  /**
+   * Creates and registers a custom Characteristic on the LeakSensor service.
+   * If the characteristic already exists (restored from cache), it is returned as-is.
+   */
+  private addEveCharacteristic(
+    displayName: string,
+    uuid: string,
+    format: string,
+    perms: string[],
+    minValue: number,
+    maxValue: number,
+    minStep: number,
+  ): Characteristic {
+    const { hap } = this.platform.api;
+
+    const existing = this.leakService.characteristics.find((c) => c.UUID === uuid);
+    if (existing) {
+      return existing;
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const props: any = { format, unit: 'gal', minValue, maxValue, minStep, perms };
+    const char = new hap.Characteristic(displayName, uuid, props);
+    char.setValue(0);
+    this.leakService.addCharacteristic(char);
+    return char;
+  }
+
+  /** Called by HomeKit to read the current leak state. */
+  private handleLeakDetectedGet(): CharacteristicValue {
+    const { LEAK_DETECTED, LEAK_NOT_DETECTED } = this.platform.Characteristic.LeakDetected;
+
+    if (!this.lastData) {
+      return LEAK_NOT_DETECTED;
+    }
+
+    return this.lastData.daily.dailyUsage > this.leakThreshold
+      ? LEAK_DETECTED
+      : LEAK_NOT_DETECTED;
+  }
+
+  /** Fetch latest data from Sensus Analytics and push updates to HomeKit. */
+  private async poll(): Promise<void> {
+    this.platform.log.debug('Sensus Analytics: polling for new data...');
+
+    const data = await this.apiClient.fetchData();
+    if (!data) {
+      this.platform.log.warn('Sensus Analytics: no data returned, will retry next interval');
+      return;
+    }
+
+    this.lastData = data;
+    const { daily, hourly } = data;
+    const { LEAK_DETECTED, LEAK_NOT_DETECTED } = this.platform.Characteristic.LeakDetected;
+
+    const isLeaking = daily.dailyUsage > this.leakThreshold;
+
+    // Push updates to HomeKit
+    this.leakService.updateCharacteristic(
+      this.platform.Characteristic.LeakDetected,
+      isLeaking ? LEAK_DETECTED : LEAK_NOT_DETECTED,
+    );
+
+    // Eve consumption characteristics
+    this.eveConsumptionChar.updateValue(daily.dailyUsage);
+    this.eveTotalChar.updateValue(daily.odometer);
+
+    // Log a summary
+    const lastHour = hourly.at(-1);
+    this.platform.log.info(
+      `[${this.accessory.displayName}] ` +
+      `daily=${daily.dailyUsage} ${daily.usageUnit} | ` +
+      `odometer=${daily.odometer} ${daily.usageUnit} | ` +
+      `billing=${daily.billingUsage} ${daily.usageUnit} | ` +
+      `leak=${isLeaking}` +
+      (lastHour ? ` | lastHourUsage=${lastHour.usage} | temp=${lastHour.temp}°F` : ''),
+    );
+  }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+import { API } from 'homebridge';
+import { SensusAnalyticsPlatform } from './platform';
+import { PLATFORM_NAME } from './settings';
+
+export = (api: API): void => {
+  api.registerPlatform(PLATFORM_NAME, SensusAnalyticsPlatform);
+};

package/src/platform.ts

@@ -0,0 +1,79 @@
+import {
+  API,
+  Characteristic,
+  DynamicPlatformPlugin,
+  Logger,
+  PlatformAccessory,
+  PlatformConfig,
+  Service,
+} from 'homebridge';
+
+import { PLATFORM_NAME, PLUGIN_NAME } from './settings';
+import { SensusWaterMeterAccessory } from './accessory';
+import { SensusAnalyticsApi } from './sensusApi';
+
+export class SensusAnalyticsPlatform implements DynamicPlatformPlugin {
+  public readonly Service: typeof Service;
+  public readonly Characteristic: typeof Characteristic;
+
+  // Restored cached accessories from disk
+  public readonly cachedAccessories: PlatformAccessory[] = [];
+
+  constructor(
+    public readonly log: Logger,
+    public readonly config: PlatformConfig,
+    public readonly api: API,
+  ) {
+    this.Service = this.api.hap.Service;
+    this.Characteristic = this.api.hap.Characteristic;
+
+    this.log.debug('Sensus Analytics platform initialising');
+
+    this.api.on('didFinishLaunching', () => {
+      this.discoverDevices();
+    });
+  }
+
+  /** Called by Homebridge to restore cached accessories on startup. */
+  configureAccessory(accessory: PlatformAccessory): void {
+    this.log.info('Restoring cached accessory:', accessory.displayName);
+    this.cachedAccessories.push(accessory);
+  }
+
+  private discoverDevices(): void {
+    const { baseUrl, username, password, accountNumber, meterNumber } = this.config;
+
+    if (!baseUrl || !username || !password || !accountNumber || !meterNumber) {
+      this.log.error(
+        'Sensus Analytics: missing required config fields ' +
+        '(baseUrl, username, password, accountNumber, meterNumber)',
+      );
+      return;
+    }
+
+    const apiClient = new SensusAnalyticsApi(
+      baseUrl,
+      username,
+      password,
+      accountNumber,
+      meterNumber,
+      this.log,
+    );
+
+    const displayName = (this.config.name as string | undefined) || 'Sensus Water Meter';
+    const uuid = this.api.hap.uuid.generate(`sensus-${meterNumber}`);
+
+    const existing = this.cachedAccessories.find((a) => a.UUID === uuid);
+
+    if (existing) {
+      this.log.info('Restoring water meter accessory:', existing.displayName);
+      new SensusWaterMeterAccessory(this, existing, apiClient);
+    } else {
+      this.log.info('Adding new water meter accessory:', displayName);
+      const accessory = new this.api.platformAccessory(displayName, uuid);
+      accessory.context.meterNumber = meterNumber;
+      new SensusWaterMeterAccessory(this, accessory, apiClient);
+      this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [accessory]);
+    }
+  }
+}

package/src/sensusApi.ts

@@ -0,0 +1,197 @@
+import axios, { AxiosInstance } from 'axios';
+import { wrapper } from 'axios-cookiejar-support';
+import { CookieJar } from 'tough-cookie';
+import { Logger } from 'homebridge';
+
+export interface DailyData {
+  dailyUsage: number;
+  usageUnit: string;
+  meterAddress: string;
+  lastRead: string;
+  meterId: string;
+  meterLat: number;
+  meterLong: number;
+  odometer: number;
+  billingUsage: number;
+}
+
+export interface HourlyEntry {
+  timestamp: number;
+  usage: number;
+  rain: number;
+  temp: number;
+  usageUnit: string;
+  rainUnit: string;
+  tempUnit: string;
+}
+
+export interface SensusData {
+  daily: DailyData;
+  hourly: HourlyEntry[];
+}
+
+export class SensusAnalyticsApi {
+  private readonly client: AxiosInstance;
+  private readonly jar: CookieJar;
+  private loggedIn = false;
+
+  constructor(
+    private readonly baseUrl: string,
+    private readonly username: string,
+    private readonly password: string,
+    private readonly accountNumber: string,
+    private readonly meterNumber: string,
+    private readonly log: Logger,
+  ) {
+    this.jar = new CookieJar();
+    this.client = wrapper(
+      axios.create({
+        baseURL: baseUrl.replace(/\/$/, ''),
+        jar: this.jar,
+        withCredentials: true,
+        // Follow redirects but treat 302 as success for login
+        maxRedirects: 5,
+        timeout: 15000,
+      }),
+    );
+  }
+
+  async login(): Promise<boolean> {
+    try {
+      this.log.debug('Sensus Analytics: attempting login...');
+      await this.client.post(
+        '/j_spring_security_check',
+        new URLSearchParams({
+          j_username: this.username,
+          j_password: this.password,
+        }).toString(),
+        {
+          headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+          // A 302 redirect means login was processed; axios follows it automatically
+          validateStatus: (s) => s < 400,
+        },
+      );
+      this.loggedIn = true;
+      this.log.debug('Sensus Analytics: login successful');
+      return true;
+    } catch (err) {
+      this.loggedIn = false;
+      this.log.error('Sensus Analytics: login failed:', (err as Error).message);
+      return false;
+    }
+  }
+
+  async fetchData(): Promise<SensusData | null> {
+    if (!this.loggedIn) {
+      const ok = await this.login();
+      if (!ok) {
+        return null;
+      }
+    }
+
+    try {
+      const [daily, hourly] = await Promise.all([
+        this.fetchDailyData(),
+        this.fetchHourlyData(),
+      ]);
+
+      if (!daily) {
+        // Session may have expired — clear and retry once
+        this.loggedIn = false;
+        const ok = await this.login();
+        if (!ok) {
+          return null;
+        }
+        const retried = await this.fetchDailyData();
+        if (!retried) {
+          return null;
+        }
+        return { daily: retried, hourly: hourly ?? [] };
+      }
+
+      return { daily, hourly: hourly ?? [] };
+    } catch (err) {
+      this.loggedIn = false;
+      this.log.error('Sensus Analytics: error fetching data:', (err as Error).message);
+      return null;
+    }
+  }
+
+  private async fetchDailyData(): Promise<DailyData | null> {
+    const response = await this.client.post('/water/widget/byPage', {
+      group: 'meters',
+      accountNumber: this.accountNumber,
+      deviceId: this.meterNumber,
+    });
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const device = (response.data as any)?.widgetList?.[0]?.data?.devices?.[0];
+    if (!device) {
+      this.log.warn('Sensus Analytics: unexpected daily data structure');
+      return null;
+    }
+
+    return {
+      dailyUsage: parseFloat(device.dailyUsage) || 0,
+      usageUnit: device.usageUnit || 'CCF',
+      meterAddress: device.meterAddress1 || '',
+      lastRead: device.lastRead || '',
+      meterId: String(device.meterId || ''),
+      meterLat: parseFloat(device.meterLat) || 0,
+      meterLong: parseFloat(device.meterLong) || 0,
+      odometer: parseFloat(device.latestReadUsage) || 0,
+      billingUsage: parseFloat(device.billingUsage) || 0,
+    };
+  }
+
+  private async fetchHourlyData(): Promise<HourlyEntry[] | null> {
+    // Fetch the previous day's data (Sensus updates at midnight)
+    const yesterday = new Date();
+    yesterday.setDate(yesterday.getDate() - 1);
+    const startOfDay = new Date(
+      yesterday.getFullYear(),
+      yesterday.getMonth(),
+      yesterday.getDate(),
+    );
+    const endOfDay = new Date(startOfDay.getTime() + 86_400_000 - 1);
+
+    const response = await this.client.get(
+      `/water/usage/${this.accountNumber}/${this.meterNumber}`,
+      {
+        params: {
+          start: startOfDay.getTime(),
+          end: endOfDay.getTime(),
+          zoom: 'day',
+          page: 'null',
+          weather: '1',
+        },
+      },
+    );
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const data = response.data as any;
+    if (!data?.operationSuccess) {
+      this.log.warn('Sensus Analytics: hourly data fetch unsuccessful');
+      return null;
+    }
+
+    const usageArray: unknown[][] = data?.data?.usage;
+    if (!Array.isArray(usageArray) || usageArray.length < 2) {
+      return [];
+    }
+
+    // First element is units row: [usageUnit, rainUnit, tempUnit, altUnit]
+    const [usageUnit, rainUnit, tempUnit] = usageArray[0] as string[];
+    const rows = usageArray.slice(1);
+
+    return rows.map((row) => ({
+      timestamp: row[0] as number,
+      usage: (row[1] as number) ?? 0,
+      rain: (row[2] as number) ?? 0,
+      temp: (row[3] as number) ?? 0,
+      usageUnit: usageUnit ?? 'CCF',
+      rainUnit: rainUnit ?? 'INCHES',
+      tempUnit: tempUnit ?? 'FAHRENHEIT',
+    }));
+  }
+}

package/src/settings.ts

@@ -0,0 +1,2 @@
+export const PLATFORM_NAME = 'SensusAnalytics';
+export const PLUGIN_NAME = 'homebridge-sensus';

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "moduleResolution": "node",
+    "experimentalDecorators": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src"]
+}