In this tutorial, I'll show you how to use the Parallax Serial Terminal for debugging with the Propeller. This builds on my other tutorials which you can find here.
The Parallax Serial Terminal is a simple, underrated piece of software which is installed automatically with the download and install of the Propeller Tool from Parallax. You’ll find the shortcut for it in the same “Start/Menu” group as the Propeller Tool.
On the surface, the Parallax Serial Terminal, or PST doesn’t seem like an important tool; that is until you start writing spin code which works with internal variables, retrieving data from a sensor, or simply start wanting to pull out hair due to a chunk of code that isn’t doing what you expected for unknown reasons. PST allows us to pull back the curtain and view what is happening behind the scenes. Because it requires only the existing programming connection to the Propeller, PST also provides us a valuable way to interact with our Propeller when on the road when other output devices like TV or VGA screen connection simply aren’t possible. I’m about to introduce you to your new best friend.
To use PST, you’ll need to be armed with a little information about where the computer sees your Propeller connected. When the Propeller is plugged into your computer, the special USB chip on the programming plug, or on the board itself (depending on your configuration) sets up a Serial Communication Port, (COM port) and assigns it a number. We can obtain that number by simply starting up the Propeller Tool, turning on your Propeller board and pressing F7. Simply make a note of the detected COM port for reference. (Twenty years ago, serial communication was the standard that almost all computers and devices. It was used with very specific port numbers with strict rules. Thankfully computing has evolved to the point where we can take advantage of this time tested standard easily.) Launch PST. Using the left-most drop down select your “Com Port:” matching the one detected with the Propeller Tool.
There are a number of other controls here which provide a degree of visual complication. Don’t be alarmed by them. The controls we will be using 99% of the time are the Com Port: setting which you are now familiar with, the Baud Rate setting, and the Disable/Enable button. If you really want some heavier, geek reading on the other checkboxes, and indicators, there is an excellent article on how serial communication works on howstuffworks.
By now you should have PST running with the proper “Com Port” set. It’s time to jump into the Programming Tool again and do some programming.
Parts
For this lesson, you'll need the following parts
- A Parallax Propeller (A Propeller Platform USB works great, but you can also use a protoboard or demoboard)
- A Ping))) Sensor (Source: Parallax)
- A 1k ohm resistor
- A 3 wire servo cable (or plug the Ping into a breadboard and use jumpers to connect to the Prop)
- LED & resistor from the blinky light lesson
The Code
Download: Code Archive
Let’s make things interesting. Take a few minutes to reconnect the LED and resistor combination from Lesson 1. We will expand on the code from that lesson a bit.
Type in the following code and send it to your Propeller with F10;
We’ve added a few lines of code to increase the speed of the Propeller to 80mhz. The LED seems to flash at same steady rate, but in reality the Propeller is operating at a much faster speed. Flashing a simple LED doesn’t require the Propeller to operate at full speed, but our next additions will take advantage of the power of PST so we’ll want the extra horsepower.
This time we’ll plug in some code for Parallax Serial Terminal.
Consider the following additions to our spin program:
We’ve added an OBJ section which tells our program to include the Parallax Serial Terminal to our code. This object is a collection of methods which will provide the interaction from our blinky light program to the PST software. Now let’s break down the three additional lines;
The PST.Start(115200) gets the object up and running on another cog with a Baud Rate of 115,200. Think of the Baud Rate as the speed setting our program and the PST program will use to talk to each other. Make a quick note of the speed as we will need to set PST to the same setting.
Notice that I’ve inserted some lines which start with pst.str after each of the outa statements. Monitoring the code from Parallax Serial Terminal, we can tell that the code is working correctly even if the LED is defective or removed from the circuit.
The method, pst.str is used to send a line of text to the Parallax Serial Terminal. See that 13 toward the end of the line? The ASCII code “13” is a carriage return telling the terminal to jump to the next line.
Once the program is running in the Propeller, launch the Parallax Serial Terminal and press the Enable button to begin taking data from the Propeller.
By now you can see that inserting some simple lines in your code Parallax Serial Terminal will allow you to troubleshoot problem code.
It’s time to take things a step further by reading some real data from a device and displaying that information on PST.
Make the three connections between your Propeller Platform Module and the PING))) sensor. Use the 1K resistor between ‘signal’ connection of the PING))) sensor and P0 as shown in the image below. The 1K resistor protects the Propeller chip from the higher voltage (5v) required by the sensor.
After making the required connections, type and run the following program:
Our program uses several of the more common methods included in the Parallax Serial Terminal code. We’ve included a new object ping in the OBJ section giving us everything we need to communicate with the PING))) sensor.
The main section breaks down as follows:
| repeat | Creates a loop. Everything indented below to loop over and over |
| range := ping.Inches(0) | Calls a method from ping to calculate inches from P0 |
| pst.clear | Clears the terminal screen |
| pst.str | Displays the line of text "PING))) distance in inches: " |
| pst.dec() | Displays the number contained in our range variable in decimal format |
| waitcnt | Provides us a small delay before returning to the top of the loop |
Run the PST program again. This time you should have distances from the PING))) sensor displayed in the Terminal window.
By now you should be able to see how adding a few simple lines you can debug and/or view information from your Spin program using Parallax Serial Terminal. No more wondering what your program is doing inside chip!