Python Applications

API Reference

To view the Python API reference information, run the following from the top level directory of the agent source code:

• Linux: pydoc device_cloud

• Windows: python -m pydoc device_cloud

Writing Your Application

To use the Python APIs, add the following to your application:

import device_cloud as iot

Because the Python agent is operating-system-independent, you must integrate your Python applications, including the device manager included with the agent, into your operating environment. For example, if you want applications to start automatically, you need to use a mechanism appropriate for your operating system. For more information about the device manager, see Device Manager.

Workflow

1. Create a thing definition in Device Cloud. For more information, see Device Cloud Management Portal User's Guide: Thing Definitions.

2. Create an application in Device Cloud and specify the thing definition as the auto-registration thing definition ID. For more information, see Device Cloud Management Portal User's Guide: Applications.

   To create an application you need organization administrator privileges. You must also specify the privileges for your application. For security reasons, you should create a role for your application that specifies only the privileges your application requires before deploying your application in a production environment.

3. Write your application using the Python APIs and implement the required elements of the thing definition you created, including properties, attributes, alarms, and methods.

4. Generate the connection configuration file for your application. For more information, see Generating a Connection Configuration File for a Python Application.

5. Run your application.

   To run your application in Linux as a service, see the example in the share/readme.md file in the source code you downloaded from the GitHub repository or the code you installed using pip. For more information about the file locations, see the following:

   • Device Cloud Quick Start for Linux: Installing the Agent on Your Linux Device
   • Device Cloud Quick Start for Windows: Installing the Agent on Your Windows Device

6. Confirm that your application connected successfully to Device Cloud.

Windows and non-Yocto-based Linux Distributions

The agent supports applications written for Python release 2.7.9 or later and Python release 3.4 or later.

The source code is available in the following GitHub repository:

https://github.com/Wind-River/device-cloud-python

Click releases and on the Releases page, download the latest release.

To install the latest Python stable release, clone or download the latest source code from the Python repository as follows:

https://github.com/deviceWISE/device-cloud-python.

For more information about obtaining the agent code and installing the agent and dependencies, see the following:

• Device Cloud Quick Start for Linux: Installing the Agent on Your Linux Device
• Device Cloud Quick Start for Windows: Installing the Agent on Your Windows Device

Yocto-based Linux Distributions

Python 3 is not supported on Yocto-based operating systems.

The files you need to include are the agent in Yocto-based operating system images, including Intelligent Device Platform (IDP) XT, are available in the following GitHub repository:

https://github.com/deviceWISE/meta-device-cloud

On IDP XT, you need RCPL0027 or later.

For build instructions, see the README.yocto.md, README.WRL9.md, and README.IDP files after you download the source code from GitHub.

As part of the build, the meta-device-cloud layer clones a stable release of the device-cloud-python GitHub repository. If you want to change to a different release or use master, change the following file after you clone the meta-device-cloud layer:

• layers/meta-device-cloud/recipes-iot/python/release.inc

To change to a different release, replace the SHA in the SRCDEV variable. To find the SHA of a stable release, on the releases page, click the SHA and then on the page of the last commit, use the SHA of the last commit.

Dependencies

In addition to a supported release of Python, you need the following packages on your device:

• paho-mqtt

• requests

• websocket-client

• PySocks to support connections through a proxy server