OSCP

SolarNetwork provides an Open Smart Charging Protocol (OSCP) 2.0 Flexibility Provider service that OSCP compliant Capacity Provider and Capacity Optimizer systems can integrate with, in order to manage real-time electrical grid demand response functionality.

The following acronyms are used throughout the OSCP documentation in SolarNetwork:

Acronym	Meaning
FR	A Flexibility Resource or asset, is a device that produces or consumes electric energy, such as Charging Stations, PV panels, (stationary) batteries, etc.
CP	A Capacity Provider system, that integrates with the SolarNetwork OSCP Flexibility Provider API. The CP manages the actual energy used or provided by the Flexibility Resources with respect to a wider electrical grid. The CP issues energy capacity forecasts to SolarNetwork, which are forwarded to an associated CO for potential load balancing action outcomes.
CO	A Capacity Optimizer system, that integrates with the SolarNetwork OSCP Flexibility Provider API. The CO is responsible for analyzing and optimizing energy usage, and issuing instructions to SolarNetwork for executing any energy management tasks.
FP	A Flexibility Provider system, in this case SolarNetwork, that facilitates electrical grid load balancing outcomes in response to forecasts issued by a CP and analyzed and then actioned by a CO.
CG	A Capacity Group defines a set of Flexibility Resources that can be managed by a CP and CO pairing as a single unit.

Within SolarNetwork, the OSCP Flexibility Provider system works like this:

SolarNode devices represent Flexibility Resources (assets) that have energy measurements captured into datum streams and can be controlled via the SolarNetwork Instruction API. Note that OCPP chargers integrated with SolarNetwork can be used as Flexibility Resources!
The SolarUser OSCP API provides an API so you can manage the credentials and other settings required for CP and CO systems to integrate with SolarNetwork. Each system integration requires both inbound and outbound credentials, as OSCP message requests flow in both directions between those systems and SolarNetwork.
OSCP defines its own token-based HTTP authentication scheme and a mutual registration process for systems to integrate with each other. SolarNetwork also supports using OAuth2 access tokens in place of that scheme, using the OAuth2 client credentials authentication flow. OAuth can be used for both inbound and outgoing messages.
A Capacity Group is what SolarNetwork uses to facilitate integration between a CP system and a CO system. Any number of groups can be configured, and each group operates as an independent integration point.

OSCP connection

To connect a CP or CO system to SolarNetwork using OSCP, the following settings must be used:

Setting	Value	Description
URL	https://oscp.solarnetwork.net/oscp/fp/2.0	The URL systems must connect to.
Token URL	https://auth.oscp.solarnetwork.net/oauth2/token	If OAuth2 authentication is used, this is the URL for systems to acquire access tokens from.

OSCP entities

Within SolarNetwork, the following entities are managed via the SolarUser OSCP API:

User Settings entity

The user settings are account-wide settings for things like datum publishing.

See the User settings update API for details.

Capacity Provider entity

The Capacity Provider entity contains the settings necessary for SolarNetwork to communiate with an external CP system, such as the URL and credentials to use.

See the Capacity Provider create API for details.

Capacity Optimizer entity

The Capacity Optimizer entity contains the settings necessary for SolarNetwork to communiate with an external CO system, such as the URL and credentials to use.

See the Capacity Optimizer create API for details.

Capacity Group entity

The Capacity Group entity pairs a single CP entity with a single CO entity and defines the settings that define how the group operates, such as the measurement reporting frequency. A group also defines a set of Asset entities.

See the Capacity Group create API for details.

Capacity Group Settings entity

The Capacity Group settings are capacity group-specific settings that override any configured account-wide user settings.

See the Capacity Group settings update API for details.

Asset entity

The Asset entity contains the settings that define a Flexibility Resource within SolarNetwork. It contains settings like the node ID and source ID of the asset's measurement datum stream.

See the Asset create API for details.

Datum stream publishing

SolarNetwork can generate datum streams out of specific OSCP interactions, and those datum can be published to both SolarIn and SolarFlux. The node ID and source ID for the generated datum streams are configured on User Settings and Capacity Group Settings entities. The User Settings serve as account-wide default values and Capacity Group Settings are group-specific values that override the User Setting values if needed.

Datum stream source ID templates

The source ID for each stream is derived from the sourceIdTemplate setting value, which supports template parameters in the form {parameterName} which are replaced by the value of the named parameter at runtime. The default source ID template is:

/oscp/{role}/{action}/{cp}/{co}/{cgIdentifier}

The following general template parameters are supported:

Parameter	Description
`action`	An Action name.
`actionCode`	A shortened Action name that includes only the upper-case letters from the action name, then changed to all lowercase. For example `UpdateGroupCapacityForecast` becomes `ugcf`. Can be useful for keeping the resolved source ID within its 64 character limit.
`cg`	The `configId` value of a Capacity Group entity.
`cgIdentifier`	The `identifier` value of a Capacity Group entity.
`cgName`	The `name` value of a Capacity Group entity.
`co`	The `configId` value of a Capacity Optimizer entity.
`coName`	The `name` value of a Capacity Optimizer entity.
`cp`	The `configId` value of a Capacity Provider entity.
`cpName`	The `name` value of a Capacity Provider entity.
`dest`	The `configId` value of the system entity that is the intended recipient of the action.
`role`	A Role alias.
`src`	The `configId` value of the system entity that initiated the action, typically the entity represented by `role`.

Heartbeat datum stream

SolarNetwork turns Heartbeat OCSP messages received from Capacity Provider systems into datum streams. The timestamp for each datum is set to the time the heartbeat message is received by SolarNetwork.

Each datum will contain the following properties:

Datum Property	Classif.	Description
`nodeId`		The `nodeId` property on the account's user settings.
`sourceId`		The source ID derived from the `sourceIdTemplate` property of the resolved user settings. See Datum stream source ID templates for more information.
`created`		The date the heartbeat message is received.
`expires`	`s`	The "offline mode at" timestamp from the heartbeat message, in a `yyyy-MM-dd HH:mm:ss.SZ` format.

An example datum looks like this:

{
	"created": "2022-10-19 05:12:00.221262Z",
	"expires": "2022-10-19 05:16:00.005Z"
}

UpdateCapacityGroupForecast datum stream

SolarNetwork turns UpdateCapacityGroupForecast OCSP messages received from Capacity Provider systems into datum streams. This message contains a list of time block amount objects. Each time block amount is turned into a single datum. Thus a single UpdateCapacityGroupForecast message can generate many datum. The timestamp for each datum is set to the start date of the time block.

Each datum will contain the following properties:

Datum Property	Classif.	Description
`nodeId`		The `nodeId` property on the resolved group or user settings.
`sourceId`		The source ID derived from the `sourceIdTemplate` property of the resolved group or user settings, with `/{forecastType}` appended (see below). Also see Datum stream source ID templates for more information.
`created`		The date associated with this time block.
`duration`	`i`	The difference between the start and end dates of the time block, in seconds.
`amount`	`i`	The amount associated with the time block, in `unit` units.
`unit`	`s`	The measurement unit.
`forecastIdentifier`	`s`	The `X-Request-ID` provided by the Capacity Provider.

UpdateCapacityGroupForecast forecast type source ID

The source ID derived from the sourceIdTemplate of the resolved settings will automatically have /{forecastType} appended, where {forecastType} is a Forecast Type alias.

🔥 Note that SolarNetwork will include an X-SN-SOURCE-ID HTTP header with the resolved source ID value when posting the UpdateCapacityGroupForecast message to the CO.

UpdateCapacityGroupForecast phase-based property names

Multiple blocks with the same start date and differing phase values will be consolidated into a single output datum. The duration, amount, and unit values will have _{phase} appended to each property name, where {phase} is a phase alias, except when the phase is All (in which case nothing is appended).

⚠️ Note that time blocks that share a start date but differ in phase and end date are not supported. The blocks will be consolidated into a single datum still, but the resolved duration value of the datum is undefined. If multiple phase blocks are used for a given start date, they must all share the same start and end times.

UpdateCapacityGroupForecast datum stream example

Here is an example OSCP 2.0 UpdateCapacityGroupForecast message that defines 3 8-hour time blocks over a single day:

