nest

README

Nest

A Go library for Nest devices. This library provides basic support for Nest Cameras (work-in-progress), Thermostats, and SmokeCoAlarms. There is support for integrating golang OAuth2.0 support into the HTTP client and is expected when constructing a new client.

Author

Jon Tsiros

Want to support me?

Installation

go get github.com/jtsiros/nest

Usage

Devices

Existing Token

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/jtsiros/nest"
	"github.com/jtsiros/nest/auth"
	"github.com/jtsiros/nest/config"
)

func main() {
	// Interactive OAuth2 configuration
	appConfig := config.Config{
		APIURL: config.APIURL,
	}

	conf := auth.NewConfig(appConfig)
	tok, err := auth.NewConfigWithToken("[TOKEN]").Token()
	if err != nil {
		log.Fatal(err)
	}
	client := conf.Client(context.Background(), tok)

	n, err := nest.NewClient(appConfig, client)
	fmt.Println(n.Devices())
}

No existing Token

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/jtsiros/nest"
	"github.com/jtsiros/nest/auth"
	"github.com/jtsiros/nest/config"
	"golang.org/x/oauth2"
)

func main() {
	// Interactive OAuth2 configuration
	appConfig := config.Config{
		ClientID: "[CLIENT_ID]",
		Secret:   "[SECRET]",
		APIURL:   config.APIURL,
	}

	conf := auth.NewConfig(appConfig)
	url := conf.AuthCodeURL("STATE")

	fmt.Printf("Enter code from this authorization URL: %v\n", url)

	var code string
	if _, err := fmt.Scan(&code); err != nil {
		log.Fatal(err)
	}

	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()
	token, err := conf.Exchange(ctx, code,
		oauth2.SetAuthURLParam("client_id", appConfig.ClientID),
		oauth2.SetAuthURLParam("client_secret", appConfig.Secret),
	)
	if err != nil {
		log.Fatal(err)
	}

	client := conf.Client(ctx, token)
	n, err := nest.NewClient(appConfig, client)

	fmt.Println(n.Devices())
}

Thermostats

thermostat, err := n.Thermostats.Get("[DEVICE_ID]")
// ... error handling
fmt.Println(thermostat.TargetTemperatureF)

n.Thermostats.SetHVACMode(thermostat.DeviceID, nest.Heat)

SmokeCoAlarms

smokeCoAlarm, err := n.SmokeCoAlarms.Get("[DEVICE_ID]")
// ... error handling
fmt.Println(smokeCoAlarm.LastConnection)

Cameras

At this time, only read-only portion of the API is implemented. I'm planning on implementing the write calls once I integrate with my HomeKit integration.

camera, err := n.Cameras.Get("[DEVICE_ID]")
// ... error handling
fmt.Println(camera.IsStreaming)

Credits

Go Gopher Coding it up by: Kari Linder

Documentation

Index

• Constants
• type CameraService
  • func NewCameraService(client *Client) *CameraService
  • func (svc *CameraService) Get(deviceid string) (*device.Camera, error)
  • func (svc *CameraService) Stream(deviceID string) (*Stream, error)
• type Client
  • func NewClient(config config.Config, client *http.Client) (*Client, error)
  • func (nest *Client) Devices() (*device.Devices, error)
• type Error
  • func (e Error) Error() string
• type Event
  • func (e Event) GetEvent() (EventsType, string, interface{}, error)
  • func (e Event) String() string
• type EventsType
• type SmokeCoAlarmService
  • func NewSmokeCoAlarmService(client *Client) *SmokeCoAlarmService
  • func (svc *SmokeCoAlarmService) Get(deviceid string) (*device.SmokeAlarm, error)
  • func (svc *SmokeCoAlarmService) Stream(deviceID string) (*Stream, error)
• type Stream
  • func NewStream(cfg *config.Config, client *http.Client) (*Stream, error)
  • func (s Stream) Open() (chan Event, error)
