Python

It is recommended to have some experience with the Python environment before reading this guide. However, installation and setup is covered in the Python Setup section.

The Arduino IoT Cloud Python Client is a library that allows you to interact with the Arduino Cloud via MQTT. It supports basic authentication using the device ID as well as secret key that is obtained from the Arduino Cloud when configuring a manual device.

Overview

In this guide we will:

• Configure a manual device in the Arduino Cloud,
• install the Arduino IoT Cloud Python library,
• write a Python script that connects to the Arduino Cloud.

Requirements

To follow this guide, make sure to have:

• An Arduino account,
• a version of Python installed,
• pip package manager installed,
• Arduino IoT Python Client installed.
• A code editor (we recommend VSCode with the Python extension installed).

The experience with Python and the pip package manager varies depending on your computer and operating system. Python needs to be in your PATH to use the Arduino IoT Cloud Python client.

Cloud Setup

To begin with, we need to create a manual device, and create a new Thing. Navigate to the Arduino Cloud and to the "Things" tab.

Thing & Device Configuration

1. Create a new Thing, by clicking on the "Create Thing" button.
2. Click on the "Select Device" in the "Associated Devices" section of your Thing.
3. Click on "Set Up New Device", and select the bottom category ("Manual Device"). Click continue in the next window, and choose a name for your device.
4. Finally, you will see a new Device ID and a Secret Key generate. You can download them as a PDF. Make sure to save it as you cannot access your Secret Key again.

• Learn more about Things in the Things documentation
• Learn more about Devices in the Devices documentation

Create Variables

Next step is to create some Cloud variables, which we will later interact with via a Python script.

1. While in Thing configuration, click on "Add Variable" which will open a new window.
2. Name your variable

   test_switch

   and select it to be of an

   boolean

   type.
3. Click on "Add Variable" at the bottom of the window.
4. Create another variable, name it

   test_value

   and select it to be

   int

   type.

You should now have two variables,

test_switch

test_value

• Learn more about how variables work in the Variables documentation

Variables that we create here can also be synchronized with variables running on any other device in the platform. This makes it possible to link an Arduino boards with a Python or JavaScript project without writing any connection code!

Python Setup

Before continuing, make sure you have a version of Python installed. You can check this by opening a terminal and running:

Copy
1python --version
2python3 --version

Install Packages

To install the Arduino IoT Cloud Python client, run the following command:

Copy
1pip install arduino-iot-cloud

You will also need to install the swig package.

Copy
1pip install swig

To test out to see if your installation worked correctly, start the Python interpreter in your terminal by typing

python

Copy
1from arduino_iot_cloud import ArduinoCloudClient

If you don't receive any import error, it means it is accessible and we can move on to testing out the example script.

Example Script

The script below creates a client that connects to the Arduino Cloud and synchronizes the variable values. Make sure to enter your device credentials (see Cloud Setup) in the

DEVICE_ID

SECRET_KEY

Create a python file, and name it something appropriate, such as

cloud_first_test.py

Copy
1import time
2import logging
3
4import sys
5sys.path.append("lib")
6
7from arduino_iot_cloud import ArduinoCloudClient
8
9DEVICE_ID = b"YOUR_DEVICE_ID"
10SECRET_KEY = b"YOUR_SECRET_KEY"
11
12def logging_func():
13    logging.basicConfig(
14        datefmt="%H:%M:%S",
15        format="%(asctime)s.%(msecs)03d %(message)s",
16        level=logging.INFO,
17    )   
18
19# This function is executed each time the "test_switch" variable changes 
20def on_switch_changed(client, value):
21    print("Switch Pressed! Status is: ", value)
22
23if __name__ == "__main__":
24
25    logging_func()
26    client = ArduinoCloudClient(device_id=DEVICE_ID, username=DEVICE_ID, password=SECRET_KEY)
27
28    client.register("test_value")  
29    client["test_value"] = 20
30    client.register("test_switch", value=None, on_write=on_switch_changed)
31    
32    client.start()

• The script uses the

  client.register()

  to configure the variables.
• The

  test_value

  we simply set a static value of

  20

  .
• For the

  test_switch

  variable, we create a callback function that is triggered any time the value is updated. This can be controlled from a dashboard in the Arduino Cloud.

To run this script, use the following command (or the "Run" button in VSCode):

Copy
1python cloud_first_test.py

After running the script, you should see in the terminal that we first attempt to connect to the Arduino Cloud. Once connected, we push the variable update for

test_value

You can test out the

test_switch

When flicking the switch, you should see the following command being printed in the terminal:

Copy
1Switch Pressed! Status is <state>

For creating dashboards and linking variables, check out the Dashboard & Widgets documentation.

Troubleshooting

• command not found: python

  - encountering this error when running a script indicates that the terminal can't access Python. You can try running

  python3

  , as some versions of Python requires this.

• Connection failed 5, retrying after 1.0s

  - this error is likely due to an invalid device ID or secret key.

• ModuleNotFoundError: No module named '_m2crypto'

  - likely if you are running an older version of the library. Try updating the library.