Documentation Center

relayr Edge Agent and the Dell/Intel/Bosch IoT Starter Kit

Introduction

The relayr Edge Agent is a Fog Computing software component that runs on edge devices that link sensor and/or actuator nodes to a public and/or private cloud. In this particular instance, we have it running on a Dell IoT Gateway 5100. The relayr Edge Agent is intended for use by developers, industrial engineers, facility managers, system integrators, etc., who are working on enterprise IoT deployments.

Installation

You should have received the gateway pre-configured and properly set up. For the sake of completeness, we detail the complete setup in this document, from unboxing to installing the relayr Edge Agent. Unless you want to redo the software installation process, you can safely skip to Edge Agent Initial Configuration.

Requirements

To set up the gateway, we need to plug it in. First we need the following items:

  • HDMI monitor.
  • USB keyboard.
  • Dell 65W power supply.
  • A computer with a web browser that can access the gateway through the network.

Gateway initial setup

Follow these steps to install the relayr Edge Agent on the Dell IoT Gateway 5100, which comes with WindRiver Linux Operating System (OS) preinstalled:

  1. Unboxing and plugging it in:
    • Remove the Dell Edge Gateway 5100 from the box. You will not need anything else from the box for this process.
    • Remove the dust covers from the DC power, HDMI sockets and one USB port on the back, and the first network port on the front.
      All ports covered

      Remove dust cover from DC power

      Remove dust cover from HDMI

      Remove dust cover from USB

      Remove dust cover from network port

    • Attach a Dell 65W power supply and an HDMI cable to a monitor and USB keyboard, and attach an ethernet cable to an Internet connection.
      Attach power supply

      Attach HDMI cable

      Attach USB keyboard
    • Switch it on.
    • When the login prompt appears, log in as user root with password root. Note that you should change the root user password after setting up the gateway. The default login is insecure. Also, as elementary security rule of thumb, root login should be avoided and disabled when accessing the gateway via SSH.
    • Windriver comes with outdated versions of some of the software we need for the Edge Agent, which must be removed. Remove IoT developer hub, Mosquitto MQTT broker, Node-RED and nodejs:
      smart remove iot-developer-hub mosquitto node-red node node-npm
      
      Enter y when prompted to remove the packages.
  2. Add the relayr RPM repository:
    smart channel --add https://packages.relayr.io/windriver/relayr.repo
    
    Enter y when prompted to include the relayr RPM Repository channel.
  3. Add the relayr GPG key to the keyring (trusted repositories):
    wget https://packages.relayr.io/windriver/relayr-pub-GPG.txt  
    rpm --import relayr-pub-GPG.txt && rm relayr-pub-GPG.txt  
    
  4. Run a smart update and upgrade and then install the Starter Kit package:
    smart update && smart upgrade
    smart install relayr-dsk  
    
    Enter y when prompted to confirm changes.
  5. Shut down the gateway:
    shutdown -h now
    
  6. Once the light on the power button has gone dark, the gateway can be unplugged. Alternatively, you can gently press the power button to shut down the gateway.
  7. Done: now the Edge Agent is installed on the gateway and is ready for configuration and onboarding by the end user.

Edge Agent initial configuration

Requirements

  • HDMI monitor.
  • USB keyboard.
  • Dell 65W power supply.
  • A computer with a web browser that can access the gateway through the network.

Setup

