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.
The Parallax Serial Terminal will open in new 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.
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.
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.
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.
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
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.
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.
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.
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
Currently this page is still under development, so please check back periodically for new links to pages as we add them to this list.
Click the link in the list below to navigate to a detailed webpage about the listed subject.
Parallax Propeller Book - Table of Content