Skip to content

morinokami/nature-remo

Repository files navigation

Python Client for Nature Remo API

PyPI version Test

Introduction

nature-remo is a Python client for the Nature Remo API.

Installation

$ pip install nature-remo

Usage

To create an instance of remo.NatureRemoAPI with your access token:

>>> from remo import NatureRemoAPI
>>> api = NatureRemoAPI('access_token')

To fetch the authenticated user's information:

>>> user = api.get_user()
>>> user.id
'user_id'
>>> user.nickname
'your_nickname'

To fetch the list of Remo devices and print the temperature of the first device:

>>> devices = api.get_devices()
>>> devices[0].newest_events['te'].val
26.528809

To fetch the list of appliances:

>>> appliances = api.get_appliances()
>>> appliances[0].id
'appliance_id'
>>> appliances[0].type
'AC'

To update air conditioner settings:

>>> aircon = appliances[0]
>>> api.update_aircon_settings(aircon.id, 'cool', '27', 'auto', 'swing', '')

To send a tv infrared signal:

>>> appliances[1].type
'TV'
>>> tv = appliances[1]
>>> api.send_tv_infrared_signal(tv.id, 'power')

To check the current rate limit status:

>>> api.get_user()
...
>>> api.rate_limit
RateLimit(checked_at=datetime.datetime(2020, 7, 28, 8, 11, 4), limit=30, remaining=29, reset=datetime.datetime(2020, 7, 28, 8, 15))
>>> api.rate_limit.checked_at, api.rate_limit.limit, api.rate_limit.remaining, api.rate_limit.reset
(datetime.datetime(2020, 7, 28, 8, 11, 4), 30, 29, datetime.datetime(2020, 7, 28, 8, 15))

To create an instance of remo.NatureRemoLocalAPI:

>>> from remo import NatureRemoLocalAPI
>>> local_api = NatureRemoLocalAPI('ip_addr')

To fetch the newest received IR signal:

>>> local_api.get_ir_signal()
IRSignal(freq=38, data=[0], format='us')

To emit an IR signal:

>>> message = '{"format": "us", "freq": 38, "data": [0]}'
>>> local_api.send_ir_signal(message)

To print the underlying urllib3 debug information:

>>> api = NatureRemoAPI('access_token', debug=True)
>>> api.get_user()
DEBUG:urllib3.connectionpool:Starting new HTTPS connection (1): api.nature.global:443
send: b'GET /1/users/me HTTP/1.1\r\nHost: api.nature.global\r\nUser-Agent: nature-remo/0.1.0 (https://github.com/morinokami/nature-remo)\r\nAccept-Encoding: gzip, deflate\r\nAccept: application/json\r\nConnection: keep-alive\r\nAuthorization: Bearer access_token\r\n\r\n'
reply: 'HTTP/1.1 200 OK\r\n'
header: Date: Mon, 27 Jul 2020 15:53:12 GMT
header: Content-Type: application/json; charset=utf-8
header: Content-Length: 72
header: Connection: keep-alive
header: Access-Control-Allow-Origin: *
header: Cache-Control: no-cache, no-store, must-revalidate, private, max-age=0
header: Expires: Thu, 01 Jan 1970 00:00:00 UTC
header: Pragma: no-cache
header: Strict-Transport-Security: max-age=86400
header: Vary: Accept-Encoding
header: X-Accel-Expires: 0
header: X-Content-Type-Options: nosniff
header: X-Frame-Options: SAMEORIGIN
header: X-Rate-Limit-Limit: 30
header: X-Rate-Limit-Remaining: 29
header: X-Rate-Limit-Reset: 1595865300
header: X-Xss-Protection: 1; mode=block
DEBUG:urllib3.connectionpool:https://api.nature.global:443 "GET /1/users/me HTTP/1.1" 200 72
User(id='user_id', nickname='your_nickname')

CLI

nature-remo has the command line interface as well. To invoke the command, type remo on the command line:

