Add commands for firmware upgrade & control IAP mode by 21km43 · Pull Request #84 · ch32-rs/wlink

21km43 · 2025-01-17T10:12:17Z

I read this issue and implemented commands which controls IAP mode.

Commands:
  iap          Enter or quit IAP mode
  upgrade      Upgrade WCH-Link/E firmware

Example (Controling iap mode):

> wlink iap
[WARN] This is an experimental feature, better use the WCH-LinkUtility!
Please choose one mode to switch, either --enter or --quit

> wlink iap --enter
<WCH-Link#0 libusb device> Bus 001 Device 031 ID 1a86:8010(USB-FS 12 Mbps) (RV mode)
[WARN] This is an experimental feature, better use the WCH-LinkUtility!
[INFO] Enter IAP mode

> wlink iap --quit
<WCH-Link#0 libusb device> Bus 001 Device 026 ID 4348:55e0(USB-FS 12 Mbps) (IAP mode)
[WARN] This is an experimental feature, better use the WCH-LinkUtility!
[INFO] Quit IAP mode

> wlink mode-switch --dap
<WCH-Link#0 libusb device> Bus 001 Device 033 ID 1a86:8010(USB-FS 12 Mbps) (RV mode)
[WARN] This is an experimental feature, better use the WCH-LinkUtility!
[INFO] Connected to WCH-Link v2.14(v34) (WCH-LinkE-CH32V305)
[INFO] Switch mode for WCH-LinkRV

> wlink iap --enter
<WCH-Link#0 libusb device> Bus 001 Device 028 ID 1a86:8012(USB-FS 12 Mbps) (DAP mode)
[WARN] This is an experimental feature, better use the WCH-LinkUtility!
[INFO] Enter IAP mode

> wlink iap --quit
<WCH-Link#0 libusb device> Bus 001 Device 026 ID 4348:55e0(USB-FS 12 Mbps) (IAP mode)
[WARN] This is an experimental feature, better use the WCH-LinkUtility!
[INFO] Quit IAP mode

Example (Upgrade firmware)

> wlink upgrade FIRMWARE_CH32V305.bin
<WCH-Link#0 WCHLinkDLL device> CH375Driver Device 1a86:8010 (RV mode)
<WCH-Link#0 libusb device> Bus 001 Device 057 ID 1a86:8010(USB-FS 12 Mbps) (RV mode)
[WARN] This is an experimental feature, better use the WCH-LinkUtility!
[INFO] Read FIRMWARE_CH32V305.bin as Binary format
[INFO] Enter IAP mode
[INFO] Start firmware upgrade
[INFO] ######################################
[INFO] DO NOT UNPLUG WCH-Link/E until done!!!
[INFO] ######################################
[INFO] Erase flash
[INFO] Flashing 94912 bytes
[INFO] Flash done
[INFO] Verifying
[INFO] Verify OK
[INFO] Firmware upgrade completed successfully
[INFO] Quit IAP mode

# If the device is already IAP mode, skip entering IAP mode and start upgrade
> wlink upgrade FIRMWARE_CH32V305.bin
<WCH-Link#0 WCHLinkDLL device> CH375Driver Device 1a86:8010 (RV mode)
<WCH-Link#0 libusb device> Bus 001 Device 057 ID 1a86:8010(USB-FS 12 Mbps) (RV mode)
[WARN] This is an experimental feature, better use the WCH-LinkUtility!
[INFO] Read FIRMWARE_CH32V305.bin as Binary format
[INFO] Device is already in IAP mode
[INFO] Start firmware upgrade
[INFO] ######################################
[INFO] DO NOT UNPLUG WCH-Link/E until done!!!
[INFO] ######################################
[INFO] Erase flash
[INFO] Flashing 94912 bytes
[INFO] Flash done
[INFO] Verifying
[INFO] Verify OK
[INFO] Firmware upgrade completed successfully
[INFO] Quit IAP mode

andelf · 2025-12-08T03:38:28Z

It would be great to add firmware upgrade support.
Are you planning to implement this?

21km43 · 2025-12-08T03:52:36Z

It would be great to add firmware upgrade support. Are you planning to implement this?

Yes. I'll implement firmware upgrade option later.

Should I integrate IAP control function and firmware upgrade function?

andelf · 2025-12-08T04:23:26Z

