Design and build a Raspberry

Pi robot

By
Stewart
Watkiss
(PenguinTutor)

DRAFT Version

Creating a more permanent circuit (stripboard vs PCB)

The breadboard circuit is sufficient for a working robot vehicle, but it does not have the same
durability as a permanent circuit soldered together. Another reason for wanting to move the motor
control from the breadboard is to free up the space on the breadboard for connecting sensors
(although this could also be achieved by having a second breadboard with one mounted on the
lower level).
One way of creating a more permanent circuit is to solder the components onto stripboard.
Stripboard is a board with strips of copper on the underside which allow components to be soldered
to them. They are available either as generic stripboards with rows of copper strips, or with a layout
similar to the breadboard layout, which makes transferring the circuit easier. Whilst using stripboard
would create a more permanent circuit it wouldn't help with creating more space for future circuits
as the stripboard would be difficult to mount over the Raspberry Pi and if positioned where the
breadboard is would take about the same amount of space as the breadboard.
A better choice would be to use a printed circuit board (PCB). There are some existing printed
circuit boards that can be used with the Raspberry Pi or it is possible to create your own. When I
first designed the Robot Vehicle there were no motor circuit controllers that were commercially
available. I did look at the PiFace digital, but that only provided a pair of single-pole relays which
would only drive a pair of motors in one direction or a single motor in forward and reverse. I
therefore starting work on creating my own printed circuit board, but whilst I was doing that the
RyanTech motor controller board was made available which saved me the task of creating my own.
If you are interested in electronic circuit design then it is a useful exercise to create your
own printed circuit board. These can be designed manually or by using specialist PCB
software such as KiCAD or Fritzing (there are also commercial software which can be
very expensive). Creating your own PCB is fiddly and involves the use of some
dangerous chemicals, but it is very rewarding to have your own completed circuit board. If creating
your first PCB I recommend starting with a simple single sided PCB rather than trying to create the
motor controller.

Printed Circuit Board - RyanTeck PCB kit RTK-000-001

The add-on board for the Raspberry Pi that I moved my circuit to is the RTK-000-001 designed by
Ryan Walmsley. It is based on the same circuit as the breadboard design (I actually made a couple
of port changes from an earlier breadboard design to make it compatible).
I have referred to this as an add-on board, but another term you may hear used is shield.
The term shield if often used with add-on boards for the Arduino micro-controller board
where there are a variety of different boards that can be stacked on top of each other.
The motor controller board is provided in a kit form. It contains a PCB and the various components
40

DRAFT Version
which need to be soldered together. The connections from the board are made using terminal blocks
so once soldered together it can easily be used for other projects
The completed board is shown below. Note that the GPIO connector is mounted on the underside of
the PCB so that it fits onto the GPIO connector on the Raspberry Pi. The IC is mounted in a IC
socket which makes it easier to solder (there is no risk of damage the IC during soldering) and
means that the chip can be removed if required.

The photo below shows the controller board mounted on the Raspberry Pi.

41

DRAFT Version

External connections are required to connect the power supply to VCC2 and the motor connections
to the terminals M1 and M2. Also note that there is no connection for VCC1 on the controller board.
The IC on the motor board is powered from the GPIO, but a power supply needs to be provided to
the Raspberry Pi through the normal micro-USB connector. I cut off the large USB connector from
a USB to micro-USB lead and connected that to the power supply from the battery. There are four
wires used in a USB connector, but only the red (5v) and black (gnd) need to be connected to the
power supply.

With diodes or without diodes

Motors are electromagnetic devices. This means that they use the electronic current to create a
magnetic field which causes an action, in this case turn the motor around. When the power is
removed the magnetic field will collapse, or if the motor continues to turn then it can act as a
generator. When this happens there can be voltage spike caused by the back EMF (electromotive
force) which could damage sensitive electronic components. Normally a diode is connected in the
reverse direction across a magnetic load to prevent the back EMF from damaging the electronic
circuitry. These have various different names including flyback diodes, freewheeling diodes,
suppressor diodes or clamp diodes.
The data sheet for the SN754410 IC shows the internal circuitry based on the diagram below.
Through this you can see two diodes connected in reverse across the transistor output which will
help to dissipate the voltage spike. However the same data sheet also shows an example circuit
diagram where external diodes are connected.

42

DRAFT Version

Unfortunately the data sheet does not provide any guidance as to whether the internal diodes are
suitable for handing the back EMF from a diode. I have tested with the motors of the magician
robot chassis and have not experienced any problems.
Adding external diodes would only cost a small amount (typically a few pence per diode), however
adding them to the breadboard made the circuit more complex and harder to follow and they are not
included in the motor controller board.
If you are using the SN754410 for larger motors then I would suggest adding external diodes to
provide additional protection, but it does not appear to be necessary for this robot vehicle. There is
also an alternative IC the L293D which includes clamp diodes, although that IC is less readily
available.

