banner

For a full list of BASHing data blog posts see the index page.     RSS

Getting data from an Enphase Envoy S — updated

Our new rooftop solar array has Enphase panels and microinverters. Between these and the local power grid are relays and a black box called an "Envoy S". In a standard installation, the black box connects to the household LAN via WiFi and sends lots of data to Enphase every 15 minutes for monitoring purposes. Enphase shares data with solar system owners, who can use the "Enlighten" Web portal to keep an eye on system performance.

We don't have a standard installation. It's against my religion to have someone I don't know, let alone a transnational company, accessing the Net through my home network.

For prickly customers like us, Enphase has another option: a gadget called "Mobile Connect" that plugs in to a USB port on the Envoy S. The gadget has its own 3G SIM card and can talk to Enphase independently.

But like a lot of solar system owners, I'd occasionally like to know more about the system's operation and state of health, so I've patched into the Envoy S through its Ethernet port. A cable runs from this port to an ancient netbook inside our house. In a browser on the netbook I can check a number of operational details by going to http://envoy.local/, because the Envoy S has its own HTTP server. Production and consumption figures, for example, are clearly displayed in a nicely designed webpage.

The Envoy S actually stores a massive amount of performance data, but many of those numbers are only accessible by Enphase support staff. Resellers and installers have a special password, unique to each Envoy S and not shared with system owners, for accessing some of the secret stuff. However, there are at least two useful data blocks that ordinary mortals like me are allowed to get from the HTTP server, as described below.

Overall production and consumption. For my particular Envoy S, the link-local address

http://169.254.120.1/production.json

returns a minified JSON file with figures updated every few minutes:

envoy1

All I want from this report are the date and the day's watt-hours of production and consumption. To get these I use jq as shown:

jq '(.production | .[1]["readingTime","whToday"]),(.consumption | .[0]["whToday"])' < production.json

envoy2

I can place these figures in a tab-separated line with paste -s, then format them with AWK to convert the UNIX epoch "readingTime" to an ISO 8601 date, and round the watt-hours to integers:

jq '(.production | .[1]["readingTime","whToday"]),(.consumption | .[0]["whToday"])' < production.json \
| paste -s \
| awk -F"\t" '{printf("%s\t%.0f\t%.0f\n",strftime("%Y-%m-%d",$1),$2,$3)}'

envoy3

I've put this command in a shell script (below) with curl to download the minified JSON file. The final output gets appended to a daily production-consumption log, and every evening I execute the script while running the netbook for a few minutes. The script could be scheduled as a cron job, but that old netbook might die soon and is overkill for this task; something like an always-on Raspberry Pi would be better.

#!/bin/bash
 
curl -s http://169.254.120.1/production.json \
| jq '(.production | .[1]["readingTime","whToday"]),(.consumption | .[0]["whToday"])' \
| paste -s \
| awk -F"\t" '{printf("%s\t%.0f\t%.0f\n",strftime("%Y-%m-%d",$1),$2,$3)}' \
>> solar_log
 
exit 0

Individual microinverters. The webpage at http://envoy.local/ tells me how many of my 20 microinverters are communicating with the Envoy S, and how many are producing power. It doesn't give details, though. To get more information, I can go to

http://169.254.120.1/api/v1/production/inverters

Access to this data requires a login. It's not the secret reseller/installer login, just username = "envoy" and password = "[last 6 digits of Envoy S serial number, in my case 083581]". For scripting purposes that means using authentication options in the curl command:

curl -s --anyauth --user envoy:083581 \
http://169.254.120.1/api/v1/production/inverters > inverters

The URL retrieves another JSON file, this time un-minified, with serial number, UNIX-epoch reading time, current watts output and maximum watts output for each of my 20 microinverters:

envoy4

To make this file more easily readable I can use a combination of json-table, sed and AWK. json-table is a command-line utility that (as the name suggests) rebuilds JSON data as a table. If I just run jt . % < inverters, each JSON block in "inverters" appears on a single line:

envoy5

I use sed to delete the double quotes and the final "}". AWK is then told that the field separators in each line are ":" and ",", and selected fields are printed tab-separated. The resulting table has serial number, date and time, current watts output and maximum recorded watts output for each microinverter:

jt . % < inverters | sed 's/"//g;s/}//' \
| awk -F"[:,]" '{printf("%s\t%s\t%s\t%s\n",$2, \
strftime("%Y-%m-%d:%H.%M",$4),$8,$10)}'

Update. Reader John Lauro kindly pointed out an error in the strftime above. Originally the date had months twice — see screenshot below. The second months (%m) should be minutes (%M).

All 20 microinverters looked OK when I grabbed the screenshot below. Maximum outputs are low because the panels were only first installed at the beginning of the Tasmanian winter.

envoy6

Last update: 2019-09-06
The blog posts on this website are licensed under a
Creative Commons Attribution-NonCommercial 4.0 International License