https://github.com/agustinmista/positron
Effortlessly control your Home Assistant devices using keyboard shortcuts
https://github.com/agustinmista/positron
alpinejs electron homeassistant shortcuts typescript
Last synced: 8 months ago
JSON representation
Effortlessly control your Home Assistant devices using keyboard shortcuts
- Host: GitHub
- URL: https://github.com/agustinmista/positron
- Owner: agustinmista
- License: mit
- Created: 2023-02-10T23:37:14.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-06-11T19:29:55.000Z (about 2 years ago)
- Last Synced: 2024-06-12T04:26:21.044Z (about 2 years ago)
- Topics: alpinejs, electron, homeassistant, shortcuts, typescript
- Language: TypeScript
- Homepage:
- Size: 1.71 MB
- Stars: 41
- Watchers: 5
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Positron
Create keyboard shortcuts for Home Assistant actions
Positron lets you associate global system shortcuts to requests to a [Home
Assistant](https://www.home-assistant.io/) server. You can use this to toggle
lights, enable scenes, run scripts, read sensors, and pretty much anything Home
Assistant supports!
## Features
* Multiplatform: available for Windows, macOS and Linux (both `deb` and `rpm`
packages).
* Associate keyboard shortcuts to HTTP requests to a Home Assistant server endpoint.
+ Shortcuts are handled directly by Electron, and you can define any
combination of keys supported by its [Accelerator
API](https://www.electronjs.org/docs/latest/api/accelerator).
+ The supported endpoints are described in the Home Assistant [REST
API](https://developers.home-assistant.io/docs/api/rest) documentation.
+ Send request data: some endpoints require JSON data to be sent in the
request body. Positron lets you add this data using key/value pairs.
* Custom notification handlers: if your request returns some useful data, you
can write a custom response handler to get a system notification when the
shortcut is triggered. This can be used to, for instance, get the state of a
sensor or read events.
+ To implement a custom notification handler, you simply need to provide an
anonymous function of type:
`{ ok: boolean, body: string } => string`
The `ok` field indicates if the request was successful, and `body` contains
the raw data that the Home Assistant server replied with or an error
message. The return value of this function should be the content of the body
of your custom notification. For instance, the default custom notification
handler is:
`res => res.ok ? 'Ok' : res.body`
+ NOTE: This uses Electron's `vm` module to run your custom code. This
provides some isolation so you don't shoot yourself in the foot, but it has
been proven not to be a _secure_ isolation mechanism. Keep your handler
simple and, needless to say, don't run code you don't trust here.
* Manually trigger the request and see the response. Useful for debugging custom
notification handlers.
* Automatically minimizes itself to the system tray.
* Automatically save your configuration after changes.
* Dark/light mode switch.
## Setup
After you first launch this app, you can set up your Home Assistant server
details under the `Settings` page. You'll need:
* A Home Assistant server URL (HTTP/HTTPS, hostname, port)
* A [long-lived access
token](https://developers.home-assistant.io/docs/auth_api/#long-lived-access-token)
## Disclaimer for Wayland users
Positron isn't a native Wayland app and as such it will run under XWayland.
By design XWayland applications can't see inputs (such as keyboard shortcuts) performed in native Wayland apps. This means that shortcuts you configured in Positron will only work in other XWayland applications. This isn't something we have any control over.
Possible workarounds include:
- running X instead of Wayland
- configuring global shortcuts (e.g. in KDE you can define custom shortcuts, which will work in all applications. To do that open Settings and find shortcuts page, click `Add Command` and paste something like this:
```
curl -X POST -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{"entity_id": ""}' :/api/services//
```
More information about creating API requests can be found in [official docs](https://developers.home-assistant.io/docs/api/rest/)
## Screenshots
### Homepage
### Creating shortcuts
### Custom notification handlers
### Custom notifications
### Settings menu
## Install
### Precompiled releases
The easiest way to install this app is to grab one of the [precompiled
releases](https://github.com/agustinmista/positron/releases).
NOTE: the release binaries are **not signed**, so you might see Windows and
macOS complaining about them. This is not going to change unless this app gets
some traction, since both Microsoft and Apple charge you a fair amount of real
money to let you become a trusted developer.
* On Windows, if you see the `Windows protected your PC` popup, you can
continue by clicking on `More info` and then `Run anyway`.
* On macOS, you might need to [allow apps from unidentified
developers](https://support.apple.com/guide/mac-help/open-a-mac-app-from-an-unidentified-developer-mh40616/mac).
### Build from source
You can also build Positron by yourself. Assuming you have `git` and `npm`
installed, this should get you far:
```
git clone https://github.com/agustinmista/positron.git
cd positron
npm install
npm start # starts the app
npm run make # packages a binary/installer
```
Please report any issue you might encounter while building the app and I will
update this file accordingly.
## Contributing
Feel free to [open an
issue](https://github.com/agustinmista/positron/issues/new) if you find a bug or
if you'd like to see a new feature implemented.
PRs are welcomed too!
## License
MIT License
Copyright (c) 2023 Agustín Mista