SolarUser OSCP API instructions

The SolarUser OSCP API supports sending OSCP messages to integrated Capacity Providers via the SolarUser /instr/add instruction API. All standard OSCP messages that can be initiated by an OSCP Capacity Optimizer and related to a Capacity Group are supported. This guide has documentation on the most common messages for convenience.

OSCP v2.0

For OSCP 2.0, the instruction topic must be OSCP_v20, e.g. the endpoint to use is /instr/add/OSCP_v20. The following request properties are common to all requests:

Property	Type	Description
topic	string	Must be OSCP_v20.
nodeId	number	The node ID the instruction is associated with.
params	object	The message parameters object. Note that all values must be provided as strings.
params.action	string	The OSCP v2.0 message name. The supported values are outlined later in this document.
params.coId	string	The configId value of a Capacity Optimizer entity.
params.cgIdentifier	string	The identifier value of a Capacity Group entity.
params.msg	string	The OSCP 2.0 action message as JSON. If longer than 256 characters, will be split into multiple msg parameters automatically, each at most 256 characters long.
params.correlationId	string	An OSCP request correlation include with the message.

Each supported OSCP v2.0 message requires a specific params.action value and an OSCP 2.0 JSON message via the params.msg value.

For example, you could send a GroupCapacityComplianceError message to a Capacity Provider using a JSON value like this (note now the params.msg value is a JSON-escaped string value, not nested JSON):

{
  "nodeId" : "1",
  "params" : {
    "coId" : "1",
    "cgIdentifier" : "foo-group",
    "action" : "GroupCapacityComplianceError",
    "msg" : "{\"message\":\"Whoops!\",\"forecasted_blocks\":[{\"capacity\":123.456,\"unit\":\"KW\",\"phase\":\"ALL\",\"start_time\":\"2022-10-08T18:00:00Z\",\"end_time\":\"2022-10-08T18:15:00Z\"}]}",
    "correlationId" : "sdldkj0-1lk3j389-flk4230fhfg"
  }
}

OSCP v2.0 Messages

This section outlines the OSCP v2.0 messages most relevant to SolarNetwork.

Action	Description
AdjustGroupCapacityForecast	Request an adjustment to a Capacity Group's capacity forecast.
GroupCapacityComplianceError	Report a Capacity Group compliance error.
Handshake	Initiate a handshake.

AdjustGroupCapacityForecast

The AdjustGroupCapacityForecast action provides a way to request an adjustment to a Capacity Group's capacity forecast from the Capacity Provider associated with a group. See §4.4.2 of the OSCP 2.0 specification for more information.

The following params values are defined for this action:

Property	Description
action	AdjustGroupCapacityForecast
coId	The configId value of a Capacity Optimizer entity.
cgIdentifier	The identifier value of a Capacity Group entity.
msg	The OSCP 2.0 AdjustGroupCapacityForecast message as JSON. If longer than 256 characters, will be split into multiple msg parameters automatically, each at most 256 characters long.
correlationId	The request ID of the UpdateGroupCapacityForecast this adjustment refers to.

An example POST to /solaruser/api/v1/sec/instr/add/OSCP_v20 looks like this:

{
  "nodeId" : "1",
  "params" : {
    "coId" : "1",
    "cgIdentifier" : "foo-group",
    "action" : "AdjustGroupCapacityForecast",
    "msg" : "{\"group_id\":\"foo-group\",\"type\":\"CONSUMPTION\",\"forecasted_blocks\":[{\"capacity\":123.456,\"unit\":\"KW\",\"phase\":\"ALL\",\"start_time\":\"2022-10-08T18:00:00Z\",\"end_time\":\"2022-10-08T18:15:00Z\"}]}",
    "correlationId" : "sdldkj0-1lk3j389-flk4230fhfg"
  }
}

GroupCapacityComplianceError

The GroupCapacityComplianceError action provides a way to report a Capacity Group compliance error to the Capacity Provider associated with a group. See §4.4.3 of the OSCP 2.0 specification for more information.

The following params values are defined for this action:

Property	Description
action	GroupCapacityComplianceError
coId	The configId value of a Capacity Optimizer entity.
cgIdentifier	The identifier value of a Capacity Group entity.
msg	The OSCP 2.0 GroupCapacityComplianceError message as JSON. If longer than 256 characters, will be split into multiple msg parameters automatically, each at most 256 characters long.
correlationId	The request ID of the UpdateGroupCapacityForecast this adjustment refers to.

An example POST to /solaruser/api/v1/sec/instr/add/OSCP_v20 looks like this:

{
  "nodeId" : "1",
  "params" : {
    "coId" : "1",
    "cgIdentifier" : "foo-group",
    "action" : "GroupCapacityComplianceError",
    "msg" : "{\"message\":\"Whoops!\",\"forecasted_blocks\":[{\"capacity\":123.456,\"unit\":\"KW\",\"phase\":\"ALL\",\"start_time\":\"2022-10-08T18:00:00Z\",\"end_time\":\"2022-10-08T18:15:00Z\"}]}",
    "correlationId" : "sdldkj0-1lk3j389-flk4230fhfg"
  }
}

Handshake

The Handshake action provides a way to initiate an OSCP "handshake" protocol negotiation with the Capacity Provider associated with a group. See §4.3.2 of the OSCP 2.0 specification for more information.

The following params values are defined for this action:

Property	Description
action	Handshake
coId	The configId value of a Capacity Optimizer entity.
cgIdentifier	The identifier value of a Capacity Group entity.
msg	The OSCP 2.0 Handshake message as JSON. If longer than 256 characters, will be split into multiple msg parameters automatically, each at most 256 characters long.

An example POST to /solaruser/api/v1/sec/instr/add/OSCP_v20 looks like this:

{
  "nodeId" : "1",
  "params" : {
    "coId" : "1",
    "cgIdentifier" : "foo-group",
    "action" : "Handshake",
    "msg": "{\"required_behaviour\":{\"heartbeat_interval\":60,\"measurement_configuration\":[\"CONTINUOUS\"]}}"
  }
}