Heatsink
I have not used an external heat sink on the motor controller IC for the robot vehicle. In normal use
I have not suffered any heat related problems. If using a motor powerful motor then it may be worth
adding an IC heatsink to the chip which may be useful if the motor stalls.

Controlling the speed of the motors with PWM

We have now built a circuit that will allow us to move the motors forwards and backwards, but we
also need to be able to control the speed. A common way to change the speed of a DC motor is to
change the DC voltage. As the voltage increases the magnetic field is more powerful and as it
decreases it produces a less powerful magnetic field. The circuit we have made is based on
switching the supply on and off rather than been able to provide a variable voltage, so what we need
is a way to make this digital on-off signal appear as though it's an analogue DC voltage.
There is a technique that can be used that can change the speed of the motor by switching the
supply on and off quickly. In fact this is a technique that can be used in other circumstances to
create an analogue output from a single digital signal.
The technique is called Pulse-width modulation (PWM). It works by switching the voltage on and
off very quickly. The ratio of time that the voltage is switched on compared to it being switched off
provides an equivalent voltage.
This is easier to understand by looking at a waveform diagram. The diagram below is simplified
from what the waveform actually does which is done to make the explanation clearer. The
waveform shows the voltage on the y-axis over time in the x-axis. The time is in milliseconds as
this all happens very quickly.

43

DRAFT Version
The blue waveform shows the output voltage used to drive the motor. It changes from 0V to 5V as
the controller is switched on (this shows only one direction the other direction would be reversed).
The red waveform shows the equivalent voltage based on the percentage of time that the actual
voltage (blue) is turned on.

We start with the actual voltage completely off. The blue line (actual voltage) is at 0v as is the red
line (equivalent voltage). Then the power is applied for three tenths of a cycle and then turned off
for seven tenths of a cycle. This means that the equivalent voltage is three tenths of the voltage
which is 1.5V. Then the width of the PWM pulses increases so that it is on for six tenths and off for
four tenths which gives an equivalent of six tenths of the supply which is 3V. Finally the supply is
fully on giving an equivalent voltage of 5V. This is greatly simplified but shows how increasing the
width of the PWM pulses increases the voltage applied to the motor. The waveform above shows
how a motor could be accelerated, although in reality this would be over a much longer time period.
The waveform shows the voltage applied to the motor but it does not necessarily reflect
what actually happens with the motor. In reality the motor will not turn at all until the
supply is sufficient to get over the physical resistance posed by the motor and the
wheels connected to it. This is very different to how a stepper motor (different type of
DC motor) is controlled which allows the motor to be moved in individual steps corresponding to
different coils being powered on in the correct sequence.
It is possible to provide PWM using hardware or software. Hardware based PWM uses circuitry
within the processor to turn the pins on and off as appropriate, whereas software based PWM does it
using software running on the processor. Hardware driven PWM is usually preferred as it uses
minimal CPU load to implement, however the library chosen for this does not currently support
hardware based PWM. At the moment we will be using software based PWM, but in future versions
of the RPi.GPIO library that may change to hardware based. Also note that even with hardware
based PWM depending upon what else is running there is no guarantee that the code controlling the
PWM will be running when required. An alternative would be to use the Arduino (with or without a
Raspberry Pi) which can be much better at responding to events in real time.

Writing the software to make it work

We have now build the hardware including the electronic circuit to control the motors. What we
now need is the software to make it work. Before we start writing the software then we need to
determine what we expect it to do and how it should do it. If you are creating a formal project then
this is normally done through a formal software requirements specification (SRS). The software
44

DRAFT Version
requirements specification doesn't explain how the software is to be written, but should provide a
list of things that we need the software needs to perform to be successful. The detail of the
specification depends upon the size of the software project, but it's always a good idea to think
through the aims of the software before you start programming. I have included an example of a
software requirements specification in the Appendix, but I've created a more basic software design
guide below.

Basic software design points

This is a brief description of the software that we will need to design and some of the criteria of the
software.
The software created is to provide the control of a robot vehicle based around the Raspberry Pi
Ruby Robot. This software is intended as a demonstration of how the vehicle can be controlled, it
can then be used as a basis for future development of a program with improved functionality. The
software will allow a user to control the robot vehicle using key-presses and will control the motors
appropriately. It should allow change in speed and direction.
Will need to run on the Raspbian operating system
It should be easy to understand the software so that it can be developed further
It must be able to control the motor controller through the GPIO ports
Although it does not need to be network based it should be possible to control this by running over
a network based protocol (eg. ssh).

Using the design to provide implementation details

The software design is only a very brief example of what may be used. If you are at college then
you will need to follow their guidelines for any projects. Note that the specification doesn't provide
any details on what programming language to use or the specific details about how this should be
implemented. Instead it provides a high level overview of the important features which are used to
guide the decisions and then as a basis for checking if the objectives have been met when the
software is being developed and when it is complete. As with the design specification for the overall
project some aspects of the software design are a little vague: How do you measure how easy a
program is to understand?, but we can still use this as a guiding principle in the design of the
software.
Some things that may be appropriate to add are page layouts of the application pages or more
details of the way that the user interacts with the application. In this example we are just creating an
interactive command line application so it wasn't relevant.