Follow these instructions in order to onboard the Edge Agent on your Dell Edge Gateway 5100:

  1. Unboxing and plugging it in:
    • Remove the Dell Edge Gateway 5100 from the box.
    • Remove the dust covers from the DC power, HDMI sockets and one USB port on the back, and the first network port on the front.
      All ports covered

      Remove dust cover from DC power

      Remove dust cover from HDMI

      Remove dust cover from USB

      Remove dust cover from network port

    • Attach a Dell 65W power supply and an HDMI cable to a monitor and USB keyboard, and attach an ethernet cable to an Internet connection.
      Attach power supply

      Attach HDMI cable

      Attach USB keyboard
    • Switch it on.
    • When the login prompt appears, log in as user root with password root. Note that you should change the root user password after setting up the gateway. The default login is insecure. Also, as elementary security rule of thumb, root login should be avoided and disabled when accessing the gateway via SSH.
  2. Find the IP address of the machine (this assumes you have connected to a LAN with DHCP):
    ifconfig  
    
    See the section below for instructions on how to parse the output for the IP address.
  3. Connect to the machine via SSH from another computer. With the above IP address, this is:
    ssh root@68.10.29.109
    
    You’re now logged in as root via SSH.
  4. Upgrade packages to the latest versions:
    smart upgrade
    
  5. In a browser, log in to the relayr Developer Dashboard.
  6. Go to Account and copy the contents of the TOKEN field, excluding the Bearer prefix. (e.g. jKEkJSGO7bUJp5alU5voM0qp0V3l3pOBYzpzO4hLBeUgsQuFckLXS2rts4hoRbj9)
  7. Configure your Edge Agent using vertex-configure. This script registers your Edge Agent with your relayr account:
    vertex-configure <Edge Agent name> <Edge Agent location> <relayr API token> 
    
    where:
    • <Edge Agent Name> is the name given to your Edge Agent device. This is used in the Edge Agent API.
    • <Edge Agent Location> is an identifier of the location (network, facility, room, etc) where your Edge Agent device is located. This is used in the Edge Agent API.
    • <relayr API token> is the token obtained above in the relayr dashboard.
  8. Reboot the gateway:
    reboot
    
  9. Done.

Parsing ifconfig output

Here is an example output from running ifconfig. The IP address will depend on your specific network setup.

br-lan    Link encap:Ethernet  HWaddr f4:83:99:02:F9:1C  
          inet addr:192.188.1.1  Bcast:192.168.1.255  Mask:255.255.255.0  
          UP BROADCAST MULTICAST  MTU:1500  Metric:1  
          RX packets:0 errors:0 dropped:0 overruns:0 frame:0  
          TX packets:0 errors:0 dropped:0 overruns:0 carrier:0  
          collisions:0 txqueuelen:0   
          RX bytes:0 (0.0 B)  TX bytes:0 (0.0 B)  

eth0      Link encap:Ethernet  HWaddr 8F:83:99:02:F9:1C  
          inet addr:68.10.29.109  Bcast:10.22.90.255  Mask:255.255.254.0  
          inet6 addr: fe80::f68e:38ff:fed5:a6c/64 Scope:Link  
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1  
          RX packets:307300 errors:0 dropped:184 overruns:0 frame:0  
          TX packets:423858 errors:0 dropped:0 overruns:0 carrier:0  
          collisions:0 txqueuelen:1000   
          RX bytes:38207350 (36.4 MiB)  TX bytes:50971843 (48.6 MiB)  
          Interrupt:106 Base address:0xe000   
         
eth1      Link encap:Ethernet  HWaddr g6:8e:38:a7:0a:6d   
          UP BROADCAST MULTICAST  MTU:1500  Metric:1  
          RX packets:0 errors:0 dropped:0 overruns:0 frame:0  
          TX packets:0 errors:0 dropped:0 overruns:0 carrier:0  
          collisions:0 txqueuelen:1000   
          RX bytes:0 (0.0 B)  TX bytes:0 (0.0 B)  
          Interrupt:107 Base address:0x2000   

lo        Link encap:Local Loopback  
          inet addr:127.0.0.1  Mask:255.0.0.0  
          inet6 addr: ::1/128 Scope:Host  
          UP LOOPBACK RUNNING  MTU:65536  Metric:1  
          RX packets:40862 errors:0 dropped:0 overruns:0 frame:0  
          TX packets:40862 errors:0 dropped:0 overruns:0 carrier:0 
          collisions:0 txqueuelen:0   
          RX bytes:17931055 (17.1 MiB)  TX bytes:17931055 (17.1 MiB)  

wlan0     Link encap:Ethernet  HWaddr 59:f1:89:02:83:67    
          UP BROADCAST MULTICAST  MTU:1500  Metric:1  
          RX packets:0 errors:0 dropped:0 overruns:0 frame:0  
          TX packets:0 errors:0 dropped:0 overruns:0 carrier:0  
          collisions:0 txqueuelen:1000   
          RX bytes:0 (0.0 B)  TX bytes:0 (0.0 B)  

The IPv4 address will follow eth0 in the inet addr field. You can extract it with:

ifconfig eth0 | grep -i 'inet addr' | cut -f 2 -d : | cut -f 1 -d ' '

