Api and other documentation (#73)

* Create CONTRIBUTING.md * key/val pair definitions, fix #55
easytarget · Oct 14, 2020 · e2dfb77 · e2dfb77
1 parent 5e1ec6f
commit e2dfb77
Show file tree

Hide file tree

Showing 5 changed files with 165 additions and 51 deletions.
diff --git a/API.md b/API.md
@@ -0,0 +1,79 @@
+# 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
+* `/` - Default index
+* `/?target=full|simple|portal` - Go direct to specific index
+* `/capture` - Return a Jpeg snapshot image
+* `/status` - Returns a JSON string with all camera status <key>/<value> pairs listed
+* `/control?var=<key>&val=<val>` - Set <key> to <val>
+* `/dump` - Status page
+
+### Stream Port
+* `/` - Raw stream
+* `/view` - Stream viewer
+
+## *key / val* settings and commands
+
+Call the `/status` URI to recieve a JSON response containing all the available settings and current value.
+
+Call `/control?var=<key>&val=<val>` with a settings key and value to set camera properties or trigger actions.
+
+#### Settings
+```
+lamp            - Lamp value in percent; integer, 0 - 100 (-1 = disabled)
+framesize       - 0=QQVGA, 3=HQVGA, QVGA=4, CIF=5, VGA=6, SVGA=7, XGA=8, SXGA=9, UXGA=10, QXGA(ov3660)=11
+quality         - 10 to 63 (ov3660: 4 to 10)
+contrast        - -2 to 2 (ov3660: -3 to 3)
+brightness      - -2 to 2 (ov3660: -3 to 3)
+saturation      - -2 to 2 (ov3660: -4 to 4)
+sharpness       - (ov3660: -3 to 3)
+denoise         - (ov3660: 0 to 8)
+ae_level        - (ov3660: -5 to 5)
+special_effect  - 0=No Effect, 1=Negative, 2=Grayscale, 3=Red Tint, 4=Green Tint, 5=Blue Tint, 6=Sepia
+awb             - 0 = disable, 1 = enable
+awb_gain        - 0 = disable, 1 = enable
+wb_mode         - if awb enabled: 0=Auto, 1=Sunny, 2=Cloudy, 3=Office, 4=Home
+aec             - 0 = disable, 1 = enable
+aec_value       - 0 to 1200 (ov3660: 0 to 1536)
+aec2            - 0 = disable, 1 = enable
+ae_level        - -2 to 2 (not ov3660)
+agc             - 0 = disable, 1 = enable
+agc_gain        - 0 to 30 (ov3660: 0 to 64)
+gainceiling     - 0 to 6 (ov3660: 0 to 511)
+bpc             - 0 = disable, 1 = enable
+wpc             - 0 = disable, 1 = enable
+raw_gma         - 0 = disable, 1 = enable
+lenc            - 0 = disable, 1 = enable
+hmirror         - 0 = disable, 1 = enable
+vflip           - 0 = disable, 1 = enable
+rotate          - Rotation Angle; integer, only -90, 0, 90 values are recognised
+dcw             - 0 = disable, 1 = enable
+colorbar        - Overlays a color test pattern on the stream; integer, 1 = enabled
+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
+```
+#### 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 `<key>`, the `<val>` must be supplied, but can be any value and is ignored.
+```
+face_enroll     - Enroll a new face in the FaceDB (only when face recognition is avctive)
+save_prefs      - Saves preferences file
+clear_prefs     - Deletes the preferences file
+reboot          - Reboots the camera
+```
+## Examples
+* Flash light: on/off
+  * `http://<IP-ADDRESS>/control?var=lamp&val=100` On
+  * `http://<IP-ADDRESS>/control?var=lamp&val=50` 50%
+  * `http://<IP-ADDRESS>/control?var=lamp&val=0` Off
+
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,49 @@
+# 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:
+
+- Reporting a bug
+- Discussing the current state of the code
+- Submitting a fix
+- Proposing new features
+- Becoming a maintainer
+
+## 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
+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. Give your branch a clear descriptive name and do your changes there.
+3. If you've changed the HTTP APIs, update the documentation.
+4. Issue a pull request against a branch *of the same name* in the main repo.
+5. Clearly describe your changes and the reason for them in the 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](./LICENSE) 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 in the main code
+
+## 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)
diff --git a/README.md b/README.md
@@ -57,14 +57,11 @@ By default the sketch assumes you have an AI-THINKER board, it creates an Access
 
 To make a permanent config for a different board, or with your home wifi settings etc. copy (or rename) the file `myconfig.sample.h` in the sketch folder to `myconfig.h`
 
