DOCSEARCHbyAlgolia
Submit Docs

HASS.Agent Documentation

repository·main·Indexed 23 days ago

https://github.com/hass-agent/hass.agent

A Windows-based companion application built on .NET 8 that integrates Windows machines with Home Assistant via MQTT. It enables sensor reporting for hardware and system status, command execution (including system power controls and custom shell commands), Windows toast notifications, media player control, and a WebView for displaying dashboards.

Tokens
7.3K
Snippets
6
Records
47
Agent score
79%

What's inside HASS.Agent

  1. Core Functionality of HASS.Agent

    main

    HASS.Agent allows you to integrate your Windows PC with Home Assistant via MQTT. Key features include:

    • Notifications: Receive Windows toast popups with images and actionable buttons (requires HASS.Agent integration).
    • Media Player: Control media playback and send text-to-speech (requires HASS.Agent integration).
    • Quick Actions: Trigger Home Assistant entities via a keyboard shortcut or a command interface.
    • Commands: Control your Windows device from Home Assistant using built-in or custom commands.
    • Sensors: Monitor PC hardware and system status by sending sensor data to Home Assistant.
    • WebView: Display websites or Home Assistant dashboards directly in a window without a separate browser.
    • Satellite Service: A background service that collects sensor data and executes commands even when no user is logged in (note: not all commands/sensors are supported in this mode).

  2. Configure Sensors and Commands

    main

    HASS.Agent automatically manages the communication of entities to Home Assistant via MQTT.

    • Sensors: You can add new sensors through the HASS.Agent configuration interface to monitor various aspects of your device. All sensors are dynamically acquired and sent to Home Assistant.
    • Commands: You can define custom commands or use built-in ones to allow Home Assistant to control your PC. These are automatically added to your Home Assistant instance.

  3. Use HASS.Agent as a Media Player and for Notifications

    main

    To use HASS.Agent's advanced communication features, you must install the HASS.Agent integration in your Home Assistant instance.

    • Notifications: Supports actionable notifications, allowing you to add buttons to toast popups for direct interaction with Home Assistant.
    • Media Player: Enables your PC to appear as a media player device in Home Assistant, allowing you to see what is playing, control playback, and send text-to-speech (TTS) commands.

  5. Install HASS.Agent on Windows

    main

    HASS.Agent is a Windows-based companion application for Home Assistant built on .NET 8.

    Standard Installation

    1. Download the latest installer from the GitHub Releases page.
    2. Run the installer.
    3. Follow the onboarding process to configure the application step-by-step.

    Note: The installer can optionally install .NET 8 if it is not already present on your system.

    Manual Installation

    If you prefer not to use the installer, .zip packages are available for every release. Refer to the official manual installation guide for details.

    https://github.com/hass-agent/HASS.Agent/releases/latest/download/HASS.Agent.Installer.exe

  6. How command storage and synchronization works

    main

    Command management in HASS.Agent follows a staged commit pattern. When you add, modify, or delete commands in the CommandsConfig UI, you are interacting with a temporary local list (_commands) and a deletion queue (_toBeDeletedCommands).

    Changes are not applied to the system or sent to Home Assistant immediately. To finalize changes, you must trigger the storage process (via BtnStore_Click). This invokes CommandsManager.StoreAsync, which performs the following:

    1. Persists the current list of configured commands.
    2. Removes the commands marked for deletion.
    3. Synchronizes the updated command set to Home Assistant via MQTT.

    If the storage process fails, an error message is displayed, and the configuration changes are not committed.

  7. Execute custom commands via HASS.Agent

    main

    The CustomCommand abstraction allows HASS.Agent to execute arbitrary shell commands or applications triggered from Home Assistant. These commands can be configured to run with standard privileges or with Low Integrity (a security sandbox mode) to limit the impact of the executed process.

    Execution Modes

    • Standard Execution: Uses CommandLineManager.Execute or ExecuteHeadless. This is the default behavior.
    • Low Integrity Execution: Uses CommandLineManager.LaunchAsLowIntegrity. This is useful for running untrusted or less critical commands in a restricted environment.

    Command Types

    • Action-only: If the command string is empty, the command acts as a trigger that only responds to specific action payloads sent from Home Assistant.
    • Switch-like: If a command is configured, it can behave like a switch, though the internal state is typically reset to OFF immediately after the execution attempt.

  8. Understand the InternalCommand abstraction

    main

    In the HASS.Agent platform, InternalCommand is a base class used to define commands that are executed within the agent itself. It manages the lifecycle of a command's state and provides the necessary MQTT discovery configuration so that Home Assistant can interact with the command.

    Key properties and behaviors include:

    • State: Tracks whether the command is currently ON or OFF.
    • CommandConfig: A string used to pass specific configuration data to the command.
    • Discovery: It automatically generates MQTT topics for availability, command, action, and state based on the configured MqttManager and device configuration.

    Developers extending the agent should override TurnOn(), TurnOff(), or TurnOnWithAction(string action) to implement the actual logic for the command.

  9. Execute PowerShell commands and scripts via HASS.Agent

    main

    HASS.Agent supports creating commands that execute PowerShell logic. These can be configured as either direct commands or .ps1 scripts.

    • PowerShell Commands: If the command string does not end in .ps1, it is treated as a standard command executed via ExecuteCommandHeadless.
    • PowerShell Scripts: If the command string ends in .ps1, it is treated as a script and executed via ExecuteScriptHeadless.

    When triggered via Home Assistant, these commands can also accept an action parameter, which is passed to the script execution logic.

  10. Implement custom commands using InternalCommand

    main

    To create a new command within HASS.Agent, inherit from InternalCommand. You must provide an entityName, a name, and a commandConfig. The entityType defaults to CommandEntityType.Switch if not specified.

    When implementing, you should override the following methods to define how the command reacts to Home Assistant signals:

    • TurnOn(): Logic to execute when the command is turned on.
    • TurnOff(): Logic to execute when the command is turned off.
    • TurnOnWithAction(string action): Logic to execute when a specific action string is received via the action_topic.

    Example implementation structure:

    // Example of how a developer would extend the class
