Connect to the LED

We'll begin by learning how to connect to the colored LED from our Python program and use some of its functions.

Test the connection with the Brick Viewer

The Brick Viewer software is a great companion to work the Tinkerforge devices. The software allows us to test each device's functionality using a simple graphical user interface (GUI) and check whether we can connect to the master brick at all. It is a good idea to first test the connection in the Brick Viewer to make sure everything is set up properly before we jump into the code.

Establish the connection

Using Brick Viewer to test Tinkerforge devices is simple. When you have the Brick Daemon installed and running, which you only need to do once, and you connected the Master Brick to your computer via the USB cable, you can open the Brick Viewer and click the "Connect" button.

With the "Connect" button, we can establish a connection to the local Tinkerforge devices.

Getting the device's UID

When using the Brick Viewer software, we can find the Unique Identifier (UID) of a device. This UID is necessary to directly connect to the device from Python. Later on, we will show another way to connect to devices without needing the UID. In this method, the devices will actively send their UID (and other information) through a provided function, allowing us to connect to them.

While we are at it, feel free to play around with RGB LED (and other devices that you have) and set its color from the Brick Viewer software. You can use sliders to set the value for each of the three RGB colors (red, green, blue), or you can use the three slider at the bottom for setting the color via HSL. We will soon learn how to do both from our Python program with a few lines of code.

You can find the device's UID in the Brick Viewer in the upper-left corner of each tab.

Connect from Python

We can see from the screenshot above that the UID of the LED that is currently connected to my computer via a USB cable is AU1. Unless you have the same device instance, your UID will be different when you try this. So copy your UID and replace it in the code below (line 3):

rgb_led.py

HOST = "localhost"
PORT = 4223
UID = "AU1" # Change this to the UID of your RGB LED Bricklet

from tinkerforge.ip_connection import IPConnection
from tinkerforge.bricklet_rgb_led import BrickletRGBLED

ipcon = IPConnection() # Create IP connection
ipcon.connect(HOST, PORT) # Connect to brickd

# Create device object
led = BrickletRGBLED(UID, ipcon)

# Set to full green color
led.set_rgb_value(0, 255, 0)

input("Press key to exit\n")

ipcon.disconnect() 

What does each line do?

When you run the above program from your laptop using python rgb_led.py, it should turn your LED to green and then wait for you to press any key to exit the program. Let's take a closer look at what each line of code does.

Defining some constants

The first three lines of code define a set of so-called constants. A constant in programming is similar to a variable with one important difference: while variables' values can be changed at any point in the program, constants constantly stay the same. Hence, the name "constants". In Python, we indicate that we define a constant by writing its name in all-capital-letters. This is only conventional, and we technically could change the values later on. Note that this is different in other programming languages like Java, where we can define real constants, whose values can't be changed after initialization.

HOST = "localhost"
PORT = 4223
UID = "AU1"

We use the constants to define the values for the connection parameters HOST, PORT, and UID. It makes sense to define them as constants, as we do not expect their values to change during our program. They are only used once at the beginning of the program to establish the connection.

Import external code (libraries)

In lines 5 and 6 we use the from and import commands to indicate that we make use of external code libraries in our program. Specifically, we import the objects IPConnection and BrickletRGBLED from different namespaces of the tinkerforge library. This library was developed and made available by Tinkerforge and facilitates working with their hardware devices. While we use Python in this module, we could use the Tinkerforge devices with many other programming languages as well, as Tinkerforge offers support for almost any popular programming language in the form of a specific library.

from tinkerforge.ip_connection import IPConnection
from tinkerforge.bricklet_rgb_led import BrickletRGBLED

Importing the two objects from the tinkerforge library makes sure we can later use these two objects to create instances of them.

Create the IP connection

The Tinkerforge devices communicate using a protocol called the Internet Protocol (IP). This protocol is used to exchange data between devices and is commonly used on the World Wide Web. To create a connection, we create a new variable called ipcon and assign it to a new instance of the IPConnection object class from the tinkerforge library. This creates a new IP-connection object which we can access using the ipcon variable. We can then use the connect() function, which expects two parameters: the hostname and port, to establish the IP-connection. These values have been defined as constants earlier in the code.

ipcon = IPConnection()
ipcon.connect(HOST, PORT)

Exercises

1. What happens if you run the code but comment out line 9, so that the IP-connection does not get connected?

2. From your Python program, how can you find out whether an IP-connection is connected? Enhance your code to include a check for that, and only then continue with everything else!