$ remo
Usage: remo [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  appliance
  device
  local
  signal
  user

The remo command consists of five subcommands, which represent the object you interact with. For example, the device subcommand can be used to interact with the Nature Remo devices associated with your account. Enter remo device on the command line to see what actions the device subcommands supports:

$ remo device
Usage: remo device [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  delete                     Delete Remo.
  get                        Fetch the list of Remo devices the user has...
  update                     Update Remo.
  update_humidity_offset     Update humidity offset.
  update_temperature_offset  Update temperature offset.

We can see that the subcommand has five actions. Thus, for example, if you want to know about the Remo devices associated with your account, enter the following command:

$ remo device get --token <access_token>
[{"created_at": "2020-07-23T03:10:21+00:00", ...}]

The access token can be specified as an environment variable:

$ export REMO_ACCESS_TOKEN=<access_token>
$ remo device get
[{"created_at": "2020-07-23T03:10:21+00:00", ...}]

Use the --debug flag to inspect the details about the HTTP connection:

$ remo user update foo --debug
DEBUG:urllib3.connectionpool:Starting new HTTPS connection (1): api.nature.global:443
send: b'POST /1/users/me HTTP/1.1\r\nHost: api.nature.global\r\nUser-Agent: nature-remo/0.3.0 (https://github.com/morinokami/nature-remo)\r\nAccept-Encoding: gzip, deflate\r\nAccept: application/json\r\nConnection: keep-alive\r\nAuthorization: Bearer access_token\r\nContent-Length: 12\r\nContent-Type: application/x-www-form-urlencoded\r\n\r\n'
send: b'nickname=foo'
reply: 'HTTP/1.1 200 OK\r\n'
header: Date: Fri, 31 Jul 2020 07:26:52 GMT
header: Content-Type: application/json; charset=utf-8
header: Content-Length: 62
header: Connection: keep-alive
header: Access-Control-Allow-Origin: *
header: Cache-Control: no-cache, no-store, must-revalidate, private, max-age=0
header: Expires: Thu, 01 Jan 1970 00:00:00 UTC
header: Pragma: no-cache
header: Strict-Transport-Security: max-age=86400
header: Vary: Accept-Encoding
header: X-Accel-Expires: 0
header: X-Content-Type-Options: nosniff
header: X-Frame-Options: SAMEORIGIN
header: X-Rate-Limit-Limit: 30
header: X-Rate-Limit-Remaining: 21
header: X-Rate-Limit-Reset: 1596180600
header: X-Xss-Protection: 1; mode=block
DEBUG:urllib3.connectionpool:https://api.nature.global:443 "POST /1/users/me HTTP/1.1" 200 62
{"id": "user_id", "nickname": "foo"}

Internally, those remo <subcommand> <action> (<args>) commands are mapped to the Nature Remo API. The full list of those mappings is as follows:

Command Nature Remo API
remo user get GET /1/users/me
remo user update POST /1/users/me
remo device get GET /1/devices
remo device update POST /1/devices/{device}
remo device delete POST /1/devices/{device}/delete
remo device update_temperature_offset POST /1/devices/{device}/temperature_offset
remo device update_humidity_offset POST /1/devices/{device}/humidity_offset
remo appliance detect POST /1/detectappliance
remo appliance create POST /1/appliances
remo appliance get GET /1/appliances
remo appliance update POST /1/appliances/{appliance}
remo appliance delete POST /1/appliances/{appliance}/delete
remo appliance update_orders POST /1/appliance_orders
remo appliance update_aircon_settings POST /1/appliances/{appliance}/aircon_settings
remo appliance send_tv_infrared_signal POST /1/appliances/{appliance}/tv
remo appliance send_light_infrared_signal POST /1/appliances/{appliance}/light
remo signal create /1/appliances/{appliance}/signals
remo signal get GET /1/appliances/{appliance}/signals
remo signal update POST /1/signals/{signal}
remo signal delete /1/signals/{signal}/delete
remo signal send /1/signals/{signal}/send
remo signal update_orders /1/appliances/{appliance}/signal_orders

Development Status

Cloud API (Base URL: api.nature.global/)

Status HTTP Method Endpoint API
⚡️ GET /1/users/me get_user
⚡️ POST /1/users/me update_user
⚡️ GET /1/devices get_devices
️⚡️ POST /1/detectappliance detect_appliance
⚡️ GET /1/appliances get_appliances
POST /1/appliances create_appliance
⚡️ POST /1/appliance_orders update_appliance_orders
POST /1/appliances/{appliance}/delete delete_appliance
⚡️ POST /1/appliances/{appliance} update_appliance
POST /1/appliances/{appliance}/aircon_settings update_aircon_settings
⚡️ POST /1/appliances/{appliance}/tv send_tv_infrared_signal
️⚡ POST /1/appliances/{appliance}/light send_light_infrared_signal
⚡️ GET /1/appliances/{appliance}/signals get_signals
POST /1/appliances/{appliance}/signals create_signal
POST /1/appliances/{appliance}/signal_orders update_signal_orders
POST /1/signals/{signal} update_signal
POST /1/signals/{signal}/delete delete_signal
POST /1/signals/{signal}/send send_signal
⚡️ POST /1/devices/{device} update_device
⚡️ POST /1/devices/{device}/delete delete_device
⚡️ POST /1/devices/{device}/temperature_offset update_temperature_offset
⚡️ POST /1/devices/{device}/humidity_offset update_humidity_offset

Local API (Base URL: remo.local/)

Status HTTP Method Endpoint API
⚡️ GET /messages get_ir_signal
⚡️ POST /messages send_ir_signal

How to Develop

$ git clone git@github.com:morinokami/nature-remo.git
$ cd nature-remo
$ pipenv sync --dev
$ pipenv shell
$ pre-commit install

はじめに

nature-remo は、Nature Remo API の Python クライアントです。

インストール

$ pip install nature-remo

使い方

アクセストークンを指定して remo.NatureRemoAPI のインスタンスを作成する:

>>> from remo import NatureRemoAPI
>>> api = NatureRemoAPI('access_token')

認証されたユーザーの情報を取得する:

>>> user = api.get_user()
>>> user.id
'user_id'
>>> user.nickname
'your_nickname'

Remo の機器リストを取得し、最初の機器の温度を表示する:

>>> devices = api.get_devices()
>>> devices[0].newest_events['te'].val
26.528809

家電製品のリストを取得する:

>>> appliances = api.get_appliances()
>>> appliances[0].id
'appliance_id'
>>> appliances[0].type
'AC'

エアコンの設定を変更する:

>>> aircon = appliances[0]
>>> api.update_aircon_settings(aircon.id, 'cool', '27', 'auto', 'swing', '')

テレビの赤外線を送信する:

>>> appliances[1].type
'TV'
>>> tv = appliances[1]
>>> api.send_tv_infrared_signal(tv.id, "power")

現在の呼び出し制限 (Rate Limit) を確認する:

>>> api.get_user()
...
>>> api.rate_limit
RateLimit(checked_at=datetime.datetime(2020, 7, 28, 8, 11, 4), limit=30, remaining=29, reset=datetime.datetime(2020, 7, 28, 8, 15))
>>> api.rate_limit.checked_at, api.rate_limit.limit, api.rate_limit.remaining, api.rate_limit.reset
(datetime.datetime(2020, 7, 28, 8, 11, 4), 30, 29, datetime.datetime(2020, 7, 28, 8, 15))

remo.NatureRemoLocalAPI のインスタンスを作成する:

>>> from remo import NatureRemoLocalAPI
>>> local_api = NatureRemoLocalAPI('ip_addr')

受信した最新の赤外線信号を取得する:

>>> local_api.get_ir_signal()
IRSignal(freq=38, data=[0], format='us')

赤外線を送出する:

>>> message = '{"format": "us", "freq": 38, "data": [0]}'
>>> local_api.send_ir_signal(message)

urllib3のデバッグ情報を出力する:

>>> api = NatureRemoAPI('access_token', debug=True)
>>> api.get_user()
DEBUG:urllib3.connectionpool:Starting new HTTPS connection (1): api.nature.global:443
send: b'GET /1/users/me HTTP/1.1\r\nHost: api.nature.global\r\nUser-Agent: nature-remo/0.1.0 (https://github.com/morinokami/nature-remo)\r\nAccept-Encoding: gzip, deflate\r\nAccept: application/json\r\nConnection: keep-alive\r\nAuthorization: Bearer access_token\r\n\r\n'
reply: 'HTTP/1.1 200 OK\r\n'
header: Date: Mon, 27 Jul 2020 15:53:12 GMT
header: Content-Type: application/json; charset=utf-8
header: Content-Length: 72
header: Connection: keep-alive
header: Access-Control-Allow-Origin: *
header: Cache-Control: no-cache, no-store, must-revalidate, private, max-age=0
header: Expires: Thu, 01 Jan 1970 00:00:00 UTC
header: Pragma: no-cache
header: Strict-Transport-Security: max-age=86400
header: Vary: Accept-Encoding
header: X-Accel-Expires: 0
header: X-Content-Type-Options: nosniff
header: X-Frame-Options: SAMEORIGIN
header: X-Rate-Limit-Limit: 30
header: X-Rate-Limit-Remaining: 29
header: X-Rate-Limit-Reset: 1595865300
header: X-Xss-Protection: 1; mode=block
DEBUG:urllib3.connectionpool:https://api.nature.global:443 "GET /1/users/me HTTP/1.1" 200 72
User(id='user_id', nickname='your_nickname')

CLI

nature-remo にはコマンドラインインターフェイスもあります。 コマンドを実行するには、コマンドラインで remo と入力してください:

$ remo
Usage: remo [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  appliance
  device
  local
  signal
  user

remo コマンドは五つのサブコマンドから成り、それぞれが操作の対象を表わしています。 たとえば、device サブコマンドは、あなたのアカウントに紐付いている Nature Remo の機器に対する操作を可能とします。 コマンドライン上で remo device と入力し、device がサポートしている操作を確認してみましょう:

$ remo device
Usage: remo device [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  delete                     Delete Remo.
  get                        Fetch the list of Remo devices the user has...
  update                     Update Remo.
  update_humidity_offset     Update humidity offset.
  update_temperature_offset  Update temperature offset.

このサブコマンドは五つの操作をサポートしていることがわかります。 これより、たとえばあなたのアカウントに紐付いている Remo の機器について知りたければ、次のコマンドを実行してください:

$ remo device get --token <access_token>
[{"created_at": "2020-07-23T03:10:21+00:00", ...}]

アクセストークンは環境変数により指定することもできます:

$ export REMO_ACCESS_TOKEN=<access_token>
$ remo device get
[{"created_at": "2020-07-23T03:10:21+00:00", ...}]

--debug フラグにより、HTTP 通信の詳細を確認することが可能です:

$ remo user update foo --debug
DEBUG:urllib3.connectionpool:Starting new HTTPS connection (1): api.nature.global:443
send: b'POST /1/users/me HTTP/1.1\r\nHost: api.nature.global\r\nUser-Agent: nature-remo/0.3.0 (https://github.com/morinokami/nature-remo)\r\nAccept-Encoding: gzip, deflate\r\nAccept: application/json\r\nConnection: keep-alive\r\nAuthorization: Bearer access_token\r\nContent-Length: 12\r\nContent-Type: application/x-www-form-urlencoded\r\n\r\n'
send: b'nickname=foo'
reply: 'HTTP/1.1 200 OK\r\n'
header: Date: Fri, 31 Jul 2020 07:26:52 GMT
header: Content-Type: application/json; charset=utf-8
header: Content-Length: 62
header: Connection: keep-alive
header: Access-Control-Allow-Origin: *
header: Cache-Control: no-cache, no-store, must-revalidate, private, max-age=0
header: Expires: Thu, 01 Jan 1970 00:00:00 UTC
header: Pragma: no-cache
header: Strict-Transport-Security: max-age=86400
header: Vary: Accept-Encoding
header: X-Accel-Expires: 0
header: X-Content-Type-Options: nosniff
header: X-Frame-Options: SAMEORIGIN
header: X-Rate-Limit-Limit: 30
header: X-Rate-Limit-Remaining: 21
header: X-Rate-Limit-Reset: 1596180600
header: X-Xss-Protection: 1; mode=block
DEBUG:urllib3.connectionpool:https://api.nature.global:443 "POST /1/users/me HTTP/1.1" 200 62
{"id": "user_id", "nickname": "foo"}

内部では、こうした remo <subcommand> <action> (<args>) コマンドは Nature Remo API へとマップされています。 マッピングのフルリストは以下の通りです:

Command Nature Remo API
remo user get GET /1/users/me
remo user update POST /1/users/me
remo device get GET /1/devices
remo device update POST /1/devices/{device}
remo device delete POST /1/devices/{device}/delete
remo device update_temperature_offset POST /1/devices/{device}/temperature_offset
remo device update_humidity_offset POST /1/devices/{device}/humidity_offset
remo appliance detect POST /1/detectappliance
remo appliance create POST /1/appliances
remo appliance get GET /1/appliances
remo appliance update POST /1/appliances/{appliance}
remo appliance delete POST /1/appliances/{appliance}/delete
remo appliance update_orders POST /1/appliance_orders
remo appliance update_aircon_settings POST /1/appliances/{appliance}/aircon_settings
remo appliance send_tv_infrared_signal POST /1/appliances/{appliance}/tv
remo appliance send_light_infrared_signal POST /1/appliances/{appliance}/light
remo signal create /1/appliances/{appliance}/signals
remo signal get GET /1/appliances/{appliance}/signals
remo signal update POST /1/signals/{signal}
remo signal delete /1/signals/{signal}/delete
remo signal send /1/signals/{signal}/send
remo signal update_orders /1/appliances/{appliance}/signal_orders