各デバイスは、ゲートウェイであれ、サブデバイスであれ、IoT Platform 上ではユニークなデバイスとして動作します。デバイスは、クラウドとの通信時の認証に、固有の証明書を使用できます。ProductKey、DeviceName、DeviceSecret など、各デバイス固有の証明書をインストールする必要があります。Bluetooth デバイスや Zigbee デバイスなどの一部のサブデバイスには、これらの固有の証明書をインストールするための高度な要件があります。認証のために動的登録を選択できます。この場合、ProductKey と DeviceName を提供することで、クラウドにサブデバイスを登録するだけで済みます。

前提条件

ゲートウェイは、デバイス証明書認証を使用して、クラウドに接続していること。

背景情報

サブデバイスの ProductKey および DeviceName は、動的登録の前に IoT Platform に提供する必要があります。ゲートウェイがサブデバイスを登録すると、IoT Platform は、このサブデバイスの DeviceName を検証します。DeviceName が検証されると、IoT Platform が DeviceSecret を発行します。

次の手順を実行します:

手順

  1. Alibaba Cloud アカウントを使用して、IoT Platform コンソールにログインします。
  2. ゲートウェイ SDK を設定します。
    注意
    ゲートウェイは、サブデバイスを登録したり、サブデバイスをオンラインまたはオフラインにしたり、ゲートウェイとそのサブデバイスとの間のトポロジー関係を維持したり、サブデバイスと IoT Platform 間の通信を中継したりすることができます。ゲートウェイデバイスの製造元は、サブデバイスから IoT Platform への接続、サブデバイスからのメッセージの受信、サブデバイストピックへのメッセージのパブリッシュ、IoT Platform のコマンドを取得するためのサブデバイストピックへのサブスクライブ、メッセージのサブデバイスへのルーティングなど、この SDK を使用してアプリケーション機能を開発します。
    1. SDK をダウンロードします。詳しくは、SDK のダウンロードを参照してください。ここでは、例として C SDK を使用します。
    2. Linux 仮想マシン (VM) にログインし、ゲートウェイの一意の証明書を設定します。
    3. この SDK のゲートウェイとサブデバイスの機能を有効にします。

      この SDK は、iotx-sdk-c\src\subdev のコードを使用し、sample\subdev にあるデモに従って設定することができます。

      サンプルコードは、次の部分で構成されています。
      • この SDK を設定するには、subdev の関数を使用してください。
        1. demo_gateway_function(msg_buf, msg_readbuf);
      • subdev_example_api.h ファイルに用意されている関数の使用例 (トピックのカプセル化) を使用して、ゲートウェイのコードを作成します。
        1. demo_thing_function(msg_buf, msg_readbuf);
      • subdev_example_api.h ファイルに用意されている関数の使用例 (トピックのカプセル化) を使用して、デバイスのコードを開発します。
        1. demo_only_one_device(msg_buf, msg_readbuf);
      サブデバイスをゲートウェイに追加します:
      • デバイス証明書認証を有効にするには、サブデバイスを IoT Platform に登録し、ゲートウェイにはサブデバイスの ProductKey、DeviceName、および DeviceSecret の値を設定する必要があります。次に、ゲートウェイは IOT_Thing_Register/IOT_Subdevice_Register を使用してサブデバイスを登録します (登録タイプ: IOTX_Thing_REGISTER_TYPE_STATIC)。
      • 動的認証を有効にするには、サブデバイスを IoT Platform に登録する必要があります。ゲートウェイは、IOT_Thing_Register/IOT_Subdevice_Register を使用してサブデバイスを動的に登録します (登録タイプ: IOTX_Thing_REGISTER_TYPE_DYNAMIC)。

        動的登録の詳細については、demo_gateway_function を参照してください。

      • example/subdev_example_api.c/.h ファイルに用意されている関数は、プロパティ、イベント、およびサービスのトピックをカプセル化します。これらの関数は、対応するトピックを操作せずに直接使用できます。
      • ゲートウェイおよびサブデバイスの機能を指定するには、make.settings で FEATURE_SUBDEVICE_ENABLED = y を定義する必要があります。

        ゲートウェイまたはサブデバイスの機能を指定するには、make.settings で FEATURE_SUBDEVICE_STATUS = subdevice を定義する必要があります。

  3. ゲートウェイは、IoT Platform に対して MQTT (Message Queuing Telemetry Transport) 接続を確立します。
  4. サブデバイスを登録します。

    ゲートウェイはサブデバイスの ProductKey および DeviceName を取得し、動的登録を使用して IoT Platform から DeviceSecret を取得します。MAC (Media Access Control) アドレスなどの GUID (Globally Unique Identifier) を DeviceDame として使用することを推奨します。

    • リクエストトピック: /sys/{gw_productKey}/{gw_deviceName}/thing/sub/register

      リクエスト形式:

      1. {"id": 123, "version": "1.0", "params": [{"deviceName": "deviceName1234", "productKey": "1234556554"}], "method": "thing.sub.register"}
    • レスポンストピック: /sys/{gw_productKey}/{gw_deviceName}/thing/sub/register_reply

      レスポンス形式:

      1. {"id": 123, "code": 200, "data": [{"iotId": "12344", "productKey": "xxx", "deviceName": "xxx", "deviceSecret": "xxx"}]}
    • JSON オブジェクトの ProductKey および DeviceName 値は、ゲートウェイの ProductKey および DeviceName 値と同じにすることはできません。
    • ゲートウェイとサブデバイスは、Quality of Service 0 (QoS 0) ベースのメッセージを送信します。
    • 対応する関数は、この SDK に含まれる IOT_Subdevice_Register です。この関数では、register_type は静的登録と動的登録をサポートします。この関数の使い方と署名計算の方法の詳細については、sample\subdev\subdev-example.c の例を参照してください。
    • register_type を OTX_SUBDEV_REGISTER_TYPE_DYNAMIC に設定した場合、この関数の使用後、ゲートウェイにオフラインサブデバイスが追加されたことが、コンソールで確認できます。
    • register_type を IOTX_SUBDEV_REGISTER_TYPE_DYNAMIC に設定した場合、この関数を 1 回呼び出すだけです。この関数を再度呼び出すと、IoT Platform は、デバイスがすでに存在することを報告します。
    • SDK の現在のバージョンには制限があります。システムは、動的登録によって生成された device_secret 値をデバイスのグローバル変数に保存します。したがって、device_secret の値は永続的ではありません。このデバイスを再起動すると、DeviceSecret が失われます。

      この関数を使用する必要がある場合は、iotx-sdk-c\src\subdev\iotx_subdev_api.c ファイルの iotx_subdevice_parse_register_reply を修正して、でデータ永続性をサポートするモジュールに device_secret を書き込みます。

    • register_type を IOTX_SUBDEV_REGISTER_TYPE_STATIC に設定した場合、この関数の使用後、既存のサブデバイスがオフラインサブデバイスとしてゲートウェイに追加されたことがコンソールで確認できます。
      1. /**
      2. * @brief Device register
      3. * This function is used to register a device and add topology.
      4. *
      5. * @param handle pointer to specify the gateway construction.
      6. * @param register type.
      7. * IOTX_SUBDEV_REGISTER_TYPE_STATIC
      8. * IOTX_SUBDEV_REGISTER_TYPE_DYNAMIC
      9. * @param product key.
      10. * @param device name.
      11. * @param timestamp. [if type = dynamic, must be NULL ]
      12. * @param client_id. [if type = dynamic, must be NULL ]
      13. * @param sign. [if type = dynamic, must be NULL ]
      14. * @param sign_method.
      15. * IOTX_SUBDEV_SIGN_METHOD_TYPE_SHA
      16. * IOTX_SUBDEV_SIGN_METHOD_TYPE_MD5
      17. *
      18. * @return 0, Logout success; -1, Logout fail.
      19. */
      20. int IOT_Subdevice_Register(void* handle,
      21. iotx_subdev_register_types_t type,
      22. const char* product_key,
      23. const char* device_name,
      24. char* timestamp,
      25. char* client_id,
      26. char* sign,
      27. iotx_subdev_sign_method_types_t sign_type);
  5. クラウド内のゲートウェイとサブデバイス間のトポロジー関係を構築します。
    • トポロジー関係を追加します。
      • リクエストトピック: /sys/{gw_productKey}/{gw_deviceName}/thing/topo/add
        リクエスト形式:
        1. {
        2. "id": "123",
        3. "version": "1.0",
        4. "params": [{
        5. "deviceName": "deviceName1234",
        6. "productKey": "1234556554",
        7. "sign": "",
        8. "signmethod": "hmacSha1", //Supports hmacSha1, hmacSha256, and hmacMd5.
        9. "timestamp": "xxxx",
        10. "clientId": "xxx" //Indicates a local identifier, and can be identical with productKey&deviceName.
        11. }],
        12. "method": "thing.topo.add"
        13. }
      • レスポンストピック: /sys/{gw_productKey}/{gw_deviceName}/thing/topo/add_reply
        リクエスト形式:
        1. {
        2. "id": "123",
        3. "code": 200,
        4. "data": {}
        5. }
      • JSON オブジェクトの ProductKey および DeviceName 値は、ゲートウェイの ProductKey および DeviceName 値と同じにすることはできません。
      • ゲートウェイとサブデバイスは、QoS 0 ベースのメッセージを送信します。
      • IOT_Subdevice_Register 関数は、SDK のこの機能をカプセル化しています。他の関数を使用する必要はありません。
    • トポロジー関係を削除します。
      • リクエストトピック: /sys/{gw_productKey}/{gw_deviceName}/thing/topo/delete
        リクエスト形式:
        1. {
        2. "id": 123,
        3. "version": "1.0",
        4. "params": [{
        5. "deviceName": "deviceName1234",
        6. "productKey": "1234556554"
        7. }],
        8. "method": "thing.topo.delete"
        9. }
      • レスポンストピック: /sys/{gw_productKey}/{gw_deviceName}/thing/topo/delete_reply
        1. {
        2. "id": 123,
        3. "code": 200,
        4. "data": {}
        5. }
      • JSON オブジェクトの ProductKey および DeviceName 値は、ゲートウェイの ProductKey および DeviceName と同じにすることはできません。
      • ゲートウェイとサブデバイスは、QoS 0 ベースのメッセージを送信します。
      • IOT_Subdevice_Unregister 関数は、SDK のこの機能をカプセル化しています。他の関数を使用する必要はありません。
    • トポロジー関係を取得します。
      • リクエストトピック: /sys/{gw_productKey}/{gw_deviceName}/thing/topo/get

        リクエスト形式:

        1. {
        2. "id": 123,
        3. "version": "1.0",
        4. "params": {},
        5. "method": "thing.topo.get"
        6. }
      • レスポンストピック: /sys/{gw_productKey}/{gw_deviceName}/thing/topo/get_reply
        1. {
        2. "id": 123,
        3. "code": 200,
        4. "data": [{
        5. "deviceName": "deviceName1234",
        6. "productKey": "1234556554"
        7. }]
        8. }
      • JSON オブジェクトの ProductKey および DeviceName 値は、ゲートウェイの ProductKey および DeviceName と同じにすることはできません。
      • ゲートウェイとサブデバイスは、QoS 0 ベースのメッセージを送信します。
      • 対応する関数は、この SDK の IOT_Gateway_Get_TOPO です。
      • この関数を使用すれば、このゲートウェイのすべてのサブデバイスについての情報 (ProductKey、DeviceName、および DeviceSecret の証明書を含む) を取得できます。get_topo_reply のレスポンスパラメーターは JSON 形式です。このレスポンスは、解析が必要です。
        1. /**
        2. * @brief Gateway get topo
        3. * This function is used to publish a packet with topo/get topic, and wait for the reply (with TOPO_GET_REPLY topic).
        4. *
        5. * @param handle pointer to specify the Gateway.
        6. * @param get_topo_reply.
        7. * @param length [in/out]. in -- get_topo_reply buffer length, out -- reply length
        8. *
        9. * @return 0, logout success; -1, logout failed.
        10. */
        11. int IOT_Gateway_Get_TOPO(void* handle,
        12. char* get_topo_reply,
        13. uint32_t* length);
  6. サブデバイスを IoT Platform に接続します。
    • リクエストトピック: /ext/session/{gw_productKey}/{gw_deviceName}/combine/login

      リクエスト形式:

      1. {
      2. "id": "123",
      3. "params": {
      4. "productKey": "xxxxx", // Sub-device ProductKey
      5. "deviceName": "xxxx", // Sub-device DeviceName
      6. "clientId": "xxxx",
      7. "timestamp": "xxxx",
      8. "signMethod": "hmacmd5 or hmacsha1 or hmacsha256",
      9. "sign": "xxxxx", //Sub-device signature
      10. "cleanSession": "true or false" // If this parameter is set to true, the system clears all QoS 1- or 2-based messages missed by the offline sub-device.
      11. }
      12. }
      13. // Sub-devices with ProductKey, DeviceName and DeviceSecret follow the same signature rules as the gateway.
      14. sign = hmac_md5(deviceSecret, clientId123deviceNametestproductKey123timestamp123)
    • レスポンストピック: /ext/session/{gw_productKey}/{gw_deviceName}/combine/login_reply
      レスポンス形式:
      1. {
      2. "id": "123",
      3. "code": 200,
      4. "message": "success"
      5. }
    • JSON オブジェクトの ProductKey および DeviceName 値は、ゲートウェイの ProductKey および DeviceName と同じにすることはできません。
    • ゲートウェイとサブデバイスは、QoS 0 ベースのメッセージを送信します。
    • 対応する関数は、この SDK に含まれる IOT_Subdevice_Login です。この関数の使用方法の詳細については、sample\subdev\subdev-example.c を参照してください。
    • この関数の使用後、サブデバイスのオンライン状態がコンソールで確認できます。
    1. /**
    2. * @brief Subdevice login
    3. * This function is used to publish a packet with the LOGIN topic, wait for the reply (with
    4. * LOGIN_REPLY topic), and then subscribe to some subdevice topics.
    5. *
    6. * @param handle pointer to specify the Gateway.
    7. * @param product key.
    8. * @param device name.
    9. * @param timestamp. [If aster_type = dynamic, must be null]
    10. * @param client_id. [if register_type = dynamic, must be NULL ]
    11. * @param sign. [if register_type = dynamic, must be NULL ]
    12. * @param sign method, HmacSha1 or HmacMd5.
    13. * @param clean session, true or false.
    14. *
    15. * @return 0, login success; -1, login failed.
    16. */
    17. int IOT_Subdevice_Login(void* handle,
    18. const char* product_key,
    19. const char* device_name,
    20. const char* timestamp,
    21. const char* client_id,
    22. const char* sign,
    23. iotx_subdev_sign_method_types_t sign_method_type,
    24. iotx_subdev_clean_session_types_t clean_session_type);
  7. サブデバイスと情報交換します。
    • IoT Platform で指定されたトピックを、/${productKey}/${deviceName}/xxx の形式で使用することも、/sys/${productKey}/${deviceName}/thing/xxx の形式で使用することもできます。
    • ゲートウェイは、サブデバイスのトピックにデータをパブリッシュします。トピックの中で /${productKey}/${deviceName}/ は、サブデバイスの ProductKey および DeviceName に対応しています。
    • MQTT ペイロードの形式に制限はありません。
    • この SDK は、メッセージのサブスクライブおよびパブリッシュのために IOT_Gateway_Subscribe、IOT_Gateway_Unsubscribe、および IOT_Gateway_Publish の 3 つの関数を提供しています。この関数の使用方法の詳細については、sample\subdev\subdev-example.c を参照してください。
    1. /**
    2. * @brief Gateway Subscribe
    3. * This function is used to subscribe to some topics.
    4. *
    5. * @param handle pointer to specify the Gateway.
    6. * @param topic list.
    7. * @param QoS.
    8. * @param function to receive data.
    9. * @param topic_handle_func's userdata.
    10. *
    11. * @return 0, Subscribe success; -1, Subscribe fail.
    12. */
    13. int IOT_Gateway_Subscribe(void* handle,
    14. const char* topic_filter,
    15. int qos,
    16. iotx_subdev_event_handle_func_fpt topic_handle_func,
    17. void* pcontext);
    18. /**
    19. * @brief Gateway Unsubscribe
    20. * This function is used to unsubscribe from some topics.
    21. *
    22. * @param handle pointer to specify the Gateway.
    23. * @param topic list.
    24. *
    25. * @return 0, Unsubscribe success; -1, Unsubscribe fail.
    26. */
    27. int IOT_Gateway_Unsubscribe(void* handle, const char* topic_filter);
    28. /**
    29. * @brief Gateway Publish
    30. * This function is used to publish some packets.
    31. *
    32. * @param handle pointer to specify the Gateway.
    33. * @param topic.
    34. * @param mqtt packet.
    35. *
    36. * @return 0, Publish success; -1, Publish fail.
    37. */
    38. int IOT_Gateway_Publish(void* handle,
    39. const char* topic_name,
    40. iotx_mqtt_topic_info_pt topic_msg);
  8. IoT Platform からサブデバイスを切断します。
    • リクエストトピック: /ext/session/{gw_productKey}/{gw_deviceName}/combine/logout
      リクエスト形式:
      1. {
      2. "id": 123,
      3. "params": {
      4. "productKey": "xxxxx", //ProductKey of the sub-device
      5. "deviceName": "xxxxx" //DeviceName of the sub-device
      6. }
      7. }
    • レスポンストピック: /ext/session/{gw_productKey}/{gw_deviceName}/combine/logout_reply
      1. {
      2. "id": "123",
      3. "code": 200,
      4. "message": "success"
      5. }
    • JSON オブジェクトの ProductKey および DeviceName 値は、ゲートウェイの ProductKey および DeviceName 値と同じにすることはできません。
    • ゲートウェイとサブデバイスは、QoS 0 ベースのメッセージを送信します。
    • 対応する関数は、この SDK に含まれる IOT_Subdevice_Logout です。この関数の使用方法の詳細については、sample\subdev\subdev-example.c を参照してください。
    • この関数の使用後、サブデバイスのオフライン状態がコンソールで確認できます。
    1. /**
    2. * @brief Subdevice logout
    3. * This function is used to unsubscribe from some subdevice topics, publish a packet with the
    4. * LOGOUT topic, and then wait for the reply (with LOGOUT_REPLY topic).
    5. *
    6. * @param handle pointer to specify the Gateway.
    7. * @param product key.
    8. * @param device name.
    9. *
    10. * @return 0, logout success; -1, logout failed.
    11. */
    12. int IOT_Subdevice_Logout(void* handle,
    13. const char* product_key,
    14. const char* device_name);
  9. サブデバイスの登録を動的に解除します。
    • リクエストトピック: /sys/{gw_productKey}/{gw_deviceName}/thing/sub/unregister
      リクエスト形式:
      1. {
      2. "id": 123,
      3. "version": "1.0",
      4. "params": [{
      5. "deviceName": "deviceName1234",
      6. "productKey": "1234556554"
      7. }],
      8. "method": "thing.sub.unregister"
      9. }
    • レスポンストピック: /sys/{gw_productKey}/{gw_deviceName}/thing/sub/unregister_reply
      1. {
      2. "id": 123,
      3. "code": 200,
      4. "data": {}
      5. }
    • JSON オブジェクトの ProductKey および DeviceName 値は、ゲートウェイの ProductKey および DeviceName と同じにすることはできません。
    • ゲートウェイとサブデバイスは、QoS 0 ベースのメッセージを送信します。
    • 対応する関数は、この SDK での IOT_Subdevice_Unregister です。この関数の使用方法の詳細については、sample\subdev\subdev-example.c を参照してください。
    • サブデバイスは破棄され、この関数を呼び出した後は使用できません。サブデバイスが必要な場合は、この関数を呼び出さないでください。
    1. /**
    2. * @brief Device unregister
    3. * This function is used to delete the topological relationship and unregister the device.
    4. * The device must dynamically register again if you want to use this device after unregistration.
    5. *
    6. * @param handle pointer to specify the gateway construction.
    7. * @param product key.
    8. * @param device name.
    9. *
    10. * @return 0, unregister success;-1, unregister fail.
    11. */
    12. int IOT_Subdevice_Unregister(void* handle,
    13. const char* product_key,
    14. const char* device_name);
    注意
    • gw_productKey は、ゲートウェイの ProductKey を示します。
    • gw_deviceName は、ゲートウェイの DeviceName を示します。

    この SDK のその他の関数の詳細については、subdev-example のコードを参照してください。