From cecae755b7a25982ad5ced74ac3e02308e2d3d06 Mon Sep 17 00:00:00 2001 From: Owen Date: Sat, 3 Oct 2020 23:21:07 +0200 Subject: [PATCH 01/10] Initial, needs key/val pair description --- API.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 API.md diff --git a/API.md b/API.md new file mode 100644 index 0000000..0babb40 --- /dev/null +++ b/API.md @@ -0,0 +1,25 @@ +# Basic HTTP Commands +## It's an API Jim, but not as we know it + +The WebUI and camera server communicate entirely via HTTP requests and responses; this makes controlling all functions of the camera via GET requests possible. An API in effect. + +## URI's +### Http Port +`/` Root URI; primary WebUI +`/capture` Return a Jpeg snapshot image +`/view` Simplified Viewer +`/status` Returns a JSON string with all camera status / pairs listed +`/control?var=&val=` Set to +`/dump` Status page + +### Stream Port +`/` Root URI; Raw stream +`/view` Stream viewer + +## / settings and commands +.. thie list.. the list is the thing. + +## Examples +Flash light: on/off +http:///control?var=lamp&val=100 +http:///control?var=lamp&val=0 From c270f8e4181dddf3d7a7ed19b84d54d75e21ca28 Mon Sep 17 00:00:00 2001 From: Owen Carter Date: Sun, 4 Oct 2020 00:22:22 +0200 Subject: [PATCH 02/10] Flesh out --- API.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 77 insertions(+), 14 deletions(-) diff --git a/API.md b/API.md index 0babb40..a650809 100644 --- a/API.md +++ b/API.md @@ -1,25 +1,88 @@ -# Basic HTTP Commands -## It's an API Jim, but not as we know it +TODO: +* Order the same as in the UI for most settings +* Brief Descriptions (ESP documentation?) +* ov2640 vs 3660 specifics (note them) + +# Basic HTTP Commands; +It's an API Jim, but not as we know it The WebUI and camera server communicate entirely via HTTP requests and responses; this makes controlling all functions of the camera via GET requests possible. An API in effect. ## URI's ### Http Port -`/` Root URI; primary WebUI -`/capture` Return a Jpeg snapshot image -`/view` Simplified Viewer -`/status` Returns a JSON string with all camera status / pairs listed -`/control?var=&val=` Set to -`/dump` Status page +* `/` Primary WebUI +* `/capture` Return a Jpeg snapshot image +* `/view` Simplified viewer +* `/status` Returns a JSON string with all camera status / pairs listed +* `/control?var=&val=` Set to +* `/dump` Status page ### Stream Port -`/` Root URI; Raw stream -`/view` Stream viewer +* `/` Raw stream +* `/view` Stream viewer -## / settings and commands +## *key / val* settings and commands .. thie list.. the list is the thing. +### Use +Call the `/status` URI to recieve a JSON response containing all the available settings and responses. + +Call `/control?var=&val=` with a settings key and value to set camera properties or trigger actions. + +#### Settings +``` +framesize - +quality - +contrast - +brightness - +saturation - +gainceiling - +colorbar - Overlays a color test pattern on the stream; integer, 1 = enabled +awb - +agc - +aec - +hmirror - +vflip - +awb_gain - +agc_gain - +aec_value - +aec2 - +dcw - +bpc - +wpc - +raw_gma - +lenc - +special_effect - +wb_mode - +ae_level - +rotate - Rotation Angle; integer, only -90, 0, 90 values are recognised +face_detect - Face Detection; 1 = enabled, Only settable if framesize <= 4 (CIF) +face_recognize - Face recognition; 1 = enabled, only settable if Face detection is already enabled +lamp - Lamp value in percent; integer, 0 - 100 (-1 = disabled) +``` +#### Read Only +These values are returned in the `/status` JSON response, but cannot be set via the `/control` URI. +``` +cam_name - Camera Name; String +code_ver - Code compile date and time; String +stream_url - Raw stream URL; string +``` +#### Commands +These are commands; they can be sent by calling the `/control` URI with them as the ``, the `` supplied is ignored. +``` +face_enroll - Enroll a new face in the FaceDB (only when face recognition is avctive) +save_face - Saves the FaceDB file (NOT YET IMPLEMENTED) +clear_face - Clears the FaceDB file (NOT YET IMPLEMENTED) +save_prefs - Saves preferences file +clear_prefs - Deletes the preferences file +reboot - Reboots the camera +``` ## Examples -Flash light: on/off -http:///control?var=lamp&val=100 -http:///control?var=lamp&val=0 +* Flash light: on/off + * `http:///control?var=lamp&val=100` On +  * `http:///control?var=lamp&val=50` 50% + * `http:///control?var=lamp&val=0` Off + +## Timelapse Example (for Linux Users) +* Install ffmpeg +* `Work this out... I've got an example somewhere` From ba89553988a301df11999d7a649f3efbf04fb3c6 Mon Sep 17 00:00:00 2001 From: Owen Date: Sat, 3 Oct 2020 23:21:07 +0200 Subject: [PATCH 03/10] Initial, needs key/val pair description --- API.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 API.md diff --git a/API.md b/API.md new file mode 100644 index 0000000..0babb40 --- /dev/null +++ b/API.md @@ -0,0 +1,25 @@ +# Basic HTTP Commands +## It's an API Jim, but not as we know it + +The WebUI and camera server communicate entirely via HTTP requests and responses; this makes controlling all functions of the camera via GET requests possible. An API in effect. + +## URI's +### Http Port +`/` Root URI; primary WebUI +`/capture` Return a Jpeg snapshot image +`/view` Simplified Viewer +`/status` Returns a JSON string with all camera status / pairs listed +`/control?var=&val=` Set to +`/dump` Status page + +### Stream Port +`/` Root URI; Raw stream +`/view` Stream viewer + +## / settings and commands +.. thie list.. the list is the thing. + +## Examples +Flash light: on/off +http:///control?var=lamp&val=100 +http:///control?var=lamp&val=0 From 84534d2fc183bb7dcb8f2c5c2535b9557862464f Mon Sep 17 00:00:00 2001 From: Owen Carter Date: Sun, 4 Oct 2020 00:22:22 +0200 Subject: [PATCH 04/10] Flesh out --- API.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 77 insertions(+), 14 deletions(-) diff --git a/API.md b/API.md index 0babb40..a650809 100644 --- a/API.md +++ b/API.md @@ -1,25 +1,88 @@ -# Basic HTTP Commands -## It's an API Jim, but not as we know it +TODO: +* Order the same as in the UI for most settings +* Brief Descriptions (ESP documentation?) +* ov2640 vs 3660 specifics (note them) + +# Basic HTTP Commands; +It's an API Jim, but not as we know it The WebUI and camera server communicate entirely via HTTP requests and responses; this makes controlling all functions of the camera via GET requests possible. An API in effect. ## URI's ### Http Port -`/` Root URI; primary WebUI -`/capture` Return a Jpeg snapshot image -`/view` Simplified Viewer -`/status` Returns a JSON string with all camera status / pairs listed -`/control?var=&val=` Set to -`/dump` Status page +* `/` Primary WebUI +* `/capture` Return a Jpeg snapshot image +* `/view` Simplified viewer +* `/status` Returns a JSON string with all camera status / pairs listed +* `/control?var=&val=` Set to +* `/dump` Status page ### Stream Port -`/` Root URI; Raw stream -`/view` Stream viewer +* `/` Raw stream +* `/view` Stream viewer -## / settings and commands +## *key / val* settings and commands .. thie list.. the list is the thing. +### Use +Call the `/status` URI to recieve a JSON response containing all the available settings and responses. + +Call `/control?var=&val=` with a settings key and value to set camera properties or trigger actions. + +#### Settings +``` +framesize - +quality - +contrast - +brightness - +saturation - +gainceiling - +colorbar - Overlays a color test pattern on the stream; integer, 1 = enabled +awb - +agc - +aec - +hmirror - +vflip - +awb_gain - +agc_gain - +aec_value - +aec2 - +dcw - +bpc - +wpc - +raw_gma - +lenc - +special_effect - +wb_mode - +ae_level - +rotate - Rotation Angle; integer, only -90, 0, 90 values are recognised +face_detect - Face Detection; 1 = enabled, Only settable if framesize <= 4 (CIF) +face_recognize - Face recognition; 1 = enabled, only settable if Face detection is already enabled +lamp - Lamp value in percent; integer, 0 - 100 (-1 = disabled) +``` +#### Read Only +These values are returned in the `/status` JSON response, but cannot be set via the `/control` URI. +``` +cam_name - Camera Name; String +code_ver - Code compile date and time; String +stream_url - Raw stream URL; string +``` +#### Commands +These are commands; they can be sent by calling the `/control` URI with them as the ``, the `` supplied is ignored. +``` +face_enroll - Enroll a new face in the FaceDB (only when face recognition is avctive) +save_face - Saves the FaceDB file (NOT YET IMPLEMENTED) +clear_face - Clears the FaceDB file (NOT YET IMPLEMENTED) +save_prefs - Saves preferences file +clear_prefs - Deletes the preferences file +reboot - Reboots the camera +``` ## Examples -Flash light: on/off -http:///control?var=lamp&val=100 -http:///control?var=lamp&val=0 +* Flash light: on/off + * `http:///control?var=lamp&val=100` On +  * `http:///control?var=lamp&val=50` 50% + * `http:///control?var=lamp&val=0` Off + +## Timelapse Example (for Linux Users) +* Install ffmpeg +* `Work this out... I've got an example somewhere` From 7117d7d9c046d9feb2e72249e1e39ea1d4880d32 Mon Sep 17 00:00:00 2001 From: Owen Date: Sat, 3 Oct 2020 23:21:07 +0200 Subject: [PATCH 05/10] Initial, needs key/val pair description --- API.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 API.md diff --git a/API.md b/API.md new file mode 100644 index 0000000..0babb40 --- /dev/null +++ b/API.md @@ -0,0 +1,25 @@ +# Basic HTTP Commands +## It's an API Jim, but not as we know it + +The WebUI and camera server communicate entirely via HTTP requests and responses; this makes controlling all functions of the camera via GET requests possible. An API in effect. + +## URI's +### Http Port +`/` Root URI; primary WebUI +`/capture` Return a Jpeg snapshot image +`/view` Simplified Viewer +`/status` Returns a JSON string with all camera status / pairs listed +`/control?var=&val=` Set to +`/dump` Status page + +### Stream Port +`/` Root URI; Raw stream +`/view` Stream viewer + +## / settings and commands +.. thie list.. the list is the thing. + +## Examples +Flash light: on/off +http:///control?var=lamp&val=100 +http:///control?var=lamp&val=0 From 95d98c3a16c3010f7d0e4f7c2f462650dc6eb6f1 Mon Sep 17 00:00:00 2001 From: Owen Carter Date: Sun, 4 Oct 2020 00:22:22 +0200 Subject: [PATCH 06/10] Flesh out --- API.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 77 insertions(+), 14 deletions(-) diff --git a/API.md b/API.md index 0babb40..a650809 100644 --- a/API.md +++ b/API.md @@ -1,25 +1,88 @@ -# Basic HTTP Commands -## It's an API Jim, but not as we know it +TODO: +* Order the same as in the UI for most settings +* Brief Descriptions (ESP documentation?) +* ov2640 vs 3660 specifics (note them) + +# Basic HTTP Commands; +It's an API Jim, but not as we know it The WebUI and camera server communicate entirely via HTTP requests and responses; this makes controlling all functions of the camera via GET requests possible. An API in effect. ## URI's ### Http Port -`/` Root URI; primary WebUI -`/capture` Return a Jpeg snapshot image -`/view` Simplified Viewer -`/status` Returns a JSON string with all camera status / pairs listed -`/control?var=&val=` Set to -`/dump` Status page +* `/` Primary WebUI +* `/capture` Return a Jpeg snapshot image +* `/view` Simplified viewer +* `/status` Returns a JSON string with all camera status / pairs listed +* `/control?var=&val=` Set to +* `/dump` Status page ### Stream Port -`/` Root URI; Raw stream -`/view` Stream viewer +* `/` Raw stream +* `/view` Stream viewer -## / settings and commands +## *key / val* settings and commands .. thie list.. the list is the thing. +### Use +Call the `/status` URI to recieve a JSON response containing all the available settings and responses. + +Call `/control?var=&val=` with a settings key and value to set camera properties or trigger actions. + +#### Settings +``` +framesize - +quality - +contrast - +brightness - +saturation - +gainceiling - +colorbar - Overlays a color test pattern on the stream; integer, 1 = enabled +awb - +agc - +aec - +hmirror - +vflip - +awb_gain - +agc_gain - +aec_value - +aec2 - +dcw - +bpc - +wpc - +raw_gma - +lenc - +special_effect - +wb_mode - +ae_level - +rotate - Rotation Angle; integer, only -90, 0, 90 values are recognised +face_detect - Face Detection; 1 = enabled, Only settable if framesize <= 4 (CIF) +face_recognize - Face recognition; 1 = enabled, only settable if Face detection is already enabled +lamp - Lamp value in percent; integer, 0 - 100 (-1 = disabled) +``` +#### Read Only +These values are returned in the `/status` JSON response, but cannot be set via the `/control` URI. +``` +cam_name - Camera Name; String +code_ver - Code compile date and time; String +stream_url - Raw stream URL; string +``` +#### Commands +These are commands; they can be sent by calling the `/control` URI with them as the ``, the `` supplied is ignored. +``` +face_enroll - Enroll a new face in the FaceDB (only when face recognition is avctive) +save_face - Saves the FaceDB file (NOT YET IMPLEMENTED) +clear_face - Clears the FaceDB file (NOT YET IMPLEMENTED) +save_prefs - Saves preferences file +clear_prefs - Deletes the preferences file +reboot - Reboots the camera +``` ## Examples -Flash light: on/off -http:///control?var=lamp&val=100 -http:///control?var=lamp&val=0 +* Flash light: on/off + * `http:///control?var=lamp&val=100` On +  * `http:///control?var=lamp&val=50` 50% + * `http:///control?var=lamp&val=0` Off + +## Timelapse Example (for Linux Users) +* Install ffmpeg +* `Work this out... I've got an example somewhere` From 13bb980cd803dc2afa49d68c0443f2e253a3f1ac Mon Sep 17 00:00:00 2001 From: Owen Date: Mon, 12 Oct 2020 13:54:44 +0200 Subject: [PATCH 07/10] Comment syntax --- esp32-cam-webserver.ino | 2 +- myconfig.sample.h | 64 +++++++++++++++++++++-------------------- 2 files changed, 34 insertions(+), 32 deletions(-) diff --git a/esp32-cam-webserver.ino b/esp32-cam-webserver.ino index fc9a38d..fc98f93 100644 --- a/esp32-cam-webserver.ino +++ b/esp32-cam-webserver.ino @@ -39,7 +39,7 @@ stationList[] = {{"ESP32-CAM-CONNECT","InsecurePassword", true}}; #endif -// Version string +// Upstream version string #include "src/version.h" // Pin Mappings diff --git a/myconfig.sample.h b/myconfig.sample.h index fabf0cd..a612d82 100644 --- a/myconfig.sample.h +++ b/myconfig.sample.h @@ -1,12 +1,12 @@ -/* +/* * Rename this example to 'myconfig.h' and fill in your details. - * + * * The local config is in the '.gitignore' file, which helps to keep details secret. */ -// Give the camera a name for the web interface -// note: this is not the network hostname +/* Give the camera a name for the web interface + * note: this is not the network hostname */ #define CAM_NAME "ESP32 camera server" @@ -29,46 +29,32 @@ struct station { * The first entry (ssid1, above) in the stationList[] is special, if WIFI_AP_ENABLE has been uncommented * it will be used for the AccessPoint ssid and password. - * - * The 'dhcp' setting controls wether the station uses static IP settings (if in doubt leave 'true') + * + * The 'dhcp' setting controls whether the station uses DHCP or static IP settings (if in doubt leave 'true') * Note the use of nested braces '{' and '}' to group each entry, and commas ',' to seperate them. */ struct station { - const char ssid[64]; // ssid (max 64 chars) - const char password[64]; // password (max 64 chars) - const bool dhcp; // use dhcp? + const char ssid[64]; // Do not edit these + const char password[64]; // three lines.. + const bool dhcp; // } stationList[] = {{"my_ssid","my_password", true}}; /* - * Static network settings for client mode - * - * Note: The same settings will be applied to all client connections where the dhcp setting is 'false' - * You must define all three: IP, Gateway and NetMask - */ -// warning - IP addresses must be seperated with commas (,) and not decimals (.) here -// #define ST_IP 192,168,0,16 -// #define ST_GATEWAY 192,168,0,2 -// #define ST_NETMASK 255,255,255,0 -// One or two optional DNS servers can be supplied, but the current firmware never uses them ;-) -// #define ST_DNS1 192,168,0,2 -// #define ST_DNS2 8,8,8,8 - -/* * AccessPoint; - * + * * Uncomment to enable AP mode; - * + * */ // #define WIFI_AP_ENABLE /* AP Mode Notes: - * + * * Once enabled the AP ssid and password will be taken from the 1st entry in the stationList[] above. - * - * If there are more entries listed they will be scanned at startup in the normal way and connected to + * + * If there are further entries listed they will be scanned at startup in the normal way and connected to * if they are found. AP then works as a fallback mode for when there are no 'real' networks available. - * + * * Setting the 'dhcp' field to true for the AP enables a captive portal and attempts to send * all visitors to the webcam page, with varying degrees of success depending on the visitors * browser and other settings. @@ -80,6 +66,22 @@ struct station { // Uncomment this to force the AccessPoint channel number, default = 1 // #define AP_CHAN 1 + +/* + * Static network settings for client mode + * + * Note: The same settings will be applied to all client connections where the dhcp setting is 'false' + * You must define all three: IP, Gateway and NetMask + */ +// warning - IP addresses must be seperated with commas (,) and not decimals (.) here +// #define ST_IP 192,168,0,16 +// #define ST_GATEWAY 192,168,0,2 +// #define ST_NETMASK 255,255,255,0 +// One or two optional DNS servers can be supplied, but the current firmware never uses them ;-) +// #define ST_DNS1 192,168,0,2 +// #define ST_DNS2 8,8,8,8 + + /* * Port numbers for WebUI and Stream, defaults to 80 and 81. * Uncomment and edit as appropriate @@ -87,7 +89,7 @@ struct station { // #define HTTP_PORT 80 // #define STREAM_PORT 81 -/* +/* * Wifi Watchdog defines how long we spend waiting for a connection before retrying, * and how often we check to see if we are still connected, milliseconds * You may wish to increase this if your WiFi is slow at conencting, @@ -114,7 +116,7 @@ struct station { /* * Additional Features - * + * */ // Default Page: uncomment to make the full control page the default, otherwise show simple viewer // #define DEFAULT_INDEX_FULL From f0f5a47e0e6fb88325ac36a9468ad1500343c71f Mon Sep 17 00:00:00 2001 From: Owen Carter Date: Tue, 13 Oct 2020 17:14:57 +0200 Subject: [PATCH 08/10] Create CONTRIBUTING.md Placeholder for contributing guidelines --- CONTRIBUTING.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..dd4e444 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,3 @@ +# Contribution Guidelines + +wip.. see main README for present From 9e6f503bbf506555fb965b4805e7078fc420f76f Mon Sep 17 00:00:00 2001 From: Owen Date: Tue, 13 Oct 2020 17:37:27 +0200 Subject: [PATCH 09/10] Still a WIP --- CONTRIBUTING.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 47 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dd4e444..5739462 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,48 @@ -# Contribution Guidelines +# Contributing to ESP32-CAM revisited +I love your input! and want to make contributing to this project as easy and transparent as possible, whether it's: -wip.. see main README for present +- Reporting a bug +- Discussing the current state of the code +- Submitting a fix +- Proposing new features +- Becoming a maintainer + +## We Develop with Github +I use github to host code, to track issues and feature requests, as well as accept pull requests. + +## I Use [Github Flow](https://guides.github.com/introduction/flow/index.html), So All Code Changes Happen Through Pull Requests +Pull requests are the best way to propose changes to the codebase (I use [Github Flow](https://guides.github.com/introduction/flow/index.html)). I actively welcome your pull requests: + +1. Fork the repo and create your branch from `master`. +2. If you've changed the HTTP APIs, update the documentation. +3. Ensure the test suite passes. +4. Issue that pull request! + +## Any contributions you make will be under the GNU Lesser General Public License v2.1 +In short, when you submit code changes, your submissions are understood to be under the same [License](./LICENCE.md) that covers the project. + +## Report bugs using Github's [issues](https://github.com/easytarget/esp32-cam-webserver/issues) +We use GitHub issues to track public bugs. Report a bug by opening a new issue; it's that easy! + +## Write bug reports with detail, background, and sample code + +**Great Bug Reports** tend to have: + +- A quick summary and/or background +- Steps to reproduce + - Be specific! +- What you expected would happen +- What actually happens +- Notes (possibly including why you think this might be happening, or stuff you tried that didn't work) + +People *love* thorough bug reports. I'm not even kidding. + +## Use a Consistent Coding Style +* 4 spaces for indentation rather than tabs + +## License +By contributing, you agree that your contributions will be licensed under its GNU Lesser General Public License v2.1 + + +## References +This document was adapted from the open-source contribution guidelines for [Facebook's Draft](https://github.com/facebook/draft-js/blob/a9316a723f9e918afde44dea68b5f9f39b7d9b00/CONTRIBUTING.md) From 34ebe098a9a4201d9841832fd291667b84d418e9 Mon Sep 17 00:00:00 2001 From: Owen Date: Tue, 13 Oct 2020 17:39:41 +0200 Subject: [PATCH 10/10] spelling --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5739462..2975da6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,7 +7,7 @@ I love your input! and want to make contributing to this project as easy and tra - Proposing new features - Becoming a maintainer -## We Develop with Github +## I Develop with Github I use github to host code, to track issues and feature requests, as well as accept pull requests. ## I Use [Github Flow](https://guides.github.com/introduction/flow/index.html), So All Code Changes Happen Through Pull Requests @@ -19,7 +19,7 @@ Pull requests are the best way to propose changes to the codebase (I use [Github 4. Issue that pull request! ## Any contributions you make will be under the GNU Lesser General Public License v2.1 -In short, when you submit code changes, your submissions are understood to be under the same [License](./LICENCE.md) that covers the project. +In short, when you submit code changes, your submissions are understood to be under the same [License](./LICENSE.md) that covers the project. ## Report bugs using Github's [issues](https://github.com/easytarget/esp32-cam-webserver/issues) We use GitHub issues to track public bugs. Report a bug by opening a new issue; it's that easy!