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.

Idempotent schedule per device

Until April 2024 you were required to submit schedules per device instead of per asset. That meant that you had to specify the schedule for all assets of a Teleport when you submitted a schedule.


REQUEST
method + URL
PUT https://api.teleport.withthegrid.com/v1/schedule/
body (in TS)
{
schedule: ({
type: 'limitProductionPower';
percentage: number;
startAt: Date;
endAt: Date;
assetIdentifiers?: string[];
} | {
type: 'reduceProductionPower';
powerReduction: number;
startAt: Date;
endAt: Date;
controlIdentifiers?: string[];
} | {
type: 'limitPower';
feedIn: number | null;
consume: number | null;
startAt: Date;
endAt: Date;
controlIdentifiers?: string[];
} | {
type: 'setBatteryOperation';
operation: {
dispatchPower: {
activePower: number;
} | null;
deliverFCR: {
maxRate: number;
} | null;
chargeToState: {
percentage: number;
} | null;
};
startAt: Date;
endAt: Date;
assetIdentifiers?: string[];
} | {
type: 'setEVOperation';
operation: {
limit: {
power?: number | null;
current?: number | null;
} | null;
};
startAt: Date;
endAt: Date;
assetIdentifiers?: string[];
})[];
deviceHashIds: string[];
}
body details
schedule
Not more than 192 elements.
schedule[](type='limitProductionPower').percentage
Non-negative and <= 100. 0 will turn power production off, 100 will not curtail it at all.
schedule[](type='limitProductionPower').assetIdentifiers?
When specified, the Teleport will only send the command to inverters or turbines whose identifier is in the array. Has no use case for Teleports that are connected to a single inverter or turbine.
schedule[](type='reduceProductionPower').powerReduction
In W and nonnegative.
schedule[](type='reduceProductionPower').controlIdentifiers?
When specified, the Teleport will only send the command to active control loops whose identifier is in the array. Has no use case for Teleports that have a single active control loop.
schedule[](type='limitPower').feedIn
In W and nonnegative
schedule[](type='limitPower').consume
In W and nonnegative
schedule[](type='limitPower').controlIdentifiers?
When specified, the Teleport will only send the command to active control loops whose identifier is in the array. Has no use case for Teleports that have a single active control loop.
schedule[](type='setBatteryOperation').operation.dispatchPower.activePower
In W. Positive means discharging, negative charging.
schedule[](type='setBatteryOperation').operation.deliverFCR.maxRate
In W and non-negative.
schedule[](type='setBatteryOperation').operation.chargeToState.percentage
Non-negative and <= 100.
schedule[](type='setBatteryOperation').assetIdentifiers?
When specified, the Teleport will only send the command to batteries whose identifier is in the array. Has no use case for Teleports that are connected to a single battery.
schedule[](type='setEVOperation').operation.limit.power?
In W. Active power for AC chargers. For non-bidirectional chargers this value should not be positive. Use null or leave the property out to indicate that no limit should be set.
schedule[](type='setEVOperation').operation.limit.current?
In A. For non-bidirectional chargers this value should not be positive. Use null or leave the property out to indicate that no limit should be set. This is the phase current. In wye configurations it is the same as the line current. For delta configurations the phase current has to be multiplied by √3 to get the line current
schedule[](type='setEVOperation').assetIdentifiers?
When specified, the Teleport will only send the command to batteries whose identifier is in the array. Has no use case for Teleports that are connected to a single battery.
deviceHashIds
1 to 100 elements.
RESPONSE
successful responses
201
Command schedule is received by the cloud and will be sent to the specified 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_device_hash_id" }
Device hashId is unknown. Details are provided in the details property of the response.