• type ThermostatService
  • func NewThermostatService(client *Client) *ThermostatService
  • func (svc *ThermostatService) Get(deviceid string) (*device.Thermostat, error)
  • func (svc *ThermostatService) GetFanTimerActive(deviceid string) error
  • func (svc *ThermostatService) SetFanTimerDuration(deviceid string, duration int) error
  • func (svc *ThermostatService) SetHVACMode(deviceid string, state hvacMode) error
  • func (svc *ThermostatService) SetLabel(deviceid string, label string) error
  • func (svc *ThermostatService) SetTargetTemperature(deviceid string, scale tempScale, target int) error
  • func (svc *ThermostatService) SetTargetTemperatureRange(deviceid string, scale tempScale, low, high int) error
  • func (svc *ThermostatService) SetTemperatureScale(deviceid string, scale tempScale) error
  • func (svc *ThermostatService) Stream(deviceID string) (*Stream, error)

Constants

const (
	// Heat mode
	Heat hvacMode = "heat"
	// Cool mode
	Cool hvacMode = "cool"
	// HeatCool mode
	HeatCool hvacMode = "heat-cool"
	// Eco mode
	Eco hvacMode = "eco"
	// Off mode
	Off hvacMode = "off"
)

const (
	// F represents Farenheight
	F tempScale = "F"
	// C represents celcius
	C tempScale = "C"
)

Types

type CameraService

type CameraService service

CameraService provides read and control for Camera devices. Most of the device calls are read-only, thus a majority of the time, a call to Get() will fetch all of the appropriate attributes although convenience methods for writing certain values are provided.

func NewCameraService

func NewCameraService(client *Client) *CameraService

NewCameraService creates a new service.

func (*CameraService) Get

func (svc *CameraService) Get(deviceid string) (*device.Camera, error)

Get fetches an updated camera object given a device id. https://developers.nest.com/reference/api-camera

func (*CameraService) Stream

func (svc *CameraService) Stream(deviceID string) (*Stream, error)

Stream opens an event stream to monitor changes on the Camera https://developers.nest.com/guides/api/rest-streaming-guide

type Client

type Client struct {
	Thermostats   *ThermostatService
	SmokeCoAlarms *SmokeCoAlarmService
	Cameras       *CameraService
	// contains filtered or unexported fields
}

Client provides API functionality to Nest APIs

func NewClient

func NewClient(config config.Config, client *http.Client) (*Client, error)

NewClient creates a new Nest API. Since the Nest API uses an authorization_code, there isn't an elegant way to prompt the API user to enter in an authorization code. This API assumes that the configured HTTP client is configured to handle OAuth2.

func (*Client) Devices

func (nest *Client) Devices() (*device.Devices, error)

Devices represent physical devices (Thermostats, Protects, and Cameras) within a structure https://developers.nest.com/documentation/cloud/architecture-overview

type Error

type Error struct {
	Err      string `json:"error"`
	Type     string `json:"type"`
	Message  string `json:"message"`
	Instance string `json:"instance"`
}

Error represents an error from API call

func (Error) Error

func (e Error) Error() string

type Event

type Event struct {
	// contains filtered or unexported fields
}

Event represents a response when changes occur in structure or device data.

func (Event) GetEvent

func (e Event) GetEvent() (EventsType, string, interface{}, error)

GetEvent returns the device data along with the type for type casting Returns the device type, device id, data, error

func (Event) String

func (e Event) String() string

type EventsType

type EventsType string

EventsType describes the supported event types (usually based on device)

const (
	Thermostats   EventsType = "thermostats"
	SmokeCoAlarms EventsType = "smoke_co_alarms"
	Cameras       EventsType = "cameras"
	KeepAlive     EventsType = "keep-alive"
	EventError    EventsType = "error"
)

all the event types

type SmokeCoAlarmService

type SmokeCoAlarmService service

SmokeCoAlarmService interacts with Smoke+CO Alarm devices to read device data.

func NewSmokeCoAlarmService

func NewSmokeCoAlarmService(client *Client) *SmokeCoAlarmService

