alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

docs: improve the installation instructions

Browse Source
This commit is contained in:
Fu Hanxi 2022-07-29 14:42:54 +08:00
parent d0a2849b02
commit 17e312f87b
12 changed files with 48 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
examples/README.md
View File

@ -42,14 +42,15 @@ Building an example is the same as building any other project:
## Running Test Python Script (ttfw)
Some of the examples have `..._test.py` scripts that are used to test that the example works as expected. These scripts run automatically in the internal test queue. They are not intended to be run by ESP-IDF users but sometimes you may want to run them locally. The following requirements must be met in the IDF python virtual environment.
Some of the examples have `..._test.py` scripts that are used to test that the example works as expected. These scripts run automatically in the internal test queue. They are not intended to be run by ESP-IDF users but sometimes you may want to run them locally.
- ttfw needs to be in the `PYTHONPATH`. Add it like this: `export PYTHONPATH=$PYTHONPATH:$IDF_PATH/tools/ci/python_packages`
- Install all requirements from `tools/ci/python_packages/ttfw_idf/requirements.txt`: `python -m pip install -r $IDF_PATH/tools/ci/python_packages/ttfw_idf/requirements.txt`
Install Python dependencies and export the Python path where the IDF CI Python modules are found with the following commands:
These commands help solve the issue with `ModuleNotFoundError: No module named 'ttfw_idf'` and `ModuleNotFoundError: No module named 'tiny_test_fw'`.
Some examples might fail due to other missing packages. You might need to install them manually: `pip install websocket`.
```bash
bash install.sh --enable-ttfw
source export.sh
export PYTHONPATH=$IDF_PATH/tools/ci/python_packages:$IDF_PATH/tools:$PYTHONPATH
```
## Running Test Python Script (pytest)

2
examples/bluetooth/nimble/ble_l2cap_coc/coc_blecent/README.md
View File

