From d71307694733d96fdd7588977efa6814d36d3575 Mon Sep 17 00:00:00 2001 From: Eric Callahan Date: Sun, 24 Jul 2022 11:27:14 -0400 Subject: [PATCH] docs: add webcam documentation Signed-off-by: Eric Callahan --- docs/configuration.md | 56 +++++++-- docs/web_api.md | 274 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 322 insertions(+), 8 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 5f7c7bb..06448ec 100644 --- a/docs/configuration.md +++ b/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. diff --git a/docs/web_api.md b/docs/web_api.md index 3482c4c..9f7c085 100644 --- a/docs/web_api.md +++ b/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: