@akospasztor/homebridge-create-ceiling-fan 1.0.0

package/dist/platform.js

@@ -0,0 +1,108 @@
+import { CreateCeilingFanAccessory } from './platformAccessory.js';
+import { PLATFORM_NAME, PLUGIN_NAME } from './settings.js';
+/**
+ * CreateCeilingFanPlatform: the platform implementation for CREATE ceiling fans.
+ *
+ * This class contains the platform implementation and follows the Homebridge
+ * plugin development recommendations.
+ *
+ * @see https://developers.homebridge.io/#/
+ * @see https://github.com/homebridge/homebridge-plugin-template/blob/latest/README.md
+ */
+export class CreateCeilingFanPlatform {
+    log;
+    config;
+    api;
+    /** The HomeKit Accessory Protocol (HAP) service. */
+    Service;
+    /** The HomeKit Accessory Protocol (HAP) characteristic. */
+    Characteristic;
+    /** Used for tracking the restored cached accessories. */
+    accessories = new Map();
+    /** Used for tracking the cached UUIDs. */
+    discoveredCacheUUIDs = [];
+    /**
+     * The CreateCeilingFanPlatform constructor.
+     *
+     * Note: This constructor is called by Homebridge.
+     *
+     * @param log    The logging object.
+     * @param config The platform configuration object.
+     * @param api    The API object.
+     */
+    constructor(log, config, api) {
+        this.log = log;
+        this.config = config;
+        this.api = api;
+        this.Service = api.hap.Service;
+        this.Characteristic = api.hap.Characteristic;
+        // When this event is fired, it means Homebridge has restored all cached
+        // accessories from the 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', () => {
+            this.discoverDevices();
+        });
+    }
+    /**
+     * This function is invoked when Homebridge restores cached accessories from
+     * the disk at startup. It should be used to set up event handlers for
+     * characteristics and update respective values.
+     *
+     * @param accessory The accessory restored from the disk at startup.
+     */
+    configureAccessory(accessory) {
+        this.log.info('Loading accessory from cache:', accessory.displayName);
+        // Add the restored accessory to the accessories cache to track if it has
+        // already been registered
+        this.accessories.set(accessory.UUID, accessory);
+    }
+    /**
+     * Register discovered accessories.
+     *
+     * Accessories must only be registered once, previously created accessories
+     * must not be registered again to prevent "duplicate UUID" errors.
+     */
+    discoverDevices() {
+        // Loop over the devices and register each one if it has not already been registered
+        for (const device of this.config.devices) {
+            // Generate a unique id for the accessory
+            // Note: this should be generated from something globally unique, but
+            // constant, for example, the device serial number or MAC address
+            const uuid = this.api.hap.uuid.generate(device.id);
+            // 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.get(uuid);
+            if (existingAccessory) {
+                this.log.info('Restoring existing accessory from cache: %s (device id: %s)', existingAccessory.displayName, existingAccessory.context.device.id);
+                // Update the `accessory.context` in case the plugin configuration (in the config.json) has changed
+                existingAccessory.context.device = device;
+                this.api.updatePlatformAccessories([existingAccessory]);
+                // Create the accessory handler for the restored accessory
+                new CreateCeilingFanAccessory(this, existingAccessory);
+            }
+            else {
+                this.log.info('Adding new accessory: %s (device id: %s)', device.name, device.id);
+                // Create a new accessory
+                const accessory = new this.api.platformAccessory(device.name, uuid);
+                // Store a copy of the device object in the `accessory.context`
+                accessory.context.device = device;
+                // Create the accessory handler for the newly created accessory
+                new CreateCeilingFanAccessory(this, accessory);
+                // Link the accessory to the platform
+                this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [accessory]);
+            }
+            // Push into discoveredCacheUUIDs
+            this.discoveredCacheUUIDs.push(uuid);
+        }
+        // Remove existing cached accessories from Homebridge if they are no longer present
+        for (const [uuid, accessory] of this.accessories) {
+            if (!this.discoveredCacheUUIDs.includes(uuid)) {
+                this.log.info('Removing existing accessory from cache: %s (device id: %s)', accessory.displayName, accessory.context.device.id);
+                this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [accessory]);
+            }
+        }
+    }
+}
+//# sourceMappingURL=platform.js.map

package/dist/platform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.js","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"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"}

package/dist/platformAccessory.d.ts

