Preliminaries - Hardware And Software For Labs

Software Guide

Universidad Nacional de Colombia

February 23, 2017

1 Introduction
Welcome to the software guide. For working with the labs, we've designed a set of software that
should let you easily vary feedback control parameters in live-running systems controlled by your
Teensy Board. This software is brand new, and part of what we're doing with this iteration of the
course is testing it out. It is all open-source, and built using open-source tools (part of why we
picked Teensy!) so if you want to mess with it, do whatever you want with it, just be aware that
if you change things about it, it may not work, so be ready to re-download the code if needed!
The idea behind the code is shown in the Figure 1 below.

Figure 1: The basic workow of our software for controlling and analyzing things!

1. The Teensy interfaces with the DC Motor by sending pulse-width modulated (pwm) signals
to the H-Bridge motor driver and by reading the position/speed sensor (encoder). Its pwm
output signal is derived from sensor readings in a feedback control loop (that you will modify).
The control loop's behavior is adjusted by values/parameters sent to it from a python-based
local server running on your computer using serial communication. In addition, at regular
intervals, the Teensy sends its measurements back to the Python server.

2. The python-based local server running on your computer is an interface. It communicates

with the Teensy via serial link, and with a Browser-based GUI via WebSockets.

3. The Browser-based GUI plots measured data from the Teensy, passed to it by the local server,
and provides simple interface for users to change the Teensy feedback loop parameters, which
it passes on to the local server.

2 Parts of the Software

The entire package of software is broken down into three pieces:
• Microcontroller Code: This is the code uploaded to the Teensy (the .ino le). It sets the
Teensy up for listening to and controlling the electronics as well as taking in parameters and
reporting values to your computer over serial (the USB cable). It is written in Arduino's
C/C++ type language.

• Server Code: This is a Python script that talks with the Teensy over serial, does some
calculations, and then talks with the GUI code in your browser. It is the "middle-person" of
our software stack.

1
 • GUI Code: Your GUI (Graphical User Interface) is basically just a web-page that is hosted
on your machine. It is written in standard html/css/javascript. Don't worry, it is locally
hosted and only you have access to it! It lives at localhost:3000 in your browser url eld when
the server script is running.

3 Questions
Why did we pick a browser-based GUI for controlling the DC Motor?:
The reason really comes down to compatibility across lots of platforms. One of the goals we
have with this course is to see how eectively we can enable the study of control theory in a dis-
tributed environment. Python does a pretty good job of maintaining libraries that function reliably
(or at least predictably) across the Windows/Mac/Unix/Linux spectrum, but plotting/graphics,
particularly in real-time, is something that is bit tougher to do across all platforms. Web Browsers
can be seen as a nice solution to this problem. Pretty much everybody and their respective operat-
ing system has a web browser, and most modern web-browsers can provide a uniform environment
in which we can deploy graphics, since graphics in the browser are pretty standardized (with some
exceptions).

What languages and libraries are used?

Well, the Arduino avor of C/C++ is used for the Teensy.

For the Python software we use the following libraries:

1. Flask and its support for Eventletis used for creating a functioning WebSocket server. This
guy is basically like the Flask expert and his work was very helpful in getting this aspect of
the software working

2. Pyserial is for its ability (as its name suggests) to give Python reliable serial port access.

For the Web GUI, standard html, css, Javascript, Bootstrap, jQuery were all used. Plotting
was done using the D3 library.

4 Installation
4.1 Getting Started

The code distribution we'll use for this software introduction is found in the supported les pro-
vided to you with this document. This is the base le for testing and setting up.

While the Python and html/javascript les are the same for all labs, we use dier-
ent microcontroller code sets for each lab, these codes will be provide to you in each
lab.
Download the .rar le, extract it, and look inside. You'll see the following things:

• An empty directory called csv_les. Don't worry about this thing for right now.

• The le server .py. This is the Python script you will run on your machine for establishing
communiation with your Teensy and browser GUI (Graphical User Interface)

