Search

The Bela button

The button on the Bela cape can be used to trigger actions without needing external components or controllers. On this page we look at its default behaviour and how to customise it.

Table of contents

  1. Default behaviour
  2. Custom behaviour
    1. Bela image v0.3 and above:

Default behaviour

By default, the button can respond to a short tap (“click”), when pressed for less than 2 seconds, or a “hold”, when pressed for more than 2 seconds.

  • click: while the Bela program is running, this stops it immediately. While the Bela program is not running, this does nothing.
  • hold: initiates a graceful shutdown of the board, which takes a few seconds to complete.

Custom behaviour

Sometimes you may want to disable or customize the behaviour of the Bela button, e.g.: you want to trigger customized actions, you are using that pin for other purposes, one dtb overlay you are loading causes the pin to trigger unexpected shutdowns …

The behaviour of the “click” while the Bela program is running is handled within the Bela program itself and can be disabled by running the Bela program with --disable-cape-button-monitoring. The other behaviours are triggered by a service running the program /usr/local/bin/bela-cape-btn (source code is here: use /usr/local/bin/bela-cape-btn --help to see usage options.

The way you customize the background service and the location of the files that get executed depends on the Bela image you have.

Bela image v0.3 and above:

The button is managed by the systemd service /lib/systemd/system/bela_button.service. You can disable / enable this with the usual systemctl commands:

systemctl disable bela_button
systemctl enable bela_button

This line in the file /lib/systemd/system/bela_button.service shows the actions for hold and click:

ExecStart=/usr/bin/stdbuf -oL -eL /usr/local/bin/bela-cape-btn --pin 115 --hold /opt/Bela/bela_button_hold.sh --delay 20 --monitor-click 0

“hold” will execute /opt/Bela/bela_button_hold.sh, while “click” is disabled --monitor-click 0). You can customize these actions by editing this line, e.g.: to run /root/customHold and /root/customClick respectively you would use:

ExecStart=/usr/bin/stdbuf -oL -eL /usr/local/bin/bela-cape-btn --pin 115 --hold /root/customHold --delay 20 --click /root/customClick