45

DRAFT Version

Choosing the programming language

Whilst the choice of programming language often comes down to personal preference there are a
number of factors that should be considered when choosing a programming language especially if
the software may need to be maintained by others.
The main two factors that I used when deciding upon the programming language were the intended
audience and existing libraries that could be used. This is intended for teaching others that are new
to programming and Python is one of the most popular languages for learning programming,
especially on the Raspberry Pi. There are also some libraries written for Python to interact with the
GPIO ports including software based PWM. In particular the RPi.GPIO library is easy to use.

Getting started with Python

Unfortunately I don't have the space or the time to provide a comprehensive guide to learning
Python. There are however many books and guides dedicated to learning Python. What we will do
though is to consider how we can write the python code on the Raspberry Pi and an explanation on
how it works.
The first thing with Python is to decide what version to run. Oh no not more choices! I hear you
cry, but this is due to a transition that Python is going through. It's kind of the next step in becoming
an even better programming language. The older version of Python is version 2.7 which has been
around a long time and has lots of libraries written for it. The newer version is version 3 which has
many improvements, but is not backwards compatible and there are not so many libraries written
that work with version 3.
I tend to use version 2.7, partly because that's what I've been used to but also because it's currently
the default on the Raspberry Pi. Although both are installed, it is version 2.7 that will run if you just
type python on the command line:
$ python -V
Python 2.7.3

(note that the V should be a capital letter, lower case means something completely different).
There is a version of the RPi.GPIO module for both 2.7 and 3 and so this should run on either
version of Python.
The next thing is how to get the code onto the Raspberry Pi mounted in the robot vehicle. We can
either do this by plugging a screen, keyboard and mouse onto the Raspberry Pi (which is mounted
on the vehicle) or we can use our network connection to program or transfer the program to the
Raspberry Pi remotely. I will use the first example here as it's easier to understand, but
46

