SORACOM Users

SORACOM Inventory : 機能の説明

SORACOM Inventory で使用する用語

デバイス ID(deviceId) - SORACOM Inventory においてデバイスを一意に識別する ID です。後述の Bootstrap の際に SORACOM Inventory より払い出しが行われます。

endpoint - LwM2M の仕様においてデバイスを一意に識別する ID であり、前述のデバイス ID と 1:1 の関係を持ちます。Bootstrap 時にデバイス側から任意の endpoint を申告します。endpoint はオペレータ(SORACOM アカウントのこと)ごとにユニークな識別子として取り扱われます。SORACOM Inventory は、Bootstrap 時にデバイスから申告された endpoint が未知のものであった場合、新規にデバイス ID の払い出しを行い、処理を進めます。一方、既知の endpoint であった場合、同一のデバイスとして取り扱い、処理を進めます。

Resource model - Inventory ではデバイス上の情報を「Resource Model(リソースモデル)」という形式で管理しています。Resource Model は LwM2M で規定されており、Object、Object Instance、Resource のツリー構造になっています。各要素には番号が割り当てられ、/3/0/0 のようになります。

Agent - Inventory での管理対象のデバイスで動作する実行可能なバイナリもしくは SDK です。管理対象のデバイスは当 Agent が動作していることが必須となります。

Bootstrap - Inventory を利用するにあたり、最初に行われるデバイス登録と鍵交換です。Bootstrap が完了すると、デバイスが Inventory に登録され、ユーザーコンソールのデバイス一覧に表示されるようになります。また、Wifi や有線などのインターネット経由でデバイス管理(デバイス情報の読み書き、実行)が可能になります。

Inventory の仕組みと構成

Inventory では、デバイス管理の仕組みとして OMA DM LwM2M(以下、LwM2M)を利用します。

コアとなるコンポーネントは、以下の 3 つです。

Bootstrap Server は主にデバイスとの接続確立のための認証情報の確認や鍵の交換などの機能を提供します。 Device Management Server は Inventory のサーバーコンポーネントとして、主要な機能の多くを提供するコンポーネントです。 Agent は実行可能なバイナリもしくは SDK として提供され、デバイス上で Agent として動作し、Bootstrap Server、Device Management Server との通信します。

Inventory を利用するにあたって、最初に行われる処理は SORACOM プラットフォームへのデバイス登録と鍵交換(bootstrap)です。認証を行うために IoT SIM で通信を行い、デバイス上の Agent で bootstrap を実行します。このとき、Agent は Bootstrap Server と通信を行い、デバイスの情報を SORACOM のプラットフォームに登録すると共に今後の通信のために鍵交換を行います。例えばソラコムより配布している C 言語版のクライアントでは以下のような操作となります。

$ lwm2mclient -n $(hostname) -b -h bootstrap.soracom.io -p 5683 -4 -c

bootstrap が完了すると、-nで指定した endpoint 名(LwM2M の仕様上、デバイスをユニークに識別する ID)に対してd-xxxxxxxxxxxxxxxxxxxxという SORACOM Inventory のデバイス ID が払い出され、ユーザーコンソールのデバイス一覧に表示されるようになります。(クライアントによっては bootstrap 実行時に自動で endpoint 名を生成するものもあります。)

Inventory に登録済みのデバイスは、ユーザーコンソールや API を使ってデバイス上のデータの読み書き(Read, Write)をしたり、デバイス側で値に変化があったら通知を受けたり(Observe)、コマンドを実行(Execute)したりするために、Agent を通じて Device Management Server と通信を行います。最初に行った bootstrap の段階でデバイスの認証や鍵交換しているため、bootstrap 済みのデバイスは WiFi などで通信していても Inventory を使ってデバイスをリモート管理できます。

リソースモデル

Inventory ではデバイス上の情報を「Resource Model」という形式で管理しています。リソースモデルは LwM2M で規定されており、オブジェクト(Object)、オブジェクトインスタンス(Object Instance)、リソース(Resource)のツリー構造になっています。各要素には番号が割り当てられ、 /3/0/0 のように表現できます。

例えば /3/0/0 はデバイスの製造元(Manufacturer)を表すリソースであり、Agent はサーバーからの Read リクエストに対して、自分の製造元情報を返します。また、 /3/0/4 は (Reboot) を表します。この Execute リクエストが Device Management Server から送信されると、デバイス自身の再起動が行われます。

定義済みのリソースモデルは、OMA LightweightM2M (LwM2M) Object and Resource Registryから確認できます。

なお、LwM2M では、リソースへのオペレーション呼び出しとレスポンスが定義されています。呼び出されたオペレーションの動作は Agent 側で実装します。例えば、先に挙げた例の /3/0/0(製造元情報)への Read に対して、どのように製造元情報を取得するかについては Agent の実装に任されています。 ソラコムでは、参照実装として以下の Agent を提供しています。

カスタムオブジェクト

LwM2M Registryに多くのリソースが定義されていますが、独自に定義できます。(カスタムオブジェクト) カスタムオブジェクトは XML, JSON で定義します。 以下は、 ObjectID 30000 で定義した例となります。

カスタムオブジェクト定義の例(XML)

<?xml version="1.0" encoding="UTF-8"?>
<LWM2M xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://openmobilealliance.org/tech/profiles/LWM2M.xsd">
    <Object ObjectType="MODefinition">
        <Name>Custom Model</Name>
        <Description1>Custom model</Description1>
        <ObjectID>30000</ObjectID>
        <ObjectURN>urn:oma:lwm2m:oma:30000</ObjectURN>
        <MultipleInstances>Single</MultipleInstances>
        <Mandatory>Optional</Mandatory>
        <Resources>
            <Item ID="0">
                <Name>CurrentX</Name>
                <Operations>R</Operations>
                <MultipleInstances>Single</MultipleInstances>
                <Mandatory>Mandatory</Mandatory>
                <Type>Float</Type>
                <RangeEnumeration />
                <Units>m</Units>
                <Description>Current location in X.</Description>
            </Item>
            <Item ID="1">
                <Name>TargetX</Name>
                <Operations>RW</Operations>
                <MultipleInstances>Single</MultipleInstances>
                <Mandatory>Mandatory</Mandatory>
                <Type>Float</Type>
                <RangeEnumeration />
                <Units>m</Units>
                <Description>Target location in X.</Description>
            </Item>
            <Item ID="2">
                <Name>Execute Command</Name>
                <Operations>E</Operations>
                <MultipleInstances>Single</MultipleInstances>
                <Mandatory>Mandatory</Mandatory>
                <Type />
                <RangeEnumeration />
                <Units />
                <Description>Execute command.</Description>
            </Item>
        </Resources>
        <Description2 />
    </Object>
</LWM2M>

当定義をコンソールから保存することで、ユーザーコンソールからカスタムオブジェクト、リソース名を表示できます。 カスタムオブジェクトを定義する場合、これに対応したクライアントエージェントの実装も必要となります。

クライアントエージェントの実装については、エージェントの Readme を参照ください。

尚 ObjectID 30099, 30100, 30101, 30110, 30111 を SORACOM Mosaic で利用しています。

SORACOM アプリケーションサービスを利用したクラウド連携

デバイスグループの設定により、SORACOM Beam、Funnel、Harvest を利用できます。 デバイスがデバイスグループに所属している必要があります。また、Observe した属性が各サービスに転送される対象になります。

デバイスグループ設定

Beam の場合のフォーマット

Beam では、HTTP もしくは HTTPS で転送されます。 フォーマットは以下のとおりです。

Header

{
  "host": "xxxxxxx.com",
  "connection": "close",
  "content-type": "application/json",
  "x-soracom-timestamp": "1524554877520",
  "x-soracom-device-id": "d-vlqqxxxxxxxxxxxxxxx",
  "x-soracom-operator-id": "OP0000000000",
  "transfer-encoding": "chunked",
  "x-request-id": "feexxxxxxxxxxx-xxxxxxxxxx",
  "x-forwarded-for": "13.112.xxx.xxx",
  "x-forwarded-proto": "https",
  "x-forwarded-port": "443",
  "via": "1.1 vegur",
  "connect-time": "0",
  "x-request-start": "1524554879323",
  "total-route-time": "0"
}

Body

{
  "deviceId": "d-vlqqxxxxxxxxxxxxxxx",
  "path": "/3/0",
  "lastModifiedTime": 1524554897553,
  "resources": {
    "13": {
      "name": "Current Time",
      "value": "Apr 24, 2018 7:28:17 AM"
    }
  }
}

Funnel の場合のフォーマット

Resource を Observe した時は以下の通りとなります。(Resource1 つずつ送信されます。)

/3/0/13 を Observe した場合の例

 {
   "operatorId": "OP0000000000",
   "timestamp": 1524551762283,
   "destination": {
     "resourceUrl": "https://xxxxx.us-west-2.amazonaws.com/my-kinesis-firehose",
     "service": "firehose",
     "provider": "aws"
   },
   "credentialsId": "aws-credentials",
   "payloads": {
     "path": "/3/0",
     "lastModifiedTime": "1524551761992",
     "deviceId": "d-vlqqxxxxxxxxxxxxxx",
     "resources": {
       "13": {
         "name": "Current Time",
         "value": "Apr 24, 2018 6:36:01 AM"
       }
     }
   },
   "sourceProtocol": "device",
   "deviceId": "d-vlqqxxxxxxxxxxxxxx"
 }

ObjectInstance を Observe した場合は、以下のようなフォーマットで送信されます。

/6/0 を Observe した場合の例

{
   "operatorId": "OP0000000000",
   "timestamp": 1524551772514,
   "destination": {
     "resourceUrl": "https://xxxxx.us-west-2.amazonaws.com/my-kinesis-firehose",
     "service": "firehose",
     "provider": "aws"
   },
   "credentialsId": "aws-credentials",
   "payloads": {
     "path": "/6/0",
     "lastModifiedTime": "1524551771914",
     "deviceId": "d-vlqqxxxxxxxxxxxxxx",
     "resources": {
       "1": {
         "name": "Longitude",
         "value": 65.1006164550781
       },
       "0": {
         "name": "Latitude",
         "value": 56.1010437011719
       },
       "5": {
         "name": "Timestamp",
         "value": "Apr 24, 2018 6:36:11 AM"
       }
     }
   },
   "sourceProtocol": "device",
   "deviceId": "d-vlqqxxxxxxxxxxxxxx"
}

Harvest の場合のフォーマット

Harvest の場合、リソース名(パス)、値が以下のように送信されます。

{
    "Example resource (/3303/0/5757)": 123,
     "Example resource2 (/3303/0/5758)": 456
}
pagetop