PBASIC Language

References

Parallax Inc are the developpers of PBASIC. They wrote a very detailled document about almost all you can do with a BS2 in terms of software. The Basic Stamp Programming Manual is free and online on their website.

BASIC Stamp Editor

This is the most popular editor for BS2s. It is very simple and easy to use. You simply type in your code, plug your BS2 in your serial port with the RS232 cable and click on RUN in the editor and your BS2 is ready to go.
You must put a special command on the first line of your program. This command will tell the Editor how to translate your program from PBASIC to binary strings before uploading it in the microcontroller:

'{$STAMP BS2}

Comments

In PBASIC everything that follows the symbol ' is a comment and will not be executed by the µprocessor.

Memory

The BS2 has 32 bytes of variable RAM space. Of these, the first six bytes are reserved for input, output, and direction control of the I/O pins. The remaining 26 bytes are available for general-purpose use as variables. That means that your program can hold a maximum of 26 variables having a maximum value of 1 byte (256).

I/O

The I/O pins of the BS2 are numbered from 0 to 15.
If you want to use them as input, you can access the variables IN0 to IN15. For example you can check if a switch connectec to pin 6 is open or closed. If the switch is open IN6 will be equal to 0. If the switch is closed IN6 will be equal to 1.
If you want to use the pins as output, you can use the variables OUT0 to OUT15.
For example, if you want to turn on a LED connected to pin 4, one possible way would be to assign the value 1 to the variable OUT4.

Variables

You can define a variable the following way:

Name VAR Size

where Name is whatever name you want, VAR tells PBASIC that it is a new variable and Size is the maximum value you will be allowed to put in this variable.
There are certain rules regarding variable names. Variables must start with a letter, can contain a mixture of letters, numbers, and underscore characters, and must not be the same as PBASIC keywords or labels used in your program. Additionally, variables can be up to 32 characters long.
The Size argument has four choices: BIT (1 bit), NIB (nibble; 4 bits), BYTE (8 bits), and WORD (16 bits). For example:

• Mouse VAR BIT
  'here the value can be 0 or 1
• Cat VAR NIB
  'here the value can be 0 to 15
• Dog VAR BYTE
  'here the value can be 0 to 255
• Rhino VAR WORD
  'here the value can be 0 to 65535

Assignments

Once a variable is declared you can start assigning it values. You do it with the equal sign. For example:

• Mouse = 1
• Cat = 9
• Dog = Cat
  'here we say copy the value stored
  'in Cat into the variable Dog

Arithmetics

You can perform arithmetic operations on numbers and variables. For example:

• 5 * 5
  'multiply 2 numbers
• Mouse + 10
  'add 10 to the value contained in Mouse
• Rhino / Cat
  'divide the value of Rhino
  'by the value of Cat

Now it is important to realize that those operations will not affect anything in the program because we do not store the result anywhere. If we want to store the result somewhere we need to incorporate the assignment operator to the statement. For example:

• Dog = 3 - 2
  'substract 2 to 3 and put the result
  'in the variable Dog
• Dog = Cat * 2
  'multiply the value stored in Cat 2 times
  'and put the result in the variable Dog
• Dog = Dog / Dog
  'divide the current value of Dog
  'by the current value of Dog and
  'put the new result in Dog.
  'In this case Dog would equal 1.

I/O part 2

LOW 'Make pin output low.
HIGH 'Make pin output high.

HIGH and LOW are easier ways to turn on and off circuits connected to output pins. HIGH sends 5V through the pin and LOW grounds the pin. For example:

HIGH 3 'this will turn on pin 3 of the BS2

Waiting

PAUSE 'Pause execution for 0–65535 milliseconds.

PAUSE is very useful in programs. The microprocessor makes very fast calculations, sometimes too fast. You might want to have it wait for some time before executing the next command. in this case you use the PAUSE command. For example:

HIGH 1 'turn on whatever is connected to pin 1

PAUSE 1000 'leave it on for 1 second

LOW 1 'and turn it off

Loops

Label: 'define a label
GOTO 'Branch to the label

This command is for lazy people. To use it, you first need to put a label at the beginning of important code you would wish to go to many times in the life of your program. Then anywhere in the program, you can simply say "GOTO WhateverLabel" and the program will jump to this piece of code. For example:

Flash: 'define the label

...... 'lines of code

GOTO Flash 'jump to the label Flash

This example would create an infinite loop.

Control Statements

IF...THEN 'Compare and conditionally branch.

This is used to make a comparsion and, depending on the result, GOTO a label or a subroutine (see below). For example:

IF IN2 = 1 THEN Flash

That means: IF the input pin 2 is on (if a button is pressed for example) THEN GOTO label Flash and execute the commands right under this label. If it is not on, simply ignore this statement.

Loops part 2

FOR...TO...NEXT 'Establish a FOR-NEXT loop.

This a more controllable form of looping. You can tell the program how many times to loop. For example:

counter VAR BYTE 'define a variable called counter

FOR counter = 0 TO 9 'tell the program to loop 10 times

.... ' execute commands in the loop

NEXT 'tell the program this is the end of the looping commands

In this code, all the commands between "FOR counter = 0 TO 9" and "NEXT" would be executed 10 times.

Subroutines

GOSUB 'Branch to subroutine at address.
RETURN 'Return from subroutine.
END 'Terminate the whole program.

The same way you create labels to use in GOTO statements, you can create subroutines. You define a label just like in GOTO but you encapsulate the code in the label by adding a RETURN or an END statement at the end. For example:

Strobe: 'define a label for the subroutine Strobe

..... 'code to be executed when calling the subroutine Strobe

RETURN 'End of the subroutine

..... 'arbitrary commands

GOSUB Strobe 'jump to subroutine Strobe

.... 'rest of the program

In this example, we define a subroutine Strobe (that could strobe LEDs for example). Then somewhere else in the program we want to strobe LEDs. So we simply call the subroutine Strobe that will strobe the LEDs and, once finished strobing, will go back to the rest of the program. If we would have put END at the end of the subroutine, that would have terminated the whole program.

Measuring potentiometers

RCTIME 'Measure an RC charge/discharge time. Can be used to measure potentiometers.

Please refer to page 256 of the Basic Stamp Programming Manual.

Generating sound

FREQOUT 'Generate one or two sine waves of specified frequencies.

Please refer to page 123 of the Basic Stamp Programming Manual.

Debugging

DEBUG 'Send information to the PC for viewing.

DEBUG is used to get dynamic information on the behaviors of you program at runtime. It opens a window in the BASIC Stamp Editor and displays whatever you tell it to display. For example:

DEBUG IN6 'display the state of input pin 6

Other Commands

There are many more commands you can use with a BS2. I suggest you have an extensive look at the Basic Stamp Programming Manual for more information and examples about them.