FlexHome Docs

Appearance

Node Control — Apply a Power Schedule ​

The NodeControlPowerScheduleModifyRequest applies a power schedule to one or more nodes. There are two ways to specify which schedule to apply:

  • By id — reference an existing power schedule via its scheduleId. Use this when the schedule has already been created with PowerScheduleCreateRequest and you only want to (re-)apply it.
  • Ad-hoc — provide an adHocDefinition consisting of a scheduleSetId and a full PowerScheduleDefinition. The platform creates a new power schedule in the specified schedule set and immediately applies it to the listed nodes — all in a single call. The id of the newly created schedule is returned in the response.

Both forms share the same filter for selecting the target nodes and produce the same response shape.

Preparations ​

Pick exactly one

The adHocDefinition and scheduleId fields are part of a oneof — provide exactly one of them in any given request. Sending both, or neither, is invalid.

Variant A — Ad-hoc Definition (create and apply in one call) ​

Use this variant when you want to define a schedule "on the fly" and apply it immediately, without first creating it via PowerScheduleCreateRequest. The platform stores the schedule in the schedule set you specify and applies it to the target nodes.

  1. Run the request on app/v1/NodeControlPowerScheduleModifyRequest.
  2. Populate filter.ids with the identifiers of the target nodes. All identifiers must be of the same type.
  3. Provide adHocDefinition:
    • scheduleSetId — the schedule set the new schedule will belong to.
    • definition.priority — within the priorityMinimum/priorityMaximum range of the target schedule set.
    • definition.controlState — must be in the constraints.controlStates of the target schedule set (typically POWER = 3).
    • definition.elements — one or more time ranges with a desired power setpoint (or desired energy).

Request body

json
{
  "header": {
    "reqId": 1234,
    "timeoutMs": 10000
  },
  "filter": {
    "ids": [
      { "type": { "id": 2 }, "stringValue": "356C2F687081150182505CCCC11BC5C461B60B53" },
      { "type": { "id": 2 }, "stringValue": "54F2664E28EDF2593B9CAAAF041687BEDB0A15C8" },
      { "type": { "id": 2 }, "stringValue": "50F6ED70B16F6846D296AD29F0530B4A3008F529" },
      { "type": { "id": 2 }, "stringValue": "6D60D12A3688E7D2CA3F2C0BD8D5BA01459E9E10" },
      { "type": { "id": 2 }, "stringValue": "870673858C4F56FB3C26550C6CA4CFDA43F45606" }
    ]
  },
  "adHocDefinition": {
    "scheduleSetId": 10,
    "definition": {
      "priority": 35,
      "controlState": 3,
      "elements": [
        {
          "startTime": 1779541075,
          "endTime": 1779541675,
          "desiredPowerSetpoint": {
            "number": -250
          }
        }
      ]
    }
  }
}

In this example, the five listed nodes are instructed to discharge with 250 W between epoch seconds 1779541075 and 1779541675 (desiredPowerSetpoint.number is negative — see the sign convention on the Power Schedules page).

adHocDefinition fields ​

FieldDescription
scheduleSetIdIdentifier of the schedule set the new power schedule will be created in. Constraints of this set (priority range and allowed control states) are enforced.
definition.priorityPriority of the schedule. Must be within the schedule set's priorityMinimum/priorityMaximum. The schedule with the highest priority whose element covers the current time is the one applied.
definition.controlStateControl state represented by the schedule. Must be in the schedule set's allowed controlStates. See the controlState table on the Power Schedules page.
definition.elementsOne or more schedule elements (startTime, endTime, and either desiredPowerSetpoint or desiredEnergy). See Schedule elements.

Variant B — Existing Schedule by Id ​

Use this variant when the power schedule already exists (created earlier with PowerScheduleCreateRequest or by a previous ad-hoc call) and you want to apply it — or re-apply it — to one or more nodes.

  1. Run the request on app/v1/NodeControlPowerScheduleModifyRequest.
  2. Populate filter.ids with the identifiers of the target nodes. All identifiers must be of the same type.
  3. Set scheduleId to the id of the existing power schedule.

