Technical Overview

This iRobot plugin for HS4 connects to your iRobot cleaning robots directly over your local network. Each robot hosts an MQTT broker which enables control and status monitoring over the LAN. However, in order to connect to the robot's MQTT broker, the robot's unique ID (BLID) and password are required. The BLID can be retrieved using the LAN discovery protocol, but at the moment the only known way to retrieve the password is to authenticate against the iRobot cloud service. Once authenticated, it's possible to retrieve a list of all robots registered to your account, including their passwords.

Robot passwords change each time a robot is factory reset.

LAN Discovery Protocol

iRobot products can be discovered on the LAN by sending a UDP broadcast message to the subnet's broadcast address on port 5678. The discovery packet should contain the ASCII encoding of "irobotmcs".

Upon successful receipt, each iRobot product on the LAN should reply to the requester with a UDP message containing some ASCII-encoded JSON, which includes details such as the robot's IP address, MAC address, BLID, SKU, and capabilities.

If you already know the IP address of a robot, it's also possible to retrieve the same discovery reply by sending the same "irobotmcs" message directly to the robot on UDP port 5678.

MQTT Connection

Once the BLID and password are known, you can connect to the robot's MQTT broker on port 8883 using TLS. The MQTT username must be the robot's BLID, and the MQTT password must be the robot's password. It's also necessary to provide the robot's BLID as your MQTT Client ID.

Each robot supports only one LAN MQTT connection at a time. If a connection is already established, subsequent connection attempts will be refused.

Once connected successfully, the robot will send JSON-encoded status updates on the $aws/things/{BLID}/shadow/update topic. Each MQTT message is a delta; messages may not contain the robot's full state and it's necessary to track state in memory and apply new state updates as patches to the state tracked in memory.

The robot will also send Wi-Fi statistics (e.g. signal strength) on the wifistat topic.

It's not necessary to explicitly subscribe to topics in order to receive messages from the robot's internal MQTT broker. However, the official iRobot Home mobile app still explicitly subscribes to the shadow update topic.

To control the robot, an MQTT client should publish a JSON-encoded message to the cmd topic. Commands should contain at least 3 keys: command is a string containing the command you're sending, time is the current Unix time as a number, and initiator should be a string "localApp". Known commands are:

• start - Start a cleaning job (same as pushing the "Clean" button on the robot)
• stop - Abort an in-progress cleaning job
• pause - Pause an in-progress cleaning job
• resume - Resume a previously paused cleaning job
• dock - Send the robot back to its dock (only possible when paused or no ongoing job)
• find - Make the robot play a sound
• train - Start a mapping run
• reset - Reboot the robot
• evac - Empty the robot's bin (only possible on Clean Base)

Some commands such as start may also take some extra parameters to customize the command.