This documentation is for WSO2 IoT Server 3.1.0. View the documentation for the latest release.
Creating a New Device Type via APIs - IoT Server 3.1.0 - WSO2 Documentation
                                                                                                                                                                                                                                                                                                                                                                                                                                                   
||
Skip to end of metadata
Go to start of metadata

The APIs in WSO2 IoT Server are extended as JAX-RS APIs. It allows you to create a device type via APIs. A device type author can consume these APIs to write their own developer friendly APIs and deploy it on an external server or they can directly use the exposed APIs.

There are two types of APIs that are exposed.

Device management APIs

Device management APIs are used by the user or application to communicate with the device type or the server. These APIs are used to:

Device agent APIs

Device agent APIs are used by the device to communicate with the server. These APIs are used to:

In this tutorial, you are going to create a new device type using the WSO2 IoT Server APIs.

 

Before you begin

You need to start the WSO2 IoT Server core and analytics profiles.

cd <IOTS_HOME>/bin  
------Linux/Mac OS/Solaris ----------
./iot-server.sh
./analytics.sh
  
-----Windows-----------
iot-server.bat
analytics.bat

Let's get started!

Creating a new device type

Follow the steps given below to create a new device type via the REST APIs:

  1. Obtain the access token to create a new device type:

     Click here to know more about how to obtain the access token.
    1. Encode the client credentials as follows:

      echo -n <USERNAME>:<PASSWORD> | base64

      Example:

      echo -n admin:admin | base64

      The response:

      YWRtaW46YWRtaW4=
      powershell "[convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(\"<USERNAME>:<PASSWORD>\"))

      Example:

      powershell "[convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(\"admin:admin\"))

      The response:

      YWRtaW46YWRtaW4=
    2. Generate the Client ID and the Secret ID.

      curl -k -X POST https://<IOTS_HOST>:8243/api-application-registration/register -H 'authorization: Basic <BASE 64 ENCODED USERNAME:PASSWORD>' -H 'content-type: application/json' -d '{ "applicationName":"appName", "tags":["device_management"]}'
      • The base 64 encoded USERNAME :PASSWORD must be the username and password that you use to sign in to WSO2 IoT Server. Else, you are not able to get the client_id and client_secret as the response.
      • The APIs that fall under different categories are grouped using tags. You subscribe to the API group by the tag you define in the cURL command.
        For example, the device_management tag is used to group all the device management APIs including those that belong to the device type APIs.
        To know about the available tags and the APIs grouped under each tag, navigate to the API Cloud Store, click on the available tags in the left side panel.

      The response:

      {"client_secret":"xxxxxxxxxxxxxxxxxxxx","client_id":"xxxxxxxxxxxxxxxxxxxx"}
      curl -k -X POST https://localhost:8243/api-application-registration/register -H 'authorization: Basic YWRtaW46YWRtaW4=' -H 'content-type: application/json' -d '{ "applicationName":"appName", "tags":["device_management"]}'

      The response:

      {"client_secret":"nboXPDTm9S1cK1yPbhAvJenbbzsa","client_id":"Ad9iV9VJ9EwyujpmLVzCi59rX8Aa"}
    3. Encode the client credentials as follows:

      echo -n <CLIENT_ID>:<CLIENT_SECRET> | base64

      Example:

      echo -n f8fc0aI14DPrQ_DwkpSau1LGdwAa:p8g_rFXtbPjl5pGMJe4bNd5fwSEa | base64

      The response:

      cDhnX3JGWHRiUGpsNXBHTUplNGJOZDVmd1NFYTpmOGZjMGFJMTREUHJRX0R3a3BTYXUxTEdkd0Fh
      powershell "[convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(\"<CLIENT_ID>:<CLIENT_SECRET>\"))

      Example:

      powershell "[convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(\"f8fc0aI14DPrQ_DwkpSau1LGdwAa:p8g_rFXtbPjl5pGMJe4bNd5fwSEa\"))

      The response:

      cDhnX3JGWHRiUGpsNXBHTUplNGJOZDVmd1NFYTpmOGZjMGFJMTREUHJRX0R3a3BTYXUxTEdkd0Fh
    4. Generate the access token using the following command:

      curl -k -d "grant_type=password&username=<USERNAME>&password=<PASSWORD>&scope=perm:admin:device-type perm:device-types:events perm:device-types:events:view perm:device-types:types perm:devices:operations" -H "Authorization: Basic <BASE 64 ENCODEd CLIENT_ID:CLIENT_SECRET>" -H "Content-Type: application/x-www-form-urlencoded" https://localhost:8243/token

      The permission to invoke the APIs are assigned via the scope defined in each API. You can define all the scopes to generate an access token that can invoke all the APIs or you can generate an access token that only has the required scope to invoke a specific API. In this scenario let's only use the APIs required to create a new device type.

      Generate the access token for the user having the user name admin and password admin, and using the default WSO2 IoT Server host, which is localhost. In this example, we are generating an access token that has access to all the device management scopes.

      curl -k -d "grant_type=password&username=admin&password=admin&scope=perm:admin:device-type perm:device-types:events perm:device-types:events:view perm:device-types:types perm:devices:operations" -H "Authorization: Basic bkl1clAwZkNZOFFtWEVQZzhjNm12OFRHZWJJYTowOG1tdXRuNW9YaEZMTzNPR2NWcnpKeUd6NGNh" -H "Content-Type: application/x-www-form-urlencoded" https://localhost:8243/token

      The response:

      {"access_token":"498ef8f9-b6a9-3859-8228-1cd4c272f286","refresh_token":"63552c76-ae4f-3fcc-be0d-fd0b074bdc2b","scope":"perm:admin:device-type perm:device-types:events perm:device-types:events:view perm:device-types:types perm:devices:operations","token_type":"Bearer","expires_in":3600}

      The access token you generated expires in an hour. After it expires you can generate a new access token using the refresh token.

  2. Create a device type:

    curl -X POST http://localhost:8280/api/device-mgt/v1.0/admin/device-types -H 'authorization: Bearer <ACCESS_TOKEN>' -H 'content-type: application/json' -d '{"name": "<DEVICE_NAME>","deviceTypeMetaDefinition": {"properties": ["<DEVICE_ATTRIBUTE>", "<DEVICE_ATTRIBUTE>"],"features": [{"code": "<FEAUTRE_CODE>","name": "<FEATURE_NAME>","description": "<FEATURE_DESCRIPTION>"}],"pushNotificationConfig": {"type": "<TRANSPORT_TYPE>","scheduled": false},"description": "<DEVICE_TYPE_DESCRIPTION>", :initialOperationConfig": {"operations": ["<THE_OPERATION_TO_BE_PUSHED_AT_DEVICE_ENROLLMENT>"]}}}'

    To check out the entire cURL command, you need to scroll to the end of the command or you can double click the code, copy it, and paste it into a text editor to view it.

    <DEVICE_NAME>The name of the device.

    <DEVICE_ATTRIBUTE>

    Define the attributes unique to the device. You can add more than one attribute using comma separated values. For example, a fire alarm will be placed in a specific building and a specific floor. Then the building_ID and the floor_ID will become its attributes.

    Let's look at another example. If your device type is a car, the make and the year of manufacture will be the device's attributes.

    featuresFeatures refer to the operations or functions your device can perform. For example, if your device is a fire alarm, it needs to ring when the temperature rises too high.

    <FEATURE_CODE>

    Provide the code to trigger the device operation. For example, ring is used as the code to trigger the fire-alert operation.
    <FEATURE_NAME>Provide a name for the device operation.This name is used to identify the device operation. 
    As per the above example, the feature name is fire-alert.
    <FEATURE_DESCRIPTION>Provide a description for the device operation.
    <TRANSPORT_TYPE>The communication method the server needs to use to send messages to the device.
    • If you select NONE, there will be no transport method implemented for the server to communicate with the device.
    • If you select MQTT, the MQTT transport is extended for the server to communicate with your device.
    <DEVICE_TYPE_DESCRIPTION>A small introduction about your device type. It should not be very long.
    <THE_OPERATION_TO_BE_PUSHED_
    AT_DEVICE_ENROLLMENT>
    InitialOperationConfig allows the author to push operation to the device after the device is enrolled with WSO2 IoT Server. For example, restarting the device after enrolling the device or ringing the device soon as it's enrolled with WSO2 IoT Server.

    Creating a new device type named fire alarm, having the buildingID and floorID as unique properties, and the operation to control the bulb.

    curl -X POST http://localhost:8280/api/device-mgt/v1.0/admin/device-types -H 'authorization: Bearer 77d11b5e-2363–3c99-afb3-c0381600b977' -H 'content-type: application/json' -d '{"name": "firealarm","deviceTypeMetaDefinition": {"properties": ["buildingId", "floorId"],"features": [{"code": "bulb","name": "control bulb","description": "on the bulb"},{"code": "ring","name": "ring","description": "this can be used test"}],"pushNotificationConfig": {"type": "MQTT","scheduled": false},"description": "this is a new remote control firealarm", "initialOperationConfig": {"operations": ["bulb"]}}}'

    To chek out the entire cURL command, you need to scroll to the end of the command or you can double click the code, copy it, and paste it into a text editor to view it.

  3. Create the event stream to gather the sensor readings or data from the device.

    curl -X POST http://localhost:8280/api/device-mgt/v1.0/events/firealarm -H 'authorization: Bearer <ACCESS_TOKEN>' -H 'content-type: application/json' -d '{"eventAttributes": {"attributes": [{"name": "<EVENT_NAME>","type": "<EVENT_TYPE>"}]},"transport": "<TRANSPORT_TYPE>"}'

    To check out the entire cURL command, you need to scroll to the end of the command or you can double click the code, copy it, and paste it into a text editor to view it.

    Let's get to know the attributes used in the cURL command:

    <ACCESS_TOKEN>The access token you generated in step 1.

    ancheventAttributes

    Define the attributed of the event stream that needs to be created to gather the data from the device. You can add more than one attribute as comma separated arrays.
    <EVENT_NAME>The name of the event stream that needs to be created.
    <EVENT_TYPE>The type of the data that is gathered by the event stream. Example: INT, STRING, FLOAT and more.
    <TRANSPORT_TYPE>The transport that needs be used by the server to communicate with the device.

    Creating an event stream to gather the temperature and the status of the device. In this sample, the device is configured to communicate with the server using MQTT.

    curl -X POST http://localhost:8280/api/device-mgt/v1.0/events/firealarm -H 'authorization: Bearer 77d11b5e-2363–3c99-afb3-c0381600b977' -H 'content-type: application/json' -d '{"eventAttributes": {"attributes": [{"name": "temperature","type": "DOUBLE"},{"name": "status","type": "STRING"},{"name": "humidity","type": "FLOAT"}]},"transport": "MQTT"}'

    To check out the entire cURL command, you need to scroll to the end of the command or you can double click the code, copy it, and paste it into a text editor to view it.

