DOCSEARCHbyAlgolia
Submit Docs

browser_mod

repository·master·Indexed 23 days ago

https://github.com/thomasloven/hass-browser_mod

A Home Assistant integration that turns web browsers (tablets, phones, computers) into controllable entities. It enables advanced UI interactions such as popups and dashboard navigation, and provides browser-specific entities including media_player, light, and various sensors to monitor and control browser devices directly from Home Assistant services.

Tokens
17.4K
Snippets
40
Records
83
Agent score
82%

What's inside browser_mod

  1. Overview of browser_mod capabilities

    master

    browser_mod is a Home Assistant integration that transforms a web browser into a controllable entity and an audio player. It allows you to interact with specific browser instances via Home Assistant automations and services.

    Common use cases include:

    • Popups: Displaying camera feeds or messages on specific tablets/screens based on triggers (e.g., doorbell ringing).
    • Tab Management: Switching browser tabs on a workstation based on Home Assistant states.
    • Audio/TTS: Playing Text-to-Speech messages through a computer's browser.
    • Screen Control: Managing screen brightness or sleep states (e.g., making a tablet screen go black at night).

  2. Synchronize and manage Browser IDs

    master

    Since version 2.13.0, Browser IDs can be synchronized to the logged-in session to prevent them from changing.

    • To enable synchronization: In the Browser Mod panel for the device, turn on Sync session selection.
    • To set a specific ID via URL: Append ?BrowserID=your_id (note the capital 'B') to any Home Assistant URL.

  3. Understand the Browser concept and BrowserID

    master

    The core abstraction in Browser Mod is the Browser. Each browser is identified by a unique BrowserID stored in the browser's LocalStorage.

    Key behaviors:

    • URL Sensitivity: Because LocalStorage is bound to a URL, accessing Home Assistant via different addresses (e.g., local IP vs. Home Assistant Cloud) may result in different BrowserIDs. You can manually unify these by selecting the same ID from the BrowserID dropdown in the Browser Panel.
    • Persistence: Browser Mod attempts to keep the ID constant, but it can change if LocalStorage is cleared (e.g., cache wipes or privacy settings).

  4. Difference between Server calls and Browser calls

    master

    Browser Mod distinguishes between two ways of calling services, which determines the target of the action when no specific ID is provided:

    1. Server calls: Triggered from scripts, automations, Developer Tools, or standard dashboard card actions. If no browser_id or user_id is specified, the service is performed on ALL REGISTERED BROWSERS.
    2. Browser calls: Triggered via a dashboard fire-dom-event action, as part of a browser_mod.sequence, or as a *_action within a browser_mod.popup. If no ID is specified, the service is performed only on THE CURRENT BROWSER.

    Tip: To show a popup on the specific browser where a user clicks a button, use a Browser call with action: fire-dom-event.

  5. Understand and use Browser Entities

    master

    Browser Mod provides a set of entities (such as media_player, light, binary_sensor, and various sensors) to control and monitor the browser device.

    Key concepts:

    • Browser Entities: These include controls for the screen (light), media playback (media_player), activity monitoring (binary_sensor), and diagnostic sensors.
    • Dashboard Cards: Use Browser Mod Tile and Browser Mod Badge to display local browser entities on your dashboard.
    • The browser_entities variable: A special dictionary available in Frontend settings templates and via Browser calls. It contains metadata for each entity, specifically entity_id and enabled.

    Important Constraints:

    • If the browser is not registered, browser_entities will be undefined. Use the default() filter in templates to handle this.
    • browser_entities is NOT available in the Developer Tools template editor; it only works in the specific scenarios mentioned above.
    • Some entities marked as __DYNAMIC__ (like battery or camera) may not be enabled due to hardware or browser restrictions.

  6. Register a Browser as a Home Assistant device

    master

    Registering a browser creates a Home Assistant Device with several associated entities. This allows the browser to act as a target for Browser Mod services.

    Associated Entities:

    • media_player: Plays sound and video. Attributes video_interaction_required and audio_interaction_required indicate if the user must interact with the browser before playback (e.g., for unmuted audio).
    • light: Controls screen brightness or on/off state. If using Fully Kiosk Browser (FKB), it controls the actual device hardware. Otherwise, it simulates the effect by covering the screen with a black/translucent box.
    • binary_sensor (motion): Reacts to mouse/keyboard activity. In FKB, it can also react to physical motion via the device camera.
    • Various sensor and binary_sensor entities providing browser metadata.

    Note: You can disable the media_player or light entities in Home Assistant to prevent Browser Mod from overriding your preferred settings (like adaptive brightness).

  8. Manage User interaction requirements

    master

    Due to browser restrictions, users often need to interact with a page before video or audio can play automatically. Browser Mod detects this via interaction tests.

    • Minimal Interaction: If muted video cannot play, an icon appears in the lower left. Clicking anywhere on the screen triggers a re-test.
    • Full user interaction: If minimal interaction fails (or if configured), a full-screen interaction prompt appears. Users must click a play button to pass the test.
    • Force full user interaction: Bypasses the minimal icon and forces the full-screen interaction prompt immediately on load.
    • Hide interaction icon: Hides the minimal interaction icon, but does not remove the actual requirement for interaction. You can monitor interaction needs via the video_interaction_required and audio_interaction_required attributes of the media_player entity.

  9. Configure popup styles in Browser Mod

    master

    Since version 2.6.0, Browser Mod popups are styled using three main parameters in the popup card configuration. You can use standard styles (normal, wide, fullscreen, classic) or define custom styles via popup_styles.

    1. initial_style: Sets the starting appearance of the popup. This can be a standard style or a custom style name defined in your popup_styles list.
    2. style_sequence: An ordered list of styles. When a user taps the popup title, the popup cycles through this list. If not set, the default is wide -> normal.
    3. popup_styles: A list of custom style definitions. Each entry allows you to name a style, include other existing styles, and inject custom CSS.

    To change styles programmatically, use the browser_mod.set_popup_style service.

    initial_style: centered
