source: azure_iot_hub_riscv/trunk/tools/kflash/README.rst@ 453

Last change on this file since 453 was 453, checked in by coas-nagasima, 4 years ago

ファイルを追加
File size: 9.0 KB
RevLine 
[453]1kflash, A Python-based Kendryte K210 UART ISP Utility
2=====================================================
3
4Usage
5-----
6
7.. code:: bash
8
9 # kflash --help
10 usage: kflash [-h] [-p PORT] [-f FLASH] [-b BAUDRATE] [-l BOOTLOADER]
11 [-k KEY] [-v] [-t] [-n] [-s] [-B BOARD] [-S SLOW]
12 firmware
13
14 positional arguments:
15 firmware firmware bin path
16
17 optional arguments:
18 -h, --help show this help message and exit
19 -p PORT, --port PORT COM Port
20 -f FLASH, --flash FLASH
21 SPI Flash type, 0 for SPI3, 1 for SPI0
22 -b BAUDRATE, --baudrate BAUDRATE
23 UART baudrate for uploading firmware
24 -l BOOTLOADER, --bootloader BOOTLOADER
25 bootloader bin path
26 -k KEY, --key KEY AES key in hex, if you need encrypt your firmware.
27 -v, --verbose increase output verbosity
28 -t, --terminal Start a terminal after finish (Python miniterm)
29 -n, --noansi Do not use ANSI colors, recommended in Windows CMD
30 -s, --sram Download firmware to SRAM and boot
31 -B BOARD, --Board BOARD
32 Select dev board, e.g. kd233, dan, bit, goD, goE or
33 trainer
34 -S SLOW, --Slow SLOW Slow download mode
35
36Attention
37---------
38
39Maixgo with openec firmware, BOARD must choose ``-B goE``, and should choose
40sencond com port.
41
42With cmsis-dap firmware(before 2019.02.21), BOARD must use ``-B goD``.
43
44You can update `new cmsis-dap firmware <http://blog.sipeed.com/p/352.html>`__, it is same as openec.
45
46For K210 Trainer V0.01b, BOARD must choose ``-B trainer``.
47
48For KD233, BOARD must choose ``-B kd233``, and the jumper for kd233 automatic
49download circuit must be set.
50
51Installation
52------------
53
54.. code:: bash
55
56 sudo pip3 install kflash
57
58If you receive an error, please try
59
60.. code:: bash
61
62 sudo python -m pip install kflash
63 sudo python3 -m pip install kflash
64 sudo pip install kflash
65 sudo pip2 install kflash
66
67For linux users, first of all, you must add yourself to dialout group.
68Or you have to use root permission every time.
69
70.. code:: bash
71
72 sudo usermod -a -G dialout $(whoami)
73
74Sample Usage
75------------
76
77.. code:: bash
78
79 # Linux or macOS
80 # Using pip
81 kflash -B dan firmware.bin
82 kflash -B dan -t firmware.bin # Open a Serial Terminal After Finish
83 # Using source code
84 python3 kflash.py -B dan firmware.bin
85 python3 kflash.py -B dan -t firmware.bin # Open a Serial Terminal After Finish
86
87 # Windows CMD or PowerShell
88 # Using pip
89 kflash -B dan firmware.bin
90 kflash -B dan -t firmware.bin # Open a Serial Terminal After Finish
91 kflash -B dan -n -t firmware.bin # Open a Serial Terminal After Finish, do not use ANSI colors
92 # Using source code
93 python kflash.py -B dan firmware.bin
94 python kflash.py -B dan -t firmware.bin # Open a Serial Terminal After Finish
95 python kflash.py -B dan -n -t firmware.bin # Open a Serial Terminal After Finish, do not use ANSI colors
96
97 # Windows Subsystem for Linux
98 # Using pip
99 sudo kflash -B dan -p /dev/ttyS13 firmware.bin # ttyS13 Stands for the COM13 in Device Manager
100 sudo kflash -B dan -p /dev/ttyS13 -t firmware.bin # Open a Serial Terminal After Finish
101 # Using source code
102 sudo python3 kflash.py -B dan -p /dev/ttyS13 firmware.bin # ttyS13 Stands for the COM13 in Device Manager
103 sudo python3 kflash.py -B dan -p /dev/ttyS13 -t firmware.bin # Open a Serial Terminal After Finish
104
105For fast programming,
106
107.. code:: bash
108
109 # Using pip
110 # This will enable opoenec super-baudrate!
111 kflash -b 4500000 -B goE firmware.bin
112 # Trainer could use 8000000 baudrate!
113 kflash -b 8000000 -B trainer firmware.bin
114 # Dan could use 3000000 baudrate!
115 kflash -b 3000000 -B dan firmware.bin
116
117 # Using source code
118 # This will enable opoenec super-baudrate!
119 python3 kflash.py -b 4500000 -B goE firmware.bin
120 # Trainer could use 8000000 baudrate!
121 python3 kflash.py -b 8000000 -B trainer firmware.bin
122 # Dan could use 3000000 baudrate!
123 python3 kflash.py -b 3000000 -B dan firmware.bin
124
125Execute user code directly in SRAM and view in serial terminal,
126
127.. code:: bash
128
129 # Using pip
130 # For `.elf` file
131 kflash -b 115200 -B goE -s -t hello_world
132 # For `.bin` file
133 kflash -b 115200 -B goE -s -t hello_world.bin
134
135 # Using source code
136 # For `.elf` file
137 python3 kflash.py -b 115200 -B goE -s -t hello_world
138 # For `.bin` file
139 python3 kflash.py -b 115200 -B goE -s -t hello_world.bin
140
141Requirements
142------------
143
144- python>=3 or python=2.7
145- pyserial>=3.4
146- pyelftools>=0.25
147
148 Python3 is recommended.
149
150If your python version below python3.4, you need:
151
152- enum34>=1.1.6
153
154Windows Requirements
155~~~~~~~~~~~~~~~~~~~~
156
157- Download and Install `Python3 at python.org <https://www.python.org/downloads/release/python-367/>`__
158- Download the `get-pip.py at https://bootstrap.pypa.io/get-pip.py <https://bootstrap.pypa.io/get-pip.py>`__
159- Start CMD or PowerShell Terminal and run the following command
160
161.. code:: bash
162
163 python get-pip.py
164 python -m pip install pyserial
165 python -m pip install pyelftools
166 # When you python version below python3.4
167 python -m pip install enum34
168
169--------------
170
171macOS Requirements
172~~~~~~~~~~~~~~~~~~
173
174.. code:: bash
175
176 # Install Homebrew, an awesome package manager for macOS
177 /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
178 brew install python
179 python3 -m pip3 install pyserial
180 python3 -m pip3 install pyelftools
181
182--------------
183
184Ubuntu, Debian Requirements
185~~~~~~~~~~~~~~~~~~~~~~~~~~~
186
187.. code:: bash
188
189 sudo apt update
190 sudo apt install python3 python3-pip
191 sudo pip3 install pyserial
192 sudo pip3 install pyelftools
193
194--------------
195
196Fedora
197~~~~~~
198
199.. code:: bash
200
201 sudo dnf install python3
202 sudo python3 -m pip install pyserial
203 sudo python3 -m pip install pyelftools
204
205--------------
206
207CentOS
208~~~~~~
209
210.. code:: bash
211
212 sudo yum -y install epel-release
213 sudo yum -y install python36u python36u-pip
214 sudo ln -s /bin/python3.6 /usr/bin/python3
215 sudo ln -s /bin/pip3.6 /usr/bin/pip3
216 sudo pip3 install pyserial
217 sudo pip3 install pyelftools
218
219Trouble Shooting
220----------------
221
222Could not open port /dev/tty*: [Errno 13] Permission denied: '/dev/tty*'
223------------------------------------------------------------------------
224
225 For Windows Subsystem for Linux, you may have to use sudo due to its docker
226 like feature
227
228- Add your self to a dialout group to use usb-to-uart devices by
229
230.. code:: bash
231
232 sudo usermod -a -G dialout $(whoami)
233
234- Logout, and log in.
235
236--------------
237
238UART Auto Detecting is Not Working, or Select the Wrong UART Port
239-----------------------------------------------------------------
240
241Windows
242~~~~~~~
243
244- Check the COM Number for your device at the Device Manager, such as
245 **USB-SERIAL CH340(COM13)**.
246
247.. code:: bash
248
249 # Using pip, only need once when you install
250 pip install kflash
251 kflash -p COM13 firmware.bin
252 # Or
253 kflash.exe -p COM13 firmware.bin
254 # Using source code
255 python kflash.py -p COM13 firmware.bin
256
257Windows Subsystem For Linux(WSL)
258~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
259
260- Check the COM Number for your device at the Device Manager, such as
261 **USB-SERIAL CH340(COM13)**.
262
263.. code:: bash
264
265 # Using pip, only need once when you install
266 sudo pip3 install kflash
267 sudo kflash -p /dev/ttyS13 firmware.bin # You have to use *sudo* here
268 # Using source code
269 sudo python3 kflash.py -p /dev/ttyS13 firmware.bin # You have to use *sudo* here
270
271Linux
272~~~~~
273
274- Check the USB Device Name, Usually presented as ttyUSB\*
275
276.. code:: bash
277
278 ls /dev/ttyUSB*
279
280- It will print :
281
282.. code:: bash
283
284 $ ls /dev/ttyUSB*
285 /dev/ttyUSB0
286 /dev/ttyUSB2
287 /dev/ttyUSB13
288
289- Choose the one you think belongs to your device, or you may try multimule
290 names.
291
292.. code:: bash
293
294 # Using pip
295 python3 kflash.py -p /dev/ttyUSB13 firmware.bin
296 # Using source code
297 kflash -p /dev/ttyUSB13 firmware.bin
298
299macOS
300~~~~~
301
302- Check the USB Device Name, Usually presented as cu.\*
303
304.. code:: bash
305
306 ls /dev/cu.*
307
308- It will print :
309
310.. code:: bash
311
312 $ ls /dev/ttyUSB*
313 /dev/cu.wchusbserial1410
314 /dev/cu.wchusbserial1437
315 /dev/cu.SLAB_USBtoUART2333
316
317- Choose the one you think belongs to your device, or you may try multimule
318 names.
319
320.. code:: bash
321
322 # Using pip
323 kflash -p /dev/cu.wchusbserial1410 firmware.bin
324 # Using source code
325 python3 kflash.py -p /dev/cu.wchusbserial1410 firmware.bin
326
327You may unable to find the device even in the /dev, check the link below for
328drivers
329
330- For K210 and Sipeed Dan -> `WCH CH34x USB2UART Chip <https://github.com/adrianmihalko/ch340g-ch34g-ch34x-mac-os-x-driver>`__
Note: See TracBrowser for help on using the repository browser.