docs: add webcam documentation

Signed-off-by:  Eric Callahan <arksine.code@gmail.com>

docs/configuration.md

@@ -232,6 +232,46 @@ dev_mode: False
 #   from RSS feeds generated by the "moonlight" repo on GitHub.
 ```
 
+### `[webcam]`
+
+The `webcam` module provides unified webcam configuration management.  Webcams
+may be configured directly through front-ends and added to the database,
+however it is also possible for users to configure one or more webcams in
+`moonraker.conf`.  If a webcam is configured in `moonraker.conf` it takes
+precedent over a webcam in the database by the same name.  The options
+available may not apply to all front-ends, refer to your front-end's
+documentation for details on camera configuration.
+
+```ini
+[webcam my_camera_name]
+location: printer
+#   A description of the webcam location, ie: what the webcam is observing.
+#   The default is "printer".
+service: mjpegstreamer
+#   The name of the application or service hosting the webcam stream.  Front-
+#   ends may use this configuration to determine how to launch or start the
+#   program.  The default is "mjpegstreamer".
+target_fps: 15
+#   An integer value specifying the target framerate.  The default is 15 fps.
+stream_url:
+#   The url for the camera stream request.  This may be a full url or a
+#   relative path (ie: /webcam?action=stream) if the stream is served on the
+#   same host as Moonraker at port 80.  This parameter must be provided.
+snapshot_url:
+#   The url for the camera snapshot request.  This may be a full url or a
+#   relative path (ie: /webcam?action=stream) if the stream is served on the
+#   same host as Moonraker at port 80.  This parameter must be provided.
+flip_horizontal: False
+#   A boolean value indicating whether the stream should be flipped
+#   horizontally.  The default is false.
+flip_vertical: False
+#   A boolean value indicating whether the stream should be flipped
+#   vertically.  The default is false.
+rotation: 0
+#   An integer value indicating the amount of clockwise rotation to apply
+#   to the stream.  May be 0, 90, 180, or 270.  The default is 0.
+```
+
 ## Optional Components
 
 Optional Components are only loaded if present in `moonraker.conf`.  This
@@ -1189,7 +1229,7 @@ referred to as "extensions".  In general terms, an extension may be defined
 as a piece of software hosted on GitHub.  The update manager breaks this
 down into 3 basic types:
 
-- `web`: A front end such as Mainsail or Fluidd.  Updates are deployed via
+- `web`: A front-end such as Mainsail or Fluidd.  Updates are deployed via
   zip files created for GitHub releases.
 - `git_repo`:  Used to manage extensions that do not fall into the "web" type.
   Updates are deployed directly via git.  Typical usage scenarios are to
@@ -1217,16 +1257,16 @@ down into 3 basic types:
 [update_manager extension_name]
 type: web
 #   The management type.  This should always be "web" for browser based
-#   front ends. This parameter must be provided.
+#   front-ends. This parameter must be provided.
 channel: stable
 #   May be stable or beta.  When beta is specified "pre-release"
 #   updates are available.
 repo:
-#   This is the GitHub repo of the front end, in the format of owner/repo_name.
+#   This is the GitHub repo of the front-end, in the format of owner/repo_name.
 #   For example, this could be set to fluidd-core/fluidd to update Fluidd or
 #   mainsail-crew/mainsail to update Mainsail.  This parameter must be provided.
 path:
-#   The path to the front end's files on disk.  This parameter must be provided.
+#   The path to the front-end's files on disk.  This parameter must be provided.
 persistent_files:
 #   A list of newline separated file names that should persist between
 #   updates.  This is useful for static configuration files, or perhaps
@@ -1241,7 +1281,7 @@ info_tags:
 #       info_tags:
 #           desc=My Client App
 #           action=webcam_restart
-#   Front ends may use these tags to perform additional actions or display
+#   Front-ends may use these tags to perform additional actions or display
 #   information, see your extension documentation for details on configuration.
 #   The default is an empty list.
 ```
@@ -1342,11 +1382,11 @@ refresh_interval:
 #   section.
 info_tags:
 #   Optional information tags about this application that will be reported
