Skip to main content

Asset Control Using Instructions

Understanding the Instructions System​

The Covolt API uses an "instructions" system to control battery and solar assets. Instructions are time-bounded commands that tell an asset what to do during a specific period.

Instruction Types​

The API supports two types of instructions:

Battery Instructions​

Battery instructions allow you to command charging or discharging behavior by specifying a target power level.

Solar Instructions​

Solar instructions allow you to control the power state (ON/OFF) of solar inverters or loggers.

Creating Instructions​

Instructions can be created for a single asset or multiple assets simultaneously.

Battery Instruction Example​

POST /v2/battery-assets/instructions/

Request body:

{
  "start_at": "2025-05-01T14:00:00Z",
  "stop_at": "2025-05-01T16:00:00Z",
  "target_command_power": 5,
  "battery_assets": ["BAT-001", "BAT-002"]
}

In this example:

  • start_at and stop_at define the time window for the instruction
  • target_command_power is set to 5 kW (positive values = discharge, negative values = charge)
  • The instruction applies to two battery assets simultaneously

Solar Instruction Example​

POST /v2/solar-assets/instructions/

Request body:

{
  "start_at": "2025-05-01T12:00:00Z",
  "stop_at": "2025-05-01T14:00:00Z",
  "target_power_state": "OFF",
  "solar_assets": ["SOL-001"]
}

Instruction Lifecycle​

  1. Creation: When you submit an instruction, it is validated and assigned a UUID
  2. Pending: Instructions with future start_at times wait until their start time
  3. Active: When the start_at time is reached, the instruction becomes active
  4. Completed: When the stop_at time is reached, the instruction is completed

Querying Instructions​

You can retrieve both active and historical instructions:

List Battery Instructions​

GET /v2/battery-assets/instructions/?asset_id=BAT-001

Get Specific Instruction​

GET /v2/battery-assets/instructions/{uuid}/

Best Practices for Instructions​

Timing Considerations​

  • Instructions should have a minimum duration of 1 minute
  • Avoid creating very short instructions as they may not execute properly
  • Use ISO 8601 format for timestamps and ensure they're in UTC

Power Management​

  • For battery assets, positive power values (e.g., 5 kW) command discharge
  • Negative power values (e.g., -5 kW) command charging
  • Consider the asset's capabilities when setting power values

Overlapping Instructions​

  • If multiple instructions overlap for the same asset, the instruction with the latest creation time takes precedence
  • To cancel an active instruction, create a new instruction with the desired behavior

Instruction Duration​

  • For battery assets, consider state of charge limitations
  • For repetitive patterns, create multiple sequential instructions
  • Instructions with very long durations may be subject to unexpected external factors

Grid Constraints Impact​

Be aware that battery instructions are subject to the grid constraints configured for the asset. If an instruction would violate these constraints, the actual power may be limited to stay within the allowed range.