DRAFT Version
programming remotely can make it easier to make quick changes to your program when testing. For
now I'm going to assume you have a monitor (or TV) connected to the Raspberry Pi HDMI port and
a keyboard and mouse (perhaps through a USB hub). Alternatively you could edit the file directly
on the Raspberry Pi using ssh and the nano editor, or another alternative is to edit the file on your
desktop / laptop computer using your favourite text editor (such as IDLE or my personal favourite is
JEdit) and then save it as a text file and copy the file onto the Raspberry Pi using scp (part of the ssh
suite of tools).
When first setting up the Raspberry Pi we decided against booting to desktop (as when we don't
have a screen attached it's just a waste of resources), but using the GUI desktop will make it easier
for programming. So after logging in on the command line run startx to get to the desktop.
We will use the IDLE programming environment which provides a graphical editor as well as a
Python shell that can be used for testing the code. It also provides syntax highlighting, which means
that certain words will be displayed in different colours to make programming easier. Depending
upon your preference start either IDLE or IDLE3 for Python 2.7 or Python 3 respectively.

IDLE starts with a python shell. You can enter python commands straight into the shell and see how
the command works, but to add this program choose FileNew to create a new file.

47

DRAFT Version

The code can then be entered into the program editor.

48

DRAFT Version

You can see one of the advantages of using the IDLE editor in that the code is colour coded to make
it easier to follow. If this is your first python program just enter:
print("Hello world!")

and then choose Run from the menu and you should see Hello world! 'printed' on the screen in the
python shell.

Learning to program in Python

If this is the first time you've programmed in python then I suggest you take a look at some other
resources to get you up to speed before continuing to the more complicated bits. Or if you can't wait
that long to get your robot working copy the code to get your robot up and running and then come
back to here so that you can understand how it works and how to make it work even better.
A good starting point for learning programming is the Raspberry Pi Education Manual. This is good
because it's FREE, but also it's been put together by some great teachers who volunteered their own
time to help teach programming:
http://pi.cs.man.ac.uk/download/Raspberry_Pi_Education_Manual.pdf
49

DRAFT Version
Some other books are listed on the web page below
http://www.penguintutor.com/programming/books#python

Programming the GPIO with Python

One of the reasons for choosing the Python programming language one the existing modules which
make accessing the GPIO port easy to code. The RPi.GPIO module is included in the Raspbian
image provided with NOOBs.
This will explain how the GPIO code is going to work, but there is no need to enter this at the
moment.
To use the RPi.GPIO module it first needs to be imported using the line:
import RPi.GPIO as GPIO

Access to the GPIO port requires root access, so it is recommended that the import statement is
wrapped in a try clause to provide a more user friendly error.
try:

import RPi.GPIO as GPIO

except RuntimeError:
print("Error importing RPi.GPIO! This must be run as root using sudo")

After loading the module we can select the appropriate numbering scheme for the GPIO ports.
There are two numbering schemes, one which refers to the pin numbers of the GPIO port (1 to 26)
and the other that uses the port numbering on the BCM2835 processor. I have used the processor
number scheme using the following instruction.
GPIO.setmode(GPIO.BCM)

We then need to set the mode for any GPIO ports that we use. The following sets the pin defined by
pin_number as an output pin.
GPIO.setup(pin_number, GPIO.OUT)

If we just wanted to turn the pin on and off then we could use
GPIO.output(pin_number, True)

50

DRAFT Version

Using True or False to set the output to a logic high or low respectively.
Instead we want to use PWM so that we can vary the speed of the motors. To do so we still need to
set the pin as a GPIO.OUT port, but then set it up as a PWM output with the following command.
# set PWM_FREQ in Hz
PWM_FREQ = 50
pwm_pin = GPIO.PWM(pin_number, PWM_FREQ)
pwm_pin.start(0)

The PWM ouput can then be varied by using the ChangeDutyCycle command, with a value
between 0 and 100 where 0 is off and 100 is full on. The following will turn the PWM for the pin to
50% on.
pwm_pin.ChangeDutyCycle(50)

The duty cycle can be changed at any time using the ChangeDutyCycle method. When the program
finishes PWM can be stopped using
pwm_pin.stop()
GPIO.cleanup()

More details of the RPi.GPIO image is available from the sourceforge page:
http://sourceforge.net/projects/raspberry-gpio-python/

Remote control Python program

The initial program is listed in appendix C. This is an initial program with basic functionality
allowing the robot vehicle to be controlled using simple key presses.
Rather than copy and paste I recommend typing the code into IDLE. As you type the code in then
look to see if you can understand what the code is doing. It's not particularly long (well not
compared with the amount of typing I've done to create this guide anyway), but does include how to
interface with the GPIO port. I have provided a bit more of an explanation of how it works below.
The program uses the RPi.GPIO module explained previously.
After the initial set-up most of the code is a loop which sets each of the motors to the appropriate
direction and then waits for the next key press, which is handled using the getch function. Whilst
51

DRAFT Version
Python code can usually be run on different operating systems the code in the getch function will
only work on Linux or Unix based computers. This is because I wanted something that would
respond as soon as a key is pressed (rather than waiting for RETURN), but that didn't take up much
code or add further dependencies. The GPIO code is Raspberry Pi specific anyway so it would not
be possible for this program to work on other operating systems anyway.
The code starts with some constants (in capitals) and a few variables. Putting these as constants and
variables makes the code easier to understand and means that it is easier to change if we decided to
use a different GPIO pin, or wanted a different key comination.
It then initialises the GPIO pins and sets them ready for PWM output.
The main part of the code is in a while loop that sets the motors going in the appropriate speed and
direction and then waits for the user to press a key. After a key is pressed the current_direction
variable is changed which is then picked up the next time around the loop.
There are some print statements when a key is pressed which gives a visual feedback of the
direction and speed selected, but these are far from being user friendly. You could change these to
be more user friendly.
The program should be saved on the Raspberry Pi. Unfortunately it won't be possible to run the
program direct from IDLE as we won't have sufficient permissions to access the GPIO port.

52

DRAFT Version
Instead the file needs to be saved to the computer and run with root permissions.
First add execute permission
chmod +x robotcontrol.py

Then run using sudo

sudo ./robotcontrol.py

If it doesn't work then it is time to start debugging. One thing to be aware of with
Python is that both case and spacing is important. So check carefully through the code
to see if there are the correct number of spaces (they should be 4 spaces per level of
indentation). Any error message should also provide the line number that the error was
found. This may not be the exact position you need to look at, often it is a line or two previously,
but it should point you in the general area.
After checking that it now works correctly it is now possible to remove the monitor, keyboard and
mouse. The robot can now be controlled remotely using ssh.

Testing the robot

It should now be possible to connect to the robot using a mobile phone, tablet or computer using the
wireless network and an ssh client. Then cd to the directory with the program stored and run the
program with
sudo ./robotcontrol.py

You can now be possible to control the robot vehicle using the key presses shown in Appendix D.
Try the robot out, then read on for further suggestions.

Adding a camera
One feature that I did include in the specifications was the option to add a Raspberry Pi camera.
This is not required for the robot to work, so there is no need to buy one, buf it you do have one
then it is easy to add.
The Raspberry Pi camera is a small circuit board with a camera designed for use in mobile phones.
It connects to the Raspberry Pi through a dedicated connector on the Raspberry Pi board which is
located between next to the HDMI connector.

53

DRAFT Version

The main advantage over using this connector and the Raspberry Pi camera rather than a standard
USB webcam is that the camera can interface with the Graphics Processing Unit (GPU) on the chip.
This means that processing of the video can be done with less workload on the main processor
(CPU). One disadvantage is that the lead between the camera and the connector is very short. It may
be possible to get a slightly longer cable, but it won't provide the same distances that can be
achieved using a webcam. Careful positioning of the Raspberry Pi and the camera should help to
overcome this.
I mounted the camera using a Pimoroni camera mount. This is a fairly simple mount made of two
pieces of plastic that clip together. A good feature of this mount is that it made it easy to remove the
camera if access was needed to the HDMI port (during the initial build phase), however it became
evident that the position of the camera was too close to the floor to be particularly useful. The
camera does come in useful for finding lost bits of Lego from under the sofa, but a higher mounting
position or different angle would be better for getting an overview of the surroundings.

54

DRAFT Version

Using the camera

Before you can use the Raspberry Pi camera, it should be enabled through raspi-config (as
discussed in the initial operating system setup). There is software included in Raspbian that can be
used to take photos or videos or it is possible to communicate with the camera in your own code.
Currently I have just used the camera using the normal camera applications based around the
raspistill and raspivid.
If you are connecting through ssh then you will need to run the command through a second ssh
session. An alternative is to use the screen command, which would need to be installed on the
Raspberry Pi first.
The raspistill command can be used to capture a photo
raspistill -n -o filename.jpg

It is possible to view a video stream

First setup mplayer (for a Linux computer) run:
nc -l -p 5001 | mplayer -fps 31 -cache 1024 -

Then on the Raspberry Pi run:

raspivid -t 999999 -o - | nc [insert the IP address of the client] 5001

55

DRAFT Version
Unfortunately the camera streaming suffers from a significant time-lag, so it's very difficult to
actually use it to control the vehicle by. This is one of the suggestions for future development (see
later).
For more details see the Raspberry Pi Camera documentation at: http://www.raspberrypi.org/wpcontent/uploads/2013/07/RaspiCam-Documentation.pdf
You can also use the picamera python interface detailed at:
https://github.com/waveform80/picamera/

Developing the robot vehicle further

This guide has gone step-by-step through the initial set-up of the robot vehicle, but that is just the
beginning. This section discusses some ideas for future development, but leaves the actual
implementation down to the reader. Now that you've build the robot it should provide a good
starting point for the robot you want to make.
I will be looking at some of these in the future. As I do so then I will add them to my website.
www.penguintutor.com/electronics/rubyrobot

Remote control vs. autonomous robots

So what have we actually made is it a robot or a remote control vehicle? In fact it's both, but you
may be expecting a different type of robot.
Robots can vary from simple remote control devices to fully autonomous robots that sense their
environment and appear to be intelligent. Making a truly independent robot is well beyond the
scope of this guide, but there are some things that can be done to give the robot a little autonomy.
When we give the robot an ability to make a decision then it is called Artificial Intelligence (AI),
this varies from very simple decisions such as if hit an obstacle reverse and try a different
direction to learning robots that can find their way around a maze. Many of the suggestions I have
added for future developments are based on adding sensors to the robot so the robot can take some
decisions about where to move to or actions to take.
With a light source and sensor it's possible for a robot to see a line on the floor and follow that, or
with an ultrasound sensor it's possible to detect walls and obstacles.
It's also useful to know how far the robot has moved. Unfortunately it's not as easy as tracking how
long the motor has been turned on for, as that can depend upon how easily it moved on the floor and
the charge in the batteries.
56

DRAFT Version

The magician chassis includes rotary encoders on each of the motors which can be used with an
infra-red sensor to detect how much the motors have moved. Remember those discs I told you to
keep safe? They are shown on the gearbox in the diagram below.

Adding additional sensors

To add sensors we need some way of connecting them. Depending upon whether using the PCB or a
custom circuit there may be some spare GPIO ports that can be connected directly to suitable
sensors, but if wanting to add more than a couple of sensors then we need to look at how sensors
can be connected using I2C or SPI.

What is I2C and SPI?

I2C and SPI are protocols designed for communicating with external devices. These are usually
sensors or actuators, but could also include intermediate electronic circuits, such as a shift-register
or even to communicate with another processor. There are alternatives particularly if
communicating with a processor board, such as the Arduino, which can be handled via a serial
communication.
The Raspberry Pi includes support for both I2C and SPI and there are pros and cons of both
protocols. Both are designed to handle multiple devices over a reduced number of ports, but SPI
does need an additional port for each slave device, whereas I2C needs only two ports regardless of
the number of devices connected. The I2C ports are also made available via a connector on the
RyanTeck PCB. It is perhaps better therefore to use I2C unless there is another reason for selecting
SPI.

57

DRAFT Version

For more details there is a good write-up about I2C and SPI from Byte Paradigm
www.byteparadigm.com/applications/introduction-to-i2c-and-spi-protocols/

What's next?
So now we've just about reached the end of this guide. If you've been following this all the way
through then well done! Hopefully you've learned some valuable new skills and had some fun on
the way.
This should not be the end of the story, but the start of a new adventure. This guide has been about
preparing you with the skills to now make something really special out of your robot. I will be
developing my robot further in the future, and I'll post updates at:
www.penguintutor.com/electronics/rubyrobot
Here are some of my ideas on how this can be developed, but I'd love to hear about how you
develop yours too.

Improve the software

Web based interface or
Dedicated app on PC / mobile phone

Control the robot using Scratch or other programming languages

Add sensors
Microswitches
Ultrasound
Infrared

Make the robot talk

Make the robot able to do something

Pick up Lego bricks

Improve the camera streaming

Make it so that the camera can look in different directions

Continue to explore, play and learn and most importantly have fun!

58

DRAFT Version

Appendix A Shopping list

This is the basic list of components needed to make the robot vehicle. There are other components
that you may want to add later, but this is sufficient for now.
A more detailed list, including suppliers and prices is available from:
http://www.penguintutor.com/electronics/rubyrobot

Raspberry Pi Model A with NOOBS SD card

or model B

Magician Robot Chassis Kit

Raspberry Pi GPIO Cobbler kit *

Optional some soldering required if used

Breadboard (half-size) with power rails *

Screw terminal power jack (female)

Mini Wi-Fi dongle

SN754410 quad half bridge IC *

Jumper wires or solid core wire *

Jumper wires male to female *

Only required if not using optional cobbler

Raspberry Pi camera board

Optional

Pimoroni camera mount

Required if using Raspberry Pi Camera board
You may want to look at alternatives

I also recommend the Ryanteck Motor Controller Board, which will replace the components marked
with *. I think it is beneficial to make the circuit using on the breadboard which will help provide a
better understanding of how the circuit works.
The motor controller board requires soldering, which is not required with the breadboard.

59

DRAFT Version

Appendix B Software requirements specification

During the guide I included a brief software design specifciation to the robot, but if you are creating
a more formal project then you may need to create a more formal software requrieements
specification. This has therefore been included in the appendex.
I have only put together a very basic specification which covers the main subject areas. A full
specification for a formal project will normally have more sections and go into much more detail in
each of the sections. This is based on a very basic version of the robot software, other ideas
suggested in the future developments. The comments adding inside square brackets [] are included
for readers of this guide and are not part of the actual specification.

Software requirements specification for Ruby Robot v1

1.0 Introduction

The software created is to provide the control of a robot vehicle based around the Raspberry Pi
Ruby Robot. This software is intended as a demonstration of how the vehicle can be controlled, it
can then be used as a basis for future development of a program with improved functionality. The
software will allow a user to control the robot vehicle using key-presses and will control the motors
appropriately. It should allow change in speed and direction.
1.1 System overview

The system comprises of a Raspberry Pi (model A or B) running Raspbian Linux. The GPIO is
connected to a RyanTeck motor controller board (or equivalent circuit on breadboard).

2. 0 Overall description

The application should be a standalone application that can be used by the user to control the
vehicle.
2.1 System interfaces

The software must interface with the Raspbian operating system.

2.2 User interfaces

The program should be text based so that it can be run in a terminal window. The users will interact
with the software through key presses within the terminal application.
2.3 Hardware interfaces

The GPIO ports connect to the RyanTeck motor controller [a link could be provided showing details
60

DRAFT Version
of the motor controller in this case linking to elsewhere in this document]. The GPIO pins are
connected directly to the output pins on the Raspberry Pi processor.
2.4 Software interfaces

The software is not required to interface with any other software for this version. The software
should not prevent the Raspberry Pi camera functions from being used outside of the application. [A
future development may be to interface with the Raspberry Pi camera software, but it is not
included in this version]
2.5 Communication interfaces

No direct network communication is required, but the software must be able to work from within a
remote ssh terminal.
2.6 Memory constraints

The application must be able to run on a Model A Raspberry Pi with 256Mb of memory. This
includes other applications that may be running including the Raspberry Pi camera applications.

3.0 Specific requirements

3.1 Performance requirements

The software should be responsive to user interactions to allow immediate control of the vehicle. A
significant delay (more than 0.5secs) will make control very difficult.
3.2 Software system attributes

There is no specific reliability concerns in this version. This is intended as a demonstration only and
so in the event of a control failure there is only minimal risk of damage to itself or other objects.
The electronic hardware already incorporates protection to prevent invalid states causing a short
circuit. [See the H-Bridge section for details of how this could be a potential risk of causing a short
circuit.]
As this is not network based there is no security restrictions required to prevent unauthorised access.
If using ssh then the security credentials of the network configuration and the ssh authentication are
required to protect from unauthorised use.
3.3 Other requirements

This software is designed as a teaching aid to accompany the Ruby Robot project. It should
therefore be written so that those learning programming can understand how this works.

61

DRAFT Version

Appendix C Program listing robotcontrol.py

#!/usr/bin/env python
# RPi Magician Robot # see http://www.penguintutor.com/magician-robot
# robotcontrol.py
# Copyright Stewart Watkiss 2014
#
#
#
#
#
#
#
#
#
#
#
#

This code is free software: you can redistribute it and/or modify

it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This software is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this software. If not, see <http://www.gnu.org/licenses/>.

try:

import RPi.GPIO as GPIO

except RuntimeError:
print("Error importing RPi.GPIO! This must be run as root using sudo")
import sys, tty, termios
# get a character from the command line
# Linux/Unix only - but that's OK as RPi.GPIO is Raspberry Pi Linux only
def getch() :
fd = sys.stdin.fileno()
old_settings = termios.tcgetattr(fd)
try:
tty.setraw(sys.stdin.fileno())
ch = sys.stdin.read(1)
finally:
termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
return ch

# Motor
MOTOR1A
MOTOR1B
MOTOR2A
MOTOR2B

PINs
= 17
= 18
= 23
= 22

#left fwd
#left rev
#right fwd
#right rev

# freq of pwm outputs

PWM_FREQ = 50 #50hz
# uses processor pin numbering
GPIO.setmode(GPIO.BCM)

62

DRAFT Version
# speed = pwm duty cycle, 0 = off, 100 = max
speed = 50
# list to convert key presses into motor on/off values to correspond with the
direction
# direction based on number keypad or letters eg.
# 8 = fwd, 2 = rev, 4 = left, 5 = right, 7 = fwd left, 9 = fwd right, 1 = rev
left, 3 = rev right
# the key for the list is the character
# values are all tuples which hold (motor1, motor2)
# values are 0 = motor stop, 1 = motor fwd (A), 2 = motor rev (B)
direction = {
# number keys
'1' : (2, 0),
'2' : (2, 2),
'3' : (0, 2),
'4' : (1, 2),
'5' : (0, 0),
'6' : (2, 1),
'7' : (1, 0),
'8' : (1, 1),
'9' : (0, 1),
# keyboard keys
'r' : (1, 0),
't' : (1, 1),
'y' : (0, 1),
'f' : (1, 2),
'g' : (0, 0),
'h' : (2, 1),
'c' : (2, 0),
'v' : (2, 2),
'b' : (0, 2)
}
current_direction = (0, 0)
# setup pins
GPIO.setup(MOTOR1A,
GPIO.setup(MOTOR1B,
GPIO.setup(MOTOR2A,
GPIO.setup(MOTOR2B,
# set
pin1A
pin1B
pin2A
pin2B

GPIO.OUT)
GPIO.OUT)
GPIO.OUT)
GPIO.OUT)

pins as PWM
= GPIO.PWM(MOTOR1A,
= GPIO.PWM(MOTOR1B,
= GPIO.PWM(MOTOR2A,
= GPIO.PWM(MOTOR2B,

# start PWM
pin1A.start
pin1B.start
pin2A.start
pin2B.start

PWM_FREQ)
PWM_FREQ)
PWM_FREQ)
PWM_FREQ)

(0)
(0)
(0)
(0)

while True:
## Motor 1
# fwd
if current_direction[0] == 1 :

63

DRAFT Version
pin1B.ChangeDutyCycle(0)
pin1A.ChangeDutyCycle(speed)

# rev
elif current_direction[0] == 2 :
pin1A.ChangeDutyCycle(0)
pin1B.ChangeDutyCycle(speed)
# stop
else :
pin1A.ChangeDutyCycle(0)
pin1B.ChangeDutyCycle(0)
## Motor 2
# fwd
if current_direction[1] == 1 :
pin2B.ChangeDutyCycle(0)
pin2A.ChangeDutyCycle(speed)
# rev
elif current_direction[1] == 2 :
pin2A.ChangeDutyCycle(0)
pin2B.ChangeDutyCycle(speed)
# stop
else :
pin2A.ChangeDutyCycle(0)
pin2B.ChangeDutyCycle(0)
# Get next key pressed
ch = getch()
# q = quit
if (ch == 'q') :
break
elif (ch == '+' or ch == 'p') :
speed += 10
if speed > 100 :
speed = 100
print "Speed : "+str(speed)+"\n"
elif (ch == '-' or ch == 'l') :
speed -= 10
if speed < 0 :
speed = 0
print "Speed : "+str(speed)+"\n"
elif (ch in direction.keys()) :
current_direction = direction[ch]
print "Direction "+str(current_direction[0])
+str(current_direction[1])+"\n"
# Stop and cleanup the PWM
pin1A.stop()
pin1B.stop()
pin2A.stop()
pin1B.stop()
GPIO.cleanup()

64

DRAFT Version

Appendix D Key codes for remote control program

Ruby Robot Instructions

o
G

o
5

3
65

Fast
P
Slow
L

Fast
+
Slow
-

DRAFT Version

Glossary
AI See artificial intelligence.
Arduino A micro-controller board similar in size to the Raspberry Pi. Unlike the Raspberry Pi
most do not run a full operating system are instead programmed from a computer which can be
disconnected after programming.
Artificial intelligence A computer making decisions based upon input that makes it appear to
have intelligence. This can vary from simple decisions such as trying a different direction if a robot
hits an obstacle to complex learning.
Breadboard A board with strips of interconnections where electronic components can be easily
inserted and removed. Often used in creating prototypes of circuits to test functionality before
soldering in a more permanent solution.
Cobbler Breakout board for the GPIO that makes it easier to connect to a breadboard.
CMOS Complimentary Metal Oxide Semiconductor. Integrated circuits created using p-type and
n-type transistors.
Data sheet Document provided by component manufacturers that provides details of how the
component works.
EMF Electromotive force. Electrical energy created by a magnetic force.
Enable pin Often used on ICs to enable or disable the circuit inputs or outputs.
Ethernet Protocol used for wired networking.
FET Field Effect Transistor. A transistor that is switched on and off depending upon the voltage
on the gate. Available as N-channel and P-channel FETs.
Flyback diode A diode connected in the reverse direction across an inductive load (such as a
relay coil or motor) that dissipates voltage spikes that could otherwise damage senstive components.
FOSS Free and Open Source Software. Software created so that it is free to use and where access
is provided to the source code to allow changes and improvements to be made.
GNU Sometimes referred to as the GNU utilities these is the core programs that run on top of the
kernel to provide the basic commands needed to communicate with the operating system. These
were instrumental in the establishment of lots of FOSS software and the Linux operating system.
GPIO General Purpose Input Output. On the Raspberry Pi this is a 26-way connector with
connections to the processor.
GUI Graphical User Interface. A way of interacting with a computer using visual graphics such as
icons.
I2C Inter-Integrated Circuit. A way for connecting additional integrated circuits to the GPIO using
only 2 GPIO ports. An alternative to I2C is SPI.
IC see integrated circuit.
IDLE Integrated programming environment for Python.
Integrated Circuit Circuit built into a single chip. ICs for hobby use are normally provided in a
66

DRAFT Version
Dual Inline Package (DIP) with a row of pins on each side. They are also available for surface
mount.
Kernel The core part of the operating system that handles the program scheduling and
communication with the hardware.
Linux An open source operating system provided free and following FOSS principles. Linux
actually refers to the kernel, but is often used to refer to the entire operating system. The operating
system is sometimes called GNU/Linux to recognise the contribution of the GNU project in the
operating system.
PCB See printed circuit board.
Printed circuit board A board used to connect electronic components into a circuit. A printed
circuit board is normally created to match the custom design of the circuit.
Python Programming language which is often used in education and for commercial projects. It
includes modules that allow control of the Raspberry Pi GPIO.
Operating system A collection of software that manages the computer hardware and provides
ways for the applications to communicate with the hardware. On Linux this includes the Linux
kernel, the GNU utilities and is usually considered to include the graphics system.
Raspberry Pi An inexpensive credit card sized computer designed for teaching programming to
children. It has also been very popular with hobby enthusiasts (Makers) for using in embedded
computer projects.
SCP Secure copy. A method of transferring files between computers based on the SSH protocols.
Serial communication A method of communicating between computers or from a computer to an
external device. It sends data as a stream of pulses down the wire. It is useful for communicating
with an alternative processor such as an Arduino, or can be used to configure the Raspberry Pi from
another computer without needing a keyboard or monitor attached.
Shell A type of user interface using text commands.
Shield Often used to refer to add-on boards for the Arduino boards to add additional functionality
or to make it easier to connect to a home made circuit.
Software Requirements Specification A formal term way of defining how software should
behave. Used in the design phase to set the expectations and outcomes.
SPI Serial Peripheral Interface Bus. A way of connecting integrated circuits to the GPIO. It uses
4-ports, and then an additional enable port for each additional device. This compares with I2C
which needs only 2 ports for any number of devices.
SRS See Software Requirements Specification
SSH - Secure Shell. A network protocol that includes encryption of the network traffic to keep the
communication secure.
Stripboard A piece of material with copper strips for soldering electronic components to. Often
used as a way of making a more permanent circuit than a breadboard that does not involve the
complexity of creating a printed circuit board.
Transistor A semiconductor that switches a larger current based upon a small current at the base.
Available as NPN and PNP types.

67

DRAFT Version
TTL Transistor Transistor Logic. Logic circuits implemented using transistors.
USB Universal Serial Bus. Used for connecting computer peripherals such as keyboards and
mice.
Wi-Fi A wireless networking protocol. Used to provide wireless network access.

68

DRAFT Version

This guide is provided by:

www.penguintutor.com

This guide is provided through a creative commons license - Attribution-ShareAlike 3.0 Unported.
License details: http://creativecommons.org/licenses/by-sa/3.0/

69