Tutorial - RED Brick

The following tutorial will demonstrate how to develop software with the RED Brick together with Bricks and Bricklets. A full step-by-step tutorial that shows how Bricks, Bricklets and Extensions are used is also available: first steps tutorial.

The RED Brick is the brain of the Tinkerforge building block system. A program that controls Bricks and Bricklets can be uploaded to and executed on the RED Brick.

In this tutorial we will demonstrate the different capabilities of the RED Brick. To keep it simple we will use a small setup consisting of a RED Brick, a Master Brick and a Temperature Bricklet. Later in the Tutorial will additionally add an Ethernet Extension to get Internet access.

At first we will test a simple program that prints the temperature on your PC and upload and execute it on the RED Brick after that. Then we will extend the program by a GUI to also show the current time on an HDMI monitor. After that we will add a web interface for our temperature measurements. The features of this example are not very useful, but it shows some of the important possibilities of the RED Brick.

If you build your application, you might use other Bricks, Bricklets or programming languages, than those used in this example. But the presented concepts and the workflow will be the same.

Install necessary software

At first you need to install the Brick Daemon and the Brick Viewer on your PC or Mac. Follow the documented steps:

Test the RED Brick

After you have installed the necessary software, you can test the RED Brick. At first you need to put a Micro-SD card with an RED Brick software image in the Micro-SD card slot of the Brick. It is located on the bottom side (a Micro-SD card with a pre-installed image can be found in our shop). After that, you can connect the RED Brick with a mini USB cable to your PC.

RED Brick with Mini-USB cable

Start the Brick Viewer software and click on Connect. A tab marked with RED Brick will show up. Click on it. You should see some status information about the state of the RED Brick. A full description of the RED Brick tab of the Brick Viewer is documented here.

The RED Brick is now ready to go!

Add Bricks and Bricklets

Now we can be sure that your RED Brick works. Before adding Bricks/Bricklets, you should power the RED Brick down. To shut it down click on System located in the right upper corner of the RED Brick tab and choose Shutdown. Wait until all LEDs turn off. After that plug a Master Brick on top of the RED Brick and connect a Temperature Bricklet Bricklet to it.

RED Brick with Master Brick and Temperature Bricklet

After that reconnect the RED Brick to the PC, open the Brick Viewer software and click on Connect. Now the RED Brick tab, a Master Brick and the Temperature Bricklet will come up. You can click through the tabs to try out the connected hardware.

Run example program

Before writing your first program you should to take a look at the API documentation of the used Bricks/Bricklet to see their supported functions. Each documentation page starts with some examples. It is a good idea to run an example program first. We take the "Simple" example of the Temperature Bricklet API documentation and execute it.

Download (example_simple.py)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
#!/usr/bin/env python
# -*- coding: utf-8 -*-

HOST = "localhost"
PORT = 4223
UID = "XYZ" # Change to your UID

from tinkerforge.ip_connection import IPConnection
from tinkerforge.bricklet_temperature import BrickletTemperature

if __name__ == "__main__":
    ipcon = IPConnection() # Create IP connection
    t = BrickletTemperature(UID, ipcon) # Create device object

    ipcon.connect(HOST, PORT) # Connect to brickd
    # Don't use device before ipcon is connected

    # Get current temperature (unit is °C/100)
    temperature = t.get_temperature()
    print("Temperature: " + str(temperature/100.0) + " °C")

    raw_input("Press key to exit\n") # Use input() in Python 3
    ipcon.disconnect()

To do this you download the example_simple.py Python program and replace the UID in the line UID = "XYZ" with the UID of your Temperature Bricklet. You can find it in the Setup tab of the Brick Viewer or in the Temperature Bricklet tab.

Execute this program on your PC. If everything went as expected, you should see the current temperature in the command line.

Execute the program on the RED Brick

Now you have tried out the example and you know that it is working correctly. In the example program we wait for user input:

raw_input('Press key to exit\n')

We do this to prevent the command line on windows from closing immediately. On the RED Brick there won't be any user interaction. We want the program to print the measured temperature one time and end the program afterwards. So we need to remove this line.

Download (example_simple_red.py)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
#!/usr/bin/env python
# -*- coding: utf-8 -*-  

HOST = "localhost"
PORT = 4223
UID = "XYZ" # Change to your UID

from tinkerforge.ip_connection import IPConnection
from tinkerforge.bricklet_temperature import Temperature

if __name__ == "__main__":
    ipcon = IPConnection() # Create IP connection
    t = Temperature(UID, ipcon) # Create device object

    ipcon.connect(HOST, PORT) # Connect to brickd
    # Don't use device before ipcon is connected

    # Get current temperature (unit is °C/100)
    temperature = t.get_temperature()/100.0

    print('Temperature: ' + str(temperature) + ' °C')

    ipcon.disconnect()

