PE Kit Tools: Propeller <-> PC Terminal Communication

Andy Lindsay (Parallax)

PE Kit Tools: Propeller <-> PC Terminal Communication


The Parallax Serial Terminal is a useful tool for testing code and displaying messages that include status indicators, variable values, I/O pin states and more.· In addition to displaying messages the Propeller sends to the PC, you can also use it to send messages to the Propeller chip.· These messages can come in handy for setting variable values and responding to menu prompts.·

In addition to general information, this article introduces a small Spin template to keep handy for adding Parallax Serial Terminal functionality to your applications and test programs.· It also provides a guided tour through Parallax Serial Terminal programs in the Propeller Library – Demos folder, along with examples of looking up the various method calls and constants the programs use in the Parallax Serial Terminal object’s documentation.· As you follow the step-by-step instructions in this article, consider how you might incorporate the Parallax Serial Terminal into your projects in progress.·

Full PDF & source code: PE Kit Tools - Propeller <-> PC Terminal Communication.zip
More info: PE Kit Labs, Tools, and Applications
Platform: Propeller Education Kit

Simple Startup Code

The Parallax Serial Terminal object is useful for small pieces of test code as well as for incorporating into applications that need some light debugging.· Figure 1 shows ·some minimal code you can use to start test applications, or add to applications in progress for debugging.·


Figure 1: Minimal Parallax Serial Terminal Code (left) and Parallax Serial Terminal (right)



First Time Setup

If this is your first time using the Parallax Serial Terminal, here are instructions for downloading the software and adjusting its settings:

P······ If you have not already done so, download and install the latest Propeller Tool software from www.parallax.com → Propeller → Downloads & Articles.· Versions 1.6 and newer contain the Parallax Serial Terminal, and the installer will place a shortcut on your desktop.
P······ Make sure your PE Platform is connected to your PC and has power.
P······ Use the Propeller Tool software's F7 function to Determine the COM port your Propeller’s programming tool is connected to.
P······ Run the Parallax Serial Terminal.
P······ Set the Parallax Serial Terminal‘s Com Port dropdown to the Propeller programming tool’s COM port number (that you found with F7 in a previous step).
P······ Set the Parallax Serial Terminal’s Baud Rate of 115200.
P······ Make sure the Echo On checkbox is checked.

Run the Test Program

Running the test program and viewing the results takes two steps.· First use the Propeller Tool software to load the application into the Propeller chip, then click the Parallax Serial Terminal’s Enable button.

P······ Enter the test code shown in Figure 1 into the Propeller Tool software.
P······ Click Run → Compile Current → Load EEPROM (F11).
P······ As soon as the Propeller Tool software’s communication window reports, “Loading…” click the Parallax Serial Terminal’s Enable button.



Make a Quick Start File

The code you just ran is a nice starting point for applications and test programs because you can use it to display values and messages along the way.· For example, if this code is in a file located at the top of the folder with your projects, you can make a copy of it to start each new project and test program.

P······ Save your work as PST Mini Template.
P······ Make a copy of the file that you can have ready for your next project or piece of test code.

Bidirectional Communication

Figure 2 shows the Parallax Serial Terminal’s Transmit and Receive windowpanes.· The Receive windowpane displays messages the Parallax Serial Terminal receives from the Propeller chip, and the Transmit windowpane forwards any characters you type to the Propeller chip.·


Figure 2: Transmit and Receive Windowpanes


By adding code to your application that receives strings and/or numeric values, you can set up tests for various conditions in your application to make sure that they are processed correctly.· It’s also convenient for setting up tests for certain bugs by setting variable values in the program before it performs a particular task you want to test.·

Test Bidirectional Communication

The Propeller Library – Demos folder has two example programs that show how to use the Parallax Serial Terminal in bidirectional communication:

········· Parallax Serial Terminal QuickStart.spin
········· Parallax Serial Terminal Demo.spin

Let’s try Parallax Serial Terminal QuickStart.spin first.· Figure 2 shows the Parallax Serial Terminal while this program is running.· The application receives decimal numbers you enter into the Parallax Serial Terminal’s transmit windowpane and displays their hexadecimal equivalents in the receive windowpane.· In the figure, the user entered the value 100 in reply to the first prompt, and the result was hexadecimal 64.· The user has just finished typing the decimal digits 256 into the transmit windowpane, and is about to press enter to see the next conversion.