-#   front ends as a list of strings. Each tag should be separated by a new line.
+#   front-ends as a list of strings. Each tag should be separated by a new line.
 #   For example:
 #       info_tags:
 #           desc=Special Application
-#   Front ends my use these tags to perform additional actions or display
+#   Front-ends my use these tags to perform additional actions or display
 #   information, see your extension documentation for details on configuration.
 #   The default is an empty list.
 ```
@@ -2010,7 +2050,7 @@ temperature_store_size: 600
 gcode_store_size: 1000
 ```
 
-The common front ends provide a UI for modifying `moonraker.conf`, otherwise
+The common front-ends provide a UI for modifying `moonraker.conf`, otherwise
 it will be necessary to ssh into the host and use a tool such as `nano` to
 make the changes.
 

docs/web_api.md

@@ -2981,6 +2981,280 @@ The name of the new feed and the action taken.  The `action` will be
 }
 ```
 
+### Webcam APIs
+The following APIs are available to manage webcam configuration:
+
+#### List Webcams
+
+HTTP request:
+```http
+GET /server/webcams/list
+```
+JSON-RPC request:
+```json
+{
+    "jsonrpc": "2.0",
+    "method": "server.webcams.list",
+    "id": 4654
+}
+```
+
+Returns:
+
+A list of configured webcams:
+
+```json
+{
+    "webcams": [
+        {
+            "name": "testcam3",
+            "location": "door",
+            "service": "mjpegstreamer",
+            "target_fps": 20,
+            "stream_url": "http://camera.lan/webcam?action=stream",
+            "snapshot_url": "http://camera.lan/webcam?action=snapshot",
+            "flip_horizontal": false,
+            "flip_vertical": true,
+            "rotation": 90,
+            "source": "config"
+        },
+        {
+            "name": "tc2",
+            "location": "printer",
+            "service": "mjpegstreamer",
+            "target_fps": 15,
+            "stream_url": "http://printer.lan/webcam?action=stream",
+            "snapshot_url": "http://printer.lan/webcam?action=snapshot",
+            "flip_horizontal": false,
+            "flip_vertical": false,
+            "rotation": 0,
+            "source": "database"
+        },
+        {
+            "name": "TestCam",
+            "location": "printer",
+            "service": "mjpegstreamer",
+            "target_fps": 15,
+            "stream_url": "/webcam/?action=stream",
+            "snapshot_url": "/webcam/?action=snapshot",
+            "flip_horizontal": false,
+            "flip_vertical": false,
+            "rotation": 0,
+            "source": "database"
+        }
+    ]
+}
+```
+
+#### Get Webcam Information
+
+HTTP request:
+```http
+GET /server/webcams/item?name=cam_name
+```
+JSON-RPC request:
+```json
+{
+    "jsonrpc": "2.0",
+    "method": "server.webcams.get_item",
+    "parmams": {
+        "name": "cam_name"
+    },
+    "id": 4654
+}
+```
+
+Parameters:
+
+- `name`: The name of the camera to request information for.  If the named
+  camera is not available the request will return with an error.  This
+  parameter must be provided.
+
+Returns:
+
+The full configuration for the requested webcam:
+
+```json
+{
+    "webcam": {
+        "name": "TestCam",
+        "location": "printer",
+        "service": "mjpegstreamer",
+        "target_fps": 15,
+        "stream_url": "/webcam/?action=stream",
+        "snapshot_url": "/webcam/?action=snapshot",
+        "flip_horizontal": false,
+        "flip_vertical": false,
+        "rotation": 0,
+        "source": "database"
+    }
+}
+```
+#### Add or update a webcam
+
+!!! Note
+    A webcam configured via `moonraker.conf` cannot be updated or
+    overwritten using this API.
+
+HTTP request:
+```http
+POST /server/webcams/item
+Content-Type: application/json
+
+{
+    "name": "cam_name",
+    "snapshot_url": "http://printer.lan:8080/webcam?action=snapshot",
+    "stream_url": "http://printer.lan:8080/webcam?action=stream"
+}
+```
+
+JSON-RPC request:
+```json
+{
+    "jsonrpc": "2.0",
+    "method": "server.webcams.post_item",
+    "parmams": {
+        "name": "cam_name",
+        "snapshot_url": "/webcam?action=snapshot",
+        "stream_url": "/webcam?action=stream"
+    },
+    "id": 4654
+}
+```
+
+Parameters:
+
+- `name`: The name of the camera to add or update.  This parameter must
+  be provided.
+- `location`: A description of the webcam location, ie: what the webcam is
+  observing.  The default is "printer".
+- `service`: The name of the webcam application streaming service.  The default
+  is "mjpegstreamer".
+- `target_fps`:  The target framerate.  The default is 15
+- `stream_url`:  The url for the camera stream request.  This may be a full url
+  or a url relative to Moonraker's host machine.  If the url is relative it is
+  assumed that the stream is available over http on port 80. This parameter
+  must be provided.
+- `snapshot_url`: The url for the camera snapshot request. This may be a full
+  url or a url relative to Moonraker's host machine.  If the url is relative
+  it is assumed that the snapshot is available over http on port 80. This
+  parameter must be provided.
+- `flip_horizontal`:  A boolean value indicating whether the stream should be
+  flipped horizontally.  The default is false.
+- `flip_vertical`: A boolean value indicating whether the stream should be
+  flipped vertically.  The default is false.
+- `rotation`: An integer value indicating the amount of clockwise rotation to
+   apply to the stream.  May be 0, 90, 180, or 270.  The default is 0.
+
+Returns:
+
+The full configuration for the added webcam:
+
+```json
+{
+    "webcam": {
+        "name": "TestCam",
+        "location": "printer",
+        "service": "mjpegstreamer",
+        "target_fps": 15,
+        "stream_url": "/webcam/?action=stream",
+        "snapshot_url": "/webcam/?action=snapshot",
+        "flip_horizontal": false,
+        "flip_vertical": false,
+        "rotation": 0,
+        "source": "database"
+    }
+}
+```
+
+#### Delete a webcam
+
+!!! Note
+    A webcam configured via `moonraker.conf` cannot be deleted
+    using this API.
+
+HTTP request:
+```http
+DELETE /server/webcams/item?name=cam_name
+```
+JSON-RPC request:
+```json
+{
+    "jsonrpc": "2.0",
+    "method": "server.webcams.delete_item",
+    "parmams": {
+        "name": "cam_name"
+    },
+    "id": 4654
+}
+```
+
+Parameters:
+
+- `name`: The name of the camera to delete.  If the named camera is not
+  available the request will return with an error.  This parameter must
+  be provided.
+
+Returns:
+
+The full configuration of the deleted webcam:
+
+```json
+{
+    "webcam": {
+        "name": "TestCam",
+        "location": "printer",
+        "service": "mjpegstreamer",
+        "target_fps": 15,
+        "stream_url": "/webcam/?action=stream",
+        "snapshot_url": "/webcam/?action=snapshot",
+        "flip_horizontal": false,
+        "flip_vertical": false,
+        "rotation": 0,
+        "source": "database"
+    }
+}
+```
+
+#### Test a webcam
+
+Resolves a webcam's stream and snapshot urls.  If the snapshot
+is served over http, a test is performed to see if the url is
+reachable.
+
+HTTP request:
+```http
+POST /server/webcams/test?name=cam_name
+```
+JSON-RPC request:
+```json
+{
+    "jsonrpc": "2.0",
+    "method": "server.webcams.test",
+    "parmams": {
+        "name": "cam_name"
+    },
+    "id": 4654
+}
+```
+
+Parameters:
+
+- `name`: The name of the camera to test.  If the named camera is not
+  available the request will return with an error.  This parameter must
+  be provided.
+
+Returns: Test results in the following format
+
+```json
+{
+    "name": "TestCam",
+    "snapshot_reachable": true,
+    "snapshot_url": "http://127.0.0.1:80/webcam/?action=snapshot",
+    "stream_url": "http://127.0.0.1:80/webcam/?action=stream"
+}
+```
+
 ### Update Manager APIs
 The following endpoints are available when the `[update_manager]` component has
 been configured: