home-assistant
/
joshuar-go-hass-agent
mirror of https://github.com/joshuar/go-hass-agent.git
0
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
A Home Assistant, native app for desktop/laptop devices.
262 Commits 2 Branches 95 Tags 6.5 MiB
Go 98.7%
Shell 0.9%
Dockerfile 0.4%
Go to file
Joshua Rich 6d7fa2f575
Merge pull request #15 from joshuar/release-please--branches--main 
chore(main): release 1.0.0
 		2023-05-20 10:42:32 +10:00
.github ci(release_please): adjust steps for goreleaser 2023-05-08 09:45:45 +10:00
assets Clean up documentation. 2023-04-16 11:44:36 +10:00
cmd refactor(agent): simplify NewAgent function 2023-05-17 10:42:47 +10:00
docs Squashed commit of the following: 2023-04-28 08:27:35 +10:00
internal docs(device,linux): document functions 2023-05-20 10:33:17 +10:00
tools/ansible Add licensing. 2023-04-10 09:45:12 +10:00
.gitignore chore(git): clean-up .gitignore 2023-05-06 13:38:49 +10:00
.goreleaser.yaml fix(build): fix dependencies for rpm/deb packages 2023-05-05 15:05:58 +10:00
CHANGELOG.md chore(main): release 1.0.0 2023-05-20 00:23:23 +00:00
LICENSE Add licensing. 2023-04-10 09:45:12 +10:00
README.md docs(README): add details on headless mode 2023-05-13 11:49:03 +10:00
go.mod fix(agent): better initial window size for sensors display 2023-05-19 15:13:37 +10:00
go.sum fix(agent): better initial window size for sensors display 2023-05-19 15:13:37 +10:00
main.go Add check to ensure agent doesn't run as root or with elevated privileges. 2023-04-14 22:17:14 +10:00

README.md

go-hass-app

MIT GitHub last commit Go Report Card Go Reference Release

A Home Assistant, native app integration for desktop/laptop devices.

🎉 Features

This app will add some sensors to a Home Assistant instance:

  • Device location.
  • Current active application and list of running applications.
  • Battery status (for example, laptop battery and any peripherals).
  • Network status (for example, network connection status, internal and external IP addresses and Wi-Fi details where relevant).
  • Memory and swap usage (total/free/used).
  • Disk usage.
  • Load Averages.
  • Uptime.
  • Power profile.
  • Problems detected by ABRT.

The code can be extended to add additional sensors. See the development docs for details.

🤔 Use-cases

As examples of some of the things that can be done with the data published by this app:

  • Change your lighting depending on what active/running apps are on your laptop/desktop. For example, you could set your lights dim or activate a scene when you are gaming.
  • With your laptop plugged into a smart plug that is also controlled by Home Assistant, turn the smart plug on/off based on the battery charge to force a full charge/discharge cycle of the battery, extending its life over leaving it constantly charged.
  • Like on mobile devices, create automations based on the location of your laptop running this app.
  • Receive notifications from Home Assistant on your desktop/laptop.

See also the FAQ.

🤝 Compatibility

Currently, only Linux is supported. Though the code is designed to be extensible to other operating systems. See the development docs for details on how to extend for other operating systems.

⬇️ Installation

Head over to the releases page and download the appropriate package for your operating system and/or distribution.

🖱️ Usage

go-hass-agent runs as a tray icon by default. It is operating system, distribution and desktop-environment agnostic and should manifest itself in any tray of any desktop environment.

First-run

On first-run, go-hass-agent will display a window where you will need to enter some details, so it can register itself with a Home Assistant instance to be able to report sensors and receive notifications.

Registration Window

You will need:

  • A long-lived access token. You can generate one on your account profile page.
  • The hostname (or IP address) and port on which a Home Assistant instance can be found.
    • go-hass-agent will try to auto-detect this for you, and you can select it in the Auto-discovered servers list. Otherwise, you will need to select Use Custom Server?, and enter the details manually in Manual Server Entry.
  • If the Home Assistant instance supports TLS/SSL, be sure to select Use TLS? as well.

When you have entered all the details, click Submit and the agent should start running and reporting sensors to the Home Assistant instance.

As alternative, you can register go-hass-agent on the command-line with by running:

go-hass-agent register --token _TOKEN_ --url _URL_

You will need to provide a long-lived token _TOKEN_ and the URL of your Home Assistant instance, _URL_.

Regular Usage

When running, go-hass-agent will appear as a device under the Mobile App integration in your Home Assistant instance. It should also report a list of sensors/entities you can use in any automations, scripts, dashboards and other parts of Home Assistant.

Running Headless

go-hass-agent can run in a "headless" mode, without any GUI elements, by specifying the -t or --terminal command-line option.

🧑‍🤝‍🧑 Contributing

🏗️ Development

I would welcome your contribution! If you find any improvement or issue you want to fix, feel free to send a pull request!

Some documentation for development can be found in the development docs. There is information for developing go-hass-agent for different operating systems as well as adding additional sensors. This might help anyone looking to contribute, extend or fork this tool.

🌐 Translations

While this application does not have many points where text is displayed to the end user (logging aside), translation is supported through the language and message packages that are part of golang.org/x/text.

I would welcome pull requests for translations!

🙌 Acknowledgements

The app icon is taken from the Home Assistant project.

License

MIT