Why this manual?
 Top Next
This manual was written by a satisfied user of ViewPort shortly after he shed the title of ViewPort "newbie".

ViewPort is not hard to use. But as a "newbie", I found several frustrating ways to confuse myself. That no longer happens to me because I developed a set of "best practices" that have kept me out of trouble. This tiny manual shares those "practices" in hopes that your experiences as you progress from running the "canned" demos to using ViewPort in your own projects will be positive ones.

Note that this is less a "how to" and more of a "how not to" document. For the more detailed "how to" stuff, I refer you to the main ViewPort documentation.


Minimalist Theory of Operation
 Previous Top Next
ViewPort is used to debug the top level Spin object running in Hub memory. The debugger allows you to pause and set breakpoints in the top object.

It operates by loading a "spy program" (called Conduit) into a cog and starting it up. This cog never quits running and continuously streams "longs", one after the other, from a block of variables (specified by you in a "Share" statement) in Hub memory to the ViewPort GUI where a variety of widgets are available to aid in the visualization of the variables. This streaming of variables is done as fast as possible. With an 80Mhz Propeller clock speed and a 2Mbps USB connection, this means about 50,000 values per second will be sent to the GUI.

If you want to have pin states displayed by the ViewPort GUI (see Making Pin States Visible ), there is another "spy program" called QuickSample that loads a block of longs in cog memory with sequential INA readings and interleaves a "spy, then stream" sequence of this block with the stream of variables described above.

Conduit also provides the path by which you can control the operation of your program. It enables single-stepping and the modification of shared variables at run time. It also reads configuration strings stored in your program so that on startup, ViewPort is "customized" to showing your variables in your preferred style.


Limits and Limitations
ViewPort is used to debug the top level Spin object running in Hub memory. The debugger allows you to pause and set breakpoints only in the top object. You cannot pause or set breakpoints on code running in other objects or cogs. However, the debugger will allow you to see the results of code running in other cogs if those results appear in Hub memory. In that sense, it is possible to debug multiple cogs running in the top level object. And those cogs can be running Spin or PASM.

For looking at variables, ViewPort only "spys" on blocks of longs. Do not mix words and/or bytes in the "block" that you specify in the "Share" statement.

You can "spy on" (share) a maximum of 25 longs.

Assuming an 80Mhz Propeller clock speed:

You can read port pins (INA) at up 20Msps (using a single dedicated cog) or up to 80Msps (with 4 dedicated cogs). When using a single dedicated cog, 360 samples are taken in a burst, then sent to the GUI. When using 4 dedicated cogs, 4*360 samples are taken in a burst, then sent to the GUI.

It is not possible to single step into a child object.

You cannot single step into code (Spin or PASM) that is running in a cog.


Clock Settings
Because ViewPort operates a high speed (2Mbps with USB serial) bi-directional serial communication link to the GUI, it is necessary to run the Propeller chip at 80Mhz (or higher). Select _clkmode and _xinfreq suitable for your hardware to achieve the needed clock speed. Below is a commonly used clock setup...

CON

  'Clock setup (80Mhz) for a PropStick

  _clkmode        = xtal1 + pll16x
  _xinfreq        = 5_000_000

ViewPort will use these clock setup parameters to automatically adapt to other Propeller clock speeds, but 80Mhz is the most commonly used operating frequency.

