This documentation is for WSO2 IoT Server 3.1.0. View the documentation for the latest release.
Device Communicating with the Server - IoT Server 3.1.0 - WSO2 Documentation
                                                                                                                                                                                                                                                                                                                                                                                                                                                   
||
Skip to end of metadata
Go to start of metadata

 The data received by your device sensors will be sent to WSO2 Data Analytic Server (DAS) so that you can view them in real-time or as historical data. Before sending data to WSO2 DAS, you will want to encode it or convert it to a preferred format. How can you do this?

WSO2 IoT Server provides you with the ability to transform and validate content before sending them to WSO2 DAS. Once this is done you can configure WSO2 IoT Server to send data to subscribed events or send them directly to WSO2 DAS. Take a look at the diagram given below:

Let's take a look at how you can send data to WSO2 DAS:

You can write your own custom logic to transform and validate content before sending your data to WSO2 DAS. To understand how this is done, let's take a look at how the content transformer and validator are used by the analytics receiver of the RaspberryPi device type

The MQTT transport extension is used for this purpose.

  1. Transform the data you receive, such as encoding the data, before sending it to WSO2 DAS. 

    In the case of the RaspberryPi device type, it uses the default content transformer that sends the data as it is to WSO2 DAS.

    1. If you wish to transform the content, you need to implement the contentTransformer interface.
      Example:

      public class MQTTContentTransformer implements ContentTransformer {}
    2. Customize the content transformer to match your requirement.
  2. Validate content.

    Why validate?

    Once the MQTT transport extension/input adapter receives the data sent by the device, you will need to verify if it's a spoofer or if it's the device user that is sending the data. After this fact is verified you can configure WSO2 IoT Server to send the content to WSO2 DAS.

    In the RaspberryPi device type, the API path that is used to send the data is verified by checking if the device ID in it matches the ID of the device registered with WSO2 IoT Server. You can validate the content using the MQTT, HTTP, and XMPP content validators.

    1. Extend the content transformer interface, and customize it to suit our requirement.
      Example: MQTTContentValidator.java

      public class MQTTContentValidator implements ContentValidator {}
    2. Customize the content validator to match the device ID and verify the user and the device.
      Example: MQTTContentValidator.java

      public class MQTTContentValidator implements ContentValidator {
       private static final String JSON_ARRAY_START_CHAR = "[";
       private static final Log log = LogFactory.getLog(MQTTContentValidator.class);
       @Override
       public ContentInfo validate(Object msgPayload, Map < String, String > contentValidationParams,
        Map < String, String > dynamicParams) {
        String topic = dynamicParams.get(MQTTEventAdapterConstants.TOPIC);
        String topics[] = topic.split("/");
        String deviceIdJsonPath = contentValidationParams.get(MQTTEventAdapterConstants.DEVICE_ID_JSON_PATH);
        String deviceIdInTopicHierarchyLevel = contentValidationParams.get(
         MQTTEventAdapterConstants.DEVICE_ID_TOPIC_HIERARCHY_INDEX);
        int deviceIdInTopicHierarchyLevelIndex = 0;
        if (deviceIdInTopicHierarchyLevel != null && !deviceIdInTopicHierarchyLevel.isEmpty()) {
         deviceIdInTopicHierarchyLevelIndex = Integer.parseInt(deviceIdInTopicHierarchyLevel);
        }
        String deviceIdFromTopic = topics[deviceIdInTopicHierarchyLevelIndex];
        boolean status;
        String message = (String) msgPayload;
        if (message.startsWith(JSON_ARRAY_START_CHAR)) {
         status = processMultipleEvents(message, deviceIdFromTopic, deviceIdJsonPath);
        } else {
         status = processSingleEvent(message, deviceIdFromTopic, deviceIdJsonPath);
        }
        return new ContentInfo(status, msgPayload);
       }
  3. Configuring the Analytic Receiver by adding the following configurations.

    Why configure the receiver?

    Once you have configured WSO2 IoT Server to transform and validate content, you need to direct the receiver that receives these data to the correct classpaths so as to transform and validate the content accordingly. This needs to be configured in the respective <DEVICE_TYPE>-receiver-<TENANT-DOMAIN>.xml.
    Example: raspberrypi_receiver-carbon.super.xml

    • Super Tenant configurations 

       Click here for more information.
      1. Add the classpath to where you configured the content transformer.

        If you are using the default method provided by WSO2 IoT Server, you need to define the value as default. In the default method, the data received will be sent directly to WSO2 DAS without any transformation.

        Example: 

        <property name="contentTransformer">default</property>
      2. Add the classpath to where you configured the content validation.

        If you are using the default method provided by WSO2 IoT Server, you need to define the value as default. In the default method, the data received will be sent directly to WSO2 DAS without any validation.

        Example:

        <property name="contentValidator">org.wso2.carbon.device.mgt.iot.input.adapter.mqtt.util.MQTTContentValidator</property>
    • Tenant configurations
      Want to configure the analytics receiver for your tenant without using the super tenant configurations? Follow the steps given below:

       Click here for more information.
      1. Open the respective <DEVICE_TYPE>-receiver.xml file that is in the carbon-device-mgt-plugins/features/device-types-feature/<DEVICE_TYPE>-plugin-feature/org.wso2.carbon.device.mgt.iot.<DEVICETYPE>.backend.feature/src/main/resources/receiver directory.
        Example: raspberrypi-receiver.xml
      2. Add the classpath to where you configured the content transformer.

        If you are using the default method provided by WSO2 IoT Server, you need to define the value as default. In the default method, the data received will be sent directly to WSO2 DAS without any transformation.

        Example: 

        <property name="contentTransformer">default</property>
      3. Add the classpath to where you configured the content validation.

        If you are using the default method provided by WSO2 IoT Server, you need to define the value as default. In the default method, the data received will be sent directly to WSO2 DAS without any validation.

        Example:

        <property name="contentValidator">org.wso2.carbon.device.mgt.iot.input.adapter.mqtt.util.MQTTContentValidator</property>
      4. Restart the WSO2 IoT Server's broker, core, and analytics profiles.

        cd <IOTS_HOME>/bin
        
        
        -----Start the broker profile------
        ./broker.sh or broker.bat
        
        
        -----Start the core profile---------
        ./iot-server.sh or iot-server.bat
        
        
        ----Start the analytics profile-----
        ./analytics.sh or analytics.bat
      5. Sign in to the device management console using your tenant credentials.
        If you are not sure of how to create a tenant, see adding a new tenant.
      6. Click the menu icon > CONFIGURATION MANAGEMENT > PLATFORM CONFIGURATIONS.
      7. Click on your device specific configuration (e.g., Raspberry Pi Configuration) and click Deploy Analytics Artifacts.

        Navigate to the analytics console: https://<IOTS_HOST>:<IOTS_PORT>/carbon, click Receivers that is on the Main tab, and you will see that a new stream has for raspberrypi other than the receiver stream for the raspberrypi_receiver-carbon.super.

        Example:


      Optionally, if you want to configure the Analytic Receiver after deploying the artifacts, follow the steps given below:

      1. Navigate to the analytics console: https://<IOTS_HOST>:<IOTS_PORT>/carbon

        The default IoT Server host is localhost and the default analytics port on IoT Server is 9445.

      2. Click Receivers that is on the Main tab, and click on the event publisher your want to configure.
      3. Click Edit and edit the details of the receiver.
        Example:

        PropertyDescription
        Event Receiver Name

        This is the unique name of your event receiver. The name is similar to what you have defined in your <DEVICE_TYPE>-receiver-<TENANT-DOMAIN>.xml file.
        Example: raspberrypi_receiver-carbon.super.xml

        eventReceiver name="raspberrypi_receiver-carbon.super"
        Input-Event Adapter Type

        An input event adapter (transport) configuration via which the event receiver receives events.

        You can define the content transformer and validator properties only if you select oauth-mqtt or XMPP.

        Topic

        The name of the topic that the receiver needs to subscribe to.
        This is similar to what's defined in the raspberrypi_receiver-carbon.super.xml file.

        <property name="topic">carbon.super/raspberrypi/+/temperature</property>
        contentValidation

        Type of the content Validation or 'default' to set default type, required to implement (if required)

        contentTransformerType of the content transformer or 'default' to set default type, required to implement (if required)
      4. Click Update.
  • No labels