nest_gen2

Turn a rooted Nest Learning Thermostat (2nd gen) into a small Elixir device: a 320×320 round screen, a rotating ring with a press, a piezo, motion sensors and a climate sensor, all driven from your own OTP application.

Status: alpha (0.1). It runs the example app, foxbus, on a real Nest every day. The public API is described in docs/api.md and the module docs. Expect API changes between 0.x minor versions (see Versioning).

Install

def deps do
  [{:nest_gen2, "~> 0.1.0"}]
end

Before the Hex release, or to track a tag: {:nest_gen2, github: "integration-technology/nest_gen2_sdk", tag: "v0.1.0"}. The device side (rooting, runtime, boot hook) is described in platform/README.md.

Example app: foxbus

foxbus is a complete application built on this SDK, kept as a GitHub repository rather than a Hex package so it can be read, forked and adapted. It shows live bus departures for two stops, a splash screen with the room temperature, disruption warnings, and a countdown with an arrival alarm, using:

• NestGen2.Display and NestGen2.Text for the screens,
• NestGen2.Dial steps and presses to move between them and mute the alarm,
• NestGen2.Power.keep_awake/1 to keep the screen on while the alarm sounds,
• NestGen2.Climate for the temperature, and
• platform/deploy_app.sh to build and install it on the Nest (set NEST_HOST, or put it in ~/.config/nest_gen2/target).

Versioning

Both the SDK and foxbus follow Semantic Versioning.

• While the SDK is 0.x, a minor release (0.1 → 0.2) may change the API; patch releases (0.1.0 → 0.1.1) only fix things. Depend on it with ~> 0.1.0 (which allows 0.1.x but not 0.2), not ~> 0.1 (which in Elixir allows anything below 1.0).
• From 1.0, breaking changes only come with a major release.
• Every release is a git tag (v0.1.0) with an entry in CHANGELOG.md.
• Apps are deployed separately from the SDK. platform/deploy_app.sh refuses to install an app built against a different SDK version from the one on the device.

Layout

Build and test

The Nest runs OTP 26 / Elixir 1.17, so build with that toolchain:

. platform/host_env.sh
mix test

Layers

1. Platform — the device runs our BEAM instead of Nest's software.
2. Native helpers — small static C programs for the device nodes Erlang can't read reliably.
3. SDK — the hex package nest_gen2 (NestGen2.*).
4. Apps — your OTP application, e.g. foxbus.

The SDK provides mechanisms with sensible defaults and apps decide policy. The backplate keep-alive always runs.

Contributing

Issues and pull requests are welcome at github.com/integration-technology/nest_gen2_sdk. For hardware problems, please include the board (Gen 2 "Diamond"), the backplate firmware version (the 0x0001 message after a backplate reset) and what the Nest's own firmware does in the same situation.

Credits

This work stands on the shoulders of the Nest right-to-repair community:

• NoLongerEvil-Thermostat by codykociemba — the installer we use to root the Nest and flash custom firmware. Every device running this SDK starts there. Its own credits, which we pass on:
  • grant-h / ajb142 — omap_loader, the USB bootloader tool used to flash OMAP devices.
  • exploiteers (GTVHacker) — the original research behind the Nest DFU Attack, which showed custom firmware could be flashed to Nest gen 1 and gen 2.
  • FULU and bounty backers — for funding the Nest Learning Thermostat Gen 1/2 bounty and supporting right to repair.
• stb_truetype by Sean Barrett (public domain / MIT), vendored in c_src/vendor, which rasterises text on the device.
• Nest Labs' published GPL kernel sources — reading the board file and drivers is how the display, dial, backlight and sensors were understood.

Licence

GPL-3.0-only; see LICENSE. If you distribute an app built on this SDK, the app must be released under a GPL-compatible licence too.

Nest's Akkurat fonts (/nestlabs/share/fonts) are commercially licensed and are not covered by this licence. This repository never contains them or anything rendered from them; the SDK renders text from the device's own copy at runtime.