WCHISPTool CMD Command Line Programming Tool Instructions

: June 15, 2024
: WCH

Table of Contents

Introduction
Windows Platform
Linux Platform
- Instruction
- Run log file
macOS Platform
- Instruction
- Run log file
Documents / Resources

**WCHISPTool CMD Command Line Programming Tool

**

Introduction

Software function

WCHISPTool _ CMD is a multi-platform command line tool for WCH MCU burning online, which supports firmware download, verification and other operations for series MCU of WCH through USB or serial port. The tool contains ISP library and sample programs for customized development of ISP tool.

Supported operating system: Windows x86/x64, Linux x64, macOS x64/arm64.

Supported chip model: CH54x/ CH55x/ CH56x/ CH641x/ CH643x/ CH57x/ CH58x/ CH59x/ CH32F10x/ CH3F20x/ CH32V00x/ CH32V10x/ CH32V20x/ CH32V30x/ CH32X03x/ CH32L10x.

Command line

Download

USB mode:
sudo ./WCHISPTool_CMD -p /dev/ch37x -c Config.ini -o program -f Target.hex

Serial port mode:
sudo ./WCHISPTool_CMD -p /dev/ttyISP0 -b 115200 -c Config.ini -o program -f Target.hex

Verify

USB mode:
sudo ./WCHISPTool_CMD -p /dev/ch37x -c Config.ini -o verify -f Target.hex

Serial port mode:
sudo ./WCHISPTool_CMD -p /dev/ttyISP0 -b 115200 -c Config.ini -o verify -f Target.hex

Parameter description

-p|

Instruction ~~description~~

|

Parameters description

---|---|---
USB ISP device or serial device node| /dev/ch37x /dev/ttyISPx| Download via USB in Linux Download via serial port in Linux
LocationlD *COM(/dev/tty.)| Download via USB in macOS Download via serial port in macOS
-b| Communication baud rate of serial port| 115200/230400/| Communication baud rate of serial port
-v| Print version number| boot/tool| The boot/tool version
-c| The full path name of the configure file| xxx.ini| The full/relative path
-o| The type of operation| program/verify| Download/Verify
-f| The name of Flash file| xxx. hex/xxx. bin**| The full/relative path

Notes:

All commands and parameters must appear in pairs in the format “-x xxx”.
Download or verify operation is required to pass in -p,-c,-o,-f instructions.
For the confirmation method of the USB ISP device or serial port node name corresponding to the – p command,

Status code

Instruction description	Parameters description
0	Execute successfully
1	Invalid input parameter
2	Failed to get parameters from the configuration file
3	Failed to set ISP parameters
4	The specified serial port name is invalid
5	No device enumerated
6	The specified chip type is not consistent with the actual chip type
7	Failed to get the device information
8	Invalid Flash file path
9	Invalid Flash file length
10	Failed to read the Flash file
11	Failed to convert the Flash file from HEX to BIN format
12	Failed to disable read protection
13	Failed to download
14	Failed to verify
100	Unknown error

Configuration file

The configuration file is generated by the “Save UI Config” function of WchIspStudio.exe in Windows. The specific operations are as follows: First, open the software and select MCU series on the right side of the software. Next, select series and model of the chip in the interface of “Chip Option” and configure the chip in the interface of “Download Config”. Then click the main menu “File ->Save UI Config”. Finally select the name and location of the configuration file. The operation interface is as follows.

Custom development

The src directory in each system folder contains the source files of the command line burning tool, which can be directly developed based on this code to meet the customized demand of users. The lib directory contains the ISP development dynamic library and header files. For functions and call instructions, users could refer to WCH55XISPDLL. H and other header files in the lib directory.

Windows Platform

For details, please refer to: https://www.wch.cn/downloads/WCHISPTool_Setup_exe.html install path \ WCHISPTool_XXX\Doc.

Linux Platform

Instruction

USB download mode

Plug USB
Make sure MCU is in BOOT download mode, and PID of USB device is 0x55e0.
Install USB device driver
Open the system terminal, enter the driver folder, and execute the “make install” command. This operation is only required for the first download.
Determine USB ISP device name
Use the “ls” command to check whether the /dev/ch37x character device exists.
Execute download instruction
Execute according to the instruction format requirements of the tool, for example, sudo ./WCHISPTool_CMD -p /dev/ch37x0 -c Config.ini -o program -f Target.hex

Serial port download mode

Connect MCU with serial port
Ensure MCU is in BOOT download mode.
Create serial ISP device name
Confirm the serial port device node name, and then use the “ln” command to create a soft link named “ttyISPx” for this device. The specific command is as follows. sudo ln –s /dev/ttyUSB0 /dev/ttyISP0
Execute download instruction.
Execute according to the instruction format requirements of the tool, for example, sudo ./WCHISPTool_CMD -p /dev/ttyISP0 –b 115200 -c Config.ini -o program -f Target.hex

Run log file

The instance of successful download operation
Run log file

The instance of failed download operation

The instance of getting the BOOT version separately

The instance of getting the software version separately

macOS Platform

Instruction

USB download mode

Plug USB
Make sure MCU is in BOOT download mode, and PID of USB device is 0x55e0.
Determine the location ID of the USB device in the macOS system. Find the device in the System Report ->Hardware ->USB. The location ID in the USB device tree is shown in the following figure.
Execute download instruction
Execute according to the instruction format requirements of the tool, for example, sudo ./WCHISPTool_CMD -p 0x02131000 -c Config.ini -o program -f Target.hex

Serial port download mode

Connect MCU with serial port
Ensure MCU is in BOOT download mode.
Determine the node name of the serial port on the device, and run the “ls /dev/tty.*” command on the
terminal to check the serial port on the macOS(If the WCH serial port chip is used, install the CH34xVCPDriver of the macOS). A specific operation is shown in the figure below.
Execute download instruction
Execute according to the instruction format requirements of the tool, for example, sudo ./WCHISPTool_CMD -p tty.wchusbserial214201–b 115200 -c Config.ini -o program -f Target.hex

Run log file

The instance of successful download operation

The instance of failed download operation

The instance of getting the BOOT version separately

The instance of getting the software version separately

Documents / Resources

| WCH WCHISPTool CMD Command Line Programming Tool [pdf] Instructions
WCHISPTool CMD Command Line Programming Tool, WCHISPTool, CMD Command Line Programming Tool, Command Line Programming Tool, Line Programming Tool, Programming Tool
---|---