Commands

Direct control and automation across your energy infrastructure

Commands in Texture provide a unified interface for controlling devices across different manufacturers and protocols. We abstract away the complexity of varying API signatures, input formats, and device models—giving you a clean, consistent way to take action on your energy infrastructure.

Every command has its own dedicated API endpoint with clearly defined input requirements. Commands are asynchronous by design, enabling reliable execution even when devices are temporarily unavailable or manufacturer APIs are experiencing issues.

Why Commands?

Commands enable you to:

Unified Control — Control devices across different manufacturers with a single interface
Reliable Execution — Asynchronous design ensures commands complete even with temporary failures
Real-Time Response — Get immediate feedback on command status and execution
Automated Workflows — Trigger commands based on events, schedules, or conditions
Grid Services Integration — Leverage advanced grid interaction capabilities through OEM partnerships
Batch Operations — Execute commands across multiple devices simultaneously

Commands transform complex device interactions into simple, reliable API calls that power your energy automation.

Command Structure

All commands follow a consistent pattern for reliable execution:

Request Format

{
  "deviceId": "device_identifier",
  "input": {
    // Command-specific parameters
  }
}

Response Format

{
  "id": "command_identifier",
  "status": "pending|success|failed",
  "deviceId": "device_identifier",
  "command": "command_type",
  "createdAt": "timestamp"
}

Command Lifecycle

Submit Command — Send command via API endpoint
Receive ID — Get command identifier for tracking
Monitor Status — Check execution status via polling or webhooks
Handle Results — Process success/failure and take appropriate action

Available Commands

Texture supports commands across multiple device types, each with specific capabilities:

Device Type	Available Commands	Primary Use Cases
Batteries	Set Reserve, Set Operating Mode	Energy storage optimization, grid services
Thermostats	Set Operating Mode, Set Fan Mode	HVAC control, comfort management
Chargers	Set Operating Mode	EV charging control
Vehicles	Set Operating Mode, Set Charge Limit	EV battery management

Each command includes detailed JSONSchema validation to ensure type-safe requests.

Battery Commands

Set Reserve

Control the minimum charge level that a battery will maintain before acting as a grid passthrough.

Purpose: Ensure homes never lose power during outages by maintaining a minimum reserve.

POST /v1/commands/battery/set-reserve
{
  "deviceId": "clm6r8xuf0003systrvwyfn42",
  "input": {
    "chargePercentage": 30
  }
}

Behavior: The battery will discharge freely until reaching the specified percentage, then act as a passthrough for upstream energy sources (grid, solar, wind, etc.).

Set Operating Mode

Control the fundamental charging state of a battery with four operating modes: charge, discharge, idle, or reset.

Operating Modes:

Mode	Purpose	Grid Interaction
`charge`	Prioritize charging the battery	Optional (configurable)
`discharge`	Prioritize discharging the battery	Optional (configurable)
`idle`	Maintain current charge level	Uses current settings
`reset`	Restore last known settings	Restores previous configuration

Additional Parameters:

minimumBatteryReserve — Used with discharge mode to set backup reserve
maximumBatteryReserve — Used with charge mode to set maximum charge level
enableGridInteraction — Allow import/export from grid (default: false)
executionPriority — Control execution strategy (grid_services vs baseline)

Operating Mode Behavior

The table below outlines the behavior of each operating mode:

Desired Mode	Grid Interaction	Strategy	Reserve Behavior	Notes
`charge`	true	Time of use	Adjusted to `maximumBatteryReserve`	May update time-of-use settings for off-peak charging
`discharge`	true	Time of use	Adjusted to `minimumBatteryReserve`	May update time-of-use settings for peak discharging
`charge`	false	Self Consumption	Adjusted to `maximumBatteryReserve`	May still import from grid if solar insufficient
`discharge`	false	Self Consumption	Adjusted to `minimumBatteryReserve`	Uses solar first, excess may charge battery
`idle`	N/A	Current strategy	Maintains current charge level	Strategy depends on `enableGridInteraction` setting
`reset`	N/A	N/A	N/A	Restores last known settings (within 24 hours)

