> For the complete documentation index, see [llms.txt](https://renewables.docs.helinplatform.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://renewables.docs.helinplatform.com/sgm-product-docs/reference-docs/scheduling-setpoints.md).
# Scheduling setpoints
How setpoints are delivered, how they persist, and how the priority hierarchy resolves overlap.
Two questions decide what value an asset is running right now:
1. **Who sent the setpoint?**, direct API request, schedule, or watchdog. This is the **delivery method**.
2. **How is it being maintained over time?**, written once, periodically rewritten, or actively held at a target. This is the **lifetime model**.
The two are independent. A direct API request can be paired with closed-loop maintenance; a scheduled setpoint can be backed by the cyclic writer. Understanding this split is the cleanest way to reason about why an asset is doing what it's doing right now.
## Delivery methods (who sets the value)
```mermaid
flowchart TD
A[Direct API request highest priority] --> Z[Asset]
B[Scheduled setpoint middle priority] --> Z
C[Watchdog fallback safety net] --> Z
style A fill:#dcfce7,stroke:#22c55e,color:#000
style B fill:#dbeafe,stroke:#3b82f6,color:#000
style C fill:#fee2e2,stroke:#ef4444,color:#000
```
### Direct setpoints
A direct setpoint is sent via the API and applied immediately. Use it for real-time control: responding to spot price signals, reacting to grid events, manual operator overrides.
A direct setpoint stays active until it's replaced by another direct setpoint, until the [watchdog](#watchdog) timeout fires, or until cancelled.
### Scheduled setpoints
A schedule is a per-site, per-category, per-date map of times to values. The platform pushes the schedule down to the gateway, which executes it locally, no live cloud connection required during execution.
This makes schedules the right tool for day-ahead trading and any planned curtailment pattern.
**Schedule rules:**
* Times align to **15-minute increments in UTC** (`00:00`, `00:15`, `00:30`, `00:45`, ...). Anything finer rounds down.
* A `null` value (or a missing slot) means "use the device's `default_value` for that window".
* One schedule covers one calendar date, one category, one site.
* Submit as many days ahead as you like, schedules sit on the gateway until their `valid_on` date.
{% hint style="warning" %}
**Post your schedule at least 5 minutes before the first scheduled interval.** Gateways pull schedule updates on a polling cycle; cutting the lead time tighter risks the first slot starting against the device's `default_value` rather than your scheduled value.
{% endhint %}
```mermaid
gantt
title Setpoint timeline, day-ahead schedule with intraday override
dateFormat HH:mm
axisFormat %H:%M
section Scheduled
Night rate charge limit :done, 00:00, 06:00
Morning ramp up :done, 06:00, 08:00
Peak curtailment window :crit, 08:00, 11:00
Mid-day full production :done, 11:00, 15:00
Afternoon curtailment :crit, 15:00, 18:00
Evening discharge :done, 18:00, 22:00
Night fallback :done, 22:00, 24:00
section Direct override
Operator manual override :active, 10:00, 10:30
```
### Watchdog
The watchdog is the safety net. Each site has a `curtailment_time_limit` (typically 60-90 seconds). If no direct API request arrives within that window, the watchdog activates:
1. If a scheduled value is active for the current time slot, that value is applied.
2. Otherwise, every device reverts to its `default_value`.
This is what protects you against runaway state, a crashed control loop, a missed cron job, a network partition. The site cannot stay in an exotic curtailment state indefinitely; it always falls back to a known-safe value.
Both the timeout duration and per-asset `default_value`s are configured by Helin during commissioning. The watchdog applies at the **site level**, one timeout per site.
{% hint style="warning" %}
There is no API endpoint to query the remaining watchdog time. Monitoring of watchdog activations is available via the platform's remote HMI access.
{% endhint %}
## Lifetime models (how the value persists)
Once a delivery method has supplied a value, one of three lifetime models keeps it active:
### Singular application
The value is written to the device once. No automatic repetition. Stays in effect until replaced.
This is the default for direct API requests. Fast, simple, and predictable, which is what you want when an operator is in the loop.
### Cyclic value application
The platform re-writes the active value to each device on a fixed interval, set per site via `cyclic_write_timeout`. This defends against memory loss after device power cycles and silent command drops.
The cyclic writer **never changes** the active value, only **reinforces** it. See [Cyclic Writer](/sgm-product-docs/concepts/cyclic-writer.md).
### Closed loop control
Instead of writing a value to the asset, the platform holds a **target** at a downstream measurement (typically a grid meter). It reads the meter on every cycle, compares to the target, and adjusts the asset's setpoint up or down to close the gap.
This is the right model when what you care about is the meter reading, not the inverter setpoint, for example, enforcing a CBC cap on grid feed-in regardless of how local consumption fluctuates. See [Closed Loop Control](/sgm-product-docs/concepts/closed-loop-control.md).
## Priority resolution
When multiple delivery methods could apply at the same time, the gateway resolves them in this order:
```mermaid
flowchart TD
A[Setpoint request arrives] --> B{Direct API request active & fresh?}
B -->|Yes| C[Direct setpoint applied]
B -->|No, watchdog fired| D{Schedule slot active?}
D -->|Yes| E[Scheduled value applied]
D -->|No| F[Default value applied]
style C fill:#dcfce7,stroke:#22c55e,color:#000
style E fill:#dbeafe,stroke:#3b82f6,color:#000
style F fill:#fee2e2,stroke:#ef4444,color:#000
```
A direct setpoint sent during a scheduled window takes effect immediately. The schedule resumes the next time the watchdog times out the override, or at the next slot boundary if a fresh direct setpoint isn't sent.
## Day-ahead market workflow
A typical EPEX day-ahead workflow with SGM:
1. Your system receives day-ahead prices for the next day.
2. Your optimisation logic computes the schedule (curtailment windows, charge/discharge periods).
3. Submit the full 24-hour schedule to the API **before midnight, with the 5-minute lead time** in mind.
4. The gateway downloads and acknowledges the schedule.
5. From midnight, the gateway executes each slot autonomously, no live API connection needed.
6. Override any slot with a direct setpoint if intraday conditions change. The watchdog reverts to the schedule when the direct setpoint expires.
## Scheduling for grid operator constraints
Scheduled setpoints are also useful for recurring contractual obligations. If your CBC contract specifies curtailment windows on weekday mornings, pre-load those setpoints at the start of each week. The gateway executes them reliably regardless of what your upstream systems are doing at that moment.
## Relevant pages
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://renewables.docs.helinplatform.com/sgm-product-docs/reference-docs/scheduling-setpoints.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.