PE Kit Tools - Debug LITE for the Parallax Serial Terminal

Andy Lindsay (Parallax)

This is the Debug LITE project for Parallax Serial Terminal; it's a completely different animal from ViewPort.· ViewPort offers an IDE style debugger as well as a myriad of ways to graphically display Spin variables and I/O pin states; whereas, this PE Kit Tool utilizes the text-only Parallax Serial Terminal.·

PE Kit Tools - Debug LITE for the Parallax Serial Terminal
·
The PST Debug LITE object is a simple and convenient tool for debugging Spin code with the Parallax Serial Terminal.· Figure 1 shows an example debug display, paused at a breakpoint during a debugging session.· The display features I/O pin directions and states next to a list of variables and their values.· There’s also a message at the bottom prompting to press any key to continue from the breakpoint.· (Make sure to click the Parallax Serial Terminal’s Transmit windowpane before pressing Enter.)
·
Full PDF & source code: PE Kit Tools – PST Debug LITE.zip
More info: PE Kit Labs, Tools, and Applications
Platform: Propeller Education Kit

·
·
“Test Debug.spin” is a program that changes a number of variable values along with a few I/O pin manipulations for the sake of viewing with PST Debug LITE.· The method calls that resulted in the Figure 1 display are highlighted in Figure 2 along with the typical setup (clock settings, PST Debug LITE object declaration, and call its Start method).··
·

Figure 2:·· Test Debug.spin Application Tests Variable Display and Breakpoints

······

The ListHome method sends the Parallax Serial Terminal’s cursor to the beginning of the list, then three Vars calls populate the list with three groups of contiguous variables.· After the Vars method calls, the Break method call stops program execution until the PST Debug LITE receives a character from the Parallax Serial Terminal’s transmit windowpane.

Incorporating PST Debug Lite into an Application

Follow these steps to incorporate PST Debug LITE into an application:

1)····· Declare the PST Debug LITE object.
·
OBJ
· debug : "PST Debug LITE"
·
2)····· Pass the Parallax Serial Terminal’s baud rate to its Start method along with the display style.·
·
debug.start(115_200, debug#DEFAULT)
·
Other display styles are listed in the PST Debug LITE object’s Display Style Constants section.· TIP: Open PST Debug LITE.spin with the Propeller Tool software, and click the Documentation radio button.· Then use CTRL + F to find the words - Display Style.

3)····· Make sure the clock settings support serial communication at the baud rate you chose.· If in doubt with the PE Kit, set the system clock to 80 MHz with the 5 MHz crystal.·
·
CON
· _clkmode = xtal1 + pll16x
· _xinfreq = 5_000_000····
·
4)····· Call the ListHome and Vars methods to control the display, and call the Break method to halt cog code execution at certain points.

Testing PST Debug LITE


P······ Download “PE Kit Tools – PST Debug LITE.zip”.
P······ Unzip to a folder.
P······ Open Test Debug.spin with the Propeller Tool.
P······ Run the Parallax Serial Terminal, and set the Baud Rate to 115200 to match the baud rate in the example program’s Start method call.· Then, set the Com Port to the Propeller chip’s programming port.· If you’re not sure what the COM port number is, use F7 in the Propeller Tool software to find out.
P······ The Echo On box should be unchecked for this application.
P······ Make sure the Parallax Serial Terminal is resized to be large enough to fit the display shown in Figure 1.
P······ In the Propeller Tool, press F11 to load the program into the Propeller chip’s EEPROM.
P······ As soon as the Propeller Communication window reports “Loading EEPROM…” click the Parallax Serial Terminal’s Enable button.· (Don’t wait for the download to complete before clicking Enable.)
P······ When you see the pinmap and variable displays, click the Parallax Serial Terminal’s transmit windowpane.
P······ Press/release the Enter key on your computer’s keyboard to advance from one breakpoint to the next.·
P······ Make sure to take a close look at the Start, ListHome, Vars, and Break method calls in the example program.