@ -21,7 +21,7 @@ Maximum data of 512 bytes can be transferred over L2CAP when MTU is set to 512 a
Note :
* Make sure to run `python -m pip install --user -r $IDF_PATH/requirements.txt -r $IDF_PATH/tools/ble/requirements.txt` to install the dependency packages needed.
* To install the dependency packages needed, please refer to the top level [README file](../../../../README.md#running-test-python-script-ttfw).
* Currently this Python utility is only supported on Linux (BLE communication is via BLuez + DBus).
## How to Use Example

4
examples/bluetooth/nimble/ble_l2cap_coc/coc_bleprph/README.md
View File

@ -21,8 +21,8 @@ Maximum data of 512 bytes can be transferred over L2CAP when MTU is set to 512 a
Note :
* Make sure to run `python -m pip install --user -r $IDF_PATH/requirements.txt -r $IDF_PATH/tools/ble/requirements.txt` to install the dependency packages needed.
* Currently this Python utility is only supported on Linux (BLE communication is via BLuez + DBus).
* To install the dependency packages needed, please refer to the top level [README file](../../../../README.md#running-test-python-script-ttfw).
* * Currently this Python utility is only supported on Linux (BLE communication is via BLuez + DBus).
## How to Use Example

2
examples/bluetooth/nimble/ble_spp/spp_client/README.md
View File

@ -76,7 +76,7 @@ It performs three GATT operations against the specified peer:
Note :
* Make sure to run `python -m pip install --user -r $IDF_PATH/requirements.txt -r $IDF_PATH/tools/ble/requirements.txt` to install the dependency packages needed.
* To install the dependency packages needed, please refer to the top level [README file](../../../../README.md#running-test-python-script-ttfw).
* Currently this Python utility is only supported on Linux (BLE communication is via BLuez + DBus).
## How to use example

2
examples/bluetooth/nimble/ble_spp/spp_server/README.md
View File

@ -76,7 +76,7 @@ It performs three GATT operations against the specified peer:
Note :
* Make sure to run `python -m pip install --user -r $IDF_PATH/requirements.txt -r $IDF_PATH/tools/ble/requirements.txt` to install the dependency packages needed.
* To install the dependency packages needed, please refer to the top level [README file](../../../../README.md#running-test-python-script-ttfw).
* Currently this Python utility is only supported on Linux (BLE communication is via BLuez + DBus).
## How to use example

2
examples/bluetooth/nimble/blecent/README.md
View File

@ -27,7 +27,7 @@ A Python based utility `blecent_test.py` is also provided (which will run as a B
Note :
* Make sure to run `python -m pip install --user -r $IDF_PATH/requirements.txt -r $IDF_PATH/tools/ble/requirements.txt` to install the dependency packages needed.
* To install the dependency packages needed, please refer to the top level [README file](../../../README.md#running-test-python-script-ttfw).
* Currently this Python utility is only supported on Linux (BLE communication is via BLuez + DBus).
## How to Use Example

2
examples/bluetooth/nimble/blehr/README.md
View File

@ -17,7 +17,7 @@ A Python based utility `blehr_test.py` is also provided (which will run as a BLE
Note :
* Make sure to run `python -m pip install --user -r $IDF_PATH/requirements.txt -r $IDF_PATH/tools/ble/requirements.txt` to install the dependency packages needed.
* To install the dependency packages needed, please refer to the top level [README file](../../../README.md#running-test-python-script-ttfw).
* Currently this Python utility is only supported on Linux (BLE communication is via BLuez + DBus).
## How to Use Example

2
examples/bluetooth/nimble/bleprph/README.md
View File

@ -21,7 +21,7 @@ A Python based utility `bleprph_test.py` is also provided (which will run as a B
Note :
* Make sure to run `python -m pip install --user -r $IDF_PATH/requirements.txt -r $IDF_PATH/tools/ble/requirements.txt` to install the dependency packages needed.
* To install the dependency packages needed, please refer to the top level [README file](../../../README.md#running-test-python-script-ttfw).
* Currently this Python utility is only supported on Linux (BLE communication is via BLuez + DBus).
## How to Use Example

2
examples/provisioning/wifi_prov_mgr/README.md
View File

@ -45,7 +45,7 @@ For iOS, a provisioning application along with source code is available on GitHu
#### Platform : Linux / Windows / macOS
To provision the device running this example, the `esp_prov.py` script needs to be run (found under `$IDF_PATH/tools/esp_prov`). Make sure to satisfy all the dependencies prior to running the script (check out the `requirements.txt` file in `esp_prov` directory).
To install the dependency packages needed, please refer to the top level [README file](../../README.md#running-test-python-script-ttfw).
`esp_prov` supports BLE and SoftAP transport for Linux, MacOS and Windows platforms. For BLE, however, if dependencies are not met, the script falls back to console mode and requires another application through which the communication can take place. The `esp_prov` console will guide you through the provisioning process of locating the correct BLE GATT services and characteristics, the values to write, and input read values.

9
tools/esp_prov/README.md
View File

@ -90,16 +90,17 @@ For Android, a provisioning tool along with source code is available [here](http
## Dependencies
This requires the following python libraries to run (included in requirements.txt):
This requires the following python libraries to run:
* `bleak`
* `future`
* `protobuf`
* `cryptography`
Run `pip install -r $IDF_PATH/tools/esp_prov/requirements.txt`
To install the dependency packages needed, please run the following command:
Note :
* The packages listed in requirements.txt are limited only to the ones needed AFTER fully satisfying the requirements of ESP-IDF
```shell
bash install.sh --enable-ttfw
```
# EXAMPLE USAGE

12
tools/test_apps/README.md
View File

@ -63,12 +63,14 @@ All the following instructions are general. Part of them may be complemented by
### Requirements
The following requirements need to be satisfied in the IDF python virtual environment.
Install Python dependencies and export the Python path where the IDF CI Python modules are found with the following commands:
- ttfw needs to be in the `PYTHONPATH`. Add it like this: `export PYTHONPATH=$PYTHONPATH:$IDF_PATH/tools/ci/python_packages`
- Install all requirements from `tools/ci/python_packages/ttfw_idf/requirements.txt`: `pip install -r $IDF_PATH/tools/ci/python_packages/ttfw_idf/requirements.txt`
You should also set the port via the environment variable ESPPORT to prevent the tools from looking and iterating over all serial ports. The latter causes much trouble, currently:
```bash
bash install.sh --enable-ttfw
source export.sh
export PYTHONPATH=$IDF_PATH/tools/ci/python_packages:$PYTHONPATH
```
You should also set the port via the environment variable `ESPPORT` to prevent the tools from looking and iterating over all serial ports. The latter causes much trouble, currently:
```
export ESPPORT=/dev/ttyUSB<X>

25
tools/unit-test-app/README.md
View File

@ -39,7 +39,7 @@ Unit test uses 3 stages in CI: `build`, `assign_test`, `unit_test`.
### Build Stage:
`build_esp_idf_tests` job will build all UT configs and run script `UnitTestParser.py` to parse test cases form built elf files. Built binary (`tools/unit-test-app/output`) and parsed cases (`components/idf_test/unit_test/TestCaseAll.yml`) will be saved as artifacts.
`build_esp_idf_tests` job will build all UT configs and run script `UnitTestParser.py` to parse test cases form built elf files. Built binary (`tools/unit-test-app/build_<target>_<config>`) and parsed cases (`components/idf_test/unit_test/TestCaseAll.yml`) will be saved as artifacts.
When we add new test case, it will construct a structure to save case data during build. We'll parse the test case from this structure. The description (defined in test case: `TEST_CASE("name", "description")`) is used to extend test case definition. The format of test description is a list of tags:
@ -63,7 +63,7 @@ We will build unit-test-app with different sdkconfigs. Some config items require
### Assign Test Stage:
`assign_test` job will try to assign all cases to test jobs defined in `.gitlab-ci.yml`, according to test environment and tags. For each job, one config file with same name of test job will be generated in `components/idf_test/unit_test/CIConfigs/`(this folder will be passed to test jobs as artifacts). These config files will tell test jobs which cases it need to run, and pass some extra configs (like if the case will reset) of test case to runner.
`assign_unit_test` job will try to assign all cases to test jobs defined in `.gitlab-ci.yml`, according to test environment and tags. For each job, one config file with same name of test job will be generated in `components/idf_test/unit_test/CIConfigs/`(this folder will be passed to test jobs as artifacts). These config files will tell test jobs which cases it need to run, and pass some extra configs (like if the case will reset) of test case to runner.
Please check related document in tiny-test-fw for details.
@ -110,7 +110,7 @@ First you can check the logs. It's saved as unit test job artifacts. You can dow
If you want to reproduce locally, you need to:
1. Download artifacts of `build_esp_idf_tests`. The built binary is in `tools/unit-test-app/output` folder.
1. Download artifacts of `build_esp_idf_tests`. The built binary is in `tools/unit-test-app/build_<target>_<config>` folder.
* Built binary in CI could be slightly different from locally built binary with the same revision, some cases might only fails with CI built binary.
2. Check the following print in CI job to get the config name: `Running unit test for config: config_name`. Then flash the binary of this config to your board.
3. Run the failed case on your board (refer to Running Unit Tests section).
@ -124,8 +124,9 @@ If you want to reproduce locally, you need to:
First, install Python dependencies and export the Python path where the IDF CI Python modules are found:
```bash
pip install -r $IDF_PATH/tools/ci/python_packages/tiny_test_fw/requirements.txt
export PYTHONPATH=$IDF_PATH/tools/ci/python_packages
bash install.sh --enable-ttfw
source export.sh
export PYTHONPATH=$IDF_PATH/tools/ci/python_packages:$PYTHONPATH
```
Change to the unit test app directory, configure the app as needed and build it in the default "build" directory. For example:
@ -138,6 +139,20 @@ idf.py build -T vfs
(Instead of these steps, you can do whatever is needed to configure & build a unit test app with the tests and config that you need.)
If you want to build exactly the same binary files under the same location as they are in CI pipelines, you may run:
```bash
cd $IDF_PATH
python tools/ci/ci_build_apps.py tools/unit-test-app -v -t $IDF_TARGET --config "configs/*=" --copy-sdkconfig --preserve-all
```
This would build all configs. if you want to build only one config (let's take `psram` as an example), you may use:
```bash
cd $IDF_PATH
python tools/ci/ci_build_apps.py tools/unit-test-app -v -t $IDF_TARGET --config "configs/psram=" --copy-sdkconfig --preserve-all
```
### run a single test case by name
```bash