Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/vowstar/kflash.py
kflash, A Python-based cross-platform Kendryte K210 UART ISP Utility
https://github.com/vowstar/kflash.py
k210 kflash
Last synced: 21 days ago
JSON representation
kflash, A Python-based cross-platform Kendryte K210 UART ISP Utility
- Host: GitHub
- URL: https://github.com/vowstar/kflash.py
- Owner: vowstar
- License: mit
- Created: 2020-04-15T04:10:37.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2022-06-20T08:19:43.000Z (over 2 years ago)
- Last Synced: 2024-10-11T13:35:59.629Z (about 1 month ago)
- Topics: k210, kflash
- Language: Python
- Size: 915 KB
- Stars: 6
- Watchers: 3
- Forks: 8
- Open Issues: 0
-
Metadata Files:
- Readme: README.rst
- License: LICENSE
Awesome Lists containing this project
README
kflash, A Python-based Kendryte K210 UART ISP Utility
=====================================================
.. image:: https://img.shields.io/pypi/v/kflash.svg
:target: https://pypi.org/project/kflash/
.. image:: https://img.shields.io/pypi/pyversions/kflash.svg
:target: https://pypi.org/project/kflash/
.. image:: https://github.com/vowstar/kflash.py/actions/workflows/main.yml/badge.svg
:target: https://github.com/vowstar/kflash.py/actions/workflows/main.yml
The latest release version will put here, and sync with pip.
Usage
-----
.. code:: bash
# kflash --help
usage: kflash.py [-h] [-p PORT] [-f FLASH] [-b BAUDRATE] [-l BOOTLOADER] [-e] [-k KEY] [-v] [--verbose] [-t]
[-n] [-s] [-B {kd233,dan,bit,bit_mic,goE,goD,maixduino,trainer}] [-S] [-A ADDR] [-L LENGTH]
[-i IOMODE]
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
-e, --erase Erase flash (chip erase)
-k KEY, --key KEY AES key in hex, if you need encrypt your firmware.
-v, --version Print version.
--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 {kd233,dan,bit,bit_mic,goE,goD,maixduino,trainer}, --Board {kd233,dan,bit,bit_mic,goE,goD,maixduino,trainer}
Select dev board
-S, --Slow Slow download mode
-A ADDR, --addr ADDR Erase flash addr
-L LENGTH, --length LENGTH
Erase flash length
-i IOMODE, --iomode IOMODE
SPI flash IO mode, dio for dual SPI, qio for quad SPI
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:
.. code:: bash
sudo pip3 install --upgrade kflash
If you installed as a non root user, please try:
.. code:: bash
pip install kflash --user --upgrade
And then add ``${HOME}/.local/bin`` to your ``${PATH}``, .e.g, in your ``.bashrc`` or ``.zshrc``.
.. code:: bash
export PATH=${HOME}/.local/bin:${PATH}
If you got an error, please try
.. code:: bash
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.
.. code:: bash
sudo usermod -a -G dialout $(whoami)
For gentoo user
.. code:: bash
sudo usermod -a -G uucp $(whoami)
Sample Usage
------------
.. code:: bash
# 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,
.. code:: bash
# 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,
.. code:: bash
# 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
Erase flash before download firmware, use -e (--erase) option to do chip erase before download firmware,
or use the erase command to erase a specific address and length without download firmware.
.. code:: bash
python3 kflash.py -e -B bit -b 1500000 -p /dev/ttyUSB0 hello_world.bin
python3 kflash.py -b 115200 -p /dev/ttyUSB0 erase --addr 0x00011000 --length 0x1000
Select SPI I/O mode by use --iomode option.
dio is set flash mode to Dual SPI, the Dual SPI serial throughput rates reach around 20 Mbps.
qio is set flash mode to Quad SPI, the Quad SPI serial throughput rates reach around 40 Mbps.
Usually DIO mode has better compatibility and QIO mode has faster speed.
If you find that your k210 cannot boot, you can try DIO mode.
.. code:: bash
python3 kflash.py -i dio -B bit -b 1500000 -p /dev/ttyUSB0 hello_world.bin
python3 kflash.py -i qio -B bit -b 1500000 -p /dev/ttyUSB0 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
.. code:: bash
python get-pip.py
python -m pip install pyserial
python -m pip install pyelftools
--------------
macOS Requirements
~~~~~~~~~~~~~~~~~~
.. code:: bash
# 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code:: bash
sudo apt update
sudo apt install python3 python3-pip
sudo pip3 install pyserial
sudo pip3 install pyelftools
--------------
Fedora
~~~~~~
.. code:: bash
sudo dnf install python3
sudo python3 -m pip install pyserial
sudo python3 -m pip install pyelftools
--------------
CentOS
~~~~~~
.. code:: bash
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
.. code:: bash
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)**.
.. code:: bash
# 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)**.
.. code:: bash
# 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\*
.. code:: bash
ls /dev/ttyUSB*
- It will print :
.. code:: bash
$ ls /dev/ttyUSB*
/dev/ttyUSB0
/dev/ttyUSB2
/dev/ttyUSB13
- Choose the one you think belongs to your device, or you may try multimule
names.
.. code:: bash
# 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.\*
.. code:: bash
ls /dev/cu.*
- It will print :
.. code:: bash
$ 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.
.. code:: bash
# 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 `__