BUTTON

Syntax: BUTTON Pin, DownState, Delay, Rate, Workspace, TargetState, Address

Function

Monitor and process a pushbutton input, perform auto-repeat, and branch to address if button is in target state. Button circuits may be active-low or active-high.

• Pin is a variable/constant/expression* (0 - 15) that specifies the I/O pin to use. This pin will be set to input mode.
• DownState is a variable/constant/expression* (0 or 1) that specifies which logical state occurs when the button is pressed.
• Delay is a variable/constant/expression* (0 - 255) that specifies how long the button must be pressed before auto-repeat starts. The delay is measured in cycles of the BUTTON routine. Delay has two special settings: 0 and 255. If Delay is 0, BUTTON performs no debounce or auto-repeat. If Delay is 255, Button performs debounce, but no auto-repeat.
• Rate is a variable/constant/expression* (0 - 255) that specifies the number of cycles between auto-repeats. The rate is expressed in cycles of the BUTTON routine.
• Workspace is a byte variable used by BUTTON for workspace. It must be cleared to 0 before being used by BUTTON for the first time and should not be adjusted outside of the BUTTON instruction. NOTE: All RAM is cleared to 0 by default upon power-up or reset of the BASIC Stamp.
• TargetState is a variable/constant/expression* (0 or 1) that specifies which state the button should be in for a branch to occur (0=not pressed, 1=pressed).
• Address is a label that specifies where to branch if the button is in the target state.

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

Explanation

When you press a button or flip a switch, the contacts make or break a connection. A brief (1 to 20-ms) burst of noise occurs as the contacts scrape and bounce against each other. By scanning an input within a loop to ensure that the contact remains in a specified state for a minimum duration, spurious multiple inputs caused by contact noise can be eliminated. The BUTTON instruction helps prevent this noise from being interpreted as more than one switch action; this is the function of the Delay parameter. (For a demonstration of switch bounce, see the demo program for the COUNT instruction.) Delay, combined with the Rate parameter, allows the programmer to control the rate at which multiple inputs are accepted by the BASIC Stamp.

BUTTON also lets PBASIC react to a button press the way your computer keyboard does to a key press. When you press a key, a character immediately appears on the screen. If you hold the key down, there's a delay, then a rapid-fire stream of characters appears on the screen. BUTTON's auto-repeat function can be set up to work much the same way.

BUTTON is designed for use inside a program loop. Each time through the loop, BUTTON checks the state of the specified pin. When it first matches DownState, BUTTON begins the Delay countdown for auto-repeat. Then, in accordance with TargetState, it either branches to address (TargetState = 1) or doesn't (TargetState = 0).

If the switch stays in DownState, BUTTON counts the number of program loops that execute. When this count equals Delay, BUTTONonce again triggers the action specified by TargetState and Address. Hereafter, if the switch remains in DownState, BUTTON waits Rate number of cycles between actions. The Workspace variable is used by BUTTON to keep track of how many cycles have occurred since the pin switched to TargetState or since the last auto-repeat.

BUTTON does not stop program execution. In order for its delay and auto repeat functions to work properly, BUTTON must be executed from within a program loop.