Button

This library implements debouncing for buttons connected to an imp. It requires just two lines of code in your device firmware: one to require the library, the second to instantiate the class. Instantiation involves providing callback functions that will be executed, respectively, when the button is pressed and then released. The class automatically handles bounces, ensuring your callbacks are only run when the button has been intentionally pressed and released.

You can view the library’s source code on GitHub. Click here to see information on the available versions of this library.

To add this library to your project, add #require "Button.class.nut:1.2.0" to the top of your device code

Class Usage

Constructor: Button(pin, pull[, polarity][, pressCallback][, releaseCallback])

The Button constructor has two required parameters — pin and pull — and three optional parameters: polarity, pressCallback and releaseCallback.

• pin — The unconfigured imp pin object the button is wired to (eg. hardware.pin1).
• pull — The impOS™ constant used to configure the digital input used to read the button’s state (DIGITAL_IN, DIGITAL_IN_PULLDOWN, DIGITAL_IN_PULLUP or DIGITAL_IN_WAKEUP).
• polarity — The unpressed button state (Button.NORMALLY_HIGH or Button.NORMALLY_LOW). If this parameter is not passed to the constructor, it will be inferred from the pull parameter:
  • DIGITAL_IN -> Button.NORMALLY_HIGH
  • DIGITAL_IN_PULLUP -> Button.NORMALLY_HIGH
  • DIGITAL_IN_PULLDOWN -> Button.NORMALLY_LOW
  • DIGITAL_IN_WAKEUP -> Button.NORMALLY_LOW
• pressCallback — The callback function to be executed when the button is pressed.
• releaseCallback — The callback function to be executed when the button is released.

Neither callback function should include any parameters:

#require "Button.class.nut:1.2.0"

// Button on pin7
button <- Button(hardware.pin7, DIGITAL_IN_PULLUP, Button.NORMALLY_HIGH,
    function() {
        server.log("Button pressed");
    }
);

Class Methods

onPress([callback])

The onPress() method sets the callback for the button’s onPress event (ie. when the button is depressed). If an onPress callback function is already registered, it will be replaced with the new callback. Setting the callback to null (or passing no reference) will result in no action being taken when the button is pressed. This is the default behavior.

button.onPress(function() {
    server.log("Button Pressed!");
});

onRelease([callback])

The onRelease() method sets the callback for the button’s onRelease event (ie. when the button is released). If an onRelease callback function is already registered, it will be replaced with the new callback. Setting the callback to null (or passing no reference) will result in no action being taken when the button is released. This is the default behavior.

button.onRelease(function() {
    server.log("Button Released!");
});

Method Chaining

All methods return the this, the instance of the instantiated object. This allows method chaining as shown below:

Button(hardware.pin1, DIGITAL_IN_WAKEUP)
.onPress(function() {
    server.log("Pressed");
}).onRelease(function() {
    server.log("Released.. going to sleep");
    imp.onidle(function() { server.sleepfor(3600); });
});

Release History

The Electric Imp Dev Center documents the latest version of the library. For past versions, please see the Electric Imp public GitHub repos listed below.

Version	Source Code	Notes
1.1.0	GitHub	Initial release
1.1.1	GitHub	Minor code changes
1.2.0	GitHub	onRelease() and onPress() callback parameters now optional

License

The Button library is licensed under the MIT License.