Enrolling a new device

Follow the steps given below to enroll the fire alarm using the REST APIs.

  1. Obtain the access token to enroll a new device.

     Click here to know more about how to obtain the access token.
    1. Encode the client credentials as follows:

      echo -n <USERNAME>:<PASSWORD> | base64

      Example:

      echo -n admin:admin | base64

      The response:

      YWRtaW46YWRtaW4=
      powershell "[convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(\"<USERNAME>:<PASSWORD>\"))

      Example:

      powershell "[convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(\"admin:admin\"))

      The response:

      YWRtaW46YWRtaW4=
    2. Generate the Client ID and the Secret ID.

      curl -k -X POST https://<IOTS_HOST>:8243/api-application-registration/register -H 'authorization: Basic <BASE 64 ENCODED USERNAME:PASSWORD>' -H 'content-type: application/json' -d '{ "applicationName":"appName", "tags":["device_agent"]}'
      • The base 64 encoded USERNAME :PASSWORD must be the username and password that you use to sign in to WSO2 IoT Server. Else, you will not be able to get the client_id and client_secret as the response.
      • The APIs that fall under different categories are grouped using tags. You subscribe to the API group by the tag you define in the cURL command.
        For example, the device_management tag is used to group all the device management APIs including those that belong to the device type APIs.
        To know about the available tags and the APIs grouped under each tag, navigate to the API Cloud Store, click on the available tags in the left side panel.

      The response:

      {"client_secret":"xxxxxxxxxxxxxxxxxxxx","client_id":"xxxxxxxxxxxxxxxxxxxx"}
      curl -k -X POST https://localhost:8243/api-application-registration/register -H 'authorization: Basic YWRtaW46YWRtaW4=' -H 'content-type: application/json' -d '{ "applicationName":"appName", "tags":["device_agent"]}'

      The response:

      {"client_secret":"nboXPDTm9S1cK1yPbhAvJenbbzsa","client_id":"Ad9iV9VJ9EwyujpmLVzCi59rX8Aa"}
    3. Encode the client credentials as follows:

      echo -n <CLIENT_ID>:<CLIENT_SECRET> | base64

      Example:

      echo -n f8fc0aI14DPrQ_DwkpSau1LGdwAa:p8g_rFXtbPjl5pGMJe4bNd5fwSEa | base64

      The response:

      cDhnX3JGWHRiUGpsNXBHTUplNGJOZDVmd1NFYTpmOGZjMGFJMTREUHJRX0R3a3BTYXUxTEdkd0Fh
      powershell "[convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(\"<CLIENT_ID>:<CLIENT_SECRET>\"))

      Example:

      powershell "[convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(\"f8fc0aI14DPrQ_DwkpSau1LGdwAa:p8g_rFXtbPjl5pGMJe4bNd5fwSEa\"))

      The response:

      cDhnX3JGWHRiUGpsNXBHTUplNGJOZDVmd1NFYTpmOGZjMGFJMTREUHJRX0R3a3BTYXUxTEdkd0Fh
    4. Generate the access token using the following command:

      curl -k -d "grant_type=password&username=<USERNAME>&password=<PASSWORD>&scope=perm:device:enroll perm:device:disenroll perm:device:modify perm:device:operations perm:device:publish-event" -H "Authorization: Basic <BASE 64 ENCODEd CLIENT_ID:CLIENT_SECRET>" -H "Content-Type: application/x-www-form-urlencoded" https://localhost:8243/token

      The permission to invoke the APIs are assigned via the scope defined in each API. You can define all the scopes to generate an access token so you can invoke all the APIs or you can generate an access token that only has the required scope to invoke a specific API. In this scenario let's only use the APIs required to create a new device type.

      Generate the access token for the user having the user name admin and password admin, and using the default WSO2 IoT Server host, which is localhost. In this example, we are generating an access token that has access to all the device management scopes.

      curl -k -d "grant_type=password&username=admin&password=admin&scope=perm:device:enroll perm:device:disenroll perm:device:modify perm:device:operations perm:device:publish-event" -H "Authorization: Basic bkl1clAwZkNZOFFtWEVQZzhjNm12OFRHZWJJYTowOG1tdXRuNW9YaEZMTzNPR2NWcnpKeUd6NGNh" -H "Content-Type: application/x-www-form-urlencoded" https://localhost:8243/token

      The response:

      {"access_token":"34frf8f9-ber4-3we9-8333-1cd42d4rs246","refresh_token":"63552c76-ae4f-3fcc-be0d-fd0b074bdc2b","scope":"perm:device:enroll perm:device:disenroll perm:device:modify perm:device:operations perm:device:publish-event","token_type":"Bearer","expires_in":3600}

      The access token you generated expires in an hour. After it expires you can generate a new access token using the refresh token.

  2. Add a new device for the device type you created using the REST APIs.

    curl -k -X POST https://localhost:8243/api/device-mgt/v1.0/device/agent/enroll -H 'accept: application/json' -H 'authorization: Bearer <ACCESS_TOKEN>' -H 'content-type: application/json' -d '{ "name": "<DEVICE_NAME>", "type": "<DEVICE_TYPE>", "description": "<DESCRIPTION_OF_YOUR_DEVICE>", "deviceIdentifier": "<UNIQUE_DEVICE_ID>", "enrolmentInfo": {"ownership": "<DEVICE_OWNERSHIP_TYPE>", "status": "<DEVICE_STATUS>", "owner": "<DEVICE_OWNER>"} ,"properties": [{"name": "<DEVICE_ATTRIBUTE>","value": "<ATTRIBUTE_VALUE>"}]}'

    To check out the entire cURL command, you need to scroll to the end of the command or you can double click the code, copy it, and paste it into a text editor to view it.

    Enter the details to add a new device. The details that need to be entered varies on the attribute values you defined when creating the device type. 
    For example, when creating the fire alarm, the Building_ID and Floor_ID were added as attributes. Therefore, you need to enter the values when creating the new device.Let's get to know the properties used in the cURL command:

    <ACCESS_TOKEN>The access token you generated in step 1 under creating a new device type.
    <DEVICE_NAME>The name you want to give your device.
    <DESCRIPTION_OF_YOUR_DEVICE>The description of your device.

    <UNIQUE_DEVICE_ID>

    A unique device identifier.
    <DEVICE_OWNERSHIP_TYPE>Defineif the device belongs to the BYOD or COPE device ownership types.
    • Bring Your Own Device (BYOD) refers to your own personal device
    • Corporate Owner, Personally Enabled (COPE) refers to the device given to your by your organization.
    <DEVICE_STATUS>Define the device activity status:
    • ACTIVE if the device needs to be marked as actively communicating with the server.
    • INACTIVE if the device is not actively communicating with the server.
    • REMOVED if the device is disenrolled from WSO2 IoT Server.
    <DEVICE_OWNER>The name of the user who owns the device.
    <DEVICE_ATTRIBUTE>The attributes you define when creating the new device type. More than one device attribute and it's value can be added as comma-separated arrays.
    <ATTRIBUTE_VALUE>The value you want to define for the attributes.

    Let's add a new fire alarm device type using the cURL command given below.

    curl -k -X POST https://localhost:8243/api/device-mgt/v1.0/device/agent/enroll -H 'accept: application/json' -H 'authorization: Bearer 34670364–56c8–3f25-ac04–5c01af28c6d1' -H 'content-type: application/json' -d '{ "name": "myhomealarmx1", "type": "firealarm", "description": "this alarm is placed in my house", "deviceIdentifier": "123422", "enrolmentInfo": {"ownership": "BYOD", "status": "ACTIVE", "owner": "admin"} ,"properties": [{"name": "buildingId","value": "wso2"}, {"name": "floorId","value": "2"}]}'

    To chek out the entire cURL command, you need to scroll to the end of the command or you can double click the code, copy it, and paste it into a text editor to view it.

