Metadata-Version: 2.4
Name: netatmo-thermostat
Version: 0.0.2
Summary: A simple Python SDK for the Netatmo Energy API (thermostats).
Home-page: https://github.com/kafkasl/netatmo-thermostat
Author: Pol Alvarez
Author-email: pol.avms@gmail.com
License: Apache Software License 2.0
Keywords: nbdev jupyter notebook python
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastcore
Requires-Dist: httpx
Requires-Dist: python-fasthtml
Requires-Dist: monsterui
Requires-Dist: python-dotenv
Provides-Extra: dev
Requires-Dist: matplotlib; extra == "dev"
Requires-Dist: nbdev; extra == "dev"
Requires-Dist: jupyter; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# netatmo-energy


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## Setup

1.  Create an app at [dev.netatmo.com](https://dev.netatmo.com) to get
    your API credentials
2.  Either create a `.env` file:

<!-- -->

    CLIENT_ID=your_client_id
    CLIENT_SECRET=your_client_secret
    ACCESS_TOKEN=your_access_token
    REFRESH_TOKEN=your_refresh_token

of pass in the vars to
`Thermostat(client_id, client_secret, access_token, refresh_token)` when
initializing the API client.

## Usage

``` python
t = Thermostat()
hd = t.homesdata()
home_id = hd.homes[0].id
room_id = hd.homes[0].rooms[0].id

# Get current status
t.room_temperatures(home_id)
```

    [{'room_id': '3352988001',
      'temperature': 21.7,
      'setpoint': 21.5,
      'setpoint_mode': 'manual'}]

``` python
# Set room to 20°C for 1 hour
t.setroomthermpoint(home_id, room_id, mode='manual', temp=21, endtime=int(time())+3600)
```

``` python
{'status': 'ok', 'time_server': 1767753063}
```

``` python
t.room_temperatures(home_id)
```

    [{'room_id': '3352988001',
      'temperature': 21.7,
      'setpoint': 21,
      'setpoint_mode': 'manual'}]

``` python
# Get temperature history
r = t.getroommeasure(home_id, room_id)[0]
list(r), r['value'][:3]
```

    (['beg_time', 'step_time', 'value'], [[22.2], [22.2], [22.1]])

## Methods

- `homesdata()` — get homes and topology
- `homestatus(home_id)` — current device status
- `room_temperatures(home_id)` — quick view of all room temps
- `getroommeasure(home_id, room_id, ...)` — temperature history
- `setroomthermpoint(home_id, room_id, mode, ...)` — set room
  temperature
- `setthermmode(home_id, mode)` — set home mode (schedule/away/hg)
- `getmeasure(device_id, ...)` — boiler history
- `createnewhomeschedule(...)` — create weekly schedule
- `synchomeschedule(...)` — modify schedule
- `switchhomeschedule(home_id, schedule_id)` — activate schedule

## Thermostat Widget

The library includes a ready-to-use FastHTML/MonsterUI thermostat widget
for building web dashboards. Use
[`setup_thermostat_widget()`](https://kafkasl.github.io/netatmo-thermostat/core.html#setup_thermostat_widget)
to register the routes and get the widget component:

``` python
app, rt = fast_app()
t = Thermostat()

# Get your home and room IDs
homes = t.homesdata()
home_id = homes.homes[0].id
room_id = homes.homes[0].rooms[0].id

# Setup widget (registers /setpoint route and returns the component)
climate_widget = setup_thermostat_widget(rt, t, home_id, room_id)

@rt("/")
def get():
    return climate_widget
```

![Thermostat Widget](widget-demo.png)

The widget displays current temperature, target setpoint with +/-
controls, and a temperature history chart. Clicking the controls makes
HTMX requests to adjust the thermostat in real-time.

**Note:** the widget uses MonsterUI’s ApexCharts so you will have to
include this in your headers `Theme.blue.headers(apex_charts=True)`

## Dashboard

The `main.py` file includes a fully functional dashboard app with Google
OAuth authentication, ready to be deployed. The solar energy widget is a
placeholder—only the climate/thermostat functionality is connected to
the Netatmo API.

Deployment was done using [pla.sh](https://pla.sh) and is documented in
the `nbs/00_core.ipynb` notebook.

![Dashboard](app-demo.png)

The house thumbnail was generated by copy-pasting a Google Maps
screenshot into [Gemini Nano
Banana](https://x.com/NanoBanana/status/1995828741486903296) with this
prompt:

> Present a clear, 45° top-down isometric miniature 3D cartoon scene of
> \[LOCATION\], featuring its most iconic landmarks and architectural
> elements. Use soft, refined textures with realistic PBR materials and
> gentle, lifelike lighting and shadows. Integrate the current weather
> conditions directly into the city environment to create an immersive
> atmospheric mood. Use a clean, minimalistic composition with a soft,
> solid-colored background.

## Background

Inspired by [Andrej Karpathy’s tweet](https://x.com/karpathy) about
using Claude Code for home automation. Instead of burning tokens on
network scanning, this takes the “boring” approach: read the docs, write
a simple SDK.
