Skip to content

Commit 818a730

Browse files
SergioGasquezJurajSadel
SergioGasquez
and
JurajSadel
authored
Add serial ports config file (#777)
* feat: Add serial ports config file * fix: Remove unused comment Co-authored-by: Juraj Sadel <jurajsadel@gmail.com> * docs: Update readme instructions * docs: Update changelog * docs: Fix typo Co-authored-by: Juraj Sadel <jurajsadel@gmail.com> * feat: Use a single config struct * feat: Simplify find_config_path methods * docs: Update config documentation * fix: Use a single config struct in cargo-espflash * feat: Simplify save_with method * docs: Improve docstrings * fix: Clippy lint * docs: Add a note about why there are 2 config files --------- Co-authored-by: Juraj Sadel <jurajsadel@gmail.com>
1 parent 628947d commit 818a730

File tree

8 files changed

+197
-119
lines changed

8 files changed

+197
-119
lines changed

‎CHANGELOG.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
2727
- Run some arguments checks for monitoring flags. (#842)
2828
- Add support for the ESP32-C5 (#863)
2929
- `--after` options now work with `espflash board-info`, `espflash read-flash` and `espflash checksum-md5` (#867)
30+
- Add support for serial port configuration files. (#777)
3031

3132
### Changed
3233

‎cargo-espflash/README.md

Lines changed: 49 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,10 @@ Supports the **ESP32**, **ESP32-C2/C3/C5/C6**, **ESP32-H2**, **ESP32-P4**, and *
1717
- [Permissions on Linux](#permissions-on-linux)
1818
- [Windows Subsystem for Linux](#windows-subsystem-for-linux)
1919
- [Bootloader and Partition Table](#bootloader-and-partition-table)
20-
- [Configuration File](#configuration-file)
20+
- [Configuration Files](#configuration-files)
21+
- [`espflash_ports.toml`](#espflash_portstoml)
22+
- [`espflash.toml`](#espflashtoml)
23+
- [Configuration Files Location](#configuration-files-location)
2124
- [Configuration Precedence](#configuration-precedence)
2225
- [Logging Format](#logging-format)
2326
- [Development Kit Support Policy](#development-kit-support-policy)
@@ -111,49 +114,61 @@ If the `--bootloader` and/or `--partition-table` options are provided then these
111114

112115
[esp-idf-sys]: https://github.com/esp-rs/esp-idf-sys
113116

114-
## Configuration File
115-
116-
The configuration file allows you to define various parameters for your application:
117-
118-
- Serial port:
119-
- By name:
120-
```toml
121-
[connection]
122-
serial = "/dev/ttyUSB0"
123-
```
124-
- By USB VID/PID values:
125-
```toml
126-
[[usb_device]]
127-
vid = "303a"
128-
pid = "1001"
129-
```
130-
- Baudrate:
117+
## Configuration Files
118+
119+
There are two configuration files allowing you to define various parameters for your application:
120+
121+
- `espflash.toml`: Project configuration
122+
- `espflash_ports.toml`: Port configuration
123+
124+
The reason to split configuration into two different files is to allow Git ignoring the Serial Port configuration, which is specific to the user (see [#727](https://github.com/esp-rs/espflash/issues/727)).
125+
126+
### `espflash_ports.toml`
127+
128+
This file allows you to define the serial port connection parameters:
129+
- By name:
131130
```toml
132-
baudrate = 460800
131+
[connection]
132+
serial = "/dev/ttyUSB0"
133133
```
134-
- Bootloader:
134+
- By USB VID/PID values:
135135
```toml
136-
bootloader = "path/to/custom/bootloader.bin"
136+
[[usb_device]]
137+
vid = "303a"
138+
pid = "1001"
137139
```
140+
141+
### `espflash.toml`
142+
143+
This file allows you to define different flash parameters:
144+
- Baudrate:
145+
```toml
146+
baudrate = 460800
147+
```
148+
- Bootloader:
149+
```toml
150+
bootloader = "path/to/custom/bootloader.bin"
151+
```
138152
- Partition table
139-
```toml
140-
partition_table = "path/to/custom/partition-table.bin"
141-
```
153+
```toml
154+
partition_table = "path/to/custom/partition-table.bin"
155+
```
142156
- Flash settings
143-
```toml
144-
[flash]
145-
mode = "qio"
146-
size = "8MB"
147-
frequency = "80MHz"
148-
```
157+
```toml
158+
[flash]
159+
mode = "qio"
160+
size = "8MB"
161+
frequency = "80MHz"
162+
```
149163

150-
You can have a local and/or a global configuration file:
164+
### Configuration Files Location
165+
You can have a local and/or a global configuration file(s):
151166

152167
- For local configurations, store the file under the current working directory or in the parent directory (to support Cargo workspaces) with the name `espflash.toml`
153168
- Global file location differs based on your operating system:
154-
- Linux: `$HOME/.config/espflash/espflash.toml`
155-
- macOS: `$HOME/Library/Application Support/rs.esp.espflash/espflash.toml`
156-
- Windows: `%APPDATA%\esp\espflash\espflash.toml`
169+
- Linux: `$HOME/.config/espflash/espflash.toml` or `$HOME/.config/espflash/espflash_ports.toml`
170+
- macOS: `$HOME/Library/Application Support/rs.esp.espflash/espflash.toml` or `$HOME/Library/Application Support/rs.esp.espflash/espflash_ports.toml`
171+
- Windows: `%APPDATA%\esp\espflash\espflash.toml` or `%APPDATA%\esp\espflash\espflash_ports.toml`
157172

158173
### Configuration Precedence
159174

‎cargo-espflash/src/main.rs

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -242,7 +242,7 @@ fn main() -> Result<()> {
242242
Commands::EraseRegion(args) => erase_region(args, &config),
243243
Commands::Flash(args) => flash(args, &config),
244244
Commands::HoldInReset(args) => hold_in_reset(args, &config),
245-
Commands::ListPorts(args) => list_ports(&args, &config),
245+
Commands::ListPorts(args) => list_ports(&args, &config.port_config),
246246
Commands::Monitor(args) => serial_monitor(args, &config),
247247
Commands::PartitionTable(args) => partition_table(args),
248248
Commands::ReadFlash(args) => read_flash(args, &config),
@@ -267,7 +267,7 @@ pub fn erase_parts(args: ErasePartsArgs, config: &Config) -> Result<()> {
267267
let partition_table = args
268268
.partition_table
269269
.as_deref()
270-
.or(config.partition_table.as_deref());
270+
.or(config.project_config.partition_table.as_deref());
271271

272272
let mut flasher = connect(&args.connect_args, config, false, false)?;
273273
let chip = flasher.chip();
@@ -302,7 +302,7 @@ fn flash(args: FlashArgs, config: &Config) -> Result<()> {
302302
// we'll override the detected (or default) value with this.
303303
if let Some(flash_size) = args.build_args.flash_config_args.flash_size {
304304
flasher.set_flash_size(flash_size);
305-
} else if let Some(flash_size) = config.flash.size {
305+
} else if let Some(flash_size) = config.project_config.flash.size {
306306
flasher.set_flash_size(flash_size);
307307
}
308308

@@ -329,7 +329,7 @@ fn flash(args: FlashArgs, config: &Config) -> Result<()> {
329329
let mut flash_config = args.build_args.flash_config_args;
330330
flash_config.flash_size = flash_config
331331
.flash_size // Use CLI argument if provided
332-
.or(config.flash.size) // If no CLI argument, try the config file
332+
.or(config.project_config.flash.size) // If no CLI argument, try the config file
333333
.or_else(|| flasher.flash_detect().ok().flatten()) // Try detecting flash size next
334334
.or_else(|| Some(FlashSize::default())); // Otherwise, use a reasonable default value
335335

@@ -576,7 +576,7 @@ fn save_image(args: SaveImageArgs, config: &Config) -> Result<()> {
576576
let mut flash_config = args.build_args.flash_config_args;
577577
flash_config.flash_size = flash_config
578578
.flash_size // Use CLI argument if provided
579-
.or(config.flash.size) // If no CLI argument, try the config file
579+
.or(config.project_config.flash.size) // If no CLI argument, try the config file
580580
.or_else(|| Some(FlashSize::default())); // Otherwise, use a reasonable default value
581581

582582
let flash_data = make_flash_data(

‎espflash/README.md

Lines changed: 49 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,10 @@ Supports the **ESP32**, **ESP32-C2/C3/C5/C6**, **ESP32-H2**, **ESP32-P4**, and *
1919
- [Windows Subsystem for Linux](#windows-subsystem-for-linux)
2020
- [Cargo Runner](#cargo-runner)
2121
- [Using `espflash` as a Library](#using-espflash-as-a-library)
22-
- [Configuration File](#configuration-file)
22+
- [Configuration Files](#configuration-files)
23+
- [`espflash_ports.toml`](#espflash_portstoml)
24+
- [`espflash.toml`](#espflashtoml)
25+
- [Configuration Files Location](#configuration-files-location)
2326
- [Configuration Precedence](#configuration-precedence)
2427
- [Logging Format](#logging-format)
2528
- [Development Kit Support Policy](#development-kit-support-policy)
@@ -131,49 +134,61 @@ or `cargo add espflash --no-default-features`
131134
132135
We disable the `default-features` to opt-out the `cli` feature, which is enabled by default; you likely will not need any of these types or functions in your application so there’s no use pulling in the extra dependencies.
133136

134-
## Configuration File
135-
136-
The configuration file allows you to define various parameters for your application:
137-
138-
- Serial port:
139-
- By name:
140-
```toml
141-
[connection]
142-
serial = "/dev/ttyUSB0"
143-
```
144-
- By USB VID/PID values:
145-
```toml
146-
[[usb_device]]
147-
vid = "303a"
148-
pid = "1001"
149-
```
150-
- Baudrate:
137+
## Configuration Files
138+
139+
There are two configuration files allowing you to define various parameters for your application:
140+
141+
- `espflash.toml`: Project configuration
142+
- `espflash_ports.toml`: Port configuration
143+
144+
The reason to split configuration into two different files is to allow Git ignoring the Serial Port configuration, which is specific to the user (see [#727](https://github.com/esp-rs/espflash/issues/727)).
145+
146+
### `espflash_ports.toml`
147+
148+
This file allows you to define the serial port connection parameters:
149+
- By name:
151150
```toml
152-
baudrate = 460800
151+
[connection]
152+
serial = "/dev/ttyUSB0"
153153
```
154-
- Bootloader:
154+
- By USB VID/PID values:
155155
```toml
156-
bootloader = "path/to/custom/bootloader.bin"
156+
[[usb_device]]
157+
vid = "303a"
158+
pid = "1001"
157159
```
160+
161+
### `espflash.toml`
162+
163+
This file allows you to define different flash parameters:
164+
- Baudrate:
165+
```toml
166+
baudrate = 460800
167+
```
168+
- Bootloader:
169+
```toml
170+
bootloader = "path/to/custom/bootloader.bin"
171+
```
158172
- Partition table
159-
```toml
160-
partition_table = "path/to/custom/partition-table.bin"
161-
```
173+
```toml
174+
partition_table = "path/to/custom/partition-table.bin"
175+
```
162176
- Flash settings
163-
```toml
164-
[flash]
165-
mode = "qio"
166-
size = "8MB"
167-
frequency = "80MHz"
168-
```
177+
```toml
178+
[flash]
179+
mode = "qio"
180+
size = "8MB"
181+
frequency = "80MHz"
182+
```
169183

170-
You can have a local and/or a global configuration file:
184+
### Configuration Files Location
185+
You can have a local and/or a global configuration file(s):
171186

172187
- For local configurations, store the file under the current working directory or in the parent directory (to support Cargo workspaces) with the name `espflash.toml`
173188
- Global file location differs based on your operating system:
174-
- Linux: `$HOME/.config/espflash/espflash.toml`
175-
- macOS: `$HOME/Library/Application Support/rs.esp.espflash/espflash.toml`
176-
- Windows: `%APPDATA%\esp\espflash\espflash.toml`
189+
- Linux: `$HOME/.config/espflash/espflash.toml` or `$HOME/.config/espflash/espflash_ports.toml`
190+
- macOS: `$HOME/Library/Application Support/rs.esp.espflash/espflash.toml` or `$HOME/Library/Application Support/rs.esp.espflash/espflash_ports.toml`
191+
- Windows: `%APPDATA%\esp\espflash\espflash.toml` or `%APPDATA%\esp\espflash\espflash_ports.toml`
177192

178193
### Configuration Precedence
179194

‎espflash/src/bin/espflash.rs

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -173,7 +173,7 @@ fn main() -> Result<()> {
173173
Commands::EraseRegion(args) => erase_region(args, &config),
174174
Commands::Flash(args) => flash(args, &config),
175175
Commands::HoldInReset(args) => hold_in_reset(args, &config),
176-
Commands::ListPorts(args) => list_ports(&args, &config),
176+
Commands::ListPorts(args) => list_ports(&args, &config.port_config),
177177
Commands::Monitor(args) => serial_monitor(args, &config),
178178
Commands::PartitionTable(args) => partition_table(args),
179179
Commands::ReadFlash(args) => read_flash(args, &config),
@@ -224,7 +224,7 @@ fn flash(args: FlashArgs, config: &Config) -> Result<()> {
224224
// override the detected (or default) value with this.
225225
if let Some(flash_size) = args.flash_config_args.flash_size {
226226
flasher.set_flash_size(flash_size);
227-
} else if let Some(flash_size) = config.flash.size {
227+
} else if let Some(flash_size) = config.project_config.flash.size {
228228
flasher.set_flash_size(flash_size);
229229
}
230230

@@ -241,7 +241,7 @@ fn flash(args: FlashArgs, config: &Config) -> Result<()> {
241241
let mut flash_config = args.flash_config_args;
242242
flash_config.flash_size = flash_config
243243
.flash_size // Use CLI argument if provided
244-
.or(config.flash.size) // If no CLI argument, try the config file
244+
.or(config.project_config.flash.size) // If no CLI argument, try the config file
245245
.or_else(|| flasher.flash_detect().ok().flatten()) // Try detecting flash size next
246246
.or_else(|| Some(FlashSize::default())); // Otherwise, use a reasonable default value
247247

@@ -296,7 +296,7 @@ fn save_image(args: SaveImageArgs, config: &Config) -> Result<()> {
296296
let mut flash_config = args.flash_config_args;
297297
flash_config.flash_size = flash_config
298298
.flash_size // Use CLI argument if provided
299-
.or(config.flash.size) // If no CLI argument, try the config file
299+
.or(config.project_config.flash.size) // If no CLI argument, try the config file
300300
.or_else(|| Some(FlashSize::default())); // Otherwise, use a reasonable default value
301301

302302
let flash_data = make_flash_data(

0 commit comments

Comments
 (0)