> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ariscomfort.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Controlling Zones

> Manage temperature setpoints and operating modes

Zones are the primary way to control comfort in your home. Each zone represents a distinct area with its own temperature sensor and setpoints.

## Understanding Zones

A zone can have:

* One or more **temperature sensors** (thermostats, FCU sensors)
* One or more **terminal devices** (FCUs, radiant emitters)
* Independent **heating and cooling setpoints**
* Its own **operating mode**

## Listing Zones

Get all zones with their current state:

```bash theme={null}
curl http://aris.local/api/zones \
  -H "Authorization: Bearer YOUR_TOKEN"
```

```json theme={null}
{
  "zones": [
    {
      "zoneId": "primary_bedroom",
      "friendlyName": "Primary Bedroom",
      "tempC": 22.4,
      "rhPercent": 45,
      "mode": "auto",
      "tempHeatSetC": 21.0,
      "tempCoolSetC": 24.0,
      "activeCall": "none",
      "supportsHeat": true,
      "supportsCool": true
    }
  ]
}
```

### Zone Properties

| Property       | Description                            |
| -------------- | -------------------------------------- |
| `zoneId`       | Unique identifier (from system config) |
| `friendlyName` | Display name                           |
| `tempC`        | Current temperature in Celsius         |
| `rhPercent`    | Relative humidity percentage           |
| `mode`         | Operating mode (heat/cool/auto/off)    |
| `tempHeatSetC` | Heating setpoint                       |
| `tempCoolSetC` | Cooling setpoint                       |
| `activeCall`   | Current demand (heat/cool/none)        |
| `supportsHeat` | Whether zone can heat                  |
| `supportsCool` | Whether zone can cool                  |

## Setting Temperature

Adjust the heating setpoint:

```bash theme={null}
curl -X POST http://aris.local/api/zones/primary_bedroom/command \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tempHeatSetC": 22.0}'
```

Adjust the cooling setpoint:

```bash theme={null}
curl -X POST http://aris.local/api/zones/primary_bedroom/command \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tempCoolSetC": 25.0}'
```

Set both at once:

```bash theme={null}
curl -X POST http://aris.local/api/zones/primary_bedroom/command \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tempHeatSetC": 21.0,
    "tempCoolSetC": 24.0
  }'
```

### Setpoint Constraints

<Warning>
  **Valid range:** 10-30°C (50-86°F)

  **Minimum gap:** 2.2°C (4°F) between heat and cool setpoints

  If you set setpoints that violate the gap, the system automatically adjusts the other setpoint to maintain the minimum gap.
</Warning>

## Changing Zone Mode

Each zone can operate in one of four modes:

| Mode   | Behavior                                                  |
| ------ | --------------------------------------------------------- |
| `heat` | Only heating is active                                    |
| `cool` | Only cooling is active                                    |
| `auto` | System automatically switches between heating and cooling |
| `off`  | Zone is disabled (no heating or cooling)                  |

Set a zone's mode:

```bash theme={null}
curl -X POST http://aris.local/api/zones/primary_bedroom/command \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "heat"}'
```

### Mode Propagation

Mode behavior depends on your system's thermal energy storage (TES) topology:

| Mode                   | Behavior                                                     |
| ---------------------- | ------------------------------------------------------------ |
| `off`                  | Always zone-specific. Only disables the targeted zone.       |
| `heat`, `cool`, `auto` | May propagate to other zones depending on TES configuration. |

**Why modes propagate:** Zones sharing the same TES tank must operate in the same thermal mode because the tank can only store hot or cold water at a time, not both.

* **Single-TES systems:** The `heat`, `cool`, and `auto` modes are effectively system-wide since all zones share one thermal source. Setting any zone to `heat` means the entire system operates in heating mode.
* **Multi-TES systems:** Zones served by different TES tanks may operate independently. For example, upstairs zones on TES-1 could be in cooling mode while basement zones on TES-2 heat.

<Note>
  The API accepts mode changes on any zone. If the mode would affect other zones due to TES topology, the system applies it consistently across all affected zones.
</Note>

## Combined Commands

Set mode and temperature in one request:

```bash theme={null}
curl -X POST http://aris.local/api/zones/primary_bedroom/command \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "heat",
    "tempHeatSetC": 22.0
  }'
```

## Renaming Zones

Update a zone's friendly name:

```bash theme={null}
curl -X PATCH http://aris.local/api/zones/primary_bedroom/name \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Master Suite"}'
```

Names must be 1-50 characters.

## Viewing History

Get historical temperature data for a zone:

```bash theme={null}
# Last 24 hours (default)
curl "http://aris.local/api/zones/primary_bedroom/history" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Last 7 days
curl "http://aris.local/api/zones/primary_bedroom/history?hours=168" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Specific time range
curl "http://aris.local/api/zones/primary_bedroom/history?start=2024-01-01T00:00:00Z&end=2024-01-02T00:00:00Z" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

```json theme={null}
{
  "zoneId": "primary_bedroom",
  "start": "2024-01-14T10:30:00Z",
  "end": "2024-01-15T10:30:00Z",
  "points": [
    {
      "timestamp": "2024-01-14T10:30:00Z",
      "tempC": 21.5,
      "tempHeatSetC": 21.0,
      "tempCoolSetC": 24.0
    }
  ],
  "count": 288
}
```

## Python Example

A complete example for monitoring and controlling zones:

```python theme={null}
import requests
import time

BRAIN_URL = "http://aris.local"
TOKEN = "your-api-token"

def get_headers():
    return {"Authorization": f"Bearer {TOKEN}"}

def get_zones():
    """Get all zone states"""
    response = requests.get(f"{BRAIN_URL}/api/zones", headers=get_headers())
    return response.json()["zones"]

def set_temperature(zone_id: str, heat: float = None, cool: float = None):
    """Set zone temperature setpoints"""
    payload = {}
    if heat is not None:
        payload["tempHeatSetC"] = heat
    if cool is not None:
        payload["tempCoolSetC"] = cool

    response = requests.post(
        f"{BRAIN_URL}/api/zones/{zone_id}/command",
        headers=get_headers(),
        json=payload
    )
    return response.json()

def set_mode(zone_id: str, mode: str):
    """Set zone mode (heat/cool/auto/off)"""
    response = requests.post(
        f"{BRAIN_URL}/api/zones/{zone_id}/command",
        headers=get_headers(),
        json={"mode": mode}
    )
    return response.json()

# Example: Turn off bedroom at night, warm up in morning
if __name__ == "__main__":
    zones = get_zones()
    for zone in zones:
        print(f"{zone['friendlyName']}: {zone['tempC']}°C (target: {zone['tempHeatSetC']}°C)")

    # Nighttime setback
    set_temperature("primary_bedroom", heat=18.0)
    print("Bedroom set to 18°C for night")

    # Morning warmup (run this at 6am via cron)
    # set_temperature("primary_bedroom", heat=21.0)
```

## Common Patterns

<AccordionGroup>
  <Accordion title="Night setback">
    Lower heating setpoints at night to save energy:

    ```python theme={null}
    for zone in get_zones():
        set_temperature(zone["zoneId"], heat=18.0)
    ```
  </Accordion>

  <Accordion title="Away mode">
    When leaving home, set a wider deadband:

    ```python theme={null}
    for zone in get_zones():
        set_temperature(zone["zoneId"], heat=16.0, cool=28.0)
    ```
  </Accordion>

  <Accordion title="Guest arrival preparation">
    Warm up guest rooms before arrival:

    ```python theme={null}
    set_temperature("guest_room", heat=22.0)
    set_mode("guest_room", "heat")
    ```
  </Accordion>
</AccordionGroup>