Parallax Propeller Book - Parallax Serial Terminal

Parallax Serial Terminal

The Parallax Serial Terminal software (PST.exe) is a convenient tool for PC/Propeller chip communication.

It displays text and numeric messages from the Propeller chip and also allows you to send similar messages to the Propeller chip.

How to Start PST

  1. Start Propeller Tool
  2. At top Left click Run
  3. In a Pop Up menu click Parallax Serial Terminal

The Parallax Serial Terminal will open in new window.

PST Window
Figure 16-1 PST window

This Parallax Serial Terminal has a Transmit windowpane that sends characters you type to the Propeller chip [Top Yellow], and a Receive windowpane that displays characters sent by the Propeller chip [Light Blue].

It has drop-down menus for Com Port and Baud Rate selection and port activity indicators and checkbox controls for the various serial channels (TX, RX, etc).

There’s also an Echo On checkbox that is selected by default so that characters entered into the Transmit windowpane also appear in the Receive windowpane.

On the Parallax Serial Terminal window’s lower-right, there are control buttons that:

The [Disable/Enable] button in the Parallax Serial Terminal’s lower-right corner is important. (See Figure 16-1.)

When it displays Disable, it means the terminal is connected to the serial port.

When you click the [Disable] button, the Parallax Serial Terminal releases the serial port so that the Propeller Tool can use it to load a program into the Propeller chip.

While the Parallax Serial Terminal is disabled, the button displays [Enable], flashing on/off.

After the program has loaded, you can click the [Enable] button to resume terminal communication with the Propeller chip.

Automatic Disable/Enable Settings:

In Prefs → Serial Port Selection, the Automatically disable… and Wait for busy… checkboxes are selected by default.

With these settings, you can just click the Propeller Tool software, load a program, and immediately click the [Enable] button to reconnect.

There’s no need to click [Disable] before switching to the Propeller Tool to load a program because the Parallax Serial Terminal will automatically disconnect from the serial port as soon as you have clicked another window.

Likewise, you don’t have to wait for the program to finish loading into the Propeller chip before clicking the [Enable] button.

You can just click it as soon as you have started the program loading, and the Parallax Serial Terminal will detect that the serial port is still busy and wait until the Propeller Tool is done loading the program before it reconnects.

You can click the Parallax Serial Terminal’s [Prefs] button to view the [Appearance] and [Function] preference tabs shown in Figure 16-2.

 

Preferences Window
Figure 16-2 Preferences pop up window

 

The [Appearance] preferences allow you to define the terminal’s colors, fonts, and other formatting.

The [Function] preferences allow you to select special functions for non-printable ASCII characters.

Leave all of them checked for this tutorial since we’ll be using them to clear the screen, display carriage returns, etc…

It’s also best to leave both the boxes in the Serial Port Selection category checked.

The Automatically Disable… feature makes the Parallax Serial Terminal automatically disable to free the serial port for program loading whenever you click the Propeller Tool software.

Wait for busy port… makes the Parallax Serial Terminal automatically wait up to 10 seconds if you click the [Enable] button before the Propeller tool is finished loading the program. (Not an issue with Load RAM (F10), but Load EEPROM (F11) can take a few seconds.)

If those features were unchecked, you would have to manually click [Disable] before loading a program and wait until the program is finished loading before clicking [Enable] to reconnect.

When to uncheck the Automatically disable… setting:

The Automatically disable… setting is very convenient for iteratively modifying code with the Propeller Tool software and observing the results in the Parallax Serial Terminal.

The event that triggers the automatic Disable is the fact that you clicked another window.

Let’s say you are instead switching back and forth between the Parallax Serial Terminal and some other software such as a Spreadsheet for sensor measurement analysis.

With the Automatically disable… setting, each time you click the other window, the Parallax Serial Terminal automatically disconnects from the serial port, and any messages sent by the Propeller chip will not be buffered or displayed.

To make the Parallax Serial Terminal maintain the serial port connection while you are working with other windows, uncheck the Automatically disable… setting. Then, the Parallax Serial Terminal will remain connected to the serial port and continue displaying updated messages, regardless of which window you are working in.

