Describe The Bug:

To Reproduce:

Expected behavior:

Screenshots:

Device Model:

Hub Mini, Curtains, remote (e.g., all products).

SwitchBotAPI

• Use Case:
  Will this api documentation work for talking to your hub mini locally? Controlling the devices locally without the cloud is extremely important.

Describe The Bug:

I added a infrared remote to the mini hub to control a Speaker. It did not work correctly in homebridge-switchbot-openapi. I noticed it mentioned an incorrect device id. I then tried it directly from the api and the device id looks weird there too:

{"statusCode":100,"body":{"deviceList":[{"deviceId":"DD58D5B7FB3C","deviceName":"Hub Mini 3C","deviceType":"Hub Mini","hubDeviceId":"000000000000"},{"deviceId":"F0AE49955AD4","deviceName":"Open Bot","deviceType":"Bot","enableCloudService":true,"hubDeviceId":"DD58D5B7FB3C"},{"deviceId":"FB3C5D545A86","deviceName":"Sluit Bot","deviceType":"Bot","enableCloudService":true,"hubDeviceId":"DD58D5B7FB3C"}],"infraredRemoteList":[{"deviceId":"02-202103071019-45073334","deviceName":"Computer Speaker","remoteType":"DIY Speaker","hubDeviceId":"DD58D5B7FB3C"}]},"message":"success"}

To Reproduce:

Add a new ir device to the mini hub. I used other and trained the remote. Then use the api to retrieve the device list

Expected behavior:

A correct device id.

Screenshots:

Device Model:

SwitchBotAPI

• Use Case:

First of all, I appreciate all the hard work that has been put into this REST API. I can't wait to get my own API key.

IMHO, the current documentation is a bit hard to read because it's just a single lengthy README. I'd be happy if the documentation is split into a structured manner and deployed as a static web site.

I made a prototype of the documentation at https://switchbot-api-doc-prototype.netlify.app using HonKit, an active fork of the abandoned GitBook CLI. I personally prefer MkDocs (written in Python) for its material theme and extensibility, but I choose HonKit for the following reasons:

• Python doesn't have an established dependency management compared to Node.js
• TypeScript projects are hosted under OpenWonderLabs organization, so developers here should be familiar with the npm ecosystem

Before submitting a PR, I'd like to ask for your feedback. Should a documentation site really be hosted? If so, what toolchain should be used?

Is your feature request related to a problem? Please describe.

I noticed the majority of the SwitchBot devices I got do have a light sensor built in and reported to the app in terms of dim/bright. This is the case at least for the Motion Sensor, the Contact Sensor and the Curtain, even though the feature is sometimes marked beta, e. g. for the Curtain. These sensors are unused in the API right now, if I did not terribly overlook it.

Describe the solution you'd like

I would love to have these values reported in the json so I could work on an extra sensor set for the homebridge-switchbot-openapi plugin, e. g. if you add the Curtain bot, an extra ambient brightness sensor is added, too.

Describe alternatives you've considered

there is none I guess. I looked at other homebridge plugins and none has that feature (yet). As far as i can tell, it all comes back to the API which does not provide these values yet.

Is your feature request related to a problem? Please describe.

It seems there exist no command to start/stop a recording from an Indoor Cam.
I would like to trigger a recording start and stop through commands via this API.

Describe the solution you'd like

1. A new command for the Indoor Cam called startRecording.
   There could be a parameter to know whether the recording takes place in a memory card or in the Cloud using your Cloud service. eg: parameter: memoryCard|cloudService.
   For the later one, the user needs to have subscribed to your Cloud service.

2. A new command called stopRecording that ends the recording.

I also sent a request in for token I used the option "ask a question" hopefully that gets routed correctly. Is there a more official way to request a token at this time? I will be writing my own rest code I do not use homebridge, or any other platform for that matter, at all. Thanks.

Very minor but it would be kind of cool to be able to toggle the light states on\off via the API on the hub plus.

Is that something that can perhaps be added as well? Would be nice to be able to query for that and monitor for when it starts to get low, do not believe the app warns\monitors in its current form.