which prints: 68.10.29.109.

Adding devices to your Edge Agent

Now you can complete the setup process by associating your devices with the Edge Agent. By doing so, you will ensure that your device data is communicated to the Cloud via the Edge Agent. This section is written as a general guideline for any device running on your gateway.

Get Edge Agent UUID

In order to associate a device with the Edge Agent, you will need the Edge Agent’s device ID. Log in to the Gateway running the Edge Agent via SSH and run the following command:

cat /etc/vertex/config | sed -n '/username/p' | cut -f 2 -d ':' | sed 's/[",]//g'

This will print out the UUID from the Edge Agent’s config file without any extraneous characters.

Create a device in the Developer Dashboard

Now you must add your device to the relayr Platform via the Developer Dashboard or via API call. This will create a representation of your device in the Cloud, which can then be associated with the Edge Agent. Follow these steps:

  1. Log in to the Developer Dashboard.
      NOTE:   You must log in to the Dashboard using the same account as the one used in step 4 of the Edge Agent Setup process. All devices that will be associated with the Edge Agent must be on the same account as the Edge Agent itself.
  2. In the left-hand column, click Devices. Then, at the bottom, click Add Device.
    Devices section
    Add device
  3. The Add New Device screen will load. Here you can select a device model for the device you want to add (such as Intel® Edison or Bosch XDK). If you know which device model corresponds with your device, you can either type the name of the model in the search bar or click on one of the four tabs (“By relayr”, “By Partners”, “By the Community”, or “By me”) to look for it. If not, you can create your own device model — click here for more information.
    Choose a device model
    If you want to create a device without a model, click the Continue without a model button at the bottom of the screen. The cloud will still be able to receive data from your device, but you will not be able to send commands or configurations from the Dashboard.   NOTE:   You will not be able to change the device’s model after adding it to the Cloud.**
  4. The Generated Firmware screen will load. On this screen, the system will generate firmware code to be uploaded to your device. You can choose to generate code for devices running on Arduino, NodeJS or Python from the dropdown above the generated codeblock. Copy and paste the generated firmware into a file and save it on your device.
    Generated Firmware

  5. When you install the firmware on your device, please be sure to change the value of the MQTT server in the code from mqtt.relayr.io to the IP address where the Edge Agent is running, which you retrieved during the initial setup using ifconfig.
  6. From this screen, you can also test your device to make sure that it’s working correctly. Click the link to download libraries/dependencies for the firmware and then install it on your device. Once your device is turned on, follow the instructions underneath the download link and click Test.
    Step 4
    On the Test Device screen, there are two panes at the top: Select reading, which allows you to visualize the readings defined in the device model, and Select command, which allows you to test the commands that your device can receive. At the bottom of the screen is the Device log, which logs the data sent by the device. Click It works! if everything is working properly, or click It doesn’t work for troubleshooting tips.
    Test device

  7. Click Finish.
  8. Enter a name for your device.
  9. Click Go to device.

Your device is now stored in the relayr Cloud. All that’s left is to bind it to the Edge Agent.

Associate device with the Edge Agent

The last step in this process is to send a request to the relayr API to associate your device with the Edge Agent.

Parameters

The following parameters are required for the Edge Agent association request:

  • Edge Agent Id: UUID of your Edge Agent gateway, which you retrieved in the first step of this section.
  • Authorization Token: A token that authorizes you to make API calls to your user account and devices that you manage. You can find this on the Account page of the Developer Dashboard. It is formatted as Bearer followed by a random string.
  • Device Id: UUID of the device that will be associated with the Edge Agent. You can find this by going to the Devices section of the Developer Dashboard and clicking on the device you added in the previous step, then clicking on the Device Settings icon (the gear icon in the top right).
  • User: Username for connecting to the MQTT broker. In this case, it is the same as the Device Id.
  • Password: Password for connecting to the MQTT broker. You can find this in the Device Settings menu as described above.

Using cURL

Open the terminal (or CLI) and paste the following cURL call. Replace the variables header, deviceId, and credentials with your own, insert your Edge Agent ID after /vertices/, and press enter:

 curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "authorization: <Authorization Token>" -d '{"deviceId": "{deviceId}", "transport": "mqtt", "configuration": {}, "credentials": {"user": "{deviceId}", "password": "{mqtt_password}"}}' https://api.relayr.io/vertices/{edgeAgentId}/devices

