> 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/concepts/how-sgm-works.md).
# How SGM works
Edge gateway, cloud interface, how a setpoint reaches your asset, and what happens when connections fail.
SGM has two layers that work together: a **Helin Gateway** installed at your site, and a **cloud interface** that connects your systems to it. Understanding how these two layers interact, and what happens when they can't, is the foundation for working with SGM effectively.
## System architecture
```mermaid
flowchart LR
subgraph ASSETS [On-site Assets]
direction TB
PV[Solar PV]
WIND[Wind]
BESS[Battery]
EV[EV Charger]
LOAD[Building Load]
end
subgraph NODE [Helin Node - Edge]
direction TB
DC_E[Data Collector]
EMS_E[EMS Control]
NM[Node Management]
end
subgraph CLOUD [Helin Cloud]
direction TB
API[Control API]
DC_C[Data Collector]
PORTAL[Management Portal]
end
subgraph CLIENT [Client]
direction TB
EMS_C[EMS\nClient Commands]
MON[Monitoring]
PORT[Portfolio MGMT]
end
PV & WIND & BESS & EV & LOAD <-->|Modbus / MQTT| NODE
NODE <-->|Encrypted Data Stream| CLOUD
API -->|Energy Control API| EMS_C
DC_C --> MON
PORTAL --> PORT
style ASSETS fill:#f8fafc,stroke:#94a3b8
style NODE fill:#fff7ed,stroke:#f97316
style CLOUD fill:#eff6ff,stroke:#3b82f6
style CLIENT fill:#f0fdf4,stroke:#22c55e
```
## The two layers
### The Helin Gateway (edge)
The Gateway is a Linux-based edge computer that runs at your site, physically connected to your assets over Ethernet or RS485. This is where the actual control happens. When you send a setpoint via the API, it travels to the Gateway, which translates it into a hardware command and sends it to the right asset.
The Gateway is not a dumb relay. It runs the full SGM control logic locally, including your configured limits, failsafe values, and any scheduled setpoints. This means the site keeps running correctly even when the internet connection goes down.
It also buffers telemetry data locally when connectivity is lost, and syncs it upstream as soon as the connection is restored. No data is dropped during outages.
### The cloud interface
The cloud layer is what your systems talk to. It exposes the SGM API, handles authentication and access management, stores your site configurations, and provides the Helin Platform features (OTA updates, remote HMI access, zero trust networking).
It also handles multi-site management, meaning one API connection gives you control over your entire portfolio, not just a single site.
## How a setpoint gets to your asset
```mermaid
sequenceDiagram
participant YS as Your System
participant API as SGM Cloud API
participant GW as Helin Gateway
participant AS as Asset
YS->>API: POST setpoint (OAuth 2.0)
API->>API: Validate & route to site
API->>GW: Forward setpoint
GW->>GW: Check against configured limits
GW->>AS: Hardware command
AS-->>GW: Telemetry
GW-->>API: Telemetry sync
API-->>YS: Response
```
When you send a setpoint through the API, here is what happens:
1. Your system sends a request to the SGM cloud API (authenticated via OAuth 2.0)
2. The cloud validates the request and routes it to the correct site's Gateway
3. The Gateway receives the setpoint and checks it against the configured limits for that asset
4. If the setpoint is within limits, it is passed to the asset as a hardware command
5. The asset adjusts its output accordingly
6. Telemetry confirming the new state flows back up through the Gateway to the cloud
Scheduled setpoints follow the same path but are stored on the Gateway in advance. When the scheduled time arrives, the Gateway executes them locally, no cloud round-trip required.
## What happens when things go wrong
SGM is designed around the assumption that connections fail. There are four failure scenarios, each with a defined safe outcome:
```mermaid
flowchart TD
F1[Cloud connection lost] --> R1[Gateway uses failsafe setpoint\nor active scheduled setpoint\nData buffered until reconnect]
F2[Local control failure\ne.g. grid meter unavailable] --> R2[Gateway sends safe fallback\nto all affected assets\nAlarm raised for Site Control]
F3[Gateway failure] --> R3[Assets revert to hardcoded\nsafe state set at commissioning]
F4[3rd-party controller failure] --> R3
style F1 fill:#fee2e2,stroke:#ef4444,color:#000
style F2 fill:#fee2e2,stroke:#ef4444,color:#000
style F3 fill:#fee2e2,stroke:#ef4444,color:#000
style F4 fill:#fee2e2,stroke:#ef4444,color:#000
style R1 fill:#dcfce7,stroke:#22c55e,color:#000
style R2 fill:#dcfce7,stroke:#22c55e,color:#000
style R3 fill:#dcfce7,stroke:#22c55e,color:#000
```
**1. Cloud connection or API loss**\
The Gateway falls back to its configured failsafe setpoint, or, if a scheduled setpoint is active for that time window, it uses that instead. Data is buffered locally until connectivity is restored.
**2. Local control failure**\
If a device needed for feedback control (such as a grid meter) becomes unavailable, the Gateway sends a safe fallback setpoint to all affected assets. For Site Control setups, the controller raises an alarm and attempts to stay within limits using the remaining functioning assets. If that isn't possible, it reverts to a predefined state.
**3. Gateway failure**\
If the Gateway itself stops responding, assets fall back to a hardcoded state configured in the hardware during commissioning. This fallback does not depend on any software, it is baked into the asset firmware. Defining these values correctly is part of the Helin commissioning process.
**4. Third-party controller failure**\
Where SGM routes setpoints through a local third-party controller (rather than directly to the asset), the same hardware-level fallback applies. The assets behind that controller revert to their commissioned safe state if commands stop arriving.
{% hint style="info" %}
Failsafe values and timeout durations are configured by Helin during commissioning. Self-service configuration of these settings is planned for a future release.
{% endhint %}
## Why the edge layer matters
The failsafe design means that your site never relies on a continuous cloud connection to stay safe. The Gateway is the last line of defence, and it is engineered to keep the site within its physical and contractual limits regardless of what is happening upstream.
This is especially important for sites with limited grid connections, where a loss of control, even briefly, could result in a grid limit breach. See [Site Control](/sgm-product-docs/reference-docs/site-control.md) for how SGM handles those scenarios.
## 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/concepts/how-sgm-works.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.