Controlling Zones

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:

curl http://aris.local/api/zones \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "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:

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:

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:

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

Valid range: 10-30°C (50-86°F)Minimum gap: 2.2°C (4°F) between heat and cool setpointsIf you set setpoints that violate the gap, the system automatically adjusts the other setpoint to maintain the minimum gap.

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:

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.

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.

Combined Commands

Set mode and temperature in one request:

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:

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:

# 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"

{
  "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:

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

Night setback

Lower heating setpoints at night to save energy:

for zone in get_zones():
    set_temperature(zone["zoneId"], heat=18.0)

Away mode

When leaving home, set a wider deadband:

for zone in get_zones():
    set_temperature(zone["zoneId"], heat=16.0, cool=28.0)

Guest arrival preparation

Warm up guest rooms before arrival:

set_temperature("guest_room", heat=22.0)
set_mode("guest_room", "heat")

Get Started

Guides

Controlling Zones

Understanding Zones

Listing Zones

Zone Properties

Setting Temperature

Setpoint Constraints

Changing Zone Mode

Mode Propagation

Combined Commands

Renaming Zones

Viewing History

Python Example

Common Patterns

​Understanding Zones

​Listing Zones

​Zone Properties

​Setting Temperature

​Setpoint Constraints

​Changing Zone Mode

​Mode Propagation

​Combined Commands

​Renaming Zones

​Viewing History

​Python Example

​Common Patterns

Understanding Zones

Listing Zones

Zone Properties

Setting Temperature

Setpoint Constraints

Changing Zone Mode

Mode Propagation

Combined Commands

Renaming Zones

Viewing History

Python Example

Common Patterns