{
  "group_id" : "g1",
  "type"     : "CONSUMPTION",
  "forecasted_blocks" : [
    {
      "capacity"   : 1234,
      "phase"      : "ALL",
      "unit"       : "KW",
      "start_time" : "2022-10-01T00:00:00Z",
      "end_time"   : "2022-10-01T08:00:00Z"
    },
    {
      "capacity"   : 2345,
      "phase"      : "ALL",
      "unit"       : "KW",
      "start_time" : "2022-10-01T08:00:00Z",
      "end_time"   : "2022-10-01T16:00:00Z"
    },
    {
      "capacity"   : 3456,
      "phase"      : "ALL",
      "unit"       : "KW",
      "start_time" : "2022-10-01T16:00:00Z",
      "end_time"   : "2022-10-02T00:00:00Z"
    }
  ]
}

If we assume resolved settings of:

Setting	Resolved value
`nodeId`	`1`
`sourceIdTemplate`	`/oscp/{role}/{action}/{cp}/{co}/{cgIdentifier}`

and runtime parameters of:

Parameter	Resolved value
`role`	`cp`
`action`	`UpdateCapacityGroupForecast`
`cp`	`123`
`co`	`234`
`cgIdentifier`	`g1`

then the resolved source ID would be:

/oscp/cp/UpdateCapacityGroupForecast/123/234/g1/c

⚠️ Note the /c forecast type appended to the source ID! This comes from the "type" : "CONSUMPTION" part of the OSCP message.

The following 3 datum would be generated from this message (one for each time block):

[
  {
    "created"            : "2022-10-01 00:00:00Z",
    "duration"           : "28800"
    "amount"             : 1234,
    "unit"               : "kW",
    "forecastIdentifier" : "slkdj-dlke3jlkj-dl3e93jlk"
  },
  {
    "created"            : "2022-10-01 08:00:00Z",
    "duration"           : "28800"
    "amount"             : 2345,
    "unit"               : "kW",
    "forecastIdentifier" : "slkdj-dlke3jlkj-dl3e93jlk"
  },
  {
    "created"            : "2022-10-01 16:00:00Z",
    "duration"           : "28800"
    "amount"             : 3456,
    "unit"               : "kW",
    "forecastIdentifier" : "slkdj-dlke3jlkj-dl3e93jlk"
  }
]

UpdateCapacityGroupForecast datum stream example with phases

Here is an example OSCP 2.0 UpdateCapacityGroupForecast message with 4 blocks that define different phase amounts for a single 8-hour period (notice how the start and end times are identical in all blocks):

{
  "group_id" : "g1",
  "type"     : "CONSUMPTION",
  "forecasted_blocks" : [
    {
      "capacity"           : 1234,
      "phase"              : "ALL",
      "unit"               : "KW",
      "forecastIdentifier" : "slkdj-dlke3jlkj-dl3e93jlk",
      "start_time"         : "2022-10-01 00:00:00Z",
      "end_time"           : "2022-10-01 08:00:00Z"
    },
    {
      "capacity"           : 2345,
      "phase"              : "ONE",
      "unit"               : "KW",
      "forecastIdentifier" : "slkdj-dlke3jlkj-dl3e93jlk",
      "start_time"         : "2022-10-01 00:00:00Z",
      "end_time"           : "2022-10-01 08:00:00Z"
    },
    {
      "capacity"           : 3456,
      "phase"              : "TWO",
      "unit"               : "KW",
      "forecastIdentifier" : "slkdj-dlke3jlkj-dl3e93jlk",
      "start_time"         : "2022-10-01 00:00:00Z",
      "end_time"           : "2022-10-01 08:00:00Z"
    },
    {
      "capacity"           : 4567,
      "phase"              : "THREE",
      "unit"               : "KW",
      "forecastIdentifier" : "slkdj-dlke3jlkj-dl3e93jlk",
      "start_time"         : "2022-10-01 00:00:00Z",
      "end_time"           : "2022-10-01 08:00:00Z"
    }
  ]
}

Assuming the same settings and parameters as the previous example, the following datum would be generated from this message (phases consolidated):

[
  {
    "created"            : "2022-10-01T00:00:00Z",
    "duration"           : "28800"
    "amount"             : 1234,
    "unit"               : "kW",
    "forecastIdentifier" : "slkdj-dlke3jlkj-dl3e93jlk",
    "amount_a"           : 2345,
    "unit_a"             : "kW",
    "amount_b"           : 3456,
    "unit_b"             : "kW",
    "amount_c"           : 4567,
    "unit_c"             : "kW"
  }
]

Provide feedback

Saved searches

Use saved searches to filter your results more quickly