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.

Recently updated

/v2/schedule is introduced in April 2024. It replaces /v1/schedule, which was idempotent per device instead of per asset. /v1/schedule is still available, see below.

REQUEST

DescriptionExample

method + URL

PUT https://api.teleport.withthegrid.com/v2/schedule/

body (in TS)

{

schedule: (LimitProductionPower | ReduceProductionPower | LimitPower | SetBatteryOperation)[];

assetIdentifiers: string[];

}

body details

schedule

Not more than 192 elements.

assetIdentifiers

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.

Deprecated

/v1/schedule is deprecated. Do not use it for new integrations. We will reach out to existing users of /v1/schedule to discuss the transition to /v2/schedule.

REQUEST

DescriptionExample

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[];

})[];

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.

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.