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

You are able to create a device type plugin in one go using the Maven archetype in WSO2 IoT Server. Follow the steps given below:

Step 1:  Installing the Maven Archetype

Follow the steps given below to install the Maven archetype on your local system, which is a one-time installation.

  1. Clone the maven archetype from GitHub to a preferred location.

    git clone -b v1.0.0 --single-branch https://github.com/wso2/carbon-device-mgt-maven-plugin.git

    Example:

    git clone -b v1.0.0 --single-branch https://github.com/wso2/carbon-device-mgt-maven-plugin.git
  2. Navigate to the cloned folder via the console, and install the Maven archetype into your local system.
    Example: 

    cd <PATH-WHERE-THE-FILE-WAS-CLONED>/carbon-device-mgt-maven-plugin
    mvn clean install

Step 2: Creating a new device type

    1. Download WSO2 IoT Server, if you have not downloaded it previously.

       Click here for more information on downloading WSO2 IoTS

      1. Download WSO2 IoT Server.

        Tip: If you want to try out the advanced device search capabilities, download the WSO2 IoT Server 3.10-Update1 pack and try it out.

      2. Copy the downloaded file to a preferred location and unzip it. The unzipped file is called <IOTS_HOME> throughout this documentation.

        • The downloaded WSO2 IoT Server file is large. Therefore, when unzipping, it might extract halfway through and stop. To avoid this, we recommend that you unzip the file via the terminal.
          Example:

          unzip wso2iot-3.1.0.zip
        • The maximum character count supported for a file path in the Windows OS is 260. If this count is exceeded when extracting the pack into a directory, you will get the Error 0x80010135: Path too long error. To overcome this issue use the commands given below:
          • Create a substring and map the current file path to it.
            In the example given below, the WSO2 IoT Server .zip file is located in the C:\Users\Administrator\Downloads\pre-beta directory.

            C:\Users\Administrator\Downloads\pre-beta>subst Y: C:\Users\Administrator\Downloads\pre-beta
          • Copy the IoT Server Server zip folder to the new path you created and unzip the file there.
            Example: Unzip the file in the Y: directory.

    2. Navigate to the <IoTS_HOME>/samples folder.

      cd <IoTS_HOME>/samples
    3. Create the new device plugin.

      1. Run the command given below to start creating the new device type plugin.

        mvn archetype:generate -DarchetypeCatalog=local
      2. You will be prompted to choose the archetype. Select org.wso2.cdmf.devicetype:cdmf-devicetype-archetype (number may differ) to create the new device type.

        Example:

        [INFO] Scanning for projects...
        [INFO]                                                                         
        [INFO] ------------------------------------------------------------------------
        [INFO] Building Maven Stub Project (No POM) 1
        [INFO] ------------------------------------------------------------------------
        [INFO] 
        [INFO] >>> maven-archetype-plugin:2.4:generate (default-cli) > generate-sources @ standalone-pom >>>
        [INFO] 
        [INFO] <<< maven-archetype-plugin:2.4:generate (default-cli) < generate-sources @ standalone-pom <<<
        [INFO] 
        [INFO] --- maven-archetype-plugin:2.4:generate (default-cli) @ standalone-pom ---
        [INFO] Generating project in Interactive mode
        [INFO] No archetype defined. Using maven-archetype-quickstart (org.apache.maven.archetypes:maven-archetype-quickstart:1.0)
        Choose archetype:
        1: local -> org.wso2.mdm:mdm-android-agent-archetype (Creates a MDM-Android agent project)
        2: local -> org.wso2.iot:mdm-android-agent-archetype (Creates a MDM-Android agent project)
        3: local -> org.wso2.cdmf.devicetype:cdmf-devicetype-archetype (WSO2 CDMF Device Type Archetype)
        4: local -> cdmf.devicetype:cdmf-devicetype-archetype (WSO2 CDMF Device Type Archetype)
        Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): : 3

        The available archetypes are not shown?

         Click here to find out why.

        The archetypes will not be shown if the wrong local catalog file path is being read. To overcome this issue, follow the steps give below:

        1. Run the command given below to identify the path that is being read: 

          mvn archetype:generate -DarchetypeCatalog=local -X

          This will run the maven archetype in debug mode and search for the archetype-catalog.xml file.

        2. Check the output that is given:

          • If the path is  ~/.m2/repository/archetype-catalog.xml, you shouldn't be facing an issue.
          • If the path is different to that given above, you need to move the archetype-catalog.xml file from the given location to the repository directory using the command given below:

            cp ~/.<CURRENT_LOCATION_OF THE_FILE>/archetype-catalog.xml ~/.m2/repository/

            The archetype-catalog.xml file must be in the .m2 directory.


            Example: If the path that is being read is ~/.m2/repository/archetype-catalog.xml, you need to move the archetype-catalog.xml file to the repository directory.

            cp ~/.m2/archetype-catalog.xml ~/.m2/repository/
        3. Run the command to start creating the new device type.

          mvn archetype:generate -DarchetypeCatalog=local
      3. You will be prompted to provide the values for the properties given below:

        Define value for property 'groupId': 
        Define value for property 'artifactId': 
        Define value for property 'version':  3.0-SNAPSHOT:
        Define value for property 'package':  
        Define value for property 'deviceType': 
        Define value for property 'sensorType1':
        Define value for property 'sensorType2':
        Define value for property 'sensorType3':
        PropertyDefinitionExampleRequired
        groupId

        The group ID is used to identify a created project uniquely across all projects.

        This is a mandatory field to generate the folder structure for a project using the Maven Archetype.

        org.homeautomation

        Yes
        artifactId

        The value you define as the artifactId will be given as the folder name for the device type you are creating in the <IoTS_HOME>/samples folder.

        This is a mandatory field to generate the folder structure for a project using the Maven Archetype.

        currentsensorYes
        version

        Provide the version of the new device type plugin you are creating. If you wish to use the default version (3.0-SNAPSHOT) click enter.

        This is a mandatory field to generate the folder structure for a project using the Maven Archetype.

        3.0-SNAPSHOTYes
        packageProvide the package name. This is not a mandatory field, therefore, if you do not provide a package name when prompted the value you assigned to the groupId will be used as the default value.-No
        deviceType

        The value you define for the deviceType.

         Click here for more information on the places this value is used when generating the deviceType:

        Once you create the device plugin the device type will be used in the following places:

        Analytics scripts

        • The event receiver will have the MQTT publisher topic defined in the <TENANT_DOMAIN>.<DEVICE_TYPE>.<DEVICE_ID>.<OTHER_STRINGS> format.
          Example: connected_cup_receiver

          <property name="topic">carbon.super/connectedcup/#</property>
        • The event stream will have the device type defined as a sample. You are able to configure the stream to suit your requirement.
          Example: connected_cup_stream

          "metaData": [
            {"name": "owner", "type": "STRING"},
            {"name": "deviceId", "type": "STRING"},
            {"name": "DeviceType", "type": "STRING"},
            {"name": "timestamp", "type": "LONG"}
          ]
        • The metadata defined in the event stream needs to be defined in the event store. Therefore, if there is an attribute from the deviceType defined in the event stream you need to define it in the event store too.

        API

        • Each API will have permissions defined in the permission.xml file that is in the respective JAXRS directories META-INF file. The permissions for these APIs are only accessible by the device type, therefore, it will include the deviceType you specify.
          Example: The get device API has the permission path defined as /device-mgt/<DEVICE_TYPE>/user.

          <Permission>
             <name>Get device</name>
             <path>/device-mgt/currentsensor/user</path>
             <url>/device/*</url>
             <method>GET</method>
             <scope>currentsensor_user</scope>
          </Permission>
        • The device type is defined when creating an API using the @DeviceType annotation.
          Example:

          @DeviceType(value = "currentsensor")

        UI

        • The device type UI is written using the cdmf.unit.device.type.<DEVICE_TYPE>.type-view unit. 
        • The device details UI is written using the cdmf.unit.device.type.<DEVICE_TYPE>.device-view unit.
        • The config.json file in the cdmf.unit.device.type.<DEVICE_TYPE>.device-view unit includes the device type specific information in the label and downloadAgentUri attributes.
          Example:

          {
            "deviceType": {
              "label": "currentsensor",
              "category": "virtual",
              "downloadAgentUri": "currentsensor/device/download"
            }
          }
        • The device details UI is written using the cdmf.unit.device.type.<DEVICE_TYPE>.realtime.analytics-view unit. 
        • The device details UI is written using the cdmf.unit.device.type.<DEVICE_TYPE>.analytics-view unit.
        currentsensorYes

        sensorType1

        Each device will have specific sensors. Define the sensor for the device type you are creating.

        Using the Maven Archetype you are only able to define one sensor.

        currentYes

        Example:

        Define value for property 'groupId': : org.homeautomation              
        Define value for property 'artifactId': : currentsensor
        Define value for property 'version':  1.0-SNAPSHOT: : 3.0-SNAPSHOT
        Define value for property 'package':  org.homeautomation: : 
        Define value for property 'deviceType': : currentsensor
        Define value for property 'sensorType1': : currentSensor
        Define value for property 'sensorType2': : waterFlowSensor
        Define value for property 'sensorType3': : voltageSensor
      4. Confirm the property configurations by entering Yes or Y as the value. If you wish to make any changes to the values you defined, enter No as the value to start over again 
        Example:

        Confirm properties configuration:
        groupId: org.homeautomation
        artifactId: currentsensor
        version: 3.0.0-SNAPSHOT
        package: org.homeautomation
        deviceType: currentsensor
        sensorType1: currentSensor
        sensorType2: waterFlowSensor
        sensorType3: voltageSensor
        Y: Yes
    4. Configure the device-plugins-deployer.xml file that is in the <IoTS_HOME>/samples directory.

      The values you assigned to the properties in step 3.c above will be used here.

      1. Add the new module under the <modules> tag.

        <modules>
           <module>{artifactID}</module>
        </modules>

        Example:

        <modules>
           <module>currentsensor</module>
        </modules>
      2. Add the device type feature under the <featureArtifacts> tag.

        <featureArtifactDef>
           {groupID}:{groupID}.{artifactID}.feature:<version>
        </featureArtifactDef>

        Example: 

        <featureArtifactDef>
           org.homeautomation:org.homeautomation.currentsensor.feature:3.0-SNAPSHOT
        </featureArtifactDef>
      3. Add the device type feature group under the <features> tag.

        <features>
           <feature>
              <id>{groupID}.{artifactID}.feature.group</id>
              <version>{version}</version>
           </feature>
        </features>

        Example: 

        <features>
           <feature>
              <id>org.homeautomation.currentsensor.feature.group</id>
              <version>3.0-SNAPSHOT</version>
           </feature>
        </features>
    5. Navigate to the <IoTS_HOME>/samples, and deploy the sample device type you created.

      mvn clean install -f device-plugins-deployer.xml

      Why is this step required?

      This command is required to create the device type feature. When the samples-deployer.xml runs, it will create the P2 repository in the device types folder. To deploy the sample device type you created, you need to execute the command given below from the same location as the samples-deployer.xml.

Step 3: Try out the new device type

  1. Start WSO2 IoT Server.

    cd <IoTS_HOME>/bin
    ./wso2server.sh
  2. Access the device management console. You will see the newly created device on the device page.
    Example: https://localhost:9443/devicemgt

    For more information, see accessing the device management console.

  3. Click on the new device type and download the agent.

    Unable to download the agent?

     Click here to expand...

    If you run into an error when downloading the agent for the device type you created, follow the steps given below:

    1. Confirm that the <DEVICE_TYPE>.war file is created by navigating to <IoT_HOME>/core/repository/deployment/webapps directory.
    2. Next, open the <IoT_HOME>/conf/etc/webapp-publisher-config.xml file and check if the <EnabledUpdateApi> is enabled. If it's not enabled, assign the value as true.
      Example:

      <EnabledUpdateApi>true</EnabledUpdateApi>
  4. Copy the downloaded agent to a preferred location and unzip it.
  5. Start the agent of the device type.

    cd <DOWNLOADED_AGENT>
    ./startService.sh

    You will be prompted to enter the time interval that you want for the device to push data to WSO2 DAS, in seconds.
    Example: Push data every 45 seconds.

    What's the time-interval (in seconds) between successive Data-Pushes to the WSO2-DAS (ex: '60' indicates 1 minute) > 45

What's next?

  • Navigate to the Device Management page to view the device you created and check the data it pushes in the form of a graph.

     Click here for more information on navigating to the Device Management page.
    1. Sign into the Device Management console.
    2. Click the menu icon.
    3. Click Device Management.
  • For more information on the device plugin, see Writing Device Types.
  • For more information on writing device specific APIs, see Writing Device APIs.
  • For more information on customizing the device view User Interface, see Writing UI Extensions.
  • For more information on working with analytics, see Writing Analytics.
  • No labels