Skip to content

Latest commit

 

History

History
146 lines (120 loc) · 6.01 KB

ADF_TEMPLATE_EXAMPLE_README_EN.md

File metadata and controls

146 lines (120 loc) · 6.01 KB

Note that this is a template for an ESP-ADF example README.md file. When using this template, replace all these emphasised placeholders with example-specific content.

Example Title

English Version or Chinese Version

Add a picture to describe the difficulty level

  • Basic Example: alt text - to get started
  • Regular Example: alt text - demonstrates functionality of ESP-ADF or audio board
  • Complex Example: alt text - like regular example but requires more configuration steps, interaction with other programs, setting up some cloud accounts, or more user expertise

Example Brief

  • Introduce the realization of the example program from a functional point of view
  • From a technical point of view, describe the main technical functions demonstrated. For example, to demonstrate the use of pipeline and element, element obtains data directly from callback

Resources

It's optional, such as RAM, CPU loading

Prerequisites

  • It's optional
  • Guide first-time users to run get started example first
  • Guide users to learn the background

Folder contents

  • It's optional
  • It is short explanation of remaining files in the project folder, e.g: play_mp3 folder
├── components
│   └── my_board
│       ├── my_board_v1_0
│       │   ├── board.c
│       │   ├── board.h
│       │   ├── board_def.h
│       │   └── board_pins_config.c
│       ├── my_codec_driver
│       │   ├── new_codec.h
│       │   └── new_codec.c
│       ├── CMakeLists.txt
│       ├── component.mk
│       └── Kconfig.projbuild
├── CMakeLists.txt
├── example_test.py            Python script used for automated example testing
├── main
│   ├── CMakeLists.txt
│   ├── component.mk           Component make file
│   ├── adf_music.mp3          Test music file
│   └── play_mp3_example.c
├── Makefile                   Makefile used by legacy GNU Make
└── README.md                  This is the file you are currently reading

Environment Setup

Hardware Required

List all the hardware, Such as Boards, speakers, SD card, LCD module, Camera module, Bluetooth speaker, etc.

Additional Requirements

  • It's optional
  • Such as Baidu Cloud's profile or Amazon's token authentication, tone bins, music files, etc.
  • Such as SIP server, DLNA APP, etc.

Example Set Up

Default IDF Branch

The default IDF branch is ADF's built-in branch $ADF_PATH/esp-idf

Other special IDF branches

  • When required to select a special IDF/ADF version branch, which must be clearly pointed out and described
  • For example, DU1906 project select the IDF branch audio/stack_on_psram_v3.3 to compile
cd $IDF_PATH
git checkout master
git pull
git checkout audio/stack_on_psram_v3.3
git submodule update --init --recursive

Configuration

  • Such as select compatible audio board in menuconfig > Audio HAL
  • Such as other important tips, such as turning on long file name support for fatfs
Component config > FAT Filesystem support > Long filename support

Build and Flash

Build the project and flash it to the board, then run monitor tool to view serial output:

idf.py build -p PORT flash monitor

How to use the Example

Example Functionality

  • To explain how to use this example, what features are supported and what results would be get
  • Such as description button functionality
  • If any other items (server, BLE device, app, second chip, whatever) are needed, mention them here. Include links if applicable. Explain how to set them up

For example, the DU1906 voice interaction command * "小度小度" "在呢" "讲个笑话" * "小度小度" "在呢" "上海天气怎么样？" * "小度小度" "在呢" "播放一首歌" * "小度小度" "在呢" "百度百科乐鑫信息科技"

e.g. pipeline_raw_http, run python server.py - place the file server.py at root of this example, and make sure this directory is writable

Example Logs

  • Select the booting log, e.g.
I (64) boot: Chip Revision: 3
I (35) boot: ESP-IDF v3.3.1-203-g0c1859a5a 2nd stage bootloader
I (35) boot: compile time 21:43:15
I (35) boot: Enabling RNG early entropy source...
I (41) qio_mode: Enabling default flash chip QIO
I (46) boot: SPI Speed      : 80MHz
I (50) boot: SPI Mode       : QIO
I (54) boot: SPI Flash Size : 8MB
I (58) boot: Partition Table:
I (62) boot: ## Label            Usage          Type ST Offset   Length
I (69) boot:  0 nvs              WiFi data        01 02 00009000 00004000
I (76) boot:  1 otadata          OTA data         01 00 0000d000 00002000
I (84) boot:  2 phy_init         RF data          01 01 0000f000 00001000
I (91) boot:  3 ota_0            OTA app          00 10 00010000 00280000
I (99) boot:  4 ota_1            OTA app          00 11 00290000 00280000
I (106) boot:  5 dsp_bin          Unknown data     01 24 00510000 00280000
I (114) boot:  6 profile          Unknown data     01 29 00790000 00001000
I (121) boot:  7 flash_tone       Unknown data     01 27 00791000 00060000
I (129) boot: End of partition table

References

Running results, text description, or video links, etc. (optional). e.g. ESP32-S3 Offline Speech Recognition

Troubleshooting

It's optional. If there are any likely problems or errors which many users might encounter, mention them here. Remove this section for very simple examples where nothing is likely to go wrong.

Technical support and feedback

Please use the following feedback channels:

  • For technical queries, go to the esp32.com forum
  • For a feature request or bug report, create a GitHub issue

We will get back to you as soon as possible.