Keep in mind that with this setting unchecked, you will have to manually click the [Disable] button before loading a program and then click the [Enable] button after the program is done loading.

The [Edit Ports] button in Preferences Function Tab (Figure 16-3) opens the Serial Port Search List.

 

Preferences Function Tab
Figure 16-3 Preferences Function Tab

You can drag entries in the list up and down to change the order they appear in the Parallax Serial Terminal’s Com Port drop-down menu. You can also right-click an entry to include or exclude it, or even create rules for which ports get included or excluded based on text in the Port Description column.

Parallax Serial Terminal Test Messages

Object HelloPST.spin sends to the Parallax Serial Terminal test text message: "This is a test message!"

HelloPST.spin declares the Parallax Serial Terminal object in the OJB block, giving it the nickname pst.

The HelloPST.spin makes the Propeller send messages to the Parallax Serial Terminal software by making calls to the Parallax Serial Terminal object’s methods.

HelloPST.spin TestMessages method first calls the Parallax Serial Terminal object’s start method with pst.Start.

Next come the pst.Str and pst.NewLine method calls in a repeat loop, so HelloPST.spin repeatedly sends the same text string, followed by a carriage return, to the Parallax Serial Terminal window.

Let’s first give it a try, and then take a closer look at the Parallax Serial Terminal object and its features and methods.

''HelloPST.spin
''Test message to Parallax Serial Terminal.
CON
  _clkmode = xtal1 + pll16x
  _xinfreq = 5_000_000
  
OBJ
  pst : "Parallax Serial Terminal"
  
PUB TestMessages
''Send test messages to Parallax Serial Terminal.
  pst.Start(115_200)
  repeat
    pst.Str(string("This is a test message!"))
    Pst.NewLine
    waitcnt(clkfreq*3 + cnt)

The Parallax Serial Terminal window will display following message that will print another repeated line every 3 seconds, indefinitely. 


This is a test message!
This is a test message!
This is a test message!

IMPORTANT NOTE FOR WHEN YOUR PROPELLER CHIP IS NOT CONNECTED TO THE PC!

If your Propeller chip is running an application, but is not connected to the PC, the Spin code that tries to send messages to the PC can cause the Propeller chip to be reset by the USB to serial converter.

The USB to serial converter normally gets its power from the USB port.

If the USB-to-serial converter is disconnected from the USB port, its FTDI USB-to-serial converter chip should be shut down.

However, if the Propeller tries to send messages to the PC, the signal voltages can supply enough power for the FTDI chip to wake up briefly.

When it wakes up, one of the first things it does is toggle its DTR pin, which is connected to the Propeller chip’s /RES (reset) line, resulting in a Propeller chip reset and program restart.

The solution for the 40-pin DIP version of the PE Kit is simple. Just unplug the Propeller Plug from the 4-pin header to remove the USB-to-serial converter from the system.

This prevents any messages intended for a PC to inadvertently cause the FTDI chip to reset the Propeller chip.

Since other Parallax Propeller Boards with the USB module have its FTDI USB-to-serial converter built-in, they need a different remedy.

Before running an application that's not connected to the PC with the USB cable, make sure to comment out or remove all code that attempts to send messages to the PC.

This will prevent the application from mysteriously resetting when the Parallax Propeller Board is not connected to a PC.

Displaying Values

The Parallax Serial Terminal object has a method named Dec, which is for displaying decimal values.

The Dec method takes a value and converts it to the characters that represent the value and then serially transmits them to the Parallax Serial Terminal.

It’s especially useful for displaying sensor measurements and other values stored by variables at various points in a program.

HelloPSTwithcounter.spin illustrates the use of Dec to transmit such variable. 


''HelloPSTwithcounter.spin
''Test message to Parallax Serial Terminal.

CON
  _clkmode = xtal1 + pll16x
  _xinfreq = 5_000_000
  
OBJ
  pst : "Parallax Serial Terminal"
  
