POLLIN

Syntax: POLLIN Pin, State

Function

Specify a polled-input 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 input mode.
• State is a variable/constant/expression (0 - 1) that specifies whether to poll the I/O pin for a low (0) or a high (1) level.

Quick Facts

Explanation

The POLLIN command is one of a family of unique "polling" commands on the BS2p, BS2pe, and BS2px modules. The other commands in this family include POLLMODE, POLLOUT, POLLRUN and POLLWAIT. The POLLIN command is used to specify an input pin to monitor, or "poll", in-between instructions during the rest of the PBASIC program. The BASIC Stamp will then perform some activity (in between instructions) when the specified State is detected. The activity performed depends on the POLLMODE, POLLOUT and POLLRUNcommands.

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 following is an example of the POLLIN command:

  POLLIN 0, 0
  POLLMODE 2

The POLLIN command in the above code will cause the BASIC Stamp to set I/O pin 0 to an input mode and get ready to poll it for a low (0) state. The BASIC Stamp will not actually start polling until it is set to the appropriate mode, however. The second 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.

In the code above, no obvious action will be noticed since we didn't tell the BASIC Stamp what to do when it detects a change on the I/O pin. One possible action the BASIC Stamp can be instructed to take is to change the state of an output, called a polled-output. Take a look at the next example:

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

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

In this example, in addition to an endless loop, we've added another polling command called POLLOUT (see the POLLOUT description for more information). Our 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, it will set polled-output pin 1 to low (0), instead.

Once the program reaches the endless loop, starting 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 GOTOcommands 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.

Other possible actions in response to polled-input states are: 1) Running another program (in a specified program slot), 2) Waiting (pausing program execution with or without low-power mode) until the poll state is reached, or 3) Any combination of the above-mentioned actions