{"id":13622470,"url":"https://github.com/borisbu/OctoRelay","last_synced_at":"2025-04-15T09:32:32.956Z","repository":{"id":37974715,"uuid":"347163750","full_name":"borisbu/OctoRelay","owner":"borisbu","description":"OctoPrint / Octopi plugin to control relays","archived":false,"fork":false,"pushed_at":"2025-01-19T15:13:17.000Z","size":5739,"stargazers_count":44,"open_issues_count":8,"forks_count":25,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-19T15:18:44.851Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/borisbu.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-12T18:39:39.000Z","updated_at":"2024-11-25T20:14:08.000Z","dependencies_parsed_at":"2023-09-21T22:59:03.867Z","dependency_job_id":"e719963e-1ab1-4001-8a8a-bc0b167110a9","html_url":"https://github.com/borisbu/OctoRelay","commit_stats":null,"previous_names":[],"tags_count":164,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/borisbu%2FOctoRelay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/borisbu%2FOctoRelay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/borisbu%2FOctoRelay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/borisbu%2FOctoRelay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/borisbu","download_url":"https://codeload.github.com/borisbu/OctoRelay/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249043040,"owners_count":21203402,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T21:01:19.754Z","updated_at":"2025-04-15T09:32:32.020Z","avatar_url":"https://github.com/borisbu.png","language":"Python","readme":"# OctoRelay\n\n[![CI](https://github.com/borisbu/OctoRelay/actions/workflows/CI.yaml/badge.svg)](https://github.com/borisbu/OctoRelay/actions/workflows/CI.yaml)\n[![CodeQL](https://github.com/borisbu/OctoRelay/actions/workflows/codeql.yml/badge.svg)](https://github.com/borisbu/OctoRelay/actions/workflows/codeql.yml)\n[![Coverage Status](https://coveralls.io/repos/github/borisbu/OctoRelay/badge.svg?branch=master)](https://coveralls.io/github/borisbu/OctoRelay?branch=master)\n[![Downloads of latest release](https://img.shields.io/github/downloads/borisbu/octorelay/latest/release.zip?color=blue)](https://github.com/borisbu/OctoRelay/releases/latest)\n\nThe plugin adds buttons to control GPIO pins of Raspberry Pi (incl. Pi 5) for switching relays and indicating their states.\n\n![WebUI interface](img/controls.png)\n\nIn this screenshot, the black printer icon shows the `ON` state of its relay, and the gray ones indicate `OFF`.\nThe plugin allows you to set your own icons and flexibly customize the way the relay states are displayed.\n\n\u003e _I use it with a 4 relay board, and printed this\n\u003e [case for it](https://www.thingiverse.com/thing:2975944)._\n\u003e _Just hooked up the GPIO pins with the relay board, and now I can turn the\n\u003e power of the printer, the fan and the light on and off with OctoPrint._\n\u003e\n\u003e _This plugin was based on the [OctoLight Plugin](https://github.com/gigibu5/OctoLight) by Žiga Kralj, thanks ;-)_\n\u003e\n\u003e — _Boris Burgstaller_\n\n| ![Relay Board](img/relay.jpg) | ![Raspberry Pi GPIO](img/gpio.png) |\n|-------------------------------|------------------------------------|\n\n## Requirements\n\n- Python — at least `3.9` ⚠️\n  - Earlier versions of Python are supported by the plugin version `4.x`;\n  - That version however does not support Raspberry Pi 5;\n  - You can install that version of the plugin manually using this URL in OctoPrint Plugin Manager:\n    `https://github.com/borisbu/OctoRelay/releases/download/4.2.1/release.zip`.\n- OctoPrint — at least `1.5.3`:\n  - For [AutoConnect feature](https://github.com/borisbu/OctoRelay/blob/master/CHANGELOG.md#330) — at least `1.9.0`.\n\n## Setup\n\nInstall via the bundled [Plugin Manager](https://docs.octoprint.org/en/master/bundledplugins/pluginmanager.html)\nor manually using this URL:\n\n```\nhttps://github.com/borisbu/OctoRelay/releases/latest/download/release.zip\n```\n\nIn case you want to enable the plugin for user groups other than admins and users (operators), you need to\ngrant them the permission \"Relay switching\" in the \"Access control\" section of OctoPrint settings.\n\nAfter installing the plugin you need to configure it in order to see the control buttons in the navigation bar.\n\n## Configuration\n\n![Settings panel](img/settings.png)\n\nCurrently, OctoRelay supports up to 8 relays represented by the tabs on the top of the settings screen.\nEach relay has the following settings *(in order of appearance)*:\n\n| Setting                 | Description                                                      |\n|-------------------------|------------------------------------------------------------------|\n| Active                  | Activates the relay control and indication on the navigation bar |\n| Label                   | The relay description to show on tooltip and in dialogs          |\n| Icon `ON` / `OFF`       | An image or emoji to indicate the relay state (supports HTML)    |\n| This is printer relay   | Closes the printer connection when turning this relay `OFF`      |\n| AutoConnect delay       | Printer relay feature adjustment when turning it `ON`            |\n| GPIO Number             | The [GPIO pin on the Raspberry Pi](https://pinout.xyz/)          |\n| Inverted output         | For normally closed relay: the relay is `ON` without power       |\n| Confirm turning `OFF`   | Enables a confirmation dialog when turning the relay `OFF`       |\n| Alert on switches ahead | Notifies on upcoming switch with an ability to cancel it         |\n| **Events:**             | Behavior customization (automation)                              |\n| on Startup              | The state to switch the relay to when OctoPrint started          |\n| on Printing Started     | The state to switch the relay to when started printing           |\n| on Printing Stopped     | The state to switch the relay to when stopped printing           |\n| after Turned `ON`       | The state to switch the relay to after it has been turned `ON`   |\n| skip *(option)*         | No action should be taken                                        |\n| delay                   | Postpones the action for the time specified in seconds           |\n| **Side effects:**       | Additional actions in certain cases                              |\n| Command `ON` / `OFF`    | An optional OS command to run when toggling the relay            |\n\n## Operation\n\nYou can toggle the relays ON and OFF the following ways:\n\n- By clicking the control buttons on the navigation bar.\n  - The icon you choose for the button will display the current state.\n- By sending GCODE command `@OCTORELAY r# [ON|OFF]`.\n  - Where `#` is relay index from `1` to `8`;\n  - While `[ON|OFF]` is an optional target.\n- Or by querying the API (see below).\n\n## OctoRelay API\n\nRelays can be queried and updated through the [OctoPrint API](https://docs.octoprint.org/en/master/api/). Read that documentation on how to get an API Key.\n\n### Change the relay state\n\nThis query turns the relay `r1` OFF:\n\n```bash\ncurl 'http://octopi.local/api/plugin/octorelay' \\\n  -H 'X-Api-Key: YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -X POST \\\n  -d '{ \"command\": \"update\", \"subject\": \"r1\", \"target\": false }'\n\n# Sample response:\n# {\n#   \"status\": false\n# }\n```\n\nThe `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.\n\n### Request the relay state\n\nThis query provides the status or the relay `r1`:\n\n```bash\ncurl 'http://octopi.local/api/plugin/octorelay' \\\n  -H 'X-Api-Key: YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -X POST \\\n  -d '{ \"command\": \"getStatus\", \"subject\": \"r1\" }'\n\n# Sample response:\n# {\n#   \"status\": true\n# }\n```\n\n### List all the relay states\n\nThis query provides the statuses of all the relays:\n\n```bash\ncurl 'http://octopi.local/api/plugin/octorelay' \\\n  -H 'X-Api-Key: YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -X POST \\\n  -d '{ \"command\": \"listAllStatus\" }'\n\n# Sample response:\n# [\n#   {\n#     \"status\": true,\n#     \"id\": \"r1\",\n#     \"name\": \"Light\"\n#   },\n#   {\n#     \"status\": false,\n#     \"id\": \"r2\",\n#     \"name\": \"Printer\"\n#   }\n# ]\n```\n\nThe `status` entry reflects the actual state of the relay.\n\n## Updates\n\nCheck out the versions, their features and bug fixes in the [Changelog](CHANGELOG.md).\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fborisbu%2FOctoRelay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fborisbu%2FOctoRelay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fborisbu%2FOctoRelay/lists"}