PUB TestMessages | counter
''Send test messages to Parallax Serial Terminal.

  pst.Start(115_200)

  waitcnt(clkfreq*4 + cnt) 
  pst.Str(string("Hello World !!!"  ))
  Pst.NewLine
  waitcnt(clkfreq*2 + cnt)
   
  repeat
    pst.Str(string("This is a test message!  - "  ))
    pst.Str(String("seconds counter = "))
    pst.Dec(counter++)
    Pst.NewLine
    waitcnt(clkfreq + cnt)

The Parallax Serial Terminal window will display following message that will print another repeated line with increased number every second, indefinitely.

Hello World !!!
This is a test message!  - seconds counter = 0
This is a test message!  - seconds counter = 1
This is a test message!  - seconds counter = 2
This is a test message!  - seconds counter = 3
This is a test message!  - seconds counter = 4
This is a test message!  - seconds counter = 5

More PST

The next application shows some other PST display functions, such as displaying number as Hex (Hexa Decimal) or Bin (Binary). Also we have the Propeller do some simple calculation and then display the result.

{{ DisplayPST.spin }} 
CON          
  _clkmode = xtal1 + pll16x
  _xinfreq = 5_000_000

OBJ
  pst : "Parallax Serial Terminal"    'Call Object and declare alias

PUB Main | Temp
  pst.Start(115_200)                           'Start Parallax Serial Terminal    

  waitcnt(clkfreq*4 + cnt)
  pst.Clear 
  pst.Str(string("Hello World !!!"  ))
  Pst.NewLine
  waitcnt(clkfreq*2 + cnt)
  
  Pst.NewLine                                                                            
  Temp := 900 * 45 + 401                      'Evaluate expression  
  pst.Str(string("  900 * 45 + 401     = "))         'then display it and  
  pst.Dec(Temp)           'its result in decimal
  Pst.NewLine                                                                     
  pst.Str(string("In hexadecimal it's  = "))   'and in hexadecimal
  pst.Hex(Temp, 8)                                           
  Pst.NewLine
  pst.Str(string("In binary it's (%)   = "))   'and in binary   
  pst.Bin(Temp, 32)                                                                    
  Pst.NewLine                                                                    

  waitcnt(clkfreq*1 + cnt) 
  Temp := 0                                                                            
  Pst.NewLine
  pst.Str(string("Counting by fives:"))        'Now count by fives   
  Pst.NewLine 
   repeat Temp from 0 to 30 step 5
    	waitcnt(clkfreq*1 + cnt)
    	pst.Dec(Temp)           'its result in decimal
    	if Temp < 30
        pst.Str(string(" , "))

  Pst.NewLine                                                                     
  Pst.NewLine
  waitcnt(clkfreq*2 + cnt)
  
  pst.Str(string("The END !!!"))

  pst.Stop

Try to modify the above Application with different calculations and see how the results are displayed.

Entering and Displaying Values

EnterAndDisplayValues.spin utilizes the Parallax Serial Terminal.spin Object’s Methods to make the Propeller chip send prompts that are displayed in Parallax Serial Terminal’s Receive window pane.

After you type a decimal value into the Transmit window pane and press the [ENTER] key, the Propeller chip converts the string of characters to its corresponding value, stores it in a variable, and then uses the Parallax Serial Terminal.spin, object to send back decimal, hexadecimal, and binary representations of the value. 

CON
  _clkmode = xtal1 + pll16x
  _xinfreq = 5_000_000

OBJ
  pst : "Parallax Serial Terminal"

