JET IoT ご利用マニュアル

はじめに

本書では、IoT外部連携サービス「JET IoT」における、ご利用方法について記載しています。

JET IoTは、外部WEBアプリケーションとの連携を可能にするための「WEB API」や「Webhook」インタフェースを提供します。JET IoTのご利用には、事前に利用登録申し込みおよび契約が必要になります。

サービス利用規約

ご利用にあたり、 クラウドサービス利用規約 に同意頂く必要がございます。

ご利用環境について

JET IoT（以下、当サービス）は以下の環境でのご利用を推奨いたします。

PC

OSWindows 10 / Mac
インターネット・ブラウザGoogle Chrome（最新版）

ご利用いただけるデバイス

現在お使いいただけるデバイスは下記のとおりです。

デバイス型式機能概要
BICO-EL2LTEモジュール／Ethernet／デジタル出力端子×2を搭載した、インターネット経由で遠隔制御できるデジタル接点出力機
BICO-EL8LTEモジュール／Ethernet／デジタル出力端子×8を搭載した、インターネット経由で遠隔制御できるデジタル接点出力機

JET IoTのご利用方法

JET IoTコンソールへのログイン

JET IoTログインURLにアクセスし、登録済アカウントの「メールアドレス」「パスワード」を入力し、「ログイン」ボタンをクリックして「デバイス管理」画面が表示されることを確認します。

デバイスの登録

ログイン後に表示される「デバイス管理」画面の「デバイス登録」ボタンをクリックし、デバイス登録ダイアログを表示します。

デバイス購入時に同封されている「デバイスID」「アクティベートコード」を入力し、「アクティベート」ボタンをクリックします。

デバイス登録確認後、一覧に登録したデバイスIDが追加されている事を確認します。

JET IoT WEBアプリケーション用のAPI KEYの発行

アプリケーションの登録

上部メニュー「アプリケーション管理」をクリックし、「アプリケーション管理」画面を表示、「アプリケーション登録」ボタンをクリックしてアプリケーション登録ダイアログを表示します。

下記を入力し、「登録」ボタンをクリックしてアプリケーション登録を完了します。

  • アプリケーション名：外部システム名
  • WEB API IP制限：入力IPアドレス以外からのアクセスを受け付けなくなります。
  • WEB HOOK URL：Webhookを利用する場合の外部システムURL（例 https://example.com）
  • メモ：任意入力

アプリケーション一覧に、登録したアプリケーションが追加されている事を確認します。

「API KEY」「API SECRET」の取得

登録したアプリケーションの「詳細」ボタンをクリックし、詳細ダイアログを表示します。詳細ダイアログに表示されている「API KEY」「API SECRET」を控えます。（「API KEY」「API SECRET」は後述のWEBアプリケーションで利用します。）

※「API SECRET」は右に表示されているアイコンをクリックすることで表示されます。

デバイスとアプリケーションの紐付け登録

デバイス毎にアプリケーションの紐付け登録を行うことで、外部システムからのデバイスアクセスが可能になります。

アプリケーションに属するデバイスの選択

上部メニューの「デバイス管理」をクリックし、「デバイス管理」画面を表示します。

アプリケーションに紐付けるデバイスの、左側に表示されているチェックボックスをクリックし、選択状態にします。サブメニュー内の「アプリケーション変更」をクリックし、アプリケーション変更ダイアログを表示します。

アプリケーションの変更

変更対象のデバイスが表示されていることを確認の上、紐付けるアプリケーションを選択し、「更新」ボタンをクリックします。

アプリケーションの変更の確認

対象のデバイスが、変更したアプリケーションに切り替わっている事を確認します。

Web API

外部システムから、JET IoTを利用して、当社デバイス BICO-EL2 、 BICO-EL8 を遠隔制御する際のAPI利用例を紹介します。

Web API 共通

リクエスト

URL

ご契約後に[APIエンドポイント]をお伝えいたします。

Method

GET

または

POST

Header

Authorization: Basic base64_encode([API KEY]:[API SECRET])

Body

JSON 形式で記述

レスポンス

StatusCode説明
200アプリケーション正常応答時
401API KEY、API SECRETが正しくない
404URLまたはMethodが正しくない
502デバイスへ通信できない
504デバイスから 30 秒間応答が無く、タイムアウト時

※通信環境によって上記以外のステータスコードが返却される場合があります。

※プロキシ等がステータスコード 200 を返却する可能性があります。

Header

Content-Type: application/json; charset=utf-8

Body

JSON形式で返却

JET IoT登録デバイス一覧情報取得API

アプリケーションに紐付いたデバイスの一覧情報を取得します。

リクエスト

URL

[APIエンドポイント]/device

Method

GET

Body

なし

レスポンス

Body

例）

{
  "code": 0,
  "data": {
    "devices": [
      {
        "device_id": "abcdefgh",
        "name": "名前",
        "product_name": "bico-el2",
        "product_version": "v1.0.0",
        "alive_flg": false,
        "revoke_flg": false,
        "connected_at": null,
        "disconnected_at": "2017-01-31 12:00:00"
      },
      {
        "device_id": " 12345678 ",
        "name": "名前",
        "product_name": "bico-el2",
        "product_version": "v1.0.0",
        "alive_flg": true,
        "revoke_flg": false,
        "connected_at": "2017-01-31 12:00:00",
        "disconnected_at": null
      },
      ...
    ]
  }
}

※connected_at, disconnected_atはalive_flgの内容に応じてnullになります。

指定デバイス情報取得API

