QuickStart 6: Using the Parallax Serial Terminal

The Parallax Serial Terminal is a simple, underrated piece of software which is installed automatically by the Propeller Tool installer from Parallax.   (A shortcut for PST can be found in the same “Start Menu” group as the Propeller Tool.)

PST is actually an important asset in programming as it allows us to pull back the curtain and view what is happening behind the scenes, making it a handy debugger.   Because it requires only the existing programming connection to the Propeller, PST also provides a valuable way to interact with the Propeller when on the road when other output devices like a TV or VGA screen connection simply aren’t possible. 

When the Propeller is plugged into your computer, the FTDI chip on your Quickstart board is assigned a serial port number by Windows. 

• Obtain that number by starting up the Propeller Tool and pressing F7.  
• Make a note of the detected COM port for reference and launch PST. 
• Using the left-most drop down select “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 commonly used controls are the “Com Port:” setting, the “Baud Rate” setting, and the Disable/Enable button.  

The following Spin program is lesson2.spin from the QuickStart 2: Propeller Programming First Steps.  It is a simple LED flasher.

CON

  _clkmode = xtal1 + pll16x
  _xinfreq = 5_000_000

PUB LedOnOff                        ' Method declaration 
                       
    dira[16] := 1                   ' Set P16 to output

    repeat                          ' Endless loop prevents
                                    ' program from ending.
     
        outa[16] := 1               ' Set P16 high 
        waitcnt(clkfreq/4 + cnt)    ' Wait a moment
        outa[16] := 0               ' Set P16 low
        waitcnt(clkfreq/4 + cnt)    ' Wait a moment
        

The LED flashes at a steady rate.   As long as the LED continues to work correctly, the program can be observed as working correctly, but what would happen if the LED failed?

Consider the following additions to the Spin program:

CON

  _clkmode = xtal1 + pll16x
  _xinfreq = 5_000_000

OBJ

   pst : "Parallax Serial Terminal"
   

PUB LedOnOff                          ' Method declaration 
    pst.start(115200)                 ' Start PST on another cog.  
    dira[16] := 1                     ' Set P16 to output

    repeat                            ' Endless loop prevents
                                      ' program from ending.
     
        outa[16] := 1                 ' Set P16 high 
        pst.str(string("LED ON", 13)) ' Send "LED ON" to PST
        waitcnt(clkfreq/4 + cnt)      ' Wait a moment
        outa[16] := 0                 ' Set P16 low
        pst.str(string("LED OFF", 13))' Send "LED OFF" to PST   
        waitcnt(clkfreq/4 + cnt)      ' Wait a moment
        

An OBJ block has been added, instructing the program to include the Parallax Serial Terminal in our code.  This object is a collection of methods which will provide the interaction from the LED flasher program to the PST software.

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 which the program and the PST program will use to talk to each other.   Make a quick note of the speed and set PST to the same setting.

The additional changes to the program include two lines which start with “pst.str” after each of the outa statements.  The method call pst.str is used to send a line of text to the Parallax Serial Terminal.  Note the 13 toward the end of the line.  The ASCII code “13” is a carriage return telling the terminal to jump to the next line.

Monitoring the code from Parallax Serial Terminal, we can tell that the code is working correctly even if the LED is defective, wired incorrectly, or removed from the circuit.

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.

Commonly used methods included with Parallax Serial Terminal:

• start(baud_rate)— Start PST in another cog at the specified baud rate.
• str(string(“ “))— Send a text string to the PST window.
• dec( )— Display contents of a variable as a decimal number on the PST window.
• newline— Send a carriage return to the PST window.

This QuickStart demonstrates Parallax Serial Terminal used as a simple debugging tool.  PST is also capable of user input as well as many advanced display functions.   Full documentation for PST can be found in the free Propeller Education Kit Labs: Fundamentals text[1].