AlsoEnergy Cloud Integrations

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.

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 hiearachy

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.