• The le index.html. This is a webpage that acts as your GUI.

• The le req.txt. This is a le that lists libraries needed in addition to normal Python. Don't
worry about it right now, but we'll use it during install.
• The directory static. This has the javascript/css libraries your browser GUI uses. We use
local copies of these libraries so you can run this software when not connected to the internet.
Just leave this as it is.

2
 • The directory called teensy_test. These contain simple communication check microcontroller
code le for the Teensy 3.2. They are good "sanity check" les.
Ok onto the install. We'll rst start with the Arduino/Teensy Environment.

4.2 Arduino Install

In the standard way of taking this course, you'll be using an Teensy 3.2 to directly control the
systems we're analyzing (DC Motor). As a result, you will need a functioning Arduino IDE
environment on your machine both to upload code and to let your computer have serial access to
it (This is not the only way to program the Teensy, but the one we will use). We'll point you to
get the Arduino IDE running (if you don't have that already).
Depending on what your background is, you can either just head on over to the Arduino
Download Site, and install it. Or maybe, if you'd like more details with the install, Arduino has
some nice walkthroughs for each of the big operating system families:

• Windows: https://www.arduino.cc/en/Guide/Windows
• Mac OS X: https://www.arduino.cc/en/Guide/MacOSX
• Linux: http://playground.arduino.cc/Learning/Linux

4.2.1 TEENSYDUINO SOFTWARE ADD-ON

As we are using a Teensy 3.2, once you've got your Arduino IDE working, go to the
PJRC software site at https://www.pjrc.com/teensy/td_download.html and follow the
instructions for adding their Teensy add-on software. This stu has been shown to
work on all OS's!
4.2.2 New to Arduino?
If you're new to Arduino, don't worry! We don't really require any actual coding of the Arduino in
this course since we'll provide you the code les that do what we need to do in lab. All
we really need for you to do is to be able to upload an Arduino script (.ino le) onto the Teensy
3.2 using the IDE. Following the step-by-steps above should get you up through this point. If you
run into problems, check out the Arduino Troubleshooting Page: https://www.arduino.cc/en/
Guide/Troubleshooting.

4.3 Python Install-PYTHON ON WINDOWS

Windows does not come with Python usually. If you already have it, determine what version you
have:

• If it is Python 2, make sure it is at or above Python v2.7.9

• If it is Python 3, make sure it is at or above Python v3.4

One easy way to check on your Python is to open up a Windows PowerShell up and inside, type:

python version

Some text should come back telling you if you have Python and what version it is. Red text
probably means you don't have it. Our code should work on both Python versions 2.7 and
If you do not have Python installed, you will need
above as well as Python 3.3 and above.
to do that. I'd recommend getting Python 3 for this software, though both families (2.7+
and 3+ will work). Go to the Python Download Page: https://www.python.org/downloads/,
I'd recommend the .exe installer if
nd the appropriate install version for your computer (
you're ok with that), follow the well-written directions, and you should be good to go.
IMPORTANT!!!: It is very important that during the install you check the option
about adding Python to your Path which happens on the rst/second window of the
installer executable!!!

3
4.3.1 PIP
The next piece which you need is pip, which is a nice Python Package Manager that we use to
install the appropriate install les. If you download either the newest version of Python 2 (after
v 2.7.9) and any version of Python3 starting with Python 3.4 you should have pip preinstalled.
To make sure you have pip, run the following command in the Windows PowerShell (not the
Python shell!) or Windows Command prompt!:

pip version

If some stu comes back giving you a version number, you'll be good to go. If not
I'd recommend you update your Python (using the Python download link above) and
in the process get pip by default!
4.3.2 TROUBLESHOOTING
Python can sometimes be a little dicult to get working on a Windows machine. The following
resources may be helpful:

• Using Python on Windows:

https://docs.python.org/2/using/windows.html
• How to Install Python on Windows:
https://www.howtogeek.com/197947/how-to-install-python-on-windows/
• Python Guide:
http://docs.python-guide.org/en/latest/starting/install/win/
• How to Install pip on Windows (The easy way):
https://www.youtube.com/watch?v=zPMr0lEMqpo
• How to Add the Python Path In Windows 7Installing Python and Pip using Powershell:
http://stackoverflow.com/questions/3701646/how-to-add-to-the-pythonpath-in-windows-7

4.3.3 Additional Software

Assuming you got everything working on the previous page, move into the course le you down-
loaded in your Windows PowerShell (not the Python shell) or Command shell. Once there,
run the command (you may be prompted for a machine password based on your settings):

pip install -r req.txt

(Note: if you're using Python3 you may (not necessarily) need to do pip3> install -r
req.txt instead!)

It may take a minute or so depending on your machine. A whole bunch of text should y by
in a neutral color like green (if red stu appears, it *may* mean there was an error in install. At
that point I'd head to the email and we'll try to see what we can gure out.).

If the install was a success, the next thing you need to do is start the server using Python. Type:

python server.py

(Note: Depending on how you set up your Python, it may be called by the command "python3"
rather than just "python". Try both if you have issues. On my several test installs on "clean"
Windows machines, when installing Python 3.5, it just established "python" and "pip" as the ap-
propriate commands, but it is possible that the could end up as "python3" and "pip3".)

After starting running, some stu will appear, but as long as it isn't very long it means you
should be good. Head on over to a browser (Google Chrome, Mozilla Firefox,...etc) and in the

4
URL eld type:

localhost:3000

You should see something similar to that shown in the image 2 below.

Figure 2: Browser-Based GUI

Figure 2 shows what the Browser-Based GUI should look (sort of depending on version) like
when you rst open it. In the top pull-down tab at right, you should hopefully see the Serial port
associated with your microcontroller (assuming drivers have been isntalled for it which will have
been the case if you succssessfully uploaded the test code in the previous step).
If you've got stu working the way describe above, you should be good.

4.4 Python Install-PYTHON ON MAC OSX

Note: If you are able to, updating to the most recent version of OSX can minimize the chance of
installation problems popping up with Python associated with stdio.h not being present

If you've got a Mac, chances are you most likely already have Python installed on your machine.
If you go to the Launchpad and search for "Terminal" you should nd a symbol that looks sort of
like Figure 3:

Figure 3: Terminal Figure

If you're not familiar with the terminal, I would check out this link:

How to Use Terminal on a Mac

http://www.macworld.co.uk/feature/mac-software/get-more-out-of-os-x-terminal-3608274/

just to see some basic commands. It can seem a bit intimidating at rst, but it we aren't doing
anything too dicult with it so just a bit of practice should be enough.

Open the terminal up and inside, type:

python version

to see if you have Python Version 2 and:

python3 version

to see if you have Python Version 3. Some text should come back telling you if you have Python
and what version it is. Our code should work on both Python versions 2.7 and above as well as

5
Python 3.3 and above. If you do not have Python installed, you need to do that. I'd recommend
getting Python 3 for this software, though both families (2.7+ and 3+ will work). Go to the
Python Download Page,

https://www.python.org/downloads/

nd the appropriate install version for your computer, follow the directions, and you should be
good.

4.4.1 PIP
The next piece which you need is pip, which is a nice Python Package Manager that we use to
install the appropriate install les. If you download either the newest version of Python 2 (after v
2.7.9) and any version of Python3 starting with Python3.4 come with pip preinstalled. To make
sure you have pip if you're using the Python 2 family, run:

pip version

If you're using the Python 3 series, run:

pip3 version

If some stu comes back giving you a version number, you'll be good to go. If not I'd recommend
you update your Python (using the Python download link above) and in the process get pip by
default!

4.4.2 Additional Software

Assuming you got everything working on the previous page, move into the course le you down-
loaded in your Terminal. Once there, run the command (you may be prompted for a machine
password based on your settings):

pip install -r req.txt

(Note: if you're using Python3 you may (not necessarily) need to do pip3> install -r
req.txt instead!)

It may take a minute or so depending on your machine. A whole bunch of text should y by
in a neutral color like green (if red stu appears, it *may* mean there was an error in install. At
that point I'd head to the email and we'll try to see what we can gure out.).

If the install was a success, the next thing you need to do is start the server using Python. Type:

python server.py

(Note: Depending on how you set up your Python, it may be called by the command "python3"
rather than just "python". Try both if you have issues. On my several test installs, when installing
Python 3.5, it just established "python" and "pip" as the appropriate commands, but it is possible
that the could end up as "python3" and "pip3".)

After starting running, some stu will appear, but as long as it isn't very long it means you
should be good. Head on over to a browser (Safari, Vivaldi,...etc) and in the URL eld type:

localhost:3000

You should see something similar to that shown in the image 4 below.
Figure 4 shows what the Browser-Based GUI should look (sort of depending on version) like
when you rst open it. In the top pull-down tab at right, you should hopefully see the Serial port

6
 Figure 4: Browser-Based GUI

associated with your microcontroller (assuming drivers have been isntalled for it which will have
been the case if you succssessfully uploaded the test code in the previous step).
If you've got stu working the way describe above, you should be good.

4.5 Python Install-PYTHON ON UNIX/LINUX

Depending on your Unix/Linux distribution, you may already have Python. You can check by
opening up a terminal up and typing:

python version

to see if you have Python Version 2 and:

python3 version

to see if you have Python Version 3. Some text should come back telling you if you have Python
and what version it is. Our code should work on both Python versions 2.7 and above as well as
Python 3.3 and above. If you do not have Python installed, you need to do that. I'd recommend
getting Python 3 for this software, though both families (2.7+ and 3+ will work). Go to the
Python Download Page:

https://www.python.org/downloads/

nd the appropriate install version for your computer, follow the directions, and you should be
good.
Depending on your settings you could also just do:

sudo apt-get install python

for Python 2 or

sudo apt-get install python3

for Python 3.

4.5.1 PIP
The next piece which you need is pip, which is a nice Python Package Manager that we use to
install the appropriate install les. If you download either the newest version of Python 2 (after v
2.7.9) and any version of Python3 starting with Python3.4 come with pip preinstalled. To make
sure you have pip if you're using the Python 2 family, run:

pip version

7
 If you're using the Python 3 series, run:

pip3 version

If some stu comes back giving you a version number, you'll be good to go. If not I'd recommend
you update your Python (using the Python download link above) and in the process get pip by
default!

4.5.2 Additional Software

Assuming you've done everything you need to done all the tasks listed above and on previous
pages, download the zip le provided, extract it, and then move into the newly extracted folder in
your terminal. Once there, if you're using Python 2, run the command (you may be prompted for
a machine password based on your settings):

sudo pip install -r req.txt

Or if you're a Python 3, do:

sudo pip3 install -r req.txt

It may take a minute or so depending on your machine. A whole bunch of text should y by
in a neutral color like green (if red stu appears, it *may* mean there was an error in install. At
that point I'd head to the email and we'll try to see what we can gure out.).

Note: One bug I ran into when installing on my Ubuntu v15.04 machine was I didn't have
developer packages installed...If you get an error, try running:

sudo apt-get install python3-dev

sudo apt-get install libevent-dev

Then try the pip install again!

If the install was a success, the next thing you need to do is start the server using Python. Type:

python server.py

After starting running, some stu will appear, but as long as it isn't very long it means you
should be good. Head on over to a browser (Chromium, Firefox...etc) and in the URL eld type:

localhost:3000

You should see something similar to that shown in the image 5 below.

Figure 5: Browser-Based GUI

8
 Figure 5 shows what the Browser-Based GUI should look (sort of depending on version) like
when you rst open it. In the top pull-down tab at right, you should hopefully see the Serial port
associated with your microcontroller (assuming drivers have been isntalled for it which will have
been the case if you succssessfully uploaded the test code in the previous step).
If you've got stu working the way describe above, you should be good.