thanks.

Describe The Bug:

As far as I investigate, current API accepts any strings but customize as a value for commandType of all devices except for the "Others" IR device. The same thing happens with parameter as well.

To Reproduce:

Send a control command request which satisfies the condition above. E.g., sending a turn-on commands for TV with commandType (resp. parameter) set to foo (resp. bar):

curl -H "Authorization:[MY_API_KEY]"  https://api.switch-bot.com/v1.0/devices/[MY_TV_ID]/commands \
-H "Content-Type: application/json" \
-X POST -d '{"command":"turnOn","commandType":"foo","parameter":"bar"}'

This will return {"statusCode":100,"body":{},"message":"success"} and the TV turns on indeed.

Expected behavior:

I expect a failure response would be returned.

I know the API documentation says that parameter and commandType are not required, but I don't think "not required" means it accepts values including nonsense ones. Optional parameters just have certain fallback values when they are not explicitly specified.

Screenshots:

N/A

Device Model:

N/A

SwitchBotAPI

• Use Case: just found this phenomena while developing a client package. No specific use case is assumed.

Is there a way to add light controls to the API for the Humidifier? I know you can do it through the app, so figured I would ask.

Is your feature request related to a problem? Please describe.

Right now I am not able to see if my bot is On or if it is Off or if it is in press mode or switch mode.

Describe the solution you'd like

Display modes in API as either "switch" or "press"
Display On or Off in API if in Switch Mode.

Describe alternatives you've considered

If this isn't in the API, the device can get out of sync with status of device.
Additional context

Is your feature request related to a problem? Please describe.

he API documentation only provides the command message for a few of the built in buttons. Could the rest be added to the document.

Describe the solution you'd like

What is the command for the INPUT button, the up / down / left / right arrows, the home button. etc.

Describe alternatives you've considered

Hacking random guesses

Additional context

When trying to add commands to control remote devices, it is time consuming to try and guess what the commands might be.

Describe The Bug:

Not actually a bug, but the documentation seems unclear to me with regard to error responses.

To Reproduce:

Send a control command that is incompatible with a device specified in the URL. I tried sending a setAllStatus command (exclusive to Smart Fan) using a DIY TV ID.

curl -H "Authorization:[MY_API_KEY]" https://api.switch-bot.com/v1.0/devices/[DIY_TV_ID]/commands \ 
-H "Content-Type: application/json" \
-X POST -d '{"commandType":"command","command":"setAllStatus","parameter":"on,1,1,60"}'

Then, this curl returns {"statusCode":160,"body":{},"message":"No this command"}.

Expected behavior:

The returned response is not listed here. There is a 160, but other information such as about other possible keys and possible values they may take is a bit obscure IMHO.

Screenshots:
N/A.

Device Model:
N/A, I suppose.

SwitchBotAPI

• Use Case: I'm developing a Node.js client for the API and I want to grasp every possible response the API could return (be it success or failure) as accurately as possible, so that I can define strict types.

Describe The Bug:
The documentation for the GET /v1.0/devices/{deviceId}/status mentions the field brightness twice, with different definitions. It looks like the motion sensor and contact sensor report a different type than the color bulb.

To Reproduce:

See documentation

Expected behavior:

Probably one of the brightness fields should be called differently. The way it is described now makes it very hard to integrate with this API from strongly typed languages such as Java (I am working on an OpenHAB implementation), as there are two types defined for the same field name.

Device Model:
Motion sensor/Contact sensor/Light bulb.

Is your feature request related to a problem? Please describe.

For many users, getting the API key from the app is awkward plus they have to copy that to the other automaton system which often leads to mistakes and frustration.

Describe the solution you'd like

Add an API call that takes the username and password and returns the API key.

Describe alternatives you've considered

OAuth2 authentication but this requires a lot more complexity.

Additional context

The aim of most systems is simplicity. If a system is too complex / error prone then users will give up and seek other solutions.