public class MyCustomCommand : InternalCommand
{
    public MyCustomCommand(string entityName, string name, string config) 
        : base(entityName, name, config, CommandEntityType.Switch)
    {
    }

    public override void TurnOn()
    {
        base.TurnOn();
        // Implement custom logic here
    }

    public override void TurnOff()
    {
        base.TurnOff();
        // Implement custom logic here
    }
}

  11. Manage HASS.Agent commands via CommandsConfig

    main

    The CommandsConfig interface allows users to manage the collection of commands that HASS.Agent can execute. Commands are stored locally and then synchronized to Home Assistant via MQTT.

    Key capabilities include:

    • Add Commands: Create new command configurations using the CommandsMod dialog.
    • Modify Commands: Edit existing command settings (such as entity names or execution parameters) by selecting a command and using the modify function.
    • Delete Commands: Mark selected commands for removal. Note that deletion is staged and only finalized when the configuration is stored.
    • Store and Sync: Use the 'Store' action to commit all pending additions, modifications, and deletions. This process triggers CommandsManager.StoreAsync, which synchronizes the updated command list to Home Assistant through MQTT.

  12. Configure the LaunchUrl command

    main

    The LaunchUrlCommand allows Home Assistant to trigger the opening of a specific URL on the host machine. This command is configured via a JSON string passed as urlInfo.

    To configure the command, provide a JSON object containing the following keys:

    • Url: The target web address (string).
    • Incognito: A boolean indicating whether to launch the URL in incognito/private mode.

    If the Url is not provided in the configuration, the command can still be used as an 'action-only' command where the URL is passed dynamically via the TurnOnWithAction method (the action parameter).