NewSmokeCoAlarmService creates a new service to interact with Smoke+CO alarms.

func (*SmokeCoAlarmService) Get

func (svc *SmokeCoAlarmService) Get(deviceid string) (*device.SmokeAlarm, error)

Get fetches an updated smokecoalarm object given a device id. https://developers.nest.com/reference/api-smoke-co-alarm

func (*SmokeCoAlarmService) Stream

func (svc *SmokeCoAlarmService) Stream(deviceID string) (*Stream, error)

Stream opens an event stream to monitor changes on the smokecoalarm. https://developers.nest.com/guides/api/rest-streaming-guide https://developers.nest.com/reference/api-smoke-co-alarm

type Stream

type Stream struct {
	// contains filtered or unexported fields
}

Stream represents an open connection to the Nest APIs for device and structure changes. This will maintain an open socket for every stream connected to a device.

func NewStream

func NewStream(cfg *config.Config, client *http.Client) (*Stream, error)

NewStream returns a new stream given a configuration and http client objects.

func (Stream) Open

func (s Stream) Open() (chan Event, error)

Open opens a connection and streams events from the Nest API.

type ThermostatService

type ThermostatService service

ThermostatService interacts with Thermostat devices to control and read device data.

func NewThermostatService

func NewThermostatService(client *Client) *ThermostatService

NewThermostatService creates a new service to interact with Thermostats.

func (*ThermostatService) Get

func (svc *ThermostatService) Get(deviceid string) (*device.Thermostat, error)

Get fetches an updated thermostat object given a deviceID. https://developers.nest.com/guides/api/thermostat-guide See Thermostat Identifiers

func (*ThermostatService) GetFanTimerActive

func (svc *ThermostatService) GetFanTimerActive(deviceid string) error

GetFanTimerActive indicates if the fan timer is engaged. This is typically set with SetFanTimerDuration See https://developers.nest.com/reference/api-thermostat#fan_timer_active

func (*ThermostatService) SetFanTimerDuration

func (svc *ThermostatService) SetFanTimerDuration(deviceid string, duration int) error

SetFanTimerDuration specifies the length of time (in minutes) that the fan is set to run. See https://developers.nest.com/reference/api-thermostat#fan_timer_duration

func (*ThermostatService) SetHVACMode

func (svc *ThermostatService) SetHVACMode(deviceid string, state hvacMode) error

SetHVACMode sets thermostat to the given mode. Current modes supported: (heat, cool, heat-cool, eco, off) Indicates HVAC system heating/cooling modes, like Heat•Cool for systems with heating and cooling capacity, or Eco Temperatures for energy savings.

See https://developers.nest.com/reference/api-thermostat#hvac_mode

func (*ThermostatService) SetLabel

func (svc *ThermostatService) SetLabel(deviceid string, label string) error

SetLabel sets a custom label for a thermostat. See https://developers.nest.com/reference/api-thermostat#label

func (*ThermostatService) SetTargetTemperature

func (svc *ThermostatService) SetTargetTemperature(deviceid string, scale tempScale, target int) error

SetTargetTemperature changes the target temperature on the Thermostat. See https://developers.nest.com/guides/thermostat-guide#target_temperature

func (*ThermostatService) SetTargetTemperatureRange

func (svc *ThermostatService) SetTargetTemperatureRange(deviceid string, scale tempScale, low, high int) error

SetTargetTemperatureRange changes the target temperature on the Thermostat with a given range. See https://developers.nest.com/guides/thermostat-guide# target_temperature_low(f|c) target_temperature_high(f|c)

func (*ThermostatService) SetTemperatureScale

func (svc *ThermostatService) SetTemperatureScale(deviceid string, scale tempScale) error

SetTemperatureScale sets the temperature scale display to F or C.

func (*ThermostatService) Stream

func (svc *ThermostatService) Stream(deviceID string) (*Stream, error)

Stream opens an event stream to monitor changes on the Thermostat https://developers.nest.com/guides/api/rest-streaming-guide