BUTTON pin,downstate,delay,rate,bytevariable,targetstate,address

Pin - is a variable/constant which specifies the i/o pin to use.

Downstate - is a variable/constant (0 or 1) which specifies which logical state is read when the button is pressed. If the input is active high, at V+ when the button is pressed (e.g. a 10k pull down resistor with switch wired to V+) then enter 1 here. If the input is active low, at 0V when the button is pressed (e.g. a 10k pull up resistor with switch wired to 0V) then enter 0.

Delay - is a variable/constant (1-254, 0 or 255) which is a counter which specifies the number of loops to complete before the auto repeat feature starts if BUTTON is used within a loop. If the value is between 1 and 254 this value will be loaded into the bytevariable when the switch becomes active, and then decremented on every loop whilst the button is still active. Only when the counter reaches 0 will the address be processed for the second time. This gives an initial delay before the auto-repeat starts. A value of 255 disables the auto-repeat feature. The button will still be debounced, so use the value 255 when you want a simple debounce feature without auto repeat. A value of 0 disables both the debounce and auto-repeat features. Therefore with delay=0 the command will operate as a simple 'if pin = targetstate then' command.

Rate - is a variable/constant (0-255) which specifies the auto-repeat rate in BUTTON cycles. After the initial delay this value will be loaded into the bytevariable, and then decremented on every loop whilst the button is still active. Only when the value reaches 0 will the address be processed again. This gives the delay between every auto-repeat cycle.

Bytevariable - is a variable which is used as the workspace for the auto repeat loop counters. It must be cleared to 0 before being used by BUTTON for the first time (before the loop that BUTTON is used within.)

Targetstate - is a variable/constant (0 or 1) which specifies what state (0=not pressed, 1=pressed) the button should be in for the branch (goto) to address to occur. This value can be used to 'invert' the operation of the address jump, jumping when either pushed (1) or when not pushed (0).

Address - is a label which specifies where to go if the button is in the target state.

Debounce button, auto-repeat, and branch if button is in target state. When mechanical switches are activated the metal 'contacts' do not actually close in one smooth action, but 'bounce' against each other a number of times before settling. This can cause microcontrollers to register multiple 'hits' with a single physical action, as the microcontroller can register each bounce as a new hit

One simple way of overcoming this is to simply put a small pause (e.g. pause 10) within the program, this gives time for the switch to settle.

Alternately the button command can be used to overcome these issues. When the button command is executed, the microcontroller looks to see if the 'downstate' is matched. If this is true the switch is debounced, and then program flow jumps to 'address' if 'targetstate' = 1. If targetstate = '0' the program continues. If the button command is within a loop, the next time the command is executed 'downstate' is once again checked. If the condition is still true, the variable 'bytevariable' is loaded with the 'delay' value. On each subsequent loop where the condition is still true bytevariable is decremented until it reaches 0. At this point a second jump to 'address' is made if 'targetstate' = 1. Bytevariable is then reset to the 'rate' value and the whole process then repeats, as once again on each loop bytevariable is decremented until it reaches 0, and at 0 another jump to 'address' is made if 'targetstate' = 1.

This gives action like a computer keyboard key press - send one press, wait for 'delay' number of loops, then send multiple presses at time interval 'rate'. Note that button should be used within a loop. It does not pause program flow and so only checks the input switch condition as program flow passes through the command.