Should I integrate IAP control function and firmware upgrade function?

Yes, please integrate them together.

Switching IAP mode separately would leave wch-link in an intermediate state,
which isn't ideal. The official PC software treats "IAP switch + firmware upgrade"
as a single operation, so we should follow that pattern for consistency and reliability.

* initial checkout * implement iap_flash_firmware * fix fileend copy * fix read endpoint * fix loginfo * fix sleep time * add log detail info * Remove redundant notation * fix write verify commands to enum * add readme * add warning

…ices (#6) * Initial plan * Refactor library selection to support dynamic DLL loading for IAP and normal modes Co-authored-by: 21km43 <48169975+21km43@users.noreply.github.com> * Don't refresh device_index * Remove dll fallback --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: 21km43 <48169975+21km43@users.noreply.github.com> Co-authored-by: Koki Mizumoto <21km43@gmail.com>

Removed unreleased changes for IAP mode switch and WCH-LinkE firmware upgrade.

Copilot

Pull request overview

This pull request adds experimental firmware upgrade capabilities and IAP (In-Application Programming) mode control for WCH-Link/E devices. The implementation draws from community references and adds two new CLI commands: iap for entering/exiting IAP mode, and upgrade for flashing WCH-Link firmware.

Changes:

Added IAP mode control commands (enter/quit) and firmware upgrade functionality
Enhanced CH375 driver support to handle both WCHLinkDLL.dll and CH375DLL.dll for IAP mode devices on Windows
Added new USB constants and endpoints for IAP mode device communication

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
src/main.rs	Added CLI commands for IAP mode switching and firmware upgrade with appropriate warnings
src/probe.rs	Implemented IAP mode functions (enter, quit, erase, flash) with USB communication logic
src/usb_device.rs	Enhanced CH375 driver to support dual DLL loading and IAP mode device handling
src/commands/mod.rs	Added IapProgram enum for write/verify operations and updated command documentation
README.md	Updated feature list to include IAP mode switching and firmware upgrade capabilities

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-18T09:20:40Z

+            txbuf.fill(0);
+
+            // First 4 bytes: cmd, size, addr low, addr high
+            txbuf[0] = cmd;


The copy_size is cast to u8 which limits it to a maximum value of 255. However, the code initializes copy_size to 60 and only reduces it when near the end of the data. If the protocol is ever changed to support larger chunk sizes, this cast could silently truncate the value. While not currently a bug, consider adding an assertion or debug check to ensure copy_size never exceeds 255.

Suggested change

txbuf[0] = cmd;

txbuf[0] = cmd;

debug_assert!(

copy_size <= u8::MAX as usize,

"copy_size ({}) exceeds u8::MAX ({})",

copy_size,

u8::MAX

);

Copilot · 2026-01-18T09:20:41Z

        Ok(())
    }

+    /// Switch IAP mode


The comment says "Switch IAP mode" but the function name is "iap_enter". The comment should be more specific, such as "Enter IAP mode" to match the function's purpose.

Suggested change

/// Switch IAP mode

/// Enter IAP mode

Copilot · 2026-01-18T09:20:41Z

+    /// Switch IAP mode
+    // ref: https://github.com/cjacker/wlink-iap/blob/main/src/main.c
+    pub fn iap_enter(nth: usize) -> Result<()> {
+


There's an unnecessary blank line at the start of the function body. Remove it for consistency with the codebase style.

Suggested change

Copilot · 2026-01-18T09:20:41Z

+        log::info!("Quit IAP mode");
+        let buf = [0x83, 0x02, 0x00, 0x00];
+        log::trace!("send {} {}", hex::encode(&buf[..3]), hex::encode(&buf[3..]));
+        let _ = dev.write_endpoint(ENDPOINT_OUT_IAP, &buf);


The write_endpoint result is being ignored when sending the IAP quit command. If the write fails, the function will return Ok despite the mode switch command not being sent, potentially leaving the device in IAP mode. Consider propagating the error instead of silently ignoring it.

Suggested change

let _ = dev.write_endpoint(ENDPOINT_OUT_IAP, &buf);

dev.write_endpoint(ENDPOINT_OUT_IAP, &buf)?;

Copilot · 2026-01-18T09:20:42Z

+        } else {
+            return Err(Error::ProbeNotFound);
+        };
+


