utilities/telegraf-plugins#9: Soliscloud Plugin

Their API uses signature based authentication - using a shared secret to generate a HMAC of the request specifics. It's a little unusual in that they're using base64'd hashes rather than hexdumps, but it's otherwise relatively straightforward.

The API doc defines the auth header structure as

Authorization = "API " + KeyId + ":" + Sign
Sign = base64(HmacSHA1(KeySecret,
VERB + "\n"
+ Content-MD5 + "\n"
+ Content-Type + "\n"
+ Date + "\n"
+ CanonicalizedResource)

It doesn't give a clear specification of what the expected behaviour is for Content-MD5 if the request body is empty:

When the message content is empty, the string is empty.

I've taken that to mean that the MD5 should be omitted (i.e. that part of the signstring should just be `\n") rather than that the input to the digest should be an empty string.

So, once I've got access, we may need to come back and change that (assuming we generate any requests with empty request bodies in the first place).

Commit dc32216 implements support for the auth mechanism

v1/api/userStationList

The API doc and the cloud interface use slightly different terminology, but it looks like v1/api/userStationList will give a list of what the Cloud UI call "Plants" (i.e. locations where inverters are installed) - in my case, there'll be just one listed (though a business might have more).

It gives an overview of total solar yield, battery charge rates and whether there are any faults detected - obviously all useful things to collect stats from

For this endpoint (and I'm guessing all others) there's a compulsory request body

{"pageNo":1,"pageSize":100}

/v1/api/stationDetail

This endpoint provides more detailed information about the location, including cumulative counters (such as money saved etc).

Depending on what actually gets populated once the device is installed, this will totally be worth calling.

It has one required request body property

{"id":1234}

(where that ID is taken from the station list)

But, it'll be worth being conscious of rate limits - I won't hit them (because only one location), but if someone else with multiple locations were to use this plugin they might - when iterating over stations listed in /v1/api/userStationList will need to be conscious of that

/v1/api/inverterList

Lists installed inverters, like the station listing, it requires

{"pageNo":1,"pageSize":100}

/v1/api/inverterDetail

Gives extended detail on a specific inverter, including batter details.

Requires either the ID, or the serial number to be provided

{"id":1234, "sn": "abcdef"}

/v1/api/alarmList

Lists details of alarms/faults.

Returns the station ID, the serial number of the alarming device along with alarm codes and levels.

There's a list of alarm codes [here](https://oss.ginlong.com/templet/Alarm%20information%28%E6%8A%A5%E8%AD%A6%E4%BF%A1 %E6%81%AF%29.xls)

Input is

{"pageNo":1,"pageSize":100, "stationId": 1234}

Station ID is optional

The API has a number of other endpoints - some are for collecting historic data, others relate to grabbing data from data-loggers and Electronic Power Monitoring (EPM) boxes: I'm not having those installed, so won't add support for those.

Need to think about the eventual schema then.

My existing power consumption data goes into a measurement called power_watts. That could be reused as long as we avoid existing field names (to ensure that the new data doesn't lead to existing graphs misreading) - I'll likely make the measurement name configurable anyway.

Essentially though, we've got one set of information:

• Generated
• Money saved
• Battery charge %age
• Battery discharge rate
• Battery discharge today
• Battery charge added today
• Alarm state/code/level

But the data is available at different scopes - per device/inverter and per-site.

So, we probably want to convert to a single schema, with tags differentiating whether this is scoped to a site or a device.

power_watts,type=device,device_type=battery,inverter_id=1234 charge=99.9,output=300,today_charge=500,today_consumed=100
power_watts,type=device,device_type=inverter,inverter_id=1234,alarm_state=0 today_generated=300,today_money=3.50,alarm_code=3

That's obviously going to change a little depending on what results the API actually gives (the API doc doesn't give much detail/example).

To help progress development, I've added mocked responses to the script - they'll need removing once devices are reporting into the API.

Currently the script:

• Calls stationList to get a list of locations
• Calls inverterList to get a list of inverters in each location
• Calls inverterDetail to get battery information from each inverter

None of this, yet, gets turned into Line Protocol, so that's probably the next thing to do.

Now that the install's complete, I've made some tweaks based on observation of the API output.

There are some headaches with the API's output though

• The value of gridPurchasedTodayEnergy is (according to gridPurchasedTodayEnergyStr) in kWh. Yet it's claiming ~650, suggesting it's actually in Wh
• That 650 value, though, doesn't match anything in their Cloud UI/app

If it's simply mislabelled and is consistently in Wh, that's fine. My concern is whether it switches to being in kWh once it reaches over 1000 (note: it does - 24h later I'm getting a reading of 5.04kWh - we might need to guess unit based on some sort of threshold check).

Extra Notes:

• Each of the panel array's current power can be found in pow1, pow2 etc. These are in Wh.
• Despite what the API docs say, BatteryPowerPec does not seem to give a percentage for the battery. batteryCapacitySoc however, does.
• The station object also contains some interesting information: capacityPercent details what percentage of the installed solar capacity is currently being realised. condTxtD gives a cloudy/sunny etc

The API docs say that field state has the following values/meanings

However, my inverter is currently reporting state as 3 (so, according to the above, Alarm).

But, the Cloud UI doesn't show anything in an alarm state

I'm going to leave collection of that value in the plugin, but if alerting is built around it it's probably better to look for changes rather than relying on the values in the docs.

The value of gridPurchasedTodayEnergy is (according to gridPurchasedTodayEnergyStr) in kWh. Yet it's claiming ~650, suggesting it's actually in Wh

I'm now getting reads using the correct unit - we've pulled in 5.04kWh so I get a value of 5.04.

What's curious though, is that the behaviour didn't reproduce in the early hours of this morning. After the daily counter reset to 0, there was a period where we'd pulled hundreds of Wh from the grid, but not yet 1000 - yet the value reported by the API was correctly in kWh (i.e. it was a decimal)

The best that I can surmise is that it's something to do with the fact that the inverter had only just been brought online yesterday. Why that should matter... but we have been getting a consistent unit today.

I've been able to build a Grafana dashboard around the stats we're collecting so far

So, I think it's probably time to look at merging the plugin into the master branch and closing this issue out - anything new can be logged as a FR/bug.

Changed have been merged and the source branch has been deleted.