Package: python-nest
Installation[sudo]pipinstallpython-nestNOTEThe4.xversion uses the streaming endpoint. To use the older
polling/caching behavior pin your requirements topython-nest<4.0.NOTEThe3.xversion uses the Nest official api. As such, some functionality
was removed as it is not available. To keep the old version and functionality, make sure to set
your requirements topython-nest<3.0.Nest Developer AccountYou will need a Nest developer account, and a Product on the Nest developer portal to use this module:VisitNest Developers, and sign in. Create an account if you don’t have one already.Fill in the account details:The “Company Information” can be anything.Submit changes.Click “Products” at top of page.Click “Create New Product”Fill in details:Product name must be unique.The description, users, urls can all be anything you want.For permissions, check every box and if it’s an option select the read/write option.The description requires a specific format to be accepted.Click “Create Product”.Once the new product page opens the “Product ID” and “Product Secret” are located on the right side. These will be used as client_id and client_secret below.UsageMigrate to 4.xThe version 4.x usesNest Stream API, so that you can get nearly real time status update of your Nest devices.If you use python-nest as a command line tool:You don’t need to change, but there is a new command line option--keep-aliveyou can give a try.If you use python-nest in a poll loop, to query Nest device’s property in certain period, there are several noticeable changes:The internal cache removed, theStructureandDeviceobjects will always return their current state presented in Nest API.A persistence HTTP connection will keep open for eachNestobject. Therefore, please avoid to create more than one Nest object in your program.Your poll query would not hit the API rate limit, you can increase your poll frequency.If you want to change to Push mode:You need to listenNest.update_event.
Please note, any data change in all of your structures an devices will set theupdate_event. You don’t know which field got update.importnestnapi=nest.Nest(client_id=client_id,client_secret=client_secret,access_token_cache_file=access_token_cache_file)whilenapi.update_event.wait():napi.update_event.clear()# assume you have one Nest Cameraprint(napi.structures[0].cameras[0].motion_detected)If you use asyncio:You have to wrapupdate_event.wait()in anThreadPoolExecutor, for example:importasyncioimportnestnapi=nest.Nest(client_id=client_id,client_secret=client_secret,access_token_cache_file=access_token_cache_file)event_loop=asyncio.get_event_loop()try:event_loop.run_until_complete(nest_update(event_loop,napi))finally:event_loop.close()asyncdefnest_update(loop,napi):withThreadPoolExecutor(max_workers=1)asexecutor:whileTrue:awaitloop.run_in_executor(executor,nest.update_event.wait)nest.update_event.clear()# assume you have one Nest Cameraprint(napi.structures[0].cameras[0].motion_detected)ModuleYou can import the module asnest.importnestimportsysclient_id='XXXXXXXXXXXXXXX'client_secret='XXXXXXXXXXXXXXX'access_token_cache_file='nest.json'napi=nest.Nest(client_id=client_id,client_secret=client_secret,access_token_cache_file=access_token_cache_file)ifnapi.authorization_required:print('Go to '+napi.authorize_url+' to authorize, then enter PIN below')ifsys.version_info[0]<3:pin=raw_input("PIN: ")else:pin=input("PIN: ")napi.request_token(pin)forstructureinnapi.structures:print('Structure%s'%structure.name)print('    Away:%s'%structure.away)print('    Security State:%s'%structure.security_state)print('    Devices:')fordeviceinstructure.thermostats:print('        Device:%s'%device.name)print('            Temp:%0.1f'%device.temperature)# Access advanced structure properties:forstructureinnapi.structures:print('Structure   :%s'%structure.name)print(' Postal Code                    :%s'%structure.postal_code)print(' Country                        :%s'%structure.country_code)print(' num_thermostats                :%s'%structure.num_thermostats)# Access advanced device properties:fordeviceinstructure.thermostats:print('        Device:%s'%device.name)print('        Where:%s'%device.where)print('            Mode       :%s'%device.mode)print('            HVAC State :%s'%device.hvac_state)print('            Fan        :%s'%device.fan)print('            Fan Timer  :%i'%device.fan_timer)print('            Temp       :%0.1fC'%device.temperature)print('            Humidity   :%0.1f%%'%device.humidity)print('            Target     :%0.1fC'%device.target)print('            Eco High   :%0.1fC'%device.eco_temperature.high)print('            Eco Low    :%0.1fC'%device.eco_temperature.low)print('            hvac_emer_heat_state  :%s'%device.is_using_emergency_heat)print('            online                :%s'%device.online)# The Nest object can also be used as a context manager# It is only for demo purpose, please do not create more than one Nest object in your program especially after 4.0 releasewithnest.Nest(client_id=client_id,client_secret=client_secret,access_token_cache_file=access_token_cache_file)asnapi:fordeviceinnapi.thermostats:device.temperature=23# Nest products can be updated to include other permissions. Before you# can access them with the API, a user has to authorize again. To handle this# and detect when re-authorization is required, pass in a product_versionclient_id='XXXXXXXXXXXXXXX'client_secret='XXXXXXXXXXXXXXX'access_token_cache_file='nest.json'product_version=1337# It is only for demo purpose, please do not create more than one Nest object in your program especially after 4.0 releasenapi=nest.Nest(client_id=client_id,client_secret=client_secret,access_token_cache_file=access_token_cache_file,product_version=product_version)print("Never Authorized:%s"%napi.never_authorized)print("Invalid Token:%s"%napi.invalid_access_token)print("Client Version out of date:%s"%napi.client_version_out_of_date)ifnapi.authorization_requiredisNone:print('Go to '+napi.authorize_url+' to authorize, then enter PIN below')pin=input("PIN: ")napi.request_token(pin)# NOTE: By default all datetime objects are timezone unaware (UTC)#       By passing ``local_time=True`` to the ``Nest`` object datetime objects#       will be converted to the timezone reported by nest. If the ``pytz``#       module is installed those timezone objects are used, else one is#       synthesized from the nest datanapi=nest.Nest(username,password,local_time=True)printnapi.structures[0].weather.current.datetime.tzinfoIn the API, all temperature values are reported and set in the temperature scale
the device is set to (as determined by thedevice.temperature_scaleproperty).Helper functions for conversion are in theutilsmodule:fromnestimportutilsasnest_utilstemp=23.5fahrenheit=nest_utils.c_to_f(temp)temp==nest_utils.f_to_c(fahrenheit)The utils function usedecimal.Decimalto ensure precision.Command lineusage:nest[-h][--confFILE][--token-cacheTOKEN_CACHE_FILE][-tTOKEN][--client-idID][--client-secretSECRET][-k][-c][-sSERIAL][-SSTRUCTURE][-iINDEX][-v]{temp,fan,mode,away,target,humid,target_hum,show,camera-show,camera-streaming,protect-show}...CommandlineinterfacetoNest™Thermostatspositionalarguments:{temp,fan,mode,away,target,humid,target_hum,show,camera-show,camera-streaming,protect-show}commandhelptempshow/settemperaturefansetfan"on"or"auto"modeshow/setcurrentmodeawayshow/setcurrentawaystatustargetshowcurrenttemptargethumidshowcurrenthumiditytarget_humshow/settargethumidtyshowshoweverythingcamera-showshoweverything(forcameras)camera-streamingshow/setcamerastreamingprotect-showshoweverything(forNestProtect)optionalarguments:-h,--helpshowthishelpmessageandexit--confFILEconfigfile(default~/.config/nest/config)--token-cacheTOKEN_CACHE_FILEauthaccesstokencachefile-tTOKEN,--tokenTOKENauthaccesstoken--client-idIDproductidondeveloper.nest.com--client-secretSECRETproductsecretfornest.com-k,--keep-alivekeepshowingupdatereceivedfromstreamAPIinshowandcamera-showcommands-c,--celsiususecelsiusinsteadoffarenheit-sSERIAL,--serialSERIALoptional,specifyserialnumberofnestthermostattotalkto-SSTRUCTURE,--structureSTRUCTUREoptional,specifystructurenametoscopedeviceactions-iINDEX,--indexINDEXoptional,specifyindexnumberofnesttotalkto-v,--verboseshowingverboseloggingexamples:# If your nest is not in range modenest--confmyconfig--client-idCLIENTID--client-secretSECRETtemp73# If your nest is in range modenest--confmyconfig--client-idCLIENTID--client-secretSECRETtemp6673nest--confmyconfig--client-idCLIENTID--client-secretSECRETfan--autonest--confmyconfig--client-idCLIENTID--client-secretSECRETtarget_hum35# nestcam examplesnest--confmyconfig--client-idCLIENTID--client-secretSECRETcamera-shownest--confmyconfig--client-idCLIENTID--client-secretSECRETcamera-streaming--enable-camera-streaming# Stream API examplenest--confmyconfig--client-idCLIENTID--client-secretSECRET--keep-aliveshownest--confmyconfig--client-idCLIENTID--client-secretSECRET--keep-alivecamera-show# Set ETA 5 minutes from nownest--confmyconfig--client-idCLIENTID--client-secretSECRETaway--away--eta5A configuration file must be specified and used for the credentials to communicate with the NEST Thermostat initially.  Once completed and a token is generated, if you’re using the default location for the token, the command line option will read from it automatically.[NEST]client_id=your_client_idclient_secret=your_client_secrettoken_cache=~/.config/nest/token_cacheThe[NEST]section may also be named[nest]for convenience. Do not use[DEFAULT]as it cannot be readHistoryThis module was originally a fork ofnest_thermostatwhich was a fork ofpynest