POLLOUT

Syntax: POLLOUT Pin, State

Function

Specify a polled-output pin and active state.

• Pin is a variable/constant/expression (0 - 15) that specifies the I/O pin to use. This I/O pin will be set to output mode.
• State is a variable/constant/expression (0 - 1) that specifies whether to set the I/O pin low (0) or high (1) when a polled-input pin changes to its poll state.

Quick Facts

Explanation

The POLLOUT command is one of a family of unique "polling" commands on the BS2p, BS2pe, and BS2px modules. The other commands in this family include POLLIN, POLLMODE, POLLRUN and POLLWAIT. The POLLOUT command is used to specify an output pin that changes states in response to changes on any of the defined polled-input pins. This activity will occur in between instructions during the rest of the PBASIC program.

The "polling" commands allow the BASIC Stamp to respond to certain I/O pin events at a faster rate than what is normally possible through manual PBASIC programming. The term "poll" comes from the fact that the BASIC Stamp's interpreter periodically checks the state of the designated polled-input pins. It "polls" these pins after the end of each PBASIC instruction and before it reads the next PBASIC instruction from the user program; giving the appearance that it is polling "in the background".

This feature should not be confused with the concept of interrupts, as the BASIC Stamp does not support true interrupts.

The POLLOUT command achieves one of three possible actions in response to a polled-input event. This command works in conjunction with the POLLIN and POLLMODE commands. The following is an example of the POLLOUT command:

Setup:
  POLLIN 0, 0
  POLLOUT 1, 1
  POLLMODE 2

Main:
  DEBUG "Looping...", CR
  GOTO Main

In this example, the POLLOUT command tells the BASIC Stamp to set I/O pin 1 to an output mode and set it high (1) when it detects the desired poll state. The poll state is the low (0) level on I/O pin 0 that POLLIN told it to look for. If the polled-input pin is high, the BASIC Stamp will set polled-output pin 1 to low (0), instead. The BASIC Stamp will not actually start polling until it is set to the appropriate mode, however. The third line, POLLMODE, initiates the polling process (see the POLLMODE description for more information). From then on, as the BASIC Stamp executes the rest of the program, it will check for a low level (logic 0) on I/O pin 0 in between instructions.

Once the program reaches the endless loop, at Main, it will continuously print "Looping...." on the PC screen. In between reading the DEBUG command and the GOTO command (and vice versa) it will check polled-input pin 0 and set polled-output pin 1 accordingly. In this case, when I/O pin 0 is set low, the BASIC Stamp will set I/O pin 1 high. When I/O pin 0 is set high, the BASIC Stamp will set I/O pin 1 low. It will continue to perform this operation, in between each command in the loop, endlessly.

It's important to note that in this example only the DEBUG and GOTO commands are being executed over and over again. The first three lines of code are only run once, yet their effects are "remembered" by the BASIC Stamp throughout the rest of the program.

If the polling commands were not used, the program would have to look like the one below in order to achieve the same effect.

Setup:
  INPUT 0
  OUTPUT 1

Main:
  OUT1 = ~IN0
  DEBUG  "Looping...", CR
  OUT1 = ~IN0
  GOTO Main

In this example, we create the inverse relationship of input pin 0 and output pin 1 manually, in-between the DEBUG and GOTO lines. Though the effects are the same as when using the polling commands, this program actually takes a little longer to run and consumes 7 additional bytes of program (EEPROM) space. Clearly, using the polling commands is more efficient.

You can have as many polled-input and polled-output pins as you have available. If multiple polled-input pins are defined, any one of them can trigger changes on the polled-output pins that are also defined. For example:

Setup:
  POLLIN 0, 1
  POLLIN 1, 1
  POLLOUT 2, 1
  POLLMODE 2

Main:
  DEBUG "Looping...", CR
  GOTO Main

This code sets I/O pins 0 and 1 to polled-input pins (looking for a high (1) state) and sets I/O pin 2 to be a polled-output pin (with a high-active state). If either I/O pin 0 or 1 goes high, the BASIC Stamp will set I/O pin 2 high. This works similar to a logical OR operation. The truth table below shows all the possible states of these two polled-input pins and the corresponding states the BASIC Stamp will set the polled-output pin to.

Normally, any polled-output pins reflect the state changes continuously, as described above. The POLLMODE command supports another feature, however, where the polled-output pins will latch the active state; they will change only once (when the poll state is reached) and stay in the new state until the PBASIC program tells it to change again. See the POLLMODE description for more information.

A clever use of the "latched" feature is to set a polled-output to be the same as the polled-input. For example, suppose an application needed to respond in some way if a polled-input pin goes high, but it doesn't need to respond immediately, and the other tasks should not be interrupted. In essence, we need a way to know if the pin has gone high since the last time we checked it. Look at this example:

idx     VAR     Byte

Setup:
  POLLOUT 0, 1                          ' pin 0 is polled-output, high
  POLLIN 0, 1                           ' pin 0 back to polled-input, high
  POLLMODE 10                           ' Set mode to latch the polled-output

Work:                                   ' kill time waiting for polled 
  FOR idx = 1 TO 20                     '   event
    DEBUG  "Working....", CR        
  NEXT
  IF (OUT0 = 0) THEN Work

Respond:                                ' Response message
  DEBUG CR, 
        "You set my pin high!", CR
  POLLMODE 10                           ' Reset polled-output's latch function
  GOTO Work

Here, we set I/O pin 0 to a polled-output, then immediately set it to a polled-input. Then we set the polled-mode to latch the polled-outputs. Since the POLLIN command occurred after the POLLOUT, I/O pin 0 will be an input, but the polling feature will still affect the OUT0 bit (output latch for I/O pin 0). Then, the program performs some work, and once in a while, checks the state of OUT0. If OUT0 is 0, I/O pin 0 was never seen to go high. If, however, OUT0 is 1, I/O pin 0 must have gone high while the program was doing other work, and now it can respond in the proper manner. This even works if the pin had gone high and then low again before we check it (as long as it was high at some point in between the instructions in our Work routine.

It is important to note that during the time between the POLLOUT and POLLIN commands, I/O pin 0 will be set to an output direction. This can cause a temporary short with the circuitry connected to I/O pin 0, so it is vital that a large enough series resister (perhaps 220 ohms or greater) be inserted on that pin to protect the external device and the BASIC Stamp.