PUB TwoWayCom | value    ''Test Parallax Serial Terminal number entry and display.
  pst.Start(115_200)
  waitcnt(clkfreq*4 + cnt)
  pst.Clear
  pst.Str(String("INSTRUCTIONS: "))
  pst.Str(String(pst#NL,"1.) Enter a decimal value"))
  pst.Str(String(pst#NL,"2.) Press [ENTER] Key"))
  pst.Str(String(pst#NL,"3.) Program will display the entered value,",pst#NL,pst#NL,pst#NL)) 
   			'in decimal, binary, and hexadecimal formats.
  waitcnt(clkfreq*4 + cnt)
  repeat
    pst.Str(String("Enter a decimal value: "))
    value := pst.DecIn
    pst.Str(String(pst#NL, "You Entered", pst#NL, "--------------"))
    pst.Str(String(pst#NL, "Decimal:     "))
    pst.Dec(value)
    pst.Str(String(pst#NL, "Hexadecimal: "))
    pst.Hex(value, 8)
    pst.Str(String(pst#NL, "Binary:      "))
    pst.Bin(value, 32)
    repeat 2
      pst.NewLine

The Propeller represents negative numbers with 32-bit twos complement.

The Propeller chip’s long variables store 32 bit signed integer values, ranging from -2,147,483,648 to 2,147,483,647.

􀀳 Enter these values: 4, 3, 2, 1, 0, -1, -2, -3, -4, -5, and discern the pattern of twos complement.

􀀳 Try entering 2,147,483,645, 2,147,483,646, and 2,147,483,647 and examine the equivalent hexadecimal and binary values.

􀀳 Also try it with -2,147,483,646, -2,147,483,647, and -2,147,483,648.

pst.Dec vs. pst.DecIn

The Parallax Serial Terminal Object’s DecIn Method buffers characters it receives from the Parallax Serial Terminal until the [ENTER] key is pressed.

Then, it converts the characters into the value they represent and returns that value.

The expression value := pst.DecIn copies the result returned by the DecIn Method call to the value variable.

In contrast, the pst.Dec(value) Method call sends the decimal character representation of the number stored by the value variable to the Parallax Serial Terminal.

The pst.Hex(value, 8) Method call displays value in 8-character hexadecimal format, and the pst.Bin(value, 32) call displays it in 32-character binary format.

Object-Constant Reference “#”

An Object that declares another Object can access its constants using the Object-Constant reference symbol #.

You may have noticed several instances of pst#NL in the EnterAndDisplayValues.spin Object’s String directives.

Inside the Parallax Serial Terminal.spin object, NL is the constant 13.

So, this Method call:

pst.Str(String(pst#NL, "You Entered", pst#NL, "--------------"))

…is equivalent to:

pst.Str(String(13, "You Entered", 13, "--------------"))

In the Parallax Serial Terminal, 13 is the New Line control character.

When the Parallax Serial Terminal receives 13 from the Propeller, it has the same effect as when you press the [ENTER] key while typing in a word processor—the cursor moves down to the leftmost position on the next line.

So, as the Propeller transmits the characters in the string, each time it transmits a 13 to the Parallax Serial Terminal, it advances the cursor to the next line.

It’s a convenient way to embed the functionality of a call to pst.NewLine in a string. 


''     Parallax Serial Terminal
''    Control Character Constants
''──────────────────---------------------------------------───────────
  CS = 16  ''CS: Clear Screen 			pst.Clear     
  CE = 11  ''CE: Clear to End of line    	pst.ClearEnd 
  CB = 12  ''CB: Clear lines Below 		pst.ClearBelow

  HM =  1  ''HM: HoMe cursor       		pst.Home
  PC =  2  ''PC: Position Cursor in x,y          
  PX = 14  ''PX: Position cursor in X         
  PY = 15  ''PY: Position cursor in Y         

  NL = 13  ''NL: New Line               	  pst.NewLine       
  LF = 10  ''LF: Line Feed       		pst.LineFeed
  ML =  3  ''ML: Move cursor Left          
  MR =  4  ''MR: Move cursor Right         
  MU =  5  ''MU: Move cursor Up          
  MD =  6  ''MD: Move cursor Down
  TB =  9  ''TB: TaB          			pst.Tab
  BS =  8  ''BS: BackSpace          		pst.Backspace
           
  BP =  7  ''BP: BeeP speaker       		pst.Beep

Under Construction
Currently this page is still under development, so please check back periodically for new links to pages as we add them to this list.

Links to related Webpages

Click the link in the list below to navigate to a detailed webpage about the listed subject.

Parallax Propeller Book - Table of Content