I use 1 SwitchBot Hub mini and 1 SwitchBot Meter.
Also, I use Node-Red on Raspberry Pi to request the Meter to get status value.

When I request the SwitchBot Meter to getting status,
sometimes it returns past data which does not show on meter's display now.

There seems to be 5 - 20 minutes for refresh the status value.
Could you tell me how to force refresh?

Is your feature request related to a problem? Please describe.

It seems there exist no API command to start/stop a recording from an Indoor Cam, especially using Switchbot Cloud service.
I would like to trigger a recording start and stop through commands via this API.
I would also like to be able to retrieve the recorded videos on the Cloud service via the API.

Those commands would add to much more values to the Switchbot Cloud service.

Describe the solution you'd like

1. A new command for the Indoor Cam called startRecording.
   There could be a parameter to know whether the recording takes place in a memory card or in the Cloud using your Cloud service. eg: parameter: memoryCard|cloudService.
   For the first one, a memory card needs to be inserted into the device.
   For the later one, the user needs to have subscribed to your Cloud service.

2. A new command called stopRecording that ends the recording.

3. A new command/endpoint to retrieve the list of videos recorded in the Cloud service.

Describe alternatives you've considered

-> Today, a workaround to record on a memory Card to do this is to create a scene that set recording mode to "on" then executing this scene via the API. Then to stop, create an other scene and trigger this scene.
-> There is no workaround to record on the Cloud? Which is a too bad for a paid feature.

Additional context

Describe The Bug:
I have 10 curtains, 2 meters, and plan to get some bots. Due to the current request limit 1000 times/day, I have to set the status refresh rate at 1200 seconds which is inconvenience. Would that be a possible that the request limit is determined by the device numbers in the SwitchBot account.

To Reproduce:

Expected behavior:

Screenshots:

Device Model:

SwitchBotAPI

• Use Case:

Describe The Bug:

When you issue any of the commands on a curtain that is part of a group and that curtain is not the master, it will return an error 190 "ExpressionAttributeValues must not be empty". If you issue the command on a master, the entire group moves. It is not possible to move them separately as is possible in the app (since the recent update).