ListHome, Vars, and Break Methods

Calls to Vars append the variable list on the right hand side of Figure 1.· A call to the ListHome method places the cursor back at the beginning of the list:
·
· debug.ListHome
·
The list of variables in Figure 1 is three separate lists that were transmitted to the Parallax Serial Terminal as a result of the three different Vars method calls.· The list includes both global and local variables, arrays and a method return value for good measure.·
·
The Vars method can be used to display global long, word or byte variables as well as local variables.· When displaying local variables, the Vars call should be inside the method with the local variables to be displayed.· The Vars method call accepts two parameters: startAddr and stringAddr.· The startAddr parameter should be the address of the first variable in a declaration with the variables you want to display, and stringAddr is the address of a string that contains a copy of the variable declaration.· Here are three examples from Test Debug.spin:
·
· debug.Vars(@wa, String("word wa, wb[noparse][[/noparse]3], wcc"))
·
· debug.Vars(@dT, String("| dT, index, array[noparse][[/noparse]3], myVal"))
·
· debug.Vars(@a, String("PUB moreVars(a, b, c) : retVal | i"))
·
…and of course, you can set a breakpoint with a call to the Break method:
·
· debug.Break
·
To resume program execution from a break method, click the Parallax Serial Terminal’s Transmit windowpane, and then press the enter key on your keyboard once.

Vars Method Call Tips

Here is a quick, simple and reliable way to add a Vars method call a program:
·
P······ Start with debug.Vars(@ , String(""))
P······ Copy and paste the method block or variable declaration that contains the variables you want to display between the quotation marks in the second parameter’s String expression.·
P······ Copy the first variable from the declaration and paste it to the right of the @ operator in the first parameter.
·
Example:
··
Make sure that:
·
P······ The String begins with byte, word, long, PUB, PRI or |.· (Not case sensitive.)
P······ The start address in the first parameter matches the first variable in the variable declaration string.
·
Advanced Topic – Viewing Variables in a Building Block Object
In some cases, you may want to examine a list of global variables starting at a particular address inside one of the objects declared by your top file.· If the object does not already do so, modify it so that a method returns the starting address of the variable list you want to examine.· For example, let’s say that your top file has copied the starting address of a ten element long variable array to a variable named varAddr, you can then use this call to view the object’s variable list:
·
· debug.Vars(varAddr, String("long objname.arrayName[noparse][[/noparse]10]"))
·
Note that in this case, the varAddr variable is not preceded by the @ sign because we don’t want the address of varAddr, we want the address value it stores.· That value is the address of the first array element.· Also, keep in mind that future PST Debug LITE should make it possible to declare instances of PST Debug Lite in several objects in the same application, which will in turn make it possible to insert calls anywhere in the Spin language application.·

Next Steps for the PST Debug LITE Project

