kflash 1.0.3

Kendryte UART ISP Utility - programming code to k210

The latest release version will put here, and sync with pip.

Usage

# kflash --help
usage: kflash [-h] [-p PORT] [-f FLASH] [-b BAUDRATE] [-l BOOTLOADER]
                [-k KEY] [-v] [-t] [-n] [-s] [-B BOARD] [-S SLOW]
                firmware

positional arguments:
firmware              firmware bin path

optional arguments:
-h, --help            show this help message and exit
-p PORT, --port PORT  COM Port
-f FLASH, --flash FLASH
                        SPI Flash type, 0 for SPI3, 1 for SPI0
-b BAUDRATE, --baudrate BAUDRATE
                        UART baudrate for uploading firmware
-l BOOTLOADER, --bootloader BOOTLOADER
                        bootloader bin path
-k KEY, --key KEY     AES key in hex, if you need encrypt your firmware.
-v, --verbose         increase output verbosity
-t, --terminal        Start a terminal after finish (Python miniterm)
-n, --noansi          Do not use ANSI colors, recommended in Windows CMD
-s, --sram            Download firmware to SRAM and boot
-B BOARD, --Board BOARD
                        Select dev board, e.g. kd233, dan, bit, goD, goE or
                        trainer
-S SLOW, --Slow SLOW  Slow download mode

Attention

Maixgo with openec firmware, BOARD must choose -B goE, and should choose sencond com port.

With cmsis-dap firmware(before 2019.02.21), BOARD must use -B goD.

You can update new cmsis-dap firmware, it is same as openec.

For K210 Trainer V0.01b, BOARD must choose -B trainer.

For KD233, BOARD must choose -B kd233, and the jumper for kd233 automatic download circuit must be set.

Installation

If you installed as a root user, please try:

sudo pip3 install --upgrade kflash

If you installed as a non root user, please try:

pip install kflash --user --upgrade

And then add ${HOME}/.local/bin to your ${PATH}, .e.g, in your .bashrc or .zshrc.

export PATH=${HOME}/.local/bin:${PATH}

If you got an error, please try

sudo python -m pip install --upgrade kflash
sudo python3 -m pip install --upgrade kflash
sudo pip install --upgrade kflash
sudo pip2 install --upgrade kflash

For linux users, first of all, you must add yourself to dialout group. Or you have to use root permission every time.

sudo usermod -a -G dialout $(whoami)

For gentoo user

sudo usermod -a -G uucp $(whoami)

Sample Usage

# Linux or macOS
# Using pip
kflash -B dan firmware.bin
kflash -B dan -t firmware.bin # Open a Serial Terminal After Finish
# Using source code
python3 kflash.py -B dan firmware.bin
python3 kflash.py -B dan -t firmware.bin # Open a Serial Terminal After Finish

# Windows CMD or PowerShell
# Using pip
kflash -B dan firmware.bin
kflash -B dan -t firmware.bin # Open a Serial Terminal After Finish
kflash -B dan -n -t firmware.bin # Open a Serial Terminal After Finish, do not use ANSI colors
# Using source code
python kflash.py -B dan firmware.bin
python kflash.py -B dan -t firmware.bin # Open a Serial Terminal After Finish
python kflash.py -B dan -n -t firmware.bin # Open a Serial Terminal After Finish, do not use ANSI colors

# Windows Subsystem for Linux
# Using pip
sudo kflash -B dan -p /dev/ttyS13 firmware.bin # ttyS13 Stands for the COM13 in Device Manager
sudo kflash -B dan -p /dev/ttyS13 -t firmware.bin # Open a Serial Terminal After Finish
# Using source code
sudo python3 kflash.py -B dan -p /dev/ttyS13 firmware.bin # ttyS13 Stands for the COM13 in Device Manager
sudo python3 kflash.py -B dan -p /dev/ttyS13 -t firmware.bin # Open a Serial Terminal After Finish

For fast programming,

# Using pip
# This will enable opoenec super-baudrate!
kflash -b 4500000 -B goE firmware.bin
# Trainer could use 8000000 baudrate!
kflash -b 8000000 -B trainer firmware.bin
# Dan could use 3000000 baudrate!
kflash -b 3000000 -B dan firmware.bin

# Using source code
# This will enable opoenec super-baudrate!
python3 kflash.py -b 4500000 -B goE firmware.bin
# Trainer could use 8000000 baudrate!
python3 kflash.py -b 8000000 -B trainer firmware.bin
# Dan could use 3000000 baudrate!
python3 kflash.py -b 3000000 -B dan firmware.bin

Execute user code directly in SRAM and view in serial terminal,

# Using pip
# For `.elf` file
kflash -b 115200 -B goE -s -t hello_world
# For `.bin` file
kflash -b 115200 -B goE -s -t hello_world.bin

# Using source code
# For `.elf` file
python3 kflash.py -b 115200 -B goE -s -t hello_world
# For `.bin` file
python3 kflash.py -b 115200 -B goE -s -t hello_world.bin

Requirements

• python>=3 or python=2.7

• pyserial>=3.4

• pyelftools>=0.25

  Python3 is recommended.

If your python version below python3.6, you need upgrade python at least python 3.6.

Windows Requirements

• Download and Install Python3 at python.org

• Download the get-pip.py at https://bootstrap.pypa.io/get-pip.py

• Start CMD or PowerShell Terminal and run the following command

python get-pip.py
python -m pip install pyserial
python -m pip install pyelftools

---

macOS Requirements

# Install Homebrew, an awesome package manager for macOS
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
brew install python
python3 -m pip3 install pyserial
python3 -m pip3 install pyelftools

---

Ubuntu, Debian Requirements

sudo apt update
sudo apt install python3 python3-pip
sudo pip3 install pyserial
sudo pip3 install pyelftools

---

Fedora

sudo dnf install python3
sudo python3 -m pip install pyserial
sudo python3 -m pip install pyelftools

---

CentOS

sudo yum -y install epel-release
sudo yum -y install python36u python36u-pip
sudo ln -s /bin/python3.6 /usr/bin/python3
sudo ln -s /bin/pip3.6 /usr/bin/pip3
sudo pip3 install pyserial
sudo pip3 install pyelftools

Trouble Shooting

Could not open port /dev/tty*: [Errno 13] Permission denied: ‘/dev/tty*’

For Windows Subsystem for Linux, you may have to use sudo due to its docker like feature

• Add your self to a dialout group to use usb-to-uart devices by

sudo usermod -a -G dialout $(whoami)

• Logout, and log in.

---

UART Auto Detecting is Not Working, or Select the Wrong UART Port

Windows

• Check the COM Number for your device at the Device Manager, such as USB-SERIAL CH340(COM13).

# Using pip, only need once when you install
pip install kflash
kflash -p COM13 firmware.bin
# Or
kflash.exe -p COM13 firmware.bin
# Using source code
python kflash.py -p COM13 firmware.bin

Windows Subsystem For Linux(WSL)

• Check the COM Number for your device at the Device Manager, such as USB-SERIAL CH340(COM13).

# Using pip, only need once when you install
sudo pip3 install kflash
sudo kflash -p /dev/ttyS13 firmware.bin # You have to use *sudo* here
# Using source code
sudo python3 kflash.py -p /dev/ttyS13 firmware.bin # You have to use *sudo* here

Linux

• Check the USB Device Name, Usually presented as ttyUSB*

ls /dev/ttyUSB*

• It will print :

$ ls /dev/ttyUSB*
/dev/ttyUSB0
/dev/ttyUSB2
/dev/ttyUSB13

• Choose the one you think belongs to your device, or you may try multimule names.

# Using pip
python3 kflash.py -p /dev/ttyUSB13 firmware.bin
# Using source code
kflash -p /dev/ttyUSB13 firmware.bin

macOS

• Check the USB Device Name, Usually presented as cu.*

ls /dev/cu.*

• It will print :

$ ls /dev/ttyUSB*
/dev/cu.wchusbserial1410
/dev/cu.wchusbserial1437
/dev/cu.SLAB_USBtoUART2333

• Choose the one you think belongs to your device, or you may try multimule names.

# Using pip
kflash -p /dev/cu.wchusbserial1410 firmware.bin
# Using source code
python3 kflash.py -p /dev/cu.wchusbserial1410 firmware.bin

You may unable to find the device even in the /dev, check the link below for drivers

• For K210 and Sipeed Dan -> WCH CH34x USB2UART Chip