Nature Remo E API について #

＜2023年3月24日公開： Nature Remo E API をお試しいただけるようになりました＞

2023年3月24日に Nature Remo E API （本API）の一部を一般のお客さま向けに公開いたしました！本エントリでは、本API の基本仕様および想定APIユースケースについて記載します。

APIの概要 #

　本APIは HTTPクライアント経由でリクエスト可能な Cloud API です。本APIを利用することで、Nature Remo E に登録されている以下クラスの ECHONET Lite 対応機器（EL機器）から得られるプロパティ情報（EPC）の取得、操作をするなどのアクションを行うことができます。

太陽光発電クラス
蓄電池クラス
電気自動車用充放電器クラス
電気温水器クラス

RemoE-API-network

用語の定義 #

　本エントリにて登場する用語の定義を以下にまとめます。

用語	意味	参考
Nature Remo E	Nature Remo E（ネイチャーリモイー）は、家庭のエネルギーマネジメントを、安価で手軽に行える次世代型HEMSです。	https://nature.global/nature-remo-e/
HEMS	HEMS（Home Energy Management Systtem）とは、家庭で使うエネルギーをかしこく管理するシステムのことです。HEMSを設置することにより、電気の発電量や使用量、ガス・水道の使用量をモニター画面などで「見える化」したり、HEMS対応の家電や住宅設備を「制御」することができるようになります。家庭全体や家電機器の使用電力量を「見える化」することにより、家族全員の節電意識が高まり、電気使用のムダを省いて電気代を節約できます。	https://echonet.jp/about/hems/.
ECHONET Lite	ECHONET Liteは、センサ類、白物家電、設備系機器など省リソースの機器をIoT化し、エネルギーマネジメントやリモートメンテナンスなどのサービスを実現するための通信仕様です. 通信仕様や各機器の制御コマンドを共通化することで、マルチベンダー環境でのシステム構築を実現します。	https://echonet.jp/about/features/
EL機器	本書では、ECHONET Lite対応機器（太陽光発電システム、蓄電池システム等）の総称として定義します。ECHONET Lite規格でHEMSと通信することができます。	-
EPC	ECHONET Lite規格で定義されている ECHONETプロパティコードの略。EL機器の状態・設定情報(プロパティ)を識別するためのコード	-

API仕様 #

　本APIでは、以下3種類のリクエストを送信することができます。

Nature Remo E が最後に取得した EPC を取得する
対象EL機器の EPC の取得を要求する
（有償サポートオプション）対象EL機器の EPC のセットを要求する

　以下に各リクエストの仕様を記載します。

Nature Remo E が最後に取得した EPC を取得する #

　Nature Remo E は定期的に、登録済みのEL機器の特定のプロパティ（EPC）の取得をしています。本リクエストでは、Nature Remo E が取得済で、クラウドサーバーにアップロードされている最新の EPC 情報を取得できます。

GET /1/echonetlite/appliances HTTP/1.1
...
Authorization: Bearer ${アクセストークン}

　下記のような json がレスポンスされます。type について、蓄電池クラスの場合は type が EL_STORAGE_BATTERY 太陽光発電クラスの場合は EL_SOLAR_POWER 電気自動車用充放電器クラスの場合は EL_EVCD 電気温水器クラスの場合は EL_ELECTRIC_WATER_HEATER が指定されます。

　properties 以下に取得された EPC の配列が配置され、各オブジェクトには epc, val, updated_at キーが存在します。 epc, val の値は hex string となります。

　device プロパティのキーについては https://swagger.nature.global の Device Model が指定されます。この値は Nature Remo E からの定期要求、お客さまからのスマートフォンアプリを通じての要求、機器からの announce 通知、本APIでの更新などにより変更されます。

{
    "appliances": 
        [
            {
                "id": "xxx-xxx-xxx...",
                "nickname": "蓄電池",
                "type": "EL_STORAGE_BATTERY",
                "properties": [
                    {
                        "epc": "cf",
                        "val": "42",
                        "updated_at": "2020-04-27T15:24:03Z"
                    },
                    {
                        "epc": "da",
                        "val": "44",
                        "updated_at": "2020-04-27T15:24:03Z"
                    }
                ],
                "device": {
                    "id": "xxx-xxx-xxx...",
                    "name": "remo-e",
                    "serial_number": "00000000000000",
                    ...
                }
            }
        ]
}

対象EL機器の EPC の取得を要求する #

　本リクエストでは、Nature Remo E で定期取得していない EPC の取得、および定期収集している特定の EPC の最新値の取得を要求できます。

POST /1/echonetlite/appliances/$uuid/refresh HTTP/1.1
...
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer ${アクセストークン}

epc=cf,da

　取得したい EPC をカンマ区切りで指定してください。本リクエストを受け付けた場合には、ステータスコード 202 を返します。Nature Remo E がオフラインになっている場合も同じステータスコードを返します。

　一度に複数の EPC を指定出来ます（最大 12個まで）が、一度に取得できるプロパティの数は実際の機器に依存していますのでご注意ください。一度に13個以上指定があった場合、ステータスコード 400 と code, messageが入ったJSONが返されます。

　本リクエストによりプロパティの取得が成功した場合、GET /1/echonetlite/appliances の結果に反映されます。反映されるまでの時間はネットワークの状態に依存します。また一部のプロパティは Nature Remo E が定期取得していますので、お客さまが明示的に指定する必要のない場合もございます。一度本リクエストで取得されたプロパティは、以降 GET /1/echonetlite/appliances の結果に含まれ続けますが、定期取得していないプロパティについては最後に明示的にリクエストした時の値とタイムスタンプが保持されます。

（有償サポートオプション）対象EL機器の EPC のセットを要求する #

　本リクエストでは、Nature Remo E 経由で対象EL機器の EPC のセットができます。

　注. 本リクエストは別途 Nature株式会社が許可したお客さまのみお使いいただけます。ご利用を検討しているお客さまは、Nature API のフォームからお問い合わせくださいませ。

POST /1/echonetlite/appliances/$uuid/set HTTP/1.1
...
Content-Type:  application/x-www-form-urlencoded
Authorization: Bearer ${アクセストークン}

epc=da
val=44

指定された epc に対して val で指定した値を書き込みます。本リクエストも上述の refresh と同様、リクエストを受け付けた場合にステータスコード202を返します。またデバイスのオフラインの場合での挙動も同様です。値の書き込みが成功した後に、再度そのプロパティの取得を行いその値を返します。書き込み、再取得が成功した場合、 GET /1/echonetlite/appliances の結果に反映されます。反映されるまでの時間はネットワークの状態に依存します。複数の EPC を同時に書き込むことは現在サポートしていません。

【アクセスインターバル制限】

なお、ECHONET Lite 仕様の「連続要求」における

要求を連続する場合は、要求に対する応答を受信後、もしくは応答待ちタイムアウト後に次の要求を行うものとする。

の記載に基づき、POST /1/echonetlite/appliances/:applianceid/set 又は /refresh を要求したあと、要求に対する応答が機器から返ってくるまで、あるいは応答待ち時間を超過するまでは、 POST /1/echonetlite/appliances/:applianceid/set 又は /refresh はご利用いただけません。この要求に対する応答待ち時間は最大20秒です。

API 設計指針と利用時の注意点 #

　本 API は汎用的に利用いただける API にすることを目的として設計されています。そのため、過度な抽象化を行わず ECHONET 機器オブジェクト詳細規定に沿った入力をパラメータとして利用し、また取得する値もそのままのデータを返すようになっています。これに伴い、API を利用いただくユーザには下記のような注意点があります。

1. API レスポンスは hex string で返ってくる #

　下記は API のレスポンスの一部ですが、 epc や val は両方とも hex string で返ってきます。特に val は注意が必要で、10進数の 42 ではなく、16進数の 42 のため、10進数では 66 です。なお、このときの返り値の hex string は小文字で返ってきます。

GET /1/echonetlite/appliances HTTP/1.1
...

...
    { 
      "epc": "cf",
       "val": "42",
       ...
 }

2. API リクエストも hex string で送る必要がある #

　こちらも同上のように hex string でリクエストを送る必要があります。特に注意しなければいけないのが、val の指定です。val は ECHONET 機器オブジェクト詳細規定に記載のバイト数だけ正確に入力する必要があります。例えば 1byte であれば 01, 2バイトであれば 0001, 4バイトであれば 00000001 の用に 0 パディングする必要があります。なお、API リクエストの際の hex string は大文字、小文字どちらでも指定できます。

POST /1/echonetlite/appliances/$uuid/set  HTTP/1.1
...

epc=aa
val=000FFFFF

想定 API ユースケース #

　ここでは API の利用について、下記２つのユースケースを想定し、それぞれの実現方法を記載します。

