AlsoEnergy Cloud Integrations - SolarNetwork/solarnetwork GitHub Wiki

AlsoEnergy Cloud Integrations

This page descirbes the Cloud Integrations support for AlsoEnergy.

AlsoEnergy Integration service

The AlsoEnergy integration service identifier is s10k.c2c.i9n.also. The following service properties are supported:

Property Description
oauthClientId The OAuth client identifier to use for authentication. Note this value is not actually used, but one must be provided and can be configured as anything.
username The user login name to use for authentication.
password The user login password to use for authentication.
baseUrl An optional alternate URL to use to access the cloud service.

AlsoEnergy Datum Stream services

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

Service Identifier Description
AlsoEnergy s10k.c2c.ds.also Polling datum stream using the AlsoEnergy API.

AlsoEnergy Datum Stream Service

The AlsoEnergy datum stream service identifier is s10k.c2c.ds.also. The following service properties are supported:

Property Description
granularity The resolution of the data to request. One of Raw, FiveMinute, FifteenMinute, Hour, Day, Month, Year. Defaults to Raw if not specified.
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.
multiStreamMaximumLag A maximum amount of time to accommodate partially reported data across multiple datum streams before giving up. When resolving multiple datum streams within a request and any stream lags behind other streams, the polling reference time will not advance beyond the lagging stream's latest timestamp for at most this duration. Can be specified as an ISO duration like PT2H for "2 hours" or an integer number of seconds. Defaults to PT3H (3 hours). Configure as PT0S or 0 to disable.
virtualSourceIds A list or comma-delimited list of virtual source IDs. See Virtual datum streams for more information.

The following placeholders are supported on the placeholders service property:

Placeholder Description
siteId A single AlsoEnergy site ID value to associate with the datum stream
hardwareId A single AlsoEnergy hardware ID value to associate with the datum stream

The following Data Filters are supported:

Filter Key Description
siteId An AlsoEnergy site ID value

Datum Stream data value metadata

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

Key Description
functionCode Hardware function code, from the Hardware.functionCode AlsoEnergy API property
deviceType Hardware configuration device type, from the DeviceConfig.deviceType AlsoEnergy API property

Data value hierarchy

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

  1. Site
  2. Hardware (device)
  3. Field (property)
  4. Function (aggregate)

Site and Hardware objects have unique number IDs, fields have names like KwhAC or Iab, and functions are a fixed enumeration of values like Last, Avg, Min, Max, and so on. Value references are formed as:

/{siteId}/{hardwareId}/{fieldName}/{function}

For example:

/12345/23456/KwhAC/Avg

Using placeholders a value reference could be instead specified like:

/{siteId}/{hardwareId}/KwhAC/Avg

Datum Stream source ID mapping

By default the AlsoEnergy Datum Steam service will generate unique source IDs based on the combination of the Datum Stream sourceId value and the pattern /{siteId}/{hardwareId} 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/11111/KW/Last watts i
/12345/11111/KWHnet/Last wattHours a
/12345/22222/KW/Last watts i
/12345/22222/KWHnet/Last wattHours a

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

  1. S01/12345/11111
  2. S01/12345/22222

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/111111":"S1/INV/01", "/12345/22222":"S1/GEN/01"}

or a string like:

"/12345/111111=S1/INV/01, /12345/22222=S1/GEN/01"

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

{
  "enabled": true,
  "name": "AlsoEnergy Test",
  "datumStreamMappingId": 1,
  "schedule": "300",
  "kind": "n",
  "objectId": 123,
  "sourceId": "unused",
  "serviceIdentifier": "s10k.c2c.ds.also",
  "serviceProperties": {
    "sourceIdMap": {
      "/12345/111111": "S1/INV/01",
      "/12345/222222": "S1/GEN/01"
    }
  }
}

Here the generated datum streams would be S1/INV/01 and S1/GEN/01 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/01
  2. S1/GEN/01

☝️ 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. {siteId}
  2. {hardwareId}

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/111111": "S1/INV/01",
      "/12345/222222": "S1/GEN/01"
    }
}

and a set of property mappings like this:

Value Reference SolarNetwork Property Property Type
/{siteId}/{hardwareId}/KW/Last watts i
/{siteId}/{hardwareId}/KWHnet/Last wattHours a

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

Effective Value Reference SolarNetwork Property Property Type
/12345/11111/KW/Last watts i
/12345/11111/KWHnet/Last wattHours a
/12345/22222/KW/Last watts i
/12345/22222/KWHnet/Last wattHours a

Datum Import support

This service supports the Cloud Datum Stream import service.

Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️