Clarification Needed on Retrieving SwitchBot Hub Status via API

[cosysense-jack]

Current Situation

Hello,

I am working on integrating my SwitchBot devices with a custom application using the SwitchBot API. I noticed that while the API documentation provides comprehensive details on retrieving the status of devices connected to the SwitchBot Hub, it is not immediately clear how to query the status of the Hub itself.

Specifically, I am interested in:

• Confirming whether it is possible to query the status of a SwitchBot Hub directly via the API.
  If possible, I would like to understand the correct API endpoint and payload structure needed to retrieve this information.

• Could you please provide guidance on how to achieve this, or update the documentation with an example if this feature is supported?

Thank you for your assistance!

Best regards,
Jack

Logs

N/A

Configuration

N/A

Environment

• OS:
• Software:
• Node:
• npm:

Additional Context

No response

[hsakoh]

When you refer to "Hub," are you specifically referring to the Hub, Hub Plus, Hub Mini, or Hub 2?

I do not own the Hub or Hub Plus, but I do have both the Hub Mini and Hub 2.

While the Hub Mini is not listed as a target in the Get Device Status API, it can actually be called.
The endpoint is the same as for other devices: /v1.1/devices/{deviceId}/status.

The response is as follows:

{"statusCode":100,"body":{},"message":"success"}

This response is the same for other devices with no fields to retrieve, such as remote buttons.
No Webhooks or other events are triggered.

If you are referring to the Hub 2, documentation should be available here.

[cosysense-jack]

Hi hsakoh,

Thank you for replying! Yeah I am referring to the Hub Mini and I have tried the same endpoint for other devices and I do get the same response as you have pasted.

However, I tried it when the Hub was plugged in and out (even after waiting 10 mins) and I got the same response saying "success". So this is not ideal!

Do you experience the same thing when querying?

[hsakoh]

Yes, it always returns "success" even when offline.
I feel that the GetDeviceStatusAPI is an API that references a snapshot of the status rather than querying the status in real time.

but I digress...
Recently, I've been spending time reverse-engineering apps. I noticed that when I turn off Bluetooth on my smartphone, the app can still retrieve the status, so there seems to be a way for real-time communication with the hub (internally within SwitchBot). It looks like messages are being exchanged via AWS IoT Core (MQTT), probably.

[cosysense-jack]

So it isn't really possible to know if my remote command to a Hub will be a success beforehand? Only afterwards if I check the response and see "Hub Offline"?

That's interesting about real-time communication - not sure how one would tap into that.

[strunker]

This wouldnt scale at all like in a real production setting but... You could always ping the IP in a thread or async loop, and if its offline it would fail to respond. Annoyingly, the IP nor the MAC address are returned from the switchbot API. I also checked and the hub doesnt respond to ssdp discovery which would have been nice. Anyway, if you get the IP and ensure its static, then you can rely on that. If this is some type of app you plan to distribute then this obviously isnt an ideal work around.

The Hub 2 has the ability to subscribe to event webhooks, no clue why they wouldnt have back ported this to the other hubs, but its something to perhaps consider. In the webhook payload data device mac address is included. Which is also annoying because its included here but not when you call the /devices endpoint and get the device status.

All around, the switchbot api is super limited and since its cloud based, relatively slow, and lacks a ton of features. If it were local you wouldnt even be having this problem, because if the hub was down the api server would be as well. Switchbot is also extremely slow updating this api and responding to any type of issue or request so...

Anyway, I digress, good luck to you but I think the only way you are going to solve this problem is with some type of network discovery/tcp test of some kind. Depending on your network equipment, you can ssh to router and extract a list of connected device mac addresses, and compare hub mac to connected device list. This is how things like home assistant know (other than GPS based location) when you leave your house, they track mac on wifi.

[hsakoh]

@cosysense-jack

So it isn't really possible to know if my remote command to a Hub will be a success beforehand?

Yes, that's correct. There's no way to know in advance.

Only afterwards if I check the response and see "Hub Offline"?

No, generally, commands sent to devices through the Hub (those that cannot connect to the internet directly) won't even return a response like "Offline." As long as the command is formally correct, the Command API will always return a success response, whether the Hub or the device is offline. (In my experience, this is always the case with the devices I am aware of.)

[hsakoh]

I provided some incorrect information earlier.
It seems that for the SwitchBot Lock, lock/unlock commands do return a synchronous response.
(However, instead of responses like statusCode 161 (device offline) or 171 (hub device is offline) as described in the interface specifications,
the response is an HTTP 200 OK with the following payload:

{"errorMessage":"2024-08-29T12:29:42.513Z {guid} Task timed out after 10.02 seconds"}

Commands to the circulator fan or to the keypad return successful responses offline.

At least in my experience, I have never seen a statusCode 161 (device offline) or 171 (hub device is offline) response.