-Additional boot-time changes to other camera properties can be made in the main sketch file; see the comments [around line 253](https://github.com/easytarget/esp32-cam-webserver/blob/doc-options/esp32-cam-webserver.ino#L253).
-
 You can now set a camera name, board model, wifi settings and some other defaults in that file. And because this is your private copy it will not get overwritten if you update the main sketch!
 
 ### Programming 
 
 Assuming you are using the latest Espressif Arduino core the AI-THINKER board (or whatever you use) will appear in the ESP32 Arduino section of the boards list. 
-
 ![IDE board config](Docs/board-selection-small.png)
 
 Compile and upload the code from the IDE, when the `Connecting...` appears in the console reboot the ESP32 module while keeping **GPIO0** grounded. You can release GPO0 once the sketch is uploading, most boards have a 'boot' button to trigger a reboot.
@@ -77,8 +74,6 @@ Go to the URL given in the serial output, the web UI should appear with the sett
 
 ## My Modifications:
 
-The basic example is extended to allow control of a high power LED FlashLamps, which are present on my modules. It can also blink a status LED to show when it connects to WiFi.
-
 The WiFi details can be stored in an (optional) header file to allow easier code development, and a camera name for the UI title can be configured. The lamp and status LED's are optional, and the lamp uses a exponential scale for brightness so that the control has some finess.
 
 The compressed and binary encoded HTML used in the example has been unpacked to raw text, this makes it much easier to access and modify the Javascript and UI elements. Given the relatively small size of the index page there is very little benefit from compressing it.
@@ -101,11 +96,7 @@ I would also like to shoutout to @jmfloyd; who suggested rotating the image in t
 
 ## Contributing
 
-Contributions are welcome!
-
-To make a PR please first fork the repo in github, and make a branch in that fork with a sensible name. Apply your changes to that branch (and test if you can), commit and then create a PR to merge to a branch of the same name in my repo.
-
-Please do not submit PR's onto the master branch of my repo unless they are very trivial (spellings etc). Make sure your changes are consistent with the style and purpose of the existing code; and provide a coherent explanation of what/why in the PR. 
+Contributions are welcome; please see the [Contribution guidelines](CONTRIBUTING.md).
 
 ## Plans
 
@@ -117,19 +108,12 @@ V3 Options, UI and server enhancements;
 * UI now shows stream links and build info
 * Nearly Complete
 
-V4 Preferences; 
-* Cam module preferences and face recognition Db saved between sessions in LittleFS (formerly SPIFS).
-* Upload/Download FaceDB as Json document in browser
+V4 Remove face recognition entirely;
+* Dont try to make it optional, this is a code and maintenance nightmare. V3 can be maintained on a branch for those who need it.
 * Investigate using SD card to capture images
-* Not started; will have to wait until I have time.
-
-V5 Remove face recognition entirely;
-* Dont try to make it optional, this is a code and maintenance nightmare. V4 can be maintained on a branch for those who need it.
 * implement OTA and a better network stack for remembering multiple AP's, auto-config etc.
 * UI Skinning/Theming
 
 You can check the [enhancement list](https://github.com/easytarget/esp32-cam-webserver/issues?q=is%3Aissue+label%3Aenhancement) (past and present), and add any thoghts you may have there. Things that have occurred to me are, in no particular order:
-* Improve Wifi, add a captive portal for setup and fallback, better disconnect/reconnect behaviour.
 * The module has a SD/TF card slot; this is currently unused, but I would like to add the ability to store snapshots; recording Video at low resolution may be possible, but the card interface is too slow for HD video as far as I know.
 * Remove face rcognition to save a Mb+ of code space and then implement over the air updates.
-* Combine current split html pages (one per camera type) into one which adapts as needed.
diff --git 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
@@ -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,14 +66,30 @@ 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
  */
 // #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