Now you can execute it on the RED Brick. The general program uploading procedure can be found in the RED Brick Brick Viewer description. We will only describe the necessary steps here:

Screenshot of RED Brick program upload step 1.

First, open the RED Brick tab in the Brick Viewer and select the Program tab.

Screenshot of RED Brick program upload step 2.

The New button will open the New Program wizard. Enter "Temperature Logger" as name of the program, and select Python as language. Click on Next.

Screenshot of RED Brick program upload step 3.

Click on Add Files and select the example_simple_red.py program. Click on Next.

Screenshot of RED Brick program upload step 4.

We will use Python version 2.7.3, Script File as start mode and our single file as script file. All of these settings are already the default, so we can again click on Next.

Screenshot of RED Brick program upload step 5.

Our simple Python program does not need any arguments or environment variable, so we can again click on the Next button.

Screenshot of RED Brick program upload step 6.

We use Pipe as standard input and log all output (standard output and standard error) to a continuous log file. So no changes are required. Click on Next again.

Screenshot of RED Brick program upload step 7.

There are many options for scheduling, one of the easiest option is to schedule a program with a given time interval. Will will choose Interval as mode with an interval time of 10 minutes (600 seconds). This means that our program will be scheduled every 10 minutes, i.e. the temperature will be logged every 10 minutes.

Screenshot of RED Brick program upload step 8.

The summary page will show your configuration. Click on Next.

Screenshot of RED Brick program upload step 9.

Click on the Start Upload Button to upload the file. After that click on Finish. You should now be able to take a look at the log file and see the logged temperatures.

Screenshot Log Files

You can select log files in the browser view and downloading them to your PC by clicking on Download. By the View button you can directly take a look inside the log. With the Delete button you can delete the log file from the RED Brick.

Gain Internet Access

To gain Internet access on the RED Brick we can either connect a USB Wi-Fi/Ethernet dongle or the Ethernet Extension. In this example we will add the Ethernet Extension:

RED Brick with Master Brick, Temperature Bricklet and Ethernet Extension

Shut the RED Brick down and remove the power before you stack the Extension on top of the stack.

After that reconnect power and wait until the enhanced stack has booted. Click on "Settings". The Network section should be opened and tfX: Wired should be selected (X is a number). Select between DHCP or a static IP and press Connect. After a few seconds the Current Network Status should change to Connected.

Screenshot of RED Brick network settings.

Now that you have Internet access, you can easily do Internet-of-Things and similar applications. Another advantage of Internet access is, that the RED Brick will automatically use NTP and thus have a correct system time.

This means that you can now add a time to each measured temperature.

Download (example_time_red.py)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
#!/usr/bin/env python
# -*- coding: utf-8 -*-  

HOST = "localhost"
PORT = 4223
UID = "XYZ" # Change to your UID

import time

from tinkerforge.ip_connection import IPConnection
from tinkerforge.bricklet_temperature import Temperature

if __name__ == "__main__":
    ipcon = IPConnection() # Create IP connection
    t = Temperature(UID, ipcon) # Create device object

    ipcon.connect(HOST, PORT) # Connect to brickd
    # Don't use device before ipcon is connected

    # Get current temperature (unit is °C/100)
    temperature = t.get_temperature()/100.0
    print('Temperature of ' + str(temperature) + ' °C on ' + time.ctime())

    ipcon.disconnect()

You can upload this program the same way as before.

Develop a custom RED Brick GUI

Note

GUI on the RED Brick only works with the full image.

Another type of program that the RED Brick can execute is a GUI program that is shown on the HDMI output. In this example we will add a PyQt GUI to the simple Temperature Bricklet program.

Download (example_gui_red.py)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
#!/usr/bin/env python
# -*- coding: utf-8 -*-

from PyQt4 import QtGui, QtCore
import sys

from tinkerforge.ip_connection import IPConnection
from tinkerforge.bricklet_temperature import Temperature

HOST = "localhost"
PORT = 4223
UID_TEMPERATURE = "XYZ" # Enter Temperature Bricklet UID here

