DEBUG

Syntax: DEBUG OutputData {, OutputData}

Function

Display information on the PC screen within the BASIC Stamp editor program. This command can be used to display text or numbers in various formats on the PC screen in order to follow program flow (called debugging) or as part of the functionality of the BASIC Stamp application.

• OutputData is a variable/constant/expression* (0 - 65535) that specifies the information to output. Valid data can be ASCII characters (text strings and control characters), decimal numbers (0 - 65535), hexadecimal numbers ($0000 - $FFFF) or binary numbers (up to %1111111111111111). Data can be modified with special formatters as explained below.

* Note: Expressions are not allowed as arguments on the BS1. The only constant allowed for the BS1 DEBUG command is a text string.

Quick Facts

Explanation

DEBUG provides a convenient way for your BASIC Stamp to send messages to the PC screen while running. The name "debug" suggests its most popular use; debugging programs by showing you the value of a variable or expression, or by indicating what portion of a program is currently executing. DEBUG is also a great way to rehearse programming techniques. Throughout this manual, we use DEBUG to give you immediate feedback on the effects of instructions. The following example demonstrates using the DEBUG command to send the text string message "Hello World!".

  DEBUG "Hello, World!"                         ' test Message

After you download this one-line program, the BASIC Stamp Editor will open a Debug terminal on your PC screen and wait for a response from the BASIC Stamp. A moment later, the phrase "Hello World!" will appear. Note that if you close the Debug terminal, your program keeps executing, but you can't see the DEBUG data anymore.

Multiple pieces of data can be sent with one DEBUG command by separating the data with commas (,). The following example produces exactly the same results as the example above.

  DEBUG "Hello, ", "World!"                     ' test Message

DEBUG can also print and format numbers (values) from both constants and variables. Please note that formatting the DEBUG output with the BS1 differs significantly from formatting the DEBUG output with the BS2 family. Please read the appropriate sections that follow carefully.

Tip:  Don't let your BASIC Stamp be mistaken for a mouse!

Connecting USB-based boards to your PC may cause the BASIC Stamp to reset. If your BASIC Stamp program immediately starts sending serial data to the computer via a DEBUG or SEROUT command, your computer's operating system may mistake it for a mouse or other serial plug-and-play device. To avoid this, place a 1-second pause at the beginning of the program.

  BASIC Stamp 1 Formatting

On the BS1, the DEBUG command, by default, displays numbers in the format "symbol = value" (followed by a carriage return), using the decimal number system. For example:

SYMBOL  x       = B2

Init:
  x = 75

Main:
  DEBUG x
  END