指定デバイスの情報を取得します。

リクエスト

URL

[APIエンドポイント]/device/[デバイスID]

Method

GET

Body

なし

レスポンス

Body

例）

{
  "code": 0,
  "data": {
    "device": {
      "device_id": "abcdefgh",
      "name": "名前",
      "product_name": "bico-el2",
      "product_version": "v1.0.0",
      "alive_flg": false,
      "revoke_flg": false,
      "connected_at": null,
      "disconnected_at": "2017-01-31 12:00:00"
    }
  }
}

※connected_at, disconnected_atはalive_flgの内容に応じてnullになります。

BICO-EL2 / BICO-EL8 接点制御API

指定したデバイス（ BICO-EL2 / BICO-EL8 ）の接点端子を、指定秒数間、ON／OFFにします。

リクエスト

URL

[APIエンドポイント]/device/[デバイスID]

Method

POST

Body

JSON 形式で記述します。

  • key: write固定
  • data 配列指定
  • data pin: pin番号
  • data state: 0でoff、1でon
  • data time: リクエスト送信後ONを維持する時間（milliseconds）（最大30分）。指定時間後stateが反転します。0の場合は状態保持を継続します。（API実行時または再起動時（※）にリセットされます）

※ネットワーク切断時は自動的にデバイス再起動が行われます。

例）

{
  "key": "write",
  "data": [
    {
      "pin": 1,
      "state": 1,
      "time": 1000
     }
  ]
}

レスポンス

Body

例） 正常時

{
  "code": 0,
  "data":  [
    {
      "pin": 1,
      "state": 1
     },
    {
      "pin": 2,
      "state": 1
     },
  ]
}

例） 異常時

{
  "code": -1,
  "data": "[エラーメッセージ]"
}
  • code: -1　JSONパースエラー
  • code: -2　JSONのフォーマットが異なる（keyがない等）
  • code: -3　keyがoutput以外
  • code: -4　dataフォーマットが異なる

Webhook

デバイスからの通知を、管理画面で設定したURLへ特定のフォーマットで送信します。

外部システムから、JET IoTを利用して、当社デバイス BICI-EL2 からの通知を受信するAPIを紹介します。

リクエスト

URL

ご契約後に[APIエンドポイント]をお伝えいたします。

Method

POST

Header

X-JET-DEVICE-ID: [デバイスのIDが送信される]

Body

初期化時

デバイス起動時に送信されます。

{
  "key": "init",
  "data": {
    "input": [
      {
        "pin": 1,
        "state": 1
      },
      {
        "pin": 2,
        "state": 1
      }
    ]
  }
}

状態変化時

接点入力の状態変化検出時に送信されます。

{
  "key": "input",
  "data": {
    "pin": 1,
    "state": 1
  }
}

※key: input固定

※data pin: pin番号

※data state: 1:ON、 0:OFF

BICI-EL2では、検出データをデバイス内でキューとして処理します。キューは、JET IoT（外部システム）からのレスポンスを待って順次処理されます。レスポンスが3秒以内になければレスポンスを待たず次のキューを実行します。キューは最大16個まで保持します。

レスポンス

Status Code

200の場合のみ、端末側へ送信

Body

自由に定義可能（そのまま端末に送信されます）

サンプルソースコード編

デバイスステータス一覧取得（Web API）

「JET IoT登録デバイス一覧情報取得API」を利用したサンプルソースコード（PHP）です。

[API KEY] , [API SECRET] , [APIエンドポイント]を変更してご利用ください。

<?php
$api_key = [API KEY];
$api_secret = [API SECRET];
$url = '[APIエンドポイント]/device';

$context = stream_context_create([
'http' => [
  'method' => 'GET',
  'header' => implode("\r\n", [
    'Content-Type: application/x-www-form-urlencoded',
    'Authorization: Basic '.base64_encode($api_key.':'.$api_secret),
    ]),
  ],
]);

$contents = file_get_contents($url, false, $context);
var_dump($contents);

デバイス接点制御（Web API）

「 BICO-EL2 / BICO-EL8 接点制御API」を利用して、指定デバイスの接点端子を1秒間ONに操作するサンプルソースコード（PHP）です。

[API KEY] , [API SECRET] , [DEVICE ID] , [APIエンドポイント]を変更してご利用ください。

<?php
$api_key = [API KEY];
$api_secret = [API SECRET];
$device_id = [DEVICE ID];
$url = '[APIエンドポイント]/device/'.$device_id;

$context = stream_context_create([
'http' => [
  'method' => 'POST',
  'header' => implode("\r\n", [
    'Content-Type: application/json',
    'Authorization: Basic '.base64_encode($api_key.':'.$api_secret),
    ]),
    'content' => json_encode([[
      "pin": 1,
      "state": 1,
      "time": 1000
    ]]),
  ],
]);

$contents = file_get_contents($url, false, $context);
var_dump($contents);

接点入力検出（Webhook）

BICI-EL2 からの、接点入力の検出通知を受信するソースコード（PHP）です。

<?php
$headers = getallheaders();
$body = file_get_contents('php://input');
$json = json_decode($body, true);
​
if ($json) {
  error_log('JET Device ID: ' . $headers['X-JET-DEVICE-ID']);

  if (@$json['key'] == 'init') {
    error_log('初期データ通知');
    error_log(json_encode(@$json['data']['input']));
    
  } else if (@$json['key'] == 'input') {
    error_log('状態変化通知');
    error_log(json_encode(@$json['data']));
  }
}