class Window(QtGui.QWidget):
    qtcb_temperature = QtCore.pyqtSignal(int)

    def __init__(self):
        QtGui.QWidget.__init__(self)
        self.button = QtGui.QPushButton('Refresh', self)
        self.button.clicked.connect(self.handle_button)
        self.label = QtGui.QLabel('TBD')
        layout = QtGui.QVBoxLayout(self)
        layout.addWidget(self.button)
        layout.addWidget(self.label)

        self.ipcon = IPConnection()
        self.temperature = Temperature(UID_TEMPERATURE, self.ipcon)
        self.ipcon.connect(HOST, PORT)

        # We send the callback through the Qt signal/slot
        # system to make sure that we can change the label
        self.qtcb_temperature.connect(self.cb_temperature)
        self.temperature.register_callback(Temperature.CALLBACK_TEMPERATURE, self.qtcb_temperature.emit)

        # Refresh every second
        self.temperature.set_temperature_callback_period(1000)
        
        # Refresh once on startup
        self.handle_button()

    # Refresh by hand
    def handle_button(self):
        self.cb_temperature(self.temperature.get_temperature())

    def cb_temperature(self, temperature):
        # Show temperature
        self.label.setText(u"Temperature: {0} °C".format(temperature/100.0))

if __name__ == '__main__':
    app = QtGui.QApplication(sys.argv)
    window = Window()
    window.show()              # In window
    # window.showFullScreen()  # Fullscreen
    sys.exit(app.exec_())

The GUI has a label that is refreshed with the current temperature every second. Additionally there is a Refresh button that forces a refresh of the label.

You can upload this program the same way as the other Python programs before, with two small differences:

Screenshot of RED Brick GUI environment.

In step 4 you need to add the environment variable DISPLAY with a value of :0. With this configuration the GUI will be shown on the RED Brick desktop that is running on the full image. Adding this variable is necessary, the program will not be able to start otherwise.

Screenshot of RED Brick GUI schedule.

For the scheduler you may want to choose Always and tick off Continue After Error. With this configuration your GUI will be automatically restarted if is closed and also if it fails with an error.

On the RED Brick desktop the simple GUI looks as follows:

Screenshot of RED Brick Temperature GUI.

Develop a custom RED Brick web interface

If your RED Brick has a network interface (Wi-Fi dongle or Ethernet Extension), you can also use it to display a dynamic web page. Currently we support HTML/JavaScript, PHP and Python for this purpose.

Please look at the RED Brick web interface documentation for more information about the web interface. Basically you can call your start point index.html, index.php or index.py and it will automatically be used as a directory index.

Our simple Temperature Bricklet program as a web interface looks as follows (Python and PHP):

Download (index.py)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
#!/usr/bin/env python
# -*- coding: utf-8 -*-  

from flask import Flask       # Use Flask framework
application = Flask(__name__) # Function "application" is used by Apache/wsgi
app = application             # Use shortcut for routing

HOST = "localhost"
PORT = 4223
UID = "XYZ" # Change to your UID

from tinkerforge.ip_connection import IPConnection
from tinkerforge.bricklet_temperature import Temperature

PAGE = u"""
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<html>
 <head>
  <title>Temperature</title>
 </head>
 <body>
  <p>Temperature: {0} °C<p>
 </body>
</html>
"""

@app.route('/')
def index():
    ipcon = IPConnection() # Create IP connection
    t = Temperature(UID, ipcon) # Create device object

    ipcon.connect(HOST, PORT) # Connect to brickd
    # Don't use device before ipcon is connected

    # Get current temperature (unit is °C/100)
    temperature = t.get_temperature()/100.0

    ipcon.disconnect()
    return PAGE.format(temperature)

Download (index.php)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
<?php
require_once('Tinkerforge/IPConnection.php');
require_once('Tinkerforge/BrickletTemperature.php');

use Tinkerforge\IPConnection;
use Tinkerforge\BrickletTemperature;

const HOST = 'localhost';
const PORT = 4223;
const UID = 'XYZ'; // Change to your UID

$ipcon = new IPConnection(); // Create IP connection
$t = new BrickletTemperature(UID, $ipcon); // Create device object

$ipcon->connect(HOST, PORT); // Connect to brickd
// Don't use device before ipcon is connected

// Get current temperature (unit is °C/100)
$temperature = $t->getTemperature() / 100.0;

$ipcon->disconnect();

header('content-type: text/html; charset=utf-8');
?>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<html>
 <head>
  <title>Temperature</title>
 </head>
 <body>
  <p>Temperature: <?php echo $temperature; ?> °C<p>
 </body>
</html>

If your program is used as a web interface, you don't need to configure your executable, arguments, environment and working directory. The steps 4-6 will actually be skipped if you choose Web Interface in Step 3:

Screenshot of RED Brick web interface execution configuration.

To take a look at your web interface go to the IP address or hostname of your RED Brick with a browser and click on the Bin button of your program. It will redirect you to your program path for which your index file will be executed automatically:

Screenshot of RED Brick web interface.