note

Grid Services Override

If the device is enrolled in a grid services program, the battery will be controlled by the program rather than these operating mode settings.

Examples

Discharge with grid export:

POST /v1/commands/battery/set-operating-mode
{
  "deviceId": "clm6r8xuf0003systrvwyfn42",
  "input": {
    "operatingMode": "discharge",
    "enableGridInteraction": true
  }
}

Charge from solar primarily:

POST /v1/commands/battery/set-operating-mode
{
  "deviceId": "clm6r8xuf0003systrvwyfn42",
  "input": {
    "operatingMode": "charge"
  }
}

Reset to previous settings:

POST /v1/commands/battery/set-operating-mode
{
  "deviceId": "clm6r8xuf0003systrvwyfn42",
  "input": {
    "operatingMode": "reset"
  }
}

Thermostat Commands

Set Operating Mode

Control HVAC operating modes including cool, heat, off, and more.

POST /v1/commands/thermostat/set-operating-mode
{
  "deviceId": "cllcsqn45000008mn3u76afas",
  "input": {
    "operatingMode": "cool",
    "coolTarget": 72
  }
}

Behavior: The thermostat will maintain the specified temperature by cycling the HVAC system on and off as needed.

Set Fan Mode

Control fan operation with modes: auto, on, off, and circulate.

POST /v1/commands/thermostat/set-fan-mode
{
  "deviceId": "cllcsqn45000008mn3u76afas",
  "input": {
    "fanMode": "auto"
  }
}

Behavior: auto mode runs the fan only when heating or cooling is active.

Pause Schedule

Pause the on-device thermostat schedule to allow Texture platform schedules to control the device without conflicts.

POST /v1/commands/thermostat/pause-schedule
{
  "deviceId": "cllcsqn45000008mn3u76afas",
  "input": {}
}

Behavior: This command pauses the thermostat's internal schedule (programmed directly on the device), not Texture platform schedules. Use this as a coordination lever when you want Texture schedules to take precedence over the device's native schedule. The device will remain controllable via other commands and schedules.

Note: This affects the on-device schedule only. Texture platform schedules continue to operate normally.

Resume Schedule

Resume the on-device thermostat schedule after it has been paused.

POST /v1/commands/thermostat/resume-schedule
{
  "deviceId": "cllcsqn45000008mn3u76afas",
  "input": {}
}

Behavior: This command reactivates the thermostat's internal schedule (programmed directly on the device). Use this to return control to the device's native schedule when Texture platform schedules no longer need priority. The device will follow its programmed on-device schedule after this command.

Note: This affects the on-device schedule only. Texture platform schedules continue to operate normally.

Charger Commands

Set Operating Mode

Control EV charging with start-charging or stop-charging modes.

POST /v1/commands/charger/set-operating-mode
{
  "deviceId": "cllcsqn45000008mn3u76afas",
  "input": {
    "operatingMode": "start-charging"
  }
}

Vehicle Commands

Set Operating Mode

Control vehicle charging with start-charging or stop-charging modes.

POST /v1/commands/vehicle/set-operating-mode
{
  "deviceId": "cllcsqn45000008mn3u76afas",
  "input": {
    "operatingMode": "start-charging"
  }
}

Home Location Guard

Vehicle commands support an optional home location guard to prevent charging control when the vehicle is away from its designated home location. This is useful for preventing unintended charging starts/stops when vehicles are on the road or at public charging stations.

Parameters:

requireHomeLocation (boolean, optional) — When true, the command will only execute if the vehicle is within the specified radius of its home location
homeRadiusMeters (number, optional) — The allowed radius from home in meters (default: 250)

Example:

POST /v1/commands/vehicle/set-operating-mode
{
  "deviceId": "cllcsqn45000008mn3u76afas",
  "input": {
    "operatingMode": "start-charging",
    "requireHomeLocation": true,
    "homeRadiusMeters": 500
  }
}

Behavior:

If requireHomeLocation is true, the command checks the vehicle's latest location against its home site location
If the vehicle is outside the specified radius, the command fails with a clear error message
If vehicle or home location data is unavailable, the command fails closed for safety
Location checks use great-circle distance (haversine formula) for accuracy

