Scheduling asset commands

Schedule commands for your assets. This will overwrite the existing command schedule on all Teleport devices involved in the request. Each Teleport device will instruct its connected assets according to the schedule.

Request

REQUEST
method + URL
PUT https://api.teleport.withthegrid.com/v1/schedule/
body (in TS)
{
deviceHashIds: string[];
}
body details
schedule
Not more than 192 elements.

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.

Models

LimitProductionPower

Limit the power production of an inverter or turbine. The Teleport device will send an extra measurement report immediately after startAt and endAt (unless a report is already scheduled within 3 seconds).

MODEL
{
type: 'limitProductionPower';
percentage: number;
startAt: Date;
endAt: Date;
assetIdentifiers?: string[];
}
details
percentage
Non-negative and <= 100. 0 will turn power production off, 100 will not curtail it at all.

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.

ReduceProductionPower

Reduce the power production of an inverter or turbine with the specified power, compared to the available power given the weather conditions. This can be used when providing automatic Frequency Restoration Reserve (aFRR) services. For PV assets this requires at least one pyranometer or irradiance sensor on site. LimitProductionPower commands for the same asset can be active in parallel: the Teleport will apply the power reduction on the lowest active setpoint.

MODEL
{
type: 'reduceProductionPower';
powerReduction: number;
startAt: Date;
endAt: Date;
controlIdentifiers?: string[];
}
details
powerReduction
In W and nonnegative.

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.

SetBatteryOperation

TIP

Teleport uses the IEC 61850-7-520 Producer Reference Frame (generator sign convention).

Set the operating mode for a battery.

MODEL
{
type: 'setBatteryOperation';
operation: {
dispatchPower: {
activePower: number;
} | null;
deliverFCR: {
maxRate: number;
} | null;
chargeToState: {
percentage: number;
} | null;
};
startAt: Date;
endAt: Date;
assetIdentifiers?: string[];
}
details
operation.dispatchPower.activePower
In W. Positive means discharging, negative charging.

operation.deliverFCR.maxRate
In W and non-negative.

operation.chargeToState.percentage
Non-negative and <= 100.

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.

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
    • assetIdentifiers not present or assetIdentifiers including an element that equals the identifier of the asset
  2. When there are both candidates with matching assetIdentifiers and candidates without assetIdentifiers, those without assetIdentifiers are dropped for that asset
  3. When still multiple candidates exist, the first candidate from the schedule array is used