Investigate espflash library usage

[MabezDev]

We don't have much from crates.io rev deps, but what we can, and should do is do a code search on Github/Gitlab to find library usage. From here, we can find what needs to be exposed in the library and what doesn't. It's also not that black and white, a module may be used because our other APIs are insufficient, or are tangled together forcing users to use both modules so keep that in mind.

[jessebraham]

A few projects which appears to be using espflash directly as a library:

• https://github.com/probe-rs/probe-rs/
• https://github.com/yanshay/esp-hal-app
• https://github.com/EyeTrackVR/FirmwareFlashingTool
• https://github.com/ivmarkov/espfactory
• https://github.com/3STechLabs-org/ESP32-Flasher
• https://github.com/QTShock/QTHub

This is not comprehensive, but investigating how these projects are using the library should at least give us a reasonable idea of how people are currently using espflash.

[nullstalgia]

I'm currently working on a binary crate (serial-terminal adjacent, still an early WIP) that intends to use espflash as a library! (I had just started to sniff through issues here to get a clearer picture on what I might need to look out for, and ran into this issue near the top. 😄)

But so far, something I've really appreciated is the ability to create helpers like Connections and Flashers, and then be able to consume them and get back the Port object for my terminal to use again without reconnecting! The ResetStrategy's request for a &mut Port also makes this easy, and is also appreciated.

If you have more questions about how I intend to use it as a library, or would like feedback as I get deeper into the project, I'd be happy to oblige!

[i404788]

Also wanted to chime in and say I'm planning to use parts of espflash currently not yet exposed (mainly the Command struct) for an in-circuit esp programmer (which can't use serialport cause no_std & no usb). It's still early days & probably won't be fully fleshed out until a few months, but if anything of note comes up I'll post an update. Also happy to answer questions or contribute if needed.

[nullstalgia]

Howdy, been a second but I'm finally at the stage in my application where I'm able to focus on the fancier things like espflash integration.

And while I was starting to set up pipework for events and errors, I noticed something not-so-ideal for my use-case.

Errors during espflash::Flasher connection/construction will drop the entire serialport::Port object, rather than returning it back to the caller.

"Why are you using the Flasher?"

To take control of the serial port and reset the ESP into it's bootloader on-demand with a button.

I do also later intend to allow flashing binaries through my UI, for which I will need the Flasher.

"Why are you using the Flasher instead of the Connection for that?"

Since the Flasher construction also gets the chip type and has the device_info method.

But, I do also use the Connection to reset the ESP back into flashed code with another button.

---

I have already worked around my app's structs needing to "lend out" ownership of the serialport::Port, but I'm wondering if a &mut Port parameter would make more sense? Or allow construction of Flasher separate from initial communication attempts like Connection?

Instead storing a &mut Port in the Connection might be possible to avoid dropping the Port unnecessarily, but I also don't know how incompatible that is with the current internal flow.

Regardless of how you wish to tackle it, I'm excited to see and give feedback! 💖

[nullstalgia]

If I had to make a small wishlist based on my experience thus far (semi-relating to #854):

The reset module's visibility is now crate-only, so I can't make any Flashers myself now due to the Before/After actions, I don't think?

As for the experience of flashing files:

I also can't use any of the FlashTarget trait methods myself, since Flashers method + field for SPI info are private.

I would appreciate valid and skip params on if Flasher::write_bins_to_flash used the struct's existing skip/verify bools. (I made a quick fork with that change based on v3.3.0 so I can still have CI test my app commits and have reset module access)

The current usage of ProgressCallbacks doesn't get called for skipped files, so if I want to show filename with currently flashing file, I have to guess which is the current file based on size (since sequential calls to Flasher::write_bin_to_flash, the single-segment variant, will call Connection::reset_after each time).

In addition, there's no callbacks for when verifying a file, which would be nice to have shown on a UI.

---

I'd be okay having a more manual implementation so I can place callbacks and such where I please, but the aforementioned SPI visibility makes that presently not possible (as far as I can tell).

Would be happy to help come up with something meant to sit in the main crate though!

---

Video of the app I am working on and integrating espflash into:

2025-05-16--20-10-12-WindowsTerminal.mp4

[MabezDev]

Hi @nullstalgia, @i404788,

Thanks for the feedback! We've been making some changes through out, and I think with #901 most of your comments should be addressed. If you could try that branch (or main once it's merged) that would be really great. I hope we've covered everything for your usecases.

@nullstalgia I have a couple of follow up questions, if you don't mind:

The current usage of ProgressCallbacks doesn't get called for skipped files, so if I want to show filename with currently flashing file, I have to guess which is the current file based on size (since sequential calls to Flasher::write_bin_to_flash, the single-segment variant, will call Connection::reset_after each time).

Can you explain what you'd expect? If there is nothing to do, I'm not sure we can report progress on it.

In addition, there's no callbacks for when verifying a file, which would be nice to have shown on a UI.

Verify is actually a one-shot command, so, I'm not sure it makes sense here. It either verifies successfully or not.

[nullstalgia]

Will do soon! Hopefully before it's merged.

I have a couple of follow up questions, if you don't mind:

Sure!

The current usage of ProgressCallbacks doesn't get called for skipped files...

Can you explain what you'd expect? If there is nothing to do, I'm not sure we can report progress on it.

My desire comes from wanting to emulate the feedback seen from espflash during CLI usage.

As you can see, it notes to the user the partition was skipped since the checksums matched. However if I wish to tell my users that, I can't, since the self.skip check is all before ProgressCallbacks::init() is ever called.

Verify is actually a one-shot command, so, I'm not sure it makes sense here.

And my intent for verification is similar, just wanting to show the user what's happening behind the scenes.

For example, here's an upload with verification on:

Screencast_20250624_201917.webm

And one with verification off:

Screencast_20250624_201729.webm

To the user, the one with verification on just sits at 100% for a moment longer with no indication why. I could just assume verification has started once it hits 100% progress, but that felt sloppy 😛 .

I think things might be a little more clear if I show my implementation of ProgressCallbacks:

impl ProgressCallbacks for ProgressPropagator {
    fn init(&mut self, addr: u32, total: usize) {
        _ = self.tx.send(
            FlashProgress::Init {
                chip: self.chip.clone(),
                addr,
                size: total,
                // name: self.filenames[self.current_index as usize].to_compact_string(),
            }
            .into(),
        );
       // self.current_index += 1;
    }
    fn update(&mut self, current: usize) {
        _ = self.tx.send(FlashProgress::Progress(current).into());
    }
    fn finish(&mut self) {
        _ = self.tx.send(FlashProgress::SegmentFinished.into());
    }
}

I'm just trying to get the exact state of whats happening so I can properly display it to my users. 😅

I'll reply soon with my thoughts on the PR! Thanks again for taking my feedback into consideration! 💖