EnphaseCollector

Support for envoy firmware > D5.0.34

From around V7 of the envoy firmware the security model for API access was changed. This is obviously problematic for software such as mine that relies on local access to the API's

While it is entirely up to Enphase as to how they develop their software I see a number of issues with their new security model

• It links your enphase community account to the token needed to access the API (If you don't want an account or enphase suspends your account you will lose access)
• It does not look to be based on a standard authentication mechanism such as OAuth (You should never write your own authentication protocol)
• It is currently broken in a number of ways and will reduce the security of your envoy device (I will not list the issues here)

EnphaseCollector uses the undocumented API in the Envoy device to collect individual solar panel data and upload to an influx db, pvoutput site or just as an internal view

Can be run as a java application or using the docker image

Main Page	Weekly History Tab

If using the jar file you will need a Java 17 that you can get from https://adoptopenjdk.net/

Example #1 with default internal website (assuming jar is named enphasecollector-DEV.jar)

java -jar enphasecollector-DEV.jar

where the application will attempt to guess the envoy location and password.

Example #2 when envoy.local is not resolved and you need to specify the ip address and the password cannot be guessed.

java -jar enphasecollector-DEV.jar --envoy.controller.host=envoy-ip --envoy.controller.password=envoy-password

where envoy-ip is the ip address of your envoy controller and envoy-password is likely to be the last 6 characters of your envoy controller serial number

If using the docker image

Example #1 using influxDB for storage

docker run \
-e TZ=your-timezone \
-e ENVOY_CONTROLLER_PASSWORD=envoy-password \
-e ENVOY_CONTROLLER_HOST=envoy-ip \
-e ENVOY_INFLUXDBRESOURCE_HOST=influxdb-ip \
-e ENVOY_INFLUXDBRESOURCE_PORT=influxdb-port \
-e SPRING_PROFILES_ACTIVE=influxdb \
dlmcpaul/enphasecollector

where envoy-password is likely to be the last 6 characters of your envoy controller serial number

Example #2 in standalone mode with internal database storage

docker run \
-e TZ=your-timezone \
-e ENVOY_CONTROLLER_PASSWORD=envoy-password \
-e ENVOY_CONTROLLER_HOST=envoy-ip \
-p 8080:8080 \
dlmcpaul/enphasecollector

and a web page available at http://localhost:8080/solar and looks like this

You can also link the internal database to an external file system, so the database kept on upgrade of the image using the mount point /internal_db

docker run \
-e TZ=your-timezone \
-e ENVOY_CONTROLLER_PASSWORD=envoy-password \
-e ENVOY_CONTROLLER_HOST=envoy-ip \
-p 8080:8080 \
--mount target=/internal_db,source=host_path
dlmcpaul/enphasecollector

and replace host_path with the path on your host machine where you want to store the data.

Example #3 sending data to pvoutput.

docker run \
-e TZ=your-timezone \
-e ENVOY_CONTROLLER_PASSWORD=envoy-password \
-e ENVOY_CONTROLLER_HOST=envoy-ip \
-e ENVOY_PVOUTPUTRESOURCE_SYSTEMID=your-system-id \
-e ENVOY_PVOUTPUTRESOURCE_KEY=your-key \
-e SPRING_PROFILES_ACTIVE=pvoutput \
dlmcpaul/enphasecollector

Your timezone is something like Australia/Sydney or similar

Available environment variables descriptions:

• ENVOY_CONTROLLER_HOST Set to your Envoy Controller IP Address
• ENVOY_CONTROLLER_PASSWORD Set to your Envoy Controller password
• ENVOY_INFLUXDBRESOURCE_HOST Set to your Influx Database IP Address
• ENVOY_INFLUXDBRESOURCE_PORT Set to your Influx Database Port No
• ENVOY_PVOUTPUTRESOURCE_SYSTEMID Set to your pvoutput systemid
• ENBOY_PVOUTPUTRESOURCE_KEY Set to your pvoutput key
• SPRING_PROFILES_ACTIVE Determines destination for stats. if not set only an internal database gets the stats. Values can be influxdb and pvoutput
• ENVOY_REFRESHSECONDS How often to poll the Envoy Controller. Default 60
• ENVOY_PAYMENTPERKILOWATT How much you get paid to export power to grid (FIT) eg 0.125 is 12.5c/Kw
• ENVOY_CHARGEPERKILOWATT How much it costs to buy from the grid eg 0.32285 is 32.285c/Kw
• ENVOY_DAILYSUPPLYCHARGE How much it costs to access the grid every day eg 0.93 is 93c/day
• SERVER_SERVLET_CONTEXT-PATH Context path for local view

New configuration

• ENVOY_EXPORT-LIMIT If you have a limit on your export this will display a upper boundary on the main graph and display a new excess production line
• ENVOY_BANDS[].FROM The bands array configuration will add a shaded band to the main graph that you can use to highlight changes to import costs and the like
• ENVOY_BANDS[].TO From and To are start and end times in 24hr format (must include a leading 0 eg 0700)
• ENVOY_BANDS[].COLOUR The Colour field can be formatted like #55BF3B or rgba(200, 60, 60, .2)

External Configuration file

The easiest way to configure the bands is with an external configuration file

• Create a file called application.properties containing values like the following (defining 2 bands 8am-12pm & 4pm-6pm)

envoy.bands[0].from = 0800
envoy.bands[0].to = 1200
envoy.bands[0].colour = #55BF3B
envoy.bands[1].from = 1600
envoy.bands[1].to = 1800
envoy.bands[1].colour = rgba(200, 60, 60, .2)

• Pass the file to the jar using the spring.config.additional-location parameter

java -jar enphasecollector.jar --spring.config.additional-location=file:application.properties

All properties can be configured this way and will override any defaults set in the jar. Check the application.properties file for more properties that can be set

For Docker you will need a local directory to hold the file

docker run \
-e TZ=your-timezone \
-e ENVOY_CONTROLLER_PASSWORD=envoy-password \
-e ENVOY_CONTROLLER_HOST=envoy-ip \
-p 8080:8080 \
--mount target=/internal_db,source=host_path
--mount target=/properties,source=host_path
dlmcpaul/enphasecollector

Exposing this application to the web

While I make every effort to make this application secure I cannot make any guarantees. The application should be hosted behind a firewall and only exposed through a reverse proxy which includes an authentication mechanism and utilises https.

Dependencies

• Docker (or Java 17)

• If profile set to influxdb then an Influx DB is needed for storage of the statistics (Will autocreate 2 databases called 'solardb' and 'collectorStats')

• If profile set to pvoutput then every 5m the stats will be uploaded to your account at https://pvoutput.org (you will need to create an account to to get the systemid and key)

• You can set both profiles separated by a comma eg influxdb,pvoutput

• The internal database is always populated so the local view is always available at /solar

• Stats can be pulled to Prometheus by using the Actuator endpoint configured at /solar/actuator/prometheus