This documentation is for WSO2 IoT Server 3.1.0. View the documentation for the latest release.
Page Comparison - Creating a New Device Type via APIs (v.25 vs v.26) - IoT Server 3.1.0 - WSO2 Documentation

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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

  1. Anchor
    #Device_agent_access_token
    #Device_agent_access_token
    Obtain the access token to enroll a new device.

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

      Localtab Group
      Localtab
      activetrue
      titleLinux/Mac
      Panel
      borderColor#11375B
      bgColor#ffffff
      borderWidth1
      Code Block
      echo -n <USERNAME>:<PASSWORD> | base64

      Example:

      Code Block
      echo -n admin:admin | base64

      The response:

      Code Block
      YWRtaW46YWRtaW4=
      Localtab
      titleWindows
      Panel
      borderColor#11375B
      bgColor#ffffff
      borderWidth1
      Code Block
      powershell "[convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(\"<USERNAME>:<PASSWORD>\"))

      Example:

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

      The response:

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

      Localtab Group
      Localtab
      activetrue
      titlecURL command
      Panel
      borderColor#11375B
      bgColor#ffffff
      borderWidth1
      Code Block
      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"]}'
      Info
      • 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:

      Code Block
      {"client_secret":"xxxxxxxxxxxxxxxxxxxx","client_id":"xxxxxxxxxxxxxxxxxxxx"}
      Localtab
      titleExample:
      Panel
      borderColor#11375B
      bgColor#ffffff
      borderWidth1
      Code Block
      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:

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

      Localtab Group
      Localtab
      activetrue
      titleLinux/Mac
      Panel
      borderColor#11375B
      bgColor#ffffff
      borderWidth1
      Code Block
      echo -n <CLIENT_ID>:<CLIENT_SECRET> | base64

      Example:

      Code Block
      echo -n f8fc0aI14DPrQ_DwkpSau1LGdwAa:p8g_rFXtbPjl5pGMJe4bNd5fwSEa | base64

      The response:

      Code Block
      cDhnX3JGWHRiUGpsNXBHTUplNGJOZDVmd1NFYTpmOGZjMGFJMTREUHJRX0R3a3BTYXUxTEdkd0Fh
      Localtab
      titleWindows
      Panel
      borderColor#11375B
      bgColor#ffffff
      borderWidth1
      Code Block
      powershell "[convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(\"<CLIENT_ID>:<CLIENT_SECRET>\"))

      Example:

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

      The response:

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

      Localtab Group
      Localtab
      titlecURL command
      Panel
      borderColor#11375B
      bgColor#ffffff
      borderWidth1
      Code Block
      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
      Info

      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.

      Localtab
      titleExample
      Panel
      borderColor#11375B
      bgColor#ffffff
      borderWidth1

      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.

      Code Block
      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:

      Code Block
      {"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}
      Note

      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.

    Localtab Group
    Localtab
    activetrue
    titlecURL command
    Code Block
    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>"}]}'
    Info

    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.

    Anchor
    unique_ID
    unique_ID
    <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.
    Localtab
    titleExample:

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

    Code Block
    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"}]}'
    Info

    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.

...