This first step in the PST Debug LITE project involves testing with some simple programs in a single cog to improve the interface and get the bugs out.· (Along the way, code space needs to be reduced so that it really qualifies as LITE, string parsing needs to be condensed, user interface methods improved and so on&#8230[noparse];)[/noparse]
·
Step two will incorporate semaphores to allow multiple cogs to pass information without scrambling the display.· The version of FullDuplexSerialPlus this object relies on for communication with the Parallax Serial Terminal incorporates features in SerialMirror from the obex.parallax.com.· This will be crucial for step 3, expanding PST Debug LITE to allow all objects in a given application to pass information to the same serial buffer.· (This changed, see UPDATES 2009.01.25.)
·
Please feel free to report bugs, ask questions or pitch in with suggestions in this thread.· You can also contact me directly using the email button to the left of this post.



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

Education Department
Parallax, Inc.

Post Edited (Andy Lindsay (Parallax)) : 8/24/2010 6:06:14 PM GMT

Andy Lindsay (Parallax)

Reserved...

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

Education Department
Parallax, Inc.

Andy Lindsay (Parallax)

Reserved...

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

Education Department
Parallax, Inc.

Andy Lindsay (Parallax)

Reserved...

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

Education Department
Parallax, Inc.

Andy Lindsay (Parallax)

Thanks to the folks who submitted suggestions and bug reports for PST Debug LITE.· You can get the·current version of the·object and documentation by scrolling to the·beginning of this thread.· Here is a list of the most recent object and documentation updates:

--- Updates 2009.05.07 ---

Modifications:

·- Vars method replaces Longs, Words and Bytes for appending the Variable = Value list.
··· The Vars method uses the string copy of the variable declaration to figure out if the variables
··· are longs, words, or bytes.

Bugs fixed:

·- The first element of the second array in a given variable declaration was displayed as
··· array[noparse][[/noparse]0000] instead of array[noparse][[/noparse]0]

·- A space following the string copy of the variable declaration in the Vars method call resulted
··· in an in an extra (nonexistent) variable being added to the list.

Documentation:

·- PDF and Forum post updated
·- PDF and Forum post revised
·- Example code updated

To-Do List:

·- Restrict Break message to width of pin map
·- Add reference·parameter to Break methods
·- Move string buffers to DAT section and test in multiple objects
·- Add locks that route and queue variable values from different cogs
·- Simplify and reduce string parsing code

--- Updates 2009.05.07 ---

·- The FullDuplexSerialPlus object has been replaced with Parallax Serial Terminal.· Although the current version puts both functionalities in the same object, the goal is to have PST Debug LITE declare a modified version of Parallax Serial Terminal that goes back to the Serial Mirror approach of using DAT for memory so that all instances of the object will share the same buffer space.

·- If the first variable in the declaration happened to be an array, the first element was displayed correctly, but subsequent elements were missing the first character.· This has been fixed, well maybe it was more of a patch, but it does display correctly now.

·- Different display styles are useful for different tasks.· The default display was featured here.· Some other useful formats include comma delimited lists, variable = value lists, and pinmap only mode.

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

Education Department
Parallax, Inc.

Post Edited (Andy Lindsay (Parallax)) : 1/26/2010 5:12:20 AM GMT

slcott

i'm using brad spin tool on linux with the object and am getting mostly garbage in my terminal.

BradC

slcott said...
i'm using brad spin tool on linux with the object and am getting mostly garbage in my terminal.

Probably. PST uses its own control-codes to do cursor movement and formatting. All I can say is a PST compatibility option for the bst terminal is in the works, but it might be later rather than sooner I'm afraid.

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
"Are you suggesting coconuts migrate?"

Videomachine

Re: Propeller Education Kit Labs, Tools, and Applications
Installation of PE Kit Tools - Debug Lite for the Parallel Serial Terminal is no problem.
But the displays shows different results. (Figure 1. Parallax Serial Terminal Debugging Session)

Even though I click on the serial terminal transmit windowpane the text Parallel Serial Terminal Debug-LITE and the structure of the IC P8X32 is not shown.

1-> <-1 dT 8000000
1-> <-0 index = 24
1-> <-1 array[0] = 100
1-> <-0 array[1] = 84
0<- <-0 array[2] = 92
0<- <-0 myVal = 126
0<- <-0 a = 10
1<- <-0 b = 20
c = 30
retVal = 128
i = 3
wa = 30
1<- <-0 wb[0] = 24
etc.


What goes wrong?

wjsteele

Just looking at the code, it should be printing it out... perhaps your code is too large or there is another piece of code that is overwritting the memory where the "io_map" is defined in the DAT block.

Strings on the propeller are null (character 0) terminated... if one gets written into that memory area, it will cause exactly what you are seeing.

{EDIT: One way to test this is to try and reorganize your application... if you do, it should fail in different places.}

Bill

Powersoft

Hello,

I try the test example thats found in the directory downloaded in this tread.
Have the same problem, not showing up the IC.
What is going wrong?

Thanks for any help.

Jan Kromhout
Hellevoetsluis-NL