Basic Stamp Emulator Lite V0.7 Beta
(c) 1998-2001 by Al Williams Consulting
http://www.al-williams.com/awce.htm
Makers of the PAK series coprocessors
NOTE: THIS IS NOT PUBLIC DOMAIN SOFTWARE. PLEASE READ "DISTRIBUTION"
BELOW TO FIND OUT MORE.

What is it?
===========
BS1 is an emulator for the Basic Stamp I. It is being released as
complimentary software to the Basic Stamp community. As such, there
is limited support and you may or may not find the emulator useful
to you. This is a Beta release, and as such, you can expect to find
things that do not work.

How do I use it?
================
Write your program using the STAMP.EXE editor (from Parallax). Then
add a line anywhere in your program that reads "BSAVE". Download the
program (even if you don't really have a Stamp hooked up -- you don't
even have to own a Stamp). This places a file in the current directory
called CODE.OBJ. You can rename the file if you like, but keep the
.OBJ extension.

Next, start BS1. It will bring up a dialog where you can pick what
file you want to open. After you open the file, the main screen
will appear. At the top of the window are 8 LEDs that show
your outputs (black is 0, red is 1, and hollow means the pin is an input).
Below that are 8 buttons that represent your inputs. Black is a zero input
and green is a one input. Below that are several special I/O locations 
(see below). Below that are all the W and B registers along with the 
PORT register. You can modify the W registers by typing over the
numbers already there. At the very bottom of the screen you will
see a decoding of the next statement to execute (which may look a little odd,
but you'll be able to figure it out).

There are three buttons: Run, Step, and Step Over. The Run button causes the
program to execute as fast as possible (about 1 instruction per millisecond).
Step executes one line of code. Step Over executes a line of code too, but
if it is a GOSUB, the debugger stops when it hits the corresponding RETURN.
When you press RUN, by the way, the button changes to STOP and you can
press it to go back to single step mode.

Special I/O Locations
=====================
In the center of the screen are three boxes: LastPWM, Pot Input, and 
Pulse In. The LastPWM box shows the result of the last PWM command (to
any pin) as a fraction of 5 volts. You can't change this value and the next
PWM will write over it.

The Pot Input and Pulse In boxes let you specify input values for any POT or
PULSIN command regardless of the pin specified in the program. If you
leave the boxes blank, BS1 will prompt you for a value (which is not
handy when you are in RUN mode). If you use more than one POT or PULSIN pin,
you'll probably want to leave these boxes blank when you run at full speed.


Unsupported Constructs
======================
In this release DEBUG is not functional (it is ignored).
BUTTON, SEROUT, and SERIN are not functional and will cause BS1 to reset.
If there is interest, there may be a full version of BS1 for sale
sometime in the future. Drop us an e-mail and let us know what you
think.

Quirks
======
Disassembling BS1 statements is difficult since much of the information
you supplied at runtime is already gone. Some statments (notably FOR/NEXT)
do not disassemble completely, but they function correctly. Others like
SOUND and BRANCH will have an extra comma in the list which is harmless.

Of course, you will not see any comments or symbol information. Addresses
are shown in hex which probably doesn't mean anything to anyone.

Specifics
=========
LET, LOOKDOWN, LOOKUP, HIGH, LOW, INPUT, OUTPUT, TOGGLE, REVERSE - No notes.
GOTO, BRANCH, END - No notes.
PWM - The PWM command shows its output in the Last PWM box. It changes
the state of the pin correctly, but you won't see any change to the
digital state of the output.
POT - The POT command will read from the special input box, if possible. You
should enter the final answer you expect from the POT reading (0-255).
PULSOUT - PULSOUT doesn't really pause for the correct number of 10uS periods,
but it does attempt to flash the digital output visually and leaves the
pin in the correct state.
PULSIN - PULSIN reads from the special input box, if possible. Enter the
period in 10uS units.
FOR - As noted, the FOR statement doesn't disassemble correctly, but it does
function properly. You will only see the variable and the inital value as in
"FOR B1=10"
NEXT - It would be possible to show more information for the NEXT, but
in this release it does not. Let us know what you think.
READ - EEPROM reads are not paced to account for their slow execution.
WRITE - EEPROM writes are not paced to account for their slow execution.
GOSUB - There is a 16 GOSUB limit. GOSUB writes zeros to W6 so that
you know not to use it (as in the real BS1) but the execution details
are not the same!
RETURN - Same notes as for GOSUB (W6 is destroyed even though BS1 doesn't
really use it).
PAUSE - PAUSE attempts to wait the correct interval in RUN mode although
this is not a sure thing.
NAP - NAP attempts to wait the correct interval in RUN mode.
SLEEP - SLEEP attempts to wait the correct interval in RUN mode.
RANDOM - RANDOM probably uses a different algorithm to generate numbers
than the real Stamp. However, starting with the same seed should give
you the same numbers in BS1 (but that may be different from a real Stamp).
SOUND - Windows 95 makes the same sound for any note value (works on NT).
IF - The IF statment shows a little arrow next to it if the jump will be
taken.
DEBUG - Unimplemented and ignored.
BUTTON, SERIN, SEROUT - Unimplemented in the Lite version.

Bug Reports and Comments
========================
Send reports to alw@al-williams.com. This is a freebie, so if I can
help you, great! If I can't, then too bad. If you have questions
about specific Stamp programming, try the Basic Stamp mailing list
(go to http://www.parallaxinc.com to join).

The Non-Lite Version
====================
Will there be a non-Lite version? That's up to you. Let us know if you
would be interested in seeing us introduce a full version for sale.

Some features MIGHT be:
* Real serial I/O via the PC's serial port or simulated to a terminal window
* Unlimited Pot and PulsIn pin simulations
* Better disassembly corresponding to original source file
* Viewing of entire program at once
* Bounds checking on READ/WRITE; W6 usage, etc.
* Better SOUND emulation
* Emulation of BUTTON
* Allow for intermittent I/O (push buttons)
* Allow for reversing sense of switches/LEDs
* Breakpoints and Watchpoints
* Support
* What would you like to see? Let us know

Distribution
============
This software is compliments of AWC and you are free to use it
for your personal use as you see fit. However, this software is
not public domain and you may not redistribute it in any way
with any product or service. If you would like to mirror the
official distribution on your Web or FTP site, contact AWC and
we will not unreasonably withold our permission to do so provided you
agree not to charge for the software, add or delete content from
the distrution, and you agree to keep the most current version.

About AWC
=========
AWC also makes the ASP-I Solderless Stamp Breadboard. You can use
the ASP-I to quickly and easily prototype Stamp I and Stamp II
designs. And with the APP-I add-on kit, you can inexpensively
work with PicStics, and PIC 16C84/16F84 processors, too.
For more information, check out our Web site 
at http://www.al-williams.com/awce


Disclaimers
===========
This software is provided free and is as-is. AWC makes no warantee
as to its fitness for any purpose whatsoever. Basic Stamps are a
product of Parallax Inc. AWC is in no way affiliated with 
Parallax.

AWC
310 Ivy Glen Court
League City, TX 77573
http://www.al-williams.com/awce


Bug History
===========
Version 0.1, Initial Release
Version 0.2, Fixed problem when Sound note=0, realized note>127 does not work (declined)
	     Long sleep values cause overflow
	     Fixed LEDs intermittently changing Input/output status
Version 0.3, Fixed PWM parsing
	     Incorrect byte register display fixed
	     For with negative step or 0xFFFF limit fixed
Version 0.4, Chased down more overflow problems, End works correctly again, Hitting an
             End statement stops run mode
Version 0.5, Yet more overflow problems
Version 0.6, One more overflow problem
Version 0.7, Finally got around to adding nice switches and LEDs
Version 0.8, Gosubs at byte boundaries were broken upon return









