P······ For this app, make sure the Parallax Serial Terminal’s Echo On box has a checkmark.
P······ In the Propeller Tool software, click File → Open From → Propeller Library Demos, and Open Parallax Serial Terminal QuickStart.
P······ Press F11 to load the application into the Propeller chip, and while it’s loading, click the Parallax Serial Terminal’s Enable button.
P······ When the Parallax Serial Terminal displays the “Enter decimal value:” prompt, type in a number into its Transmit windowpane (see Figure 2).
P······ When you press enter, the receive windowpane should display the hexadecimal equivalent of the value you entered.

Parallax Serial Terminal Object Documentation

The Parallax Serial Terminal QuickStart program you just tried demonstrates how to use some of the Parallax Serial Terminal object’s methods and constants. ·Here is a list of the ones it uses to do its job:·

········· Str to display text strings
········· DecIn to get a decimal value (entered as digit characters) from the Parallax Serial Terminal’s Transmit Windowpane
········· Hex to display hexadecimal values
········· NewLine to move the Parallax Serial Terminal’s cursor to the next line
········· Dec to display a decimal value
········· pst#NL (a constant in the Parallax Serial Terminal object) transmitted as a character or in a string has the same result as the NewLine method

All of these features are explained in the Parallax Serial Terminal object’s documentation comments.· Try looking up each method.

P······ Open the Parallax Serial Terminal object with the Propeller Tool software.· (File → Open From… → Propeller Library.
P······ Click the documentation radio button.·
P······ Examine the following sections:
o······· Object “Parallax Serial Terminal” Interface (partially shown in Figure 3).
o······· Parallax Serial Terminal Control Character Constants
o······· Method explanations from the Start method downwards.


Figure 3: Excerpt from Parallax Serial Terminal Object in Documentation View



Parallax Serial Terminal Demo

The Parallax Serial Terminal Demo program is also in the Propeller Library – Demos folder.· It demonstrates even more of the Parallax Serial Terminal object’s features, and will give you a few more methods and constants to look up in the Parallax Serial Terminal object’s documentation.

P······ Try File → Open From… → Propeller Library – Demos → Parallax Serial Terminal Demo
P······ Reconcile the method explanations in the Parallax Serial Terminal object’s Documentation.

More Examples

The Objects Lab in Propeller Education Kit Labs: Fundamentals includes lots of examples that use the Parallax Serial Terminal.· It’s available for PDF + zipped source code download from www.parallax.com → Propeller → Downloads & Articles.· Note that the PE Kit Labs book relies on an object named FullDuplexSerialPlus.· This object is a predecessor of Parallax Serial Terminal.· Some of the method names will be different, but the Parallax Serial Terminal object has all the functionality of FullDuplexSerialPlus, and includes a few small bug fixes as well.· So if you have been using FullDuplexSerial or FullDuplexSerialPlus, consider switching to the Parallax Serial Terminal object from here onward.

Exercises

1)····· Write a program that displays the value of an index for each repetition of a loop that counts to ten using repeat i from 0 to 10.· Add some code to determine the value of the index variable i after the loop has completed.·
·
CON·····························
································
· _clkmode = xtal1 + pll16x·····
· _xinfreq = 5_000_000··········
································
OBJ·····························
································
· pst·· : "Parallax Serial Terminal"
·
PUB go | i·····························
·················································
· pst.Start(115_200)
· pst.Str(String("Loop: "))
· repeat i from 0 to 10
··· pst.Dec(i)
··· pst.Char(" ")
· pst.Str(String(pst#NL,"After loop: "))
· pst.Dec(i)
·
2)····· Write a loop that contains i++ in a pst.Dec method call.· Compare the values against ++i.
·
CON·····························
································
· _clkmode = xtal1 + pll16x·····
· _xinfreq = 5_000_000··········
································
OBJ·····························
································
· pst· ·: "Parallax Serial Terminal"
·
PUB go | i·····························
·················································
· pst.Start(115_200)
·
· pst.Str(String("Test post/pre increment...", pst#NL))
· pst.Str(String("i := 25, pst.Dec(i++) -> "))
· i := 25
· pst.Dec(i++)
· pst.NewLine
· pst.Str(String("i := 25, pst.Dec(++i) -> "))
· i := 25
· pst.Dec(++i)
· pst.Newline·
·
Look up some Spin commands in the Propeller Manual, and write programs to test and verify your understanding of a command you are already familiar with as well as one you haven’t tried before.


▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Andy Lindsay

Education Department
Parallax, Inc.

Post Edited (Andy Lindsay (Parallax)) : 8/24/2010 6:03:55 PM GMT