homebridge-sharp-air-purifier-mqtt

Homebridge platform plugin for Sharp air purifiers that directly controls the device using the local ECHONET Lite protocol through echonetlite2mqtt.

This plugin is designed for local LAN control. It talks to your air purifier through echonetlite2mqtt and MQTT, so it does not require the Cocoro Air cloud API, Cocoro Air credentials, or internet access after your local network is set up.

It creates one HomeKit accessory with an AirPurifier service, optional humidity/temperature sensors, and optional humidifier control.

Requirements

• Homebridge 1.6+
• Node.js 18+
• A running echonetlite2mqtt instance
• MQTT broker reachable from Homebridge

No Cocoro Air API token, cloud account, or remote service is required.

This plugin was tested with a Sharp airCleaner device whose MQTT base topic looks like:

echonetlite2mqtt/elapi/v2/devices/<deviceId>

Install

For local packaging:

npm install
npm test
npm pack

Then install the generated .tgz on your Homebridge host:

npm install -g /path/to/homebridge-sharp-air-purifier-mqtt-0.1.0.tgz

Configuration

{
  "platforms": [
    {
      "platform": "SharpAirPurifierMqtt",
      "name": "Sharp Air Purifier MQTT",
      "brokerUrl": "mqtt://YOUR_MQTT_HOST:1883",
      "deviceId": "YOUR_ECHONETLITE2MQTT_DEVICE_ID",
      "topicPrefix": "echonetlite2mqtt/elapi/v2/devices",
      "accessoryName": "Sharp Air Purifier",
      "enableHumiditySensor": true,
      "enableTemperatureSensor": false,
      "enableAirQualitySensor": false,
      "enableRoomLightSensor": false,
      "refreshIntervalSeconds": 60,
      "enableHumidifierService": true,
      "enableModeSwitches": true,
      "nightModeSwitchName": "Night Mode",
      "pollenModeSwitchName": "Pollen Mode",
      "realizeModeSwitchName": "Realize Mode"
    }
  ]
}

Options

| Option | Default | Description | | --- | --- | --- | | brokerUrl | mqtt://YOUR_MQTT_HOST:1883 | MQTT broker URL. | | username / password | unset | MQTT credentials, if needed. | | clientId | random | Optional MQTT client ID. | | deviceId | required | echonetlite2mqtt air cleaner device ID. | | topicPrefix | echonetlite2mqtt/elapi/v2/devices | MQTT topic prefix before the device ID. | | accessoryName | Sharp Air Purifier | Name shown in HomeKit. | | enableHumiditySensor | true | Reads humidity from Sharp unknown_F1. | | enableTemperatureSensor | false | Reads temperature from Sharp unknown_F1. | | enableAirQualitySensor | false | Reads PM2.5 from Sharp unknown_F1 byte 28. | | enableRoomLightSensor | false | Exposes room light state from Sharp unknown_F2 byte 20 as a HomeKit light sensor. Uses 100 lux for on and 0.0001 lux for off. | | refreshIntervalSeconds | 60 | Requests unknown_F1 and unknown_F2 on this interval for PM2.5, humidity, temperature, filter state, and humidifier runtime state. Set to 0 to disable polling. | | enableHumidifierService | true | Exposes humidifier ON/OFF control. | | enableModeSwitches | true | Exposes Night, Pollen, and Realize mode switches. | | nightModeSwitchName | Night Mode | Name for the Night switch. | | pollenModeSwitchName | Pollen Mode | Name for the Pollen switch. | | realizeModeSwitchName | Realize Mode | Name for the Realize switch. |

Humidifier Runtime State

When enableHumidifierService is enabled, the plugin reads Sharp unknown_F2 to expose humidifier runtime details in HomeKit:

| HomeKit water level | Meaning | | --- | --- | | 100% | Water is available. | | 10% | Probably low or empty, but the device is not currently blocked from humidifying. | | 0% | The device cannot humidify because of the water supply state. This also sets StatusFault. |

RelativeHumidityHumidifierThreshold is fixed at 55% for HomeKit. The device itself still controls whether it is idle or actively humidifying.

Development

npm install
npm test

The tests cover payload generation, Sharp ECHONET property parsing, and the HomeKit-to-MQTT command path.