MG Smarthome Homebridge Integration

This directory contains the custom Homebridge Dynamic Platform Plugin for MG Smarthome.

What It Does

• connects Homebridge to the existing MQTT broker
• subscribes to room-monitoring/+/data
• parses payloads like 01,20.10,47.50
• creates separate HomeKit accessories for temperature and humidity
• restores cached accessories on restart
• prunes cached accessories that are not rediscovered from active MQTT devices
• keeps device freshness state with:
  • stale after 5 minutes
  • offline after 30 minutes

Project Structure

homebridge_integration/
  package.json
  tsconfig.json
  README.md
  src/
    index.ts
    platform.ts
    platformAccessory.ts
    mqttClient.ts
    payloadParser.ts
    sensorTypes.ts
    settings.ts
    configTypes.ts
  test/
    payloadParser.test.ts

Install

1. Install Node.js 18 or newer.
2. Change into homebridge_integration/.
3. Run npm install.
4. Build the plugin with npm run build.
5. Link or install the plugin into the Homebridge environment.

Example local link workflow:

cd homebridge_integration
npm install
npm run build
npm link
cd /var/lib/homebridge
npm link homebridge-mg-smarthome

Homebridge Configuration

The Flask application can generate the JSON block from:

/settings/homebridge/administration

The export endpoints are admin-only and read-only:

• /settings/homebridge/administration
• /settings/homebridge/export.json
• /settings/homebridge/download

Example platform block:

{
  "platform": "MGSmarthome",
  "name": "MG Smarthome",
  "mqtt": {
    "host": "localhost",
    "port": 1883,
    "username": "<user>",
    "password": "<password>",
    "protocol": "mqtt",
    "clientId": "homebridge-mg-smarthome"
  },
  "topics": {
    "data": "room-monitoring/+/data"
  },
  "qos": 0,
  "thresholds": {
    "staleMinutes": 5,
    "offlineMinutes": 30
  },
  "debounceMs": 500,
  "logLevel": "info",
  "debug": false,
  "sensorTypes": {
    "01": {
      "name": "Room Monitoring",
      "values": [
        {
          "index": 1,
          "type": "temperature",
          "service": "TemperatureSensor",
          "characteristic": "CurrentTemperature",
          "unit": "celsius",
          "min": -50,
          "max": 100
        },
        {
          "index": 2,
          "type": "humidity",
          "service": "HumiditySensor",
          "characteristic": "CurrentRelativeHumidity",
          "unit": "percent",
          "min": 0,
          "max": 100
        }
      ]
    }
  }
}

Add that block inside Homebridge config.json under platforms.

logLevel supports:

• error
• warn
• info
• debug
• trace

If logLevel is omitted, the plugin defaults to info. Legacy debug: true remains supported and elevates the effective log level to debug.

Note: The current export design includes real MQTT credential values and does not mask the password in the generated JSON. This matches the current project decision for copy/download export and is not intended as a hardened secret-management model.

Run Locally

1. Start Homebridge with the plugin installed.
2. Verify the log contains:
   • MQTT connection success
   • topic subscription success
   • received MQTT topic logs when logLevel is debug or trace
   • accessory discovery messages
3. Publish a test message:

mosquitto_pub -h 127.0.0.1 -p 1883 -t room-monitoring/24DCC3C11E2C/data -m "01,20.10,47.50"

Expected Apple Home Result

• one temperature accessory for the active device
• one humidity accessory for the active device
• both accessories update from MQTT payloads

Current design note: The plugin currently uses multiple HomeKit accessories per physical device rather than one accessory with multiple services.

Tests

Run the TypeScript parser tests with:

npm test

Flask Export

The export is read-only and does not modify Homebridge files directly.