forked from LAB02-Research/HASS.Agent.Staging
-
Notifications
You must be signed in to change notification settings - Fork 19
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #26 from hass-agent/development
Release: 2.0.0 readme changes
- Loading branch information
Showing
1 changed file
with
185 additions
and
54 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,90 +1,221 @@ | ||
| [](https://github.com/hass-agent/HASS.Agent/releases/) | ||
| [](#license) | ||
| [](https://www.microsoft.com/ "Go to Microsoft homepage") | ||
| [](https://img.shields.io/badge/.NET-6.0-blue) | ||
|  | ||
|  | ||
| [](https://discord.com/invite/JfZj98xqJr) | ||
|
|
||
| <a href="https://github.com/LAB02-Research/HASS.Agent/"> | ||
| <img src="https://raw.githubusercontent.com/LAB02-Research/HASS.Agent/main/images/logo_128.png" alt="HASS.Agent logo" title="HASS.Agent" align="right" height="128" /></a> | ||
|
|
||
| # HASS.Agent Project | ||
| # HASS.Agent | ||
|
|
||
| HASS.Agent is a Windows-based client (*companion*) application for [Home Assistant](https://www.home-assistant.io), developed in .NET 6. | ||
|
|
||
| Click [here](https://github.com/hass-agent/HASS.Agent/releases/latest/download/HASS.Agent.Installer.exe) to download the latest installer. | ||
|
|
||
| ---- | ||
|
|
||
| HASS.Agent is **completely free**, and will always stay that way without restrictions. | ||
|
|
||
| ---- | ||
|
|
||
| ### Contents | ||
|
|
||
| * [Why?](#why) | ||
| * [Fork?](#fork) | ||
| * [Functionality](#functionality) | ||
| * [Screenshots](#screenshots) | ||
| * [Installation](#installation) | ||
| * [Help and Documentation](#help-and-documentation) | ||
| * [Articles](#articles) | ||
| * [What it's not](#what-its-not) | ||
| * [Issue Tracker](#issue-tracker) | ||
| * [Helping Out](#helping-out) | ||
| * [Wishlist](#wishlist) | ||
| * [Credits and Licensing](#credits-and-licensing) | ||
| * [Legacy](#legacy) | ||
|
|
||
| ---- | ||
|
|
||
| ### Why? | ||
|
|
||
| Quick note from Sam on the initial idea: | ||
| > The main reason I built this is that I wanted to receive notifications on my PC, including images, and to quickly perform actions (e.g. to toggle a lamp). There weren't any software-based solutions for this, so I set out to build one myself. | ||
| There's no need to explain that we (and the Community overall) like the idea. That's why we're here, to continue the development in the Home Assistant spirit of integrating **everything** into open source smarthome world. | ||
|
|
||
| ---- | ||
|
|
||
| ### Fork? | ||
|
|
||
| The original HASS.Agent has been created by [Sam](https://github.com/LAB02-Admin). | ||
|
|
||
| Unfortunately due to some time constraints, they're not able to provide the constant support and feature updates. That's where we step in - trying to keep HASS.Agent bug free (dreams need to be big right?) and to introduce new features here and there! | ||
|
|
||
| ---- | ||
|
|
||
| ### Functionality | ||
|
|
||
| Summary of the core functions: | ||
|
|
||
| * **Notifications**: receive notifications, show them using Windows builtin toast popups, attach images and receive input from them. Supports *actionable notifications*: add buttons so you can easily interact with Home Assistant, without having to open anything or ask user for an answer to a question. | ||
| - *This requires the installation of the [HASS.Agent integration](https://github.com/hass-agent/HASS.Agent-Integration)*. | ||
|
|
||
| * **Media Player**: use HASS.Agent as a mediaplayer device: see and control what's playing and send text-to-speech. | ||
| - *This requires the installation of the [HASS.Agent integration](https://github.com/hass-agent/HASS.Agent-Integration)*. | ||
|
|
||
| * **Quick Actions**: use a keyboard shortcut to quickly pull up a command interface, through which you can control Home Assistant entities - or, assign a keyboard shortcut to individual Quick Actions for even faster triggering. | ||
|
|
||
| * **Commands**: control your PC (or other Windows based device) through Home Assistant using custom- or built-in commands. | ||
|
|
||
| * **Sensors**: send your PC's sensors to Home Assistant to monitor every aspect of your device. | ||
|
|
||
| * **WebView**: quickly show any website, anywhere - no browser required, for instance a HA dashboard. | ||
|
|
||
| * **Satellite Service**: use the service to collect sensordata and execute commands, even when you're not logged in (**not all commands/sensors are available for Satellite Service**) | ||
|
|
||
| * All entities are dynamically acquired from your Home Assistant instance. | ||
|
|
||
| * Commands and sensors are automatically added to your Home Assistant instance via MQTT Integration | ||
|
|
||
| ---- | ||
|
|
||
| ### Screenshots | ||
|
|
||
| Notification examples: | ||
|
|
||
|
|
||
| This project is a fork of the [original HASS.Agent](https://github.com/LAB02-Research/HASS.Agent) created by [Sam](https://github.com/LAB02-Research). | ||
|
|
||
| The Purpose of this project is to provide updates/features/fixes until development on the original project resumes. | ||
|
|
||
| At first all PRs made by me will be merged, but in time, I'll approach authors of other PRs for permission to also include them in here. | ||
|  | ||
|  | ||
|  | ||
|
|
||
| **NOTE**: I did my best to always maintain backward compatibility but this ***cannot be guaranteed***, please report any issues you may encounter. | ||
|
|
||
| ## Installation | ||
| WebView example, showing a dashboard when right-clicking the tray icon: | ||
|
|
||
| ### Installer | ||
|  | ||
|
|
||
| **Will be detailed and moved to the documentation soon :)** | ||
| This is the Quick Action window you'll see when using the hotkey. This window automatically resizes to the amount of buttons you've added: | ||
|
|
||
| 1. Download and run the installer exe from the releases page | ||
| 2. Launch HASS.Agent either manually or as a last step of installation | ||
|  | ||
|
|
||
| The installer will also offer and install the required x64 .net runtime. | ||
| You can easily configure a new Quick Action, HASS.Agent will fetch your entities for you: | ||
|
|
||
| ### Manual | ||
|  | ||
|
|
||
| Note: Both Client and Satellite Service ***may*** function without installation as a portable applications. | ||
| The sensors configuration screen: | ||
|
|
||
| **The recommended and official way is to use the installer.** | ||
|  | ||
|
|
||
| Adding a new sensor is just as easy: | ||
|
|
||
| 1. Download Client/Satellite Service ZIP files from the releases page | ||
| 3. Make sure [.net 6 (x64)](https://dotnet.microsoft.com/en-us/download/dotnet/thank-you/runtime-desktop-6.0.25-windows-x64-installer) and [Windows App SDK 1.4.2](https://aka.ms/windowsappsdk/1.4/1.4.231008000/windowsappruntimeinstall-x64.exe) is installed on your system | ||
| 4. Extract the files to separate folders (Client and Satellite Service) | ||
| 5. [Register](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/sc-create) the service in elevated cmd | ||
| ``` | ||
| sc.exe create hass.agent.svc binPath= "<absolute path to HASS.Agent.Satellite.Service.exe>" | ||
| ``` | ||
| 6. Run "HASS.Agent.exe" | ||
|  | ||
|
|
||
| Easily manage the satellite service through HASS.Agent: | ||
|
|
||
|  | ||
|
|
||
| You'll be guided through the configuration options during onboarding: | ||
|
|
||
|  | ||
|
|
||
| ---- | ||
|
|
||
| "Project" differences from the base project: | ||
| 1. No separation between "HASS.Agent" and "HASS.Agent.Staging" - since I have no access to the original repositories, it'll be easier for me to maintain it this way | ||
| 2. No documentation available yet - best case scenario the descriptions in the application should be sufficient but even so, I'd like to have unofficial documentation created at some point | ||
| 3. The update functionality present in UI does not work with the unofficial version, yet | ||
| ### Installation | ||
|
|
||
| Installing HASS.Agent is easy; just [download the latest installer](https://github.com/hass-agent/HASS.Agent/releases/latest/download/HASS.Agent.Installer.exe), run it and you're done! The installer is signed by us and won't download or do weird stuff - it just places everything where it should, and launches with the right parameter. (optionally installing .NET6) | ||
|
|
||
| After installing, the onboarding process will help you get everything configured, step by step. If you want an introduction into HASS.Agent, be sure to read the [introduction docs](https://www.hass-agent.io/latest/getting-started/). | ||
|
|
||
| Original HASS.Agent documentation is available [here](https://hassagent.readthedocs.io/en/latest/introduction/) - please bear in mind however that it may not represent state of things present in this version. | ||
|
|
||
| [Click here to download the latest installer](https://github.com/hass-agent/HASS.Agent/releases/latest/download/HASS.Agent.Installer.exe) | ||
|
|
||
| If you want to install manually, there are .zip packages available for every release. Read the [manual](https://www.hass-agent.io/latest/getting-started/installation/#manualzip-files) for more info. | ||
|
|
||
| ---- | ||
|
|
||
| **Will be moved to the documentation soon :)** | ||
|
|
||
| Major feature changes compared to the original project: | ||
| 1. [Virtual desktop sensor and command](https://github.com/LAB02-Research/HASS.Agent.Staging/pull/12) | ||
| 2. [Quick Action carousel/circular navigation](https://github.com/LAB02-Research/HASS.Agent.Staging/pull/15) | ||
| 3. [Notification library change an improvements including possible Win11 fix](https://github.com/LAB02-Research/HASS.Agent.Staging/pull/18) | ||
| 4. [Application volume controls (per application control, audio output command, audio sensor overhaul)](https://github.com/LAB02-Research/HASS.Agent.Staging/pull/19) | ||
| 5. [Internal device sensors - sensors present on the device running HASS.Agent](https://github.com/LAB02-Research/HASS.Agent.Staging/pull/21) | ||
| 6. [Ignore availability option for sensors](https://github.com/LAB02-Research/HASS.Agent.Staging/pull/22) | ||
| 6. [Radio (BT/WiFi/Broadband) control command](https://github.com/LAB02-Research/HASS.Agent.Staging/pull/23) | ||
| 7. [LastActive sensor refresh upon wake from sleep/hibernation](https://github.com/LAB02-Research/HASS.Agent.Staging/pull/9) | ||
|
|
||
| Major bug fix changes compared to the original project: | ||
| 1. [GPU temperature and load sensor returns proper values when encountering an error](https://github.com/LAB02-Research/HASS.Agent.Staging/pull/10) | ||
| 2. [Key commands emulation not actually "releases" the key after "pressing it"](https://github.com/LAB02-Research/HASS.Agent.Staging/pull/13) | ||
| 3. [PowerShell command action parameters now include check culture config missing on some systems](https://github.com/LAB02-Research/HASS.Agent.Staging/pull/14) | ||
| 4. [PerformanceCounter sensors do not call NextValue twice causing values to be borked](https://github.com/LAB02-Research/HASS.Agent.Staging/pull/16) | ||
| 5. [Adjustments per Home Assistant 2023.8 MQTT changes regarding sensor/device naming convention](https://github.com/LAB02-Research/HASS.Agent.Staging/pull/20) | ||
| ### Help and Documentation | ||
|
|
||
| Stuck while installing or using HASS.Agent, need some help integrating the sensors/commands or have a great idea for the next version? There are a few channels through which you can reach out: | ||
|
|
||
| * [Github Tickets](https://github.com/hass-agent/HASS.Agent/issues): Report bugs, feature requests, ideas, tips, .. | ||
|
|
||
| * [Documentation](https://www.hass-agent.io/latest/): Installation, configuration and usage documentation, as well as examples. | ||
|
|
||
| * [Discord](https://discord.com/invite/JfZj98xqJr): Get help with setting up and using HASS.Agent, report bugs or just talk about whatever. | ||
|
|
||
| * [Home Assistant forum](https://community.home-assistant.io/): Bit of everything, with the addition that other HA users can help as well. | ||
|
|
||
| Starting from zero, and want to learn what HASS.Agent's about and how to start? Be sure to check the [introduction article](https://www.hass-agent.io/latest/getting-started/#introduction), and optionally the [command basics](https://hassagent.readthedocs.io/en/latest/commands/command-basics/). | ||
|
|
||
| EverythingSmartHome's youtube video is a great guide on the original HASS.Agent version: [Control Your Windows PC With Home Assistant!](https://www.youtube.com/watch?v=B4SnJPVbSXc). We recommend having a look at his other videos as well, great stuff! | ||
|
|
||
| If you want to help with the development of HASS.Agent, check out the [Helping Out](#helping-out) section for (translating) info. | ||
|
|
||
| ---- | ||
|
|
||
| This project contains the latest code of all three parts of the HASS.Agent platform: | ||
| ### Articles | ||
|
|
||
| ### Original HASS.Agent | ||
|
|
||
| Liam Alexander Colman from [Home Assistant Guide](https://home-assistant-guide.com) was kind enough to write an article about HASS.Agent: [Integrate Home Assistant with Windows using HASS.Agent](https://home-assistant-guide.com/2022/04/20/integrate-home-assistant-with-windows-using-hass-agent/). The website's full of useful articles, worth having a look :) | ||
|
|
||
| ---- | ||
|
|
||
| | Project | Description | | ||
| |---|---| | ||
| | HASS.Agent | Main client, containing the UI, runs in userspace, by default without elevation | | ||
| | HASS.Agent.Satellite.Service | Windows client, runs under SYSTEM account | | ||
| | HASS.Agent.Shared | Library, contains all commands, sensors, shared functions and enums | | ||
| ### What it's not | ||
|
|
||
| <br/> | ||
| A Linux/macOS client! | ||
|
|
||
| This question comes up a lot, understandably. However it's currently focussed on being a Windows-based client. Even though .NET 6 allows for Linux/macOS development, it's not as easy as pressing a button. The interface would have to be redesigned from the ground up, sensors and commands would need multiple codebases for each OS, testing would take way more time, every OS handles notifications differently, etc. | ||
|
|
||
| Note: when reporting issues it's best to have `enable extended logging` enabled. | ||
| You can use the [official companion app](https://apps.apple.com/us/app/home-assistant/id1099568401) for macOS, or [IoPC](https://github.com/maksimkurb/IoPC) which runs on Linux. Note: We haven't tested either. | ||
|
|
||
| ---- | ||
|
|
||
| Documentation for the original project is available here: [https://hassagent.readthedocs.io/en/latest/development/introduction/](https://hassagent.readthedocs.io/en/latest/development/introduction/) | ||
| ### Helping Out | ||
|
|
||
| The best way to help out is to test as much as you can (or even join the beta program), and report any weird or failing behavior by [opening a ticket](https://github.com/hass-agent/HASS.Agent/issues). | ||
|
|
||
| Same goes for sharing ideas for new (or improved) functionality! If you want, you can [join on Discord](https://discord.com/invite/JfZj98xqJr) to discuss your ideas. | ||
|
|
||
| ---- | ||
|
|
||
| Thanks! If you need more info, please join on [Discord](https://discord.com/invite/JfZj98xqJr). | ||
| ### Credits and Licensing | ||
|
|
||
| First and foremost, huge thanks for [Sam](https://github.com/LAB02-Admin) for creating and maintaining the original HASS.Agent in their spare time! We wouldn't be here withot the spark that pushed them to write the first line of code :heart: | ||
|
|
||
| As of now, we do not accept any kind of donation/coffee :) | ||
| <br>If you'd like however, you can support [creator](https://github.com/LAB02-Admin) of original HASS.Agent: | ||
|
|
||
| | [](https://ko-fi.com/lab02research) | [](https://www.buymeacoffee.com/lab02research) | [](https://www.paypal.com/donate/?hosted_button_id=5YL6UP94AQSPC) | | ||
| |:---:|---|---| | ||
|
|
||
| Thanks to the entire team that's developing [Home Assistant](https://www.home-assistant.io) - such an amazing platform! | ||
|
|
||
| The initial development was boosed by sleevezipper's [HASS Workstation Service](https://github.com/sleevezipper/hass-workstation-service). Thank you for sharing your hard work. | ||
|
|
||
| And a big thank you to all other packages: | ||
|
|
||
| [CoreAudio](https://github.com/morphx666/CoreAudio), [HotkeyListener](https://github.com/Willy-Kimura/HotkeyListener), [MQTTnet](https://github.com/chkr1011/MQTTnet), [Syncfusion](https://www.syncfusion.com), [Octokit](https://github.com/octokit/octokit.net), [Cassia](https://www.nuget.org/packages/Cassia.NetStandard/), [Grapevine](https://scottoffen.github.io/grapevine), [LibreHardwareMonitor](https://github.com/LibreHardwareMonitor/LibreHardwareMonitor), [Newtonsoft.Json](https://www.newtonsoft.com/json), [Serilog](https://github.com/serilog/serilog), [CliWrap](https://github.com/Tyrrrz/CliWrap), [HADotNet](https://github.com/qJake/HADotNet), [Microsoft.Toolkit.Uwp.Notifications](https://github.com/CommunityToolkit/WindowsCommunityToolkit), [GrpcDotNetNamedPipes](https://github.com/cyanfish/grpc-dotnet-namedpipes), [gRPC](https://github.com/grpc/grpc), [ByteSize](https://github.com/omar/ByteSize). | ||
|
|
||
| Please consult their individual licensing if you plan to use any of their code. | ||
|
|
||
| Everything on the HASS.Agent platform is released under the [MIT license](https://opensource.org/licenses/MIT). | ||
|
|
||
| --- | ||
|
|
||
| ### Legacy | ||
|
|
||
| HASS.Agent is a .NET 6 application. If for some reason you can't install .NET 6, you can use the last .NET Framework 4.8 version: | ||
|
|
||
| [v2022.3.8](https://github.com/LAB02-Research/HASS.Agent/releases/tag/v2022.3.8) | ||
|
|
||
| It's pretty feature complete if you just want commands, sensors, quickactions and notifications. | ||
|
|
||
| You'll need to have .NET Framework 4.8 installed on your PC, which you can [download here](https://dotnet.microsoft.com/en-us/download/dotnet-framework/thank-you/net48-web-installer). | ||
|
|
||
| If you find any bugs, feel free to [create a ticket](https://github.com/LAB02-Research/HASS.Agent/issues) and I'll try to patch it. |