search

Matthew1471 / Enphase-API

Enphase-API is an unofficial project providing an API wrapper (including local/LAN Gateway API) and the documentation for Enphase®'s products and services.
GNU General Public License v3.0
76 stars 10 forks source link

API documentation source #2

Closed mattosaurus closed 1 month ago

mattosaurus commented 1 year ago

Hi,

I've just got an Enphase IQ Gateway and have started playing around with the APIs and I was planning on creating something similar to this in C#.

I was wondering where you found the complete API documentation for the gateway as the online pdf only contains a brief summary of the available endpoints?

I can happily base use this library as a reference for the endpoints but figured it might be better to go straight to the source if possible :)

Thanks

Matthew1471 commented 1 year ago

Apologies for the delay in reply, I found a few vulnerabilities in the IQ Gateway that I have been responsibly disclosing to Enphase.

To answer your question, a lot of the information has been found from either looking inside the client side JavaScript (https://envoy.local/backbone/application.js) and running it through a JavaScript prettifier to unminify it.

Some further information was obtained from decompilation of the Android Enphase Installer ToolKit.

The documentation is produced by gateway_generate_docs.py which is undergoing continuous improvements. The program has a metadata file (API_Details.json) where I teach it the URLs / JSON response and it fetches the JSON response and then derives the schema.. I then fill in the blanks from either my own knowledge "v" being "230" in the UK means V = "Voltage" or from the JavaScript/tookit code.

Through my research I've accidentally stumbled across the firmware and also the source code that runs on the IQ Gateway - it's written in lua and Ruby.. but I am unsure of the legality of sharing that and in all honesty most of the API end-point functionality can (and was) mostly be derived from the above - the JSON that comes back from the HTTP GET should be pretty much the same irrespective of what software we're running. Obtaining the public key for the JWT was a nice touch however - haven't seen that information anywhere else! Also a lot of the APIs actually behind the scenes themselves make further HTTP API requests - so I'll definitely include in the documentation where is the best to get which bits of data (briefly, the /stream/meter is just /ivp/meters/reports behind the scenes with some JSON key/value re-mapping and on a timer!).

If you create a C# wrapper and it follows the same lean principles (not too many third party dependencies etc) as the rest of the project I'd love to include it in this project. I put some of the code inside the "Python" folder in the hope that there could later be a "C#" folder etc for clients in other languages.

One thing I hadn't realised when I started this project was just how massive it would be - which is why I invested time in writing a script to automatically produce the documentation and to infer JSON schema etc.. I plan to always be improving the documentation. Some of the "examples" are in-use in my house (gateway_amqp_meters.py, amqp_database_meters.py and amqp_unicorn_hat_hd.py) so while the documentation and the library was the primary focus, the examples actually are written to be production ready.

Hope you enjoy this project as much as I have :). If you have any pull requests I'll happily add stuff in - just might tweak it to be in keeping with the simplicity of the project (no dependency hell).

mattosaurus commented 1 year ago

Thanks for the detailed response, I hadn't realised quite how complicated this was!

I'm currently working on a library for accessing a GivEnergy battery as control of that is of more use to me initially than this gateway. Once that's done I'll get back to working on this library and can then share it with you when complete to see if you want to include it or not.

Keep up the good work.