📶 Robot Wi-Fi Onboarding¶
Bumper answers the server side of the official app's Wi-Fi setup for MQTT robots. The phone still talks to the robot's setup access point; Bumper does not configure the robot's Wi-Fi. Bumper starts the setup, waits for the robot to connect, and then returns the robot identity to the app.
🔄 Flow¶
sequenceDiagram
participant App as Ecovacs app
participant B as Bumper
participant R as Robot access point
participant M as Robot MQTT client
App->>B: DecodeQrCode / getConfigGroups
App->>B: PreWifiConfig (sck)
B-->>App: {"ret":"ok"}
App->>R: SetApConfig (SSID, password, broker data)
R->>M: join the home Wi-Fi
loop while setup is pending
App->>B: PollSCResult (sck)
B-->>App: pending, or the robot identity
end
M->>B: MQTT login
M->>B: iot/scsync/<poll key>
App->>B: GetGlobalDeviceList (did)
✅ How Bumper completes a setup¶
PreWifiConfig*opens one in-memory setup slot for the app user. The slot lives for 30 minutes.- While the robot has not connected,
PollSCResultanswers the pending shape from the official server:ret: fail,errno: 600,subCode: 1. Bumper adds a shortdebughint, which the app ignores. - A robot authenticates to Bumper's MQTT broker and publishes
iot/scsync/<key>. The setup completes when that key matches the poll key from the same app user's setup flow. - The next poll answers with the robot identity:
{"ret":"ok","did":…,"type":…,"resource":…,"name":…}. - The MQTT login already created the bot record, so
GetGlobalDeviceListreturns the new bot. When the request carries adid, Bumper returns only that device, which is what the app asks for after setup.
The sck sent with PreWifiConfig and the sck sent with PollSCResult can differ.
The app user is the stable link between the two calls, so Bumper does not require the keys to be equal.
After success the app may also call homed/device/move, device/blacklist/check,
member/getBindBenefit, and users/user.do with todo: SetDeviceNick.
Bumper answers those requests; device/move is a no-op because Bumper reports every device in its default home.
🚫 What Bumper does not do¶
- It does not implement the robot's local setup endpoint
(
http://192.168.0.1:8888/rcp.do,SetApConfig). The phone must reach the robot's access point and send the Wi-Fi credentials itself. - It does not create a DID, password, class, or resource for a factory-fresh robot. The robot must already have usable credentials.
- It does not change the robot's certificate trust. Some firmware trusts an embedded Ecovacs CA and will not accept Bumper's generated certificate without a device-side change.
- It supports one setup at a time.
A second
PreWifiConfigreplaces the active slot.
📋 Requirements for a working setup¶
- The app and the robot must reach Bumper's web and MQTT services.
- The robot must trust Bumper's TLS certificate and authenticate with credentials Bumper accepts.
- The robot's class must exist in Bumper's product map, so the device list can describe it.
- The phone must be able to complete the local AP handoff; Bumper cannot do that part.
🔍 Verifying a setup¶
A successful run looks like this in the Bumper log:
PreWifiConfigreturnsok.- The first
PollSCResultreturns the pending shape. - The robot authenticates over MQTT.
- The robot publishes
iot/scsync/<poll key>. - The next
PollSCResultreturns the robot identity. GetGlobalDeviceListwith the newdidreturns one device, and the app opens that robot.
If the poll stays pending, check the robot's MQTT login, its iot/scsync publish,
the app user on both setup calls, and whether the class is present in the product map.
A phone-to-robot AP failure happens before Bumper is involved; Bumper cannot see or repair it.