To Reproduce:
GET info of the master curtain (simplified the ID's):

        {
            "deviceType" : "Curtain",
            "calibrate" : true,
            "deviceId" : "1",
            "master" : true,
            "hubDeviceId" : "99",
            "curtainDevicesIds" : [
               "1",
               "2"
            ],
            "enableCloudService" : true,
            "openDirection" : "left",
            "deviceName" : "Living room",
            "group" : true
         },

Simple cURL, 2 would be the slave as 1 is master:
curl -XPOST -H 'Authorization: {{token}}' -H "Content-type: application/json" --data { "command": "turnOn", "parameter": "default", "commandType": "command"} 'https://api.switch-bot.com/v1.0/devices/2/commands'

Response:
{"statusCode":190,"body":{},"message":"ExpressionAttributeValues must not be empty"}

Expected behavior:

This has 2 possible solutions I think:

• If calling a single ID, only that curtain in the group should move. To move them all together, maybe the group should receive a separate ID or the user should just call both ID's. This should probably be dependent on the mode set in the app (which is set to Single in my case).
• Or using the slave's ID in the URL should move the group the same as it would for the master or in the least return a meaningful error.

Device Model:

Switchbot Curtain

SwitchBotAPI

Is your feature request related to a problem? Please describe.

I would like to access the temperatures history of a SwitchBot Meter via the API.

Not just the current temperature but the past history.

Describe the solution you'd like

There could be a command for the Meter called getTemperatureHistory that returns all the temperatures values collected by the device.

It could be the exact same CSV that we have when we click "export data" in SwitchBot app or it could be some json like so:

{
    "temperatures": [
       { "date": "2021-08-08 09.18", "value": 24.5 },
       { "date": "2021-08-08 09.23", "value": 24.2 },
       { "date": "2021-08-08 09.38", "value": 23.5 }
    ]
}

Describe alternatives you've considered
A dedicated endpoint?

Additional context
None

Is your feature request related to a problem? Please describe.
It seems that the status of an infrared remote cannot be obtained through this API even though the similar can be done for other devices like a SwitchBot curtain.
At least, I could not find out how to do this by reading README.
For example, I want to get the current settings of my air conditioner, such as temperature and mode.
I think we should be able to do this through the API since the same thing can be done in the smartphone app.

Describe the solution you'd like
If something like
GET https://api.switch-bot.com/v1.0/devices/{infraredRemoteId}/status
returned the status of the infrared remote, it would be very nice.

Describe alternatives you've considered

Additional context

Hi there,

Yesterday i have setting up the API for my homeassistant and it worked for me with 3 curtain devices.
Today the api looks like broken but the result still success.

I tried use the Postman for test the API manually ,
Both https://api.switch-bot.com/v1.0/devices AND https://api.switch-bot.com/v1.0/devices/C60E256*****/status
are worked, But when i use https://api.switch-bot.com/v1.0/devices/C2F1406*****/commands to send the command,
curtain still not move but the reponse looks like have no problem.
{
"statusCode": 100,
"body": {},
"message": "success"
}

Could you please take a look for me?

Thank you

=====UPDATE=======

When i rebooted the Hub mini, the API worked again,may be this is a bug for Hub mini or?

Thank you

Is there a way to show the water level of the humidifier through the API?

not that it has to show that it is at a certain percentage, but at least if it would say the humidifier is empty that would be helpful to display.

Hi,

I can't found the Generate Open Token BTN from the iOS APP.

Will this api documentation work for talking to your hub mini locally? Controlling the devices locally without the cloud is extremely important.

This may be obvious to others, but is the 10,000 request limit global or per user, and what is the typical number of daily requests?
If global then are there plans to increase it if it gets near the limit, as it seems pointless developing an app if it won't work reliably?

Describe The Bug:

When I am requesting the status of a Switchbot Curtain it sometimes causes the device to move. The motor is only running very shortly - maybe for half a second or so, but it is clearly audible.

To Reproduce:

Sending a request to the /status URL causes this behaviour sometimes. When trying to close an already closed curtain through Alexa the same short movement is triggered.

Expected behavior:

The expectation would be that accessing /status only gives the last known status of the device. Either without accessing the device at all (if the position is stored in the cloud) or directly from the device - under no circumstances should the motor be triggered.

Screenshots:

NA

Device Model:

Switchbot Curtain

SwitchBotAPI

• Use Case:
  NA

Is your feature request related to a problem? Please describe.

Somewhat. The SwitchBot temperature and humidity sensor don't get recognised as a sensor within HomeKit.

Describe the solution you'd like

The SwitchBot temperature and humidity sensor to be recognised as a sensor within HomeKit

Describe alternatives you've considered

I don't think there are any alternatives.

Additional context

If it could be recognised as a sensor within HomeKit, you could be opened up to creating HomeKit automations that occur when a temperature/humidity is reached.

Is your feature request related to a problem? Please describe.

It could be interesting to know ho many requests we have again the right to make when calling the API.

Describe the solution you'd like

For example, a "pending" attribute outside the "body".
In this way we would not loose a call as we would get the remaining authorizations for the token and it could be possible to anticipate.

Describe alternatives you've considered

A special request, which would not be counted, I.E. /remaining_calls.

Additional context

It is not useful to make any call if we know we will not be able to do so.
Maybe it could be possible to adapt calls as we could know how many we could make before reaching rate limit.
I still think rate limit is not a good think but anticipating is a kind of alternative to avoid errors.

Is your feature request related to a problem? Please describe.

It is uneasy to understand what commands are available for a given device through the API.
There is a section with a big table in this documentation. A big table is kind of unpractical and the main problem is we have no idea whether it is up-to-date or not.

For instance, today, I have no idea whether the Indoor cam can receive commands or if it can but it is just not documented yet into this big table.

This would solve those kind of issues of guessing the available commands as well: #39

Describe the solution you'd like

I would like the following endpoint to be available:
GET /v1.0/devices/{deviceId}/commands

It would return a list of all the commands that can be executed for a given device.
Eg, for a bot it could return something like this:

{
    "commands": [{
        "name": "turnOff",
        "description": "switches the bot to OFF state",
        "parameter": "default"
    }, {
        "name": "turnOn",
        "description": "switches the bot to ON state",
        "parameter": "default"
    }, {
        "name": "press",
        "description": "trigger a press",
        "parameter": "default"
    }]
}

Introducing an endpoint to get the available commands would ensure this documentation is always up-to-date and also there would be no need to take time to update this big table anymore.

Is your feature request related to a problem? Please describe.

The function to know the power consumption is useful, but there are too many steps to operate the application.

Describe the solution you'd like

I would like to see not only power ON/OFF, but also current, voltage, and power consumption items.

Describe alternatives you've considered

I take my smart phone and operate it at least five times to find out.

Additional context

Describe The Bug:
I have been using the API for days without any issues. Today I am getting "message": "Unauthorized". Anyone else getting having this issue?

To Reproduce:
I tried to reset the token and it still is not working.

Expected behavior:
The token should work and was working.

Screenshots:

Device Model:

1.0

SwitchBotAPI

• Use Case:

When I try to turn on a switch bot using the API it says:

{
  "statusCode": 190,
  "body": {},
  "message": "ExpressionAttributeValues must not be empty"
}

Step 1. call https://api.switch-bot.com/v1.0/devices/C13FED5A9E1C/commands

Using POST and pass this in JSON body

{
   "command": "turnOff",
   "parameter": "default",
   "commandType": "command"
}

also, pass your authorization code in the header

Is there a way to add child lock controls to the API for the Humidifier?

I'm stumped trying to close a curtain.

I'm using the following headers and params, but I'm getting the following error:
{u'body': {}, u'message': u'param is invalid', u'statusCode': 190}

`HEADERS = {'Content-Type': 'application/json; charset=utf8',
'Authorization': '{0}'.format(API_KEY)}
turnOff = {'command':'turnOff'}
turnOn = {'command':'turnOn'}

def set_devices_info(url, params):
response = requests.post(url, headers=HEADERS, params=params)
if response.status_code == 200:
return json.loads(response.content.decode('utf-8'))
else:
return None
`

the URL is correct as per the docs.

Anyone have any thoughts what I'm doing wrong?

Is your feature request related to a problem? Please describe.

With the current polling only system and rate limited API calls, things like door contacts and motion sensors are unusable in third party systems. Most times these events are completely missed as they happen in between calls to get the status.

Describe the solution you'd like

Add a method to register a callback / webhook URL which is passed the status events as soon as they happen.
This would mean polling is not required, reducing the load on the SwitchBot servers. Plus events from door contacts, etc would be useful.
The data return would be a JSON object and need to include the bridge id, device id and at least the parameter(s) being updated. Also the registered URL should be allowed to contain parameters.

Describe alternatives you've considered

Change the polling rate limit to allow updates every 2 seconds per device.

Additional context

Other manufactures integrations I use implement webhooks and they work very well. Data is only sent when it changes so the transfers are reduce to the minimum whilst proving a very responsive system.

I have been using the API for days without any issues. Today I am getting "message": "Unauthorized". Anyone else getting having this issue?

Is your feature request related to a problem? Please describe.

Currently the SwitchBot App Shows more commands for TV then the API displays or excepts.

Describe the solution you'd like

Add API Commands for:

• Ok
• DirectionUp
• DirectionDown
• DirectionRight
• DirectionLeft
• Menu
• Back

Describe alternatives you've considered

Us on/off, volume, and channels for now.

Additional context

Is your feature request related to a problem? Please describe.

For Air Purifiers, I am only seeing on/off Commands.

Describe the solution you'd like

Either update current commands to have air purifier included or add additional commands for Air Purifiers

Describe alternatives you've considered

Just have on/off for Air Purifiers

Additional context

Is your feature request related to a problem? Please describe.

No

Describe the solution you'd like

The SwitchBot curtain includes a light sensor. Getting api programmatic access to that data coming out of that sensor would be great. It currently is not included nor is battery level on the curtain device.

please make this API capable of running in a online(internet) and offline(Lan) mode.

in the offline mode it would be running via the HUB, or maybe some linux api server application that can be hosted on e.g. a Raspberry PI.

Please enable support for Motion Sensor and Contact sensor (Camera as well). Currently API return success without any attributes/information.

Thank you!

Is your feature request related to a problem? Please describe.

It's extremely important to control this hub and products locally (preferably via mqtt or http). Having cloud dependencies doesn't work when networks go down or companies go under or kill a product line.

Describe the solution you'd like

I'd like to control my devices locally and get metadata about them (firmware version info, current state, etc).

Describe alternatives you've considered

Additional context

From reading I thought you were working on a local api for the hub but it's only a cloud api.

References #12, #13 where I asked a question if this for the cloud api or local control.

Is your feature request related to a problem? Please describe.

Can't pause curtains with API

Describe the solution you'd like

Add pause command to API to be able to pause curtains

Describe alternatives you've considered

Just open or close curtains but that's not fun... 😀
Additional context

SwitchBot App has it.

Describe The Bug:

To Reproduce:

Expected behavior:

Screenshots:

Device Model:

SwitchBotAPI

I'm stumped trying to close a curtain.

I'm using the following headers and params, but I'm getting the following error:
{u'body': {}, u'message': u'param is invalid', u'statusCode': 190}

`HEADERS = {'Content-Type': 'application/json; charset=utf8',
'Authorization': '{0}'.format(API_KEY)}
turnOff = {'command':'turnOff'}
turnOn = {'command':'turnOn'}

def set_devices_info(url, params):
response = requests.post(url, headers=HEADERS, params=params)
if response.status_code == 200:
return json.loads(response.content.decode('utf-8'))
else:
return None
`

the URL is correct as per the docs.

Anyone have any thoughts what I'm doing wrong?

Describe The Bug:

When I am requesting the status of a Switchbot Curtain it sometimes causes the device to move. The motor is only running very shortly - maybe for half a second or so, but it is clearly audible.

To Reproduce:

Sending a request to the /status URL causes this behaviour sometimes. When trying to close an already closed curtain through Alexa the same short movement is triggered.

Expected behavior:

The expectation would be that accessing /status only gives the last known status of the device. Either without accessing the device at all (if the position is stored in the cloud) or directly from the device - under no circumstances should the motor be triggered.

Screenshots:

Device Model:

Switchbot Curtain

Is your feature request related to a problem? Please describe.

The remote controls are lovely devices but have a very limited use.

Describe the solution you'd like

Add the remotes to the API so they can be used for many more situations within the complete home automation system.

Describe alternatives you've considered

Use other remote controls

Additional context

If the remotes could be added to the API they could be included into other systems. Then button press information provided could be sent via a webhook to trigger a whole range of extra devices.

Is your feature request related to a problem? Please describe.

There are many features to add to this early stage API.
The only thing I can do to aim for a better API is opening issues.
As a developer, I would love to contribute.

Describe the solution you'd like

I would like to have access to the API source code to be able to do merge requests and implement feature requests :)
Making the source code kind of open would enable other developers to do so as well.

Describe alternatives you've considered

Additional context

The following example consists of 6 consecutive payloads returned by the API in 5 seconds.

Issues:

• The fields calibrate group moving are present in the first 3 payloads but missing in the last 3
• hubDeviceId changed from C3E770****** to C65A75****** while I have only one hub
• The value of field slidePosition were 0, then suddenly jumped to 100 even though the curtain is still moving
• The value of moving remains false even though the curtain is still moving

Is your feature request related to a problem? Please describe.

The API documentation only provides the command message for a few of the built in buttons. Could the rest be added to the document.

Describe the solution you'd like

What is the command for the INPUT button, the up / down / left / right arrows, the home button. etc.