The plugin adds buttons to control GPIO pins of Raspberry Pi (incl. Pi 5) for switching relays and indicating their states.
In this screenshot, the black printer icon shows the ON
state of its relay, and the gray ones indicate OFF
.
The plugin allows you to set your own icons and flexibly customize the way the relay states are displayed.
I use it with a 4 relay board, and printed this case for it. Just hooked up the GPIO pins with the relay board, and now I can turn the power of the printer, the fan and the light on and off with OctoPrint.
This plugin was based on the OctoLight Plugin by Žiga Kralj, thanks ;-)
— Boris Burgstaller
![]() |
![]() |
---|
3.9
:
4.x
(however it does not support Raspberry Pi 5);1.5.3
:
1.9.0
.Install via the bundled Plugin Manager or manually using this URL:
https://github.com/borisbu/OctoRelay/releases/latest/download/release.zip
In case you want to enable the plugin for user groups other than admins and users (operators), you need to grant them the permission "Relay switching" in the "Access control" section of OctoPrint settings.
After installing the plugin you need to configure it in order to see the control buttons in the navigation bar.
Currently, OctoRelay supports up to 8 relays represented by the tabs on the top of the settings screen. Each relay has the following settings (in order of appearance):
Setting | Description |
---|---|
Active | Activates the relay control and indication on the navigation bar |
Label | The relay description to show on tooltip and in dialogs |
Icon ON / OFF |
An image or emoji to indicate the relay state (supports HTML) |
This is printer relay | Closes the printer connection when turning this relay OFF |
AutoConnect delay | Printer relay feature adjustment when turning it ON |
GPIO Number | The GPIO pin on the Raspberry Pi |
Inverted output | For normally closed relay: the relay is ON without power |
Confirm turning OFF |
Enables a confirmation dialog when turning the relay OFF |
Alert on switches ahead | Notifies on upcoming switch with an ability to cancel it |
Events: | Behavior customization (automation) |
on Startup | The state to switch the relay to when OctoPrint started |
on Printing Started | The state to switch the relay to when started printing |
on Printing Stopped | The state to switch the relay to when stopped printing |
after Turned ON |
The state to switch the relay to after it has been turned ON |
skip (option) | No action should be taken |
delay | Postpones the action for the time specified in seconds |
Side effects: | Additional actions in certain cases |
Command ON / OFF |
An optional OS command to run when toggling the relay |
You can toggle the relays ON and OFF the following ways:
@OCTORELAY r# [ON|OFF]
.
#
is relay index from 1
to 8
;[ON|OFF]
is an optional target.Relays can be queried and updated through the OctoPrint API. Read that documentation on how to get an API Key.
This query turns the relay r1
OFF:
curl 'http://octopi.local/api/plugin/octorelay' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-X POST \
-d '{ "command": "update", "subject": "r1", "target": false }'
# Sample response:
# {
# "status": false
# }
The target
entry in request payload is an optional boolean parameter. When it's null
or omitted the relay will toggle. The status
entry in the response payload reflects the relay state as the outcome of the request.
This query provides the status or the relay r1
:
curl 'http://octopi.local/api/plugin/octorelay' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-X POST \
-d '{ "command": "getStatus", "subject": "r1" }'
# Sample response:
# {
# "status": true
# }
This query provides the statuses of all the relays:
curl 'http://octopi.local/api/plugin/octorelay' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-X POST \
-d '{ "command": "listAllStatus" }'
# Sample response:
# [
# {
# "status": true,
# "id": "r1",
# "name": "Light"
# },
# {
# "status": false,
# "id": "r2",
# "name": "Printer"
# }
# ]
The status
entry reflects the actual state of the relay.
Check out the versions, their features and bug fixes in the Changelog.