August 22, 2011

1

MATLAB Support Package for BASIC Stamp
User's Guide
Contents
Introduction ................................................................................................................................................................2
Installation Instructions ..............................................................................................................................................3
Step 1: Downloading Firmware ..............................................................................................................................3
Step 2: Running Setup ............................................................................................................................................4
Getting Started ...........................................................................................................................................................6
Finding the Correct Serial Port ...............................................................................................................................6
Creating a BasicStamp Object ................................................................................................................................6
Calling Methods ......................................................................................................................................................6
Cleaning Up ............................................................................................................................................................7
Accessing Help ........................................................................................................................................................7
Examples .................................................................................................................................................................7
Reference Guide and Advanced Topics ......................................................................................................................9
BasicStamp Methods ..............................................................................................................................................9
Test Mode ...............................................................................................................................................................9
Extending Functionality ....................................................................................................................................... 10
Troubleshooting ...................................................................................................................................................... 12


August 22, 2011
2

Introduction
The MATLAB Support Package for BASIC Stamp (hereby referred to as the Support Package) is a MATLAB
interface to the Parallax BASIC Stamp 2 (BS2) that allows access to the BS2s functionality in real time through a
RS-232 (also known as a COM or serial port) or USB connection. More specifically, the Support Package was
designed for a BS2 installed on a USB Board of Education; however, it should work with any BS2 and serial
interface.
Requirements:
Windows, Mac OS X, or Linux platform
32 or 64 bit MATLAB R2009a or later
A BASIC Stamp editor that supports PBASIC 2.5
The Support Package was tested using Windows 7 and Parallaxs BASIC Stamp Editor v2.5.2. However, any
platform that is capable of running a supported version of MATLAB should be able to use this package. Similarly,
any BASIC Stamp editor that can download PBASIC 2.5 code to a BASIC Stamp 2 should be sufficient to download
firmware to the device.


August 22, 2011
3

Installation Instructions
Step 1: Downloading Firmware
The Support Package requires that the included PBASIC firmware is running on the BS2. The following download
instructions are for Windows 2000 or later and use Parallaxs BASIC Stamp Editor to download the firmware to
the BS2. Parallax also provides software for earlier versions of Windows, as well as for Mac and Linux
environments. The process should be similar for other PBASIC editors; see their documentation for help. Note
that PBASIC 2.5 support is required.
1. Go to this website and follow the instructions to download and install the latest version of the BASIC
Stamp Editor.
2. Connect the BASIC Stamp 2 to the computer through a USB or serial port and turn it on.
3. Open the BASIC Stamp Editor. You can do this through the Windows Start menu (Start menu > All
Programs > Parallax Inc > BASIC Stamp Editor v2.5.2 > BASIC Stamp Editor v2.5.2)

4. In the BASIC Stamp Editor, select File > Open
Navigate to the folder containing this support package
Double-click on stampfirmware.bs2
5. In the BASIC Stamp Editor, select Run > Identify
You will see a dialog box with information like the following:



Note the port that the BS2 is connected to; in the example above, a BS2 is connected to COM4.
Knowing what this port is will help to skip some steps later
6. In the BASIC Stamp Editor, select Run > Run. This will tokenize and download the firmware to the BS2.
7. Firmware installation is now complete. The firmware should remain on the BS2 until another program is
downloaded and overwrites the program. If this happens, simply follow steps 3-7 to download the
firmware again.


Port Device Type: Version Loopback Echo
COM1: No No
COM4: BASIC Stamp 2 v1.0 Yes Yes
August 22, 2011
4

Step 2: Running Setup
1. On Windows Vista or Win7 systems, run MATLAB as an administrator by right clicking on the MATLAB
icon and selecting Run as administrator. On other systems, start MATLAB in the normal way.


2. Click on the ellipsis () to the right of the Current Folder prompt at the top of the screen

3. Navigate to this folder (\BASICStamp\) and click OK.

4. In the Command Prompt, type stamp.setup without the quote marks



