Quick Start Guide

This guide will help you to set up thing’s development environment, then build and run a thing application.


Configuring the KNoT Gateway

Flashing the KNoT Gateway

Execute the following steps if you have a Raspberry Pi that is not flashed with a KNoT Gateway image.

You will need an SD Card reader to install the image.

  1. Download the gateway image (.img file) for your gateway from the releases webpage.

  2. Download and install balenaEtcher.

  3. Connect an SD card to your computer.

  4. Open balenaEtcher and select the downloaded .img file.

  5. Select the target SD card.

  6. Flash it.

  7. Connect the SD card to your gateway.

You now have a flashed KNoT Gateway! Let’s configure it!

Note

Experienced users may follow Raspberry Pi’s official installing tutorial for more flashing options.

Adding Gateway to KNoT Cloud

  1. Connect the KNoT Gateway to the same network as your computer (by using an ethernet cable).

  2. Access the gateway with http://knot.local and start the setup wizard.

    Gateway: Setup Wizard
  3. Use the default cloud settings and proceed.

    Gateway: Cloud setup
  4. Create your KNoT Cloud user and sign in to it.

    Gateway: Sign in to cloud
  5. Create a new gateway at the cloud and name it.

    Gateway: Create new gateway
  6. Wait for the gateway to reboot.

  7. Log in with the email and password you just signed up at KNoT Cloud.

    Gateway: Sign in

    Note

    As there are no KNoT Things connected to your gateway, the message “No nearby devices found.” will be displayed


Thing’s Development Environment

In order to compile and flash applications for the KNoT Thing, it’s necessary to set up the development environment.

The fastest way to do it is by using a pre-built Docker image.

  1. Download and install Docker.

  2. In a terminal, get the latest KNoT Thing SDK Docker environment image.

    docker pull cesarbr/knot-zephyr-sdk:latest
    

Note

Docker is only available for Linux based systems, macOS 10.11+ and Windows 10 Pro/Enterprise.


Programming the KNoT Thing

Compiling project

  1. Clone the zephyr-knot-sdk repository to your home folder.

    git clone https://github.com/CESARBR/zephyr-knot-sdk.git ~/zephyr-knot-sdk
    
  2. Navigate to the application project directory.

    cd ~/zephyr-knot-sdk/apps/hello-dongle
    
  3. Run environment image.

    docker run -ti -v $(pwd)/:/workdir cesarbr/knot-zephyr-sdk:latest
    
  4. From the container, build the project for the target board.

    • If using the KNoT DK:

      [user@container] $ knot make --board dk
      
    • If using the KNoT Dongle:

      [user@container] $ knot make --board dongle
      

Flashing board

  1. From your project folder, export the generated files to a output folder.

    [user@container] $ knot export output/
    
  2. Install nRF Connect.

  3. Open nRF Connect and add the Programmer App.

    nRF Connect: Add Programmer
  4. Launch the Programmer App.

    nRF Connect: Launch Programmer
  5. Connect the device to a USB port.

    Tip

    If using the KNoT Dongle, press the RESET button to get into DFU mode. The red LED will start to blink.

  6. Select the target device.

    nRF Connect: Select device
  7. Define the HEX file to be flashed.

    Click Add HEX file and select the boot_sgn_apps.hex file that was exported to the output/ folder.

    nRF Connect: Add HEX file

    Note

    The path for the hex file should be ~/zephyr-knot-sdk/apps/hello-dongle/output/boot_sgn_apps.hex.

  8. Flash the project.

    Click Write and wait for the board to be flashed. The red LED will stop blinking for the Dongle.


Configuring the Thing network

In this section we are going to configure the Thing to automatically connect to the Gateway mesh network.

  1. Make sure that the device Thing is on the Setup Mode, indicated by the alternating LEDs.

    KNoT Dongle: Setup mode

    KNoT Dongle: Setup mode

    KNoT DK: Setup mode

    KNoT DK: Setup mode

  2. Download the mobile KNoT Setup App and install it to your smartphone (Android only).

  3. Connect your smartphone to the same Wi-Fi network that you connected your Gateway to.

  4. Open the KNoT Setup App, and select your gateway under the Connected tab

    Setup App: Connected Gateways
  5. Login with your user credentials

    Setup App: Gateway login
  6. Select the target Thing under the Unregistered tab

    Setup App: Unregistered Things
  7. Wait for the OpenThread configurations to be transferred.

    Setup App: OpenThread settings
  8. Power off and on the KNoT Thing.