Using Postman

The POST request to associate your device with the Edge Agent can also be done using Postman. If you are not familiar with Postman, you may have a look at this tutorial.

Fill in the following parameters to make the request:

POST URL:

https://api.relayr.io/vertices/{your Edge Agent Id}/devices

Headers:

  • Authorization: Bearer A98H8F74vHVH5z77mCukEgurEcXpOF6869qCrNdM63WwVw5YydS4Cv4oJUYMBal1 — use your own authorization token instead
  • Content-Type: application/json

Body:

{
  "deviceId": "7gdc2b5f-a440-44ae-bcb1-b3f4bcabd5b6",
  "transport": "mqtt",
  "credentials": {
    "user": "brian",
    "password": "ILoveDocumentation"
  }
} 

Installed Software

The following software components are included in your Edge Agent installation:

Broker

The relayr Edge Agent includes its own MQTT broker, which is an entity that passes messages between publishers and subscribers. In this context, the publishers and subscribers are devices that are connected to your Edge Agent gateway. Using the MQTT protocol, the broker listens for messages published by the connected devices and routes them to any devices that are subscribed to receive that data stream. The Edge Agent broker facilitates these interactions among devices on your local network so that they can communicate with each other within a shorter loop, even in the absence of an internet connection.

System Health Adapter

The System Health Adapter is a virtual device that acts like other data-producing devices. It reads system health information on the gateway and sends it as readings to the relayr cloud via the Edge Agent. By default these readings are sent every 5 seconds. The following data is included in each reading:

  • uptime: number of seconds since the gateway was booted.
  • memTotal: total system memory of the gateway, in bytes.
  • memActive: memory currently being used on the gateway, in bytes.
  • memAvailable: memory available for use, in bytes.
  • filesys: an array of file systems. Each entry in the array has the following attributes:
    • fs: file system device.
    • size: total size of the file system, in bytes.
    • used: size of data stored in the file system, in bytes.
    • use: percentage of the file system which is currently being used.
    • mount: mount point of the file system.
  • cpuTemp: CPU temperature, in degree Celsius.
  • diskReads: number of disk read operations since boot.
  • diskWrites: number of disk write operations since boot.
  • fsReadBytes: number of bytes read from disk since boot.
  • fsWriteBytes: number of bytes written to disk since boot.
  • cpuLoad: current CPU load, as a percentage from 0 to 100.
  • networks: an array of network interfaces. Each entry in the array has the following attributes:
    • iface: name of the interface.
    • rx: number of bytes received by this interface since boot.
    • tx: number of bytes sent by this interface since boot.
    • ipv4: IPv4 address of the interface, if applicable.
    • ipv6: IPv6 address of the interface, if applicable.
    • mac: MAC address of the interface.
Edge Agent health in the relayr developer dashboard

Node-RED

Node-RED is a visual data flow tool for wiring nodes in the Internet of Things. These nodes can be virtual and/or physical. Node-RED is included with the Edge Agent so that the user can connect different sources and sinks of data flows. Custom logic can be applied to any data flow. e.g., the data sent by the sensors that come in the Intel® Edison and/or the Bosch XDK.

Node-RED can be accessed via web interface on your Edge Agent installation at the following address: http://localhost:1880.

Note that by default there is no authentication mechanism enabled in Node-RED. Please consult the Node-RED security documentation for instructions on how to secure your Node-RED instance.

Alternatively you can access Node-RED at http://<Edge Agent IP address>:1880/. It is totally up to your networking policy to determine if allowing access to Node-RED remotely is reasonable.

Updating the Edge Agent in your Dell gateway

If an update is released for the Edge Agent, then follow these steps to perform an update:

  1. Power on your Gateway and connect it to the internet.
  2. Log in with the Gateway user credentials.
  3. Run a smart update and upgrade:
    smart update && smart upgrade
    
    Enter y when prompted to confirm changes.
  4. Done: The Edge Agent is now updated.

Factory reset

In the event that you need to reset the gateway to the factory default settings, please reboot the gateway and press F12, then select the Factory Reset option when prompted.

© 2017 relayr · Imprint