Add initial documentation.

README.md

@@ -114,6 +114,9 @@ See the [fully expanded cameras configuration example](#config-expanded-cameras)
 | `webrtc_card` | | :heavy_multiplication_x: | The WebRTC entity/URL to use for this camera with the `webrtc-card` live provider. See below. |
 | `id` | `camera_entity`, `webrtc_card.entity` or `camera_name` if set (in that preference order). | :heavy_multiplication_x: | An optional identifier to use throughout the card configuration to refer unambiguously to this camera. See [camera IDs](#camera-ids). |
 | `dependent_cameras` | | :heavy_multiplication_x: | An optional array of other camera identifiers (see [camera IDs](#camera-ids)). If specified the card will fetch events for this camera and *also* recursively events for the named `dependent_cameras`. All `dependent_cameras` must themselves be a configured camera in the card. This can be useful to group events for cameras that are close together, or to show events for the `birdseye` camera that otherwise would not have events itself.|
+| `trigger_by_motion` | `false` | :heavy_multiplication_x: | Whether to not to trigger the camera (see [scan mode](#scan-mode)) by automatically detecting and using the motion `binary_sensor` for this camera. This autodetection only works for Frigate cameras, and only when the motion `binary_sensor` entity has been enabled in Home Assistant.|
+| `trigger_by_occupancy` | `true` | :heavy_multiplication_x: | Whether to not to trigger the camera (see [scan mode](#scan-mode)) by automatically detecting and using the occupancy `binary_sensor` for this camera. This autodetection only works for Frigate cameras, and only when the occupancy `binary_sensor` entity has been enabled in Home Assistant.|
+| `trigger_by_entities` | | :heavy_multiplication_x: | Whether to not to trigger the camera (see [scan mode](#scan-mode)) when the state of any Home Assistant entity becomes active (i.e. state becomes `on` or `open`). This works for Frigate or non-Frigate cameras.|
 
 <a name="live-providers"></a>
 
@@ -174,7 +177,29 @@ See the [fully expanded view configuration example](#config-expanded-view) for h
 | `update_entities` | | :white_check_mark: | **YAML only**: A list of entity ids that should cause the view to reset to the default. See [card updates](#card-updates) below for behavior and usecases.|
 | `update_cycle_camera` | `false` | :white_check_mark: | When set to `true` the selected camera is cycled on each default view change. |
 | `render_entities` | | :white_check_mark: | **YAML only**: A list of entity ids that should cause the card to re-render 'in-place'. The view/camera is not changed. `update_*` flags do not pertain/relate to the behavior of this flag. This should **very** rarely be needed, but could be useful if the card is both setting and changing HA state of the same object as could be the case for some complex `card_mod` scenarios ([example](https://github.com/dermotduffy/frigate-hass-card/issues/343)). |
+| `scan` | | :white_check_mark: | Configuration for [scan mode](#scan-mode). |
 | `actions` | | :white_check_mark: | Actions to use for all views, individual actions may be overriden by view-specific actions. See [actions](#actions) below.|
+
+<a name="scan-mode"></a>
+
+#### View: Scan Mode configuration
+
+All configuration is under:
+
+```yaml
+view:
+  scan:
+```
+
+Scan mode allows the card to automatically "follow the action". In this mode the card will automatically select a camera to view when it is triggered (as defined by your camera configuration, see `trigger_by_motion`, `trigger_by_occupancy` and `trigger_by_entities` parameters). When the camera untriggers, the camera selection will return to the next most recently triggered camera (as long as it is still triggered) -- if there are no triggered cameras remaining, the camera will return to the default. Triggering is only allowed when there is no ongoing human interaction with the card -- interaction will automatically untrigger it and further triggering will not occur until after the card has been unattended for `view.timeout_seconds`. 
+
+Scan mode tracks Home Assistant state changes -- when the card is first started, it takes a positive change in state to trigger (i.e. an already occupied room will not trigger it, but a newly occupied room would trigger it).
+
+| Option | Default | Overridable | Description |
+| - | - | - | - |
+| `enabled` | `false` | :white_check_mark: | Whether to enable scan mode. |
+| `show_trigger_status` | `true` | :white_check_mark: | Whether or not the card should show a visual indication that it is triggered (a pulsing border around the card edge). |
+
 ### Menu Options
 
 All configuration is under:
@@ -921,6 +946,10 @@ cameras:
     # Show events for camera-2 when this camera is viewed.
     dependent_cameras:
       - camera-2
+    trigger_by_motion: false
+    trigger_by_occupancy: true
+    trigger_by_entities:
+      - binary_sensor.front_door_sensor
   - frigate_url: http://my-other.frigate.local
     client_id: frigate-other
     camera_name: entrance
@@ -935,6 +964,10 @@ cameras:
     webrtc_card:
       entity: camera.entrance_rtsp
       url: 'rtsp://username:password@camera:554/av_stream/ch0'
+    trigger_by_motion: false
+    trigger_by_occupancy: true
+    trigger_by_entities:
+      - binary_sensor.entrance_sensor
 ```
 </details>
 
@@ -958,6 +991,9 @@ view:
   render_entities:
     - switch.render_card
   dark_mode: 'off'
+  scan:
+    enabled: false
+    show_trigger_status: true
   actions:
     entity: light.office_main_lights
     tap_action:
@@ -2365,6 +2401,30 @@ cameras:
 ```
 </details>
 
+### Using Scan Mode
+
+Have your card follow the action with Scan Mode.
+
+<details>
+  <summary>Expand: Using scan mode</summary>
+
+```yaml
+type: custom:frigate-card
+cameras:
+  - camera_entity: camera.back_yard
+    # This camera will automatically trigger by occupancy.
+  - camera_entity: camera.front_door
+    trigger_by_occupancy: false
+    trigger_by_motion: true
+    trigger_by_entities:
+      - binary_sensor.door_opened
+view:
+  scan:
+    enabled: true
+    trigger_show_border: true
+```
+</details>
+
 <a name="card-updates"></a>
 
 ## Card Refreshes
@@ -2376,6 +2436,8 @@ The following table describes the behavior these flags have.
 
 ### Card Update Truth Table
 
+Note that no (other) automated updates are permitted when [scan mode](#scan-mode) is being triggered.
+
 | `view . update_seconds` | `view . timeout_seconds` | `view . update_force` | `view . update_entities` | Behavior |
 | :-: | :-: | :-: | :-: | - |
 | `0` | `0` | *(Any value)* | Unset | Card will not automatically refresh. |