Activity: First Program

The first program you will write and test will tell the BASIC Stamp to send a message to your computer.  The figure below shows how it sends a stream of ones and zeros to communicate the text characters displayed by your computer.  These ones and zeros are called binary numbers.  The BASIC Stamp Editor software has the ability to detect and display these messages as you will soon see.

First Program

In this Help tutorial, the program listings that you will type into the BASIC Stamp Editor and download to the BASIC Stamp module will be shown with a blue background like this: 

Example Program: FirstProgram.bs2

' Stamps in Class - FirstProgram.bs2 
' BASIC Stamp sends message to Debug Terminal.
 
' {$STAMP BS2}
' {$PBASIC 2.5}
 
DEBUG "Hello, it's me, your BASIC Stamp!"
END

You will enter this program into the BASIC Stamp Editor. Some lines of the program are created automatically by clicking buttons on the toolbar.  Other lines are made by typing them in from the keyboard.

• Begin by clicking the BS2 icon (the green diagonal chip) on the toolbar.  If you hold your cursor over this button, its flyover help description “Stamp Mode: BS2” will appear.
• Next, click on the gear icon labeled “2.5.”  It’s flyover help description is “PBASIC Language: 2.5”.

Tip:  ALWAYS use these toolbar buttons to add these two lines as the beginning of every program!   Compiler directives use braces {  }.  If you try to type in these parts of your program, you may accidentally use parentheses ( ) or square brackets [  ].  If you do this, your program will not work.

