Skip to content

Export to IBM Watson

Overview

The IBM Watson™ IoT Platform is a service offered by IBM Cloud. As an IBM Cloud service, Watson IoT Platform can be integrated with other services that are hosted on IBM Cloud. Customers could register and connect their device, be it a sensor, or a gateway, to Watson IoT Platform and start sending data securely up to the cloud using the open, lightweight MQTT messaging protocol. This page will describe how customers could register their gateway deployed with Edge Xpert to IBM Watson IoT Platform and then configure an Application Configurable Service to export EdgeX events to IBM Watson IoT Platform via MQTT protocol.

Note

In Edge Xpert V2, IBMWatsonMQTTSend function is replaced by XpertMQTTExport function.

Prerequisite

  1. An IBM Cloud account
  2. A Watson IoT platform service
  3. Register your device to IBM Watson IoT Platform
  4. Understand Edge Xpert Application Service
  5. Launch core services

Sample Configuration

The following code defines the pipeline function XpertMQTTExport:

[Writable.Pipeline.Functions.XpertMQTTExport]
  [Writable.Pipeline.Functions.XpertMQTTExport.Parameters]
  ExportMode = "IBMWatson"
  BrokerAddress = "tcps://{org_id}.messaging.internetofthings.ibmcloud.com:8883"
  Topic = "iot-2/evt/{event_id}/fmt/{formatstring}"
  ClientID = "d:{org_id}:{device_type}:{device_id}"
  SecretPath = "watson"
  Qos = "0"
  Retain = "false"
  AutoReconnect = "true"
  SkipVerify = "false"
  PersistOnError = "false"

The following table describes the configuration parameters used to define the pipeline function XpertMQTTExport:

Configuration Mandatory Description
ExportMode Yes Must specify IBMWatson to indicate that the data should be exported to Watson IoT Platform.
BrokerAddress Yes Specifies the MQTT broker address on the Watson IoT Platform.

At the time of publication, IBM allows users to access Watson IoT Platform through MQTT protocol by using the broker address in the format below:
tcps://{org_id}.messaging.internetofthings.ibmcloud.com:8883
Note that org_id is the ID of your Watson IoT Platform organization.

For further information, please refer to IBM Documentation.
Topic Yes Specifies the MQTT topic of IBM Watson IoT Platform to publish the message to. Watson IoT Platform requires device publish the messages to the topic as defined in the format below:
iot-2/evt/_eventid/fmt/_formatstring
Note that _eventid specifies the event name that's shown in Watson IoT Platform, and _formatstring is the format of the event, such as JSON.

For further information, please refer to IBM Documentation.
ClientID Yes Specifies the Client ID to access Watson IoT Platform. At the time of publication, IBM requires the Client ID in the format of d:<org_id>:<device_type>:<device_id>.

For further information, please refer to IBM Documentation.
SecretPath Yes Specifies the path in the secret provider from which to retrieve the certificate and private key of your Watson IoT Platform. At the time of publication, IBM requires the username to be use-token-auth, and password to be the unique authentication token that was generated when the device was registered with Watson IoT Platform.

When the app service is running under secure mode, username and password will be retrieved from Secret Store; when the app service is running under insecure mode, username and password will be retrieved from Writable.InsecureSecrets configuration.
Qos Specifies the Quality of Service (QoS) levels for the Watson IoT Platform MQTT connection.

Watson IoT Platform MQTT broker accepts only QoS 0, 1, or 2.

For further information, please refer to IBM Documentation.
AutoReconnect Specifies whether the connection is to be automatically reconnected if it is lost.
SkipVerify Specifies whether the Edge Xpert Application Service verifies the server's certificate chain and host name.

If set to true, TLS accepts any certificate presented by the server and any host name in that certificated. This means that TLS is susceptible to man-in-themiddle attacks. Use this setting for testing purposes only.
PersistOnError Specifies whether the events are stored for further attempts if any error is encountered during the message publication.
Note: To use persistOnError, Store and Forward must be enabled in the Application Service configuration file. For further information on Store and Forward, refer to the Advanced Topics under the Application Functions SDK section of the EdgeX Foundry documentation.
  • Set to true to enable
  • Set to false to disable

Configure an Application service to export events to Watson IoT Platform

  1. By end of step 3 in Prerequisite, customers shall expect to obtain Organization ID,Device type, Device ID, Authentication method, and Authentication token as shown below: device-credential sample Keep a note on these information, as customers will need these information to authenticate with Watson IoT Platform.

  2. Edge Xpert offers a proprietary built-in function “XpertMQTTExport“ to send the events to IBM Watson IoT Platform via MQTT, and a sample configuration is provided with Edge Xpert CLI utility. Once customers completes the installation of Edge Xpert CLI utility, the sample configuration is available at /usr/share/edgexpert/examples/app-configurable/ibmwatson-mqtt-export/configuration-insecure.toml. Copy and save the sample configuration file as a separate file, e.g. ibmwatson-mqtt-export.toml, and then revise this configuration per the Organization ID, Device type, Device ID, Authentication method, and Authentication token as obtained from the step 3 of Prerequisite.
    For example, if users have device credentials: Organization ID: 3wrbbc, Device Type: edgex, Device ID: test01, Authentication Method: use-token-auth, Authentication Token: K*&WB2!9nvY*NG-kzF, user shall revise XpertMQTTExport with following parameters: (More configuration details will be described in next section.)

    [Writable.Pipeline.Functions.XpertMQTTExport]
      [Writable.Pipeline.Functions.XpertMQTTExport.Parameters]
      ExportMode = "IBMWatson"
      BrokerAddress = "tcps://3wrbbc.messaging.internetofthings.ibmcloud.com:8883"
      Topic = "iot-2/evt/mesaage123/fmt/JSON"
      ClientID = "d:3wrbbc:edgex:test01"
      SecretPath = "watson"
      Qos = "0"
      Retain = "false"
      AutoReconnect = "true"
      SkipVerify = "false"
      PersistOnError = "false"
    

    If customers would like to launch the application service under secure mode, they shall add username, and password into secret store. Please refer to Edge Xpert Application Services for details about adding secrets into secret store. If customers would like to launch the application service under insecure mode, they shall revise Writable.InsecureSecrets.watson configuration as shown below:

    [Writable.InsecureSecrets.watson]
      path = 'watson'
      [Writable.InsecureSecrets.watson.Secrets]
          username = 'use-token-auth'
          password = 'K*&WB2!9nvY*NG-kzF'
          cacert = ''
          clientcert = ''
          clientkey = ''
    

  3. Once configuration is ready, launch an application service with such configuration:

    # Under secure mode
    $ edgexpert up --secret app-service --path=<path your confgiuration file>
    
    # Under insecure mode
    $ edgexpert up app-service --path=<path your confgiuration file>
    

  4. Now, an application service is up and ready to export events to IBM Watson IoT Platform. To simulate the device sending readings from southbound, we could start up virtual device service:

    # Under secure mode
    $ edgexpert up --secret device-virtual
    
    # Under insecure mode
    $ edgexpert up device-virtual
    

  5. To monitor those events being published to IBM Watson IoT Platform, customers could go to their Watson IoT Platform dashboard, select Devices > >Recent Events

    events sample

Back to top