Enphase Cloud Integrations

Enphase Cloud Integrations

This page descirbes the Cloud Integrations support for Enphase.

Enphase Integration service

The Enphase integration service identifier is s10k.c2c.i9n.enphase. The following service properties are supported:

Property	Description
apiKey	The Enphase API key to use.
oauthClientId	The OAuth client identifier to use for refreshing access tokens.
oauthClientSecret	The OAuth client secret to use for refreshing access tokens.
oauthAccessToken	The OAuth access token to start with. This will be refreshed internally over time. See below for more details.
oauthRefreshToken	The user login password to use for authentication.
baseUrl	An optional alternate URL to use to access the cloud service.

Enphase OAuth support

Enphase uses the authorization code OAuth flow, which requires a browser-based UI to procure access and refresh token values, as required by the oauthAccessToken and oauthRefreshToken service properties. This UI must be handled outside the SolarNetwork API. See the Enphase developer docs for more details. Once the access and refresh token values are obtained, they can be saved on the Cloud Integration entity. SolarNetwork will then refresh the token going forward, as needed.

☝️ Note that the refreshed token values will not be updated on the Cloud Integration entity service properties. SolarNetwork will maintain the updated values internally.

⚠️ If the token refresh process fails for any reason, such as from another application refreshing the same access token or the token being revoked, the integration with Enphase will break as SolarNetwork will no longer be able to authenticate with Enphase. To remedy this situation, repeat the original token procurement process and update the Cloud Integration entity with new oauthAccessToken and oauthRefreshToken values.

Enphase Datum Stream services

The Enphase integration supports the following Cloud Datum Stream Service implementations:

Service	Identifier	Description
Enphase	s10k.c2c.ds.enphase	Polling datum stream using the Enphase API.

Enphase Datum Stream Service

The Enphase datum stream service identifier is s10k.c2c.ds.enphase.

The following service properties are supported:

Property	Description
placeholders	An optional Map of placeholder names with asscoiated values, to make available to Datum Stream Mapping Property value references
sourceIdMap	A map or comma-delimited mapping list of component IDs to associated source ID values. See source ID mapping for more information.
upperCaseSourceId	When true then force all source ID values to upper case. Defaults to false if not specified.

The following placeholders are supported on the placeholders service property:

Placeholder	Description
systemId	A single Enphase system ID value to associate with the datum stream
deviceId	A single Enphase device ID value to associate with the datum stream, or sys for system-level aggregate data

⚠️ Currently only system-level data is supported by the Enphase Datum Stream Service. That means the only supported device ID is sys.

The following Data Filters are supported:

Filter Key	Description
systemId	An Enphase system ID value

Datum Stream data value metadata

The Enphase integration uses the following data value cloud-speicifc metadata keys:

Key	Description
lastSeenAt	The date a system last connected to Enphase, in YYYY-MM-DD HH:MM:SS'Z' format.

Data value hiearachy

The Enphase cloud data value model is represented in 4 levels:

1. System
2. Device type
3. Device
4. Field (property)

System and Device objects have unique IDs, with sys being a device constant used for "system level" data. Device type is one of inv or met. Fields have names like W or WhDel. Value references are formed as:

/{systemId}/{deviceType}/{deviceId}/{fieldName}

For example:

/12345/inv/sys/W

Using placeholders a value reference could be instead specified like:

/{systemId}/inv/sys/W

Device types

The device types supported by this service are:

Device Type	Description
inv	The Enphase microinverter type. For system-level data uses the /api/v4/systems/{systemId}/telemetry/production_micro Enphase API endpoint.
met	The Enphase revenue-grade meter type. For system-level data uses the /api/v4/systems/{system_id}/rgm_stats Enpahse API endpoint.

