From a9bb9a4fe98469ff726bc8e91dc3254770963213 Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@koston.org>
Date: Wed, 11 Aug 2021 14:56:47 -0500
Subject: [PATCH] Add camera entity docs (#1020)

---
 docs/core/entity/camera.md | 114 +++++++++++++++++++++++++++++++++++++
 sidebars.js                |   1 +
 2 files changed, 115 insertions(+)
 create mode 100644 docs/core/entity/camera.md

diff --git a/docs/core/entity/camera.md b/docs/core/entity/camera.md
new file mode 100644
index 00000000..28bfcacc
--- /dev/null
+++ b/docs/core/entity/camera.md
@@ -0,0 +1,114 @@
+---
+title: Camera Entity
+sidebar_label: Camera
+---
+
+A camera entity can display images, and optionally a video stream. Derive a platform entity from [`homeassistant.components.camera.Camera`](https://github.com/home-assistant/core/blob/dev/homeassistant/components/camera/__init__.py).
+
+## Properties
+
+:::tip
+Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data.
+:::
+
+| Name | Type | Default | Description
+| ---- | ---- | ------- | -----------
+| is_recording | bool | None | Indication of whether the camera is recording. Used to determine `state`.
+| motion_detection_enabled | bool | False | Indication of whether the camera has motion detection enabled.
+| is_on | bool | True | Indication camera is on.
+| brand | str | None | The brand (manufacturer) of the camera.
+| model | str | None | The model of the camera.
+| frame_interval | float | 0.5 | The interval between frames of the stream.
+
+## Methods
+
+### Camera Image
+
+When the width and height as passed, scaling should be done on a best-effort basis. The UI will fall back to scaling at the display layer if scaling cannot be done by the camera.
+
+- Integrations should pass on the width and height if the underlying camera is capable of scaling the image.
+
+- Integrations may choose to ignore the height parameter to preserve the aspect ratio.
+
+- If the integration cannot scale the image and returns a jpeg image, it will automatically be scaled by the camera integration when requested.
+
+```python
+class MyCamera(Camera):
+    # Implement one of these methods.
+
+    def camera_image(
+        self, width: int | None = None, height: int | None = None
+    ) -> bytes | None:
+        """Return bytes of camera image."""
+        raise NotImplementedError()
+
+    async def async_camera_image(
+        self, width: int | None = None, height: int | None = None
+    ) -> bytes | None:
+        """Return bytes of camera image."""
+
+```
+
+### Stream Source
+
+The stream source should return a url that is usable by ffmpeg.
+
+```python
+class MyCamera(Camera):
+
+    async def stream_source(self) -> str | None:
+        """Return the source of the stream."""
+
+```
+
+### Turn on
+
+```python
+class MyCamera(Camera):
+    # Implement one of these methods.
+
+    def turn_on(self) -> None:
+        """Turn on camera."""
+
+    async def async_turn_on(self) -> None:
+        """Turn on camera."""
+```
+
+### Turn off
+
+```python
+class MyCamera(Camera):
+    # Implement one of these methods.
+
+    def turn_off(self) -> None:
+        """Turn off camera."""
+
+    async def async_turn_off(self) -> None:
+        """Turn off camera."""
+```
+
+### Enable motion detection
+
+```python
+class MyCamera(Camera):
+    # Implement one of these methods.
+
+    def enable_motion_detection(self) -> None:
+        """Enable motion detection in the camera."""
+
+    async def async_enable_motion_detection(self) -> None:
+        """Enable motion detection in the camera."""
+```
+
+### Disable motion detection
+
+```python
+class MyCamera(Camera):
+    # Implement one of these methods.
+
+    def disable_motion_detection(self) -> None:
+        """Disable motion detection in camera."""
+
+    async def async_disable_motion_detection(self) -> None:
+        """Disable motion detection in camera."""
+```
\ No newline at end of file
diff --git a/sidebars.js b/sidebars.js
index 7ef6c65d..3baeda19 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -151,6 +151,7 @@ module.exports = {
       "core/entity/air-quality",
       "core/entity/alarm-control-panel",
       "core/entity/binary-sensor",
+      "core/entity/camera",
       "core/entity/climate",
       "core/entity/cover",
       "core/entity/device-tracker",