There's trailing whitespace at the end of this line. Remove it for consistency with the codebase style.

Suggested change

Copilot · 2026-01-18T09:20:43Z

+                    WchLink::iap_quit(device_index)?;
+                }
+                Firmware::Sections(_sections) => {
+                    log::error!("HEX firmware format not supported for WCH-Link upgrade");


When the firmware format is HEX (Sections), the function only logs an error but doesn't return an error. This means the upgrade process will continue silently and quit IAP mode without actually upgrading the firmware, potentially leaving the device in an inconsistent state. The function should return an error to prevent the code from continuing to line 282 (quit IAP mode).

Suggested change

log::error!("HEX firmware format not supported for WCH-Link upgrade");

log::error!("HEX firmware format not supported for WCH-Link upgrade");

return Err(

wlink::Error::Custom(

"HEX firmware format not supported for WCH-Link upgrade".into(),

)

.into(),

);

Copilot · 2026-01-18T09:20:43Z

+                .copy_from_slice(&data[offset..offset + copy_size]);
+
+            // Write or verify binary
+            let _ = dev.write_endpoint(ENDPOINT_OUT_IAP, &txbuf[0..4 + copy_size]);


The write_endpoint result is being ignored, which could hide critical errors during the IAP flash/verify operation. Since the subsequent read_endpoint is expected to return a response confirming the write was successful, a failure to write could lead to misleading error messages. The write_endpoint call should propagate errors.

Suggested change

let _ = dev.write_endpoint(ENDPOINT_OUT_IAP, &txbuf[0..4 + copy_size]);

dev.write_endpoint(ENDPOINT_OUT_IAP, &txbuf[0..4 + copy_size])?;

Copilot · 2026-01-18T09:20:44Z

+            log::info!("Enter IAP mode");
+            let buf = [0x81, 0x0f, 0x01, 0x01];
+            log::trace!("send {} {}", hex::encode(&buf[..3]), hex::encode(&buf[3..]));
+            let _ = dev.write_endpoint(endp_out, &buf);


The write_endpoint result is being ignored when sending the IAP enter command. If the write fails but the device is not already in IAP mode, the function will return Ok despite the mode switch command not being sent. Consider propagating the error instead of silently ignoring it.

Suggested change

let _ = dev.write_endpoint(endp_out, &buf);

if let Err(e) = dev.write_endpoint(endp_out, &buf) {

log::error!("Failed to send IAP enter command: {:?}", e);

return Err(e);

}

Copilot · 2026-01-18T09:20:44Z

+        log::info!("Erase flash");
+        let buf = [0x81, 0x02, 0x00, 0x00];
+        log::trace!("send {} {}", hex::encode(&buf[..3]), hex::encode(&buf[3..]));
+        let _ = dev.write_endpoint(ENDPOINT_OUT_IAP, &buf);


The write_endpoint result is being ignored when sending the IAP erase command. If the write fails, the function will return Ok despite the erase command not being sent, potentially causing issues in the firmware upgrade process that expects the flash to be erased. Consider propagating the error instead of silently ignoring it.

Copilot · 2026-01-18T09:20:44Z

+            // First 4 bytes: cmd, size, addr low, addr high
+            txbuf[0] = cmd;
+            txbuf[1] = copy_size as u8;
+            txbuf[2] = (offset & 0xFF) as u8;
+            txbuf[3] = ((offset >> 8) & 0xFF) as u8;


The offset is encoded as a 16-bit value (using only 2 bytes at positions 2 and 3), which limits the maximum addressable offset to 65535 bytes. However, the function accepts data of any length without validating this constraint. If data.len() exceeds 65535 bytes, the offset will silently overflow and wrap around, causing firmware to be written to incorrect addresses. Add validation to ensure data.len() does not exceed 65535 bytes, or use a larger address field if the protocol supports it.

andelf · 2026-01-18T09:31:42Z

Leave the rebase work to me. I'll resolve them later.

21km43 and others added 3 commits January 17, 2025 16:51

add functions to switch iap mode

c6e8085

typo fix

32065bc

Simplified RV and DAP determination

67529b9

21km43 mentioned this pull request Jan 17, 2025

Feature Request: Upgrade WCH-Link firmware #42

Open

21km43 added 4 commits January 17, 2025 21:37

function name fix

db77c46

ch375dll64 test

be0e8fd

test 2

beee4ba

rebase

9c17a2e

21km43 marked this pull request as draft January 19, 2025 08:30

Support IAP mode without Zadig (x86)

75d40ee

21km43 marked this pull request as ready for review January 19, 2025 09:15

21km43 added 2 commits December 8, 2025 10:27

Merge branch 'main' into iap

11e270e

unsafe

e394617

21km43 force-pushed the iap branch from 39dfab2 to e394617 Compare December 8, 2025 02:02

andelf self-requested a review December 8, 2025 03:35

21km43 marked this pull request as draft December 8, 2025 04:07

21km43 added 11 commits December 8, 2025 14:53

initial checkout

89e0ca7

Merge branch 'upgrade' of https://github.com/21km43/wlink into upgrade

e202d84

implement iap_flash_firmware

929a2ba

fix fileend copy

b1fea68

fix read endpoint

d7108c9

fix loginfo

f022c83

fix sleep time

058f134

add log detail info

c33d4b3

Remove redundant notation

53ee3cb

fix write verify commands to enum

958506a

add readme

3d8ebfa

21km43 and others added 4 commits December 8, 2025 16:31

add warning

2ba4e90

Upgrade (#4)

bf833b8

* initial checkout * implement iap_flash_firmware * fix fileend copy * fix read endpoint * fix loginfo * fix sleep time * add log detail info * Remove redundant notation * fix write verify commands to enum * add readme * add warning

fix

abac3e8

Merge branch 'upgrade' into iap

53c42d5

21km43 changed the title ~~Add commands for controling IAP mode~~ Add commands for firmware upgrade & control IAP mode Dec 8, 2025

21km43 marked this pull request as ready for review December 8, 2025 07:44

21km43 and others added 9 commits December 8, 2025 16:46

Fix typo in firmware upgrade task

10ef56a

skip get_device_descriptor when opening iap device

558c636

Merge branch 'main' into iap

86ad85b

Update macOS environment in CI workflow

b5449e7

refactoring

8a8db95

revent ci.yml

fd22325

revent changelog.md

6773618

Removed unreleased changes for IAP mode switch and WCH-LinkE firmware upgrade.

Merge branch 'ch32-rs:main' into iap

b4fbba5

This was referenced Jan 1, 2026

[Feature Request] Upgrade firmware via IAP mode prosper00/CH32V305-DAPLink-HS#3

Open

IAP Upgrade 21km43/CH32V305-DAPLink-HS#2

Open

andelf requested a review from Copilot January 18, 2026 09:15

Copilot started reviewing on behalf of andelf January 18, 2026 09:16 View session

Copilot AI reviewed Jan 18, 2026

View reviewed changes

21km43 added 2 commits February 4, 2026 10:47

Merge branch 'ch32-rs:main' into iap

6645050

Merge branch 'ch32-rs:main' into iap

f454230

-            txbuf[0] = cmd;
+            txbuf[0] = cmd;
+            debug_assert!(
+                copy_size <= u8::MAX as usize,
+                "copy_size ({}) exceeds u8::MAX ({})",
+                copy_size,
+                u8::MAX
+            );

	let _ = dev.write_endpoint(ENDPOINT_OUT_IAP, &buf);
	dev.write_endpoint(ENDPOINT_OUT_IAP, &buf)?;

	let _ = dev.write_endpoint(ENDPOINT_OUT_IAP, &txbuf[0..4 + copy_size]);
	dev.write_endpoint(ENDPOINT_OUT_IAP, &txbuf[0..4 + copy_size])?;

-            let _ = dev.write_endpoint(endp_out, &buf);
+            if let Err(e) = dev.write_endpoint(endp_out, &buf) {
+                log::error!("Failed to send IAP enter command: {:?}", e);
+                return Err(e);
+            }

Uh oh!

Conversation

21km43 commented Jan 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

andelf commented Dec 8, 2025

Uh oh!

21km43 commented Dec 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

andelf commented Dec 8, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 18, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 18, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 18, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 18, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 18, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 18, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 18, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 18, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 18, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 18, 2026

Choose a reason for hiding this comment

Uh oh!

andelf commented Jan 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

21km43 commented Jan 17, 2025 •

edited

Loading

21km43 commented Dec 8, 2025 •

edited

Loading