Updated readme to V2
This commit is contained in:
parent
8dbd00aa0f
commit
2e696ecd30
912
README.md
912
README.md
@ -1,4 +1,4 @@
|
|||||||
# browser_mod
|
# browser_mod 2.0
|
||||||
|
|
||||||
[](https://github.com/custom-components/hacs)
|
[](https://github.com/custom-components/hacs)
|
||||||
|
|
||||||
@ -16,634 +16,410 @@ For more usage examples, see the [cookbook](https://github.com/thomasloven/hass-
|
|||||||
|
|
||||||
# Installation instructions
|
# Installation instructions
|
||||||
|
|
||||||
- Copy the contents of `custom_components/browser_mod/` to `<your config dir>/custom_components/browser_mod/`.
|
- **First make sure you have completely removed any installation of Browser Mod 1**
|
||||||
|
|
||||||
- Add the following to your `configuration.yaml`:
|
- Either
|
||||||
|
|
||||||
```yaml
|
- Find and install Browser Mod under `integrations`in [HACS](https://hacs.xyz)
|
||||||
browser_mod:
|
- OR copy the contents of `custom_components/browser_mod/` to `<your config dir>/custom_components/browser_mod/`.
|
||||||
```
|
|
||||||
|
|
||||||
- Restart Home Assistant
|
- Restart Home Assistant
|
||||||
|
|
||||||
> Note: If you want to use browser_mod with Home Assistant Cast, you need to also add:
|
- Add the "Browser Mod" integration in Settings -> Devices & Services -> Add Integration or click this button: [](https://my.home-assistant.io/redirect/config_flow_start/?domain=browser_mod)
|
||||||
|
|
||||||
|
- Restart Home Assistant
|
||||||
|
|
||||||
|
# Browser Mod Panel
|
||||||
|
|
||||||
|
When you're logged in as an administrator you should see a new panel called _Browser Mod_ in the sidebar. This is where you controll any Browser Mod settings.
|
||||||
|
|
||||||
|
## This browser
|
||||||
|
|
||||||
|
A basic concept for Browser Mod is the _Browser_. A _Browser_ is identified by a unique `BrowserID` stored in the browsers [LocalStorage](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API).
|
||||||
|
|
||||||
|
Browser Mod will initially assigning a random `BrowserID` to each _Browser_ that connects, but you can change this if you want.
|
||||||
|
|
||||||
|
LocalStorage works basically like cookies in that the information is stored locally on your device. Unlike a cookie, though, the information is bound to a URL. Therefore you may get different `BrowserID`s in the same browser if you e.g. access Home Assistant through different URLs inside and outside of your LAN, or through Home Assistant Cloud.
|
||||||
|
|
||||||
|
### Register
|
||||||
|
|
||||||
|
Registering a _Browser_ as a device will create a Home Assistant Device associated with that browser. The device has the following entities:
|
||||||
|
|
||||||
|
- A `media_player` entitiy which will play sound through the browser.
|
||||||
|
- A `light` entity will turn the screen on or off and controll the brightness if you are using [Fully Kiosk Browser](https://www.fully-kiosk.com/) (FKB). If you are not using FKB the function will be simulated by covering the screen with a black (or semitransparent) box.
|
||||||
|
- A motion `binary_sensor` which reacts to mouse and/or keyboard activity in the Browser. In FKB this can also react to motion in front of the devices camera.
|
||||||
|
- A number of `sensor` and `binary_sensor` entities providing different bits of information about the Browser which you may or may not find useful.
|
||||||
|
|
||||||
|
Registering a browser also enables it to act as a target for Browser Mod _services_.
|
||||||
|
|
||||||
|
### BrowserId
|
||||||
|
|
||||||
|
This box lets you set the `BrowserID` for the current _Browser_.
|
||||||
|
Note that it is possible to assign the same `BrowserID` to several browsers, but unpredictable things _may_ happen if several of them are open at the same time.
|
||||||
|
There may be benefits to using the same `BrowserID` in some cases, so you'll have to experiment with what works for you.
|
||||||
|
|
||||||
|
### Enable camera
|
||||||
|
|
||||||
|
If your device has a camera, this will allow it to be forwarded as a `camera` entity to Home Assistant.
|
||||||
|
|
||||||
|
## Registered Browsers
|
||||||
|
|
||||||
|
This section shows all currently registered _Browsers_ and allows you to unregister them. This is useful e.g. if a `BrowserID` has changed or if you do not have access to a device anymore.
|
||||||
|
|
||||||
|
### Register CAST browser
|
||||||
|
|
||||||
|
If you are using [Home Assistant Cast](https://www.home-assistant.io/integrations/cast/#home-assistant-cast) to display a lovelace view on a Chromecast device it will get a BrowserID of "`CAST`". Since you can't access the Browser Mod config panel from the device, clicking this button will register the `CAST` browser. Most Browser Mod services will work under Home Assistant Cast.
|
||||||
|
|
||||||
|
## Frontend Settings
|
||||||
|
|
||||||
|
This section is for settings that change the default behavior of the Home Assistant frontend.
|
||||||
|
|
||||||
|
Each setting has three levels, _Global_, _Browser_ and _User_.
|
||||||
|
|
||||||
|
- Changes made on the _Global_ tab will be applied for everyone on every browser.
|
||||||
|
- Changes made on the _Browser_ tab will be applied for this _Browser_. The settings here override any _Global_ settings.
|
||||||
|
- Changes made on the _User_ tab will be applied for the user you're currently logged in as - on any device. The settings here override any _Global_ or _Browser_ settings.
|
||||||
|
|
||||||
|
Note that if a setting is set at a lower level but _cleared_ on a higher, it is not _undone_. It's just not overridden.
|
||||||
|
|
||||||
|
Also note that _User_ level settings can only be made when logged in as the user in question, and that the Browser Mod configuration panel is only available to administrators. If you need to change a setting for a non-admin user, you will need to temporarily make them admin for the setup, and then un-admin them.
|
||||||
|
|
||||||
|
### Favicon template
|
||||||
|
|
||||||
|
This allows you to set and dynamically update the favicon of the browser tab/window. I.e. the little icon next to the page title. Favicons can be .png or .ico files and should be placed in your `<config>/www` directory. The box here should then contain a jinja [template](https://www.home-assistant.io/docs/configuration/templating/) which resolves to the path of the icon with `<config>/www/` replaced by `/local/` (see [Hosting files](https://www.home-assistant.io/integrations/http/#hosting-files)).
|
||||||
|
|
||||||
|
> Ex:
|
||||||
>
|
>
|
||||||
> ```yaml
|
> ```jinja
|
||||||
> resources:
|
> {% if is_state("light.bed_light", "on") %}
|
||||||
> - url: /browser_mod.js
|
> /local/icons/green.png
|
||||||
> type: module
|
> {% else %}
|
||||||
|
> /local/icons/red.png
|
||||||
|
> {% endif %}
|
||||||
> ```
|
> ```
|
||||||
|
|
||||||
|
Note that this _only_ applies to the current favicon of the page, not any manifest icons such as the loading icon or the icon you get if you save the page to your smartphones homescreen. For those, please see the [hass-favicon](https://github.com/thomasloven/hass-favicon) integration.
|
||||||
|
|
||||||
|
### Title template
|
||||||
|
|
||||||
|
This allows you to set and dynamically update the title text of the browser tab/window by means on a Jinja [template](https://www.home-assistant.io/docs/configuration/templating/).
|
||||||
|
|
||||||
|
> Ex:
|
||||||
>
|
>
|
||||||
> to your `ui_lovelace.yaml`.
|
> ```jinja
|
||||||
> Don't worry about where to put browser_mod.js, the integration will handle that automatically, and please note that it's **not** `/local/browser_mod.js`.
|
> {{ states.persistent_notification | list | count}} - Home Assistant
|
||||||
|
> ```
|
||||||
|
|
||||||
# Usage
|
### Hide Sidebar
|
||||||
|
|
||||||
Here's a fantastic video summary of all `browser_mod` functions by Pinkywafer: [Youtube link](https://www.youtube.com/watch?v=atpIP2RYldA).
|
This will hide the sidebar wit the navigation links. You can still access all the pages via normal links.
|
||||||
|
|
||||||
## Devices
|
> Tip: add `/browser-mod` to the end of your home assistant URL when you need to turn this off again...
|
||||||
|
|
||||||
The most important concept of `browser_mod` is the _device_.
|
### Hide header
|
||||||
|
|
||||||
A _device_ is a machine-browser combination identified by a unique `deviceID`. The `deviceID` is randomly generated and may look like `ded3b4dc-abedd098`.
|
This will hide the header bar. Completely. It does not care if there are useful navigation links there or not. It's gone.
|
||||||
|
|
||||||
- Chrome on your desktop and Chrome on your laptop are two different _devices_.
|
> Tip: See the big yellow warning box at the top of this card? For some reason, it seems to be really easy to forget you turned this on. Please do not bother the Home Assistant team about the header bar missing if you have hidden it yourself. Really, I've forgotten multiple times myself.
|
||||||
- Chrome on your laptop and Safari on your laptop are two different _devices_.
|
|
||||||
- Two tabs in Firefox on the same computer is one _device_.
|
|
||||||
- Two windows in Edge on the same computer is one _device_.
|
|
||||||
|
|
||||||
In the two latter cases, the last loaded tab/window will be the _active_ one.
|
### Sidebar order
|
||||||
|
|
||||||
Note: Incognito mode will generate a new `deviceID` and thus a new _device_ every time it's started.
|
Did you know that you can change the order and hide items from the sidebar? To do so, either go into your profile settings at the bottom left and click "Change the order and hide items from the sidebar", or click and hold on the "Home Assistant" text at the top of the sidebar.
|
||||||
|
|
||||||
### Aliases
|
Normally, the order and hidden items only applies to the current device, but this will make it persistent according to the levels described above.
|
||||||
|
|
||||||
Since the deviceID can be a bit hard to remember for devices you use often, you can specify an alias in `configuration.yaml`
|
### Default dashboard
|
||||||
|
|
||||||
|
Like the Sidebar order, the default dashboard (the page shown when you simply access `https://<your home assistant url>/` with nothing after the `/`) can be set in your profile settings but only applies to the current device. This fixes that.
|
||||||
|
|
||||||
|
# Browser Mod Services
|
||||||
|
|
||||||
|
Browser Mod has a number of services you can call to cause things to happen in the target Browser.
|
||||||
|
|
||||||
|
<details><summary>Reading guide</summary>
|
||||||
|
Service parameters are described using the following conventions:
|
||||||
|
|
||||||
|
- `<type>` describes the type of a parameter, e.g.
|
||||||
|
|
||||||
|
- `<string>` is a piece of text
|
||||||
|
- `<number>` is a number
|
||||||
|
- `<TRUE/false>` means the value must be either `true` or `false` with `true` being the default
|
||||||
|
- `<service call>` means a full service call specification. Note that this can be any service, not just Browser Mod services
|
||||||
|
- `<Browser IDs>` is a list of BrowserIDs
|
||||||
|
|
||||||
|
- Square brackets `[ ]` indicate that a parameter is optional and can be omitted.
|
||||||
|
|
||||||
|
### `<service call>`
|
||||||
|
|
||||||
|
A service call is a combination of a service and it's data:
|
||||||
|
|
||||||
|
Ex, a `<service call>` for `browser_mod.more_info` with `light.bed_light` as entity:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
browser_mod:
|
service: browser_mod.more_info
|
||||||
devices:
|
|
||||||
99980b13-dabc9563:
|
|
||||||
name: arrakis
|
|
||||||
d2fc860c-16379d23:
|
|
||||||
name: dashboard
|
|
||||||
```
|
|
||||||
|
|
||||||
This binds the _aliases_ `arrakis` to `99980b13-dabc9563` and `dashboard` to `d2fc860c-16379d23`.
|
|
||||||
|
|
||||||
Note: Aliases must be unique.
|
|
||||||
|
|
||||||
#### Changing deviceID
|
|
||||||
|
|
||||||
You can change the deviceID of your device by adding a `browser-player` card to your lovelace interface and clicking the deviceID at the bottom of the card. Set it to `clear` to generate a new random one.
|
|
||||||
|
|
||||||
You can also set a deviceID by adding `?deviceID=mydeviceID` to the end of the URL you're using to access Home Assistant. Be careful - I have no idea what could happen if several devices were to have the same ID.
|
|
||||||
Use `?deviceID=clear` to generate a new random one.
|
|
||||||
|
|
||||||
**Take care to avoid deviceID collissions. There's no telling what could happen if more devices share the same ID.**
|
|
||||||
|
|
||||||
### Prefix
|
|
||||||
|
|
||||||
You can add a custom prefix to all entity ids in `configuration.yaml`:
|
|
||||||
|
|
||||||
E.g. to give entities default names like `media_player.browser_99980b13_dabc9563` add:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
browser_mod:
|
|
||||||
prefix: "browser_"
|
|
||||||
```
|
|
||||||
|
|
||||||
This does not apply to devices with an alias.
|
|
||||||
|
|
||||||
### Disabling entities
|
|
||||||
|
|
||||||
`browser_mod` creates a number of entities, which is explained below. In some cases, you may not want to do that. If so, add a list of entity types you do _not_ want to add to a `disable` section, either for each device, or globally to ignore for all unknown devices:
|
|
||||||
|
|
||||||
E.g. to disable the `light` and `media_player` for the device aliased to `arrakis`, AND disable _all_ entities for all devices which _don't_ have an alias:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
browser_mod:
|
|
||||||
devices:
|
|
||||||
99980b13-dabc9563:
|
|
||||||
name: arrakis
|
|
||||||
disable:
|
|
||||||
- light
|
|
||||||
- media_player
|
|
||||||
disable:
|
|
||||||
- all
|
|
||||||
```
|
|
||||||
|
|
||||||
## Entities
|
|
||||||
|
|
||||||
Once `browser_mod` is installed, loading up your Home Assistant frontend on a new _device_ will create three to five new devices.
|
|
||||||
|
|
||||||
- `sensor.<device>`
|
|
||||||
- `media_player.<device>`
|
|
||||||
- `light.<device>`
|
|
||||||
- If you've enabled it: `camera.<device>`
|
|
||||||
- If you're using Fully Kiosk Browser: `binary_sensor.<device>`
|
|
||||||
|
|
||||||
`<device>` here will be the `deviceID` of the _device_ but with the dash (`-`) replaced by an underscore (`_`). If you've defined an alias, it will be that instead.
|
|
||||||
|
|
||||||
E.g:
|
|
||||||
Connecting your phone with `deviceID: ded3b4dc-abedd098` will create the entities `sensor.ded3b4dc_abedd098`, `media_player.ded3b4dc_abedd098` and `light.ded3b4dc_abedd098`.
|
|
||||||
Connecting with the computer named `Arrakis` above with `deviceID: 99980b13-dabc9563` will create the entities `sensor.arrakis`, `media_player.arrakis` and `light.arrakis`.
|
|
||||||
|
|
||||||
<details><summary>sensor</summary>
|
|
||||||
The `sensor` will display the number of connected views (tabs/windows) of the device. Note that using multiple view isn't really recommended, and any action targeting a device will happen in the last loaded view.
|
|
||||||
|
|
||||||
The sensor also has the following attributes:
|
|
||||||
|
|
||||||
| attribute | content |
|
|
||||||
| --------------- | ------------------------------------------------------------------- |
|
|
||||||
| `type` | `browser_mod` |
|
|
||||||
| `last_seen` | The time when the _device_ was last seen |
|
|
||||||
| `deviceID` | The deviceID of the _device_. |
|
|
||||||
| `path` | The currently displayed path on the _device_. |
|
|
||||||
| `visibility` | Whether the frontend is currently visible on the _device_. |
|
|
||||||
| `userAgent` | The User Agent of the associated browser. |
|
|
||||||
| `currentUser` | The user currently logged in on the _device_. |
|
|
||||||
| `fullyKiosk` | True if the _device_ is a Fully Kiosk browser. Undefined otherwise. |
|
|
||||||
| `width` | The current width of the browser window in pixels. |
|
|
||||||
| `height` | The current height of the browser window in pixels. |
|
|
||||||
| `battery_level` | The current battery level of your device - if supported |
|
|
||||||
| `charging` | The current charging state of your device - if supported |
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
<details><summary>media_player</summary>
|
|
||||||
The `media_player` can be used to play sounds on the _device_.
|
|
||||||
|
|
||||||
**NOTE: Because Apple is Apple; on iOS you need to touch the screen once after loading the frontend before any playback will work.**
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
<details><summary>light</summary>
|
|
||||||
The `light` can be used to blackout the screen.
|
|
||||||
For Fully Kiosk Browser, the screen will actually turn off.
|
|
||||||
For other browsers, the interface will just be covered with black (the screen is still on, will have a visible glow in the dark, and you won't save any battery).
|
|
||||||
</details>
|
|
||||||
|
|
||||||
<details><summary>camera</summary>
|
|
||||||
For security and UX reasons, the camera must be enabled manually on a device by device basis.
|
|
||||||
|
|
||||||
> **NOTE:** Browser only allow access to the camera in secure contexts (since 2019). That means it only works if you access Home Assistant through `https://`, NOT `http://` or through `localhost`.
|
|
||||||
|
|
||||||
Enabling the camera is done by adding `camera: true` to the devices configuration in `configuration.yaml`:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
browser_mod:
|
|
||||||
devices:
|
|
||||||
99980b13-dabc9563:
|
|
||||||
name: arrakis
|
|
||||||
camera: true
|
|
||||||
d2fc860c-16379d23:
|
|
||||||
name: dashboard
|
|
||||||
```
|
|
||||||
|
|
||||||
After restarting Home Assistant (and [clearing cache](https://github.com/thomasloven/hass-config/wiki/Lovelace-Plugins#clearing-cache)), the next time you load your interface your browser will ask you if you want Home Assistant to be able to access your camera. Some browsers (e.g. mobile Safari) will ask every time you make a hard refresh.
|
|
||||||
|
|
||||||
Be aware that keeping the camera on may make your device run hot and drain your battery.
|
|
||||||
|
|
||||||
For Fully Kiosk Browser, the camera requires Motion Detection (PLUS) to be enabled, and will only appear for the first time once motion has been detected. It does not need to be enabled in the configuration, though.
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
<details><summary>binary_sensor</summary>
|
|
||||||
The `binary_sensor` will only be available for Fully Kiosk Browser PRO _devices_.
|
|
||||||
It's state will be the state of the camera motion detector of the _device_ (5 second cooldown).
|
|
||||||
</details>
|
|
||||||
|
|
||||||
## Commands
|
|
||||||
|
|
||||||
`browser_mod` has a number of commands that will perform various things for one or many _devices_.
|
|
||||||
|
|
||||||
### Calling commands
|
|
||||||
|
|
||||||
There are three ways of calling commands.
|
|
||||||
|
|
||||||
<details><summary>From the backend</summary>
|
|
||||||
This is how commands are called from scripts or automations.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
service: browser_mod.<command>
|
|
||||||
data:
|
data:
|
||||||
parameter: value
|
entity: light.bed_light
|
||||||
other_parameter: other value
|
|
||||||
deviceID:
|
|
||||||
- device1
|
|
||||||
- device2
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Note that `parameter` and `other_parameter` etc. depends on the command, but `deviceID` (which is optional) is available for all commands unless otherwise stated.
|
Seems obvious, hopefully.
|
||||||
|
|
||||||
`deviceID` shall be a list of device IDs that the command will be run on. \
|
|
||||||
If `deviceID` is not specified, the command will be run on ALL connected _devices_.
|
|
||||||
|
|
||||||
</details>
|
</details>
|
||||||
|
|
||||||
<details><summary>From the frontend via call-service</summary>
|
## Calling services
|
||||||
This is the same configuration as above, but for use in lovelace configurations, e.g. a [button card](https://www.home-assistant.io/lovelace/button/#tap-action).
|
|
||||||
|
Services can be called from the backend using the normal service call procedures. Registered Browsers can be selected as targets through their device:
|
||||||
|
|
||||||
|
|
||||||
|
In yaml, the BrowserID can be used for targeting a specific browser:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
tap_action:
|
service: browser_mod.more_info
|
||||||
action: call-service
|
data:
|
||||||
service: browser_mod.<command>
|
entity: light.bed_light
|
||||||
service_data:
|
browser_id:
|
||||||
parameter: value
|
- 79be65e8-f06c78f
|
||||||
other_parameter: other value
|
|
||||||
deviceID:
|
|
||||||
- device1
|
|
||||||
- device2
|
|
||||||
```
|
```
|
||||||
|
|
||||||
If `deviceID` is not specified, the command will be run on ALL connected _devices_.
|
If no target or `browser_id` is specified, the service will target all registerd Browsers.
|
||||||
|
|
||||||
</details>
|
To call a service from a dashboard use the call-service [action](https://www.home-assistant.io/dashboards/actions/) or the special action `fire-dom-event`:
|
||||||
|
|
||||||
<details><summary>From the frontend via fire-dom-event</summary>
|
|
||||||
When using this as a `tap_action`, the command will be run on ONLY the _device_ the command that was tapped.
|
|
||||||
|
|
||||||
`deviceID` will be ignored.
|
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
tap_action:
|
tap_action:
|
||||||
action: fire-dom-event
|
action: fire-dom-event
|
||||||
browser_mod:
|
browser_mod:
|
||||||
command: <command>
|
service: browser_mod.more_info
|
||||||
parameter: value
|
|
||||||
other_parameter: other value
|
|
||||||
```
|
|
||||||
|
|
||||||
> Note: This works for [`tap_action`, `hold_action` and `double_tap_action`](https://www.home-assistant.io/lovelace/actions/) for all core Lovelace cards, but may not be supported by all custom cards yet.
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
### Available commands
|
|
||||||
|
|
||||||
<details><summary>debug</summary>
|
|
||||||
Display a popup with the deviceID _and_ a javascript alert with the deviceID on all connected _devices_.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
service: browser_mod.debug
|
|
||||||
```
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
<details><summary>set_theme</summary>
|
|
||||||
Set the current theme.
|
|
||||||
|
|
||||||
This changes the _frontend_ setting - the same as if you click your initials in the bottom left corner and pick a theme from there.
|
|
||||||
|
|
||||||
Parameters:
|
|
||||||
|
|
||||||
- `theme` - the name of the theme to set
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
service: browser_mod.set_theme
|
|
||||||
data:
|
|
||||||
theme: clear_light
|
|
||||||
```
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
<details><summary>navigate</summary>
|
|
||||||
Navigate to a different view or panel.
|
|
||||||
|
|
||||||
Works like the `navigate` `tap_action`.
|
|
||||||
|
|
||||||
Parameters:
|
|
||||||
|
|
||||||
- `navigation_path` - the path to navigate to
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
service: browser_mod.navigate
|
|
||||||
data:
|
|
||||||
navigation_path: /lovelace/1
|
|
||||||
```
|
|
||||||
|
|
||||||
Note: `navigation_path` does not have to be a lovelace path. All paths in Home Assistant works. (E.g. `/states`, `/dev-info`, `/map`)
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
<details><summary>more_info</summary>
|
|
||||||
Displays the more-info dialog for an entity.
|
|
||||||
|
|
||||||
Parameters:
|
|
||||||
|
|
||||||
- `entity_id` - the entity whose more-info dialog should be opened.
|
|
||||||
- `large` - if set to `true` will make the popup wider. (**optional**, default: `false`)
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
service: browser_mod.more_info
|
|
||||||
data:
|
|
||||||
entity_id: camera.front_door
|
|
||||||
```
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
<details><summary>toast</summary>
|
|
||||||
Display a notification toast.
|
|
||||||
|
|
||||||
Parameters:
|
|
||||||
|
|
||||||
- `message` - the message to display
|
|
||||||
- `duration` - time in ms the toast is shown. (**optional**, default: 3000)
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
service: browser_mod.toast
|
|
||||||
data:
|
|
||||||
message: Short message
|
|
||||||
```
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
<details><summary>popup</summary>
|
|
||||||
Display a lovelace card as a popup over the interface.
|
|
||||||
|
|
||||||
Parameters:
|
|
||||||
|
|
||||||
- `title` - heading text
|
|
||||||
- `card` - Lovelace card configuration
|
|
||||||
- `large` - if set to `true` will make the popup wider. (**optional**, default: `false`)
|
|
||||||
- `hide_header` - if set to `true` will hide the header bar and close button (**optional**, default: `false`)
|
|
||||||
- `auto_close` - if set to `true` the popup will close automatically when the mouse or keyboard is touched. Also hides the header. (**optional**, default: `false`)
|
|
||||||
- `time` - if used with `auto_close` will turn the popup into a "screensaver". See the `blackout` command
|
|
||||||
- `style` - see below
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
service: browser_mod.popup
|
|
||||||
data:
|
|
||||||
title: Popup example
|
|
||||||
card:
|
|
||||||
type: entities
|
|
||||||
entities:
|
|
||||||
- light.bed_light
|
|
||||||
- light.kitchen_lights
|
|
||||||
- light.ceiling_lights
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
If [card-mod](https://github.com/thomasloven/lovelace-card-mod) is installed, the popup can be styled by the optional `style` parameter, or by the `card-mod-more-info[-yaml]` theme variable.
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
<details><summary>close_popup</summary>
|
|
||||||
Will close all more-info dialogs and popups that are open.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
service: browser_mod.close_popup
|
|
||||||
```
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
<details><summary>blackout</summary>
|
|
||||||
Will cover the entire browser window with a black box. \
|
|
||||||
Moving the mouse, touching the screen or pressing any key will restore the view.
|
|
||||||
|
|
||||||
> Note: This will _not_ turn off your screen backlight. Most screens will still emit light in a dark room.
|
|
||||||
|
|
||||||
Parameters:
|
|
||||||
|
|
||||||
- `time` - if set, the blackout will turn on automatically after this many seconds of inactivity. Kind of like a screensaver. Call the `blackout` command with `time` set to `-1` to disable. (**Optional**, default: None)
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
service: browser_mod.blackout
|
|
||||||
```
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
<details><summary>no_blackout</summary>
|
|
||||||
Remove a blackout.
|
|
||||||
|
|
||||||
Parameters:
|
|
||||||
|
|
||||||
- `brightness` - will set the screen brightness in Fully Kiosk Browser to a value between 0 and 255 (**Optional**, default: none)
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
service: browser_mod.no_blackout
|
|
||||||
```
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
<details><summary>lovelace_reload</summary>
|
|
||||||
Refreshes the lovelace config. Same as clicking "Refresh" in the top right menu in lovelace.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
service: browser_mod.lovelace_reload
|
|
||||||
```
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
<details><summary>window_reload</summary>
|
|
||||||
Forces the browser to reload the page. Same as clicking your browser's refresh button.
|
|
||||||
|
|
||||||
> Note: This is not guaranteed to clear the frontend cache.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
service: browser_mod.window_reload
|
|
||||||
```
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
<details><summary>command</summary>
|
|
||||||
This command is deprecated and left in for backwards compatibility
|
|
||||||
</details>
|
|
||||||
|
|
||||||
<details><summary>commands</summary>
|
|
||||||
Command**s** with an **s**. Will call a list of commands consecutively.
|
|
||||||
|
|
||||||
This is mostly useful with the `fire-dom-event` method of calling commands.
|
|
||||||
|
|
||||||
Parameters:
|
|
||||||
|
|
||||||
- `commands` - list of `browser_mod` commands to perform.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
service: browser_mod.commands
|
|
||||||
data:
|
|
||||||
commands:
|
|
||||||
- command: <command>
|
|
||||||
<parameters>
|
|
||||||
- command: <command>
|
|
||||||
<parameters>
|
|
||||||
```
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
<details><summary>delay</summary>
|
|
||||||
Do nothing for a specified time.
|
|
||||||
Most useful with the `commands` command.
|
|
||||||
|
|
||||||
Parameters:
|
|
||||||
|
|
||||||
- `seconds` - number of seconds to wait
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
service: browser_mod.commands
|
|
||||||
data:
|
|
||||||
commands:
|
|
||||||
- command: blackout
|
|
||||||
- command: delay
|
|
||||||
seconds: 5
|
|
||||||
- command: no_blackout
|
|
||||||
```
|
|
||||||
|
|
||||||
</details>
|
|
||||||
|
|
||||||
<details><summary>call_service</summary>
|
|
||||||
This command is **only** runnable through `fire-dom-event`.
|
|
||||||
Will call a Home Assistant service but will replace `deviceID: this` with the deviceID of the current _device_.
|
|
||||||
|
|
||||||
Parameters:
|
|
||||||
|
|
||||||
- `service` - the service to call
|
|
||||||
- `service_data` - data for the service
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
command: call-service
|
|
||||||
service: script.do_stuff
|
|
||||||
service_data:
|
|
||||||
some_variable: 42
|
|
||||||
deviceID: this
|
|
||||||
```
|
|
||||||
|
|
||||||
Example script:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
sequence:
|
|
||||||
- service: system_log.write
|
|
||||||
data:
|
data:
|
||||||
message: "The do_stuff script was called from the device {{ deviceID }}"
|
entity: light.bed_light
|
||||||
```
|
```
|
||||||
|
|
||||||
</details>
|
Services called via `fire-dom-event` or called as a part of a different service call will (by default) _only_ target the current Browser (even if it's not registered).
|
||||||
|
|
||||||
# `browser-player` card
|
Finally, in service calls via `fire-dom-event` or as part of a different service call, the following a parameter `browser_id` with the value `THIS` will be replaced with the current Browsers browser ID.
|
||||||
|
|
||||||
To control the playback in the current _device_, `browser_mod` includes a custom lovelace card. Just add
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
type: custom:browser-player
|
|
||||||
```
|
|
||||||
|
|
||||||
anywhere in your lovelace configuration.
|
|
||||||
|
|
||||||
The player card also displays the `entityID`. Click it to change it.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
# Fully Kiosk Browser
|
|
||||||
|
|
||||||
If you are using a device running [Fully Kiosk Browser](https://www.ozerov.de/fully-kiosk-browser/) (PLUS version only) you will have access to a few more functions.
|
|
||||||
|
|
||||||
For this to work you need to activate `Settings->Advanced Web Settings->Javascript Interface (PLUS)` and `Settings->Motion Detection (PLUS)->Enable Visual Motion Detection`.
|
|
||||||
|
|
||||||
First of all the commands `blackout` and `no-blackout` will control the devices screen directly.
|
|
||||||
`no-blackout` also has an optional parameter `brightness` that can set the screen brightness between 0 and 255.
|
|
||||||
|
|
||||||
Second, there are a few more attributes available
|
|
||||||
|
|
||||||
| attribute | content |
|
|
||||||
| --------------- | ---------------------------------------------------------------------------- |
|
|
||||||
| `fullyKiosk` | True. |
|
|
||||||
| `brightness` | The current screen brightness. |
|
|
||||||
| `battery_level` | The current charge percentage of the devices battery. |
|
|
||||||
| `charging` | Whether the battery is currently charging. |
|
|
||||||
| `motion` | Whether the devices camera has detected any motion in the last five seconds. |
|
|
||||||
|
|
||||||
# Replacing more-info dialogs
|
|
||||||
|
|
||||||
With browser_mod, you can replace any more-info dialog with any lovelace card you choose yourself. This can be done either per lovelace view, or globally (even outside of lovelace).
|
|
||||||
|
|
||||||
The replacement is included in your lovelace or lovelace view configuration, and the syntax is exactly like the `popup` service, except you can't use `auto_close` or `time`.
|
|
||||||
|
|
||||||
Ex:
|
Ex:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
views:
|
tap_action:
|
||||||
- title: Home view
|
action: fire-dom-event
|
||||||
icon: mdi:house
|
browser_mod:
|
||||||
popup_cards:
|
service: script.print_clicking_browser
|
||||||
light.ceiling_light:
|
data:
|
||||||
title: My popup
|
browser_id: THIS
|
||||||
card:
|
|
||||||
type: entities
|
|
||||||
entities:
|
|
||||||
- light.ceiling_light_bulb1
|
|
||||||
- light.ceiling_light_bulb2
|
|
||||||
- light.ceiling_light_bulb3
|
|
||||||
- light.ceiling_light_bulb4
|
|
||||||
```
|
```
|
||||||
|
|
||||||
This would show an entities card with four bulbs any time the more-info dialog for `light.ceiling_light` would normally be shown when you're on the Home view in lovelace.
|
with the script:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
title: My home
|
script:
|
||||||
resources:
|
print_clicking_browser:
|
||||||
- url: /local/card-mod.js
|
sequence:
|
||||||
type: module
|
- service: system_log.write
|
||||||
popup_cards:
|
data:
|
||||||
sensor.sensor1:
|
message: "Button was clicked in {{browser_id}}"
|
||||||
title: First sensor
|
|
||||||
card:
|
|
||||||
type: gauge
|
|
||||||
entity: sensor.sensor1
|
|
||||||
sensor.sensor2:
|
|
||||||
title: Second sensor
|
|
||||||
card:
|
|
||||||
type: gauge
|
|
||||||
entity: sensor.sensor2
|
|
||||||
```
|
```
|
||||||
|
|
||||||
This would replace the more-info dialogs of `sensor.sensor1` and `sensor.sensor2` anywhere in your interface. Even outside of lovelace - be careful about that.
|
Will print `"Button was clicked in 79be65e8-f06c78f" to the Home Assistant log.
|
||||||
|
|
||||||
# Support
|
## Services
|
||||||
|
|
||||||
[Home Assistant community forum thread](https://community.home-assistant.io/t/browser-mod-turn-your-browser-into-a-controllable-device-and-a-media-player/123806)
|
### `browser_mod.navigate`
|
||||||
|
|
||||||
# FAQ
|
|
||||||
|
|
||||||
### Where can I find my deviceID?
|
|
||||||
|
|
||||||
The easiest way is to go to `/developer-tools/service` and call the `browser_mod.debug` service.
|
|
||||||
|
|
||||||
But you can also find the device id on the `browser-player` card, if you added one to your lovelace config.
|
|
||||||
|
|
||||||
An alternative way is to type `localStorage["lovelace-player-device-id"]` into your browsers console.
|
|
||||||
|
|
||||||
### Does this replace lovelace-player and lovelace-browser-commander
|
|
||||||
|
|
||||||
Yes.
|
|
||||||
|
|
||||||
Some improvements
|
|
||||||
|
|
||||||
- With the backend support `browser_mod` does the same things as both of those, but better.
|
|
||||||
- Since `browser_mod` uses a service for executing commands rather than events, the commands can be easily triggered by any lovelace element which has a `tap_action` setting.
|
|
||||||
This actually means it pretty much replaces `popup-card` as well.
|
|
||||||
- `browser_mod` uses websockets to get immediate feedback from the _device_ to the backend and much better tracking of disconnects.
|
|
||||||
- _Aliases_. 'nuff said.
|
|
||||||
- `browser_mod` works outside of `/lovelace`.
|
|
||||||
- This works even if the currently logged in user is not in the admin group.
|
|
||||||
|
|
||||||
### Does this replace lovelace-fullykiosk
|
|
||||||
|
|
||||||
Yes. You need the paid version, btw.
|
|
||||||
|
|
||||||
### Can the deviceID be used to track me across the internet
|
|
||||||
|
|
||||||
No\*. The device is stored in your browsers localStorage - a data store which is sandboxed only to Home Assistant. That means only Home Assistant can access it. Furthermore, different Home Assistant installations cannot acces each others localStorage.
|
|
||||||
|
|
||||||
Some of [my lovelace plugins](https://github.com/thomasloven/hass-config/wiki/My-Lovelace-Plugins) use the device to do different things for different _devices_.
|
|
||||||
|
|
||||||
> _\*There is one exception. If you are using [Fully Kiosk Browser](https://www.ozerov.de/fully-kiosk-browser/), the deviceID is taken from the browser instead of being randomly generated. This deviceID will be the same for each website that asks for it._
|
|
||||||
|
|
||||||
### My Fully Kiosk Browser device goes unavailable after the screen has been turned off for five minutes
|
|
||||||
|
|
||||||
This seems to be a problem with Android, and not much to do about it.
|
|
||||||
As a workaround you can add the following to your configuration:
|
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
browser_mod:
|
service: browser_mod.navigate
|
||||||
devices:
|
data:
|
||||||
d2fc860c-16379d23: # DeviceID of your FKB device
|
path: <string>
|
||||||
force_stay_awake: true
|
[browser_id: <Browser IDs>]
|
||||||
```
|
```
|
||||||
|
|
||||||
That will make the screen turn on and off again for a second regularly to stop the five minute timer from running out.
|
This will point the browser to the Home Assistant path given as `path`.
|
||||||
|
E.g. `/lovelace/`, `/my-dashboard/bedroom`, `/browser_mod/`, `/config/devices/device/20911cc5a63b1caafa2089618545eb8a`...
|
||||||
|
|
||||||
Optionally, you can make the screen black by using the Screensaver instead of turning the screen off. In that case, you can set the `light` entity to control and respond to the screensaver rather than the screen state through:
|
### `browser_mod.refresh`
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
browser_mod:
|
service: browser_mod.refresh
|
||||||
devices:
|
data:
|
||||||
d2fc860c-16379d23: # DeviceID of your FKB device
|
[browser_id: <Browser IDs>]
|
||||||
screensaver: true
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
This will reload the current page.
|
||||||
|
|
||||||
|
### `browser_mod.more_info`
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
service: browser_mod.more_info
|
||||||
|
data:
|
||||||
|
entity: <string>
|
||||||
|
[large: <true/FALSE>]
|
||||||
|
[ignore_popup_card: <true/FALSE>]
|
||||||
|
[browser_id: <Browser IDs>]
|
||||||
|
```
|
||||||
|
|
||||||
|
This will show the more-info dialog for `entity`. \
|
||||||
|
If `large` is true it will be displayed wider (as if you had clicked the name in the dialog). \
|
||||||
|
If `ignore_popup_card` is true the more-info dialog will be shown even if it is currently overriden by a popup-card.
|
||||||
|
|
||||||
|
### `browser_mod.popup`
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
service: browser_mod.popup
|
||||||
|
data:
|
||||||
|
[title: <string>]
|
||||||
|
content: <string / Dashboard card configuration>
|
||||||
|
[size: <NORMAL/wide/fullscreen>]
|
||||||
|
[right_button: <string>]
|
||||||
|
[right_button_action: <service call>]
|
||||||
|
[left_button: <string>]
|
||||||
|
[left_button_action: <service call>]
|
||||||
|
[dismissable: <TRUE/false>]
|
||||||
|
[dismiss_action: <service call>]
|
||||||
|
[timeout: <number>]
|
||||||
|
[timeout_action: <service call>]
|
||||||
|
[style: <string>]
|
||||||
|
[browser_id: <Browser IDs>]
|
||||||
|
```
|
||||||
|
|
||||||
|
This will display a popup dialog. \
|
||||||
|
`content` may be either some text (including HTML) or a dashboard card configuration. \
|
||||||
|
If `size` is `wide` or `fullscreen` the card will be displayed wider or covering the entire window. \
|
||||||
|
`right_button` and `left_button` specify the text of two action buttons. \
|
||||||
|
When either action button is clicked, the dialog is closed and the service specified as `right_button_action` or `left_button_action` is called. \
|
||||||
|
If `dismissable` is false, the dialog cannot be closed by the user without clicking either action button. If it is true and the dialog is dismissed, `dismiss_action` is called. \
|
||||||
|
If `timeout` is specified the dialog will close automatically after `timeout` milliseconds, at which point `timeout_action` will be called. \
|
||||||
|
Finally, `style` lets you specify some CSS styles to apply to the dialog itself (to style a card in the dialog check out [card-mod](https://github.com/thomasloven/lovelace-card-mod))
|
||||||
|
|
||||||
|
Note that any Browser Mod services performed as `_action`s here will be performed only on the same Browser as initiated the action unless `browser_id` is given.
|
||||||
|
|
||||||
|
Ex:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
service: browser_mod.popup
|
||||||
|
data:
|
||||||
|
title: The title
|
||||||
|
content: The content
|
||||||
|
right_button: Right button
|
||||||
|
left_button: Left button
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
service: browser_mod.popup
|
||||||
|
data:
|
||||||
|
title: The title
|
||||||
|
right_button: Right button
|
||||||
|
left_button: Left button
|
||||||
|
content:
|
||||||
|
type: entities
|
||||||
|
entities:
|
||||||
|
- light.bed_light
|
||||||
|
- light.ceiling_lights
|
||||||
|
- light.kitchen_lights
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
service: browser_mod.popup
|
||||||
|
data:
|
||||||
|
content: Do you want to turn the light on?
|
||||||
|
right_button: "Yes"
|
||||||
|
left_button: "No"
|
||||||
|
right_button_action:
|
||||||
|
service: light.turn_on
|
||||||
|
data:
|
||||||
|
entity_id: light.bed_light
|
||||||
|
left_button_action:
|
||||||
|
service: browser_mod.popup
|
||||||
|
data:
|
||||||
|
title: Really?
|
||||||
|
content: Are you sure?
|
||||||
|
right_button: "Yes"
|
||||||
|
left_button: "No"
|
||||||
|
right_button_action:
|
||||||
|
service: browser_mod.popup
|
||||||
|
data:
|
||||||
|
content: Fine, live in darkness.
|
||||||
|
dismissable: false
|
||||||
|
title: Ok
|
||||||
|
timeout: 3000
|
||||||
|
left_button_action:
|
||||||
|
service: light.turn_on
|
||||||
|
data:
|
||||||
|
entity_id: light.bed_light
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### `browser_mod.close_popup`
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
service: browser_mod.close_popup
|
||||||
|
data:
|
||||||
|
[browser_id: <Browser IDs>]
|
||||||
|
```
|
||||||
|
|
||||||
|
This will close any currently open popup or more-info dialogs.
|
||||||
|
|
||||||
|
### `browser_mod.sequence`
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
service: browser_mod.sequence
|
||||||
|
data:
|
||||||
|
sequence:
|
||||||
|
- <service call>
|
||||||
|
- <service call>
|
||||||
|
- ...
|
||||||
|
[browser_id: <Browser IDs>]
|
||||||
|
```
|
||||||
|
|
||||||
|
This will perform the listed servie calls one after the other.
|
||||||
|
|
||||||
|
Note that if `browser_id` is omitted in the service calls listed in `sequence` the services will be performed on the Browser that's targeted as a whole rather than all browsers.
|
||||||
|
|
||||||
|
### `browser_mod.delay`
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
service: browser_mod.delay
|
||||||
|
data:
|
||||||
|
time: <number>
|
||||||
|
[browser_id: <Browser IDs>]
|
||||||
|
```
|
||||||
|
|
||||||
|
This will wait for `time` millliseconds. It's probably most useful as part of a `browser_mod.sequence` call...
|
||||||
|
|
||||||
|
### `browsermod.console`
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
service: browser_mod.console
|
||||||
|
data:
|
||||||
|
message: <string>
|
||||||
|
[browser_id: <Browser IDs>]
|
||||||
|
```
|
||||||
|
|
||||||
|
This will print `message` to the console of the target Browser.
|
||||||
|
|
||||||
|
### `browsermod.javascript`
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
service: browser_mod.console
|
||||||
|
data:
|
||||||
|
code: <string>
|
||||||
|
[browser_id: <Browser IDs>]
|
||||||
|
```
|
||||||
|
|
||||||
|
This will run the arbitrary javascript `code` in the target Browser.
|
||||||
|
|
||||||
|
Only use this one if you know what you're doing.
|
||||||
|
|
||||||
|
|
||||||
|
# Popup card
|
||||||
|
|
||||||
|
Add a popup card to a lovelace view (via the GUI) and it will override the more-info dialog for the given entity. Try it. More info to come.
|
||||||
|
|
||||||
|
# Browser Player
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
<a href="https://www.buymeacoffee.com/uqD6KHCdJ" target="_blank"><img src="https://www.buymeacoffee.com/assets/img/custom_images/white_img.png" alt="Buy Me A Coffee" style="height: auto !important;width: auto !important;" ></a>
|
<a href="https://www.buymeacoffee.com/uqD6KHCdJ" target="_blank"><img src="https://www.buymeacoffee.com/assets/img/custom_images/white_img.png" alt="Buy Me A Coffee" style="height: auto !important;width: auto !important;" ></a>
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user