August 22, 2011
5

5. A message box saying "Setup was successful" should pop up. If an error box that says Unable to save
updated MATLAB path pops up instead, make sure that MATLAB is has administrative rights. If it does
and the error still pops up, check that you have write access to pathdef.m (click this link for more
information on the MATLAB search path).

6. Installation is now complete.
August 22, 2011
6

Getting Started
The Support package uses MATLAB's Object Oriented (OO) Programming feature to provide a stable interface to
the BS2. Users unfamiliar with MATLAB OO concepts should read this guide to familiarize themselves with the
basics of object creation and method calls.
Finding the Correct Serial Port
The Support Package accesses the BASIC Stamp 2 through an object of the MATLAB class called
stamp.BasicStamp. To create a stamp.BasicStamp object, the serial port that the BS2 is connected to must be
known. One way to find this port name is to open the BASIC Stamp Editor and select Run > Identify This will
show a table like the one below, which indicates that the BS2 is connected to the COM4 serial port.


Alternatively, there is a MATLAB function in the package called stamp.findComPorts that will list the valid serial
ports for the computer. To call this function, type the following in the Command Window:
stamp.findComPorts

This may list multiple ports; in this case, a RS-232 device will likely be connected to a lower-numbered port,
while a USB device will likely be connected to a higher-numbed port. If there are multiple listed ports, simply try
to create a stamp.BasicStamp with each; the object will only be created without an error for a serial port
connected to a BS2 running the proper firmware.
Creating a BasicStamp Object
As mentioned above, its necessary to create a stamp.BasicStamp (hereby referred to as BasicStamp) object to
interface with the BS2. To create the object and name it bs, type the following in the Command Window,
replacing comport with the serial port determined above:
bs = stamp.BasicStamp('comport')

For example, if the BS2 was connected to the serial port COM4, typing the following would create a BasicStamp
object for accessing that BS2:
bs = stamp.BasicStamp('COM4')
Calling Methods
The functionality of the BS2 is accessed through the BasicStamp class's methods. For example, BasicStamp's
readPin method returns the digital state of the specified pin:
bs.readPin(0)

This will return a one if pin 0 is high or a zero if pin 0 is low. These methods act like any other class method and
can be integrated with other MATLAB code to manipulate the BS2 and any other hardware attached to it. A full
method list for the Basic Stamp class is included in the Reference Guide section of this document. In addition,
help for each method can be accessed as described in Accessing Help below.
Port Device Type: Version Loopback Echo
COM1: No No
COM4: BASIC Stamp 2 v1.0 Yes Yes
August 22, 2011
7

Cleaning Up
Its good practice to delete any objects in the workspace once theyre no longer in use. This frees up memory
and can fix some strange errors elsewhere. To delete bs, type:
delete(bs);

This will automatically end the serial connection with the BS2. Deleting an object won't remove its variable from
the MATLAB workspace; use the clear command to remove this variable, as in the following:
clear bs;

Accessing Help
The Support Package has built-in help for each of BasicStamp's methods and for every included file.
help topic

Topic can be any method name, class name, or m-file name (m-files are files with the .m extension; their
filename is the part before the extension). For example, to get help for BasicStamp, BasicStamp's getState
method, and the stamp.findSerialPorts script, type:
help stamp.BasicStamp
help stamp.BasicStamp.getState
help stamp.findSerialPorts

Note that the package name must be included; typing "help BasicStamp" will return an error. All help includes a
description of what the method, script, or function does, as well as proper calling syntax where appropriate.
Some of the help texts will direct attention to PBASIC functions. This is because much of the Support Package
provides direct access to these well-documented functions. Parallax's documentation on PBASIC can be found in
the BASIC Stamp Syntax and Reference Manual v2.2, which is available as a book with the BASIC Stamp
Discovery Kit or as a downloadable PDF here.
Examples
The Support also comes with several examples. These correspond directly with examples from What's a
Microcontroller?, which is available in book form with the BASIC Stamp Discovery Kit or in PDF form on this
webpage. The help text for each example (available by typing "help examplename" while in the \examples
directory, where examplename is the name of the example file minus the .m extension) contains a reference to
an example name and a page number, with the page number referring to version 3.0 of the book. These
examples use electronic components from the BASIC Stamp Discovery Kit; however, these can easily be replaced
by equivalent components typically used by hobbyists.
For all examples, use the hardware setup in the book, but run the MATLAB code instead of the provided PBASIC
code. For scripts, do this by opening the script in the MATLAB editor and pressing the green run arrow.
August 22, 2011
8


