getting_started.md

Getting Started Project

The Getting Started project demonstrates a simple use case where an Elastic Pi is virtually connected to temperature and humidity sensors, regularly acquiring values from an industrial machine.

Elastic Pi ?

To let you paractically try out the project without the need of a physical Pi, we created an Elastic Pi (a virtual device) and connected it to your Getting Started project.

You can see your Elastic Pi from the Device Configuration panel, in connected status:

The code

Move to the Management Scripts panel:

Generating sensor data readings

In the demo project the values of the sensors are randomly generated by an ad hoc function defined in the global section.

The code is in the global section:

def read_data_from_sensor(sensortype):
  """simulates the reading of a sensor randomly generating values"""
  if sensortype == "temperature":
    # randomly generate temperature value
    return round_reading(random.uniform(30,50))   
  elif sensortype == "humidity":
    # randomly generate humidity value
    return round_reading(random.uniform(20,80))  

Polling for sensor data readings

The main code in the loop section, simply polls sensors' data value every 5 sec, as it would do in a real scenario, and stores it in a global variable (as usual defined in the global section):

def loop():
  """the main loop of your device, running on a dedicated process"""

  # this example simply "polls" the temperature value every 5 sec,
  # storing them in global variables (defined in the global section)

  temp_value.value = read_data_from_sensor("temperature")
  hum_value.value = read_data_from_sensor("humidity")

  time.sleep(5)

Messages to remotely interact with the Pis

Move to the Messages panel:

Interactively ask the Pi for sensor readings

Let's say we want to remotely ask the Pi for the temperature and/or humidity value. What we need is a command and the code to handle it.

The command has been defined with the following structure:

{"read_sensor_data": {"sensortype": "<temperature|humidity|both>"}}

Where:

• read_sensor_data is the message type describing that we will use this command to read sensor data from the py
• sensortype is a keyword accepting 3 possible values, to allow us to ask for temperature, humidity or both.

Iottly automatically generates the command handler for us, naming the function as the message type. All we need to do is to put the logic inside, to get the requested data from the global variables and to send them to Iottly through MQTT:

def read_sensor_data(command):
  """
  function to handle the command read_sensor_data
  command description: Make a sensor data reading
  format of command dict:
  {"read_sensor_data":{"sensortype":"<temperature|humidity|both>"}}

  Command handlers run in a dedicated process (one for all)  
  """

  # cmdpars stores the command parameters
  cmdpars = command["read_sensor_data"]

  # based on the value of sensortype get the data :
  #   - from temp_value.value,
  #   - or from hum_value.value
  #   - or from both of them

  if (cmdpars["sensortype"] == "temperature"):  
    sensor_data_reading = {"temperaure":temp_value.value}

  elif (cmdpars["sensortype"] == "humidity"):   
    sensor_data_reading = {"humidity": hum_value.value}

  elif (cmdpars["sensortype"] == "both"):
    sensor_data_reading = {
      "temperaure": temp_value.value,
      "humidity": hum_value.value
    }

  # prepare a message as the following:
  # {"sensor_data_reading":{
  #    "temperature": <temp value from temp_value.value>,
  #    "humidity": <hum value from hum_value.value>,
  #  }}      
  message = {"sensor_data_reading": sensor_data_reading}

  # finally send the message over MQTT with the built in iottly function    
  send_msg(message)

Debug the code in the console

Move to the Console panel:

When the message read_sensor_data was defined, iottly took also care of creating a command in the Console panel, so that we can immediately test if the code is behaving correctly.

Try to send the command read_sensor_data, you should see a message with sensor readings in the Logs. Newer messages are at the bottom. You can clear and reload the history to get just the first 10 messages.

Try it by yourself

Send an alarm when the temperature is too high

Copy this code and paste it in the loop function, jsut before the time.sleep, to have the Elastic Pi sending an alarm whenever the temperature is greater than 48°.

  if temp_value.value > 48:
    alarm = {"description":"temperature too high",
                 "temp_value":temp_value.value}

    message = {"ALARM": alarm}

    send_msg(message)    

Click on Flash over-the-air to send the new code to the Elastic Pi. After the agent restarts, you will see the alarm message in the Console panel, whenever the randomly generated temperature value exceeds 48.

Configure the alarm threshold remotely

Let's say we would like to change the alarm threshold over time.

Lets' sketch how we could do it with iottly, entirely remotely. You can try it by yourself!

We need to

• create a new command to remotely set the threshold
• define a new global variable for the threshold value
• fill the new command handler with the logic to store the threshold into the variable
• change the loop function where we hardcoded the 48 value
• finally flash the new code and test it.

Create a new command

Move to the Messages panel and create a command like this one:

Define a new global variable

Move to the Management Scripts panel and add this line to the global section:

Threshold = multiprocessing.Value('d',45.0)

Fill the new command handler with the logic to store the threshold

In the Management Scripts panel, you will find a new command handler set_alarm_threshold which have been generated when you created the new command.

Simply add this code at the end of the handler:

  #-----------------------------------------------------------------------------#
  # here your code!!
  limit = cmdpars["threshold"]
  Threshold.value = float(limit)
  change = {"new_threshold_value": Threshold.value }
  send_msg(change)
  #-----------------------------------------------------------------------------#

Change the loop function

In the Management Scripts panel, go to the loop function and change the alarm condition, like this:

  if temp_value.value > Threshold.value:

Finally Flash the new code and test it!!

Next steps

Goon, create a new project and connect your physical board to it!!!

The full tutorial to work with physical Pis is here: https://iottly.github.io/