💡 Note that when polling for data, SolarNetwork will use the last_report_at metadata value returned in the Enphase API response to determine the start date to use the next time SolarNetwork polls for data. If multiple device types are configured on a single Cloud Datum Stream, then the oldest last_report_at date returned across all API calls will be used for the next start date. If one device type lags behind another, this can impact the overall progress of the polling data collection process: progress will be limited by the lagging device. You can always split the Cloud Datum Stream into multiple configurations, one for each device type, to allow each stream to progress independently.

Datum Stream source ID mapping

By default the Enphase Datum Steam service will generate unique source IDs based on the combination of the Datum Stream sourceId value and the pattern /{systemId}/{deviceType}/{deviceId} taken from the configured data value references in the stream's property mappings.

Source ID mapping example

Assuming your Datum Stream was configured with a sourceId of S01, you could configure mapping properties like this:

Value Reference	SolarNetwork Property	Property Type
/12345/inv/sys/W	watts	i
/12345/inv/sys/Wh	wh	i
/12345/met/sys/W	watts	i
/12345/met/sys/WhExp	wh	i

Because Enphase does not provide meter-reading style energy data fields typically mapped to an accumulting wattHours property , an expression property can be used to derive one, like this:

has('wh') && hasOffset(1, timestamp)
	&& offset(1, timestamp).props['wattHours'] != null
? offset(1, timestamp).wattHours + wh
: has('wh')
? wh
: 0

Then SolarNetwork would generate 2 datum streams, both with watts and wh and wattHours properties:

1. S01/12345/inv/sys
2. S01/12345/met/sys

Datum Stream explicit source ID mapping

You can also define an explicit mapping of components to source IDs with a sourceIdMap service property on a Datum Stream. This can be specified as a map or comma-delimited mapping list of component IDs to associated source ID values. For example in JSON, the sourceIdMap service property could be specified as an object like:

{"/12345/inv/sys":"S1/INV", "/12345/met/sys":"S1/GEN"}

or a string like:

"/12345/inv/sys=S1/INV, /12345/met/sys=S1/GEN"

A complete example of the Datum Stream could look like this:

{
  "enabled": true,
  "name": "Enphase Test",
  "datumStreamMappingId": 1,
  "schedule": "300",
  "kind": "n",
  "objectId": 123,
  "sourceId": "unused",
  "serviceIdentifier": "s10k.c2c.ds.enphase",
  "serviceProperties": {
	"sourceIdMap": {
	  "/12345/inv/sys": "S1/INV",
	  "/12345/met/sys": "S1/GEN"
	}
  }
}

Here the generated datum streams would be S1/INV and S1/GEN because of the sourceIdMap setting. The unused sourceId setting would not be used, and SolarNetwork would generate 2 datum streams, both with watts and wattHours properties:

1. S1/INV
2. S1/GEN

☝️ When sourceIdMap is configured, only the devices explicitly included will be generated into datum streams, and all other devices will be ignored.

Datum Stream explicit source ID mapping automatic placeholders

When an explicit sourceIdMap service property is configured, a set of placeholders is automatically generated from the mapping keys:

1. {systemId}
2. {deviceId}

This means you can configure value references that take advantage of those placeholders in the stream's associated datum property mappings. For example, given the previous sourceIdMap example:

{
   "sourceIdMap": {
	  "/12345/inv/sys": "S1/INV",
	  "/12345/met/sys": "S1/GEN"
	}
}

and a set of property mappings like this:

Value Reference	SolarNetwork Property	Property Type
/{systemId}/inv/sys/W	watts	i
/{systemId}/inv/sys/Wh	wh	i
/{systemId}/met/sys/W	watts	i
/{systemId}/met/sys/WhExp	wh	i

Then both the S1/INV and S1/GEN datum streams would include the watts and wh properties, taken from effective value references of:

Effective Value Reference	SolarNetwork Property	Property Type
/12345/inv/sys/W	watts	i
/12345/inv/sys/Wh	wh	i
/12345/met/sys/W	watts	i
/12345/met/sys/WhExp	wh	i

Datum Import support

This service supports the Cloud Datum Stream import service.