Python Library API

Library Root

The Cloud4RPi Python library provides the following public methods (defined in the __init__.py file):

connect

connect(device_token, host=mqqtBrokerHost, port=None, tls_config=None) – connects to the Cloud and returns a Device object.

Parameters:

  • device_token – a token displayed at the top of the device page on cloud4rpi.io. You can use the New Device button in the top right corner of the Devices page to create a new device and use its token.
  • host (optional) – a Cloud4RPi MQTT broker address. The default address is defined in the config.py file.
  • port (optional) – a Cloud4RPi MQTT broker port. The default port is defined in the config.py file.
  • tls_config (optional) – a dictionary with parameters for the Paho MQTT's tls_set() function.

Example:

import cloud4rpi
device = cloud4rpi.connect('823SnkK3N8L5Y7QQGiuGd53fi', tls_config={'ca_certs': '/etc/ssl/certs/ca-certificates.crt'})

set_logging_to_file

set_logging_to_file(log_file_path) – configures the library to save activity logs to a specified file.

Parameters:

log_file_path – path to a log file.

set_logging_level

set_logging_level(level=logging.INFO) – changes the logging verbosity level.

Parameters:

Device

The Device class provides the following methods to communicate with the Cloud4RPi server and manage the variables' state:

declare

declare(variables) – configures the variables attached to the device.

Parameters:

  • variables – a dictionary with the variables description of the following structure:

    { name: { 'type': type, 'bind': binding, 'value': value }, ... }, where:

    • name – an internal variable name. Name cannot contain dots (.) or dollar signs ($). You can change the name displayed in the UI on the device page.
    • type – a variable type. Available types: 'bool', 'numeric', 'string' and 'location'.
    • binding – a function that accepts the current variable as a parameter and returns a new variable. This function is called every time a value is updated (scheduled updates and value change signals from Control Panels). You can also pass a Python variable if the value should not be changed from Cloud4RPi Control Panels.
    • value (optional) – an initial variable value passed to a binding function during the first update.

    Note

    Use the following object to send the location variable values: {"lat": latitude_value, "lng": longitude_value}, where latitude_value and longitude_value are floating point numbers.

Example:

def led_control(value):
    GPIO.output(LED_PIN, value)
    return GPIO.input(LED_PIN)

ds_sensors = DS18b20.find_all()

device.declare({
    'Room Temp': {
        'type': 'numeric',
        'bind': ds_sensors[0] if ds_sensors else None
    }, 
    'LED On': {
        'type': 'bool',
        'value': False,
        'bind': led_control
    }
})

declare_diag

declare_diag(diag) – configures the diagnostic variables attached to the device.

Parameters:

  • diag – a dictionary with the diagnostic variables' description. It has the following structure:

    { name: binding, ... }, where:

  • name – a diagnostic variable's name.

  • binding – a Python variable or function that holds or returns the actual Cloud4RPi diagnostic variable's value.

Example:

device.declare_diag({
    'Host': gethostname(),
    'Operating System': " ".join(uname())
})

read_config

read_config() – prepares the previously declared (with the declare(variables) function) variables' configuration for publishing (with the publish_config(cfg=None) function).

Returns: A dictionary in the format suitable for the publish_config(cfg=None) function.

read_data

read_data() – updates all variable values and prepares the variables' state for publishing (with the publish_data(data=None) function). This method calls all the binding functions and saves the returned values as new variable values.

Returns: A dictionary in the format suitable for the publish_data(data=None) function.

read_diag

read_diag() – reads all the diagnostic variable values and prepares the data for publishing (with the publish_diag(diag=None) function).

Returns: A dictionary in the format suitable for the publish_diag(diag=None) function.

publish_config

publish_config(cfg=None) – publishes the variables' configuration to the Cloud4RPi server.

Parameters:

  • cfg (optional) – the read_config() output. If not passed, read_config() is invoked internally. This is a list with the following structure:

    [{'name': name, 'type': type}, ...], where name and type corresponds to the same values in the variables parameter passed to the declare(variables) function.

publish_data

publish_data(data=None) – publishes variable values to the Cloud4RPi server.

Parameters:

  • data (optional) – the read_data() output. If not passed, read_data() is invoked internally. This is a dictionary with the following structure:

    {name: value, ...}, where name corresponds to the variable name in the variables parameter passed to the declare(variables) function, and value is the variable value returned by binding.

publish_diag

publish_diag(diag=None) – publishes diagnostic variable values to the Cloud4RPi server.

Parameters:

  • diag (optional) – the read_diag() output. If not passed, read_diag() is invoked internally. This is a dictionary with the following structure:

    {name: value, ...}, where name corresponds to the variable's name in the diag parameter passed to the declare_diag(diag) function, and value is the variable's value the binding returns.