Open nazar-pc opened 1 year ago
As a primer, for my inverter X1 Hybrid G4 the correct and full mapping looks like this:
As you can see, current version of the library doesn't read AC power
and other values correctly when it is negative, resulting in ridiculous values like 62618
instead of correct value −2918
.
Published all the documentation I was able to gather: https://github.com/nazar-pc/solax-local-api-docs
New release of the app came out 3 days ago (0.4.4), but according to changelog nothing major happened there, so I didn't bother looking into it.
Very much appreciated! I just got a set of X3 Hybrids up and running. Will be testing and integrating in about 2 weeks.
BTW, what would be the right place to request more sensors in HA? I had to derive a bunch of things like load power, charge/discharge rate and remaining time, totals for stored/used battery power for energy management. I can provide templates and describe rationale, just want to make sure I post it in the correct place.
Not an expert on this component but: In general sensors are created dynamically in HA. Checkout https://github.com/squishykid/solax/blob/5fdb6d18acd78350b33fd645f69b4eb301167a72/solax/inverter.py#L85 in this component's code to see where it tells HA about the sensors. As long as the decoder provides them, HA will create the entities. Special care needs to be given in the naming. Hope this is helpful.
This library just extracts data. HA integration though should be free to add more sensors, which have derived values (for totals or change rate not provided by inverter itself it'll need access to older values for instance).
You can create sensors either from data or from calculations. HA does not care. It's the integration that delivers the data and its classification.
But I am not the author of this integration. Just happen to watch it closely as I will need it soon.
I understand that, my point is that it would be helpful if integration did provide some additional calculated sensors on top of raw values this library gets from the inverter. I just assumed you may be working on updating the library and integration afterwards, in which case I'd love to see some new sensors added.
I might look into it myself, but I don't feel very comfortable working with Python.
FYI There is also a bunch of modbus info out there that might come in handy:
https://library.loxone.com/detail/solax-x3-hybrid-(neoom-kjubee)-917/overview
Yeah, Solax even sent me docs for it. But it doesn't seem to provide any new information and it is much less convenient to work with than to issue an HTTP request.
I'm currently working on including this new information in the next release of this library.
@squishykid would you please add EV chargers as well, not just inverters?
@nazar-pc Thanks a lot for extracting the mapping! ❤️ While going through the app code did you notice how the changes are done? Is it somehow possible to use this local API to also send commands, not just to read values? That would be beneficial as with the ability to also send commands one would not need to buy Modbus converter to control the Inverter/Charger.
Yes, as long as UI allows to change settings (it does) it is certainly possible. The challenge is that API is kind of ugly and confusing, so changing critical parameters is potentially dangerous. Also limits configured in the app do not actually correspond to limits configured in the inverter itself (which leads to confusing errors), which is why I focused on reading data first rather than modifying.
I'd love to see ability to change some setting like lowering charging current depending on some rules in Home Assistant for instance, but Python is not my strong side, so unless someone volunteers to do the hard work, I can try to extract up to date mappings (they are likely also model-dependent).
FYI I have been digging into their private APIs last weekend since their public API was hard down. First of all, all the private API endpoints continued to work while the public API was down.
I used Safari and Chrome to inspect the web interface, rather than the mobile App. Then used ARC to assemble the API calls to retrieve the data. You first need to login into the web App with a simple call:
curl "https://www.solaxcloud.com/phoebus/login/loginNew" \
-X POST \
-d "username=yourusername&userpwd=yourencodedpassword" \
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"
if successful the response will include a token at the very end of the json document:
{
...
"token": "your-magic-token"
}
You need to use that token for all the realtime calls like this:
Some of the values are incorrect like userChargemaxCurrent
and userDischargemaxCurrent
that I have set to different values in the app. I have replaced identifiable things like user or site information with madeup strings.
This is not the same as local access that this library is about. Also those "real time data" are not actually real time from what I saw, they are snapshots made every 5 minutes. So it is off-topic here (and please put the text under <details></details>
, it beaks readability of the rest of the comments due to its length).
@fxstein good job on digging into it. As @nazar-pc points out though their cloud API is of low interest for us as it is slow and unreliable. Could you please try whether the local API uses the same authentication technique? It is accessed by the same app or web client so there is high chance it works the same 🤞 If you confirm that, we might be able to try changing some safe values like charger mode in case @nazar-pc manages to extract the mappings from the app.
Changing inverter settings uses a different login method and API. I have just started playing with that. The login is different as it also requires the installer password to change most settings.
curl "https://abroad.solaxcloud.com/proxy//settingnew/paramSet" \
-X POST \
-d "MIME Type: application/x-www-form-urlencoded\noptType: setReg\nnum: 1\nsn: yourreistrationcode\ninverterSn: yourinvertersn\ndeviceType: 1\ntokenId: this-is-a-different-api-token\nData: [{\"reg\":200,\"val\":80}]" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json, text/plain, */*"
in this case register 200 is the maximum charge level for the charger, setting it to 80% in this example.
I have not had time to dig deeper into its login process or other settings, but Safari or Chrome developer shows you the details of every call when you hit the save button next to any setting.
@nazar-pc changed the comment. My apologies for the length of it.
I understand that their online APIs are too slow - painfully aware of that. But I figured it can help with mapping data. My system got installed with the LAN adapters (installer meant it well wiring everything up) but because of that I currently have no local API to play with and since I have 3 systems in master-slave setup, the simplified modbus protocol does not work either. Waiting for the dongles to get swapped out for the WiFi/WLan versions...
For reading I extracted close to 100% of data. I think updating something like charging mode and charge/discharge percentages is relatively safe, but I'll have to look closer into it if someone wants to tackle implementing it. If different inverters have different mappings though the danger is that you might be editing one setting, but accidentally changing another to arbitrary value. You can trip circuit breaker, put the whole house offline or do other kinds of fun things that we better avoid.
Good thing is that it is all in the app. Bad thing is that application is poorly designed and code is minified with no documentation, so it is not exactly trivial to make sense of it. But certainly possible.
Another fun exercise would be to run mobile UI on desktop, then it is even easier to inspect things comparing to just reading the code, but I'm not in the mood (should be not too difficult though).
@fxstein I see. That's unfortunate. If only those LAN adapters worked the same as WiFi, providing local API or Modbus TCP. That would be much better than going WiFi... I am asking not because of my Inverter where I already have Modbus working but I also have the Solax EV charger (X3-EVC-11K). It has single Modbus interface and WiFi integrated into it. As it is connected to the inverter by the Modbus it seems my only option to integrate it is the local API... Off-course if we can make this local API working it will help others that haven't invested into Modbus yet or do not have the ability to easily route required cabling to the inverter. I can help with testing as I have Pocket WiFi on mine and I can read from local API using curl. @nazar-pc yep, charging mode is safe. The worst that can happen is that you will charge or discharge your battery in wrong time. That's low risk suited for playing with I would say :-)
I have 3 systems in master-slave setup, the simplified modbus protocol does not work either.
I added in support for Parallel Mode (Master Slave) a while back for the Modbus Integration. It's just untested, I don't see why it wouldn't work though. I haven't fully implemented each individual Inverter yet, but the whole system should return the totals.
As it is connected to the inverter by the Modbus it seems my only option to integrate it is the local API...
If you can get some Modbus network traffic I can look into supporting that as well in the Modbus Integration.
@wills106 Thank you! I did take a look at that but only had an ESP32 device with RS485 handy, so I played with your parallel protocol in ESPHome, but could never get any of the inverters to respond at all. I did get the occasional heartbeat message off the RS845 bus, so I knew I was on the correct settings. Currently 6000 miles away from the setup, hope to be back in person onsite in April.
As it is connected to the inverter by the Modbus it seems my only option to integrate it is the local API...
If you can get some Modbus network traffic I can look into supporting that as well in the Modbus Integration.
@wills106 The trouble is we would probably need a passive mode for this as the EV charger is connected to the same Modbus connector/cable on the Inverter as is used for the communication with the Modbus Smart meter. It is entirely possible there is no communication between EV charger and Inverter at all and the EV charger is just reading grid load from the Smart meter over Modbus... In other words it is different Modbus cable than I am using for communication with the Inverter. I am a Modbus noob, but if I understand it correctly, I would need to switch my Waveshare to passive mode and connect it to the cabling Inverter(and EV charger) is using to get values from Smart meter. That would allow me to get the values from Smart meter directly instead of from the inverter and possibly allow me to communicate with both the Inverter and EV charger and as a bonus I wouldn't even need separate cabling. Not sure if this is even technically possible though and I already have the extra Modbus cabling between Inverter and Waveshare...
need a passive mode
This might do the trick https://github.com/infradom/ha-addon-modbusspy
It is entirely possible there is no communication between EV charger and Inverter at all and the EV charger is just reading grid load from the Smart meter over Modbus...
There is a Modbus document available for the Charger.
With your installation does the Charger rely solely on the Inverter for Import / Export values? Or do you also have the CT's hooked up to your Charger? I'm going to start a discussion on my Github if you want to join in?
With your installation does the Charger rely solely on the Inverter for Import / Export values? Or do you also have the CT's hooked up to your Charger?
On the charger there is only one RJ45 port and (same as on Inverters) you have to choose whether to use that port for CT Clamps or for the Modbus link. So I have both Inverter and Charger linked through common Modbus link that leads to the main grid meter. As I said no clue whether there is any communication between Charger and Inverter on this link 🤷♂️
I'm going to start a discussion on my Github if you want to join in?
I already noticed and added a comment there. Thanks!
@squishykid do you have progress on this front? It is getting annoying to manually editing files every time I upgrade Home Assistant to fix Solax integration, hoping for version where I don't need to do that anymore :pray:
@nazar-pc I am working on this at the moment, but the refactor is difficult. It seems like some of the inverters have different mappings and I don't understand why. I.e. your mappings for inverter type 4 do not match https://github.com/squishykid/solax/blob/master/solax/inverters/x1_mini_v34.py.
I am trying to figure out how to resolve this. Perhaps you could send me a copy of the decompiled android app?
Perhaps this library can distinguish between different mappings based on whether the data parameter is required? Or perhaps it's based on whether the firmware version is >3?
From what I read in the code, it doesn't check the firmware version. Attaching zip file with all the JS files contained in the from official Android application (version 0.4.3).
One confusing thing I found was Type
and Information[1]
fields. They are both type of inverter and IIRC used interchangeably in some contexts, but not others. I suspect they are not guaranteed to be the same :man_shrugging:
I'm fairly confident I mapped those correctly according to their source code, but I could have also made a mistake somewhere.
UPD: Uploaded unmodified JS files (some were re-formatted and modified in the previous upload): solax.js.zip
@nazar-pc perhaps you can help me, the specific case I am trying to distinguish is between these two test cases. They both have the same inverter number in Information[1]
fields, but they both decode the data differently. I.e. X1MiniV34 has "Total Feed-in Energy" at index 41
. X1 Boost has "Total Export Energy" at 50
. They seem like the same field, but are at different indexes. When I look at your docs for inverter type 4, "FeedInEnergy" is between Data[50]
and Data[51]`.
How can the solax library determine which decoding to use when Information[1] == 4
?
What does type
field say for those two, is it the same as Information[1]
? It was the confusing part for me in their codebase.
Also I see the link to a blog post with modified firmware, is there a chance that firmware is incompatible with official app and doesn't follow the rules?
Also this is concerning, I have not seen any handling for type
being a string in the app: https://github.com/squishykid/solax/blob/e17c9308b61def410ac96bd087fdcbf7300d8907/solax/inverters/x1_mini.py#L12
I'll try to take a look at the latest version of the Android app (0.4.5 vs 0.4.3 that I looked at before) this weekend.
@nazar-pc If you look at the request
fields for each of the linked examples, you can see the type
fields
I see, well, I'll have to dive back into JS then to figure it out, will try to find time this weekend
I have looked at Android app 0.4.5 (latest as of right now, I was previous looking at and attached JS for 0.4.3), no meaningful changes to data handling there.
Looks like https://github.com/squishykid/solax/issues/101 also used official app to decode the data.
I have one user also stating that the data conversion must follow new format for X1 Boost in https://github.com/nazar-pc/solax-local-api-docs/issues/1 (note that they are on v3 firmware already, also you can take a sample of their inverter data there).
So far there is no consistency regarding versions or type there. As far as I can see in the code, those inverters should not be working properly with local WiFi connection. If they do I just don't see how.
This is literally from application's sources:
e.inverterType = i["Information"][1];
localStorage.setItem("inverterType", e.inverterType);
e.transportType = i["Information"][9];
e.inverterType >= 8 ? localStorage.setItem("transportType", 1) : localStorage.setItem("transportType", e.transportType);
1 == e.transportType || e.inverterType >= 8 ? e.getPub2(i["Data"]) : e.getPub1(i["Data"]);
localStorage.setItem("dongleModType", i["Information"][10]);
localStorage.setItem("dongleWorkMode", i["Information"][11]);
localStorage.setItem("sn", i["SN"] || i["sn"]);
They write dumb redundant code, but it essentially boils down to this:
inverterType >= 8 ? getPub2(Data) : getPub1(Data)
There are no checks for other fields in there. Would be great to confirm with someone whether they can see proper data in their Android app with local WiFi connection.
One thing I noticed (there are too few data points, but still) is that Information[0]
is above 1
for all devices that seem to follow new format (Data2 unique for every model) and everything that is 0.x
seems to follow the old format. Try to go with that for now when deciding between Data1/Data2 and see if it passes tests. Though I don't see anywhere in the app that this field is actually used.
For anyone interested, I found a way to set the PowerLimit (which is usefull because I have dynamic tariffs which sometimes go negative in spring and summer). Value has is a number between 1 and 100.
The trick to find what to send was using the app in local mode connected to the WiFi broadcasted from the inverter and capturing the packets with PCAPdroid.
Below what I have in a NodeRed function what I send as an HTTP request to the local IP adress of the inverter:
msg.headers = {}
msg.headers = {
'content-type': 'application/x-www-form-urlencoded',
'X-Forwarded-For': '5.8.8.8'
};
msg.payload = {}
msg.payload = {
'optType': 'ActivePowerLimit',
'ActivePowerLimitValue': '100',
'pwd':'admin'
};
return msg;
Solax Power in private conversation refused to disclose meaning of the parameters of the
ReadRealTimeData
endpoint, so I decided to go through the source code of the Android app (version 0.4.3) and extract everything I can from there, thankfully all the logic there is client-side in JS (though JS is minified, so it takes some effort).This will result in precise mapping the same exact way mobile app interprets data and will remove the need to guess values. With that information everything Android application supports will be also possible to support here in exactly the same way.
I'm only focusing on reading
ReadRealTimeData
values for now, but it would be possible to potentially replicate all the logic application supports if it is desirable (I'm a user of this library indirectly through Home Assistant, having ability to switch Work Mode, charge/discharge time and other things would be useful, but it would be a bit tricky to expose everything properly given how many inverter models they have and features are different for different inverters).Once I have basic version compiled, I'll open source it in GitHub repo and comment it here, this is just for tracking and discussion purposes for now.
cc @fxstein as you commented on https://github.com/home-assistant/home-assistant.io/issues/25151