style_sequence:
  - centered-wide
  - fullscreen
  - centered
popup_styles:
  - style: centered
    include_styles:
      - classic
    styles: |
      ha-dialog {
        --dialog-surface-margin-top: auto !important;
      }

  10. Manage multiple popups with tags

    master

    By default, if you open a new popup while one is already showing, the current popup is dismissed and replaced by the new one (if they share the same or no tag).

    To stack popups (show a new one on top of the current one), assign a unique tag to the new popup. When the top popup is closed, the previous one will remain visible.

    Rules for tags:

    • Tags must be a lower-case alphanumeric string.
    • Use the tag parameter in the browser_mod.popup service call.
    • You can also use dismiss_icon to change the icon used to close the popup.

    Example of stacking popups:

    # Inside a button tap action (Browser call)
tap_action:
  action: fire-dom-event
  browser_mod:
    service: browser_mod.popup
    data:
      title: Second popup
      content: I am a popup with a tag.
      tag: lights
      dismiss_icon: mdi:chevron-left

  11. Set the Default dashboard

    master

    You can define which dashboard is shown when accessing the Home Assistant base URL. Browser Mod applies settings in the following priority (highest first):

    1. User: Any browser used by this specific user. Overrides Browser and Global settings.
    2. Browser: This specific registered browser, regardless of user. Overrides Global settings.
    3. Global: All browsers and all users.

    Note: Browser-level overrides require Sync Browser ID to login session to be enabled. When a Browser Mod default dashboard is active, the native 'Default Dashboard' row in the Home Assistant user profile will show a notice that Browser Mod is managing it.

  12. Use THIS replacements in Browser calls

    master

    When making a Browser call, you can use the keyword THIS in your data parameters to dynamically inject information about the current browser or user. This allows you to call Home Assistant scripts without hardcoding specific IDs.

    Available replacements:

    • browser_id: THIS -> Replaced with the current Browser's ID.
    • user_id: THIS -> Replaced with the logged-in user's ID.
    • browser_entities: THIS -> Replaced with a browser_entities dictionary.
    tap_action: # Browser call with THIS replacement of Browser ID
  action: fire-dom-event
  browser_mod:
    service: script.print_clicking_browser
    data:
      browser_id: THIS