-
Notifications
You must be signed in to change notification settings - Fork 4
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 #8 from DrR0X-glitch/beta
HAD-75 Add Installation and Initial Setup Pages
- Loading branch information
Showing
9 changed files
with
151 additions
and
310 deletions.
There are no files selected for viewing
Binary file not shown.
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
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 |
|---|---|---|
| @@ -0,0 +1,70 @@ | ||
| # Initial Configuration and First Run | ||
|
|
||
| Once you've [installed](./installation.md) HASS.Agent onto your computer you are ready to run HASS.Agent. | ||
|
|
||
| ## Onboarding and First Run | ||
|
|
||
| When you open HASS.Agent for the first time it will guide you through the onboarding process to get everything setup and working. After the onboarding process is complete you can move onto the setup in Home Assistant. | ||
|
|
||
| ### API | ||
|
|
||
| During onboarding, on page 3, you'll be prompted for an API token and your Home Assistant URL. Here's how to obtain an API key from your Home Assistant installation: | ||
|
|
||
| 1. Open the [profile page](https://my.home-assistant.io/redirect/profile/){: target="\_blank"}. | ||
| 2. Scroll down to Long-lived Access Tokens. | ||
| 3. Click "Create Token". | ||
| 4. Copy the token using the button and paste it into the HASS.Agent onboarding page. | ||
|
|
||
| ### MQTT | ||
|
|
||
| For the MQTT configuration, provide your MQTT broker's username, password, URI, and port. | ||
|
|
||
| Here are the steps for getting the MQTT broker if you are using the mosquitto add-on in homeassistant. For other mqtt brokers you will need to checkout their own guides. | ||
|
|
||
| 1. **Username and Password** This depends on how you have setup the Mosquitto Add-on, but assuming you have done it in the recommended way you will have created a separate Home Assistant user for the MQTT broker. If that's the case go ahead and use it's username and password for this section. If you haven't yet setup authentication for the Home Assistant Mosquitto add-on then checkout [this](https://youtu.be/dqTn-Gk4Qeo?si=pqcLDV7mNtVqzAhh&t=326){: target="\_blank"} video. | ||
| 2. **IP and Port** This will be the IP/Hostname of your Home Assistant server and the port `1883`. So for most people use: `http://homeassistant.local` with port `1883`. | ||
|
|
||
| !!! danger "Discovery Prefix" | ||
|
|
||
| The discovery prefix is an advanced feature intended for professionals. It does not identify your PC but is used by Home Assistant to locate devices. Unless you are experienced, leave it as is. | ||
|
|
||
| ## Initial Setup in Home Assistant | ||
|
|
||
| After running the onboarding for HASS.Agent and [installing](./installation.md/#installing-the-home-assistant-integration) the integration you can move on to connecting your computer to Home Assistant. | ||
|
|
||
| #### Checklist | ||
|
|
||
| - [ ] HASS.Agent has been [installed](./installation.md) and the [onboarding](#onboarding-and-first-run) has been completed. | ||
| - [ ] The HASS.Agent HACS integration has been [installed](./installation.md/#installing-the-home-assistant-integration). | ||
|
|
||
| ### Configure your computer | ||
|
|
||
| If you navigate to your integrations dashboard you should see your HASS.Agent PC auto-discovered and pop-up. | ||
|
|
||
| [](https://my.home-assistant.io/redirect/integrations/){: target="\_blank"} | ||
|
|
||
| If not you can checkout the [troubleshooting](./troubleshooting.md) steps. | ||
|
|
||
| #### Finish Setup | ||
|
|
||
| The first time Home Assistant discovers your PC it will pop-up asking you to select the room the PC is located in. After selecting the room you are ready to move on to the next step. | ||
|
|
||
| ## Setup HASS.Agent | ||
|
|
||
| Now you have finished installing and configuring HASS.Agent you are ready to set it up how you want to use it. You can checkout these getting started guides for more: | ||
|
|
||
| <div class="grid cards" markdown> | ||
|
|
||
| - :material-remote-tv: **[Quick Actions]** – Interact with homeassistant entities and scripts from your taskbar or a hotkey! | ||
| - :material-radar: **[Sensors]** – Send data from your computer to homeassistant to create automations! | ||
| - :octicons-git-merge-24: **[Commands]** – Create commands homeassistant can run to do things on your computer! | ||
| - :material-bell-ring: **[Notifications]** – Send notifications from homeassistant, including actions and images! | ||
| - :material-file-cog: **[Other Features]** – For a guide on all the features and config options in HASS.Agent. | ||
|
|
||
| </div> | ||
|
|
||
| [Quick Actions]: ./quick-actions.md | ||
| [Sensors]: ./sensors.md | ||
| [Commands]: ./commands.md | ||
| [Notifications]: ./notifications.md | ||
| [Other Features]: ../setup/index.md |
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,101 +1,42 @@ | ||
| # Installation | ||
|
|
||
| Currently HASS.Agent is temporarily without access to the original REPO, however this is not permanent and will be resolved soon. For now though there are 2 main branches of HASS.Agent. There is the official one, which is older but more tested and stable. Then there is the beta version which is brand new with up-to-date features but less stable. We will go over installation instructions for both. | ||
| HASS.Agent consists of two parts: the client/Windows app and the Home Assistant integration. You will need to install and configure both of these to use most of HASS.Agent's features. | ||
|
|
||
| **Quick Install:** Click [here](https://github.com/LAB02-Research/HASS.Agent/releases/latest/download/HASS.Agent.Installer.exe) to download the official(old) build. | ||
| ## Prerequisites | ||
|
|
||
| ### Installation Methods | ||
| - **Home Assistant:** Ensure that your Home Assistant version is newer than `2023.6.0`. If you need help with Home Assistant, refer to the [official documentation](https://www.home-assistant.io/installation/){: target="\_blank"}. | ||
| - **MQTT:** Set up an MQTT broker and install/configure the MQTT add-on in Home Assistant. A simple guide for MQTT setup can be found [here](https://www.youtube.com/watch?v=dqTn-Gk4Qeo){: target="\_blank"}. | ||
| - **Windows 10/11:** HASS.Agent supports Windows 10 and 11. Older versions may work, but functionality is not guaranteed. | ||
|
|
||
| HASS.Agent consists of two main programs; The client and the service. The client is the interface that you will interact with to update settings and access quick actions. The Service(Satellite Service) is what allows HASS.Agent to run commands in the background. This means that the client must be installed for each user whereas the service is installed for the entire machine. | ||
| ??? question "I don't want to install or use MQTT, can I still use HASS.Agent?" | ||
|
|
||
| #### Installers | ||
| You don't **have** to have MQTT to use HASS.Agent; however, most features rely on it for bidirectional communication. Without MQTT, only Quick Actions will work. | ||
|
|
||
| Installers are simple programs you download and run that will install all necessary files and take you through the full setup. Installers only work for one user. Click [here](#installer-recommended) for this method. | ||
| ## Installing HASS.Agent | ||
|
|
||
| #### Manual .zip files | ||
| To get started with installing HASS.Agent, follow these steps: | ||
|
|
||
| You can also manually download the .zip files for both parts of HASS.Agent; the service and the client. Click [here](#manualzip-files) for this method. | ||
| 1. Download the latest installer from [here](https://github.com/hass-agent/HASS.Agent/releases/latest/download/HASS.Agent.Installer.exe). | ||
| 2. Open the installer and follow the on-screen instructions. | ||
| 3. **Optional:** The installer allows you to copy the configuration from the previously installed version of HASS.Agent (Pre v2). | ||
|
|
||
| #### Special Case: Installing for multiple users | ||
| ## Installing the Home Assistant Integration | ||
|
|
||
| If you want to install HASS.Agent on multiple accounts on the same PC, first install using the installer, then use the corresponding .zip package for the remaining accounts. | ||
| After installing HASS.Agent on your PC, follow these steps to install the Home Assistant integration: | ||
|
|
||
| > Note: you only have to install HASS.Agent on those accounts, the service is once-per-machine. | ||
| 1. Ensure you have HACS installed. If not, follow the installation guide [here](https://hacs.xyz/docs/setup/download){: target="\_blank"}. | ||
| 2. Click the button below to install the HASS.Agent integration. | ||
|
|
||
| --- | ||
| [](https://my.home-assistant.io/redirect/hacs_repository/?owner=LAB02-Research&repository=HASS.Agent-Integration){: target="\_blank"} | ||
|
|
||
| ## Installer (recommended) | ||
| ??? question "I don't want to install HACS, can I still install the HASS.Agent integration?" | ||
|
|
||
| > Note: Requires elevated privileges(Administrator) to install | ||
| Yes, it is possible to install the integration without HACS; however, it is more difficult. Find more information [here](./other-installs.md/#installing-the-integration-without-hacs). | ||
|
|
||
| HASS.Agent can use an entry in your user account's registry to launch on login. It's disabled by default, but you'll be offered to enable this during onboarding, or you can always disable/enable using the Configuration window. | ||
| ## Finishing up | ||
|
|
||
| To use notifications and/or the mediaplayer functionality, you'll need to install the [HASS.Agent integration](https://github.com/LAB02-Research/HASS.Agent-Integration). Checkout [this]() guide for more info. | ||
| After installing both the integration and client/Windows app, proceed to the initial setup and configuration. | ||
|
|
||
| ### Official Installer Release | ||
| ???+ info | ||
|
|
||
| Click [here](https://github.com/LAB02-Research/HASS.Agent/releases/latest/download/HASS.Agent.Installer.exe) to download the official installer. | ||
|
|
||
| ### Beta Installer Release | ||
|
|
||
| The current dev team has no access to the original installer so betas are using a separate more bare-bones installer. | ||
|
|
||
| Click [here]() to download the beta installer. | ||
|
|
||
| --- | ||
|
|
||
| ## Manual(.zip files) | ||
|
|
||
| If you don't want to (or can't) use the installer, you can also install manually - it's not that hard. | ||
|
|
||
| Make sure you have dotnet 6 desktop runtime installed, you can [get that here](https://dotnet.microsoft.com/en-us/download/dotnet/thank-you/runtime-desktop-6.0.4-windows-x64-installer). | ||
|
|
||
| There are two zip files to download with every release; the client and the service. Get them just below. | ||
|
|
||
| HASS.Agent needs to be placed in a folder with write access. The default is `%appdata%\LAB02 Research\HASS.Agent`, but anywhere will do. | ||
|
|
||
| The Satellite Service's default folder is `C:\Program Files (x86)\LAB02 Research\HASS.Agent Satellite Service`. You can place it anywhere you want, however, if that's the case you need to manually start `HASS.Agent.Satellite.Service.exe`, wait for it to start, then close it again. This way, it'll have configured a local registry setting telling HASS.Agent where it's stored. | ||
|
|
||
| When both are done, you can start the configuration process by opening an **elevated** command prompt in HASS.Agent's directory. Then, execute the following command: | ||
|
|
||
| `HASS.Agent.exe update` | ||
|
|
||
| HASS.Agent will now launch, install and configure the service and firewall rules, then relaunch itself without elevation. | ||
|
|
||
| All done! | ||
|
|
||
| ### Official .zip Release | ||
|
|
||
| Click [here](https://github.com/LAB02-Research/HASS.Agent/releases/latest/download/HASS.Agent.zip) to download the latest HASS.Agent package. | ||
|
|
||
| Click [here](https://github.com/LAB02-Research/HASS.Agent/releases/latest/download/HASS.Agent.Satellite.Service.zip) to download the latest Satellite Service package. | ||
|
|
||
| ### Beta .zip Release | ||
|
|
||
| Click to download the latest HASS.Agent package. | ||
|
|
||
| Click to download the latest Satellite Service package. | ||
|
|
||
| --- | ||
|
|
||
| ## Build From Scratch (Official only) | ||
|
|
||
| If you want, you can also build everything yourself. You'll need to have Visual Studio 2022 installed. Also, make sure you have dotnet 6 desktop runtime installed, you can [get that here](https://dotnet.microsoft.com/en-us/download/dotnet/thank-you/runtime-desktop-6.0.4-windows-x64-installer). | ||
|
|
||
| There are two main projects: | ||
|
|
||
| [HASS.Agent](https://github.com/LAB02-Research/HASS.Agent/tree/main/src) | ||
|
|
||
| [HASS.Agent Satellite Service](https://github.com/LAB02-Research/HASS.Agent.Satellite.Service/tree/main/src) | ||
|
|
||
| Just get the source through git or GitHub's zip download, launch the solution files, make sure you set `x64` as its output type and build. | ||
|
|
||
| If you want to control the entire process: both projects use `HASS.Agent.Shared`, a library which contains models and code mainly for the commands and sensors. It's added as a [nuget](https://www.nuget.org/packages/HASS.Agent.Shared). | ||
|
|
||
| You can download its source here: | ||
|
|
||
| [HASS.Agent.Shared](https://github.com/LAB02-Research/HASS.Agent.Shared) | ||
|
|
||
| Just like before, make sure you set `x64` as its output type and build. Then, remove the nuget reference from both projects, add your own library and rebuild them. | ||
|
|
||
| When all this is done, you can follow step 2 'manual' on this page to resume installation. | ||
| After installation, you can delete the `HASS.Agent.Installer.exe`. |
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 |
|---|---|---|
| @@ -0,0 +1,14 @@ | ||
| # Other HASS.Agent Installation Methods | ||
|
|
||
| ## Installing the integration without HACS | ||
|
|
||
| If you don't want to use HACS for installation of the HASS.Agent integration you can do it manually. | ||
|
|
||
| !!! warning | ||
|
|
||
| If you choose to install the integration without HACS you will not automatically receive updates. You will have to follow these installation steps again for each update. | ||
|
|
||
| 1. Download and extract the files in the [Integration Repo](https://github.com/hass-agent/integration/archive/refs/heads/main.zip){: target="\_blank"}. | ||
| 2. Copy the `custom_components/` directory into your Home Assistant's `config/` directory. | ||
|
|
||
| Done! Thats it, but remember there will be no updates, so you need to re-download the file and copy again for each update of the integration. Make sure to restart Home Assistant to apply the changes. |
Oops, something went wrong.