homebridge-dji-romo

homebridge-dji-romo is a Homebridge dynamic platform plugin for exposing a DJI Romo robot vacuum to Apple Home.

Phase 1 is intentionally mock-first: the plugin is fully usable without a DJI connection. The HomeKit implementation talks only to the RomoClient interface, so the real DJI client can be completed later without changing the platform or accessory code.

Matter robot vacuum mode is experimental

Homebridge 2.1.x exposes an experimental Matter plugin API. This plugin can opt into that path with:

"exposureMode": "matter"

Requirements for Matter mode:

• Homebridge 2.1.0 or newer
• Matter enabled in the Homebridge bridge or child bridge config
• Node 22 or 24 as required by Homebridge 2.1.x

Matter mode exposes one RoboticVacuumCleaner accessory with RVC Run Mode, RVC Operational State, Power Source, Identify, and optional Service Area clusters. It is intended to be tested with mock mode first. It does not make the real DJI protocol functional.

Battery state is mapped to Matter PowerSource as a best-effort cluster. Homebridge 2.1.x types expose this state API, but RVC battery rendering in Apple Home still needs end-to-end verification.

Homebridge publishes Matter robot vacuums as external Matter accessories. The child-bridge Matter QR code can appear as an empty bridge in Apple Home; the vacuum itself may have a separate pairing code in the Homebridge logs or Matter accessory UI. Look for log lines such as Commissioning codes for DJI Romo or External Matter accessory published: DJI Romo.

Real DJI mode is not functional yet

Real DJI mode is scaffold-only. The plugin does not currently know verified DJI Home MQTT topics, authentication rules, command payloads, or status payloads for Romo.

When mockMode is false, DjiRomoClient fails clearly instead of guessing a productive API. This is deliberate. MQTT support must be enabled only after real DJI Home MQTT captures or documentation confirm the exact mapping.

Every unknown protocol area is marked in code with:

TODO: Verify against actual DJI Home MQTT protocol for Romo.

Architecture

• RomoClient is the public robot interface used by all HomeKit code.
• MockRomoClient implements the full Phase 1 behavior without network access.
• DjiRomoClient contains only the prepared MQTT scaffold and TODO placeholders.
• DjiRomoPlatform selects the client with config.mockMode.
• RomoAccessory maps HomeKit services to RomoClient methods.
• RomoMatterAccessory maps Matter robot vacuum clusters to RomoClient methods.

No DJI-specific topic, auth, or payload logic appears in the HomeKit classes.

Mock Mode

Mock mode is enabled by default and requires no credentials.

It simulates:

• Start cleaning
• Pause and resume
• Stop
• Return to dock
• Charging and battery drain
• Room cleaning
• Locate/beeper command
• Error states for tests

HomeKit Mapping

The plugin uses HomeKit-compatible services because Homebridge does not expose a native RobotVacuum service for Apple Home.

• Fanv2
  • Active = 1: start or resume cleaning
  • Active = 0: pause cleaning
  • RotationSpeed: suction level, 0-100
• BatteryService
  • BatteryLevel
  • ChargingState
  • StatusLowBattery
• Optional switches
  • Return to Dock
  • Pause
  • Locate
• Room switches
  • One separate Switch accessory per configured room
  • Turning on a room switch calls cleanRoom(room.id)
  • The switch resets when room cleaning finishes

Matter Mapping

Set exposureMode to matter to expose only the Matter robot vacuum, or both to keep the legacy HomeKit fan/switch model too.

• RvcRunMode
  • Idle
  • Cleaning
• RvcOperationalState
  • Stopped
  • Running
  • Paused
  • Seeking Charger
  • Charging
  • Docked
  • Error
• PowerSource
  • Battery percentage
  • Battery warning/critical state
  • Charging/not charging
  • Best-effort: Homebridge 2.1.x may not expose this cluster for every RVC controller path yet
• Identify
  • Calls locate()
• Optional ServiceArea
  • Uses configured rooms when enableMatterServiceArea is true
  • rooms[].matterAreaId can be set explicitly
  • If omitted, a stable numeric Matter area id is derived from rooms[].id

Room selection is intentionally conservative: the current RomoClient only supports one cleanRoom(roomId) call at a time, so a Matter request for multiple selected areas uses the first selected room when cleaning starts.

Installation

npm install
npm run build

For Homebridge development:

npm link
homebridge -D

Example Configuration

{
  "platform": "DjiRomo",
  "name": "DJI Romo",
  "exposureMode": "hap",
  "mockMode": true,
  "userToken": "",
  "deviceSn": "",
  "mqttHost": "",
  "mqttPort": 8883,
  "clientId": "",
  "pollIntervalSeconds": 15,
  "enableRoomSwitches": true,
  "enableDockSwitch": true,
  "enablePauseSwitch": true,
  "enableLocateSwitch": true,
  "enableMatterServiceArea": true,
  "debug": false,
  "rooms": [
    {
      "id": "kitchen",
      "name": "Kueche",
      "matterAreaId": 1001
    },
    {
      "id": "living_room",
      "name": "Wohnzimmer",
      "matterAreaId": 1002
    }
  ]
}

mockMode defaults to true in config.schema.json.

Homebridge UI Configuration

In the Homebridge UI, add a platform named DjiRomo. Leave Mock Mode enabled for Phase 1 testing.

Only disable mock mode after the real MQTT mapping has been verified and implemented.

Security Concept

• The plugin only works with the configured deviceSn.
• No global wildcard MQTT subscriptions are implemented.
• No camera, microphone, video stream, map, or floorplan features are implemented.
• No serial numbers, tokens, or client IDs are logged in full.
• Debug logs use the same secret redaction as normal logs.
• Credentials are not persisted anywhere except Homebridge configuration.
• Real MQTT reconnect logic is scaffolded with exponential backoff.
• Bad authentication must be handled in DjiRomoClient after the real auth flow is verified.

Adjusting DJI MQTT Mapping

Only update the DJI protocol layer:

• DjiRomoClient.buildAuthOptions
• DjiRomoClient.getCommandTopic
• DjiRomoClient.getStatusTopic
• DjiRomoClient.buildCommandPayload
• DjiRomoClient.parseStatusPayload

Do not change RomoAccessory or DjiRomoPlatform for DJI protocol details.

Before enabling real mode, verify:

• MQTT host and TLS requirements
• Authentication fields
• Device-specific topic names
• Command payload format
• Status payload format
• Error payload format
• Reconnect behavior after token expiry

Testing

npm run test

The tests cover:

• Mock client lifecycle and state transitions
• Battery drain, docking, charging, room cleaning, and errors
• HomeKit status mapping
• Fanv2 command mapping
• Matter robot vacuum status mapping
• Secret redaction

Troubleshooting

If Homebridge starts but no accessory appears, confirm the platform config uses:

"platform": "DjiRomo"

If real mode fails, that is expected for now. Keep mockMode set to true.

If room switches do not appear, check that enableRoomSwitches is true and every room has both id and name.

Known Limitations

• Real DJI MQTT mode is not implemented yet.
• No maps, camera, microphone, video, floorplans, or room discovery.
• Room IDs must be supplied manually in config.
• Fan speed is a HomeKit suction-level approximation.
• Matter clean modes and multi-room cleaning need a richer verified Romo command model before being exposed as real capabilities.
• Mock mode is a simulator, not a source of verified DJI protocol behavior.