Request body

json
{
  "header": {
    "reqId": 1234,
    "timeoutMs": 10000
  },
  "filter": {
    "ids": [
      { "type": { "id": 2 }, "stringValue": "356C2F687081150182505CCCC11BC5C461B60B53" },
      { "type": { "id": 2 }, "stringValue": "54F2664E28EDF2593B9CAAAF041687BEDB0A15C8" },
      { "type": { "id": 2 }, "stringValue": "50F6ED70B16F6846D296AD29F0530B4A3008F529" },
      { "type": { "id": 2 }, "stringValue": "6D60D12A3688E7D2CA3F2C0BD8D5BA01459E9E10" },
      { "type": { "id": 2 }, "stringValue": "870673858C4F56FB3C26550C6CA4CFDA43F45606" }
    ]
  },
  "scheduleId": 20
}

Request fields (both variants) ​

FieldDescription
header.reqIdClient-defined identifier for the request. The same value is returned in the response header.
header.timeoutMsMaximum time (in milliseconds) the platform waits for the result before responding with a timeout error.
filter.idsList of node identifiers to apply the schedule to. All identifiers must be of the same type. The same identifier type is used in the response.
adHocDefinitionVariant A only. Ad-hoc schedule that is created and applied in one call. See adHocDefinition fields.
scheduleIdVariant B only. Identifier of an existing power schedule to apply.

Response ​

The response is the same regardless of which variant was used. It splits the requested nodes into those that the schedule was applied to and those for which it could not be applied, and returns the scheduleId that is now in effect.

Response body

json
{
  "header": {
    "reqId": 1234
  },
  "appliedIds": [
    { "type": { "id": 2 }, "stringValue": "356C2F687081150182505CCCC11BC5C461B60B53" },
    { "type": { "id": 2 }, "stringValue": "54F2664E28EDF2593B9CAAAF041687BEDB0A15C8" },
    { "type": { "id": 2 }, "stringValue": "50F6ED70B16F6846D296AD29F0530B4A3008F529" }
  ],
  "unappliedIds": [
    { "type": { "id": 2 }, "stringValue": "6D60D12A3688E7D2CA3F2C0BD8D5BA01459E9E10" },
    { "type": { "id": 2 }, "stringValue": "870673858C4F56FB3C26550C6CA4CFDA43F45606" }
  ],
  "scheduleId": 582
}

Response fields ​

FieldDescription
appliedIdsIdentifiers of the nodes that the schedule was applied to. Only nodes that are connected and in a normal operation state are included here.
unappliedIdsIdentifiers of the nodes that the schedule could not be applied to — typically because the node is disconnected or in a failed operation state. Retry these nodes later, or remove them from your target set after consulting NodeStateListRequest.
scheduleIdIdentifier of the schedule that is now applied. For Variant A this is the id of the newly created schedule — capture it if you want to re-apply or list it later. For Variant B this echoes back the scheduleId from the request.

Verify the result

After applying a schedule, send a NodeStateListRequest with detailTypes including POWER_STATE (5) and inspect powerState.state.scheduleId for each node — it should match the scheduleId returned here.

Command latency

Commands may take a short time to be executed after the request has been processed. The successful application is visible in the powerState of NodeStateListRequest.

When to use which variant? ​

Use Variant A (ad-hoc) when…Use Variant B (schedule id) when…
You want a single round trip to create and apply a schedule.The schedule already exists (created via PowerScheduleCreateRequest or returned from a previous ad-hoc call).
The schedule is short-lived or one-off and you do not need to manage it independently before the call.You want to re-apply the same schedule to additional nodes without creating a duplicate.
You still need the schedule to be persistent and discoverable afterwards — the platform persists ad-hoc schedules and PowerScheduleListRequest returns them.You want to keep request payloads small (no embedded definition).