You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+41-7Lines changed: 41 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# Espressif IDF Monitor
2
2
3
-
The ```esp-idf-monitor``` is a Python-based, open-source package that is part of the [ESP-IDF](https://github.com/espressif/esp-idf) SDK for Espressif products.
3
+
The `esp-idf-monitor` is a Python-based, open-source package that is part of the [ESP-IDF](https://github.com/espressif/esp-idf) SDK or can be used as a standalond tool for monitoring of Espressif microcontrollers.
4
4
5
5
The main responsibility of the IDF Monitor is serial communication input and output in ESP-IDF projects.
6
6
@@ -11,13 +11,47 @@ Other advanced topics like configuration file will be described in the following
11
11
12
12
### Table of Contents
13
13
14
+
-[Installation](#installation)
15
+
-[Usage](#usage)
14
16
-[Configuration File](#configuration-file)
15
17
-[File Location](#file-location)
16
18
-[Configuration Options](#configuration-options)
17
19
-[Custom Reset Sequence](#custom-reset-sequence)
18
20
-[Share Configuration Across Tools](#share-configuration-across-tools)
19
21
-[Syntax](#syntax)
20
22
23
+
## Installation
24
+
25
+
You can install the project with your favorite package manager, but for standalone installations it is recommended to use [uv](https://docs.astral.sh/uv/) or [pipx](https://pipx.pypa.io/stable/). Using one of the following commands:
26
+
27
+
```sh
28
+
uv install esp-idf-monitor
29
+
```
30
+
31
+
or
32
+
33
+
```sh
34
+
pipx install esp-idf-monitor
35
+
```
36
+
37
+
These will install an `idf-monitor` executable for the current user without requiring administrator privileges.
38
+
39
+
## Usage
40
+
41
+
Usually IDF Monitor is run within ESP-IDF environment, which prefills a lot of arguments for features such as address decoding. However, IDF Monitor can work as standalone tool as well. For the standalone mode run:
42
+
43
+
```sh
44
+
idf-monitor
45
+
```
46
+
47
+
or
48
+
49
+
```sh
50
+
python -m esp_idf_monitor
51
+
```
52
+
53
+
For all parameters and their function please see `idf-monitor --help`.
54
+
21
55
## Configuration File
22
56
23
57
`esp-idf-monitor` is using [C0 control codes](https://en.wikipedia.org/wiki/C0_and_C1_control_codes) to interact with the console. Characters from the config file are converted to their C0 control codes. Available characters include the English alphabet (A-Z) and special symbols: `[`, `]`, `\`, `^`, `_`.
@@ -27,7 +61,7 @@ Other advanced topics like configuration file will be described in the following
27
61
28
62
### File Location
29
63
30
-
The default name for a configuration file is `esp-idf-monitor.cfg`. First, the same directory `esp-idf-monitor` is being run if is inspected.
64
+
The default name for a configuration file is `esp-idf-monitor.cfg`. First, the same directory where `esp-idf-monitor` is being run is inspected.
31
65
32
66
If a configuration file is not found here, the current user's OS configuration directory is inspected next:
33
67
@@ -90,7 +124,7 @@ Example:
90
124
custom_reset_sequence = U0,1|W0.1|D1|R0|W0.5|D0
91
125
```
92
126
93
-
Refer to [custom reset sequence](https://docs.espressif.com/projects/esptool/en/latest/esptool/configuration-file.html#custom-reset-sequence) from Esptool documentation for further details. Please note that ``custom_reset_sequence`` is the only used value from the Esptool configuration, and others will be ignored in IDF Monitor.
127
+
Refer to [custom reset sequence](https://docs.espressif.com/projects/esptool/en/latest/esptool/configuration-file.html#custom-reset-sequence) from Esptool documentation for further details. Please note that `custom_reset_sequence` is the only used value from the Esptool configuration, and others will be ignored in IDF Monitor.
94
128
95
129
##### Share Configuration Across Tools
96
130
@@ -136,28 +170,28 @@ skip_menu_key = False
136
170
137
171
### Code Style & Static Analysis
138
172
139
-
Please follow these coding standards when writing code for ``esp-idf-monitor``:
173
+
Please follow these coding standards when writing code for `esp-idf-monitor`:
140
174
141
175
#### Pre-commit Checks
142
176
143
177
[pre-commit](https://pre-commit.com/) is a framework for managing pre-commit hooks. These hooks help to identify simple issues before committing code for review.
144
178
145
-
To use the tool, first install ``pre-commit``. Then enable the ``pre-commit`` and ``commit-msg`` git hooks:
179
+
To use the tool, first install `pre-commit`. Then enable the `pre-commit` and `commit-msg` git hooks:
146
180
147
181
```sh
148
182
python -m pip install pre-commit
149
183
pre-commit install -t pre-commit -t commit-msg
150
184
```
151
185
152
-
On the first commit ``pre-commit`` will install the hooks, subsequent checks will be significantly faster. If an error is found an appropriate error message will be displayed.
186
+
On the first commit `pre-commit` will install the hooks, subsequent checks will be significantly faster. If an error is found an appropriate error message will be displayed.
153
187
154
188
##### Codespell Check
155
189
156
190
This repository utilizes an automatic [spell checker](https://github.com/codespell-project/codespell) integrated into the pre-commit process. If any spelling issues are detected, the recommended corrections will be applied automatically to the file, ready for commit. In the event of false positives, you can adjust the configuration in the `pyproject.toml` file under the `[tool.codespell]` section. To exclude files from the spell check, utilize the `skip` keyword followed by comma-separated paths to the files (wildcards are supported). Additionally, to exclude specific words from the spell check, employ the `ignore-words-list` keyword followed by comma-separated words to be skipped.
157
191
158
192
#### Conventional Commits
159
193
160
-
``esp-idf-monitor`` complies with the [Conventional Commits standard](https://www.conventionalcommits.org/en/v1.0.0/#specification). Every commit message is checked with [Conventional Precommit Linter](https://github.com/espressif/conventional-precommit-linter), ensuring it adheres to the standard.
194
+
`esp-idf-monitor` complies with the [Conventional Commits standard](https://www.conventionalcommits.org/en/v1.0.0/#specification). Every commit message is checked with [Conventional Precommit Linter](https://github.com/espressif/conventional-precommit-linter), ensuring it adheres to the standard.
0 commit comments