Device Control Models

Pylontech OpenAPI provides three ways to change device behavior: Configuration, Schedule, and Command. They differ primarily in how long a change remains effective and how time is represented.

Comparison

Model	Effective period	Time basis	Typical use
Configuration	Persists until changed	No time window	Operating mode, SOC limits, site import or export limits
Schedule	Repeats on selected days	Device local time	Daily or weekly charge and discharge plan
Command	Temporary absolute time window	UTC	Temporary charge, discharge, or power restriction

Configuration

Use Configuration for the device's persistent baseline.

A configuration read returns the complete configuration currently exposed by the API. A configuration update is partial: send only the properties that need to change. Values not included in the request retain their existing settings.

Configuration is suitable when the setting should remain active until another configuration request changes it.

Open configuration operations

Schedule

Use Schedule when the same charge or discharge behavior should recur at known local times.

Each period defines:

• a local startTime and endTime;
• charge or discharge;
• target battery power; and
• optional weekdays, where Monday is 1 and Sunday is 7.

Unlike Command timestamps, schedule times do not contain a date or UTC offset. They follow the local time of the device's site.

Open schedule operations

Command

Use Command for a temporary control action with an explicit start and end timestamp.

Command values override the corresponding device defaults during the command's effective time window. Properties omitted from powerControl keep their existing values.

Commands are processed asynchronously and have their own execution lifecycle. They can be queried and, while pending or executing, cancelled.

Read the Device Commands guide

Choosing a Model

Requirement	Use
Keep a setting active until it is changed again	Configuration
Repeat a charge or discharge period every day or on selected weekdays	Schedule
Apply a one-time control action between two UTC timestamps	Command
Apply the same persistent setting to multiple devices	Batch Configuration
Apply the same recurring plan to multiple devices	Batch Schedule
Dispatch the same temporary action to multiple devices	Batch Command

Control precedence

When two or more control models set the same parameter, the following precedence applies:

Command > Schedule > Configuration

• An active Command overrides conflicting Schedule and Configuration values.
• An active Schedule overrides conflicting Configuration values when no Command is controlling the same parameter.
• Configuration provides the persistent baseline when neither a Command nor an active Schedule overrides the parameter.

When a Command ends or is cancelled, the active Schedule takes effect again. If no Schedule is active, the device returns to its Configuration value. When a Schedule period ends, the corresponding Configuration value takes effect again.