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]
                    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
    -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

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 <http://blog.sipeed.com/p/352.html>`__, 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

.. code:: bash

    python3 kflash.py -e -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 <https://www.python.org/downloads/release/python-367/>`__
-  Download the `get-pip.py at https://bootstrap.pypa.io/get-pip.py <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 <https://github.com/adrianmihalko/ch340g-ch34g-ch34x-mac-os-x-driver>`__