For functions, navigate to the \examples\ directory and type the function name (with arguments, if applicable)
in the Command Window.


August 22, 2011
9

Reference Guide and Advanced Topics
BasicStamp Methods
Note: all methods should be invoked on a BASIC Stamp object. For example, the getState method would be
invoked like this:
bs = stamp.BasicStamp('COM4')
result = bs.getState(pin)
For brevity, the bs. Is omitted in the tables below.

General I/O
result = getState(pin) Returns the input/output state of pin
setState(pin,state) Sets the input/output state of pin to state
result = readPin(pin) Reads the digital state of pin
writePin(pin,value) Sets the digital state of pin to value
result = recvPulse(pin,pulsestate) Returns the pulse width of a voltage pulse
sendPulse(pin,duration) Outputs a rectangular pulse to pin
result = getRCTime(pin,onstate) Measures how long pin stays in onstate
outputPWM(pin,dutycycle,duration) Outputs a pseudo-PWM signal
result = countStateChanges(pin,duration) Counts how many times pin changes digital state
outputSine(pin,duration,freq) Outputs a sine wave to pin
outputDTMF(pin,duration,tone) Outputs a dual-tone multi-frequency waveform to pin
outputX10(signalpin,zeroxpin,housecode,commandcode) Outputs a X10 command

Serial I/O
result = readSerialAsync(pin,baudrate,parity,polarity) Reads a single byte from an asynchronous serial
channel
writeSerialAsync(pin,baudrate,parity,polarity,databyte) Outputs one byte of data to an asynchronous
serial channel
result = readSerialSync(pin,clockpin,LSBfirst,edge) Reads a single byte from a synchronous serial
channel
writeSerialSync(pin,clockpin,LSBfirst,edge,databyte) Outputs one byte of data to a synchronous
serial channel

Advanced (See "Extending Functionality")
result = serialCommand(numoutputs,wait,args) Outputs a command to the BASIC Stamp and
returns any output from the Stamp
flushBuffer Flushes MATLAB's input buffer

Test Mode
It's possible to create a BasicStamp object in test mode. Test mode uses a dummy serial port, so it won't affect
any connected BS2s. To create a BasicStamp object in Test Mode, type:
bs = stamp.BasicStamp('test')

Test mode is helpful for testing code without having to have a BS2 connected. All BasicStamp methods that
return a value will return 0 instead.
August 22, 2011
10

Extending Functionality
The Support Package provides fairly comprehensive access to the BS2's functionality. However, there are some
pieces, such as the advanced options for serial communication, which were left out in order to simplify the
interface. Users familiar with PBASIC programming can add additional functionality by editing
stampfirmware.bs2 with their own code and interfacing it with the BasicStamp class.
To add an additional command to the serial interface, simply add additional CASEs to the SELECT structure that
makes up the bulk of the code. User code should be added at the "*Add User Code Here" comment near the end
of the code, and should follow the following general format:
CASE XX 'Command number (0-16 are reserved by the default code)
' ***USER CODE***

