From ac958d5ad81fd76b9903aa836acef9728f365626 Mon Sep 17 00:00:00 2001
From: Phil Bruckner <pnbruckner@gmail.com>
Date: Tue, 7 May 2019 20:04:06 -0500
Subject: [PATCH] Add amcrest camera services and deprecate switches (#9180)

* Add amcrest services and deprecate switches

* Rename services

* Update amcrest.markdown

Refer to amcrest-specific services as just "services." Referring to them as "camera services" can be misleading, since the services are not in the camera domain.
---
 source/_components/amcrest.markdown | 78 +++++++++++++++++++++++++----
 1 file changed, 68 insertions(+), 10 deletions(-)

diff --git a/source/_components/amcrest.markdown b/source/_components/amcrest.markdown
index 3d2235d954b..841920a0f9a 100644
--- a/source/_components/amcrest.markdown
+++ b/source/_components/amcrest.markdown
@@ -29,7 +29,7 @@ There is currently support for the following device types within Home Assistant:
 - Binary Sensor
 - Camera
 - Sensor
-- Switch
+- Switch (deprecated)
 
 ## {% linkable_title Configuration %}
 
@@ -128,8 +128,8 @@ sensors:
     motion_detector:
       description: >
         Return `true`/`false` when motion is detected.  
-
-        **Note:** This sensor is deprecated and will be removed in a future release.
+        
+        **Note:** The motion_detector sensor is deprecated and will be removed in a future release.
         Use **binary_sensors** option **motion_detected** instead.
     sdcard:
       description: Return the SD card usage by reporting the total and used space.
@@ -139,7 +139,11 @@ sensors:
         configured for the given camera.
 switches:
   description: >
-    Switches to display in the frontend.
+    Switches to display in the frontend.  
+    
+    **Note:** Switches are deprecated and will be removed in a future release.  
+    Use services and attributes instead.  
+    
     The following switches can be monitored:
   required: false
   type: list
@@ -163,9 +167,66 @@ Newer Amcrest firmware may not work, then **rtsp** is recommended instead.
 make sure to follow the steps mentioned at [FFMPEG](/components/ffmpeg/)
 documentation to install the `ffmpeg`.
 
-To check if your Amcrest camera is supported/tested, visit the
-[supportability matrix](https://github.com/tchellomello/python-amcrest#supportability-matrix)
-link from the `amcrest` project.
+## {% linkable_title Services %}
+
+Once loaded, the `amcrest` component will expose services that can be called to perform various actions. The `entity_id` service attribute can specify one or more specific cameras, or `all` can be used to specify all configured Amcrest cameras.
+
+Available services:
+`enable_audio`, `disable_audio`,
+`enable_motion_recording`, `disable_motion_recording`,
+`enable_recording`, `disable_recording`,
+`goto_preset`, `set_color_bw`,
+`start_tour` and `stop_tour`
+
+#### {% linkable_title Service `enable_audio`/`disable_audio` %}
+
+These services enable or disable the camera's audio stream.
+
+Service data attribute | Optional | Description
+-|-|-
+`entity_id` | no | Name(s) of entities, e.g., `camera.living_room_camera`.
+
+#### {% linkable_title Service `enable_motion_recording`/`disable_motion_recording` %}
+
+These services enable or disable the camera to record a clip to its configured storage location when motion is detected.
+
+Service data attribute | Optional | Description
+-|-|-
+`entity_id` | no | Name(s) of entities, e.g., `camera.living_room_camera`.
+
+#### {% linkable_title Service `enable_recording`/`disable_recording` %}
+
+These services enable or disable the camera to continuously record to its configured storage location.
+
+Service data attribute | Optional | Description
+-|-|-
+`entity_id` | no | Name(s) of entities, e.g., `camera.living_room_camera`.
+
+#### {% linkable_title Service `goto_preset` %}
+
+This service will cause the camera to move to one of the PTZ locations configured within the camera.
+
+Service data attribute | Optional | Description
+-|-|-
+`entity_id` | no | Name(s) of entities, e.g., `camera.living_room_camera`.
+`preset` | no | Preset number, starting from 1.
+
+#### {% linkable_title Service `set_color_bw` %}
+
+This service will set the color mode of the camera.
+
+Service data attribute | Optional | Description
+-|-|-
+`entity_id` | no | Name(s) of entities, e.g., `camera.living_room_camera`.
+`color_bw` | no | One of `auto`, `bw` or `color`.
+
+#### {% linkable_title Service `start_tour`/`stop_tour` %}
+
+These services start or stop the camera's PTZ tour function.
+
+Service data attribute | Optional | Description
+-|-|-
+`entity_id` | no | Name(s) of entities, e.g., `camera.living_room_camera`.
 
 ## {% linkable_title Advanced Configuration %}
 
@@ -181,9 +242,6 @@ amcrest:
       - motion_detected
     sensors:
       - sdcard
-    switches:
-      - motion_detection
-      - motion_recording
 
   # Add second camera
   - host: IP_ADDRESS_CAMERA_2