Skip to content

cloud.smarthq.service.demandresponse.event.v1

  • Configuration

    Describes boundaries and fixed properties for the service.

    Go There

  • State

    A list of the states this service can be in.

    Go There

  • Commands

    How to change the state of the service.

    Go There

  • Data Types

    All the data types used for this service.

    Go There

Description

Service for reading and writing available demand response events to an appliance

Example Device Response (Digital Twin API)

Example Service to read and write the demand response events to an appliance.

{
  "adapterId": "0000000000000000000000000000000000000000",
  "alertTypes": [],
  "createdDateTime": "2022-03-04T12:12:12.123Z",
  "deviceId": "0000000000000000000000000000000000000000000000000000000000000000",
  "deviceType": "cloud.smarthq.device.ptac",
  "gatewayId": "0000000000000000000000000000000000000000000000000000000000000000",
  "kind": "device#item",
  "lastPresenceTime": "2022-03-04T12:12:12.123Z",
  "lastSyncTime": "2022-03-04T12:12:12.123Z",
  "presence": "OFFLINE",
  "removable": true,
  "services": [
    {
      "serviceType": "cloud.smarthq.service.demandresponse.event.v1",
      "lastSyncTime": "2022-03-04T12:12:12.123Z",
      "domainType": "cloud.smarthq.domain.demandresponse",
      "supportedCommands": [
        "cloud.smarthq.command.demandresponse.event.v1.set",
        "cloud.smarthq.command.demandresponse.event.v1.useroption.set"
      ],
      "state": {
        "eventId": "b5a1d4d3f5f5d1d1e6f5e5a5f5e5d1d1",
        "curtailmentLevel": 3.0,
        "temperatureOffset": 5.5,
        "eventStatus": "cloud.smarthq.type.demandresponse.eventstatus.active",
        "userOption": "cloud.smarthq.type.demandresponse.useroption.optin"
      },
      "serviceId": "0000000000000000000000000000000000000000000000000000000000000000",
      "serviceDeviceType": "cloud.smarthq.device.appliance",
      "config": {
        "curtailmentLevelMaximum": 3.0,
        "eventStatusesAvailable": [
          "cloud.smarthq.type.demandresponse.eventstatus.noevent",
          "cloud.smarthq.type.demandresponse.eventstatus.active",
          "cloud.smarthq.type.demandresponse.eventstatus.cancelled"
        ],
        "userOptionsAvailable": [
          "cloud.smarthq.type.demandresponse.useroption.optin",
          "cloud.smarthq.type.demandresponse.useroption.optout"
        ],
        "curtailmentLevelMinimum": 1.0
      },
      "lastStateTime": "2022-03-04T12:12:12.123Z"
    }
  ],
  "userId": "000000000000000"
}

Configuration

The following are properties for the gateway/device sync as part of the "config" object for each individual service.

Field Name Property Type Required
curtailmentLevelMaximum INTEGER Yes
curtailmentLevelMinimum INTEGER Yes
eventStatusesAvailable SET<DEMAND_RESPONSE_EVENT_STATUS> Yes
userOptionsAvailable SET<DEMAND_RESPONSE_USER_OPTION> Yes

State

The following are properties for the device state report as part of the "state" object for each individual service.

Field Name Property Type Required
curtailmentLevel INTEGER No
disabled BOOLEAN No
eventId STRING No
eventStatus DEMAND_RESPONSE_EVENT_STATUS Yes
temperatureOffset DOUBLE No
userOption DEMAND_RESPONSE_USER_OPTION No

Commands

The following are properties for both the Digital Twin API to send a command to the device as well as the properties passed as part of a command to the gateway to be processed by the device itself.

cloud.smarthq.command.demandresponse.event.v1.set

Command used to set the demand response events on the appliance.

Field Name Property Type Required
curtailmentLevel INTEGER Yes
eventId STRING Yes
eventStatus DEMAND_RESPONSE_EVENT_STATUS Yes
temperatureOffset DOUBLE No
userOption DEMAND_RESPONSE_USER_OPTION No

Example Commands

Command to set the demand response event on ptac.

{
  "command": {
    "eventId": "b5a1d4d3f5f5d1d1e6f5e5a5f5e5d1d1",
    "commandType": "cloud.smarthq.command.demandresponse.event.v1.set",
    "curtailmentLevel": 1.0,
    "eventStatus": "cloud.smarthq.type.demandresponse.eventstatus.active",
    "userOption": "cloud.smarthq.type.demandresponse.useroption.optin"
  },
  "deviceId": "00000000000000000000000000000000000000000000000000000000000000",
  "domainType": "cloud.smarthq.domain.demandresponse",
  "kind": "service#command",
  "serviceDeviceType": "cloud.smarthq.device.appliance",
  "serviceType": "cloud.smarthq.service.demandresponse.event.v1"
}