The case number should be the smallest unused case number and represents the command code that MATLAB
will send to the device (codes 0-16 are used by the default firmware). The current structure supports up to 15
additional commands; up to 255 total commands are possible by adding more SELECT structures.
The default firmware provides four words of input memory. The input memory is where the BASIC Stamp stores
the serial input from MATLAB, and is named both on a word and byte level (for the most part). An additional
word of input can be added by uncommenting the third SERIN command after the Start label and by changing
BasicStamp.NUMINPUTS from 6 to 8 (see below). The following table describes naming conventions for input
memory:
Word Name N/A value43 value65 value87
Byte Name command pinnum value3 value4 value5 value6 value7 value8
Description Command # Pin to affect (Potentially) optional arguments Additional optional
arguments (off by default)
args Entry 1 2 3-6 7-8

In addition, three words of working memory, respectively named scratch1, scratch2, and scratch3, are provided.
These aren't populated by the firmware but instead serve as preallocated memory for functions to use.
Finally, to output values to MATLAB, use the following SEROUT command:
SEROUT Ser, Baud, [data to output]

To use any additional commands added to the firmware, call BasicStamp's serialCommand method. This method
takes three arguments: the expected number of outputs from the Stamp, the amount of time to wait between
write and read operations (helpful if the Stamp needs time to monitor inputs), and a row vector of arguments to
send to the Stamp. The latter should be a 1xn vector of scalars that can be cast into 8-bit unsigned integers
(examples include any integer and 8-bit encoded characters).
The format for this array is shown in the above table; in short, the first two entries (args(1) and args(2)) should
be the command number and the pin number, respectively, while the rest are value(s). serialCommand will
automatically pad args with zeros if it's shorter than the expected number of outputs, so not all optional
arguments are required. Similarly, serialCommand will ignore later entries for args if it is longer than expected.
August 22, 2011
11

The number of inputs MATLAB will send to the BS2 is determined by BasicStamp's NUMINPUTS property. To
change this, open BasicStamp.m in the +stamp folder and change the value of NUMINPUTS in the second
Properties field. This is necessary if values 7 and 8 are used. Note that leaving the number of inputs that
MATLAB and the BS2 desynchronized will lead to unpredictable behavior.
Finally, as a convenience, BasicStamp provides a method for flushing MATLAB's serial input buffer.
serialCommand expects that the buffer is empty before issuing a command, and will usually issue a write error if
it is not. Use BasicStamp's flushBuffer command to empty the serial buffer. This should never be necessary
during normal operation, but may be helpful during debugging. If it seems necessary to call flushBuffer before
each command call, check that the right number of output arguments is being specified and that NUMINPUTS is
set to the correct value.

August 22, 2011
12

Troubleshooting
Make sure to read the rest of the guide before accessing this section. Questions or comments regarding the
MATLAB Support Package for BASIC Stamp may be sent to classroom-resources@mathworks.com
??? Could not connect to the BASIC Stamp
Check that it is attached and that the specified serial port is correct

BasicStamp could not open a connection to the BS2. Check that the USB or serial cable is securely attached to
both the computer and the Board of Education (or equivalent). Also check that comport is correct.

??? Firmware error
Check that the BASIC Stamp is connected and powered
Try downloading the firmware to the BS2 again
See README.pdf for information on downloading firmware

BasicStamp could open a connection with the specified serial port but could not validate the BS2 firmware.
Check that the USB or serial cable is securely attached to both the computer and the Board of Education (or
equivalent) and that the BS2 is receiving power. Also check that comport is correct. Finally, try downloading
the Support Package firmware to the BS2 again (see "Step 1: Downloading Firmware").

??? Serial write failed!
Please check connection to the BASIC Stamp.

BasicStamp tried to send a command to the BS2 and could not. Check that the USB or serial cable is securely
attached to both the computer and the Board of Education (or equivalent) and that the BS2 is receiving
power.

??? Not enough output from BASIC Stamp
If this is a built-in function, try redownloading firmware
If this is a user function, make sure serialCommand is called correctly

BasicStamp sent a command to the BS2 but didn't get an expected result. Try downloading the Support
Package firmware to the BS2 again (see "Step 1: Downloading Firmware"). If this is a user function (See
"Extending Functionality"), this could be due to an error in either the PBASIC code or in the serialCommand
code; make sure that the number of outputs each are expecting match up.