Web / JSON documentation
I'm working on a native integration to Home Assistant - which is built on Python. As such, I need to write native handlers for all the underlying HTTP requests from the API.
Is there any documentation anywhere on the actual HTTP format, and associated JSON payloads? It'd make it so much easier than reverse engineering the SDK itself...
Alistair Galbraith You can look over here, for already discovered API calls or all Informations about the SDK:
In the linked Topics you will find an API start guide provided by Niels de Klerk .
You will also find two already existing Projects:
1. openHAB by Tim Roberts
2. Homey by Niels de Klerk
Both are also available on Github, and you can see how they are going to do it if you like.
Thanks Markus Mahr for tagging me.
Alistair Galbraith have you thought about what you want to offer as features?
There are 3 different ways you can use to build your intergration, you can either use one or all depending on what you want to acheve.
- Forward NEEO events.
The NEEO brain (CP6) can forward most events using the forward neeo events. You can setup an URL with the NEEO app in settings -> NEEO brain -> forward actions. Here the user can provide the host, port and uri to where the json formated http(rest) posts need to land. This includes button presses, recepie start and stop messages etcetra. In my intergration i chose to set these parameter for the user so the user doesn't have to. this is the easyest intergration method as it only requires you to have a web server listening for post messages to a specifier URI. then parse them to JSON.
- Official and unofficial API's
Most API calls are unofficial, meaning they could potentially change with any iteration of the firmware and they are undocumented. It doesn't happen to often that an API is being changed but it does happened. don't get discouraged here but know that i could happen. i never had any real issues and a change was mostly simple to include. With these API's you can do exactly the same as you could do using the APP and more. Starting stopping recipies, setting slider values, press buttons and or change settings are possibilities amoungst them. These are ideal to controll the devices connected to your NEEO with your automation.
- NEEO SDK.
The NEEO SDK comes in the form of a NodeJs package. this package is purpose build and our type of intergrations isn't the purpose of the SDK, So using the SDK for 3rd party HA products is nearly impossible or at least very impractical. Luckaly the SDK is also REST based and relativly easy to build your own. I have build my own implementation for this to overcome the limitations that come with the NodeJs SDK package. Tim has done the same for his intergration.
Good thing to know is that both Tim and I have all three included in our intergrations. It's probably best to start with the first two depending on your skillset. When i started my intergration i had never wrote anything in JS before and i was happy to start with the first two.
There are two way's of getting all the information you need. Reverse engineering or capturing. I know that Tim does a lot of reverse engineering by looking into the SDK code. I preffer to use either wireshark or postman to see all rest calls, data that is expected etcetra. As Markus Mahr pointed out, our code is open to view and use als you see fit.
The API post i have made is only touching the surface of what's possible. I figgured not to post the more advanced stuff because if the reader isn't able to find that out then he probably better not use it anyway. Wrongly used API calls could potentially break your setup. happened to me quite some times :-D but i was allways able to fix it so don't worry there. Just capture the traffic of what you want to acheve and voila you now know how. ;-)
If you have any specific questions or runnign into a wall somewhere then just tag me ans i can see where i can help you out.
- Forward NEEO events.
I agree with what Niels de Klerk has said and recommend reading through the SDK code - it's a pretty simple straightforward read and pretty easy to duplicate in your own code (plus or minus features you need/want).
The biggest caution I have for you is that you will constantly need to update with SDK changes if you use anything internal (they do making breaking changes that you'll need to adjust for and certainly add features). The other caution is to try to duplicate the SDK standards as much as you can - but Niels de Klerk and I have both been 'burned' by not following it close enough (like how you name the SDK and how you name components)...
Feel free to post any questions if you want..