
Propalyzer (Propeller Serial Logic Analyzer) Help
-------------------------------------------------

Important Setup Notes:

Propalyzer requires .net version 2.0+ to be preinstalled on your PC.
Propalyzer will not look for .net or try install it on your system.

After launching Propalyzer:

On first use, a COM port settings dialog will appear. You need to set the
COM port to your target device port number and the baudrate to 115200.
Other settings allow more generic controls, but should normally be set
to No parity checking, 1 stop bit, 8 data bits, and no flow control.

Before using the build/download feature, Options -> Spin File and
Options -> Propellent File must be set. Spin files can be found in the zip
archive under the Spin directory. The Propellent code can be downloaded from:
http://www.parallax.com/Portals/0/Downloads/sw/propeller/Propellent-v1.1.zip

Please find Propalyzer.spin and other modules in the spin directory. Copy
all spin code to your spin directory. Propalyzer will not work without a
connection to a Propeller running the Propalyzer.spin code.

Propalyzer 1.0.1.4 is Freeware. If you want to contribute to further
development of the application or are interested in commercial liscensing,
send your request and compensation proposal to jazzdenson at yahoo dot com


-------------------------------------------------

Purpose:

To provide a serial interface logic analyzer GUI for a Propeller running
capture code.

Propalyzer is a Logic Analyzer, not an Oscilloscope. This means it will not
dynamically display data available on the Propeller pins. Use other programs
for Oscilloscope function.

Propalyzer is designed with HP analyzers in mind. Specifically, the
timing diagram is displayed in the main window. Users have control
over triggers with a bit mask and an arm state. Users can define groups
for making data more meaningful.

Features:

  - Serial communications with Propeller
  - Compile and Download Propeller with Propellent program
  - Flexible serial port settings
  - Base clock period (12.5ns default) to 2 second sample rate
  - Configurable Propeller clock frequency for display.
  - Easy to use Mask, Arm, Trigger, Display settings
  - Two waveform display variants
  - A state list window with filtering
  - Pin Group definitions
  - Display context controls
  - Key stroke display controls
  
User Controls:

In addition to the menu bar (discussed below), the user has two control
toolbars, a display context popup, and a groups toolbar.

The top toolbar contains:

  - Capture on trigger button (green target)
  - Capture continuously on trigger button (arrow on green circle)
  - Snapshot capture button (blue camera)
  - Capture Sample Period combo box
  - Reset pan to trigger button |<
  - Pan left button <
  - Pan right button >
  - Mask field
  - Arm field
  - Trigger field
  - Show field
  - Serial port properties button
  - Console transaction display connector*
  - Build/Download button

*Normally the console transaction display which is used mainly for debugging
input/output between Propalyzer and the Propeller should not be visible.
Keeping the console enabled can cause un-wanted results.

Sample Period:

The sample period combo on the tool bar contains many time scales. The time
to be used for capture is dependent mainly on the Propeller code. The 12 ns
setting is really 12.5 ns for 80MHz operation.

The Sample period adjusts to the clock frequency set in Menu -> Options ->
Clock Frequency. For example, a 100MHz clock has a period of 10ns and the
smallest sample period available will be 10ns. A 20MHz clock has a period
of 50ns so the sample period will adjust accordingly.

If you adjust the clock frequency in Propalyzer, it will not adjust the spin
code clock. That is for you, the user, to do.

  
The second toolbar contains:

  - Bit change combo box (Trigger, Mask, Arm, Show)
  - Screen refresh button
  - Flip bits button ^
  - Bit buttons
  
The trace display shows bits, time, timelines, and waveforms.

Keystroke Display Controls:

Click on the display to enable keyboard interaction. The following keys and
combinations will control the display.

  - Home: 			move cursor to time tick 0.
  - End: 			move cursor to last time tick.
  - Control Home: 	pan display to time tick 0.
  - Control End: 		pan display to last time tick.
  - Left Arrow: 		move cursor left.
  - Control-Left Arrow: pan display time left.
  - Right Arrow: 		move cursor right.
  - Control-Right Arrow:pan display time right.
  - Up Arrow: 		zoom in one level.
  - Control Up Arrow: 	zoom in 10 levels.
  - Down Arrow: 		zoom out one level.
  - Control Down Arrow: zoom out 10 levels.

Move the mouse out of the waveform display so system refresh will not
interfere with your work.

Additionally, some controls are available in the display context.