Because communication speeds of up to 2Mbps are used, the quality of the USB cable connection is critical (see Mouse is sluggish or won't move ).


Positioning of ViewPort Statements
The order of ViewPort control statements is important. Use the following template...

OBJ
  vp  : "Conduit"
  qs  : "QuickSample"

VAR
  long myFirstVar, {more vars} ,myLastVar
  long frame[400] ' if QuickSample in use

PUB Main

  vp.register(qs.sampleINA(@frame,1)

  vp.config(string(" .. {see Configuration }
        .
        .
  vp.config(string(" .. {see Configuration }

  vp.share( @myFirstVar, @myLastVar )


Starting a Program

How to Start a Program
First, make sure that the program will compile with Propeller Tool (take care to "save" the code). This is a "best practices" tip for early users that can be relaxed later as you gain experience. For now it is best to depend on PropTool to find syntax problems and let ViewPort concentrate on debugging.

Next, open ViewPort: it will open to the "welcome" panel.

Highlight the file to be debugged.

Then click the "code" tab. This procedure lets you see your code while giving you complete control over when the connection to the Propeller chip will be established and when the program will be loaded into the chip and execution started. If you click the Run button or the Debug button, your program will be loaded and start running, giving you less opportunity to take control.

Don't be concerned if the mouse pointer changes from an arrow to an I-beam as it moves over the tabs on the folders. This happens in Version 4.2.3, but may disappear in future releases.


Restarting a Program

How to Restart a Program
To restart a program from the beginning...

then...


Recovering from an Exception

ViewPort throws an Exception
Complex programs have difficulty recovering from an exception and reaching a consistent state from which continued operation is feasible. Attempting to use a program that has thrown an exception is risky. ViewPort is no exception (pun intended).

So, if you have managed to induce an exception in ViewPort, make note of what caused the problem, then close ViewPort, reopen it, fix whatever caused the exception, and continue.


Making Pin States Visible
If you want to have a visual display of pin states, use QuickSample. The advantage of using this method is that you do not have to change your code in any way to see what is happening at the pins.

The following template can be used...

OBJ
  vp  : "Conduit"
  qs  : "QuickSample"

VAR
  long myFirstVar, {more vars} ,myLastVar
  long frame[400] ' if QuickSample in use

PUB Main

  vp.register(qs.sampleINA(@frame,1)

  vp.config(string(" .. {see Configuration }
        .
        .
  vp.config(string(" .. {see Configuration }

  vp.share( @myFirstVar, @myLastVar )

With the above statements in your program, you will see...

If you don't see such a display, look at Can't see Pin States and/or Pin States Don't Change Right


Embedding Configuration in your program

Embedding Configuration strings in your program
Do not try to create and imbed configuration strings in your program by yourself. ViewPort provides a wizard that will help immensely in getting properly formatted configuration strings for use in your program. Use Copy to Clipboard and paste the results into your program ...

Failing to follow the above advice is one of the major ways to induce ViewPort to throw exceptions (see Recovering from an Exception ).

Once you have pasted the configuration strings into your program, you will find it convenient to do small edits in those strings such as changing the name of a shared variable. Those edits are obvious and it is much quicker to edit in place than to go through the wizard.


Single Step Tips
Remember: you cannot single-step into a child object. If you try, it will be treated as a "step over".

Be cautious when single-stepping a program that contains waitcnt( count ) or any of its variants. When you are single stepping, the CNT register (global Sysytem Counter) keeps incrementing. This makes it possible to set an expected count value as you step through the program, and then when you step to the waitcnt( count ) statement that tests for that value (it's a test for equality!), that value has already occurred. Now you have to wait for a 32 bit counter to cycle back around. Even at 80Mhz, this takes almost a minute. During that time, your program appears "hung".

See Pin States Don't Change Right if you're having trouble seeing certain pin states while single stepping.


Pause Clause
It is supposed to be possible to insert a breakpoint before a program has started running and then to have that breakpoint honored when it is subsequently encountered. Version 4.2.3 does not appear to work that way. Instead, it is necessary to start the program before a breakpoint can be inserted that will be honored. The following work-around, which I call a "pause clause", is easy to use.

Insert the following lines in your code before the point where you need a breakpoint...

     StopSign := 1
     repeat while StopSign == 1

Now start your program running and insert the breakpoint where you need it to stop. The program is looping forever at the pause clause, but you can release it by setting StopSign to zero (any value other than 1) using the GUI.

For example, use the Watch panel in the Code tab...

Just type a different value for StopSign, and your program will be "released" to run to the breakpoint.


Learning Config string syntax
To learn about configuration string syntax, click on Configuration|View. That will bring up the following panel...

The "Original Configuration" was gathered from your program when it first started running (Conduit provides the magic for this little trick). Any configuration changes made since program startup will be shown in "Current Configuration". Experiment and learn.


PropTool can't find Conduit
The file conduit.spin (and quickSample.spin) must be either in the same directory as the top object file that you are compiling, or in the Propeller Tool library (usually c:\Program Files\Parallax Inc\Propeller Tool v?.?.?).


Pin States not being displayed

Can't see Pin States
Version 4.2.3 has a little "quirk": immediately following startup, the GUI will not update the pin state display until you have "visited" the LSA tab once (cures the problem). Then it displays as expected.


Pin States Don't Change Right
Symptom:

While single stepping, I step through a statement that should change the state of an output pin, but it does not change on the visual display. But I can put a meter on that pin and verify that it is in fact changing level as expected.

Cure:
Check for a trigger condition that is being waited for by the QuickSample cog program. You'll see this in the status bar ...

... if that's what is happening. Go to the LSA widget (pattern tab) and remove any trigger conditions that are present. For single stepping and being able to see all pin state changes, we need to get the trigger setting to be "don't care" for all. You need to be able to see...

trigger=io[xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx]

in the config string for LSA (see Learning Config string syntax ). Or there could be a complete absence of a trigger parameter. That works too.


Early breakpoint being skipped

Can't get a Breakpoint at the beginning of a program to work
See Pause Clause


I'm having trouble with Config statements
If you're having trouble with composing configuration strings, see Imbedding Configuration in your program .

If you need to better understand what is possible in configuration strings, see Learning Config string syntax .

For setting trigger conditions to be used by QuickSample, use the Pattern tab on the LSA panel...


LSA won't show my variable
The Logic State Analyzer only does one 32 bit "channel" at a time. It always displays the first one in the list. So make sure that only one "channel" (variable) is marked to "Plot".

If you had the following in your LSA, you would only see io displayed (here I have used the wizard to single out and name just 2 bits out of the 32 available in io). If you wanted to see "Press", you have to uncheck the plot button to the right of io in the overview panel...


Communication link not working
If you are having trouble with the communication link, first make sure that you are running the Propeller chip at 80Mhz (see Clock Settings ).

Next try different baud rates.

Also, see Mouse is sluggish or won't move


It used to work, now it doesn't

Drop and reload ViewPort (see Recovering from an Exception )

If the above action does not solve the problem, you may have accidentally changed your clock settings (see Clock Settings ).

This would be rare, but maybe you were looking at the code for Conduit or QuickSample and accidentally modified it. Try reloading these files from the distribution.

If all else fails, uninstall and reinstall ViewPort. This appears to be a completely safe procedure. No files will be lost.


Mouse is sluggish or won't move
 Previous Top
ViewPort runs the FTDI driver that handles the USB serial port at up to 2Mbps. If this link is "shaky", the FTDI driver will do "retries" to handle errors. While the driver is doing retries, Windows stops getting messages from mouse movement and button clicks. This will cause your mouse to move sluggishly or maybe not at all. And mouse button clicks will be lost. Unfortunately, the FTDI driver does not provide a quality of service indicator, so ViewPort cannot warn you directly about comm errors.

You can regain control in the above situation by simply disconnecting the USB cable from the Propeller chip.

The "shaky" link can be caused by a low quality, or excessively long USB cable. I was using a 10 foot extension in my USB connection and ran into serious communication problems. The 3 foot length of the retractable USB cable that Parallax is short enough and has worked well for me, but it is not what one would consider a high quality cable (it's unshielded for one thing).