Homebridge ESPHome MTR-1 Plugin

A Homebridge plugin to integrate the Apollo Automation MTR-1 mmWave multi-sensor with Apple HomeKit via ESPHome.

Features

This plugin exposes the following sensors from your Apollo MTR-1 to HomeKit:

• Presence Sensor - Detects any target (moving or still) using mmWave radar
• Motion Sensor - Detects moving targets only
• Light Sensor - Ambient light level (LUX) from LTR390 sensor
• Temperature Sensor - Room temperature from DPS310 sensor
• Pressure Sensor (optional) - Barometric pressure from DPS310 sensor
• Target Count (optional) - Shows number of detected targets (0-3)
• Individual Targets (optional) - Three separate sensors for individual target detection

Prerequisites

• A working Homebridge installation
• Apollo Automation MTR-1 sensor running ESPHome
• ESPHome device accessible on your network

Installation

Option 1: Install from Homebridge UI

1. Search for "homebridge-esphome-mtr1" in the Homebridge UI
2. Click Install

Option 2: Manual Installation

npm install -g homebridge-esphome-mtr1

Option 3: Manual Installation (Raspberry Pi with hb-service)

IMPORTANT: For Raspberry Pi running Homebridge Config UI (hb-service), install to /var/lib/homebridge:

# Transfer the package to your Pi
scp homebridge-esphome-mtr1-1.0.0.tgz pi@YOUR_PI_IP:~/

# SSH into your Pi
ssh pi@YOUR_PI_IP

# Install to the homebridge service directory
cd /var/lib/homebridge
npm install ~/homebridge-esphome-mtr1-1.0.0.tgz

# Restart Homebridge via web interface or:
hb-service restart

Do NOT use npm install -g - this will install to the wrong location and the plugin won't be found when restarting via the web interface.

Configuration

Add the platform to your Homebridge config.json:

{
  "platforms": [
    {
      "platform": "ESPHomeMTR1",
      "devices": [
        {
          "name": "Living Room Sensor",
          "host": "192.168.1.100",
          "port": 6053,
          "encryptionKey": "your-base64-encryption-key-from-esphome",
          "sensors": {
            "occupancy": true,
            "motion": true,
            "light": true,
            "temperature": true,
            "pressure": false,
            "targetCount": false,
            "individualTargets": false
          }
        }
      ]
    }
  ]
}

Configuration Parameters

| Parameter | Required | Default | Description | |-----------|----------|---------|-------------| | platform | Yes | - | Must be "ESPHomeMTR1" | | devices | Yes | - | Array of MTR-1 devices | | devices[].name | Yes | - | Display name for the device | | devices[].host | Yes | - | IP address or hostname of ESPHome device | | devices[].port | No | 6053 | ESPHome native API port | | devices[].password | No | - | ESPHome API password (deprecated) | | devices[].encryptionKey | No | - | ESPHome encryption key (recommended) | | devices[].sensors.occupancy | No | true | Enable presence/occupancy sensor | | devices[].sensors.motion | No | true | Enable motion sensor | | devices[].sensors.light | No | true | Enable light sensor | | devices[].sensors.temperature | No | true | Enable temperature sensor | | devices[].sensors.pressure | No | false | Enable pressure sensor | | devices[].sensors.targetCount | No | false | Enable target count sensor | | devices[].sensors.individualTargets | No | false | Enable individual target sensors |

ESPHome Configuration

Your MTR-1 must be running ESPHome with the native API enabled. The entity names in your ESPHome configuration will be automatically detected.

Example ESPHome configuration snippet:

api:
  encryption:
    key: "your-encryption-key-here"

# Your MTR-1 sensor configuration
# The plugin will automatically detect entities containing:
# - "presence" or "occupancy" for presence detection
# - "moving_target" or "motion" for motion detection
# - "ltr390_light" or "lux" for light level
# - "dps310_temperature" or "temperature" for temperature
# - "dps310_pressure" or "pressure" for barometric pressure
# - "target_count" for target count
# - "target_1", "target_2", "target_3" for individual targets

Troubleshooting

Connection Issues

• Verify your ESPHome device is accessible at the configured IP/hostname
• Check that the port (default 6053) is correct
• Ensure password and encryption key match your ESPHome configuration
• Check Homebridge logs for connection errors

Sensors Not Appearing

• Enable debug logging in Homebridge to see entity discovery
• Verify the entity names in your ESPHome configuration
• You may need to adjust the entity name matching in handleStateUpdate() method

Enable Debug Logging

Set Homebridge to debug mode to see detailed logs:

homebridge -D

Development

# Build TypeScript
npm run build

# Watch for changes
npm run watch

License

MIT

Credits

• Apollo Automation for the MTR-1 sensor
• ESPHome for the firmware platform
• esphome-client for the API client