Python SDK for DevIoT service (https://deviot.cisco.com/)
You can use this SDK to register devices to DevIoT and sync up data and actions between the devices and DevIoT.
- Python: This SDK is written in Python. We support both Python 2 and 3.
- paho-mqtt: This SDK uses this library to build an MQTT client
- You can use SDK to register your own sensors and systems to DevIoT.
- Use Starter-kit to run sample codes
- Gateway: 'Gateway' is a device connected to DevIoT like a Raspberry Pi board or a mobile phone
- Thing: 'Thing' is a sensor or a module in a gateway like a light sensor, LED, or GPS. A thing is an icon in DevIoT. A gateway can have several things.
- Property: 'Property' is a variable measured by a thing. For instance, Latitude and longitude are properties of a GPS. A thing can have several properties.
- Action: 'Action' is a command for a module. For example, turning on and off LED is two different actions. A thing can have several actions.
Before using this SDK, you need to check the version of python. The master branch is written in Python 2. You can check it with the following command.
python --version
If your python version is 3.x, you need to switch to 'python3' branch in the next step.
Clone SDK git repository
git clone https://github.com/ailuropoda0/gateway-python-sdk.git
cd gateway-python-sdk
(ONLY for Python 3 users) Switch to Python 3
git fetch origin python3:python3
git checkout python3
Install SDK package on python
python setup.py install
You can refer the example code in gateway-python-starter-kit.
Import SDK
from cisco_deviot.gateway import Gateway
from cisco_deviot.thing import Thing, Property, PropertyType
Construct a Gateway object
account = "[email protected]" # enter your DevIoT account
app = Gateway(name="gateway_name", account=account)
Construct a Thing instance
thing = Thing("thing-id", "thing-name", "thing-kind")
A Thing instance can have both properties and actions. But you can only use it as either an input component or an output component in each project.
In DevIoT project page, click the 'Connect' button and connect the thing component with a rules engine by double-clicking them. The type of the component is determined by which component is first double-clicked between the thing component (input) and the rules engine (output).
(1) Input: Add a property to the thing
property = Property("variable_name", PropertyType.INT, 0)
thing.add_property(property);
(2) Output: Add an action to the thing
thing.add_action("sameple_action")
def custom_function(): ## define your action function
print("action")
thing.sameple_action = custom_function
Register the sensor to the gateway
app.register(thing)
Connect the gateway to the server
app.start()
disconnect gateway
app.stop()
ย
Gateway(name, deviot_server="deviot.cisco.com", connector_server="deviot.cisco.com:18883", kind="device", account="")
The Gateway() constructor takes the following arguments:
name
The unique name of a gateway
deviot_server
The address for the DevIoT server. The default value is 'deviot.cisco.com'. It does not need to add the protocol. The default protocol is HTTPS(secure connection).
connector_server
The address for the MQTT server. The default value is 'deviot.cisco.com:18883'. It does not need to add the protcol. The default protocol is TCP(unsecure connection) and the default port number is 1883.
kind
The kind of a gateway
account
Your DevIoT account. you also can use empty string, it will let all account get the data of your gateway.
register(*things)
The register() function adds things to the gateway. The thing should not have been already registered.
thing
A Thing instance to register
load(filename, class_directory=None)
The load() function registers things from an JSON file named [filename] and the custom Thing-sub classes inside [class_directory].
filename
The JSON file having information of things. filename should include its extension. The way to write this JSON file is described in gateway-python-starter-kit.
class_directory
The directory which has custom Thing-sub class. If the Thing-sub class is defined in the same directory, class_directory should be omitted or be None.
deregister(*things)
The deregister() function deletes things from the gateway.
*things
A Thing instance to deregister
update_thing(thing, **new_value)
The update_thing() function updates the values of a thing.
thing
The thing to be updated. It can be the string id of a thing or a Thing instance.
**new_value
The keyword arguments for the updated values. The key is the name of properties and the value is the new value.
start()
Connect the things of the gateway to the DevIoT server and the MQTT server
stop()
Disconnect the gateway from the DevIoT server and the MQTT server.
Thing(id, name, kind=None)
The Thing() constructor takes the following arguments:
id
the unique id of a thing
name
the display name of a thing in DevIot
kind
the kind of a thing
add_property(*thing_properties)
The add_property() adds properties to a Thing instance. When a string is used for arguments, new Property instance named the string is added to the Thing instance.
*thing_properties
The list of Property instances or the string value of properties' name.
add_action(*thing_actions)
The add_action() adds actions to a Thing instance. When a string is used for arguments, new Action instance named the string is added to the Thing instance.
*thing_properties
The list of Property instances or the string value of actions' name.
Property(name, type=PropertyType.INT, value=None, range=None, unit=None, description=None)
The Property() constructor takes the following arguments:
name
The name of a property. It should be unique in a thing.
type
The variable type of a property. There are 4 types: int, bool, string, color. You can use PropertyType.INT, PropertyType.BOOL, PropertyType.STRING, PropertyType.COLOR after importing 'PropertyType' class from 'cisco_deviot.thing'.
value
The value of a property.
range
The range of a property's value.
unit
The unit of a property. It is string value.
description
The description for a property. It is shown at the page of each thing.
Action(name, **kwargs)
The Action() constructor takes the following arguments:
name
The name of Action. The method with the same name should be defined in a class or an instance. So the name must not overlap with other methods of Thing class like add_property and *add_action, and the name cannot contain space ' '.
**kwargs
The keyword arguments for properties in an action. Key is the name of a property and the value of the property. It is not mandatory.
add_parameter(action_parameter)
The add_parameter adds properties to an Action instance.
action_parameter
A Property instance to be added