homebridge-ratgdo 2.8.1 → 2.9.1

package/dist/ratgdo-api.d.ts

@@ -0,0 +1,313 @@
+import type { HomebridgePluginLogging, Nullable } from "homebridge-plugin-utils";
+import { EventEmitter } from "node:events";
+/**
+ * Represents one entity from the ESPHome device.
+ *
+ * @property key - The numeric key identifier for the entity.
+ * @property name - The human-readable name of the entity.
+ * @property type - The type of entity (e.g., "switch", "light", "cover").
+ */
+interface Entity {
+    key: number;
+    name: string;
+    type: string;
+}
+/**
+ * Device information to send when requested by the ESPHome device.
+ *
+ * @property bluetoothProxyFeatureFlags - Bluetooth proxy feature flags.
+ * @property compilationTime - When the client was compiled/started.
+ * @property esphomeVersion - Version of ESPHome protocol being used.
+ * @property hasDeepSleep - Whether the client supports deep sleep.
+ * @property legacyBluetoothProxyVersion - Legacy Bluetooth proxy version.
+ * @property macAddress - MAC address of the client (format: "AA:BB:CC:DD:EE:FF").
+ * @property model - Model or type of the client.
+ * @property name - Friendly name of the client.
+ * @property projectName - Name of the project/plugin.
+ * @property projectVersion - Version of the project/plugin.
+ * @property usesPassword - Whether the client uses password authentication.
+ * @property webserverPort - Port number of any web server.
+ */
+export interface DeviceInfo {
+    bluetoothProxyFeatureFlags?: number;
+    compilationTime?: string;
+    esphomeVersion?: string;
+    hasDeepSleep?: boolean;
+    legacyBluetoothProxyVersion?: number;
+    macAddress?: string;
+    model?: string;
+    name?: string;
+    projectName?: string;
+    projectVersion?: string;
+    usesPassword?: boolean;
+    webserverPort?: number;
+}
+/**
+ * ESPHome API client for communicating with ESPHome devices.
+ * Implements the ESPHome native API protocol over TCP.
+ *
+ * @extends EventEmitter
+ * @emits connect - Connected to device.
+ * @emits disconnect - Disconnected from device.
+ * @emits message - Raw message received with type and payload.
+ * @emits entities - List of discovered entities after enumeration.
+ * @emits telemetry - Generic telemetry update for any entity.
+ * @emits heartbeat - Heartbeat response received.
+ * @emits {entityType} - Type-specific telemetry events (e.g., "cover", "light", "switch").
+ *
+ * @example
+ * ```typescript
+ * const client = new EspHomeClient(ratgdo, "192.168.1.100");
+ * client.connect();
+ *
+ * // Listen for discovered entities
+ * client.on("entities", (entities) => {
+ *
+ *   // Log all available entity IDs
+ *   client.logAllEntityIds();
+ * });
+ *
+ * // Send commands using entity IDs
+ * await client.sendSwitchCommand("switch-garagedoor", true);
+ * await client.sendLightCommand("light-light", { state: true, brightness: 0.8 });
+ * await client.sendCoverCommand("cover-door", "open");
+ * ```
+ */
+export declare class EspHomeClient extends EventEmitter {
+    private clientSocket;
+    private dataListener;
+    private host;
+    private log;
+    private port;
+    private recvBuffer;
+    private remoteDeviceInfo;
+    private discoveredEntities;
+    private entityKeys;
+    private entityNames;
+    private entityTypes;
+    /**
+     * Creates a new ESPHome client instance.
+     *
+     * @param log - Logging interface.
+     * @param host - The hostname or IP address of the ESPHome device.
+     * @param port - The port number for the ESPHome API (default: 6053).
+     */
+    constructor(log: HomebridgePluginLogging, host: string, port?: number);
+    /**
+     * Connect to the ESPHome device and start communication.
+     */
+    connect(): void;
+    /**
+     * Disconnect from the ESPHome device and cleanup resources.
+     */
+    disconnect(): void;
+    /**
+     * Handle a newly connected socket.
+     */
+    private handleConnect;
+    /**
+     * Handle socket errors.
+     */
+    private handleSocketError;
+    /**
+     * Handle socket closure.
+     */
+    private handleSocketClose;
+    /**
+     * Clean up the data listener if it exists.
+     */
+    private cleanupDataListener;
+    /**
+     * Handle incoming raw data, frame messages, and dispatch.
+     */
+    private handleData;
+    /**
+     * Dispatch based on message type.
+     */
+    private handleMessage;
+    /**
+     * Handle device info response from the ESPHome device.
+     */
+    private handleDeviceInfoResponse;
+    /**
+     * Return the device information of the connected ESPHome device if available.
+     *
+     * @returns The device information if available, or `null`.
+     */
+    deviceInfo(): Nullable<DeviceInfo>;
+    /**
+     * Check if a message type is a list entities response.
+     */
+    private isListEntitiesResponse;
+    /**
+     * Check if a message type is a state update.
+     */
+    private isStateUpdate;
+    /**
+     * Extract entity type label from message type.
+     */
+    private getEntityTypeLabel;
+    /**
+     * Parses a single ListEntities*Response, logs it, and stores it.
+     */
+    private handleListEntity;
+    /**
+     * Decodes a state update, looks up entity info, and emits events.
+     */
+    private handleTelemetry;
+    /**
+     * Handle cover state telemetry.
+     */
+    private handleCoverState;
+    /**
+     * Extract entity key from protobuf fields.
+     */
+    private extractEntityKey;
+    /**
+     * Extract fixed32 field from protobuf fields.
+     */
+    private extractFixed32Field;
+    /**
+     * Extract string field from protobuf fields.
+     */
+    private extractStringField;
+    /**
+     * Extract number field from protobuf fields.
+     */
+    private extractNumberField;
+    /**
+     * Extract telemetry value from protobuf fields.
+     */
+    private extractTelemetryValue;
+    /**
+     * Frames a raw protobuf payload with the 0x00 sentinel, length, and message type.
+     */
+    private frameAndSend;
+    /**
+     * Encode protobuf fields into a buffer.
+     */
+    private encodeProtoFields;
+    /**
+     * Build key field as fixed32 for command requests.
+     */
+    private buildKeyField;
+    /**
+     * Get entity key by ID.
+     *
+     * @param id - The entity ID to look up.
+     *
+     * @returns The entity key or `null` if not found.
+     */
+    getEntityKey(id: string): Nullable<number>;
+    /**
+     * Log all registered entity IDs for debugging.
+     * Logs entities grouped by type with their names and keys.
+     */
+    logAllEntityIds(): void;
+    /**
+     * Get entity information by ID.
+     *
+     * @param id - The entity ID to look up.
+     *
+     * @returns The entity information or `null` if not found.
+     */
+    getEntityById(id: string): Nullable<Entity>;
+    /**
+     * Check if an entity ID exists.
+     *
+     * @param id - The entity ID to check.
+     *
+     * @returns `true` if the entity exists, `false` otherwise.
+     */
+    hasEntity(id: string): boolean;
+    /**
+     * Get all available entity IDs grouped by type.
+     *
+     * @returns Object with entity types as keys and arrays of IDs as values.
+     */
+    getAvailableEntityIds(): Record<string, string[]>;
+    /**
+     * Get all entities with their IDs.
+     *
+     * @returns Array of entities with their corresponding IDs.
+     */
+    getEntitiesWithIds(): Array<Entity & {
+        id: string;
+    }>;
+    /**
+     * Send a ping request to the device to heartbeat the connection.
+     */
+    sendPing(): void;
+    /**
+     * Sends a SwitchCommandRequest for the given entity ID and on/off state.
+     *
+     * @param id - The entity ID (format: "switch-entityname").
+     * @param state - `true` for on, `false` for off.
+     */
+    sendSwitchCommand(id: string, state: boolean): void;
+    /**
+     * Sends a ButtonCommandRequest to press a button entity.
+     *
+     * @param id - The entity ID (format: "button-entityname").
+     */
+    sendButtonCommand(id: string): void;
+    /**
+     * Sends a CoverCommandRequest for the given entity ID.
+     *
+     * @param id - The entity ID (format: "cover-entityname").
+     * @param options - Command options (at least one option must be provided).
+     * @param options.command - The command: "open", "close", or "stop" (optional).
+     * @param options.position - Target position 0.0-1.0 where 0 is closed, 1 is open (optional).
+     * @param options.tilt - Target tilt 0.0-1.0 where 0 is closed, 1 is open (optional).
+     *
+     * @example
+     * ```typescript
+     * // Send a simple command
+     * await client.sendCoverCommand("cover-garagedoor", { command: "open" });
+     *
+     * // Set to specific position
+     * await client.sendCoverCommand("cover-garagedoor", { position: 0.5 }); // 50% open
+     *
+     * // Set position and tilt
+     * await client.sendCoverCommand("cover-blinds", { position: 1.0, tilt: 0.25 });
+     * ```
+     */
+    sendCoverCommand(id: string, options: {
+        command?: "open" | "close" | "stop";
+        position?: number;
+        tilt?: number;
+    }): void;
+    /**
+     * Sends a LightCommandRequest to turn on/off and optionally set brightness.
+     *
+     * @param id - The entity ID (format: "light-entityname").
+     * @param options - Command options.
+     * @param options.state - `true` for on, `false` for off (optional).
+     * @param options.brightness - Brightness level 0.0-1.0 (optional).
+     */
+    sendLightCommand(id: string, options: {
+        state?: boolean;
+        brightness?: number;
+    }): void;
+    /**
+     * Sends a LockCommandRequest to lock or unlock the given entity ID.
+     *
+     * @param id - The entity ID (format: "lock-entityname").
+     * @param command - The command to send: "lock" or "unlock".
+     * @param code - Optional unlock code.
+     */
+    sendLockCommand(id: string, command: "lock" | "unlock", code?: string): void;
+    /**
+     * Encode an integer as a VarInt (protobuf-style).
+     */
+    private encodeVarint;
+    /**
+     * Read a VarInt from buffer at offset; returns [value, bytesRead].
+     */
+    private readVarint;
+    /**
+     * Decode a simple protobuf message into a map of field numbers to values.
+     */
+    private decodeProtobuf;
+}
+export {};