Try out more operations

  • Sending an operation to the device via the REST APIs.

    curl -X POST http://localhost:8280/api/device-mgt/v1.0/devices/firealarm/operations -H 'accept: application/json' -H 'authorization: Bearer <ACCESS_TOKEN>' -H 'content-type: application/json' -d '{"deviceIdentifiers":[<UNIQUE_DEVICE_IDENTIFIER>],"operation":{"code":"<FEATURE_CODE>","typE"”:"CONFIG", "payLoad":"<PAYLOAD>"}}'

    To check out the entire cURL command, you need to scroll to the end of the command or you can double click the code, copy it, and paste it into a text editor to view it.

    Let's get to know the properties used in the cURL command:

    <ACCESS_TOKEN>The access token you generated for the device_management tag and the device management scopes in step 1 under Creating a new device type.
    <UNIQUE_DEVICE_IDENTIFIER>The unique device identifier you defined when adding a new device.
    <FEATURE_CODE>The feature code you defined when creating the new device type.
    <PAYLOAD>You can send operations to the device as a command or a config.
    • Command triggers the operations in a go. For example, ringing a device.
    • When triggering the config operation type you need pass a payload with it. For example, sending a message to the device.

    The cURL command given below sends the payload to trigger the ring feature of the device having 123422 as the unique device identifier.

    curl -X POST http://localhost:8280/api/device-mgt/v1.0/devices/firealarm/operations -H 'accept: application/json' -H 'authorization: Bearer 7e5cad0f-cf78–3981-b50e-db9d674fb741' -H 'content-type: application/json' -d '{"deviceIdentifiers":[123422],"operation":{"code":"ring","type":"CONFIG", "payLoad":"volume:30%"}}'
  • Retrieve the device data within a given time period.

    curl -k -X GET ‘https://localhost:8243/api/device-mgt/v1.0/events/firealarm/<UNIQUE_DEVICE_ID>?offset=<START_PAGINATION_INDEX>&limit=<NUMBER_OF_RECORDS_FROM_THE_START_PAGINATION_INDEX>&from=<START_DATE_AND_TIME_IN_EPOCH_FORMAT>&to=<END_DATE_AND_TIME_IN_EPOCH_FORMAT>' -H 'authorization: Bearer <ACCESS_TOKEN>' -H 'content-type: application/json'

    To check out the entire cURL command, you need to scroll to the end of the command or you can double click the code, copy it, and paste it into a text editor to view it.

    <ACCESS_TOKEN> is the access token you generated for the device_management tag and the device management scopes in step 1 under Creating a new device type.

    The below cURL command retrieves the device data from Sunday, June 4, 2017, 12:04:59 AM to Monday, June 5, 2017, 12:04:59 PM for the fire alarm device having the 123422 device ID.

    curl -k -X GET ‘https://localhost:8243/api/device-mgt/v1.0/events/firealarm/123422?offset=0&limit=100&from=1496534699000&to=1496664299000' -H 'authorization: Bearer 7e5cad0f-cf78–3981-b50e-db9d674fb741' -H 'content-type: application/json'
  • Device retrieving pending operations from the server.
    By default WSO2 IoT Server supports HTTP and MQTT transport protocols. Therefore,  in the HTTP flow, the device polls the server for pending operations and in the MQTT flow, the device receives the operation if it is subscribed to the topic.

    Let's take a look out the command used for the HTTP transport protocol.

    curl -k -X GET https://localhost:8243/api/device-mgt/v1.0/device/agent/pending/operations/<DEVICE_TYPE>/<UNIQUE_DEVICE_ID> -H 'authorization: Bearer <ACCESS_TOKEN>' -H ‘content-type: application/json'

    To check out the entire cURL command, you need to scroll to the end of the command or you can double click the code, copy it, and paste it into a text editor to view it.

    <ACCESS_TOKEN> is the access token you generated for the device_agent tag and the device management scopes in step 1 under Enrolling a Device.

    Example:

    curl -k -X GET https://localhost:8243/api/device-mgt/v1.0/device/agent/pending/operations/firealarm/123422 -H 'authorization: Bearer 34670364–56c8–3f25-ac04–5c01af28c6d1' -H 'content-type: application/json'

    Let's take a look out the command used for the MQTT transport protocol.

    Topic: <TENANT_DOMAIN>/<DEVICE_TYPE>/<UNIQUE_DEVICE_ID>/operation/#

    If you are running in a multi-tenant environment, define your the tenant domain for <TENANT_DOMAIN>. If you not running in a multi-tenant environment, use carbon.super as the <TENANT_DOMAIN>.

    Example:

    Topic: carbon.super/firealarm/123422/operation/#
  • Device responding to an operation sent by the server.

    curl -k -X PUT https://localhost:8243/api/device-mgt/v1.0/device/agent/operations/<DEVICE_TYPE>/<DEVICE_ID> -H 'authorization: Bearer <ACCESS_TOKEN>' -H 'content-type: application/json' -d '{"id": <OPERATION_ID>,"status": "<OPERATION_STATUS>", "payload": "<MEESAGE_SENT_FROM_DEVICE>"}'

    To check out the entire command, you need to scroll to the end of the command or you can double click the code, copy it, and paste it into a text editor to view it.

    • <ACCESS_TOKEN> is the access token you generated for the device_agent tag and the device management scopes in step 1 under Enrolling a Device.
    • The operation status can be one of the following values:
      • IN-PROGRESS - The operation is processing on the IoT server side and has not yet been delivered to the device.
      • PENDING - The operation is delivered to the device but the response from the device is pending.
      • COMPLETED - The operation is delivered to the device and the server has received a response back from the device.
      • ERROR - An error has occurred while carrying out the operation.

    Example:

    curl -k -X PUT https://localhost:8243/api/device-mgt/v1.0/device/agent/operations/firealarm/123422 -H 'authorization: Bearer 34670364–56c8–3f25-ac04–5c01af28c6d1' -H 'content-type: application/json' -d '{"id": 1,"status": "COMPLETED", "payload": "this is my response"}'
    Topic: carbon.super/<DEVICE_TYPE>/<DEVICE_ID>/update/operation
    Payload: {"id": <OPERATION_ID>,"status": "<OPERATION STATUS>", "operationResponse": "<MEESAGE_SENT_FROM_DEVICE>"}
    • If you are running in a multi-tenant environment, define your the tenant domain for <TENANT_DOMAIN>. If you not running in a multi-tenant environment, use carbon.super as the <TENANT_DOMAIN>.
    • The operation status can be one of the following values:
      • IN-PROGRESS - The operation is processing on the IoT server side and has not yet been delivered to the device.
      • PENDING - The operation is delivered to the device but the response from the device is pending.
      • COMPLETED - The operation is delivered to the device and the server has received a response back from the device.
      • ERROR - An error has occurred while carrying out the operation.

    Example:

    Topic: carbon.super/firealarm/123422/update/operation
    Payload: {"id": 1,"status": "COMPLETED", "operationResponse": "this is my response"}
  • Publishing data from a device.

    curl -k -X POST https://localhost:8243/api/device-mgt/v1.0/device/agent/events/publish/<DEVICE_TYPE>/<UNIQUE_DEVICE_ID> -H 'authorization: Bearer <ACCESS_TOKEN>' -H 'content-type: application/json' -d '{"<EVENT_ATTRIBUTE>":<VALUE>,"<EVENT_ATTRIBUTE>":"<VALUE>"}'

    To check out the entire command, you need to scroll to the end of the command or you can double click the code, copy it, and paste it into a text editor to view it.

    The event attributes are the values you defined when creating the event streams to gather the data of the device.

    Example:

    curl -k -X POST https://localhost:8243/api/device-mgt/v1.0/device/agent/events/publish/firealarm/123422 -H 'authorization: Bearer 34670364–56c8–3f25-ac04–5c01af28c6d1' -H 'content-type: application/json' -d '{"temperature":10,"status":"working"}'
    topic: <TENANT_DOMAIN>/<DEVICE_TYPE>/<UNIQUE_DEVICE_ID>/events
    Payload: {"EVENT_ATTRIBUTE":VALUE,"EVENT_ATTRIBUTE":"VALUE"}
    • If you are running in a multi-tenant environment, define your the tenant domain for <TENANT_DOMAIN>. If you not running in a multi-tenant environment, use carbon.super as the <TENANT_DOMAIN>.
    • The event attributes are the values you defined when creating the event streams to gather the data of the device.

    Example:

    topic: carbon.super/firealarm/123422/events
    Payload: {"temperature":10,"status":"working","humidity":20}

What's next?

  • No labels