Add physical buttons to OctoPrint

The PhysicalButton plugin (hence the name) lets you add physical buttons to your Raspberry Pi. The buttons are then able to send GCODE, actions and system commands to your printer.

The buttons have to be plugged into a ground pin and the desired GPIO pin that you want to use. The GPIO must be chosen in BCM mode (see If you have other plugins installed that use GPIOs, make sure those plugins are also set to BCM mode.

🔧 Configuration - Overview 🔧

To add a new button you have to click on the ➕. This adds a new button to the end of your list.

From there you should enter a button name, the used GPIO and the mode (NO or NC) of the button. In addition, you have to specify for how long a button has to be held in order to trigger.

The last step is to add activities to your button which are executed in order of the activities list. You can edit, move or remove activities in the right pane.

You can disable/enable buttons by pressing / .

You can back up your configuration by pressing ( Config) and import a configuration by pressing ( Config).

🔧 Configuration - Detail 🔧

  • Button Name
    • This is where you put the name of your button to differentiate it in the list of buttons.
  • GPIO
    • This is the GPIO you connect your button to. The other cable has to be connected to a ground pin (Buttons are configured to use internal pulled-up resistors).
  • Mode
    • Depending on your button setup or wiring you have to choose between the following two modes:
      • Normally Open (NO)
        • Use this mode if your button is usually not pressed (open).
      • Normally Closed (NC)
        • Use this mode if your button is usually pressed (closed).
  • Hold Time
    • This is where you set the hold time for your button, meaning how long the button has to be held until the reaction is triggered.
  • Enabled while printing
    • When this option is enabled, you can always use the button. If it’s disabled, the button won’t react to input while the printer is printing.
  • Choose activities for your button
    • Action:
      • You can choose between different actions:
        • connect:
          • Connect to the printer.
        • disconnect
          • Disconnect from the printer.
        • home
          • Homes all axes of the printer.
        • pause
          • Pause the current print.
        • resume
          • Resume the current print.
        • start
          • Start printing the currently selected file.
        • start latest
          • Start printing the latest uploaded file.
        • cancel
          • Cancel the current print.
        • toggle pause-resume
          • Toggle between pausing and resuming a print.
        • toggle start-cancel
          • Toggle between starting the currently selected file or cancelling a print.
        • toggle start latest-cancel
          • Toggle between starting the latest uploaded file and cancelling a print.
        • unselect file
          • Unselect the currently selected file.
    • File:
      • You can specify the path to a file which will be selected.
      • To start the execution of a file, add ‘start action’ behind the ‘file activity’.
      • There are three ways to specify a file:
        • Absolute path to a file:
        • Relative path to a file inside the uploads folder:
        • Path to a file on the SD-card of the printer:
    • GCODE:
      • You can input any GCODE commands.
    • System:
      • You can input any system command for your Octoprint host.
        Note that system commands will be run under the same user that owns your OctoPrint service (usually ‘pi’ for OctoPi) with the same rights and permissions, so you may need to use sudo facilities for certain tasks. Please refer to your OctoPrint host’s documentation for details.
    • Output:
      • Generate output on the given GPIO pin for a given amount of time.
      • By setting the time to 0, the output will continue until you toggle it again.
      • The async option lets the output run while also continuing with the next activities.
      • The initial value sets the level of the GPIO pin for startup and settings save.
    • Plugin:
      • This activity works in a similar way as the action activity.
      • This activity will only appear if other plugins provide actions for this plugin.
    • These activities will be executed in order of your list. You can also rearrange them by inserting them at your desired position.


You can only configure one button per GPIO. If you want more activities to be activated upon button press (/release), add more activities to the button.

Custom actions from your plugin:

If you are a developer and want to include functionality of your plugin into PhysicalButton, you can proceed as follows:

  • To get the function to register actions:
    helpers = self._plugin_manager.get_helpers("physicalbutton", "register_button_actions")
    if helpers and "register_button_actions" in helpers:
     self.register_button_actions = helpers["register_button_actions"]
  • To register actions use self.register_button_actions(self, some_action_callback_dict) with:
    • some_action_callback_dict being a dictionary with structure {some_action : some_callback, ...}.
      • some_action being a string with the name that should be displayed.
      • some_callback being a function without parameters that is executed on a button press.

Get Help / Feature request

If you encounter problems using the plugin or if you have an idea for a new feature please use the issue tracker and if applicable add the corresponding label.

⚠️ Use at your own risk ⚠️

I am not accountable for any damages made to your printer/raspberry pi when using this plugin (e.g. wrong wiring of buttons, GCODE or system commands that you send with the buttons to your printer, …).

When setting the plugin up corresponding to my instructions, nothing should happen.

❤️ Support me ❤️

If you enjoy my plugin and want to support me and the development, you can do so by sending me a donation on

paypal  ko-fi


Image that shows an output activity of a button.
Image that shows an action activity of a button.
Image that shows a gcode activity of a button.
Image that shows a system activity of a button.
Image that shows a file activity of a button.
Image that shows a plugin activity of a button.
Image that shows a modal to confirm the deletion of a configured button.
Image that shows a modal to upload a configuration/backup file.