...displays "x = 75" on the screen. To display the value, in decimal, without the "x =" text, use the decimal formatter (#) before the variable name. For example, the following code displays "75" on the screen:

SYMBOL  x       = B2

Init:
  x = 75

Main:
  DEBUG #x
  END

To display numbers in hexadecimal or binary form, use the $ or % formatter, respectively. The code below displays the same number in its hexadecimal and binary forms.

SYMBOL  x       = B2

Init:
  x = 75

Main:
  DEBUG $x, %x
  END

After running the above code, "X = $4B" and "X = %01001011" should appear on the screen. To display hexadecimal ($) or binary (%) values without the "symbol = " preface, use the # modifier as shown below:

SYMBOL  x       = B2

  x = 75
  DEBUG #x, "as HEX is ", #$x           ' displays "75 as HEX is $4B"

To display a number as its ASCII character equivalent, use the ASCII formatter (@). Typing DEBUG @x (in place of the DEBUG statement in the code above) would display "x = 'K'" on the screen.

Two pre-defined symbols, CR and CLS, can be used to send a carriage-return or clear-screen command to the Debug Terminal. The CR symbol will cause the Debug Terminal to start a new line and the CLS symbol will cause the Debug Terminal to clear itself and place the cursor at the top-left corner of the screen. The following code demonstrates this.

  DEBUG  "You can not see this.", CLS, "Here is line 1", CR, "Here is line 2"

When the above is run, the final result is "Here is line 1" on the first line of the screen and "Here is line 2" on the second line. You may or may not have seen "You can not see this." appear first. This is because it was immediately followed by a clear-screen symbol, CLS, which caused the display to clear the screen before displaying the rest of the information.

Tip:  The rest of this discussion does not apply to the BASIC Stamp 1.

  BASIC Stamp 2 Series Formatting

On the all BASIC Stamp models except the BS1, the DEBUG command, by default, displays everything as ASCII characters. What if you want to display a number? You might think the following example would do this:

x       VAR     Byte

Init:
  x = 65

Main:
  DEBUG x                               ' show value of x 
  END

Since we set x equal to 65 (in line 2), you might expect the DEBUG line to display "65" on the screen. Instead of "65", however, you'll see the letter "A" if you run this example. The problem is that we never told the BASIC Stamp how to output x, and it defaults to ASCII (the ASCII character at position 65 is "A"). Instead, we need to tell it to display the "decimal form" of the number in X. We can do this by using the decimal formatter (DEC) before the variable. The example below will display "65" on the screen.

x       VAR     Byte

Init:
  x = 65

Main:
  DEBUG DEC x                           ' show decimal value of x
  END

In addition to decimal (DEC), DEBUG can display numbers in hexadecimal (HEX) and binary (BIN). See the table below for a complete list of formatters.

Expressions are allowed within the DEBUG command arguments as well. In the above code, DEBUG DEC x+25 would yield "90" and DEBUG DEC x*10/2-3 would yield "322".

As seen above, special versions of the DEC, HEX and BIN formatters allow for the display of indicated, signed and fixed-width numbers. The term "indicated" simply means that a special symbol is displayed, before the number, indicating what number system it belongs to. For example:

x       VAR     Byte

Init:
  x = 65

Main:
  DEBUG HEX x                           ' show hexadecimal value of x
  END

...displays "41" (65, in decimal, is 41, in hexadecimal). You might see a problem here... unless you knew the number was supposed to be hexadecimal, you might think it was 41, in decimal... a totally different number. To help avoid this, use the IHEX formatter (the "I" stands for indicated). Changing the DEBUG line to read: DEBUG IHEX x would print "$41" on the screen. A similar formatter for binary also exists, IBIN, which prints a "%" before the number.

Signed numbers are preceded with a space ( ) or a minus sign (-) to indicate a positive or negative number, respectively. Normally, any number displayed by the BASIC Stamp is shown in its unsigned (positive) form without any indicator. The signed formatters allow you to display the number as a signed (rather than unsigned) value.

Tip:  Only Word-sized variables can be used for signed number display.

The code below demonstrates the difference in all three numbering schemes.

x       VAR     Word

Init:
  x = -65

Main:
  DEBUG "Signed:   ", SDEC  x, "  ", ISHEX x, "  ", ISBIN x, CR
  DEBUG "Unsigned: ", DEC  x, "  ", IHEX x, "  ", IBIN x
  END

This code will generate the display shown below:

Signed: -65 -$41 -%1000001
Unsigned: 65471 $FFBF %1111111110111111

The signed form of the number -65 is shown in decimal, hexadecimal and then in binary on the top line. The unsigned form, in all three number systems, is shown on the bottom line. If the unsigned form looks strange to you, it's because negative numbers are stored in twos-compliment format within the BASIC Stamp.

Suppose that your program contained several DEBUG instructions showing the contents of different variables. You would want some way to tell them apart. One possible way is to do the following:

x       VAR     Byte
y       VAR     Byte

Init:
  x = 100
  y = 250

Main:
  DEBUG "X = ", DEC x, CR               ' show decimal value of x
  DEBUG "Y = ", DEC y, CR               ' show decimal value of y
  END

...but typing the name of the variables in quotes (for the display) can get a little tedious. A special formatter, the question mark (?), can save you a lot of time. The code below does exactly the same thing (with less typing):

x       VAR     Byte
y       VAR     Byte

Init:
  x = 100
  y = 250

Main:
  DEBUG DEC ? x                         ' show decimal value of x
  DEBUG DEC ? y                         ' show decimal value of y
  END

The display would look something like this:

x = 100
y = 250

The ? formatter always displays data in the form "symbol = value" (followed by a carriage return). In addition, it defaults to displaying in decimal, so we really only needed to type: DEBUG ? x for the above code. You can, of course, use any of the three number systems. For example: DEBUG HEX ? x or DEBUG BIN ? y.

It's important to note that the "symbol" it displays is taken directly from what appears to the right of the ?. If you were to use an expression, for example: DEBUG ? x*10/2+3 in the above code, the display would show: "x*10/2+3 = 503".

A special formatter, ASC, is also available for use only with the ? formatter to display ASCII characters, as in: DEBUG ASC ? x.

What if you need to display a table of data; multiple rows and columns? The Signed/Unsigned code (above) approaches this but, if you notice, the columns don't line up. The number formatters (DEC, HEX and BIN) have some useful variations to make the display fixed-width. Up to 5 digits can be displayed for decimal numbers. To fix the value to a specific number of decimal digits, you can use DEC1, DEC2, DEC3, DEC4 or DEC5. For example:

x       VAR     Byte

Init:
  x = 165

Main:
  DEBUG DEC5 x                          ' show decimal value of x
  END                                   '  in 5 digits 

...displays "00165". Notice that leading zeros? The display is "fixed" to 5 digits, no more and no less. Any unused digits will be filled with zeros.

Using DEC4 in the same code would display "0165". DEC3 would display "165". What would happen if we used DEC2? Regardless of the number, the BASIC Stamp will ensure that it is always the exact number of digits you specified. In this case, it would truncate the "1" and only display "65".

Using the fixed-width version of the formatters in the Signed/Unsigned code above, may result in the following code:

x       VAR     Word

Init:
  x = -65

Main:
  DEBUG "Signed:   ", SDEC5 x, "  ", ISHEX4 x, "  ", ISBIN16 x, CR
  DEBUG "Unsigned: ", DEC5 x, "  ", IHEX4 x, "  ", IBIN16 x
  END

...and displays:

Signed: -00065 -$0041 -%0000000001000001
Unsigned: 65471 $FFBF %1111111110111111

Note that the columns don't line up exactly (due to the extra "sign" characters in the first row), but it certainly looks better than the alternative.

Displaying Strings (Byte Arrays)

If you have a string of characters to display (a byte array), you can use the STR formatter to do so. The STR formatter has two forms (as shown in the table above) for variable-width and fixed-width data. The example below is the variable-width form.

alpha   VAR     Byte(5)

Init:
  alpha(0) = "A"
  alpha(1) = "B"
  alpha(2) = "C"
  alpha(3) = "D"
  alpha(4) = 0
 
Main:
  DEBUG STR alpha, CR                   ' display "ABCD"
  END

This code displays "ABCD" on the screen. In this form, the STR formatter displays each character contained in the byte array until it finds a character that is equal to 0 (value 0, not "0"). This is convenient for use with the SERIN command's STR formatter, which appends 0's to the end of variable-width character string inputs. NOTE: If your byte array doesn't end with 0, the BASIC Stamp will read and output all RAM register contents until it finds a 0 or until it cycles through all RAM locations.

To specify a fixed-width format for the STR formatter, use the form STR alpha\n; where alpha is the byte array and n is the number of characters to print. Changing the DEBUG line in the example above to: DEBUG STR alpha\2 would display "AB" on the screen.

If you need to display the same ASCII character multiple times, the REP (repeat) formatter can help. REP takes the form: REP x\n ;where x is the character and n is the number of times to repeat it. For example:

  DEBUG REP "-"\10

...would display 10 hyphens on the screen, "----------".

Since individual DEBUG instructions can grow to be fairly complicated, and since a program can contain many DEBUGs, you'll probably want to control the character positioning of the Debug Terminal screen. DEBUG supports a number of different control characters, some with pre-defined symbols. The Debug Terminal in the Windows^® version of the editor supports all the control characters shown below, while the DOS version only supports a few of them.

Some of the control characters have pre-defined symbols associated with them. In your DEBUG commands, you can use those symbols, for example: DEBUG"Hello", CR displays "Hello" followed by a carriage return. You can always use the ASCII value for any of the control characters, however. For example: DEBUG"Hello", 13 is exactly the same as the code above.

The Move To control character is perhaps the most unique of the set. If the Debug Terminal receives this character, it expects to see an x and y position value to follow (in the next two characters received). The following line moves the cursor to column number 4 in row number 5 and displays "Hello":

  DEBUG CRSRXY, 4, 5, "Hello"

The upper-left cursor position is 0, 0 (that is column 0, line 0). The right-most cursor positions depend on the size of the Debug Terminal window (which is user adjustable). If a character position that is out of range is received, the Debug Terminal wraps back around to the opposite side of the screen.

The Clear EOL (end of line) control character clears the characters that appear to the right of, and on, the cursor's current position. The cursor is not moved by this action.

The Clear Down control character clears the characters that appear below, and on, the cursor's current line. The cursor is not moved by this action.

¹ Supported by BS1 DEBUG command (others not supported).
² This control character only works with the Windows^® version of the editor software.

In the BS2 family, DEBUG is actually a special case of the SEROUTinstruction. It is set for inverted (RS-232-compatible) serial output through the programming connector (the SOUT pin) at 9600 baud (BS2, BS2e, BS2sx, BS2p, and BS2pe) or 19.2 kBaud (BS2px), no parity, 8 data bits, and 1 stop bit. For example,

  DEBUG "Hello"

...is exactly like:

  SEROUT 16, $4054, ["Hello"]

in terms of function (on a BS2). The DEBUG line actually takes less program space, and is obviously easier to type.

You may view DEBUG's output using a terminal program set to the above parameters, but you may have to modify either your carrier board or the serial cable to temporarily disconnect pin 3 of the BASIC Stamp (pin 4 of the DB-9 connector). See the SEROUT command for more detail.

Another method to decrease program space is to reduce the number of DEBUG instructions by spreading DEBUG data across multiple lines. To do this, each line that wraps around must end with a comma as in the example below:

  DEBUG "This is line 1", CR,
        "This is line 2"

The example above works identically to, but uses less program space than, this version:

  DEBUG "This is line 1", CR
  DEBUG "This is line 2"

Tip:  Note that spreading a DEBUG statement across multiple lines requires the declaration of PBASIC 2.5 syntax.