Python SDK

The Python SDK facilitates interaction with the Data-Centric Design Hub.

Getting Started

If your Python 3 (not Python 2) environment is ready, you can directly skip to step 3.

Step 1: Setting up Python

Select, download and install the latest version of Python 3 for your system here.

Windows Once installed, go to 'Start > System > Properties > Advanced System Properties > Environment Variable' In User Variables, double click on 'Path'. At the end of the line, add a semi-colon ; (without space), followed by:

  C:\Users\YOUR_USERNAME\AppData\Local\Programs\Python\Python37;C:\Users\YOUR_USERNAME\AppData\Local\Programs\Python\Python37 \Scripts
  

(Replace YOUR_USERNAME with your Windows user name)

Open the Command Prompt to check the installation, by typing in your console:


  python --version
  
And verifying that the correct version of python was installed.
Mac / Linux After installation, open the Terminal to check if it was successful, by typing the following on your console:

  python3 --version
  
If the correct version of python is shown, the install was successful.

Step 2: Python Dependencies

In the Python ecosystem, Pip is a tool that manages packages for us. We will use it to install and update any Python library our project relies on. You can check whether Pip is already install with the following command.

Windows Type in:

  python -m pip --version
  
If it is not found, download the file get-pip.py and save it (CMD+S or Ctrl+S) in your Downloads folder. In the Atom terminal, type in the following command:

  python Downloads\get-pip.py
  
Mac / Linux Type in:

  python3 -m pip --version
  
If it is not found, you can install it as follows.

  python3 get-pip.py
  

Step 3: Python in Atom

Atom is a software to edit your code, referred to as Integrated Development Environment. Click [here] if you need to install Atom. The next step is the Python plugin for Atom, to get some help specifically for Python in Atom. Go to the terminal and type:

Windows Type in:

  python -m pip install 'python-language-server[all]'
  
Mac / Linux Type in:

  python3 -m pip install 'python-language-server[all]'
  

When it is installed, on the top menu of Atom, click on ‘Packages’ > ‘Settings View’ > ‘Install Packages/Themes’. Search and install ‘atom-ide-ui’ and ‘ide-python’.

If you do not have experience with Python, we recommend you to go through the following tutorial to get started: http://www.learnpython.org/

Step 4: Dependencies

We use Pip to install the dependencies we need, listed in the file requirements.txt. In Atom, right click at the root of your project (left panel), create a file ‘requirements.txt’ and type in the following line.

dcd-sdk>=0.0.19
paho-mqtt
python-dotenv
pyserial
requests

This is the dependence to Python SDK of the Data-Centric Design Hub.

Open the Atom terminal (‘plus’ sign in the bottom-left corner) and execute the following command.

Windows Type in:

  python -m pip install -r requirements.txt --user
  
Mac / Linux Type in:

  pip3 install -r requirements.txt --user
  

Here we ‘install’ the Python dependencies for our project. The option -r indicates we provide a file name that contains the required dependencies, the option –user indicates we install the dependencies in a dependency folder specific for the current users.

Step 5: Connecting a Thing to the Hub

At this stage you need the credentials of the Thing you want to connect to the hub. If you do not have one yet, please sign in/sign up to the DCD Hub and create a Thing following the instructions here.

In Atom, right click at the root of your project (left panel) and create a file ‘random-data.py’.

In this file, add the following lines to import the definition of a Thing and PropertyType from the Python SDK.

from dcd.entities.thing import Thing
from dcd.entities.property import PropertyType

Then, we set the credential of our Thing. In Python, it means we look at the environment variables to read the id and access token of our thing. To provide these information as environment variable, right click at the root of your project (left panel) and create a file ‘.env’.

In this file, type in the following and paste your id and access token after the equal signs.

THING_ID=
THING_TOKEN=

Note: If your are using Git, you do not want to track the file ‘.env’ with Git as it contains secrets. To avoid any mistake, the file .gitignore list all files, folders and extensions to ignore. Create a file ‘.gitignore’ and add a new line with ‘.env’.

Back into our python file, we can now import our credential. We load environment variables and access our id and token as follows:

from dotenv import load_dotenv
import os
# The thing ID and access token
load_dotenv()
THING_ID = os.environ['THING_ID']
THING_TOKEN = os.environ['THING_TOKEN']

Note: In Python, any line starting with a ‘#’ is a comment, to help understand what the code does but ignored by Python when running the programme.

Next, we can instantiate a Thing with the credentials. We store this object in a variable called ‘my_thing’, which we will use to manage our Thing on the DCD Hub.

# Instantiate a thing with its credential
my_thing = Thing(thing_id=THING_ID, token=THING_TOKEN)

The following line ‘read’ the details of our Thing, meaning it connects the DCD Hub and asks for the information related to this Thing.

# We can fetch the details of our thing
my_thing.read()

We can use the method to_json() to get a JSON view of the Thing. We show the result in the console with the Python function print(). If you just registered your Thing on the DCD Hub, it has only an Id, a name and a type.

print(my_thing.to_json())

To create a Property for our Thing, we can use the method find_or_create_property(). This method takes a property name and a property type as parameters, search for a property of the same name in the Thing, and return the property. If no property is found, it requests the creation of a new one on the DCD Hub and returns it. In the following example, we create a property with the name ‘My Random Property’ of type ‘THREE_DIMENSIONS’, meaning that every data point will be compose of three values.

# If we have no properties, let's create a random one
my_property = my_thing.find_or_create_property("My Random Property",
                                               PropertyType.THREE_DIMENSIONS)

Similar to the Thing, we can display the details of a Property with the method to_json().

# Let's have a look at the property, it should
# contains the name, a unique id and the dimensions
print(my_property.to_json())

Step 6: Execute the Python code

Let’s execute this code. Go to the Atom terminal and type in the following command:

Windows Type in:

python random-data.py
Mac / Linux Type in:

python3 random-data.py

If the example runs properly you should see a log generated every two seconds, indicating dumb data is being sent to the Hub.

Step 5: Sending Data

With this code we are ready to send data to the DCD Hub. To send random data, we add two library at the top of the file, the first for generating random numbers, the second to get time functionalities such as sleep() (pausing the programme).

from random import random
import time

Then, we create a function that send random values to the Hub. In Python we do this with the keyword ‘def’ followed by the name of the method and the parameters between parenthesis. In this function we create Dictionary with three random values and we call the method update_values(). This method prepare and send the dictionary of data to the Hub.

# Let's create a function that generate random values
def generate_dum_property_values(the_property):
    # Define a tuple with the current time, and 3 random values
    values = (random(), random(), random())
    # Update the values of the property
    the_property.update_values(values)

Finally, we can call this methods infinitely (While True), waiting 2 seconds after each update.

# Finally, we call our function to start generating dum values
while True:
    generate_dum_property_values(my_property)
    # Have a 2-second break
    time.sleep(2)

Note: Indentation is key in Python. Take the previous example of condition, the indentation defines what is in the condition. Any following line aligned with the if would be considered outside the condition.

You can execute the Python script again and check incoming data with DCD data subject.

Back in the Atom terminal, stop your Python script with CMD+C (Ctrl+C).