Update submodule & Add a custom board named KS-DIY (AIV-472)

README.md

@@ -1,119 +1,121 @@
-# ESP-WHO [[中文]](./README_CN.md)
+# ESP-WHO
 
-ESP-WHO is an image processing development platform based on Espressif chips. It contains development examples that may be applied in practical applications.
+ESP-WHO is a face detection and recognition platform that is currently based on Espressif Systems' [ESP32](https://espressif.com/en/products/hardware/esp32/overview) chip.
 
-## Overview
+# Overview
+ESP-WHO supports development of face detection and recognition applications based around Espressif Systems' [ESP32](https://espressif.com/en/products/hardware/esp32/overview) chip in the most convenient way. With ESP-WHO, you can easily build up face detection- and recognition-featured applications, for instance:
+* A coffee machine that brews coffee according to your taste preference;
+* Home applicance that will shut off the electricity automatically when unsupervised children are operating them;
+* And other more applications that suit your needs.
 
-ESP-WHO provides examples such as Human Face Detection, Human Face Recognition, Cat Face Detection, Gesture Recognition, etc. You can develop a variety of practical applications based on these examples. ESP-WHO runs on ESP-IDF. [ESP-DL](https://github.com/espressif/esp-dl) provides rich deep learning related interfaces for ESP-WHO, which can be implemented with various peripherals to realize many interesting applications.
+In general, the ESP-WHO features will be supported as shown below:
 
-<p align="center">
-    <img width="%" src="./img/architecture_en.drawio.svg"> 
-</p>
+![overview](img/overview.jpg)
 
+In ESP-WHO, Detection, Recognition and Image Utility are at the core of the platform.
 
 
-## What You Need
+* **Image Utility** offers fundamental image processing APIs.
 
-### Hardware
+* **Detection** takes images as input and give the position of face if there is a face. It is implemented with MTMN model, which refers to [MTCNN](http://cn.arxiv.org/abs/1604.02878) and [MobileNets](https://arxiv.org/abs/1801.04381).
 
-We recommend novice developers to use the development boards designed by Espressif. The examples provided by ESP-WHO are developed based on the following Espressif development board, and the corresponding relationships between the development boards and SoC are shown in the table below.
-
-|    SoC    | [ESP32](https://www.espressif.com/en/products/socs/esp32) | [ESP32-S2](https://www.espressif.com/en/products/socs/esp32-s2) | [ESP32-S3](https://www.espressif.com/en/products/socs/esp32-s3) |
-| :------- | :----------------------------------------------------------: | :----------------------------------------------------------: | :----------------------------------------------------------: |
-| Development Board | [ESP-EYE](https://www.espressif.com/en/products/devkits/esp-eye/overview) | [ESP32-S2-Kaluga-1](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/hw-reference/esp32s2/user-guide-esp32-s2-kaluga-1-kit.html) | [ESP-S3-EYE](https://www.espressif.com/en/products/devkits/esp-s3-eye/overview) |
+* **Recognition** is to identify the particular person, and it needs the results of detection. It is implemented with MobileFace model.
 
-> Using a development board not mentioned in the table above, configure pins assigned to peripherals manually, such as camera, LCD, and buttons.
+* **Optimization** is mainly to increase the precision of the inference, and to accelerate the whole process. But also it might change the structure of the network, update the coefficients, refactor the code, etc.
 
-### Software
+Both input and output are flexible.
 
-#### Get ESP-IDF
+* Image sources could be **input** via camera. However, we don't provide many drivers right now, those for other camera modules will be released in the future.
 
-ESP-WHO runs on ESP-IDF. For details on getting ESP-IDF, please refer to [ESP-IDF Programming Guide](https://idf.espressif.com/).
+* Results could be **output** and displayed through Command line, LCD or even website via Wi-Fi http service.
 
-> Please use the latest version of ESP-IDF on the master branch.
 
-#### Get ESP-WHO
+# Quick Start with ESP-WHO
 
-Run the following commands in your terminal to download ESP-WHO:
+## Hardware Preparation
 
-```bash
-git clone --recursive https://github.com/espressif/esp-who.git
-```
+To run ESP-WHO, you need to have a development board which integrates a **ESP32 module** that has sufficient GPIO pins and more than **4 MB** external SPI RAM. Either [ESP-WROVER-KIT](https://www.espressif.com/en/products/hardware/esp-wrover-kit/overview) or [ESP-EYE](https://www.espressif.com/en/products/hardware/esp-eye/overview) can be a good choice as the test board.
 
-> Remember to use ``git submodule update --recursive --init`` to pull and update submodules of ESP-WHO.
-
-## Run Examples
-
-All examples of ESP-WHO are stored in [examples](./examples) folder. Structure of this folder is shown below:
-
-```bash
-├── examples
-│   ├── cat_face_detection          // Cat Face Detection examples
-│   │   ├── lcd                     // Output displayed on LCD screen
-│   │   └── terminal                // Output displayed on terminal
-│   ├── code_recognition            // Barcode and QR Code Recognition examples
-│   ├── human_face_detection        // Human Face Detection examples
-│   │   ├── lcd
-│   │   └── terminal
-│   ├── human_face_recognition      // Human Face Recognition examples
-│   │   ├── lcd
-│   │   ├── terminal
-│   │   └── README.md               // Detailed description of examples
-│   └── motion_detection            // Motion Detection examples
-│       ├── lcd 
-│       ├── terminal
-│       ├── web
-│       └── README.rst              
-```
+On how to configure ESP32 module for your applications, please refer to the README.md of each example.
+
+
+## Software Preparation
+
+### Image
+
+The recommended resolution of input image is **QVGA (320x240)**.
+
+As for choosing camera as an image offer, make sure that the ESP32 module you choose offers specific pins that your camera needs.
+
+By now, we have provided some drivers of cameras, which are highly recommended to get started with:
+
+**OV2640**
 
-For the development boards mentioned in [Hardware](#Hardware), all examples are available out of the box. To run the examples, you only need to perform [Step 1: Set the target chip] (#Step-1 Set the target chip) and [Step 4: Launch and monitor] (#Step-4 Launch and monitor).
+**OV3660**
 
-### Step 1: Set the target chip
+**OV5640**
 
-Open the terminal and go to any folder that stores examples (e.g. examples/human_face_detection/lcd). Run the following command to set the target chip: 
+### ESP-WHO
+Make sure you clone the project recursive:
 
-```bash
-idf.py set-target [SoC]
 ```
+git clone --recursive https://github.com/espressif/esp-who.git 
+```
+
+If you clone project without `--recursive` flag, please go to the `esp-who` directory and run command `git submodule update --init` before doing anything.
+
+### ESP-IDF
+See setup guides for detailed instructions to set up the ESP-IDF:
+
+* [Getting Started Guide for ESP-IDF v4.0](https://docs.espressif.com/projects/esp-idf/en/v4.0/get-started/index.html)
 
-Replace [SoC] with your target chip, e.g. esp32, esp32s2, esp32s3.
+ We take [ESP-IDF v4.0](https://github.com/espressif/esp-idf/tree/release/v4.0) as the default version.
 
-### (Optional) Step 2: Configure the camera
+ > Now this repository supports two versions of IDF: v3.3.1 and v4.0.0.
 
-If not using the Espressif development boards mentioned in [Hardware](#Hardware), configure the camera pins manually. Enter `idf.py menuconfig` in the terminal and click (Top) -> Component config -> ESP-WHO Configuration to enter the ESP-WHO configuration interface, as shown below:
 
-![](./img/esp-who_config.png)
+# Components
 
-Click Camera Configuration to select the pin configuration of the camera according to the development board you use, as shown in the following figure:
+Components is the main framework of the SDK, with some drivers and algorithm inside.
 
-![](./img/esp-who_config_camera_config_select_pinout.png)
+## Camera
 
-If the board you are using is not shown in the figure above, please select ``Custom Camera Pinout`` and configure the corresponding pins correctly, as shown in the following figure: 
+The [camera](https://github.com/espressif/esp32-camera/tree/master) component contains drivers for camera devices of ESP32.
 
-![](./img/esp-who_config_camera_config_custom.png)
 
-### (Optional) Step 3: Configure the Wi-Fi
+## esp-face
 
-If the output of example is displayed on web server, click Wi-Fi Configuration to configure Wi-Fi password and other parameters, as shown in the following figure: 
+The [esp-face](https://github.com/espressif/esp-face/tree/master) component contains the APIs of ESP-WHO neural networks, including face detection and recognition framework.
 
-![](./img/esp-who_config_wifi_config.png)
 
-### Step 4: Launch and monitor
+# Examples
+The folder of [examples](examples) contains sample applications demonstrating the API features of ESP-WHO.
 
-Flash the program and launch IDF Monitor:
+Take one Face Detection as an example.
 
-```bash
-idf.py flash monitor
+1. Get into one example folder `esp-who/examples/single_chip/face_detection_with_command_line`.
+```
+cd esp-who/examples/single_chip/face_detection_with_command_line
+```
+
+2. Compile and flash the project.
+```
+idf.py build
+idf.py flash -p [PORT]
 ```
+3. Advanced users can modify some options by using the command `idf.py menuconfig`.
 
+The default configuration of all examples is based on [ESP-EYE](https://www.espressif.com/en/products/hardware/esp-eye/overview).
 
-## Default Binaries of Development Boards
+Check README.md of each example for more details.
 
-The default binaries for each development board are stored in the folder [default_bin](./default_bin). You can use Flash Download Tool (https://www.espressif.com/en/support/download/other-tools) to flash binaries.
 
+# Default bin
 
+The default bin is [HERE](docs/zh_CN/get-started/default_bin/). You can use [Flash Download Tools](https://www.espressif.com/en/support/download/other-tools) to write the default bin to the ESP-EYE.
 
-## Feedback
+# Resources
 
+* [Check the Issues section on github](https://github.com/espressif/esp-who/issues) if you find a bug or have a feature request, please check existing Issues before opening a new one.
 
-Please submit an [issue](https://github.com/espressif/esp-who/issues) if you find any problems using our products, and we will reply as soon as possible.
+* If you're interested in contributing to ESP-WHO, please check the [Contributions Guide](https://esp-idf.readthedocs.io/en/latest/contribute/index.html).

components/modules/Kconfig

@@ -82,6 +82,8 @@ menu "ESP-WHO Configuration"
                 bool "M5Stack Camera F (Wide)"
             config CAMERA_MODULE_AI_THINKER
                 bool "ESP32-CAM by AI-Thinker"
+            config CAMERA_MODULE_S3_KS_DIY
+                bool "ESP32-S3-CAM by S3_KS-DIY"
             config CAMERA_MODULE_CUSTOM
                 bool "Custom Camera Pinout"
         endchoice

components/modules/camera/who_camera.h

@@ -171,6 +171,26 @@
 #define CAMERA_PIN_HREF 23
 #define CAMERA_PIN_PCLK 22
 
+#elif CONFIG_CAMERA_MODULE_S3_KS_DIY
+#define CAMERA_MODULE_NAME "S3_KS_DIY"
+#define CAMERA_PIN_PWDN -4
+#define CAMERA_PIN_RESET -1
+#define CAMERA_PIN_XCLK -1
+#define CAMERA_PIN_SIOD 17
+#define CAMERA_PIN_SIOC 18
+
+#define CAMERA_PIN_D7 39
+#define CAMERA_PIN_D6 41
+#define CAMERA_PIN_D5 42
+#define CAMERA_PIN_D4 5
+#define CAMERA_PIN_D3 40
+#define CAMERA_PIN_D2 14
+#define CAMERA_PIN_D1 47
+#define CAMERA_PIN_D0 45
+#define CAMERA_PIN_VSYNC 21
+#define CAMERA_PIN_HREF 38
+#define CAMERA_PIN_PCLK 48
+
 #elif CONFIG_CAMERA_MODULE_CUSTOM
 #define CAMERA_MODULE_NAME "CUSTOM"
 #define CAMERA_PIN_PWDN CONFIG_CAMERA_PIN_PWDN

examples/code_recognition/main/include/app_peripherals.h

@@ -174,6 +174,25 @@
 #define CAMERA_PIN_HREF 23
 #define CAMERA_PIN_PCLK 22
 
+#elif CONFIG_CAMERA_MODULE_S3_KS_DIY
+#define CAMERA_MODULE_NAME "S3_KS_DIY"
+#define CAMERA_PIN_PWDN -1
+#define CAMERA_PIN_RESET -1
+#define CAMERA_PIN_XCLK -1
+#define CAMERA_PIN_SIOD 17
+#define CAMERA_PIN_SIOC 18
+
+#define CAMERA_PIN_D7 39
+#define CAMERA_PIN_D6 41
+#define CAMERA_PIN_D5 42
+#define CAMERA_PIN_D4 5
+#define CAMERA_PIN_D3 40
+#define CAMERA_PIN_D2 14
+#define CAMERA_PIN_D1 47
+#define CAMERA_PIN_D0 45
+#define CAMERA_PIN_VSYNC 21
+#define CAMERA_PIN_HREF 38
+#define CAMERA_PIN_PCLK 48
 #elif CONFIG_CAMERA_MODULE_CUSTOM
 #define CAMERA_MODULE_NAME "CUSTOM"
 #define CAMERA_PIN_PWDN CONFIG_CAMERA_PIN_PWDN
@@ -197,8 +216,8 @@
 
 #define XCLK_FREQ_HZ 20000000
 #define CAMERA_PIXFORMAT PIXFORMAT_RGB565
-#define CAMERA_FRAME_SIZE FRAMESIZE_240X240
-#define CAMERA_FB_COUNT 2
+#define CAMERA_FRAME_SIZE FRAMESIZE_QVGA
+#define CAMERA_FB_COUNT 1
 
 
 
@@ -232,6 +251,23 @@
 #define LCD_WIDTH       240
 #define LCD_HEIGHT      320
 #define LCD_ROTATE      SCR_SWAP_XY|SCR_MIRROR_X
+
+#elif CAMERA_MODULE_S3_KS_DIY
+#define LCD_CONTROLLER SCREEN_CONTROLLER_ST7789
+
+#define LCD_MOSI 11
+#define LCD_MISO 13
+#define LCD_SCLK 12
+#define LCD_CS 10
+#define LCD_DC 9
+#define LCD_RST -1
+#define LCD_BCKL -1
+
+// LCD display width and height
+#define LCD_WIDTH       240
+#define LCD_HEIGHT      320
+#define LCD_ROTATE      SCR_SWAP_XY|SCR_MIRROR_X
+
 #endif
 
 

examples/single_chip/camera_web_server/README.md

@@ -0,0 +1,22 @@
+# Camera with Web Server
+
+# Preparation
+
+To run this example, you need the following components:
+
+* An ESP32 Module: Either **ESP32-WROVER-KIT** or **ESP-EYE**, which we highly recommend for beginners, is used in this example.
+* A Camera Module: Either **OV2640** or **OV3660** or **OV5640** image sensor, which we highly recommend for beginners, is used in this example.
+
+# Quick Start
+
+After you've completed the hardware settings, please follow the steps below:
+
+1. **Connect** the camera to ESP32 module. For connection pins, please see [here](../../../docs/en/Camera_connections.md)
+2. **Configure** the example through `idf.py menuconfig`;
+3. **Build And Flash** the application to ESP32;
+4. **Open Your Browser** and point it to `http://[ip-of-esp32]/`;
+5. **To Get Image** press `Get Still` or `Start Stream`;
+6. **Use The Options** to enable/disable Face Detection, Face Recognition and more;
+7. **View The Stream**  in a player like VLC: Open Network `http://[ip-of-esp32]:81/stream`;
+
+For more details of the http handler, please refer to [esp32-camera](https://github.com/espressif/esp32-camera).