Tutorial

The following tutorial will demonstrate how to use Bricks and Bricklets with the High Level Programming Interface.

In the first part we use the DC Brick to drive a motor. After this we make the velocity of this motor controllable by a rotary potentiometer by attaching a Rotary Poti Bricklet. At the end we show how to stack Bricks together to reduce wiring and communicate over wireless or cable based interfaces.

Use a single Brick

We choose the DC Brick as a representative throughout this tutorial. It is however easily possible to transfer the concepts shown to other Bricks. Click here for an overview of all available Bricks.

Phase 1: Testing

Before the DC Brick can be used, the Brick Daemon (brickd) and the Brick Viewer (brickv) have to be installed, installation instructions can be found here and here. The Brick Daemon is a bridge between the Bricks/Bricklets and the programming language API bindings. The Brick Viewer is a GUI for testing purposes.

After the installation you are ready to tinker! Take the DC Brick and connect a motor and a battery as shown the picture below (You can of course also use a power supply instead of the battery or e.g. a Servo Brick and a servo instead of the DC Brick and a motor):

Start the Brick Viewer and connect the DC Brick over a USB cable with your PC. After pressing the “connect” button in the viewer you should get a tab called “DC Brick”. Select it. Your Brick Viewer now looks as depicted below:

You can see the voltage of the connected battery as “External Voltage” and the current used by the motor as “Current Consumption” as well as a representation of the current velocity on the right side. Different sliders allow you to modify velocity and acceleration of the motor as well as the PWM frequency of the driver. After clicking “Enable” you are in control of the motor.

Phase 2: Write your own Program

The DC Brick and motor are verified to work properly, there is now nothing in the way to write a first program that controls the DC Brick.

You can choose one of the available programming languages, in this tutorial we use Python, since it is easy to understand.

The necessary steps to get everything working are essentially the same in all programming language. This tutorial together with the examples in the “Programming Interfaces” section of every product should allow you to get any Brick working with any programming language.

In the following we assume that you now the basics of the programming language you picked and that the necessary compilers/interpreters are already installed.

Download the API bindings for your programming language from the Downloads page and install them. Installation instructions can be found here and in the readme.txt supplied with the API bindings.

Create a folder for your DC Brick test project. Download one of the examples for the DC Brick as a starting point from here and place it in the folder.

In this tutorial we take a look at example_configuration.py:

#!/usr/bin/env python
# -*- coding: utf-8 -*-  

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

from tinkerforge.ip_connection import IPConnection
from tinkerforge.brick_dc import DC

if __name__ == "__main__":
    ipcon = IPConnection(HOST, PORT) # Create IP connection to brickd

    dc = DC(UID) # Create device object
    ipcon.add_device(dc) # Add device to IP connection
    # Don't use device before it is added to a connection

    dc.set_pwm_frequency(10000) # Use PWM frequency of 10khz
    dc.set_drive_mode(1) # use 1 = Drive/Coast instead of 0 = Drive/Brake

    dc.enable()
    dc.set_acceleration(5000) # Slow acceleration
    dc.set_velocity(32767) # Full speed forward

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

Line 12 creates an IP Connection to the Brick Daemon running on the host defined in Lines 4-5. It is possible to run your program on another PC than the one which has the Brick Daemon running (e.g. you can write a program on you phone that controls a Brick connected to your PC).

Line 14 creates an object that allows to control the DC Brick. It is necessary to assign the Unique Identifier (UID) of the Brick (in this example defined in Line 6). Change it corresponding to your device!

Note

The easiest way to get the UID of your device is to use the Brick Viewer. If you connect a device to the PC, the Viewer will display the UID in the “Setup” tab.

In Line 15 the DC Brick object is attached to the IP Connection. This makes it possible to control multiple devices on different hosts from within one program.

The Lines 18-23 configure the DC Brick and let the motor run full speed forward.

Line 25 is used to prevent program termination until you press enter.

Run this python script and use it or other examples as a starting point for your own project.

Note

A full description of the API and further examples can be found in the description page of the product. In case of the DC Brick here.

Add Bricklets to extend features

You can add Bricklets to extend the features of Bricks. Click here for an overview of available Bricklets.

To use a Bricklet, connect it to your Brick over the supplied cable when the Brick is not powered.

We use a Rotary Poti Bricklet and the DC Brick from the previous part of this tutorial, but it is easy to transfer the shown concepts to any Bricklet connected to any Brick.

Phase 1: Testing

Connect the Rotary Poti Bricklet to your DC Brick as depicted in the image below.

If you now connect the DC Brick to the PC, not only a “DC Brick” tab but also a “Rotary Poti Bricklet” tab will be shown in the Brick Viewer. Select the “Rotary Poti Bricklet” tab and rotate the potentiometer. You should see a corresponding movement in the viewer.

Phase 2: Write your own Program

To incorporate the Rotary Poti Bricklet in our small project we change the program to allow controlling of the motor velocity with the rotary poti. It now look as follows (Download):

#!/usr/bin/env python
# -*- coding: utf-8 -*-  