If you are using some other 24-pin BASIC Stamp model instead of a BS2, you can still follow the activities here and in any Stamps in Class text, but you will need to adjust all time-sensitive commands or they will not work properly. Read Adapt BS2 Code to Other Models for instructions. (It's under PBASIC Language Reference in the Table of Contents).

• Type in the remaining lines of the program exactly as shown:

• Save your work by clicking File and selecting Save.

• Enter the name "FirstProgram" into the File name field near the bottom of the Save As window.
• Click the Save button.

Tip:  The next time you save, the BASIC Stamp Editor will automatically save to the same filename (FirstProgram.bs2) unless you tell it to save to a different filename by clicking File and selecting Save As (instead of just Save).

• Click Run, and select Run from the menu that appears.

A Download Progress window will appear briefly as the program is transmitted from your computer to your BASIC Stamp module.  The figure below shows the Debug Terminal that should appear when the download is complete.  You can prove to yourself that this is a message from the BASIC Stamp by pressing and releasing the Reset button on your board.  Every time you press and release it, the program will re-run, and you will see another copy of the message displayed in the Debug Terminal.

• Press and release the Reset button.  Did you see a second “Hello…” message appear in the Debug Terminal?

The BASIC Stamp Editor has shortcuts for most common tasks.  For example, to run a program, you can press the ‘Ctrl’ and ‘R’ keys at the same time.  You can also click the Run button.  It’s the blue triangle that looks like a music player’s Play button.  The flyover help (the Run hint) will appear if you point at the Run button with your mouse.  You can get similar hints to find out what the other buttons do by pointing at them too.

How FirstProgram.bs2 Works

The first two lines in the example are called comments.  A comment is a line of text that gets ignored by the BASIC Stamp Editor, because it’s meant for a human reading the program, not for the BASIC Stamp module.  In PBASIC, everything to the right of an apostrophe is normally considered to be a comment by the BASIC Stamp Editor.  The first comment tells which book the example program is from, and the program’s filename.  The second comment contains a handy, one-line description that explains what the program does.

' Stamps in Class - FirstProgram.bs2
' BASIC Stamp sends message to Debug Terminal.

Although comments are ignored most of the time, the BASIC Stamp Editor does search through comments for special directives.  Every program in this Getting Started section of help will use these two directives: 

' {$STAMP BS2} 
' {$PBASIC 2.5}

The first directive is called the $STAMP Directive, and it tells the BASIC Stamp Editor that you will be downloading the program specifically to a BASIC Stamp 2 module.  The second directive is called the $PBASIC directive, and it tells the BASIC Stamp Editor that you are using version 2.5 of the PBASIC programming language.  These special comments are called compiler directives, and they are enclosed in braces { } not parentheses ( ). You should always use the toolbar icons to place these compiler directives in your program to avoid typing errors. Also, entering the compiler directives by hand may not activate the syntax highlighting in the BASIC Stamp Editor. That function is what causes various letters, characters and words in your program to appear in different colors and capitalization schemes.  Syntax highlighting makes your programs easier to read, understand, and correct if there are any bugs in them.

A command is a word you can use to tell the BASIC Stamp do a certain job.  The first of the two commands in this program is called the DEBUG command:

DEBUG "Hello, it's me, your BASIC Stamp!"

This is the command that tells the BASIC Stamp to send a message to the PC using the serial cable. 

The second command is the END command:

END

This command is handy because it puts the BASIC Stamp into low power mode when it’s done running the program.  In low power mode, the BASIC Stamp waits for either the Reset button to be pressed (and released), or for a new program to be loaded into it by the BASIC Stamp Editor.  If the Reset button on your board is pressed (or if you disconnect and reconnect your power supply), the BASIC Stamp will re-run the program you loaded into it.  If a new program is loaded into it, the old one is erased, and the new program begins to run.

Your Turn – Delays with PAUSE, DEBUG Formatters, and Control Characters

In What’s a Microcontroller? and Robotics with the Boe-Bot, the first command you will likely see in the example programs that display messages in the Debug Terminal is a 1-second delay, typically with the command PAUSE 1000. The PAUSE command delays the program for a certain number of milliseconds. Milliseconds are thousandths of a second are typically abbreviated ms. So, PAUSE 1000 delays the program for 1000 thousandths of a second, which is one second.

• Modify the program by inserting PAUSE 1000 immediately above the DEBUG command.

PAUSE 1000

• Your code should then look like this:

' Stamps in Class - FirstProgram.bs2
' BASIC Stamp sends message to Debug Terminal.

' {$STAMP BS2}
' {$PBASIC 2.5}


PAUSE 1000
DEBUG "Hello, it's me, your BASIC Stamp!"
END

• Run the modified program and verify that it delays for a second before displaying the Hello message.

For comparison, you can disable the PAUSE command by commenting it. In other words, add an apostrophe to its left so that it reads ' PAUSE 1000. By removing the apostrophe and re-running the program, you can then test how the program behaves without the PAUSE.

• Try it.

Tip:  Inserting a one second delay before the BASIC Stamp transmits messages to the Debug Terminal ensures that the Windows operating system cannot possibly mistake the BASIC Stamp for a plug-and play-serial device like a mouse or keyboard. This can happen if the BASIC Stamp is running a program that immediately transmits messages to the Debug Terminal when it gets connected to a USB port. It can also happen if the same program is running as the computer boots while it is connected to a serial or USB port. The PAUSE 1000 ensures that this case of "mistaken microcontroller identity" won't happen because it waits longer than the 0.7 second window that PCs give serial plug-and-play devices to identify themselves.

DEBUG Formatters and Control Characters

A DEBUG formatter is a code-word you can use to make the message the BASIC Stamp sends look a certain way in the Debug Terminal. DEC is an example of a formatter that makes the Debug Terminal display a decimal value. An example of a control character is CR, which is used to send a carriage return to the Debug Terminal. The text or numbers that come after a CR will appear on the line below characters that came before it. You can modify your program so that it contains more DEBUG commands along with some formatters and control characters. Here’s an example of how to do it:

• Modify the comments at the beginning of the program so they read:

' Stamps in Class - FirstProgramYourTurn.bs2
' BASIC Stamp sends messages to Debug Terminal

• Add these three lines between the first DEBUG command and the END command:

DEBUG CR, "What's 7 X 11?"
DEBUG CR, "The answer is: "
DEBUG DEC 7 * 11

• Save the changes you made by clicking File and selecting Save As. A good name would be FirstProgramYourTurn.bs2
• Check your work against the example program shown here.
• Run your modified program.  You will have to either select Run from the Run menu again, or click the Run button.

• Check your Debug Terminal - does it now look like this?
• If not, correct your program and re-run it until you get the results you expect.

Tip:  Sometimes the Debug Terminal gets hidden behind the BASIC Stamp Editor window.  You can bring it back to the front by using the Run menu as shown, the Debug Terminal 1 shortcut button on the toolbar, or the F12 key on your keyboard.