|
| 1 | +# LOG ROUTER |
| 2 | + |
| 3 | +The `log_router` is an extension component of `esp_log` that allows users to save logs of specific levels and tags through the file system. By configuring the save path, log level, and tag filter, logs can be redirected to corresponding log files while preserving the original log output. This component provides the following features: |
| 4 | + |
| 5 | +1. Supports redirecting logs of specific levels to the file system while preserving the original log output interface |
| 6 | +2. Supports filtering logs by specific tags to capture only relevant log messages |
| 7 | +3. Supports batch writing of logs to the file system to avoid frequent flash operations |
| 8 | + |
| 9 | +## How to Configure Router Parameters |
| 10 | + |
| 11 | +First, you need to define a log partition with type `data` and subtype `fat` in the partition table, or access an SD card or external flash through the FAT file system, and complete the initialization and mounting of the FAT file system in your application. |
| 12 | + |
| 13 | +This mounting process is typically implemented using convenience functions such as `esp_vfs_fat_spiflash_mount()` or `esp_vfs_fat_sdmmc_mount()`, which are responsible for formatting the underlying FAT partition (if needed), mounting it, and registering it to ESP-IDF's Virtual File System (VFS). Once completed, you can use standard C file operation functions (such as fopen(), fread(), fprintf(), etc.) to read and write to this file system, just like operating on local files, facilitating tasks such as log storage and configuration persistence. |
| 14 | + |
| 15 | +> **Note:** `log_router` as a middleware does not handle the initialization of the FAT file system. Please complete the initialization and mounting of the FAT file system before using `log_router`. Additionally, the current version may occupy certain system time when writing due to timeout or reaching the set threshold, which may affect some time-sensitive programs. |
| 16 | +
|
| 17 | +## Add component to your project |
| 18 | + |
| 19 | +Please use the component manager command `add-dependency` to add the `log_router` to your project's dependency, during the `CMake` step the component will be downloaded automatically |
| 20 | + |
| 21 | +``` |
| 22 | +idf.py add-dependency "espressif/log_router=*" |
| 23 | +``` |
| 24 | + |
| 25 | +Alternatively, you can create `idf_component.yml`. More is in [Espressif's documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-component-manager.html). |
| 26 | + |
| 27 | +## How to use |
| 28 | + |
| 29 | +The usage of ``log_router`` is very simple. You only need to call `esp_log_router_to_file` and fill in the file to redirect to, the specified `tag` and `level` to achieve log redirection. Note that if `tag` is `NULL`, all logs greater than or equal to the set `level` will be saved. |
| 30 | + |
| 31 | +```c |
| 32 | +// Step1: Initialize FAT file system |
| 33 | + |
| 34 | +... |
| 35 | + |
| 36 | +// Step2: Redirect log output |
| 37 | + |
| 38 | +esp_log_router_to_file("/log/log.txt", TAG, ESP_LOG_WARN); |
| 39 | + |
| 40 | +// Step3: If you want to cancel log saving |
| 41 | + |
| 42 | +esp_log_delete_router("/log/log.txt"); |
| 43 | + |
| 44 | +``` |
| 45 | +
|
| 46 | +If you are using ``fatfs``, you can use the ``fatfsparse.py`` provided in the ``ESP-IDF`` SDK to parse it out. Take the following partition table as an example: |
| 47 | +
|
| 48 | +```csv |
| 49 | +# Name, Type, SubType, Offset, Size, Flags |
| 50 | +# Note: if you have increased the bootloader size, make sure to update the offsets to avoid overlap |
| 51 | +factory, app, factory, 0x10000, 1M, |
| 52 | +log, data, fat, , 500K, |
| 53 | +``` |
| 54 | + |
| 55 | +First, you need to read out the content of the specific partition: |
| 56 | + |
| 57 | +```shell |
| 58 | +parttool.py -p /dev/ttyUSB0 read_partition --partition-name=log --output "log.bin" |
| 59 | +``` |
| 60 | + |
| 61 | +Next, use the parsing script ``fatfsparse.py`` for parsing, which is located in the ``components/fatfs`` directory under the SDK: |
| 62 | + |
| 63 | +```shell |
| 64 | +cd ${IDF_PATH}/components/fatfs |
| 65 | +./fatfsparse.py log.bin |
| 66 | +``` |
0 commit comments