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 the Maven Archetype (v.9 vs v.10) - IoT Server 3.1.0 - WSO2 Documentation

Versions Compared

Key

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

...

Excerpt

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.

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

    Example:

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

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

      Expand
      titleClick here for more information on downloading WSO2 IoTS

      Excerpt Include
      Downloading the Product
      Downloading the Product
      nopaneltrue

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

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

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

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

        Code Block
        [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
        Note
        titleThe available archetypes are not shown?
        Expand
        titleClick 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: 

          Code Block
          mvn archetype:generate -DarchetypeCatalog=local -X
          Info

          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:

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

            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.

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

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

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

        Note

        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.

        Note

        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.

        Note

        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
        Anchor
        deviceType
        deviceType
        deviceType

        The value you define for the deviceType.

        Expand
        titleClick here for more information on the places this value is used when generating the deviceType:
        Panel
        borderColor#6A98FA
        bgColor#ffffff
        borderWidth1

        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

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

          Code Block
          "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.

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

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

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

        Info

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

        currentYes

        Example:

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

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

      Info

      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.

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

        Example:

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

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

        Example: 

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

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

        Example: 

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

      Code Block
      mvn clean install -f device-plugins-deployer.xml
      Info
      iconfalse
      titleWhy 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.

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

    Info

    For more information, see accessing the device management console.

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

    Info
    titleUnable to download the agent?
    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:

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

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

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

...