Netatmo

Cloud integration with Netatmo Connect. One GEM device row represents a single Netatmo account. Each zone under it maps to one weather module, one thermostat room, or one camera. Auth is OAuth2 with a long-lived refresh token that you generate once outside GEM and paste in.

What this driver covers

Product family	Read	Write
Weather station (indoor + outdoor + rain + wind modules)	Temperature, humidity, CO2, noise, pressure, rain, wind speed/angle, gust, battery, RF status	— (read-only telemetry)
Smart Thermostat + Relay + Smart Valves	Measured temp, current setpoint, mode, heating power request, open-window flag	Set temperature (bounded), set whole-home mode (schedule / away / hg / manual / off), quick boost
Welcome / Presence cameras	Power, SD card, last-seen	— (still snapshots are only exposed for prior events, not on demand)

Streaming video, energy-metering plugs, and the Healthy Home Coach are out of scope for the initial driver — call them out as a follow-up.

Prerequisites

1. A Netatmo account with at least one paired product.
2. A Netatmo Connect application created at dev.netatmo.com/apps:
   • Click Create, give it any name (e.g. GEM Controller).
   • Record the Client ID and Client Secret shown on the app detail page.
3. A one-off OAuth2 exchange to mint the refresh_token. The developer portal exposes a built-in Token generator at the bottom of the app page — pick the scopes you need, click Generate Token, and copy the returned refresh_token.

Scopes to request:

Scope	Needed for
read_station	Weather station modules
read_thermostat	Thermostat + valve state
write_thermostat	Set-point and mode commands
read_camera	Camera home_status
access_camera	Get event snapshots

Setup steps

1. Under System → Devices, click Add device and pick Netatmo Connect.
2. Paste the app Client ID into client_id.
3. Paste the app Client Secret into client_secret (masked, stored encrypted).
4. Paste the refresh_token you minted with the Token generator into refresh_token (masked, stored encrypted).
5. Leave api_base on the default (https://api.netatmo.com).
6. Save. The driver will refresh an access token, call get_devices, and populate cachedStations + cachedHomes for the address lookups below.

Then, one zone per resource you want to control or report:

7. Under System → Zones, click Add zone, pick your Netatmo device, and set the address per the format below.

Attribute reference

Device attributes

Name	Required	Description
client_id	yes	Netatmo Connect application client ID. Sent as client_id on the token refresh call and NOT sent on API calls.
client_secret	yes	Netatmo Connect application client secret. Only sent on token refresh. Stored encrypted.
refresh_token	yes	OAuth2 refresh_token minted via the app's Token generator. Stored encrypted. Netatmo may rotate this on a refresh call; the driver persists the new value back to this attribute automatically.
api_base	no	Override for https://api.netatmo.com. Leave on the default unless Netatmo moves you to a regional preview.
status_interval	no	Poll cadence in ms. Default 120 000. Minimum 60 000. Netatmo weather modules only push a new sample every ~10 minutes, so faster polling wastes quota.
request_timeout	no	Per-request HTTP timeout in ms. Default 15 000.

Zone attributes

Zones do not require any attribute besides address. State fields are populated by the poller — for weather modules the driver writes temperature, humidity, co2, noise_db, pressure_mb, rain_mm, wind_kph, wind_angle, gust_kph, battery_percent, rf_status, last_seen, and a coarse state (ok / high_co2 / high_wind). For thermostat rooms the driver writes temperature, setpoint, setpoint_mode, heating_power, open_window, anticipating, and state mirrors setpoint_mode.

Zone address format

The driver uses a prefixed identifier so a single device row can address weather modules, thermostat rooms, and cameras uniformly:

Address	Refers to
weather:<module_id>	A weather station module. module_id is the MAC-style id (e.g. 02:00:00:aa:bb:cc) returned in the _id field of each module by get_devices. The main indoor unit uses the station's own _id.
room:<home_id>:<room_id>	A single thermostat room. Both ids come from homesdata in get_devices.
camera:<camera_id>	A Welcome / Presence camera module.

Run the get_devices command against the device after saving it to enumerate everything the account can see; the returned JSON is where you copy the identifiers from.

Commands

Name	Args	Purpose
get_devices	—	Enumerate all weather stations, homes, thermostat rooms, and cameras the account can see.
get_status	address	Return the latest cached / fetched payload for the addressed zone. Weather → getmeasure for the last window. Room → homestatus for the whole home (rooms + modules).
set_temperature	address, level, endtime_minutes?	Manual override for a thermostat room. level = target Celsius. Without endtime_minutes the override is bounded by the app's default (3 h).
set_mode	address or home_id, mode, endtime_minutes?	Whole-home mode. mode = schedule / away / hg / manual / off. endtime_minutes optional for away/hg.
boost	address, duration?	Convenience: set the room to 22 °C for duration minutes (default 60). Composed from set_temperature.
get_snapshot	address	Stub. Netatmo's public API does not expose a live snapshot — see limitations.
refresh	—	Force a token refresh and re-poll all inventory immediately.

Known limitations

• No live camera snapshot. The public API only serves stills tied to a specific event id + secret key. Once we consume the events feed we can surface the most-recent event's snapshot; the current get_snapshot returns not yet implemented.
• No energy plug support. Netatmo's Smarther / smart plugs use a separate API surface and are not yet wired up.
• Setpoint is bounded. The Netatmo cloud enforces an implicit 3-hour cap on manual overrides unless endtime_minutes is passed. boost uses 60 minutes by default.
• Refresh token rotation. Netatmo rotates the refresh token on some (not all) refresh calls. The driver persists the new value transparently, but if the process dies between receiving the new token and persisting it, the old value is still valid for one more refresh — re-mint from dev.netatmo.com if you see invalid_grant errors.
• Rate limit. 500 requests / hour and 50 requests / 10 s per user. The default 120 s poll keeps one account well under.

Troubleshooting

Symptom	Likely cause / fix
401 unauthorized on the refresh call	client_id / client_secret mismatch, or the refresh_token has been invalidated (usually because you re-generated it at dev.netatmo.com since pasting). Regenerate and update the attribute.
get_devices returns empty stations and homes arrays	The account has nothing paired. Sign in to the mobile app and pair a device first.
set_temperature returns 403 write not allowed	The refresh token was minted without write_thermostat. Re-mint with both read_thermostat and write_thermostat checked.
429 too many requests	Poll cadence is too aggressive. Raise status_interval.
Zone stays on stale temperature	The physical module has fallen offline; check battery_percent and rf_status. Netatmo does not fill in absent samples.

Related

• Sensibo — Wi-Fi retrofit for IR-only ACs; similar cloud-REST integration pattern.
• Ambient Weather Network — alternative weather station integration.
• Ecobee — smart thermostat via OAuth (authorization-code flow, similar shape).