This page descirbes the Cloud Integrations support for SMA. See SMA API for information about their API.

The SMA integration service identifier is s10k.c2c.i9n.sma. The following service properties are supported:

SMA 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 SMA 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.

💡 You can include the offline_access scope in the token request to give SolarNetwork a persistent refresh token. See the Token Handling section in the SMA documentation for more details.

☝️ 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 SMA 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.

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

The SMA datum stream service identifier is s10k.c2c.ds.sma.

The following service properties are supported:

The following placeholders are supported on the placeholders service property:

The following Data Filters are supported:

The SMA integration uses the following data value cloud-speicifc metadata keys (refer to the SMA API documentation for more information on possible values):

The SMA cloud data value model is represented in 3 levels:

1. System (plant)
2. Device
3. Measurement Set (property group)
4. Measurement (property)

System and Device objects have unique IDs. Measurement Set is one of EnergyAndPowerBattery, EnergyAndPowerConsumption, EnergyAndPowerInOut, EnergyAndPowerPv, EnergyMix, PowerAc, PowerDc, EnergyDc, and Sensor. Measurements have names like pvGeneration or dcPowerInput. Each Measurement Set defines a specific set of possible Measurements, but not all devices will provide all possible measurements for a given set.

Value references are formed as:

/{systemId}/{deviceId}/{measurementSet}/{measurementName}

For example:

/12345/67890/EnergyAndPowerPv/pvGeneration

Using placeholders a value reference could be instead specified like:

/{systemId}/{deviceId}/EnergyAndPowerPv/pvGeneration

💡 The EnergyAndPower* measurement sets provide either energy or power values. SolarNetwork will always request energy values. Thus the example reference above will return PV generated energy values, in Wh.

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

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

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

1. S01/12345/67890
2. S01/23456/78901

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/67890":"S1/INV", "/23456/78901":"S2/INV"}

or a string like:

"/12345/67890=S1/INV, /23456/78901=S2/INV"

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

{
  "enabled": true,
  "name": "SMA Test",
  "datumStreamMappingId": 1,
  "schedule": "1800",
  "kind": "n",
  "objectId": 123,
  "sourceId": "unused",
  "serviceIdentifier": "s10k.c2c.ds.sma",
  "serviceProperties": {
	"sourceIdMap": {
	  "/12345/67890": "S1/INV",
	  "/23456/78901": "S2/INV"
	}
  }
}

The unused sourceId setting would not be used, and SolarNetwork would generate 2 datum streams:

1. S1/INV
2. S2/INV

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

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/67890": "S1/INV",
	  "/23456/78901": "S2/INV"
	}
}

and a set of property mappings like this:

Then both the S1/INV and S2/INV datum streams would be resolved. The effective value references are:

Because SMA does not provide meter-reading style energy data channels typically mapped to an accumulting wattHours property, an expression property can be used to derive one. For example, assuming a wh property mapped from a pvGeneration measurement:

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

With the SMA API, SolarNetwork must request each Measurement Set individually, and each set may contain "holes" of missing data, when a device did not report a value. You might configure SolarNetwork to combine multiple measurment sets into a single stream, which can lead to "missing" properties from gaps in one or more of the measurement set data. Sometimes this can lead to unexpected results, especially if you are using expressions that calculate differences, like the wattHours expression shown in the previous section.

For example, continuing the previous mapping example, we could end up with a situation like this:

The last wattHours is not the expected outcome: we want 340 to be carried foward by assumming that missing pvGeneration should be treated as 0.

To handle this situation, you can add another expression on the wh property, before the wattHours expression, that coalesces missing wh values to 0:

has('wh') ? wh : 0

With that expression configured, the last row in our example changes to the expected result:

This service supports the Cloud Datum Stream import service.