Display popup Controls contains:

  - Zoom controls
  - Left Click drag and release zoom
  - Double-click zoom
  - New group control
  - Add bit to group control
  - Delete bit from groups
  - Right-click and drag add bits to group
  - Delete group control
  - Delete all groups control
  - Set Arm
  - Set Trigger
  - Set Arm and Trigger
  - Show Listing
  
The Groups toolbar provides space for up to 6 user defined groups. Groups
are color-coded consistent with pin trace colors for easy identification.

The File menu provides file new, open, save, save as, import, export, and
exit options. The file being manipulated is a combination of analyzer
settings and data. Analyzer data can be saved or loaded separately from
analyzer settings using export and import.


-------------------------------------------------

Standard operating procedure:

Getting started requires a connection to a Propeller chip via a serial
port or USB connection. If the Propeller does not have an EEPROM for
saving host code, the code can be compiled and downloaded with the
download button.

When a Propeller is connected and running the host code, a good test is
to click the Camera toolbar button. When clicked, the Camera button will
be depressed until the data is received. Once data is received, the
Camera button will become unpressed and data will show up on the display.

It takes a few seconds for any snapshot to come over the serial link. If
you feel the connection is not working, you can click the Camera button
again, and the attempted operation will stop.

The Capture button and Capture Continuous buttons behave like the Camera
button. The difference is Capture will use the mask, arm, and trigger
fields as capture parameters.

The "Mask" field sets the bits to monitor for arm and trigger. The "Show"
field sets the bits to be displayed on the pin trace panel. If the mask
is 0, arm and trigger are ignored, otherwise they work as described next.

The "Arm" field sets the condition that must be met before a trigger can
happen. If the arm is the same as the trigger, the arm is ignored.

The "Trigger" field sets the condition that must be met before sampling
will start.

The default sample rate is set to the Menu -> Options -> Clock Frequency period.
Users should select the desired sample rate before capturing data. The sample
rate should only impact the pin trace display upon capture.


Setting mask, arm, trigger, and show fields:

A few ways are provided for setting the fields. User can set the fields
by hexadecimal numbers in the toolbar one field at a time, or by using
the bits toolbar.

Using the bits toolbar requires selecting the field for setting the bits
with the field name combo box. Bits are arranged 0 to 31 left to right
for less sophisticated users. Experienced users may also be attracted to
this feature.

Once data is captured to the waveform display, the user can right-click
on the display and choose set arm, trigger, or both to the tick value clicked.


**** Notes on ARM/TRIGGER usage ****

The snapshot button should always capture something. If it does not, you have a serial port or hardware problem.

If you set Arm/Trigger data the same and enable the Mask for the Arm/Trigger
bits, when the data is detected all data after the trigger will be captured
up to the limit of the Propeller memory being used, and the display will show
the captured states.

If you set Arm to one state and trigger to another, the Arm state must be
detected before the Trigger state for the display to show captured data.

Sometimes the Trigger may not show in the state display if the Trigger state
disappears before the Trigger is captured.

Sample periods bigger than an Arm/Trigger can cause capture to fail entirely.


Examining data:

The pin trace panel is central to data waveform analysis. Users may pan
and zoom data once captured. The arrows and magnifying glass buttons are
one way to control pan and zoom.

Other ways to control pan and zoom are with pin trace panel mouse strokes
and popup menu. Mouse left click drag and release should allow the user
to zoom to the selected area.

The zoom distance is controlled with the "Zoom Factor" trace display popup
menu item. The zoom factor in the popup menu is a text box where you can
enter a zoom value (the main menu View -> Zoom Factor control is a combo
box ... use either one).

Zoom can be reset to the initial value with the popup or main menu bar View
-> Zoom Reset menu item.


Groups are your friends:

Users can create and populate up to six bit groups using the display popup
menu. Before one can add bits to a group, a group must be created.

Create a new group with the "New Group" trace display popup item. Move the
mouse to above the "Ok" button, click the box, and enter the group name.
Then click ok, and the group will be shown as an upper case label and colored
text box on the groups toolbar.

Once you have a group, add bits to the group either one at a time with
the "Add to Group" popup item or as a group by right-click, drag and
release over the pin group. Once the "Add to Group" menu item is selected,
a combo box and ok buttun will appear. Click the combo box and select the
group name, then click ok to add bits to the group.

After adding bits to a group, the bit traces should be highlighted with
the group box background color. Users can delete a bit from all groups.

Two delete group items are on the pin trace panel popup menu. The delete
all groups item will remove all groups and pin trace highlighting.

