Add PTZ support to Foscam camera component (#10625)

* Add PTZ support to Foscam camera component

* Update service name reflecting last changes

* Add an example card using the foscam ptz service

* Change user input to lowercase snake case

source/_integrations/foscam.markdown

@@ -56,6 +56,130 @@ name:
 There seems to be some issues within Foscam with lengthy passwords and passwords containing certain symbols. Be sure to check your camera's documentation.
 </div>
 
-### Control Foscam PTZ (Pan/Tilt/Zoom) - Home/Away
+### Service `foscam.ptz`
 
- Foscam Webcams which support CGI Commands can be controlled by Home Assistant ([Source](http://www.ipcamcontrol.net/files/Foscam%20IPCamera%20CGI%20User%20Guide-V1.0.4.pdf)). For an example of how this can be done, see the [Foscam IP Camera Pan, Tilt, Zoom Control](/cookbook/foscam_away_mode_PTZ/) Cookbook entry.
+If your Foscam camera supports PTZ, you will be able to pan or tilt your camera.
+
+| Service data attribute | Description |
+| -----------------------| ----------- |
+| `entity_id` | String or list of strings that point at `entity_id`s of cameras. Else targets all. |
+| `movement` | 	Direction of the movement. Allowed values: `up`, `down`, `left`, `right`, `top_left`, `top_right`, `bottom_left`, `bottom_right` |
+| `travel_time` | (Optional) Travel time in seconds. Allowed values: float from 0 to 1. Default: 0.125 |
+
+### Example card with controls
+
+<p class='img'>
+  <img src='/images/integrations/foscam/example-card.png' alt='Screenshot showing a foscam camera using a picture-elements with PTZ controls.'>
+  Example showing a Foscam camera with controls for Pan and Tilt.
+</p>
+
+
+Using the following card code you can achieve a card displaying the live video feed from a Foscam camera with controls for moving the camera at the bottom right corner.
+
+```yaml
+type: picture-elements
+entity: camera.bedroom
+camera_image: camera.bedroom
+camera_view: live
+elements:
+  - type: icon
+    icon: 'mdi:arrow-up'
+    style:
+      background: 'rgba(255, 255, 255, 0.5)'
+      right: 25px
+      bottom: 50px
+    tap_action:
+      action: call-service
+      service: foscam.ptz
+      service_data:
+        entity_id: camera.bedroom
+        movement: up
+  - type: icon
+    icon: 'mdi:arrow-down'
+    style:
+      background: 'rgba(255, 255, 255, 0.5)'
+      right: 25px
+      bottom: 0px
+    tap_action:
+      action: call-service
+      service: foscam.ptz
+      service_data:
+        entity_id: camera.bedroom
+        movement: down
+  - type: icon
+    icon: 'mdi:arrow-left'
+    style:
+      background: 'rgba(255, 255, 255, 0.5)'
+      right: 50px
+      bottom: 25px
+    tap_action:
+      action: call-service
+      service: foscam.ptz
+      service_data:
+        entity_id: camera.bedroom
+        movement: left
+  - type: icon
+    icon: 'mdi:arrow-right'
+    style:
+      background: 'rgba(255, 255, 255, 0.5)'
+      right: 0px
+      bottom: 25px
+    tap_action:
+      action: call-service
+      service: foscam.ptz
+      service_data:
+        entity_id: camera.bedroom
+        movement: right
+  - type: icon
+    icon: 'mdi:arrow-top-left'
+    style:
+      background: 'rgba(255, 255, 255, 0.5)'
+      right: 50px
+      bottom: 50px
+    tap_action:
+      action: call-service
+      service: foscam.ptz
+      service_data:
+        entity_id: camera.bedroom
+        movement: top_left
+  - type: icon
+    icon: 'mdi:arrow-top-right'
+    style:
+      background: 'rgba(255, 255, 255, 0.5)'
+      right: 0px
+      bottom: 50px
+    tap_action:
+      action: call-service
+      service: foscam.ptz
+      service_data:
+        entity_id: camera.bedroom
+        movement: top_right
+  - type: icon
+    icon: 'mdi:arrow-bottom-left'
+    style:
+      background: 'rgba(255, 255, 255, 0.5)'
+      right: 50px
+      bottom: 0px
+    tap_action:
+      action: call-service
+      service: foscam.ptz
+      service_data:
+        entity_id: camera.bedroom
+        movement: bottom_left
+  - type: icon
+    icon: 'mdi:arrow-bottom-right'
+    style:
+      background: 'rgba(255, 255, 255, 0.5)'
+      right: 0px
+      bottom: 0px
+    tap_action:
+      action: call-service
+      service: foscam.ptz
+      service_data:
+        entity_id: camera.bedroom
+        movement: bottom_right
+```
+
+### Extra CGI Commands
+
+Foscam Webcams which support CGI Commands can be controlled by Home Assistant ([Source](http://www.ipcamcontrol.net/files/Foscam%20IPCamera%20CGI%20User%20Guide-V1.0.4.pdf)). For an example of how this can be done, see the [Foscam IP Camera Pan, Tilt, Zoom Control](/cookbook/foscam_away_mode_PTZ/) Cookbook entry.