mzzrd / nestpy

NestPy

A command line interface (cli) and module, written in python, for interfacing with your Nest Thermostat
Report Bug · Request Feature

Table of Contents

1. About The Project
2. Getting Started
   • Acquiring SDM API Credentials
   • Manual Package Install
3. Usage
   • Setting Temperature Setpoint
   • Getting Traits
   • Setting Thermostat Mode
4. License
5. Contact

About The Project

This project is aimed at being a fun way for me to learn how to make CLI programs. As a bonus it deals with something I find very interesting, which is using code to influence the physical world. It's really exciting to be able to change the temperature in my room simply by typing commands in my terminal.

The potential for automation and other projects is immense. Being a CLI program makes it easy to use in any programming language that can call shell commands. Additionally, the package can be imported into other Python scripts.

I've designed this project to fit my specific needs, so some features might be missing. However, the code is easily extendable, and I'm happy to include any contributions from others to complete this package.

(back to top)

Getting Started

Installation of this package comprises of two main steps, acruiring the smart device management (SDM) API credentials and manually installing and configuring the python package. These steps are outlined in the consequent sections respectively.

Acquiring SDM API Credentials

Before you begin, you'll need to register for Device Access. This involves accepting the Google API and Device Access Sandbox Terms of Service, as well as paying a one-time, non-refundable fee of US$5 per account.

For detailed instructions and troubleshooting tips, please consult the official guide.

Next, create a project and obtain the required API keys/credentials by following the Quick Start Guide.

Make sure to note down the following API keys/credentials for later use: project-id, device-id, access-token, refresh-token, oauth2-client-id, and oauth2-client-secret.

Note

The refresh-token will expire after 7 days if the project is in testing mode. If this happens, follow the process outlined in Google's Device Access Authorization Guide to obtain a new access and refresh token. For more information on token expiration, refer to the OAuth 2.0 Token Expiration documentation.

Manual Package Install

1. Clone the repository:

   git clone https://github.com/MZZRD/NestPy.git

2. Navigate to the directory
3. Install Python package:

   pip install .

4. Configure API keys/credentials by replacing the placeholders (...) with the corresponding values for each option:

   nestpy config \
     --project-id ... \
     --device-id ... \
     --access-token ... \
     --refresh-token ... \
     --oauth2-client-id ... \
     --oauth2-client-secret ...

(back to top)

Usage

You can use the --help option to get information about the available commands and their options.

Usage: nestpy [OPTIONS] COMMAND [ARGS]...

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  config
  get
  mode
  set

Where nestpy <COMMAND> --help shows the options available for each command.

Setting Temperature Setpoint

To set the temperature setpoint, use the -t/--temperature option followed by the desired temperature in Celsius:

nestpy set -t 23

Getting Traits

The get command is used to get traits like the ambient humidity percentage -h/--humidity, ambient temperature -t/--temperature, temperature setpoint -s/--setpoint and thermostat mode -m/--mode.

Multiple options can be chained together, like so:

nestpy get -htsm

This command outputs:

65 20.75 20.5 HEAT

The values are printed inline, separated by a space character. Chaining options like this is faster than retrieving each option individually, as it only requires a single API request instead of multiple."

Setting Thermostat Mode

The mode command is used to set the thermostat mode to either OFF -o/--off, MANUAL_ECO -e/--eco and HEAT -h/--heat.

For instance, running the command:

nestpy mode -h

sets the thermostat mode to HEAT.

Note

When the thermostat mode is set to OFF/MANUAL_ECO, it's not possible to set the current temperature setpoint, but it is possible to retrieve information about it. To be able to set the temperature setpoint again, switch the thermostat mode to HEAT.

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Maarten ten Voorde - LinkedIn - [email protected]

Project Link: https://github.com/MZZRD/NestPy

(back to top)