The delete group item allows individual groups to be deleted. A combo box
and ok button will appear for selecting the group name to delete.
Click ok to delete the group.



Show Listing:

A listing window will be displayed if the user right clicks the waveform
display area and clicks "Show Listing". The listing window will have the
groups defined in the waveform window on startup (changes in waveform
window groups require restarting the list window for group changes to be
affected there).

The list window has filter controls. The text box should contain a filter
mask that when ANDed with the list value will filter out any list items
that have resultant bits set if filtering is enabled. Additionaly,
consecutive duplicates can be filtered.

The listing control allows tracking with the waveform cursor if enabled.
The listing control can be made to stay the top window if enabled.


-------------------------------------------------

Application Menu Bar:

File -> New - starts with a new project. All groups, data, and
highlighting should disappear when clicking this menu item (mask, arm,
trigger, and show may not change).

File -> Open - loads a previously save project selected with the open
dialog. All elements of the project including the data should be restored
when the project is opened.

File -> Save - saves a project.

File -> Save As - saves a project to file named or selected with the save
dialog.

File -> Export - exports bit data as a set of 32 bit hexidecimal words
one per line to a text file.

File -> Import - reads data from a text file. The data should be formatted
as described in file export.

File -> Exit - causes the application to terminate.


View -> Delete All Groups - deletes all user defined bit groups.

View -> Invert Colors - causes the display to flip to/from black or
white background.

View -> Zoom Factor - allows setting the zoom factor or distance for
the pin trace display.

View -> Zoom Reset - resets the zoom level.


Options -> Port Settings - allows setting serial port parameters for user
preferences.

Options -> Spin File - lets the user specify the Propeller host
application for build/download.

Options -> Propellent File - lets the user specify the Propellent path
and file for build/download.


Help -> About - gives software version, etc...,  briefly describes the
program purpose, and gives credit to software contributors.


-------------------------------------------------

Current Annoyances

Shrinking a window with an edge may not update the display. Use the status bar resize or reset zoom. This is not really an issue for me since I sometimes use the right-hand side of a window as a temporary vertical cursor.


Bugs

Version 1013:
Bug: Assigning a pin state to a group fails if some pin traces are not shown.
Cause: Code did not count pin visibility.
Fix: 1014+

Version 1013:
Bug: Opening state Tick list window more than once causes a crash.
Cause: Silly programmer error.
Fix: 1014+

Version 1012:
Bug: More of an annoyance ... Tick list window would reset on reload.
Cause: Code used simple new/show update; no allowance was made for reinit/redraw.
Fix: 1013+

Version 1012:
Bug: Set Arm/Trigger was wrong if display was panned.
Cause: Did not add pan value to tick calculation.
Fix: 1013+

Version 1012:
Bug: Display refreshed and caused cursor to reset to mouse position. The event also caused the window to refresh and the trigger or other boxes to lose focus.
Cause: Was using Paint instead of Click for component container focus.
Fix: 1013+

Version 1011:
Bug: Must restart app for console settings to be effected.
Cause: Not loading settings before use in capture/snapshot methods.
Fix: 1012+

Version 1010:
Bug: Could not start application without previous install.
Cause: Empty registry item.
Fix: 1011+

Version 1007: Beta Feedback - Thanks John!
Bug: Export causes crash if no file selected and user clicks Cancel.
Cause: Not checking for zero length file string.
Fix: 1008+

Version 1007:
Bug: The display screen flashes.
Cause: Control and image backgrounds set different.
Fix: 1008+

Version 1004-1006:
Bug: Menu bar text boxes Mask, Arm, Trigger, Show all cause edited position to change if A-F are entered.
Cause: Invoking tb.Text.toUpper() during edit. Characters will remain lower case until leaving box.
Fix: 1007+




Features

Version 1014+:
Feature: User can specify Clock Frequency to be used for sample period.

Version 1014+:
Feature: User can resize window from any edge.

Version 1014+:
Feature: Propalyzer now has an icon.

Version 1012+:
Version 1012+:
Feature: Made keyboard cursor tracking more meaningful.

Version 1012+:
Feature: Zoom and pan controls more accurate.

Version 1012+:
Feature: Added ability to set Arm, Trigger, and both Arm/Trigger from tick point.

Version 1012+:
Feature: Added value 'and' filter and consecutive duplicate value filter to pin state list window.

Version 1008+:
Added state list window launched from display popup.

Version 1007+:
Feature: Added key controls for display.



