Skip to content
Teleport

Scheduling asset commands

Controlling your energy assets from the cloud is a core feature of the Teleport. To do so, you submit a schedule per asset. A schedule is an array of commands where for each command you have specified its start and end time. Submitting schedules is idempotent per asset: if you submit a new schedule the previous schedule for that asset is overwritten.


REQUEST
method + URL
PUT https://api.teleport.withthegrid.com/v2/schedule/
body (in TS)
{
assetIdentifiers: string[];
} | {
controllerIdentifiers: string[];
}
body details
(type 1)
Use for controlling assets.
(type 1).schedule
Not more than 192 elements.
(type 1).assetIdentifiers
One or more identifiers as listed in GET /v2/device, under devices[].assets[].identifier. 1 to 100 elements.
(type 2)
Use for controlling a control loop that is running on a Teleport.
(type 2).schedule
Not more than 192 elements.
(type 2).controllerIdentifiers
One or more identifiers as listed in GET /v2/device, under devices[].controllers[].identifier. 1 to 100 elements.
RESPONSE
successful responses
201
Command schedule is received by the cloud and will be sent to the relevant Teleport device(s). Devices that are offline will receive the schedule when they come back online.
error responses (next to generic errors)
400 { key: "start_at_too_far_in_future" }
The start of a command (command.startAt) cannot be more than 2147483647 ms (~24 days) in the future.
400 { key: "end_at_too_far_in_the_past" }
The end of a command (command.endAt) cannot be more than 24 hours in the past. All other commands with an endAt in the past are silently ignored.
400 { key: "interval_too_long" }
The difference between command.endAt and command.startAt cannot be more than 2147483647 ms (~24 days).
400 { key: "unknown_identifier" }
One or more identifiers is unknown. Details are provided in the details property of the response.

Active command logic

For each asset and at each time, the Teleport determines which command should be active, using the following principles:

  1. Only consider commands with:
    • the right type for the type of asset
    • startAt in the past or present
    • endAt in the future
  2. When still multiple candidates exist, the first candidate from the schedule array is used.