Add commands reset and hold-in-reset (#644)

* Add commands `reset` and `hold-in-reset`

* Fix connect call to adopt new args.

* Add changelog entry

* Add `hold-in-reset` and `reset` commands to `cargo-espflash` as well.

* Update usage blocks in READMEs.

Author: Joseph Ross

CHANGELOG.md

@@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+- Add `hold-in-reset` and `reset` subcommands
+
 ## [3.1.0] - 2024-05-24
 
 ### Added

cargo-espflash/README.md

@@ -73,9 +73,11 @@ Commands:
   erase-parts      Erase specified partitions
   erase-region     Erase specified region
   flash            Flash an application in ELF format to a target device
+  hold-in-reset    Hold the target device in reset
   monitor          Open the serial monitor without flashing the connected target device
   partition-table  Convert partition tables between CSV and binary format
   read-flash       Read SPI flash content
+  reset            Reset the target device
   save-image       Generate a binary application image and save it to a local disk
   checksum-md5     Calculate the MD5 checksum of the given region
   help             Print this message or the help of the given subcommand(s)

cargo-espflash/src/main.rs

@@ -86,6 +86,8 @@ enum Commands {
     ///
     /// https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/app_image_format.html
     Flash(FlashArgs),
+    /// Hold the target device in reset
+    HoldInReset(ConnectArgs),
     /// Open the serial monitor without flashing the connected target device
     Monitor(MonitorArgs),
     /// Convert partition tables between CSV and binary format
@@ -101,6 +103,8 @@ enum Commands {
     PartitionTable(PartitionTableArgs),
     /// Read SPI flash content
     ReadFlash(ReadFlashArgs),
+    /// Reset the target device
+    Reset(ConnectArgs),
     /// Generate a binary application image and save it to a local disk
     ///
     /// If the '--merge' option is used, then the bootloader, partition table,
@@ -216,9 +220,11 @@ fn main() -> Result<()> {
         Commands::EraseParts(args) => erase_parts(args, &config),
         Commands::EraseRegion(args) => erase_region(args, &config),
         Commands::Flash(args) => flash(args, &config),
+        Commands::HoldInReset(args) => hold_in_reset(args, &config),
         Commands::Monitor(args) => serial_monitor(args, &config),
         Commands::PartitionTable(args) => partition_table(args),
         Commands::ReadFlash(args) => read_flash(args, &config),
+        Commands::Reset(args) => reset(args, &config),
         Commands::SaveImage(args) => save_image(args, &config),
         Commands::ChecksumMd5(args) => checksum_md5(&args, &config),
     }
@@ -257,6 +263,23 @@ pub fn erase_parts(args: ErasePartsArgs, config: &Config) -> Result<()> {
     Ok(())
 }
 
+fn reset(args: ConnectArgs, config: &Config) -> Result<()> {
+    let mut args = args.clone();
+    args.no_stub = true;
+    let mut flash = connect(&args, config, true, true)?;
+    info!("Resetting target device");
+    flash.connection().reset()?;
+
+    Ok(())
+}
+
+fn hold_in_reset(args: ConnectArgs, config: &Config) -> Result<()> {
+    connect(&args, config, true, true)?;
+    info!("Holding target device in reset");
+
+    Ok(())
+}
+
 fn flash(args: FlashArgs, config: &Config) -> Result<()> {
     let metadata = PackageMetadata::load(&args.build_args.package)?;
     let cargo_config = CargoConfig::load(&metadata.workspace_root, &metadata.package_root);

espflash/README.md

@@ -68,9 +68,11 @@ Commands:
   erase-parts      Erase specified partitions
   erase-region     Erase specified region
   flash            Flash an application in ELF format to a connected target device
+  hold-in-reset    Hold the target device in reset
   monitor          Open the serial monitor without flashing the connected target device
   partition-table  Convert partition tables between CSV and binary format
   read-flash       Read SPI flash content
+  reset            Reset the target device
   save-image       Generate a binary application image and save it to a local disk
   write-bin        Write a binary file to a specific address in a target device's flash
   checksum-md5     Calculate the MD5 checksum of the given region

espflash/src/bin/espflash.rs

@@ -62,6 +62,8 @@ enum Commands {
     ///
     /// https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/app_image_format.html
     Flash(FlashArgs),
+    /// Hold the target device in reset
+    HoldInReset(ConnectArgs),
     /// Open the serial monitor without flashing the connected target device
     Monitor(MonitorArgs),
     /// Convert partition tables between CSV and binary format
@@ -77,6 +79,8 @@ enum Commands {
     PartitionTable(PartitionTableArgs),
     /// Read SPI flash content
     ReadFlash(ReadFlashArgs),
+    /// Reset the target device
+    Reset(ConnectArgs),
     /// Generate a binary application image and save it to a local disk
     ///
     /// If the '--merge' option is used, then the bootloader, partition table,
@@ -174,9 +178,11 @@ fn main() -> Result<()> {
         Commands::EraseParts(args) => erase_parts(args, &config),
         Commands::EraseRegion(args) => erase_region(args, &config),
         Commands::Flash(args) => flash(args, &config),
+        Commands::HoldInReset(args) => hold_in_reset(args, &config),
         Commands::Monitor(args) => serial_monitor(args, &config),
         Commands::PartitionTable(args) => partition_table(args),
         Commands::ReadFlash(args) => read_flash(args, &config),
+        Commands::Reset(args) => reset(args, &config),
         Commands::SaveImage(args) => save_image(args, &config),
         Commands::WriteBin(args) => write_bin(args, &config),
         Commands::ChecksumMd5(args) => checksum_md5(&args, &config),
@@ -206,6 +212,23 @@ pub fn erase_parts(args: ErasePartsArgs, config: &Config) -> Result<()> {
     Ok(())
 }
 
+fn reset(args: ConnectArgs, config: &Config) -> Result<()> {
+    let mut args = args.clone();
+    args.no_stub = true;
+    let mut flash = connect(&args, config, true, true)?;
+    info!("Resetting target device");
+    flash.connection().reset()?;
+
+    Ok(())
+}
+
+fn hold_in_reset(args: ConnectArgs, config: &Config) -> Result<()> {
+    connect(&args, config, true, true)?;
+    info!("Holding target device in reset");
+
+    Ok(())
+}
+
 fn flash(args: FlashArgs, config: &Config) -> Result<()> {
     let mut flasher = connect(
         &args.connect_args,

espflash/src/cli/mod.rs

@@ -49,7 +49,7 @@ pub mod monitor;
 mod serial;
 
 /// Establish a connection with a target device
-#[derive(Debug, Args)]
+#[derive(Debug, Args, Clone)]
 #[non_exhaustive]
 pub struct ConnectArgs {
     /// Reset operation to perform after connecting to the target