今すぐに現在のEL機器の EPC を知りたい
（有償サポートオプション）蓄電池を自動モードに設定し、その後のモードおよび動作状態を取得したい

今すぐに現在の EL機器の EPC を知りたい #

　EL機器の EPC には、Nature Remo E が定期的に取得しているものと、取得していないものの二種類があります。 Nature Remo E が定期的に値を取得している情報であっても定期的に取得している間隔以外のタイミングで情報を知りたい場合や、定期取得していないが情報を知りたい場合があります。

　その際は、EPC の再取得を促して最新値を取得するために、以下の手順を実施します。

Nature Remo E に蓄電残量1 の取得をリクエストする

　Nature Remo E に明示的に情報の取得をリクエストします。

POST /1/echonetlite/appliances/$uuid/refresh HTTP/1.1
...
Content-Type:  application/x-www-form-urlencoded
Authorization: Bearer ${アクセストークン}

epc=e2

EL機器(アプライアンス)の情報を取得する

　ステップ1 の後に EPC を取得します。この際、EL機器の仕様によっては EPC の反映に時間がかかり Nature Remo E が EPC を取得できるまでに時間を要します。そのため、ステップ 1 完了後しばらく間隔を開けてから GET リクエストを発行してください。最新の情報が取得できているかどうかは、property の updated_at を確認すると参考になります。

GET /1/echonetlite/appliances HTTP/1.1
...
Authorization: Bearer ${アクセストークン}

{
    "appliances": 
        [
            {
                "id": "xxx-xxx-xxx...",
                "nickname": "蓄電池",
                "type": "EL_STORAGE_BATTERY",
                "properties": [
                    {
                        "epc": "cf",
                        "val": "46",
                        "updated_at": "2020-04-27T15:24:03Z"
                    },
                    {
                        "epc": "da",
                        "val": "46",
                        "updated_at": "2020-04-27T15:24:03Z"
                    }
                ],
                "device": {
                    "id": "xxx-xxx-xxx...",
                    "name": "remo-e",
                    "serial_number": "00000000000000",
                    ...
                }
            }
        ]
}

（有償サポートオプション）蓄電池を自動モードに設定し、その後のモードと動作状態を取得したい #

　蓄電池のモードを変更しその状態を確認する際には、下記の 3 ステップが必要です。

　注. 対象EL機器の EPC のセットを要求するリクエストは別途 Nature株式会社が許可したお客さまのみお使いいただけます。ご利用を検討しているお客さまは、Nature API のフォームからお問い合わせください。

蓄電池のモードを自動モードにセットする

POST /1/echonetlite/appliances/$uuid/set HTTP/1.1
...
Content-Type:  application/x-www-form-urlencoded
Authorization: Bearer ${アクセストークン}

epc=da
val=46

Nature Remo E に EPC(動作モード 0xCF と動作状態 0xDA)の再取得をリクエストする

　ステップ 1 でセットされただけでは Nature Remo E は各種変更内容を取得していないため、明示的に情報の取得リクエストが必要です。

POST /1/echonetlite/appliances/$uuid/refresh HTTP/1.1
...
Content-Type:  application/x-www-form-urlencoded
Authorization: Bearer ${アクセストークン}

epc=cf,da

EL機器(アプライアンス)の情報を取得する

　ステップ 2 の後、機器の情報が最新に更新されていれば最新の情報を取得できます。この際、EL機器の仕様によっては EPC の反映に時間がかかり Nature Remo E が EPC を取得できるまでに時間を要します。そのため、ステップ 2 完了後しばらく間隔を開けてから GET リクエストを発行してください。最新の情報が取得できているかどうかは、property の updated_at を確認すると参考になります。

GET /1/echonetlite/appliances HTTP/1.1
...
Authorization: Bearer ${アクセストークン}

{
    "appliances": 
        [
            {
                "id": "xxx-xxx-xxx...",
                "nickname": "蓄電池",
                "type": "EL_STORAGE_BATTERY",
                "properties": [
                    {
                        "epc": "cf",
                        "val": "46",
                        "updated_at": "2020-04-27T15:24:03Z"
                    },
                    {
                        "epc": "da",
                        "val": "46",
                        "updated_at": "2020-04-27T15:24:03Z"
                    }
                ],
                "device": {
                    "id": "xxx-xxx-xxx...",
                    "name": "remo-e",
                    "serial_number": "00000000000000",
                    ...
                }
            }
        ]
}