HOST = "localhost"
PORT = 4223
UID_DC = "9yEBJP3Jnf3" # Change to the UID of your DC Brick
UID_POTI = "2wx" # Change to the UID of your Rotary Poti Bricklet

from tinkerforge.ip_connection import IPConnection
from tinkerforge.brick_dc import DC
from tinkerforge.bricklet_rotary_poti import RotaryPoti

dc = None

# Callback function for position callback (parameter has range -150 to 150)
def cb_position(position):
    velocity = 0xFFFF/2*position/150 # Velocity: -32767/32767
    print('Set Position/Velocity: ' + str(position) + '/' + str(velocity))
    dc.set_velocity(velocity)

if __name__ == "__main__":
    ipcon = IPConnection(HOST, PORT) # Create IP connection to brick

    dc = DC(UID_DC) # Create dc brick device object
    poti = RotaryPoti(UID_POTI) # Create rotary poti device object
    ipcon.add_device(dc) # Add device to IP connection
    ipcon.add_device(poti) # Add device to IP connection

    poti.set_position_callback_period(50) # set callback period to 50ms
    poti.register_callback(poti.CALLBACK_POSITION, cb_position)

    dc.enable()
    dc.set_acceleration(0xFFFF) # Full acceleration

    raw_input('Press Enter to exit\n') # Use input() in Python 3
    dc.disable()
    ipcon.destroy()

Lines 4-7 are the typical configurations, the UID has to be changed according to the Bricks/Bricklets you use.

In Lines 22-27 an IP Connection to the Brick Daemon is established. The Brick and Bricklet devices are created and added to the IP Connection.

We configure the Rotary Poti Bricklet, such that it calls the method cb_position every time the position of the potentiometer changes. Line 29 configures this callback to be triggered with a period of 50ms if the position changes. If the position is unchanged there won’t be any callbacks. This is an efficient implementation, only the bare minimum of USB bandwidth is used. The callback method is registered in Line 30. cb_position is defined in Line 16-19, it sets a new velocity based on the current position of the potentiometer.

In Lines 32-33 we enable the motor and set a maximum acceleration. This allows the motor to follow the potentiometer movements immediately.

In Lines 35-37 we wait for user input to prevent program termination. After this the motor is stopped and the IP Connection destroyed.

Build Stacks

To reduce wiring and save space it is possible to stack Bricks. You need a Master Brick at the bottom with a PC connection to route the data between the PC and the Bricks in the stack.

The stacking is transparent, that means there is no code change necessary between a version that uses Bricks separately connected over USB to a PC or a version with an additional Master and stacked Bricks.

It is possible to use more than one Master Brick in a stack. But only the Master Brick at the bottom of the stack acts as the master of the stack. The other Master Bricks can however be used to connect more Bricklets.

The master of a stack powers each device of the stack over its USB connection with a maximum of 500mA. Every driver Brick in the stack needs to be powered by its own onboard power-connector. To again reduce wiring and save space it is possible to use a Power Supply Board, which is attached at the bottom of the stack (below the master). These boards power the stacks internal power signal. That means, that each driver Brick which is not powered by its onboard power-connector is powered through the stack by the power supply board.

Additionally the power supply board creates a 5V signal to power the devices of the stack. No power is drawn from the PC if a power supply board is used. This is especially useful if a small embedded device is utilized to control the Bricks and Bricklets, since it might not be able to deliver the needed power.

The master of the stack can measure the voltage and the current flow of the power supply connected to the power supply board.

Note

Each driver Brick switches automatically to the stack internal power signal if no external supply is attached over the onboard power-connector. Keep this in mind!

In the following we extend the previous part by attaching a Master Brick below the DC Brick with the connected rotary poti.

Note

The white corners show how to plug the Bricks together.

Phase 1: Testing

Build a stack consisting of a Step-Down Power Supply with connected battery, a Master Brick with connected Rotary Poti Bricklet and a DC Brick with connected motor (from bottom to top).

This setup is depicted in the image below.

If you connect the Master Brick to the PC over USB, the Brick Viewer should show the Master Brick (measuring current and voltage flowing through the stack), the DC Brick and the Rotary Poti Bricklet.

Phase 2: Write your own Program

Since the stacking is transparent you are able to run the program of the previous part without any changes!

Cross-Link Stacks

The stacks as shown so far in the tutorial are not super exciting, they only reduce wiring and save space. But, as you might have already guessed, there is more to it. It is possible to attach Extensions to the stack, which extend the stack with interfaces other than USB, e.g. Chibi (wireless), RS485, and in the future WLAN and Ethernet.

You need one Master Brick and two Chibi Master Extensions additionally to the previous part. Attach one Chibi Extension on top of your stack and build a new stack from the other Chibi Extension and the Master Brick. Connect the Rotary Poti Bricklet to this new stack (see image below).

Now connect each stack separately to your PC and configure it with the Brick Viewer as described in the Chibi documentation. It is necessary that you power up the slave stacks prior to the master stack.

You should see two Master Bricks, the Rotary Poti Bricklet and the DC Brick in the Brick Viewer. If this is the case you can run your previously written code without any change.

Now you are able to control the DC motor wirelessly with the Rotary Poti Bricklet. Take this as a starting point and have fun!