Back to blog Back to blog

Connecting Your First Device to WolkAbout IoT Platform with Python Connector

Connecting Your First Device to WolkAbout IoT Platform with Python Connector

Objectives and Goals

This tutorial will guide you through the process of connecting your device to WolkAbout IoT Platform. It covers the following steps:

  • Creating new device instance
  • Connecting the device to WolkAbout Platform via Python connector
  • Sending readings/data from the device to the Platform
  • Monitoring and controlling the device from the dashboards
  • Changing configuration options on your device
  • Monitoring and controlling the device using a mobile app (Android or iOS)

Before You Begin

It is assumed you have registered an account at demo.wolkabout.com (WolkAbout IoT Platform free instance) and successfully logged in.

Guides

To explore all the features of the web and mobile applications, and to get more detailed info, please read our User Guides.

Another useful guide for adding your first device to the Platform, Getting Started Tutorial, can be found in the web app upon clicking on the Help icon in the bottom left corner of the main menu, or User/Help submenu with other available guides.

Note: Prior to creating manifest, make sure you have created all the custom reading types your device uses. For more information on this, go to our User Guides.

Step 1 - Create Device Manifest

  • Choose Devices from the left side menu
  • Go to Device manifest tab
  • Click on + button to add a new manifest

You will be presented with the option to create a device manifest from scratch or upload an existing manifest.

The rest of this step will go through the process of creating a device manifest from scratch.

If you want to skip this process, download the WolkConnect-Python repository and upload the _full_examplemanifest.json file located in WolkConnect-Python/examples/full_feature_set /. This manifest will be identical to the one created in the remainder of this step.

  • Create device manifest screen will appear where you should enter:
    • Device manifest name - a unique name that defers and describes manifest (for instance TestManifest)
    • Description - describes what exactly is the purpose of the specific device (for instance Measures T, H, P)
    • Protocol - Protocol defines the format of messages between the device and the Platform (leave at JsonSingleReferenceProtocol)
  • Check Firmware update enabled box (it is not mandatory)

The outcome of these actions should look like this:

Adding Sensors

  • Add sensor for temperature by clicking + icon on the Sensors tab
  • Add sensor screen will pop up where you should enter:
    • Sensor name - descriptive sensor name (Temperature)
    • Sensor reference - defines a unique identifier of a sensor on a device, meaning that the device has to be configured to send data with the same sensor reference (T)
    • Reading type - represents the sensor’s physical property type. You can select a reading type from a drop-down list of explicitly supported reading types: Pressure, Temperature, Humidity, etc. or you can select the Generic reading type, in which you can categorise any reading type which cannot be found in the list. In this case, select Temperature
    • Unit - defines a unit for selected reading type (select Celsius, °C)
    • Data type - defines the type of data coming from the sensor (set to NUMERIC)
    • Data size - represents the number of data coming from device sensors (set to 1)
    • Minimum - physical device limitation for data values that can be sent by the device (enter -20)
    • Maximum - physical device limitation for data values that can be sent by the device

The outcome of these actions should look like this:

  • Click Create button to create the sensor and close the pop-up
  • Similar to the temperature sensor, add two more sensors for humidity and air pressure

Humidity sensor should be set up like this:

Air pressure sensor should be set up like this:

Add the accelerometer sensor with data size 3:

Adding Actuators

  • Now let’s add two actuators: switch and slider
  • Select Actuators tab and click + button
  • Add actuator screen will pop up where you should enter:
    • Actuator name - descriptive actuator name (Switch)
    • Actuator reference - a physical actuator has to be configured to use the same actuator reference (SW)
    • Reading type - represents the actuator’s physical property type. You can select a reading type from a drop-down list of explicitly supported reading types: Count(actuator), Switch(actuator), String(actuator) or other reading types that better suit your device.
    • Data type - can be NUMERIC, STRING or BOOLEAN for a different type of an actuator (for the switch, BOOLEAN is already chosen)
    • Data size - represents the number of data coming from the device’s actuator (set to 1)

The outcome of these actions should look like this:

  • Click Create button to create the actuator and close the pop-up
  • Similar to the switch actuator, add a slider actuator
  • A slider has minimum and maximum values (physical device limitation for data values that can be sent by an actuator)

Slider actuator should be set up like this:

Adding Alarm

  • Add alarm by selecting the Alarms tab and clicking the + button
  • Add alarm screen will pop up where you should enter:
    • Alarm name - descriptive alarm name (Humidity alarm)
    • Alarm reference - (HH)
    • Message - the text that is going to be displayed upon alarm occurrence (Humidity is high)
    • Description - describes an event that occurred (Humidity high alarm occurred)
    • Severity - select between Alert, Critical and Error. Severity defines how urgent the alarm is.

The alarm should be set up like this:

  • Click the Save button to create the alarm and close the pop-up

Adding Configuration

  • Add configuration by selecting the Configurations tab and clicking the + button.
  • Add configuration screen will pop up where you should enter:
    • Configuration name - configuration_1
    • Configuration reference - config_1
    • Data type - set to NUMERIC
    • Data size - leave at 1
    • Minimum - 0
    • Maximum - 100

Configuration should be set up like this:

  • Add configuration_2, configuration_3 and configuration_4 like so:
    • Data type for configuration_2 is Boolean

  • Data type for configuration_3 is String with data size 1:

  • Data type for configuration_4 is String with a data size 3:
    • Enter “a,b,c” as value labels

  • Click Save to save the manifest
    • You will see a screen like this:

Summary of Step 1:

You have successfully created the manifest which contains:

  • Four sensors with names and references:
    • Temperature - T
    • Humidity - H
    • Pressure - P
    • Accelerometer - ACL
  • Two actuators with names and references: Switch - SW, Slider - SL
  • Humidity alarm with reference HH
  • Four configuration options with names and references:
    • configuration_1 - config_1
    • configuration_2 - config_2
    • configuration_3 - config_3
    • configuration_4 - config_4
  • Firmware update option is enabled

Let’s continue with the device creation process.

Step 2 - Create Device

  • Choose Create device with this manifest from the manifest details screen. Also, the device can be created from Devices list, just by clicking the + button.
  • A new screen will appear which will guide you through the device creation flow
  • The first step of the flow is selecting a device manifest. TestManifest is preselected in the upper right corner. The screen looks like this:

  • Proceed to the next step and enter:
    • Device name - TestDevice
    • Existing device key - leave empty

  • Click Save. A new device is created, and the pop-up with the device credentials appears:

  • After you have saved the Device key and Password click OK button
  • The device list will appear with the new device you created. Note that device status is Offline.

Summary of Step 2:

You have successfully created the device. Now it’s time to connect it to the Platform and send some readings.

Step 3 - Connect Device

  • Click on the device in the list to open the device details screen
  • Choose the Connectivity tab
  • Select Python connector type library

  • Hit GITHUB… button. Source code for the selected library will open in GitHub.

The next steps explain how to run Python connector:

  • Download the latest release or clone WolkConnect-Python connector and install it on your environment by following the installation readme file from the GitHub
  • Edit wolk_example.py file located in examples/full_feature_set and put your device credentials in lines 54 and 55. For TestDevice we created previously, it should look like this:

  • Execute the script by entering a Python command in terminal
  • The device will connect to MQTT broker, and you will see this outcome:

  • Notice that the device status is changed from Offline to Connected in the devices list

Summary of Step 3:

You have successfully connected the device and sent some readings. Now it’s time to monitor and control devices from the dashboards.

Step 4 - Create Dashboard

  • Choose Dashboards from the left side menu (the first option in the menu)
  • Create a dashboard by clicking the + button and providing a name (for instance My dashboard)
  • Click the + button in the lower right corner to add widgets. For example, add a Semantic groups widget and choose Temperature, Humidity, Pressure and Accelerometer:

  • Upon adding Semantic groups widget, add Actuators widget, select TestDevice and choose Switch and repeat the process for Slider. The dashboard should look like this:

  • While Python script is running, select Switch actuator widget and turn the switch Off in the pop-up that is displayed. Do similar with Slider actuator (change it to 45 for example). Observe that the dashboard will be updated and Python script will log switch change:

  • Add Live messages widget to the dashboard
  • While the script is running, if the randomly generated value for humidity is over 50 then the alarm message will be sent to the Platform
  • Notice that the alarm notification is displayed

Summary of Step 4:

You have successfully created the dashboard where you can monitor real-time data from your device. Also, you can control the device by changing the switch ON/OFF and adding different values to the slider.

Real-time notifications, which were generated when the device announced high humidity alarm, were immediately visible in the Live messages widget.

Step 5 - Changing Configuration Options

  • Run your script, and it will send the initial configuration values
  • Choose Devices from the left side menu
  • Click on TestDevice and navigate to the Configuration tab
  • Notice that the data that has been sent for the configuration options

  • Try changing the values and pressing the blue check mark in the lower right side corner

  • After the button is pushed, it will send new configuration options to your device, and they will be displayed in your terminal like this:

Summary of Step 5:

You have successfully sent your device’s current configuration options and then viewed them on the Platform. You then entered new values for those configurations and sent them to the device.

Step 6 - Monitor and Control Via Mobile Application

Mobile Clients

WolkAbout IoT Platform comes with the free mobile applications for iOS (App Store) and Android (Google Play Store).

Mobile applications are designed for easy access to dashboards, and are used for monitoring and controlling devices. Also, you can see all the messages created in the system, as well as get notified when alarms occur. In the mobile application, you can see all the reports created in the web application.

Connecting to Server Via Mobile Phone

Upon installing and running the mobile app, whether it’s iOS or Android, your mobile screen will look like this:

Finding the QR code is easy. Follow the next steps in the web app:

  • Click on the user menu in the upper right corner
  • Click on the Server info
  • Scan the QR code provided

After the QR code is scanned, log in to your mobile application by entering email and password and tapping Log in button.

After a successful login, your mobile screen will display your dashboards. Besides dashboards, you will be able to see all reports, messages and notifications.

Controlling Your Device Via Mobile Phone

While Python script is running, select Switch actuator widget on your mobile phone and turn switch Off. Notice that the switch on your desktop dashboard changed its value to Off.

Summary of Step 6:

You have successfully installed the mobile application. Now you are able to monitor and control your device via a mobile phone wherever you are.

This is it. You’ve created a device instance on WolkAbout IoT Platform, used MQTT to connect securely to the Platform using Python code uploaded with your device, and started visualising your data using both web and mobile apps. Now it is time to draw some insights and create some rules. :)

To learn more about WolkAbout IoT Platform features, check out our website or speed up your IoT initiative by creating free account and adding your first device today.

Follow us on social media to keep up-to-date with the latest IoT news and research highlights, and benefit from a range of useful resources: TwitterLinkedInFacebook and YouTube.