See connected Things

If all the steps were followed correctly, it will be possible to see that the KNoT Thing is connected to the target Gateway.

To do so:

  1. Access the gateway web page with http://knot.local.

  2. Login with your user credentials.

  3. Look for your connected thing and see the value being updated.

WebUI connected devices

Representing an Application on KNoT Cloud

  1. Log-in to KNoT Cloud.

    KNoT Cloud UI login page
  2. Go to Apps page and create an application.

    KNoT Cloud UI applications page
  3. Set a name to your application.

    KNoT Cloud UI applications modal
  4. Download the application credentials.

    KNoT Cloud UI download app credentials
  5. The application credentials should look like:

    {
      "type": "knot:app",
      "metadata": {
        "name": "Hello Application"
      },
      "knot": {
        "id": "3c92790f-f265-46c9-bbf8-e440f0447587",
        "isThingManager": false
      },
      "token": "826faa7d545e39c8b2a198c74d0da54f95dfea55"
    }
    

Interacting with an Application through KNoT Cloud SDK

  1. Download and install NodeJS and NPM.

  2. Create a new directory and start a NodeJS application on it.

    mkdir my_knot_app
    cd my_knot_app
    npm init -y
    
  3. Install the KNoT Cloud SDK for JavaScript.

    npm i -s @cesarbr/knot-cloud-sdk-js
    
  4. Create an index.js file and import the knot-cloud-sdk-js library.

    const { Client } = require('@cesarbr/knot-cloud-sdk-js');
    
  5. Create a client connection instance with the KNoT Cloud WebSocket server.

    const client = new Client({
      hostname: 'ws.knot.cloud',
      protocol: 'wss',
      port: 443,
      pathname: '/ws',
      id: '3c92790f-f265-46c9-bbf8-e440f0447587', // APP ID
      token: '826faa7d545e39c8b2a198c74d0da54f95dfea55', // APP TOKEN
    });
    

    Warning

    Update the id and token fields with the application credentials that you have received.

  6. Get the KNoT Thing’s ID from the gateway interface.

    KNoT Thing ID
  7. Send setData command to turn off the KNoT Thing’s LED when the connection is established.

    const data = [
      {
        sensorId: 0, // LED's sensorID
        value: false, // New LED's value
      },
    ];
    
    client.on('ready', () => {
      client.setData('2828b4c983f2d9d1', data); // Send setData command, passing to it the KNoT Thing's ID and the data.
    });
    
    client.on('sent', () => {
      client.close(); // close the connection after command is sent
    });
    
    client.on('error', (err) => {
      console.log(err);
      console.log('Connection refused');
    });
    
    client.connect();
    

    Note

    Use the KNoT Thing’s ID in lowercase like: 2828b4c983f2d9d1.

  8. Listen to data events sent by the KNoT Thing. These events can be listened to by registering a handler with on('data').

    client.on('ready', () => {});
    
    client.on('data', (data) => {
      if (data.from === '2828b4c983f2d9d1') {
        console.log(JSON.stringify(data, null, 2));
      }
    })
    
    client.on('error', (err) => {
      console.log(err);
      console.log('Connection refused');
    });
    
    client.connect();
    

    Note

    This event listener will receive every data events sent by all things associated with your user. To filter them, you just need to compare the from field with the KNoT Thing ID you want to listen.

  9. The expected incoming data should look like:

    {
      "from": "2828b4c983f2d9d1",
      "payload": {
        "sensorId": 0,
        "value": false,
      }
    }
    
  10. Run the example.

    NODE_TLS_REJECT_UNAUTHORIZED=0 node index.js
    

    Note

    The environment variable NODE_TLS_REJECT_UNAUTHORIZED need to be set to ‘0’ in order to disable the TLS certificate verification, since you are connecting to a WebSocket Secure server. It should be used only on development.