Supported Outcomes

Each service has an allow listed set of outcomes that the device may return when asked to execute a command.

Outcome Documentation
cloud.smarthq.outcome.badrequest The request was invalid.
cloud.smarthq.outcome.developererror Only used when there is a server side bug
cloud.smarthq.outcome.deviceoffline The device is offline.
cloud.smarthq.outcome.forbidden The request is forbidden due to permissions.
cloud.smarthq.outcome.internalerror The server had an issue processing the request
cloud.smarthq.outcome.missingconfig The service config is missing
cloud.smarthq.outcome.missingstate The service state is missing
cloud.smarthq.outcome.notallowed The command is not allowed.
cloud.smarthq.outcome.notfound The request is forbidden due to permissions.
cloud.smarthq.outcome.notsupported The command is not supported.
cloud.smarthq.outcome.servicedisabled Feature is currently disabled
cloud.smarthq.outcome.success Successful request
cloud.smarthq.outcome.timeout The server experienced timeout waiting for a response from the gateway

cloud.smarthq.command.demandresponse.event.v1.useroption.set

Command used to set the user option for demand response event.

Field Name Property Type Required
userOption DEMAND_RESPONSE_USER_OPTION Yes

Example Commands

Command to set the user option for an active demand response event on ptac.

{
  "command": {
    "commandType": "cloud.smarthq.command.demandresponse.event.v1.useroption.set",
    "userOption": "cloud.smarthq.type.demandresponse.useroption.optin"
  },
  "deviceId": "00000000000000000000000000000000000000000000000000000000000000",
  "domainType": "cloud.smarthq.domain.demandresponse",
  "kind": "service#command",
  "serviceDeviceType": "cloud.smarthq.device.appliance",
  "serviceType": "cloud.smarthq.service.demandresponse.event.v1"
}

Supported Outcomes

Each service has an allow listed set of outcomes that the device may return when asked to execute a command.

Outcome Documentation
cloud.smarthq.outcome.badrequest The request was invalid.
cloud.smarthq.outcome.developererror Only used when there is a server side bug
cloud.smarthq.outcome.deviceoffline The device is offline.
cloud.smarthq.outcome.forbidden The request is forbidden due to permissions.
cloud.smarthq.outcome.internalerror The server had an issue processing the request
cloud.smarthq.outcome.missingconfig The service config is missing
cloud.smarthq.outcome.missingstate The service state is missing
cloud.smarthq.outcome.notallowed The command is not allowed.
cloud.smarthq.outcome.notfound The request is forbidden due to permissions.
cloud.smarthq.outcome.notsupported The command is not supported.
cloud.smarthq.outcome.servicedisabled Feature is currently disabled
cloud.smarthq.outcome.success Successful request
cloud.smarthq.outcome.timeout The server experienced timeout waiting for a response from the gateway

Data Types

BOOLEAN

Value must be either true or false.

DOUBLE

Value must be an double. Field specific restrictions such as a minimum and maximum may apply depending on the field.

INTEGER

Value must be an integer. Field specific restrictions such as a minimum and maximum may apply depending on the field.

STRING

Value must be a sequence of characters, inserted between " and " (double quotes). Field specific restrictions such as a regular expression may apply depending on the field.

DEMAND_RESPONSE_EVENT_STATUS

DEMAND_RESPONSE_EVENT_STATUS Documentation
cloud.smarthq.type.demandresponse.eventstatus.active Active event
cloud.smarthq.type.demandresponse.eventstatus.cancelled Cancelled event
cloud.smarthq.type.demandresponse.eventstatus.noevent No active event
cloud.smarthq.type.demandresponse.eventstatus.unknown Unknown event status, set by firmware

DEMAND_RESPONSE_USER_OPTION

DEMAND_RESPONSE_USER_OPTION Documentation
cloud.smarthq.type.demandresponse.useroption.optin user optin
cloud.smarthq.type.demandresponse.useroption.optout user optout

SET<DEMAND_RESPONSE_EVENT_STATUS>

SET<DEMAND_RESPONSE_EVENT_STATUS> Documentation
cloud.smarthq.type.demandresponse.eventstatus.active Active event
cloud.smarthq.type.demandresponse.eventstatus.cancelled Cancelled event
cloud.smarthq.type.demandresponse.eventstatus.noevent No active event
cloud.smarthq.type.demandresponse.eventstatus.unknown Unknown event status, set by firmware

SET<DEMAND_RESPONSE_USER_OPTION>

SET<DEMAND_RESPONSE_USER_OPTION> Documentation
cloud.smarthq.type.demandresponse.useroption.optin user optin
cloud.smarthq.type.demandresponse.useroption.optout user optout