openwonderlabs / switchbotapi Goto Github PK
View Code? Open in Web Editor NEWSwitchBot Open API Documents
SwitchBot Open API Documents
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.
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
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.
Describe The Bug:
To Reproduce:
Expected behavior:
Screenshots:
Device Model:
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.
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.
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.
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.
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
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
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
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.
A new command called stopRecording
that ends the recording.
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:
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.
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
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 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
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.
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
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
I have been using the API for days without any issues. Today I am getting "message": "Unauthorized". Anyone else getting having this issue?
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
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.
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 there a way to add child lock controls to the API for the Humidifier?
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.
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:
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?
The following example consists of 6 consecutive payloads returned by the API in 5 seconds.
[12/27/2020, 12:06:10 AM]
{
"statusCode": 100,
"body": {
"deviceId": "C65A75******",
"deviceType": "Curtain",
"hubDeviceId": "C3E770******",
"calibrate": true,
"group": false,
"moving": false,
"slidePosition": 0
},
"message": "success"
}
[12/27/2020, 12:06:11 AM]
{
"statusCode": 100,
"body": {
"deviceId": "C65A75******",
"deviceType": "Curtain",
"hubDeviceId": "C3E770******",
"calibrate": true,
"group": false,
"moving": false,
"slidePosition": 0
},
"message": "success"
}
[12/27/2020, 12:06:12 AM]
{
"statusCode": 100,
"body": {
"deviceId": "C65A75******",
"deviceType": "Curtain",
"hubDeviceId": "C3E770******",
"calibrate": true,
"group": false,
"moving": false,
"slidePosition": 0
},
"message": "success"
}
[12/27/2020, 12:06:13 AM]
{
"statusCode": 100,
"body": {
"deviceId": "C65A75******",
"deviceType": "Curtain",
"hubDeviceId": "C65A75******",
"slidePosition": 100
},
"message": "success"
}
[12/27/2020, 12:06:14 AM]
{
"statusCode": 100,
"body": {
"deviceId": "C65A75******",
"deviceType": "Curtain",
"hubDeviceId": "C65A75******",
"slidePosition": 100
},
"message": "success"
}
[12/27/2020, 12:06:14 AM]
{
"statusCode": 100,
"body": {
"deviceId": "C65A75******",
"deviceType": "Curtain",
"hubDeviceId": "C65A75******",
"slidePosition": 100
},
"message": "success"
}
Issues:
calibrate
group
moving
are present in the first 3 payloads but missing in the last 3hubDeviceId
changed from C3E770******
to C65A75******
while I have only one hubslidePosition
were 0, then suddenly jumped to 100 even though the curtain is still movingmoving
remains false
even though the curtain is still movingHi,
I can't found the Generate Open Token BTN from the iOS APP.
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.
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.
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.
Describe The Bug:
To Reproduce:
Expected behavior:
Screenshots:
Device Model:
Hub Mini, Curtains, remote (e.g., all products).
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
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.
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.
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.
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.
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.
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.
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?
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
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:
Device Model:
Switchbot Curtain
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.
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 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
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:
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:
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
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.
A new command called stopRecording
that ends the recording.
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:
Will this api documentation work for talking to your hub mini locally? Controlling the devices locally without the cloud is extremely important.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.