docs: add user getting started

Co-authored-by: Tang Chun Yap Co-authored-by: Cao Yan
2021-11-18 19:42:25 +08:00
parent f786c5e624
commit 320ad4fd0e
40 changed files with 379 additions and 5 deletions
@@ -1,3 +0,0 @@
-
-* [English Version](../README.md)
-
@@ -0,0 +1,190 @@
+* [中文版本](./getting_started_cn.md)
+
+# Getting Started
+
+The ESP32-S3-BOX gives you a simple idea of controlling the home appliances using Voice Assistance + touch screen controller, sensor, infrared controller, and intelligent Wi-Fi gateway via the ESP32-S3-BOX. With the abundant SDKs and solutions provided by Espressif, you will be able to develop a wide variety of AIoT applications such as online and offline voice assistants, voice-enabled devices, HMI touch-screen devices, control panels, multi-protocol gateways, with great ease. 
+
+The most impressive part of the ESP32-S3-BOX is the AI voice interaction that allows you to change the command phrases to control the smart home appliances. The content of this material is only to give you a brief concept of how the ESP32-S3-BOX works, a basic idea for you to know where to begin. Once you go through the guide below, you may start developing the application yourself. So, let’s begin the journey! 
+
+<div align="center">
+<img src="_static/esp_s3_box_outline.png">
+</div>
+
+**What is in the ESP32-S3-BOX Kit:**
+
+1. ESP32-S3-BOX main unit
+2. Dock (Stand for ESP32-S3-BOX)
+3. RGB LED Module & Dupont wires for testing
+
+**What do you need:**
+
+1. Type-C Cable (not included in the BOX Kit)
+
+
+## Connect the RGB LED Module to the BOX
+
+1. Refer to the pin definition below, insert the RGB LED Module to the BOX.
+2. The RGB LED Module has four male pins: R, G, B, GND connect to the G39, G40, G41, GND female port of the PMOD 1.
+3. Only one unit of RGB Module is provided in the kit.
+
+<div align="center">
+<img src="./_static/hardware_pmod.png">
+</div>
+
+## Power on the ESP32-S3-BOX
+
+1. Use a Type-C cable (not included in the ESP32-S3-BOX kit) to power on the ESP32-S3-BOX.
+
+<div align="center">
+<img src="_static/plug_power.png">
+</div>
+
+2. Once power on, the interactive Espressif logo will display on the screen.
+
+<div align="center">
+<img src="./_static/boot_animation.png">
+</div>
+
+## Let’s play around with the ESP32-S3-BOX!
+
+1. Initially, the “Steps for usage” pop-up window gives you a hint of how to use the AI Voice Assistance. 
+
+   <div align="center">
+   <img src="./_static/page_use_intr.png">
+   </div>
+
+2. Follow the “Steps for usage” or press the “OK Let’s Go” to skip this and return to the Home Screen.
+
+   <div align="center">
+   <img src="./_static/page_home.png">
+   </div>
+
+3. Similarly, you may press the “Red Circle” on the device and return to the Home Screen.
+
+   <div align="center">
+   <img src="./_static/hardware_home.png">
+   </div>
+
+4. Now, say the wake word “Hi ESP” to activate your ESP32-S3-BOX. If the board wakes up, its screen below will display the wake word you just spoke. If the wake word is not displayed, try the wake word more times.  The animation below gives you a hint that your device is listening.
+
+   <div align="center">
+   <img src="./_static/page_hi.png">
+   </div>
+
+5. Please voice out one command phrase within 6 seconds each time and say your command such as “**Turn on the light**”, the command phrase will display on the screen, and the RGB light of the LED Module will be turned on. Around 1s, the voice user interface jumps back to the Home Screen.
+
+   <div align="center">
+   <img src="_static/page_turn_on_the_light.png">
+   </div>
+
+6. The default command words are: "**Turn on the light**", "**Turn off the light**", "**Turn Red**", "**Turn Green**", "**Turn Blue**", "**Turn White**".
+
+   <div align="center">
+   <img src="_static/page_timeout.png">
+   </div>
+
+   >**Tips:**
+   >* Check the connection of the RGB Module if the LED is not turned on. The pin of the RGB Module may be inserted into the wrong port of the BOX.
+   >* If received no command within the specified time, the voice user interface will show “Timeout” and jump back to the Home Screen.
+
+7. Press the Mute button on the top of the ESP32-S3-BOX to disable the voice wake-up and speech recognition function. Press again to restore the function.
+
+   <div align="center">
+   <img src="_static/hardware_mute_button.jpg">
+   </div>
+
+## Voice Assistance Control and Customization
+
+The most impressive part of this ESP32-S3-BOX is equipped with the Espressif proprietary AI Voice Recognition system. Meaning, you could customize the command phrases used to give the instructions. For the details of how this works, please refer to our Developer Guide.
+
+**Let’s begin to learn about the Voice Command Customization:**
+
+**1. First, connect to the ESP32-S3-BOX Wi-Fi simply using your phone**
+
+1.1. Click on the “Wi-Fi” logo from the Home Screen that appears at the upper left corner.
+
+   <div align="center">
+   <img src="_static/page_wifi_lable.png">
+   </div>
+
+1.2. You will see a QR Code (as below) once you press the Wi-Fi logo.
+
+   <div align="center">
+   <img src="_static/page_scan_qrcode.png">
+   </div>
+
+1.3. Simply turn on the QR code scanner APP on your phone or your phone’s Camera to do network provisioning. For iPhone users, you may turn on your Camera.
+
+   <div align="center">
+   <img src="_static/phone_scan_qrcode.png">
+   </div>
+
+**2. Visit Web Control Interface “192.168.4.1”**
+
+Scan another QR code again, and it will redirect you to the web control interface. Alternatively, you can turn on the mobile phone browser, enter the IP address “192.168.4.1”.
+
+   <div align="center">
+   <img src="_static/page_scan_qrcode2.png">
+   </div>
+
+   <div align="center">
+   <img src="_static/phone_scan_qrcode2.png">
+   </div>
+
+**3. Voice Command Customization**
+
+   1. You can simply turn on & turn off the light from this user interface；
+
+   <div align="center">
+   <img src="_static/web_config_light.JPG">
+   </div>
+
+   2. Press on the “light” icon and navigate to the Voice Command Device Control page to check the current default pin information and command word；
+
+   <div align="center">
+   <img src="_static/web_config_light_cmd.JPG">
+   </div>
+
+   3. The "Control” allows you to make the necessary changes to the light, including color, brightness and saturation。
+
+   <div align="center">
+   <img src="_static/web_config_light_ctrl.JPG">
+   </div>
+
+   4. The “Voice" Section allows you to modify the preference command phrases to control the light **“ON”**, **“OFF”** and **“Color”**. For example, you can custom the **“Good morning”** for action **“ON”**, click save, the page return back to the previous interface, and click save again；
+
+   <div align="center">
+   <img src="_static/web_config_light_cmd_cg.JPG">
+   </div>
+
+   5. Now, you can try out your new command! First, say “Hi ESP” to wake-up your device. Then say **“Good morning”** to turn on your light within 6 seconds. The new command phrase will display on the screen and the LED module will be turned on as below.。
+
+   <div align="center">
+   <img src="_static/page_good_morning.png">
+   </div>
+
+## ESP32-S3-BOX Graphical User Interface
+
+1. Press on the “function” logo from the Home Screen that appears at the upper right corner and navigate to the User Interface.
+
+   <div align="center">
+   <img src="./_static/page_panel_lable.png">
+   </div>
+
+2. Press on the “Light” icon will allow you to turn on and turn off the light.
+3. Long press the “Light” icon to navigate to the Light Tuning Interface, which allows changing the color display. Long press the Light Tuning Circle again to adjust the light saturation and brightness, respectively.
+4. The built-in function above is pre-programmed to give you a brief idea of how this ESP32-S3-BOX can be used in your project. 
+
+   <div align="center">
+   <img src="_static/page_panel_color.png">
+   </div>
+
+5. The other three icons (Media, Fan, Security) are added for illustration purposes, and you may start writing your exciting application program! Begin your IoT Journey!
+
+   <div align="center">
+   <img src="_static/page_panel_control.png">
+   </div>
+
+## ESP-BOX BBS
+
+Visit the BBS [esp32.com](https://esp32.com/viewforum.php?f=44) to question us or contact us at sales@espressif.com, and we will reply to you as soon as possible.
@@ -0,0 +1,187 @@
+* [English Version](./getting_started.md)
+
+# 开始使用
+
+ESP32-S3-BOX 通过使用语音助手+触摸屏控制器、传感器、红外控制器和智能 Wi-Fi 网关的概念来助力您开发 AI 智能语音项目。ESP32-S3-BOX 出厂支持语音唤醒和离线中英文命令词识，通过乐鑫丰富的 SDK 和解决方案，能够轻松构建在线和离线语音助手、智能语音设备、HMI 触摸屏设备、控制面板、多协议网关等多样的应用。
+
+更令人印象深刻的部分是它允许您更改命令词以控制智能电器。本文的内容仅为您简要介绍 ESP32-S3-BOX 能实现的参考功能，让您了解从如何开始。一旦您完成阅读下面的指南，您可以尝试开始自己开发应用。让我们开始旅程吧！
+
+   <div align="center">
+   <img src="_static/esp_s3_box_outline.png">
+   </div>
+
+**ESP32-S3-BOX 套件包含:**
+
+1. 主机，可独立使用；
+2. Dock 配件, 辅助主机站在桌面；
+3. 供测试的 LED 模块和杜邦线。
+
+**你可能还需要：**
+
+1. Type-C 数据线 (不包含在 ESP32-S3-BOX Kit 内)
+
+## 将 LED 模块插入 ESP32-S3-BOX
+
+1. 参考下面的引脚定义，将 RGB LED 模块插入 ESP32-S3-BOX；
+2. RGB LED 模块有四根公头针脚：分别将 R、G、B、GND 插入 PMOD 1 的 G39、G40、G41、GND 母头端口；
+3. 套件中仅提供一个 RGB 模块。
+
+   <div align="center">
+   <img src="./_static/hardware_pmod.png">
+   </div>
+
+## 给 ESP32-S3-BOX 供电
+
+1. 使用一根 Type-C 数据线（不包含在 ESP32-S3-BOX 套件中）给 ESP32-S3-BOX 供电；
+
+   <div align="center">
+   <img src="_static/plug_power.png">
+   </div>
+
+2. 设备启动后，屏幕上将显示 Espressif logo 的开机动画；
+
+   <div align="center">
+   <img src="./_static/boot_animation.png">
+   </div>
+
+## 开始体验 ESP32-S3-BOX
+
+1. 首先您会看到 “使用说明” 弹窗，请仔细阅读，它会提示您如何使用 AI 语音功能；
+
+   <div align="center">
+   <img src="./_static/page_use_intr_cn.png">
+   </div>
+
+2. 点击 “确认” 完成“使用说明” 的阅读并回到主页；
+
+   <div align="center">
+   <img src="./_static/page_home.png">
+   </div>
+
+3. 您也可以轻触触摸屏下方的 “小红圈” 回到主页；
+
+   <div align="center">
+   <img src="./_static/hardware_home.png">
+   </div>
+
+4. 现在，请使用唤醒词 “Hi 乐鑫” 去唤醒设备。设备唤醒成功后，唤醒词将显示在如下屏幕上并伴有提示音，如果唤醒词未出现，请再次尝试。如下展示的动画提示您的设备正在聆听；
+
+   <div align="center">
+   <img src="_static/page_hi_cn.png">
+   </div>
+
+5. 请在提示音响起后的 6 秒左右时间内对设备说命令词，比如 “**打开电灯**”，同时命令词将显示在屏幕上并且 LED 模块打开。约 1s 后语音控制界面退出；
+
+   <div align="center">
+   <img src="_static/page_turn_on_the_light_cn.png">
+   </div>
+
+6. 默认命令词为："**打开电灯**", "**关闭电灯**", "**调成红色**", "**调成绿色**", "**调成蓝色**", "**调成白色**"；
+
+   <div align="center">
+   <img src="_static/page_timeout_cn.png">
+   </div>
+
+    >注意:
+    > 如果 LED 灯没有被打开，请检察 RGB 模块的 pin 脚是否插错；
+    > 若在规定时间内未识别到命令词，则显示超时，约 1s 后界面关闭。
+
+7. 按下 ESP32-S3-BOX 顶部的静音按钮，按下后设备语音唤醒和识别功能被禁用，再次按下恢复语音功能。
+
+   <div align="center">
+   <img src="_static/hardware_mute_button.jpg">
+   </div>
+
+## 语音控制命令词自定义
+
+ESP32-S3-BOX 最令人印象深刻的功能是乐鑫专有的 AI 语音识别系统。您可以自定义用于指令的任意命令词。有关其工作原理的详细信息，请参阅我们 GIthub 上的开发指南。让我们开始了解语音命令词自定义：
+
+**1. 首先，请将你的手机连接 ESP32-S3-BOX 的 Wi-Fi**
+
+1.1. 点击主页左上角的 Wi-Fi 图标；
+
+   <div align="center">
+   <img src="_static/page_wifi_lable.png">
+   </div>
+
+1.2. 您将看到如下二维码界面；
+
+   <div align="center">
+   <img src="_static/page_scan_qrcode.png">
+   </div>
+
+1.3. 打开你手机上的二维码扫描软件或者摄像机扫码配网，对于 iPhone 用户，您可以打开摄像机（如扫码失败，请手动打无线网络，找到 “ ESP-Box” 无线网络，然后输入密码 “espressif”）；
+
+   <div align="center">
+   <img src="_static/phone_scan_qrcode.png">
+   </div>
+
+**2. 访问 Web “192.168.4.1” 进入控制界面**
+
+再次扫码进入 Web 控制界面，或者打开手机浏览器，输入IP地址 “192.168.4.1”。
+
+   <div align="center">
+   <img src="_static/page_scan_qrcode2.png">
+   </div>
+
+   <div align="center">
+   <img src="_static/phone_scan_qrcode2.png">
+   </div>
+
+**3. 自定义语音命令词**
+
+   1. 您可以简单地在这个用户界面进行开灯或者关灯；
+
+   <div align="center">
+   <img src="_static/web_config_light.JPG">
+   </div>
+
+   2. 点按 “light” 图标并进入到语音命令控制页面查看当前默认的 Pin 脚信息和命令词；
+
+   <div align="center">
+   <img src="_static/web_config_light_cmd_cn.JPG">
+   </div>
+
+   3. “设备控制” 允许您对灯光进行颜色、亮度和饱和度的更改。
+
+   <div align="center">
+   <img src="_static/web_config_light_ctrl_cn.JPG">
+   </div>
+
+   4. “语音指令” 部分允许您针对设备的 **“开”**、**“关”**、**“颜色”** 修改您喜欢的命令词来控制设备。比如，您可以定义 **“开”** 的命令词为 **“早上好”**，点击保存，界面返回上一级，然后再点击保存；
+
+   <div align="center">
+   <img src="_static/web_config_light_cmd_cg_cn.JPG">
+   </div>
+
+   5. 现在，您可以体验您的新命令词了！请先使用 **“Hi 乐鑫”** 去唤醒设备，然后在**6秒**内说出打开电灯的新命令词 **“早上好”**，新命令词会显示在屏幕上并且 LED 模块打开。
+
+   <div align="center">
+   <img src="_static/page_good_morning_cn.png">
+   </div>
+
+## ESP32-S3-BOX 图形界面
+
+1. 点击主页右上角的功能图标进入用户界面；
+
+   <div align="center">
+   <img src="./_static/page_panel_lable.png">
+   </div>
+
+2. 点按 “Light” 图标将允许您打开和关闭灯；
+3. 长按 “Light” 图标将进入灯光调整界面，可以更改颜色显示。再次长按调光圆环，分别可调节灯光饱和度和亮度；
+4. 以上出厂功能是预编程的，目的是让您简要了解如何在您的项目中使用此 ESP32-S3-BOX；
+
+   <div align="center">
+   <img src="_static/page_panel_color.png">
+   </div>
+
+5. 其他三个功能图标（Media、Fan、Security）仅用于展示，暂未开发。您可以尝试编写令人兴奋的应用程序，请开启您的物联网之旅；
+
+   <div align="center">
+   <img src="_static/page_panel_control.png">
+   </div>
+
+## ESP-BOX 论坛
+
+访问乐鑫 BBS 论坛 [esp32.com](https://esp32.com/viewforum.php?f=44) 给我们提问，或者通过 sales@espressif.com 邮箱联系我们，我们将尽快答复您。
@@ -6,9 +6,9 @@ set -ex

 if [ -n "${CI_COMMIT_TAG}" ]; then
    # for tags
-    git push github "${CI_COMMIT_TAG}"
+    git push --force github "${CI_COMMIT_TAG}"
 else
    # for branches
-    git push github "${CI_COMMIT_SHA}:refs/heads/${CI_COMMIT_REF_NAME}"
+    git push github --force "${CI_COMMIT_SHA}:refs/heads/${CI_COMMIT_REF_NAME}"
 fi