Edge Tutorial

Pre-requisites:

  1. You have created a developer account with ClearBlade (https://platform.clearblade.com).
  2. You have logged in with the developer account and created a System on the ClearBlade platform.
  3. You have created User accounts on the ClearBlade platform.

STEP 1: Create an Edge

  1. On your ClearBlade Platform, Click on the + New button which is highlighted below.

  2. Give a name to your edge with a suitable description and click on “Generate” button to generate a token.

  3. Finally, click on the Create button to create the edge.

  4. Once, you click on the Create button, Show Edges button will appear on your System.

  5. You can click on the Show Edges button to view the list of Edges that you have created.

  6. Once you click on the Show Edges button, you will see the Edges that you have created on your system.

  7. You can view the settings for an edge, by clicking on the Settings icon button to the right of a particular Edge.

  8. You can view these important settings for your Edge.

  9. This concludes STEP 1 of Creating a new Edge and viewing important settings about the newly created Edge. This information will be used in subsequent steps.

STEP 2: Install an Edge

  1. If your Edges are not currently displayed, click on the Show Edges button

  2. Click on the Settings icon button for the Edge that was created in the previous step

  3. Click on the Config tab within the settings dialog

  4. Select the operating system the Edge will be installed on from the Target dropdown
    If the target operating system you wish to install the edge on is not listed, we recommend you install VirtualBox (or any other virtualizer) and create a virtual machine with one of the target operating systems listed in the dropdown.

  5. Once the operating system has been selected, commands will be displayed that can be used to download, unzip, install and modify permissions for an edge installation

  6. Open a terminal prompt on the target operating system and download the Edge executable using the Download command listed

    • ex. curl -sSL -O -L https://github.com/ClearBlade/Edge/releases/download/3.2.0/edge-linux-amd64.tar.gz
    • For your convenience, you can also click the Copy icon to have the command copied to your clipboard.
  7. From the terminal prompt on the target operating system, unzip the Edge executable using the Unzip command listed

    • ex. tar xzvf edge-linux-amd64.tar.gz
    • For your convenience, you can also click the Copy icon to have the command copied to your clipboard.
  8. From the terminal prompt on the target operating system, install the Edge executable using the Install command listed

    • ex. sudo ln -f edge-3.2.0 /usr/local/bin/edge
    • For your convenience, you can also click the Copy icon to have the command copied to your clipboard.
  9. From the terminal prompt on the target operating system, modify the permissions of the Edge executable using the Permission command listed

    • ex. sudo chmod +x /usr/local/bin/edge
    • For your convenience, you can also click the Copy icon to have the command copied to your clipboard.

STEP 3: Connect an Edge

  1. If your Edges are not currently displayed, click on the Show Edges button

  2. Click on the Settings icon button for the Edge that was created in the previous step

  3. Click on the Config tab within the settings dialog

  4. Scroll to the bottom of the Config tab within the settings dialog until the Generate Startup Command section is displayed

  5. Enter the IP address of the machine the Edge was installed on into the Edge IP field

  6. Click the Copy icon to the far right of the Start script field to have the Edge startup command copied to the clipboard

  7. From the terminal prompt, cd into the directory where Edge was installed (typically /usr/local/bin on Mac OS and Linux)
    cd /usr/local/bin

  8. Paste the startup command into the terminal window and run it

user$  ./edge -parent-system=<SYSTEM_KEY> -novi-ip=<CLEARBLADE_PLATFORM_IP> -edge-ip=<EDGE_IP> -edge-id=<EDGE_NAME> -edge-cookie=<EDGE_TOKEN> -local

Flags:

A complete listing of the flags that can be used when starting the Edge can be found here

  1. -parent-system
    • The System Key for parent system on which Edge is created.
  2. -novi-ip
    • The IP address/Hostname of your ClearBlade Platform (Without ‘Http://’ or ‘Https://’)
  3. -edge-ip
    • The IP address/Hostname of your Edge (Without ‘Http://’ or ‘Https://’)
  4. -edge-cookie
    • Click on the Show Edges button for the appropriate System and view the settings for an edge, by clicking on the Settings icon button.
    • The -edge-cookie is the Token represented in the Settings window below.
  5. -edge-id
    • Click on the Show Edges button for the appropriate System and view the settings for an edge, by clicking on the Settings icon button.
    • The -edge-id is the System Name represented in the Settings window below.

STEP 4: Add & Customize Devices

Add Devices

  1. Click on the Auth button to navigate to the Auth section of your System.

  2. Click on the highlighted Menu button to view the different Auth tables.

  3. Once you click on the Menu button, you can see that, you can create 4 types of Auth tables.

    • Users
    • Devices
    • Edges
    • Roles
  4. Click on the Devices item from the Menu, as highlighted above.

  5. You can add a new Device by clicking on the + Device button, as highlighted below.

  6. Select your preferences and click on the Create button.

    • Name: TemperatureSensor
    • Type: Home Temperature Sensor
    • State: Blank
    • Enabled:YES
    • Allow Key Authorization:YES
    • Allow Certificate Authorization:YES
  7. You will see a newly created device as above.

    Additional Functionality

    Update Device State

  8. Device state is an important column of the newly created device. It represents the current state of the device and it accepts String values.

  9. In the case of the Temperature Sensor device, you can change the state, by double-clicking the state column in this row.

  10. Lets assume the temperature state be in units of Fahrenheit. You can set the Temperature Sensor state to be 100 Fahrenheit as highlighted above.

    Add columns to Devices

  11. You can add some additional properties to your device by clicking on the + Column button as highlighted above.

  12. This will add some properties as Columns to your Device table.

  13. Suppose, you want value of the temperature sensor to be in different units of measure. You can add additional columns to represent the different units of measure.
    NOTE: Additional columns can accept only String type values.

  14. In the above example, we also want the value of temperature sensor to be in degrees celsius along with original value of degrees Fahrenheit . We have added a column named Celsius which accepts data of type String and it shows us the degrees Celsius value of the Temperature Sensor device.

  15. You can see that the additional column has been added at the end of the columns list.

    Delete Device

  16. You can also delete the device by selecting the checkbox in front of the device that you want to delete and clicking on the - Device button.

  17. Once you delete a device, you will see a success notification on top right corner of your screen.

STEP 5: Message at Edge

Messaging at the Edge is similar to Messaging using the ClearBlade platform. This minimizes developer ramp-up time by sharing a familiar design.

If you are new to Messaging via the ClearBlade Platform, please see the Messaging Docs

A key difference will be that we need to acquire the IP Address of our Edge beforehand. Follow these steps to acquire the IP Address:

Linux or Mac OS

ifconfig

Windows

ipconfig

Raspberry PI

Find the address of pi: https://www.raspberrypi.org/documentation/remote-access/ip-address.md

With ClearBlade, you can use popular languages such as Java, C#, JavaScript, C, Python, iOS, Android and many more to utilize messaging with the ClearBlade Edge. Just choose your language and follow the tutorials for your ClearBlade SDKs. In this tutorial, we are going to use JavaScript to create a simple web application that can be used to Publish a message on the Edge. Perform the following installation procedures and use the code snippet to Publish a message on the Edge.

Installation

  1. Create a project directory/folder with name webapp.

  2. Go to webapp folder and Create a index.html file.

  3. Open the index.html file in any text based editor of your choice and Copy & Paste the following code snippet.

<!DOCTYPE html>
<html lang="en">
<head>
  <title>Sample Publish App</title>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="stylesheet" href="http://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css">
  <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.12.2/jquery.min.js"></script>
  <script src="http://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/js/bootstrap.min.js"></script>
  <script type="text/javascript" src="ClearBlade.js"></script>
  <script type="text/javascript" src="mqttws31.js"></script>
</head>
<body onload="startup()">
    <div class="container text-center">
 <form class="form-horizontal" role="form" style="margin-top:20px;">
          <h3>Messaging Sample - Publish App</h3>
               <div class="form-group">
      <label class="control-label col-sm-2">Message to Publish:</label>
      <div class="col-sm-10">
        <input type="text" class="form-control" id="msgPub" placeholder="Enter Message to Publish" />
      </div>
    </div>
      <div class="form-group">
      <div class="col-sm-offset-2 col-sm-10">
        <button type="button" class="btn btn-primary"  onclick="publishMsg (event)">Publish</button>
      </div>
    </div>
  </form>
</div>
</body>
</html>
  1. Download the ClearBlade.js file and place inside your project directory.

  2. Download the mqttws31.js file and place it inside your project directory.

Usage

  1. Initialize ClearBlade.init() from the below JavaScript code snippet, pointing to your Edge correctly. (Edit the initOptions to appropriate values)

  2. You need to copy and paste the following Javascript snippet into the <head> section of the index.html file that you just created.

<script>
var cb = new ClearBlade();
var topic = "mytopic";

/* Example
  Var initOptions = {
    URI : ‘http://192.168.0.92’,
    messagingURI : ‘192.168.0.92’,
    messagingPort: 8904,
    useMQTT: true,
    cleanSession: true,
    systemKey: ‘f887dxxxxxxxxxxxxxxxxxxxxxxx01’,
    systemSecret: ‘F887DCxxxxxxxxxxxxxxxxxxxxxx01’
    Email: ‘fan@cb.com’
    password: ‘password’
  }
*/

var initOptions = {
  URI : <IP_ADDRESS_OF_EDGE>, 
  messagingURI : <IP_ADDRESS_OF_EDGE>,  
  messagingPort:<MESSAGE_PORT>, 
  useMQTT: true,
  cleanSession: true,
  systemKey: <EDGE_SYSTEM_KEY>, 
  systemSecret: <EDGE_SYSTEM_SECRET> ,
  email:<USER_EMAIL>,
  password:<USER_PASSWORD>
};


var startup= function(){
    var initCallback = function(err, data){
        if(err) {
         console.log("init failed")
        } else {
         connectToMessaging()
        }
};
initOptions.callback = initCallback;
cb.init(initOptions);
}
var connectToMessaging = function() {
    var connectCallback = function(data) {
        console.log("connected to messaging");
        //Write your code here   
    }

    //Set “useSSl”:true if your platform url starts with “https://” or else false
    messaging = cb.Messaging({"useSSL":false}, connectCallback);
    console.log("connecting to messaging");
};

var publishMsg = function(event){
    var msg = document.getElementById("msgPub").value;
    console.log("publishing to: "+topic+"  with message: "+msg);
    messaging.publish(topic, JSON.stringify(msg));        
}
</script>

The javascript code will publish a message to a topic called mytopic on your edge.
3. Open index.html in your web browser
4. You can verify the messages getting published on your Edge by following below steps:

  1. Go to your System on ClearBlade platform.

  2. Login to your Edge, by clicking on the Edge and enter the correct credentials.

  3. You will see an Edge platform similar to following.

  4. Go to Messaging to tab by clicking on the Message button.

  5. Click on the Subscribe button, this will subscribe you to mytopic on the Edge.

  6. Open the “index.html” file, that you just created, in a web browser.

  7. Input your message in the Message to Publish: text box and click on the Publish button.

  8. You will see a message getting published on your Edge under the topic mytopic.

  9. You have successfully completed the Messaging at Edge tutorial