SEROUT

Syntax : SEROUTTpin, Baudmode, ({#} OutputData)
Syntax : SEROUTTpin {\Fpin}, Baudmode, {Pace,} {Timeout, Tlabel,} [OutputData]

Function

Transmit asynchronous serial data (e.g., RS-232 data).

• Tpin is a variable/constant/expression* (0 - 16) that specifies the I/O pin through which the serial data will be transmitted. This pin will be set to output mode. On the BS2, BS2e, BS2sx, BS2p, BS2pe, and BS2px, if Tpin is set to 16, the BASIC Stamp uses the dedicated serial-output pin (SOUT, physical pin 1), which is normally used by the Stamp Editor during the download process.
• Fpin is an optional variable/constant/expression* (0 - 15) that specifies the I/O pin to monitor for flow control status. This pin will be set to input mode. NOTE: Fpin must be specified to use the optional Timeout and Tlabel arguments in the SEROUT command.
• Baudmode is variable/constant/expression* (0 - 7 on the BS1, 0 - 65535 on all other BASIC Stamp models) that specifies serial timing and configuration.
• Pace is an optional variable/constant/expression (0 - 65535) that determines the length of the pause between transmitted bytes. NOTE: Pace cannot be used simultaneously with Timeout.
• Timeout is an optional variable/constant/expression* (0 - 65535) that tells SEROUT how long to wait for Fpin permission to send. If permission does not arrive in time, the program will jump to the address specified by Tlabel. NOTE: Fpin must be specified to use the optional Timeout and Tlabel arguments in the SEROUT command.
• Tlabel is an optional label that must be provided along with Timeout. Tlabel indicates where the program should go in the event that permission to send data is not granted within the period specified by Timeout.
• OutputData‡ is a list of variables, constants, expressions and formatters that tells SEROUT how to format outgoing data. SEROUTcan transmit individual or repeating bytes, convert values into decimal, hex or binary text representations, or transmit strings of bytes from variable arrays. These actions can be combined in any order in the OutputData list.

* Note: expressions are not allowed as arguments on the BS1. The range of the Pin argument on the BS1 is 0–7.

‡Note: The BS1's OutputData argument can only be a list of variables and the optional decimal modifier (#).

Quick Facts

Explanation

One of the most popular forms of communication between electronic devices is serial communication. There are two major types of serial communication; asynchronous and synchronous. The SERIN and SEROUT commands are used to receive and send asynchronous serial data. See the SHIFTIN and SHIFTOUT commands for information on the synchronous method.

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.

The following information is supplemental to what is discussed in the SERIN command section. Please read through the SERIN command section for additional information.

All BASIC Stamp models (except the BS1) have a line driver on its SOUT pin (Tpin = 16). The SOUT pin goes to a PC's serial data-in pin on the DB-9 connector built into BASIC Stamp development boards. The connector is wired to allow both programming and run-time serial communication (unless you are using the Stamp 2 Carrier Board which is only designed for programming). For the built-in serial port set the Tpin argument to 16 in the SEROUT command.

All BASIC Stamp models (including the BS1) can also transmit RS-232 data through any of their I/O pins (Tpin = 0 - 7 for BS1, Tpin = 0 - 15 on all other BASIC Stamp models). The I/O pins only provide a 0 to +5 volt swing (outside of RS-232 specs) and may need to be connected through a line driver for proper operation with all serial ports. Most serial ports are able to recognize a 0 to +5 volt swing, however. See the figure below sample wiring.

Note: The connections shown in red are normally not necessary. They indicate optional connections to defeat hardware handshaking requirements.

Note: A line driver may have to be used between the I/O pin and the receiving serial port to ensure proper communication.

The figure above shows the pinouts of the two styles of PC serial ports and how to connect them to the BASIC Stamp's I/O pin. Though not normally needed, the figure also shows loop back connections that defeat hardware handshaking used by some PC software. Note that PC serial ports are always male connectors. The 25-pin style of serial port (called a DB-25) looks similar to a printer (parallel) port except that it is male, whereas a parallel port is female.

Asynchronous serial communication relies on precise timing. Both the sender and receiver must be set for identical timing, usually expressed in bits per second (bps) called baud.

On all BASIC Stamp models, SEROUT requires a value called Baudmode that tells it the important characteristics of the outgoing serial data; the bit period, number of data and parity bits, and polarity.

On the BS1, serial communication is limited to: no-parity, 8-data bits and 1-stop bit at one of four different speeds: 300, 600, 1200 or 2400 baud. The table below indicates the Baudmode value or symbols to use when selecting the desired mode.

On the BS2, BS2e, BS2sx, BS2p, BS2pe, and BS2px, serial communication is very flexible. The Baudmode argument for SEROUT accepts a 16-bit value that determines its characteristics: 1-stop bit, 8-data bits/no-parity or 7-data bits/even-parity and virtually any speed from as low as 300 baud to greater than 100K baud (depending on the BASIC Stamp). The information below shows how Baudmode is calculated and show common baud modes for standard serial baud rates.

Baudmode Calculation:

1. Determine the bit period (bits 0 - 11)
   • BS2, BS2e, and BS2pe = INT(1,000,000 ÷ baud rate) - 20
   • BS2sx and BS2p = INT(2,500,000 ÷ baud rate) - 20
   • BS2px = INT(4,000,000 ÷ baud rate) - 20
     Note: INT means 'Convert to integer.' -- drop the numbers to the right of the decimal point.
2. Set data bits and parity (bit 13)
   • 8-bit / No Parity = 0 ($0000)
   • 7-bit / Even Parity = 8192 ($2000)
3. Select polarity bit (bit 14)
   • True = 0 ($0000)
   • Inverted = 16384 ($4000)
4. Select driven or open output (bit 15)
   • Driven = 0 ($0000)
   • Open = 32768 ($8000)

Common Baud Rates and Corresponding Baudmode Values

BS2, BS2e, BS2pe

BS2sx, BS2p

BS2px

Tip:   For "open" baudmodes used in networking, add 32768 ($8000) to the values from the tables above. If the dedicated serial port (Tpin = 16) is used the data is inverted and driven regardless of the Baudmode setting.

If you're communicating with existing software or hardware, its speed(s) and mode(s) will determine your choice of baud rate and mode. See the SERIN command description for more information.

The example below will transmit a single byte through I/O pin 1 at 2400 baud, 8N1, inverted:

  SEROUT 1, N2400, (65)

  SEROUT 1, 16780, [65]                         ' baudmode set for BS2/e/pe

  SEROUT 1, 17405, [65]                         ' baudmode set for BS2sx/p

Here, SEROUT will transmit a byte equal to 65 (the ASCII value of the character "A") through pin 1. If the BASIC Stamp were connected to a PC running a terminal program (set to the same baud rate) the character "A" would appear on the screen.

What if you really wanted the value 65 to appear on the screen? If you remember from the discussion in the SERIN command, "It is up to the receiving side (in serial communication) to interpret the values..." In this case, the PC is interpreting the byte-sized value to be the ASCII code for the character "A". Unless you're also writing the software for the PC, you can't change how the PC interprets the incoming serial data, so to solve this problem, the data needs to be translated before it is sent.

The SEROUT command provides a formatter, called the decimal formatter, which will translate the value 65 to two ASCII codes for the characters "6" and "5" and then transmit them. Look at the following code:

  SEROUT 1, N2400, (#65)

  SEROUT 1, 16780, [DEC 65]

  SEROUT 1, 17405, [DEC 65]

Notice the decimal formatter in the SEROUT command. It is the "#" (for the BS1) or "DEC" (for the other BASIC Stamp models) that appears just to the left of the number 65. This tells SEROUT to convert the number into separate ASCII characters which represent the value in decimal form. If the value 65 in the code were changed to 123, the SEROUT command would send three bytes (49, 50 and 51) corresponding to the characters "1", "2" and "3".

The BS2, BS2e, BS2sx, BS2p, BS2pev and BS2px have many more conversion formatters available for the SEROUT command. See below for more information.

The SEROUT command sends quoted text exactly as it appears in the OutputData list:

  SEROUT 1, N2400, ("HELLO", CR)
  SEROUT 1, N2400, ("Num = ", #100)

  SEROUT 1, 16780, ["HELLO", CR]
  SEROUT 1, 16780, ["Num = ", DEC 100]

  SEROUT 1, 17405, ["HELLO", CR]
  SEROUT 1, 17405, ["Num = ", DEC 100]

The above code will display "HELLO" on one line and "Num = 100" on the next line. Notice that you can combine data to output in one SEROUT command, separated by commas. In the example above, we could have written it as one line of code, with "HELLO", CR, "Num = ", DEC 100 in the OutputData list.

The BS1's SEROUT command is limited to above-mentioned features. If you are not using a BS1, please continue reading about the additional features below.

The SEROUT command can also be configured to pause between transmitted bytes. This is the purpose of the optional Pace argument. For example (9600 baud N8, inverted):

  SEROUT 1, 16468, 1000, ["Slowly"]             ' baudmode set for BS2

Here, the BASIC Stamp transmits the word "Slowly" with a 1 second delay between each character. See the table above for units of the Pace argument. One good reason to use the Pace feature is to support devices that require more than one stop bit. Normally, the BASIC Stamp sends data as fast as it can (with a minimum of 1 stop bit between bytes). Since a stop bit is really just a resting state in the line (no data transmitted), using the Pace option will effectively add multiple stop bits. Since the requirement for 2 or more stop bits (on some devices) is really just a "minimum" requirement, the receiving side should receive this data correctly.

Keep in mind that when we type something like "XYZ" into the SEROUT command, the BASIC Stamp actually uses the ASCII codes for each of those characters for its tasks. We could also typed: 88, 89, 90 in place of "XYZ" and the program would run the same way since 88 is the ASCII code for the "X" character, 89 is the ASCII code for the "Y" character, and so on.

The decimal formatter is only one of a whole family of conversion formatters available with SEROUT on the BS2, BS2e, BS2sx, BS2p, BS2pe, and BS2px. See the table below for a list of available conversion formatters. All of the conversion formatters work similar to the decimal formatter. The formatters translate the value into separate bytes of data until the entire number is translated or until the indicated number of digits (in the case of the fixed length formatters) is translated.

1. Fixed-digit formatters like DEC4 will pad the number with leading 0s if necessary; ex: DEC4 65 sends 0065. If a number is larger than the specified number of digits, the leading digits will be dropped; ex: DEC4 56422 sends 6422.
2. Signed modifiers work under two's complement rules.

The BS2, BS2e, BS2sx, BS2p, BS2pe, and BS2px also have special formatters for outputting a string of characters, repeated characters and undesirable characters.

The string formatter is useful for transmitting a string of characters from a byte array variable. A string of characters is a set of characters that are arranged or accessed in a certain order. The characters "ABC" could be stored in a string with the "A" first, followed by the "B" and then followed by the "C." A byte array is a similar concept to a string; it contains data that is arranged in a certain order. Each of the elements in an array is the same size. The string "ABC" could be stored in a byte array containing three bytes (elements).

Here is an example that transmits five bytes (from a byte array) through I/O pin 1 at 9600 bps, N81/inverted:

serStr  VAR     Byte(5)                         ' Make a 5-byte array. 

Main:
  serStr(0) = "H"                    
  serStr(1) = "E"
  serStr(2) = "L"
  serStr(3) = "L"
  serStr(4) = "O"

  SEROUT 1, 16468, [STR serStr\5]               ' Send 5-byte string

Note that we use the optional \L argument of STR. If we didn't specify this, the BASIC Stamp would try to keep sending characters until it found a byte equal to 0. Since we didn't specify a last byte of 0 in the array, we chose to tell it explicitly to only send 5 characters.

Parity is a simple error-checking feature. When the SEROUT command's Baudmode is set for even parity it counts the number of 1s in the outgoing byte and uses the parity bit to make that number even. For instance, if it is sending the 7-bit value: %0011010, it sets the parity bit to 1 in order to make an even number of 1s (four).

The receiver also counts the data bits to calculate what the parity bit should be. If it matches the parity bit received, the serial receiver assumes that the data was received correctly. Of course, this is not necessarily true, since two incorrectly received bits could make parity seem correct when the data was wrong, or the parity bit itself could be bad when the rest of the data was OK. Parity errors are only detected on the receiver side. Generally, the receiver determines how to handle the error. In a more robust application, the receiver and transmitter might be set up such that the receiver can request a re-send of data that was received with a parity error.

When you design an application that requires serial communication between BASIC Stamp modules, you have to work within these limitations:

• When the BASIC Stamp is sending or receiving data, it can't execute other instructions.
• When the BASIC Stamp is executing other instructions, it can't send or receive data. The BASIC Stamp does not have a serial buffer as there is in PCs. At most serial rates, the BASIC Stamp cannot receive data via SERIN, process it, and execute another SERIN in time to catch the next chunk of data, unless there are significant pauses between data transmissions.

These limitations can sometimes be addressed by using flow control; the Fpinoption for SERIN and SEROUT (at baud rates of up to the limitation shown above). Through Fpin, SERIN can tell a BASIC Stamp sender when it is ready to receive data and SEROUT (on the sender) will wait for permission to send. (For that matter, Fpin flow control follows the rules of other serial handshaking schemes, but most computers other than the BASIC Stamp cannot start and stop serial transmission on a byte-by-byte basis. That's why this discussion is limited to communication between BASIC Stamp modules.)

Here's an example using flow control on the BS2 (data through I/O pin 1, flow control through I/O pin 0, 9600 baud, N8, non-inverted):

sData   VAR     Byte

Main:
  SEROUT 1\0, 84, [sData]                       ' baudmode set for BS2

When SEROUT executes, I/O pin 1 (Tpin) is made an output, and I/O pin 0 (Fpin) is made an input, to wait for the "go" signal from the receiver. Here's the relationship of serial polarity to Fpin states.

See the SEROUT Examples for a flow control example using two BS2s. In the demo program example, without flow control, the sender would transmit the whole word "HELLO!" in about 6 ms. The receiver would catch the first byte at most; by the time it got back from the first 1-second PAUSE, the rest of the data would be long gone. With flow control, communication is flawless since the sender waits for the receiver to catch up.

In the figure below, I/O pin 0, Fpin, is pulled to ground through a 10 kΩ resistor. This is to ensure that the sender sees a stop signal (0 for inverted communications) when the receiver is being programmed.

In the flow control examples above, the only way the SEROUT instruction will end (other than RESET or power-off) is if the receiver allows it to send the entire OutputData list. If Fpin permission never occurs, the program is stuck. However, you can tell the BASIC Stamp to abort SEROUT if it doesn't receive Fpin permission within a specified time period. For instance, to transmit a decimal number through pin 1 at 9600 baud, 8N, inverted and abort SEROUT after 2 seconds (2000 ms) if no Fpin permission arrives on I/O pin 0:

Main:
  SEROUT 1\0, 16468, 2000, No_Permission, [DEC 150]
  STOP

No_Permission: 
  DEBUG CLS, "Timed out"
  STOP

If no Fpin permission arrives within 2 seconds, the program aborts SEROUT and continues at the label NoPermission.

The SEROUT command supports open-drain and open-source output, which makes it possible to network multiple BASIC Stamp modules on a single pair of wires. These "open baudmodes" only actively drive the Tpin in one state (for the other state, they simply disconnect the pin; setting it to an input mode). If two BASIC Stamp modules in a network had their SEROUT lines connected together (while a third device listened on that line) and the BASIC Stamp modules were using always-driven baudmodes, they could simultaneously output two opposite states (i.e., +5 volts and ground). This would create a short circuit. The heavy current flow would likely damage the I/O pins or the BASIC Stamp modules themselves. Since the open baudmodes only drive in one state and float in the other, there's no chance of this kind of short.

The polarity selected for SEROUT determines which state is driven and which is open as shown below:

Since open baudmodes only drive to one state, they need a resistor to pull the networked line into the other state, as shown in the table above and the figures below.

Open baudmodes allow the BASIC Stamp to share a line, but it is up to your program to resolve other networking issues such as who talks when and how to detect, prevent and fix data errors.

SEROUT Open-Drain circuit:

SEROUT Open-Source circuit:

SEROUT Troubleshooting

Serial communication, because of its complexity, can be very difficult to work with at times. Please follow these guidelines when developing a project using the SERIN and SEROUT commands:

1. Always build your project in steps.
   1. Start with small, manageable pieces of code, that deals with serial communication) and test them, one at a time.
   2. Add more and more small pieces, testing them each time, as you go.
   3. Never write a large portion of code that works with serial communication without testing its smallest workable pieces first.
2. Pay attention to timing.
   1. Be very careful to calculate and overestimate the amount of time operations should take within the BASIC Stamp. Misunderstanding the timing constraints is the source of most problems with code that communicate serially.
   2. If the serial communication in your project is bidirectional, the above statement is even more critical.
3. Pay attention to wiring.
   1. Take extra time to study and verify serial communication wiring diagrams. A mistake in wiring can cause strange problems in communication, or no communication at all. Make sure to connect the ground pins (Vss) between the devices that are communicating serially.
4. Verify port setting on the PC and in the SERIN/SEROUT commands.
   1. Unmatched settings on the sender and receiver side will cause garbled data transfers or no data transfers. If the data you receive is unreadable, it is most likely a baud rate setting error.
5. If data transmitted to the Stamp Editor's Debug Terminal is garbled, verify the output format.
   1. A common mistake is to send data with SEROUT in ASCII format. For example, SEROUT 16, 84, [ 0 ] instead of SEROUT 16, 84, [ DEC 0 ]. The first example will send a byte equal to 0 to the PC, resulting in the DEBUG Terminal clearing the screen (since 0 is the control character for a clear-screen action).
6. When using a BS2-family module, you can simplify Baudmode parameter selection by using conditional compilation. The example below can be included in the standard programming template and will handle most serial IO requirements. Remember that defining constants does not affect compiled program space, and yet does make program debugging easier.

' {$PBASIC 2.5}  

#SELECT $STAMP
  #CASE BS2, BS2E, BS2PE
    T1200       CON     813
    T2400       CON     396
    T4800       CON     188
    T9600       CON     84
    T19K2       CON     32
    T38K4       CON     6
  #CASE BS2SX, BS2P
    T1200       CON     2063
    T2400       CON     1021
    T4800       CON     500
    T9600       CON     240
    T19K2       CON     110
    T38K4       CON     45
  #CASE BS2PX
    T1200       CON     3313
    T2400       CON     1646
    T4800       CON     813
    T9600       CON     396
    T19K2       CON     188
    T38K4       CON     84
#ENDSELECT

SevenBit        CON     $2000
Inverted        CON     $4000
Open            CON     $8000

Baud            CON     T9600 + Inverted        ' match DEBUG