@@ -0,0 +1,309 @@
+import type { CharacteristicValue, PlatformAccessory } from 'homebridge';
+import type { CreateCeilingFanPlatform } from './platform.js';
+/**
+ * CreateCeilingFanAccessory: the accessory implementation for CREATE ceiling fans.
+ *
+ * This class contains the accessory implementation and follows the Homebridge
+ * plugin development recommendations.
+ *
+ * #### Exposed services and characteristics
+ *
+ * | Service     | Characteristics                                  |
+ * | ------------| ------------------------------------------------ |
+ * | `Fanv2`     | `Active`, `Rotation Direction`, `Rotation Speed` |
+ * | `Lightbulb` | `On`                                             |
+ *
+ * Note: the `Lightbulb` service is only exposed if the accessory has been
+ * configured with the light option enabled.
+ *
+ * #### Fan rotation speed representation
+ *
+ * CREATE fans have speed settings ranging from `1` (lowest) to `6` (highest).
+ * The HomeKit UI slider for the fan rotation speed provides a value from `1`
+ * to `100` and `0` means the fan is turned off. The slider steps can be
+ * configured to a desired value via the `Min Step` Characteristic. This works
+ * well e.g. for Dyson devices where the speed settings ranges from `1` to `10`.
+ * In this case the `Min Step` Characteristic can be configured to `10`,
+ * resulting in a nice user experience where the `0` - `100` UI slider is
+ * divided into 10 steps. However, this does not work well for CREATE fans with
+ * 6 speed steps. In order to provide smooth user experience, the following
+ * representation is implemented:
+ *
+ * - The UI slider is configured with the default `Min Step` Characteristic of
+ *   `1`. This provides smooth and fluid user input and slider operation.
+ * - The following UI slider inputs represent the different speed settings of
+ *   the fan:
+ *   | Device fan speed | Corresponding UI slider value | User input range on the slider |
+ *   | :--------------: | :---------------------------: | :----------------------------: |
+ *   |        1         |              10               |            1 - 19              |
+ *   |        2         |              30               |           20 - 39              |
+ *   |        3         |              50               |           40 - 59              |
+ *   |        4         |              70               |           60 - 79              |
+ *   |        5         |              90               |           80 - 94              |
+ *   |        6         |             100               |           95 - 100             |
+ *
+ *  - When the user operates the slider, a debouncing timer with the value of
+ *    {@link fanSetSpeedDebouncePeriod} member is set. When the timer fires, the
+ *    current state of the slider value is converted to the nearest value that
+ *    corresponds to the device fan speed. The purpose of the debounce timer is
+ *    to provide great user experience. Without the debounce timer, every moment
+ *    the user slides the finger would result in generating lots of events -
+ *    making the slider jump around immediately, without waiting for the user to
+ *    finish adjusting the speed.
+ *
+ *    ```text
+ *     UI slider    │ Fan speed
+ *     input value  │ value
+ *     ─────────────┼──────────────
+ *     ┌──────┐     │
+ *     │ 100 ─┼─────┼─► Fan speed 6
+ *     │      │ ▲   │
+ *     │  95  ├─┘   │
+ *     │  94  ├─┐   │
+ *     │      │ ▼   │
+ *     │  90 ─┼─────┼─► Fan speed 5
+ *     │      │ ▲   │
+ *     │  80  ├─┘   │
+ *     │  79  ├─┐   │
+ *     │      │ ▼   │
+ *     │  70 ─┼─────┼─► Fan speed 4
+ *     │      │ ▲   │
+ *     │  60  ├─┘   │
+ *     │  59  ├─┐   │
+ *     │      │ ▼   │
+ *     │  50 ─┼─────┼─► Fan speed 3
+ *     │      │ ▲   │
+ *     │  40  ├─┘   │
+ *     │  39  ├─┐   │
+ *     │      │ ▼   │
+ *     │  30 ─┼─────┼─► Fan speed 2
+ *     │      │ ▲   │
+ *     │  20  ├─┘   │
+ *     │  19  ├─┐   │
+ *     │      │ ▼   │
+ *     │  10 ─┼─────┼─► Fan speed 1
+ *     │      │ ▲   │
+ *     │   1  ├─┘   │
+ *     │   0 ─┼─────┼─► Fan off
+ *     └──────┘     │
+ *    ```
+ *
+ * #### Fan rotation direction representation
+ *
+ * The rotation of the device as seen from standing below the fan follows the
+ * HomeKit rotation representation.
+ *
+ * | Device direction raw value | HomeKit representation | Fan operation                           |
+ * | -------------------------- | ---------------------- | --------------------------------------- |
+ * | `forward` (default)        | Counter-clockwise      | Fan blows downwards (i.e. summer mode)  |
+ * | `reverse`                  | Clockwise              | Fan blows upwards (i.e. winter mode)    |
+ *
+ * #### Device communication
+ *
+ * The fan is a Tuya-compatible device and its firmware is mildly put: not the best.
+ * Among other issues, devices with these firmware are known to stop responding
+ * to commands, randomly drop connection, etc (see e.g.
+ * https://github.com/jasonacox/tinytuya/discussions/443 and
+ * https://github.com/moifort/homebridge-create-fan/issues/18).
+ *
+ * To provide reliable operation via HomeKit, this plugin implements the device
+ * communication the following way:
+ *
+ * - The device accepts one connection at a time. Therefore, a mutex with a
+ *   waiting queue is used for ensuring that only one command is sent to the
+ *   device at a time. For detailed description refer to: {@link Mutex}.
+ * - The device state is cached. Whenever the device state is requested by
+ *   HomeKit (e.g. the user opens up the Home app), the implementation
+ *   immediately returns the requested value from the cache.
+ * - The status of the device is periodically (defined by
+ *   {@link getDeviceStatusPeriod}) queried from the device. After obtaining the
+ *   device status, the device state cache as well as the HomeKit
+ *   Characteristics are automatically updated.
+ * - If the device fails to respond to the get status request, the polling
+ *   period is reduced significantly (defined by
+ *   {@link getDeviceStatusFastRetryPeriod}), so that the attempt is retried
+ *   quickly.
+ * - The communication with the device happens in a synchronous way, supported
+ *   by the mutex queue and timeout mechanism. This seems to provide the most
+ *   reliable communication with the device.
+ *
+ * Communication failure tends to happen when attempting to control the device
+ * via HomeKit right after using the device's physical remote. The device used
+ * for development & testing (CREATE Wind Calm model purchased in 2025) seemed
+ * to always recover from a failed communication latest after a few retry
+ * attempts.
+ *
+ * @see https://developers.homebridge.io/#/
+ * @see [Fanv2 service type](https://developers.homebridge.io/#/service/Fanv2)
+ * @see [Lightbulb service type](https://developers.homebridge.io/#/service/Lightbulb)
+ */
+export declare class CreateCeilingFanAccessory {
+    private readonly platform;
+    private readonly accessory;
+    private fanService;
+    private lightService;
+    private getDeviceStatusTimer;
+    private fanSetSpeedDebounceTimer;
+    private deviceCommunicator;
+    private mutex;
+    private isGetStatusInProgress;
+    private readonly fanSetSpeedDebouncePeriod;
+    private readonly getDeviceStatusFastRetryPeriod;
+    private readonly getDeviceStatusPeriod;
+    private readonly getDeviceStatusConnectTimeout;
+    private readonly getDeviceStatusReadTimeout;
+    private readonly fanRotationSpeedNormalized;
+    private state;
+    /**
+     * Constructor for the CreateCeilingFanAccessory object.
+     *
+     * @param platform  The plugin platform object.
+     * @param accessory The homebridge platform accessory object.
+     */
+    constructor(platform: CreateCeilingFanPlatform, accessory: PlatformAccessory);
+    /**
+     * Handle the get requests from HomeKit to get the current value of the Fanv2 Active characteristic
+     *
+     * @return The Fanv2 Active characteristic value from the device state cache.
+     */
+    handleFanActiveStateGet(): Promise<CharacteristicValue>;
+    /**
+     * Handle the set requests from HomeKit to set the device with the Fanv2 Active characteristic value
+     *
+     * @param value The Fanv2 Active characteristic value to be set.
+     */
+    handleFanActiveStateSet(value: CharacteristicValue): Promise<void>;
+    /**
+     * Handle the get requests from HomeKit to get the current value of the Fanv2 Rotation Speed characteristic
+     *
+     * @return The Fanv2 Rotation Speed characteristic value from the device state cache.
+     */
+    handleFanRotationSpeedGet(): Promise<CharacteristicValue>;
+    /**
+     * Handle the set requests from HomeKit to set the device with the Fanv2 Rotation Speed characteristic value
+     *
+     * @param value The Fanv2 Rotation Speed characteristic value to be set.
+     */
+    handleFanRotationSpeedSet(value: CharacteristicValue): Promise<void>;
+    /**
+     * Handle the get requests from HomeKit to get the current value of the Fanv2 Rotation Direction characteristic
+     *
+     * @return The Fanv2 Rotation Direction characteristic value from the device state cache.
+     */
+    handleFanRotationDirectionGet(): Promise<CharacteristicValue>;
+    /**
+     * Handle the set requests from HomeKit to set the device with the Fanv2 Rotation Direction characteristic value
+     *
+     * @param value The Fanv2 Rotation Direction characteristic value to be set.
+     */
+    handleFanRotationDirectionSet(value: CharacteristicValue): Promise<void>;
+    /**
+     * Handle the get requests from HomeKit to get the current value of the Lightbulb On characteristic
+     *
+     * @return The Lightbulb On characteristic value from the device state cache.
+     */
+    handleLightOnGet(): Promise<CharacteristicValue>;
+    /**
+     * Handle the set requests from HomeKit to set the device with the Lightbulb On characteristic value
+     *
+     * @param value The Lightbulb On characteristic value to be set.
+     */
+    handleLightOnSet(value: CharacteristicValue): Promise<void>;
+    /**
+     * Get device status.
+     *
+     * This method reads the status of the device periodically and updates the
+     * accessory state after completing the operation. The actual communication
+     * is carried out with a timeout mechanism, so that an unresponsive device
+     * will not make the plugin and HomeKit unresponsive. If the communication
+     * fails, the periodic timer will be set with a shorter timeout so that the
+     * next retry attempt happens fast. After the communication with the device
+     * is recovered, the period will be reset to the original period value.
+     *
+     * The function can be called in two ways:
+     *
+     * 1. Calling it with `await`: the method starts the reading operation and
+     *    waits (i.e. blocks) until the reading has been completed (or timed out).
+     * 2. Simply calling it (without `await`): the method starts the reading
+     *    operation and returns right afterwards, not waiting for the reading
+     *    to be completed. This is used when handling accessory GET requests
+     *    from HomeKit. Get requests should return as fast as possible, because
+     *    long delays will result in HomeKit being unresponsive and a bad user
+     *    experience in general.
+     *
+     * If the function is called again while there is already an ongoing read
+     * operation, the reading will simply be skipped - the accessory status will
+     * be updated anyway after executing the already ongoing reading operation.
+     * This can happen e.g. when a periodic read operation is already in place
+     * and a GET request arrives from HomeKit at the same time.
+     */
+    private getDeviceStatus;
+    /**
+     * Set device value.
+     *
+     * This method sends a command to the device to set the device into the
+     * required state. Only one parameter can be set at a time.
+     *
+     * @param dps   The data point index of the device to be set.
+     * @param value The value to be set.
+     */
+    private setDeviceValue;
+    /**
+     * Wait for a promise to be resolved within a given timeout.
+     *
+     * @param promise The promise to be resolved within a given timeout.
+     * @param ms      The timeout in [ms] within the promise should be resolved.
+     * @return        The resolved promise if it gets resolved within the timeout, otherwise reject the promise.
+     */
+    private waitForPromiseWithTimeout;
+    /**
+     * Throw a HomeKit No Response status if the accessory state is invalid.
+     */
+    private throwErrorIfDeviceUnresponsive;
+    /**
+     * Update the accessory state with the values received from the device.
+     *
+     * @param status The raw data points object received from the device.
+     */
+    private updateDeviceState;
+    /**
+     * Update all accessory service characteristics based on the accessory state.
+     */
+    private updateAccessoryState;
+    /**
+     * Convert the fan active state of the accessory to Fanv2 Active characteristic value.
+     *
+     * @return The Fanv2 Active characteristic value.
+     */
+    private fanActiveValueToCharacteristicValue;
+    /**
+     * Convert the fan rotation speed of the accessory to Fanv2 Rotation Speed characteristic value.
+     *
+     * @return The Fanv2 Rotation Speed characteristic value.
+     */
+    private fanRotationSpeedValueToCharacteristicValue;
+    /**
+     * Convert the fan rotation direction of the accessory to Fanv2 Rotation Direction characteristic value.
+     *
+     * @return The Fanv2 Rotation Direction characteristic value.
+     */
+    private fanRotationDirectionValueToCharacteristicValue;
+    /**
+     * Convert the light on state of the accessory to Lightbulb On characteristic value.
+     *
+     * @return The Lightbulb On characteristic value.
+     */
+    private lightOnValueToCharacteristicValue;
+    /**
+     * Adjust the rotation speed input value.
+     *
+     * This method is used for converting the input state of the slider value to
+     * the nearest value that corresponds to the device fan speed.
+     *
+     * See the {@link CreateCeilingFanAccessory} class description for more details.
+     *
+     * @param value The input value of the rotation speed.
+     * @return The adjusted value of the rotation speed.
+     */
+    private adjustInputRotationSpeed;
+}