Skill Level: Any Skill Level

This recipe shows the steps needed to connect a SmartServer IoT to an IOX module together, to publish data to the IBM Watson IoT Platform over a secure MQTT connection and then visualize data on cards within the Watson IoT Platform.


An organization account at IBM Watson IoT platform

A SmartServer IoT with build 2.40.507 or greater, an IOX Module with build 1.00.0011 or greater and a suitable current transformer as referenced in the IOX User's Guide at www.echelon.com/docs/iot

From the label on the back of the SmartServer IoT, the serial number, install code, host name, user name and password

Internet access to connect the SmartServer IoT with the IBM Watson IoT platform (outgoing port 1883 must be open)

A PC to configure the SmartServer IoT with a terminal emulator installed such as PuTTY, Visual Studio Code installed and an internet connection

An understanding of MQTT and Linux would be useful


  1. Generate IBM Watson IoT Platform API Key

    Log into your IBM Watson IoT Platform account and click on the App icon on the left hand side and click on Generate API Key at the top right.


    Add a description for the key and click on Next.

    1_2Select “Standard Application” from the role drop down and click Generate Key.


    Make a note of the generated API API Key and Authentication Token (the token will only be visible once).

    Key: a-7tn0wo-v8g4jxwvyz

    Token: <your token>

    Click Close



  2. Create IBM Watson IoT Platform Gateway Type

    Click on the Devices icon on the left hand side, select the Devices Types tab and click on Add Device Type at the top right.


    Click on Gateway, in the Name field type EchelonSSIoT and add a Description, then click Next.


    Click Done.


    Click on Cancel


    You will see the gateway type definition just created



  3. Create IBM Watson IoT Platform Device Type

    Click on Add Device Type at the top right


    Click on Device, type EchelonGWDevice the Name field, add a Description, click on Next


    Click Done


    Click Cancel


  4. Create IBM Watson IoT Platform Gateway Device

    Click on the Browse tab, click on Add Device at the top right


    Select the EchelonGWDevice from the Device Type drop down menu and add the name “IOXMeter0001” in the Device ID field, click on Next.


    Click on Next.


    Add the Authentication Token you noted earlier when Generating the API Key, click on Next


    Click Done.


    Click on the back arrow at the top left.


  5. Create IBM Watson IoT Platform Device

    Click on Add Device at the top right.


    From the Device Type drop down select EchelonSSIOTGW, add EchelonSSIOTGW0001″ into the field and click on Next.


    Click on Next.


    Click on Add Devices


    Check IOXMeter0001 and click Done.


    Click on Next.


    Add the Authentication Token noted earlier and click on Next.


    Click Done.


    Click on the Back Arrow at the top left.


  6. Create an IBM Watson IoT Platform Board

    Go to the boards section of the IBM Watson dashborad and create a board to visualize the data.

  7. Create IBM Watson IoT Platform Cards

    Create visualization cards on the your board with the appropriate card settings to display the data.  Make sure to select the IOXMeter001 device.  

    For Event type use “nvocurrentrmsupdate” (if the gateway were sending data the drop down would be populated), for Property type use “value” (if the gateway were sending data the drop down would be populated), for Name type use “Current” (this will appear as the line label), for Type select Number from the drop down, for Unit select “A”, for Max type “50”.


    Repeat the card set up procedure above for the other four datapoints: nvoenergyactiveupdate, nvopowerfactorupdate, nvovoltagermsupdate, nvolinefrequencyupdate using appropriate parameters and text.

  8. Setup the Hardware

    Connect the SmartServer to the IOX using a suitable USB A to USB C cable 

    Connect the supply voltage to be monitored to the phase 1 L&N voltage terminals and pass the supply cable to be monitored through the CT and connect the CT cables to the phase 1 CT input as shown below, ensuring the polarity of the CT connection and the direction of the CT wire .  If the CT is wired the wrong way around, power factor as measured will show a negative value. 


    Connect the SmartServer IoT eth0 Ethernet port to your local network infrastructure using an Ethernet patch lead.  This should be on the same subnet that your computer is attached to.

    Connect the AC/DC supply to the SmartServer and turn on the supply

  9. Connect your PC to the SmartServer IoT Console Interface

    This can be achieved using a terminal emulator connected to the SmartServer either using either a serial connection using PuTTy.exe (or similar) or by using SSH over the network.


    1.     Establishing a Serial Windows Connection

    a)     The SmartServer has a serial port labelled Console as shown below, that allows you to connect your computer directly to the SmartServer using a USB-A to USB Micro-B cable. 


    b)     Obtain the COM number for serial port using device manager.

    c)     You may also need to enable the Virtual COM Port (VCP) for the port in question in device manager.

    d)     Start PuTTY.

    e)     On the PuTTY Session page, select serial as the Connection Type,  set the COM number for the Serial Line (such as COM7), and the Speed to 115200. The serial data frame is formatted as 8-N-1 (8 bits, no parity, 1 stop bit) with no flow control, at 115200 baud rate.

    f)     Click Open to connect to the SmartServer.


    g)      Login to the SmartServer IoT as described below.

    2)     Connecting through a LAN 
    a)     Connect both your computer and the SmartServer to the same router as show below, you can connect your computer to the router using an Ethernet cable or using WiFi.


    b)     Your SmartServer IoT will announce itself with the host name smartserver-{nnnnn} as shown on the rear label and your computer can use MDNS (assuming the Bonjour service is installed) to resolve the IP address typically by adding “.local” to the hostname, for example smartserver-65e19.local as shown below:


    c)     Start PuTTY
    d)     On the Session page indicate the host name or IP address of the SmartServer IoT

    e)     Select SSH as the Connection type.

    f)      Click Open to connect to the SmartServer.


    g)      Login to the SmartServer IoT as described below.


    3.      Logging Into the SmartServer IoT

    After connecting using a serial or SSH connection a login prompt shown be shown as below:


    a)     If no login prompt appears, hit the Enter key to display the login prompt.  

    b)     Once you have a Console window displaying a login prompt, log in to the SmartServer with the username apollo, and enter the password ea{nnnnnn}, where {nnnnnn} is the serial number of your SmartServer.  The serial number is located on the back label on the SmartServer. (For example if the serial number is 123456, then the password is ea123456.)


    c)     After a successful login, you should see the following:



    a)     Note the prompt which displays the install code or SID after Apollo@smartserver-.



  10. Provisioning the IOX

    To provision the IoX you will first need to discover the IOX id, then you can use the IOX id to provision the IOX.

    1.     Find the IOX ID

     Subscribe to the “glp/0/./=engine/+/about -v” topic by typing the following shell command:

    mosquitto_sub -t glp/0/./=engine/+/about -v


    This will return the following:

     glp/0/./=engine/iox.410ee7/about {

    “components”: [{

    “name”: “iox”,

    “desc”: “I/O Expander for Apollo”,

    “license”: “Copyright (C) Echelon”,

    “manufacturer”: “Echelon”,

    “version”: “1.00.013”



    Where the IOX id from the above example is iox.410ee7

    Type <Crtl> +  c to quit the subscription.


    2.     Provision the IOX meter


    Set shell variables SID, IOX & UNID.  The SID or install code is shown in the prompt, as illustrated below as “17q2d7a” (and is also on the label at the back of the SmartServer).



    Set the SID shell variable by typing the following shell command with your own SID:



    Set the IOX shell variable by typing the following shell command with your own IOX id:

    IOX= iox.410ee7


    Set the UNID by typing the following shell command:


    Provision the IOX meter by typing the following shell command: 

    mosquitto_pub -t glp/0/${SID}/rq/dev/${IOX}/meter/do -m ‘{“action”:”create”,”args”:{“unid”:”‘${UNID}'”,”type”:”meter”,”provision”:true}}’

  11. Change the Datapoint Monitor Rates

    By default, datapoints are not polled and the monitor rate property needs to be set to a non-zero value accordingly for each datapoint in question.  This can be achieved programmatically using the IAP/MQ API or the IAP/REST API or manually in a console connection using the IAP/MQ API as shown below. The topic is glp/0/${SID}/rq/dev/${IOX}/meter/if/phase/1 (i.e. the first phase of the meter, where the shell variables SID and IOX have been set accordingly as above). The payload determines the monitor parameters for each of the relevant datapoints for the first phase: nvoVoltageRms,  nvoCurrentRms, nvoEngyActive, nvoPowerFactor and nvoLineFrequency.


    1.     Copy the following text and paste it into the console (in PuTTY, this would be using a left click) followed by the enter key.

     mosquitto_pub -t glp/0/${SID}/rq/dev/${IOX}/meter/if/phase/1 –m ‘{“nvoVoltageRms”:{“monitor”:{“rate”:20,”cat”:”data”,”inFeedback”:false,”report”:”change”,”throttle”:0,”threshold”:0}},”nvoCurrentRms”:{“monitor”:{“rate”:20,”cat”:”data”,”inFeedback”:false,”report”:”change”,”throttle”:0,”threshold”:0}},”nvoEngyActive”:{“monitor”:{“rate”:20,”cat”:”data”,”inFeedback”:false,”report”:”change”,”throttle”:0,”threshold”:0}},”nvoPowerFactor”:{“monitor”:{“rate”:20,”cat”:”data”,”inFeedback”:false,”report”:”change”,”throttle”:0,”threshold”:0}},”nvoLineFrequency”:{“monitor”:{“rate”:20,”cat”:”data”,”inFeedback”:false,”report”:”change”,”throttle”:0,”threshold”:0}}}’


    2.  Subscribe to the “mosquitto_sub -v -t glp/0/+/ev/data” by typing the following shell command:

    mosquitto_sub -v -t glp/0/+/ev/data


    You should see datapoint updates as shown below:


    Use <Ctrl> + c to quit the subscription.

  12. Open the Firewall on the SmartServer IoT for MQTT in-bound traffic

    1.     MQTT uses TCP port 1883.  Determine whether this port will be passed by the firewall by typing the following shell command:

     sudo ufw status

    This command provides a list of ports along with the keywords ALLOW and Anywhere for each port that is passed by the firewall.


    2.     If port 1883 is not in the list of allowed ports (by default it is not allowed), then type the following shell command:

     sudo ufw allow 1883


    followed by the following shell command to confirm that 1883 is listed as one of the allowed ports as shown below.:

    sudo ufw status



    Opening port 1883 allows you to run your node application on your development computer, and have access to the source level debugger on that machine. Once the application is deployed for production on the SmartServer, you should delete this rule for security purposes.

  13. Establish the SmartServer IoT IP Address

     establish the IP address assigned to your SmartServer IoT, type the following shell command:

    sudo ifconfig

    Your IP address is displayed as the inet addr for eth0.  Make a note of this IP address.

  14. Create the Node.js Proxy Application

    Although the node.js proxy application could run on the SmartServer IoT, it is easier to use Visual Studio Code on a PC to create and debug the application.  Once the application is proven on the PC the development folder can be transferred to the SmartServer IoT and the application launched under the control of the supervisor, for more details see http://supervisord.org/

    1)     Install Node.js
    a)     Click this link to find the desired version of Node.js:  https://nodejs.org/en/download/releases/

     b)     Scroll down to the Node.js 8.11.3 Carbon release, and click the Downloads link.

     c)     Select the distribution version that matches the operating system of your development computer to download.  
    For example, if your computer runs Window 10, 64-bit, download: node-v8.11.3-x64.msi.  For Mac OS, download: node-v8.11.3.pkg

    d)     Launch the downloaded file (such as node-v8.11.3-x64.msi) and select the defaults for installation.

     e)     Verify that you have installed Node.js by opening a Command Prompt window and typing the following command:

     node –version

    You will see the version of Node.js that is installed on your computer.  The following figure shows the results of this command.  If the command fails, you may need to reboot your computer, and run the command again. 


    2)     Install Visual Studio Code
    a)     Click this link to the VS Code website: https://code.visualstudio.com/

    b)     Click the Download button located at the top right of the web page.

    c)     Download and install the version that matches the operating system of your development computer.

    d)     When you start VS Code, it will attempt to integrate with Git SCM.  If not already installed in your computer, VS Code will encourage installing Git.  You should follow the links suggested by VS Code to install Git.

    3)     Install the npm Intellisense Plugin
    a)     Click this link to the npm Intellisense plugin in the Visual Studio marketplace:  https://marketplace.visualstudio.com/items?itemName=christian-kohler.npm-intellisense

    b)     Download and install the version that matches the operating system of your development computer. 

    4)     Change the VS Code Default Terminal (MS Windows 10 Only)
    a)     In VS Code, select:  File>Preferences>Settings 
    VS Code opens the User Settings for editing.


    b)     In the Search box, type:   terminal.integrated.shell.windows   
    VS Code highlights the setting (shown in the following screenshot).

    c)     To the left of the setting, click Edit>Copy to Settings  to allow you to create an override for the default in the right pane.


    d)     Change the User Setting in the right pane to C:\\WINDOWS\\System32\\cmd.exe (shown in the following screenshot).


    e)     Click File>Save to save your setting override.

    5)     Setup the Development Folder

    a)     Select File > Open Folder, and create a new folder for your development exercises and open the new folder. VS code will use this folder structure to manage work spaces.

    b)     Select File > New File and then type <cntrl>+s to save this new file with the filename: watson_proxy.js

    c)     Select View > Integrated Terminal In the terminal pane of VS Code, type: npm init  
    This command prompts you to provide a variety of information for the application you’re developing.  For this exercise, you can provide the entries highlighted by the green elispes in the following screenshot.  Note that the name entry must be in lower case characters.   


    d)     After entering the values, type yes to the prompt Is this ok?  
    This creates a package.json file for the application that will eventually be used for deployment. 

    e)     The application uses mqtt.js, so in the VS Code Terminal pane, type: npm install mqtt −−save  

    f)      This package provides the support of MQTT, and the –save option causes npm to add the mqtt module dependency to your package.json

    g)     In addition the application uses IBM’s libraries so again in the VS Code Terminal pane type: npm install ibmiotf –-save

    h)     Copy the following code and add it to the file watson_proxy.js


    // SmartServer/WatsonIoT Gateway Proxy service


    // Copyright (c) Adesto Technologies 2019

    // All rights reserved.


    var iotf = require(“ibmiotf”);

    var mqtt = require(‘mqtt’);



    // WatsonIoT Credentials (from your Watson IoT Platform account)


    var WatsonIoTconfigGateway = {

     “org” : <my 6 digit IBM org number>,

      “type” : “EchelonSSIoTGW”,

      “id” : “EchelonSSIoTGW0001”,

      “domain”: “internetofthings.ibmcloud.com”,

      “auth-method” : “token”,

      “auth-token” : “<my authentication token>”,

      “use-client-certs”: false,




    // Get date and time


    function getDateTime() {

      var date = new Date();

      var hour = date.getHours();

      hour = (hour < 10 ? “0” : “”) + hour;

      var min  = date.getMinutes();

      min = (min < 10 ? “0” : “”) + min;

      var sec  = date.getSeconds();

      sec = (sec < 10 ? “0” : “”) + sec;

      var year = date.getFullYear();

      var month = date.getMonth() + 1;

      month = (month < 10 ? “0” : “”) + month;

      var day  = date.getDate();

      day = (day < 10 ? “0” : “”) + day;

      return year + “:” + month + “:” + day + “:” + hour + “:” + min + “:” + sec;




    // SmartServer message broker address and subscription topic

    // Port 1883 needs to be open on the SmartServer – use “sudo ufw allow 1883”


    var apollo_address = “<my SmartServer IoT’s IP Address>”; // When running on the SmartSever should the address should be “smartserver-<my SID>” to avoid certificate errors

    // var apollo_address = “smartserver-17q2d7a”;

    var apollo_topic = ‘glp/0/+/ev/data’;   // Catch all event channel topic, will need filtering for datapoints of interest



    // Supported data points (as per data.message), their values, units and Watson routing parameters


    var datapoints = {

      nvoEngyActive:    { name: “nvoEngyActive”,    value: “data.data”,           units: “kWh”,  route: “nvoenergyactiveupdate”,

                          type: “EchelonGWDevice”,  id: “IOXMeter0001” },

      nvoPowerFactor:   { name: “nvoPowerFactor”,   value: “data.data”,           units: “PF”,   route: “nvopowerfactorupdate”,

                          type: “EchelonGWDevice”,  id: “IOXMeter0001” },

      nvoVoltageRms:    { name: “nvoVoltageRms”,    value: “data.data”,           units: “V”,    route: “nvovoltagermsupdate”,

                          type: “EchelonGWDevice”,  id: “IOXMeter0001” },

      nvoCurrentRms:    { name: “nvoCurrentRms”,    value: “data.data”,           units: “I”,    route: “nvocurrentrmsupdate”,

                          type: “EchelonGWDevice”,  id: “IOXMeter0001” },

      nvoLineFrequency: { name: “nvoLineFrequency”, value: “data.data”,           units: “Hz”,   route: “nvolinefrequencyupdate”,

                          type: “EchelonGWDevice”,  id: “IOXMeter0001” },




    // Establish connection with WatsonIoT


    var watsonHandle = new iotf.IotfGateway(WatsonIoTconfigGateway);



    watsonHandle.log.setLevel(‘debug’); // Set the logging level to debug, by default its ‘warn’


    watsonHandle.connect(); // Connect to Watson


    watsonHandle.on(‘error’, function (argument) {

      console.log(getDateTime() +”: ” + argument); // Could not connect



    watsonHandle.on(‘connect’, function() {

      console.log(getDateTime() +”: ” + “WatsonIoT connected”); // Connected to Watson


      // Establish connection with the SmartServer Gateway message broker


      var client  = mqtt.connect(“mqtt://” + apollo_address);


      client.on(‘error’, function (argument) {

        console.log(getDateTime() +”: ” + argument); // Could not connect to the SmartServer



      client.on(‘connect’, function () {


        console.log(getDateTime() +”: ” + “SmartServer connected”); // Connected to the SmartServer


        client.subscribe(apollo_topic); // Subscribe to the event channel



        // Translate and forward selected messages from SmartServer to WatsonIoT


        client.on(‘message’, function (topic, message) {



          // incoming message from SmartServer is in buffer


          var data = JSON.parse(message); // Parse incoming message

          console.log(getDateTime() +”: ” + “Message from datapoint ” + data.message + ” received”);


          // Process datapoints as they come in…

          // Everything from the “apollo_topic” will arrive,

          // so each message needs to be checked to see if it is of interest


          var payload; // Payload to send to Watson

          var name;    // used to index into datapoints



          // For the purposes of this simple example we are assuming that all datapoints are unique as defined only by data.message

          // which may not be the case, validation should be further refined based on the expected data.topic and data.message

          // for example: glp/0/17q2d7a/fb/dev/iox.411dee/meter/if/phase/1 and nvoVoltageRms


          for (var i in datapoints) { // Run though datapoints to see if this is a known datapoint (as defined by data.message) from the SmartServer

            if (data.message) {

              if (data.message.indexOf(datapoints[i].name) == 0) {


                // We have a match, so build Watson payload


                payload =  ‘{“d”:{‘ +

                  ‘”datapoint”:”‘ + datapoints[i].name + ‘”,’ +

                  ‘”value”:’ + eval(datapoints[i].value) + ‘,’ +

                  ‘”units”:”‘ + datapoints[i].units + ‘”,’ +

                  ‘”topic”:”‘ + data.topic + ‘”,’ +

                  ‘”deviceType”:”‘ + datapoints[i].type + ‘”,’ +

                  ‘”deviceId”:”‘ + datapoints[i].id + ‘”,’ +

                  ‘”location”:{“longitude”:-98.49,”latitude”:29.42}’ +


                name = datapoints[i].name;


                // Publish constructed payload to prescribed WatsonIoT route


                console.log(getDateTime() +”: ” + payload);

                watsonHandle.publishDeviceEvent(datapoints[name].type, datapoints[name].id,

                          datapoints[name].route, ‘json’, payload, 2)








    i)      Modify line 46 with the IP address of your SmartServer

    var apollo_address = “<my SmartServer IoT’s IP Address>”;

    j)      Modify line 4 with your own “org” number

                “org” : <my 6 digit IBM org number>,

    k)     Modify line 19 with your own IBM Watson IoT Platform authentication token that you generated

    “auth-token” : “<my authentication token>”,

  15. Run the Application and Watch the Data Come in

    1)     Click on the Debug icon on the left or press Ctrl+Shift+D, then click on the gear icon as highlight below to configure launch.json (this only needs to be done the once.

    2)     Click on the green triangle “Launch Program” icon.


    3)     After successfully connecting to the IBM Watson IoT Platform, the application will connect to the SmartServer IoT and after a successful connection it will subscribe to the ‘glp/0/+/ev/data’,  wait for updates, check they are from known data points and send the updates to IBM Watson IoT Platform.  You can check progress in the Debug Console frame and on the IBM Watson IoT Platform as show below.


Join The Discussion