Failure Scenarios:

Vehicle not at home for home-only command. — Vehicle is outside the allowed radius
Vehicle location unavailable for home-only command. — Latest vehicle location data is missing
Home location unavailable for home-only command. — Home site location is not configured

tip

When to Use Home Location Guards

Use requireHomeLocation: true when:

You want to prevent charging control during road trips
You're automating charging based on home energy prices
You want to avoid conflicts with public charging station controls
Safety and control locality are priorities over convenience

Set Charge Limit

Set the maximum charge percentage for vehicle batteries (0-100%).

POST /v1/commands/vehicle/set-charge-limit
{
  "deviceId": "cllcsqn45000008mn3u76afas",
  "input": {
    "chargeLimit": "80"
  }
}

With Home Location Guard:

POST /v1/commands/vehicle/set-charge-limit
{
  "deviceId": "cllcsqn45000008mn3u76afas",
  "input": {
    "chargeLimit": "80",
    "requireHomeLocation": true,
    "homeRadiusMeters": 250
  }
}

The requireHomeLocation and homeRadiusMeters parameters work identically to the Set Operating Mode command. See the Home Location Guard section above for full details.

Command Status and Monitoring

Asynchronous Execution

Commands are asynchronous by design to handle real-world scenarios:

Immediate Response — Get command ID instantly upon submission
Status Tracking — Monitor execution via polling or webhooks
Failure Handling — Commands may fail due to manufacturer API issues or disconnected credentials
Retry Logic — Built-in retry mechanisms for temporary failures

Monitoring Options

Polling — Use GET /commands/{id} to check status
Device History — Use GET /devices/{deviceId}/commands to view all commands
Webhooks — Configure destinations to receive command completion events

Error Handling

Common failure scenarios include:

Manufacturer API downtime
Disconnected device credentials
Invalid command parameters
Device offline or unavailable

tip

Command Reliability

Most commands execute immediately and successfully. For critical operations, implement webhook monitoring to handle edge cases where commands may fail or be delayed.

Best Practices

Validate Inputs — Use the JSONSchema from availableCommands for type-safe requests
Monitor Status — Implement webhook monitoring for critical commands
Handle Failures — Design your application to handle command failures gracefully
Batch Operations — Use batch commands for operations across multiple devices
Test Commands — Validate command behavior in your development environment
Check Device Status — Verify device connectivity before sending commands

Next Steps

Explore the full Commands API reference
Test commands with your devices
Implement webhook monitoring for reliable execution
Build automated workflows using commands and events

Commands provide the direct control layer for your energy infrastructure—enabling automation, optimization, and reliable device management across the Texture Platform.

For advanced command capabilities, see:

Batch Commands — Execute commands across multiple devices simultaneously
Grid Services — Advanced grid interaction capabilities through OEM partnerships

Why Commands?​

Command Structure​

Request Format​

Response Format​

Command Lifecycle​

Available Commands​

Battery Commands​

Set Reserve​

Set Operating Mode​

Operating Mode Behavior​

Examples​

Thermostat Commands​

Set Operating Mode​

Set Fan Mode​

Pause Schedule​

Resume Schedule​

Charger Commands​

Set Operating Mode​

Vehicle Commands​

Set Operating Mode​

Home Location Guard​

Set Charge Limit​

Command Status and Monitoring​

Asynchronous Execution​

Monitoring Options​

Error Handling​

Best Practices​

Next Steps​

Related Topics​

Why Commands?

Command Structure

Request Format

Response Format

Command Lifecycle

Available Commands

Battery Commands

Set Reserve

Set Operating Mode

Operating Mode Behavior

Examples

Thermostat Commands

Set Operating Mode

Set Fan Mode

Pause Schedule

Resume Schedule

Charger Commands

Set Operating Mode

Vehicle Commands

Set Operating Mode

Home Location Guard

Set Charge Limit

Command Status and Monitoring

Asynchronous Execution

Monitoring Options

Error Handling

Best Practices

Next Steps

Related Topics