開源 MaixPy 項目開發(fā)指南

本文是為了幫助一些想要成為開發(fā)者的用戶而寫的開源項目の開發(fā)文檔。

1. 獲取 maixpy 開源項目

請準備 linux 系統(tǒng)環(huán)境（在 Windows 上使用 WSL 也可以），掛上 XXX 代理，輸入 git clone https://github.com/sipeed/MaixPy 拉取 MaixPy 倉庫代碼和子模塊，確保拿到后閱讀目錄下的 build.md 文檔。

沒有代理的同學可以用 github 鏡像站列表（https://github.com/rc1844/fastgithub）加速拉取 maixpy 倉庫，請不要用 gitee 拉取 maixpy 倉庫，會掉子模塊倉庫的。

juwan@juwan-N85-N870HL:~$ git clone https:///github.com/sipeed/MaixPy
正克隆到 'MaixPy'...
remote: 對象計數(shù)中: 77517, 完成.
remote: 壓縮對象中: 100% (20929/20929), 完成.
remote: Total 77517 (delta 56791), reused 76050 (delta 55761)
接收對象中: 100% (77517/77517), 53.62 MiB | 972.00 KiB/s, 完成.
處理 delta 中: 100% (56791/56791), 完成.
juwan@juwan-N85-N870HL:~$ cd MaixPy/
juwan@juwan-N85-N870HL:~/MaixPy$ git submodule update --recursive --init
子模組 'components/kendryte_sdk/kendryte-standalone-sdk'（https://github.com/sipeed/kendryte-standalone-sdk）已對路徑 'components/kendryte_sdk/kendryte-standalone-sdk' 注冊
子模組 'components/micropython/core'（https://github.com/micropython/micropython.git）已對路徑 'components/micropython/core' 注冊
子模組 'components/micropython/port/src/lvgl/lv_bindings'（https://github.com/littlevgl/lv_binding_micropython.git）已對路徑 'components/micropython/port/src/lvgl/lv_bindings' 注冊
子模組 'components/micropython/port/src/ulab/micropython-ulab'（https://github.com/Neutree/micropython-ulab.git）已對路徑 'components/micropython/port/src/ulab/micropython-ulab' 注冊
子模組 'components/spiffs/core'（https://github.com/pellepl/spiffs.git）已對路徑 'components/spiffs/core' 注冊
子模組 'tools/flash/kflash_py'（https://github.com/sipeed/kflash.py.git）已對路徑 'tools/flash/kflash_py' 注冊
子模組 'tools/kconfig/Kconfiglib'（https://github.com/ulfalizer/Kconfiglib.git）已對路徑 'tools/kconfig/Kconfiglib' 注冊
子模組 'tools/spiffs/mkspiffs'（https://github.com/igrr/mkspiffs.git）已對路徑 'tools/spiffs/mkspiffs' 注冊
正克隆到 '/home/juwan/MaixPy/components/kendryte_sdk/kendryte-standalone-sdk'...
正克隆到 '/home/juwan/MaixPy/components/micropython/core'...

注意，這之后拉取子倉庫是沒有加速的，會從 github 試圖拉取，你也可以用同樣的方法單獨拉取子模塊位置（在 .gitmodules 中定義），本篇文檔是無法幫你解決網(wǎng)絡問題的。

如果 https:// 掛了，就自己想辦法找其他線路吧。

如何確認最終子模塊是否拉取完整，可以輸入 git submodule status，不完整請不要進行編譯，必出錯誤。

juwan@juwan-N85-N870HL:~/Desktop/maixpy$ git submodule status 
 7fdb511fe61026eec5874885de5981c4f60f664d components/kendryte_sdk/kendryte-standalone-sdk (v0.5.2-181-g7fdb511)
 ced340d739e84737dd5c8e6b4ab9af2ea44e29e7 components/micropython/core (v1.11-64-gced340d73)
 ddf09164ee1711a61169030a7ee8bf370ee5743f components/micropython/port/src/lvgl/lv_bindings (remotes/origin/dev-6.0-32-gddf0916)
 c315a571df49a19b843f7dffc300c21ccb7d4edd components/micropython/port/src/ulab/micropython-ulab (0.24-27-gc315a57)
 ec68ba8208d7550860e4e78299d58a529b88bf85 components/spiffs/core (0.2-234-gec68ba8)
 1ef6f4c0b2cb8b1872b6ffe9337f4e02d5487fa6 tools/flash/kflash_py (v1.0-79-g1ef6f4c)
 53c72959ac4d71f99913e4b0eea99261a6585430 tools/kconfig/Kconfiglib (v12.12.1-14-g53c7295)
 983970e40ff381d95d68a9bddff70c4d9921021b tools/spiffs/mkspiffs (0.2.3-6-g983970e)

1.1. 編譯 maixpy 開源項目

這節(jié)內(nèi)容假設你沒有任何搭建交叉編譯鏈的經(jīng)驗。

首先按 build.md 順序執(zhí)行各種操作即可，如果你不會英文你可以開翻譯機。

步驟說明如下：

• 給 linux 環(huán)境安裝必須的編譯工具和 Python 模塊，確保 cmake / make / python3 可用。
• 設置 toolchain 工具鏈到系統(tǒng)/opt/kendryte-toolchain/ 目錄下，方便 SDK 尋找編譯工具，確保存在 /opt/kendryte-toolchain/bin/riscv64-unknown-elf-gcc 編譯工具。
• 進入到 MaixPy 的具體硬件項目下cd projects/maixpy_k210 然后輸入python3 project.py build 開始編譯。

整個編譯步驟就這樣結(jié)束了， 編譯成功后你就會在 projects/maixpy_k210 目錄下得到一個 build 文件夾，里面有如下文件：

• maixpy.bin 將要被燒錄到 0x000000 地址的 K210 固件。
• maixpy.txt 當前固件對應的反編譯代碼內(nèi)容，輔助你排查 core dump 的指針地址的信息。

其他文件是編譯過程中產(chǎn)生的 .a 和 .o 中間編譯文件，可忽略。

1.2. 燒錄 maixpy 固件到你的硬件

現(xiàn)在你拿到了 maixpy.bin 固件，插入硬件，然后使用 python3 project.py -B goE -p /dev/ttyUSB1 -b 1500000 flash 燒錄硬件，以 -B 參數(shù)為例。

juwan@juwan-N85-N870HL:~/Desktop/maixpy/projects/maixpy_k210$ python3 project.py -h
-- SDK_PATH:/home/juwan/Desktop/maixpy
maixpy
usage: project.py [-h] [-p PORT] [-b BAUDRATE] [-t] [-n] [-s] [-B {dan,bit,bit_mic,goE,goD,maixduino,kd233,auto}] [-S] [--toolchain PATH] [--toolchain-prefix PREFIX]
                  [--config_file PATH] [--verbose]
                  {config,build,rebuild,menuconfig,clean,distclean,clean_conf,flash}

build tool, e.g. `python project.py build`

其中 -B goE 是選擇版型，可選的項有 dan,bit,bit_mic,goE,goD,maixduino,kd233,auto 表示燒錄方式，這個和具體硬件有很大關(guān)系。

• bit 通常對應使用 CH340 的芯片。
• maixduino 通常對應使用 CH552 的芯片。

具體你可以多種試試，還可以選擇燒錄頻率 115200 、1500000 的 BAUDRATE 選擇，當然，無論是哪種配置，只要能燒錄進去就行，更多的使用方法你需要查看 -h 的幫助說明。

常見的燒錄過程如下：

?  maixpy_k210_minimum git:(master) ? sudo kflash -b 1500000 -p /dev/ttyUSB0 build/maixpy.bin
[sudo] fqr 的密碼： 
[INFO] COM Port Selected Manually:  /dev/ttyUSB0 
[INFO] Default baudrate is 115200 , later it may be changed to the value you set. 
[INFO] Trying to Enter the ISP Mode... 
._
[INFO] Automatically detected goE/kd233 

[INFO] Greeting Message Detected, Start Downloading ISP 
Downloading ISP: |============================================================================================================| 100.0% 10kiB/s
[INFO] Booting From 0x80000000 
[INFO] Wait For 0.1 second for ISP to Boot 
[INFO] Boot to Flashmode Successfully 
[INFO] Selected Baudrate:  1500000 
[INFO] Baudrate changed, greeting with ISP again ...  
[INFO] Boot to Flashmode Successfully 
[INFO] Selected Flash:  On-Board 
[INFO] Initialization flash Successfully 
Programming BIN: |============================================================================================================| 100.0% 47kiB/s
[INFO] Rebooting...

1.3. 命令行連接硬件 & 運行代碼

到這一步基本都會使用了吧。

這里推薦一下開發(fā)時的一些 linux 或 micropython 的快速操作，首先可以使用 minicom 或 picocom 串口工具進入 MicroPython 終端（在燒錄命令后加上 && picocom /dev/ttyUSB0 -b 115200 就可以了），接著進入到 micropython 可以按下 Ctrl + E 進入粘貼模式，然后粘貼代碼后輸入 Ctrl + D 結(jié)束輸入運行代碼。

>>> 
paste mode; Ctrl-C to cancel, Ctrl-D to finish
=== 
=== print('hello world!')
=== 
hello world!

這樣你就完成了快速的驗證和開發(fā)，但如果你是要調(diào)試某一段功能代碼，你可以通過 mpfshell-lite 直接命令行上傳代碼，復位就運行，然后報錯和調(diào)試。

底層開發(fā)動態(tài)語言經(jīng)常這樣操作，所以要感謝所有做解釋器接口的開發(fā)者做了大量的接口驗證。

2. MaixPy 項目應用說明

假設已經(jīng)知道如何使用 MaixPy 工程進行開發(fā)、編譯、燒錄，接下來將深入介紹一些工具的用法，這里面只交待一些常見用法，并不會展開細節(jié)說明。

2.1. 介紹 cmake 的工程編譯方法

cmake 是通過 CMakeLists.txt 編寫代碼和規(guī)則后編譯生成 Makefile 的工具，用法和細節(jié)自行百度，這里有一個結(jié)構(gòu)簡單的 cmake 工程Get_static_library_by_cmake供你運行和參考學習。

在沒有 cmake 之前，都是使用 makefile 的方式進行工程管理，直到今天 micropython 官方也依然是使用雙層 Makefile + inclue(makefile) 的工程管理多版型硬件的方法。

但 MaixPy 只把 micropython 當做一個依賴庫包加入到自己的環(huán)境當中，所以實際上 MaixPy 的軟件架構(gòu)設計是圍繞著 K210 軟件組件的形式進行構(gòu)建的。

因此可以來到 maixpy 文件夾里存在一個 hello_world 的工程，讓看看它是怎么構(gòu)成的。

• hello_world
  • build
  • compile
  • main
  • CMakeLists.txt
  • config_defaults.mk
  • project.py

MaixPy 項目已經(jīng)準備了一個模板提供給你進行 K210 的項目構(gòu)建，這里忽略項目構(gòu)建的過程，重點關(guān)注需要可以編譯鏈接的工程配置部分，也就是 main 下的 CMakeLists.txt ，它的內(nèi)容如下。

############### Add include ###################
# list(APPEND ADD_INCLUDE "include"
#     )
# list(APPEND ADD_PRIVATE_INCLUDE "")
###############################################

############ Add source files #################
list(APPEND ADD_SRCS  "src/main.cpp"
    )
# aux_source_directory(src ADD_SRCS)
# list(REMOVE_ITEM COMPONENT_SRCS "src/test2.c")
###############################################

###### Add required/dependent components ######
list(APPEND ADD_REQUIREMENTS kendryte_sdk)
###############################################

############ Add static libs ##################
# list(APPEND ADD_STATIC_LIB "lib/libtest.a")
###############################################

register_component()

可以看到 ADD_SRCS 鏈接了一個 src/main.cpp 代碼文件作為程序入口。

通過 ADD_REQUIREMENTS 就可以加載其他地方的模塊進來，例如 list(APPEND ADD_REQUIREMENTS kendryte_sdk) 則請求了 kendryte_sdk 這個 SDK 包。

如果想要鏈接自己的 nncase 庫呢？其他庫代碼呢？

可以直接則改為絕對路徑下的 LINK_DIRECTORIES(/home/juwan/maixpy/projects/maixpy_old/main/src/nncase) 的代碼就可以了，這樣做的前提是這個庫是由 cmake 工程的方式提供的。

這里示范了如何在編譯調(diào)用自己的 nncase 庫，結(jié)合這些關(guān)鍵訊息再去閱讀工程，應該就可以較為輕松的用起來了吧。

2.2. 如何打包 micropython spiffs 文件系統(tǒng)分享出來

如果你深入使用了 MaixPy 進行開發(fā)，你會發(fā)現(xiàn) MaixUI 提供了一種文件系統(tǒng)文件（img），當你刷入這個 UI 系統(tǒng)一樣的 img ，你就會在燒錄后直接進入 UI 界面。

需要知道 MicroPython 是從 0x0 開始的程序，在程序中會通過 spiffs 在 Flash 的 [0xD00000, (0xD00000 + 0x300000)) 區(qū)間構(gòu)建 VFS （虛擬文件系統(tǒng)），是由 maixpy/projects/maixpy_xxxxx/config_defaults.mk 中定義得到的。

CONFIG_SPIFFS_SIZE=0x300000
CONFIG_SPIFFS_START_ADDR=0xD00000

這里只討論工具的使用，而不對其實現(xiàn)做詳解。

而 spiffs 是不支持目錄結(jié)構(gòu)的，那么我們會發(fā)現(xiàn) ui 的 img 在 flash 里的文件名稱會存在 lib/core.py 這樣的名稱，而正常情況下我們是不可能將這個文件創(chuàng)建起來的，所以要通過工具將其打包。

在 tools/spiffs/mkspiffs 目錄下有 gen_spiffs_image.py 腳本完成這個打包鏡像的功能，用法請看 tools/spiffs/README.md 說明。

• 在 spiffs 目錄下準備一個 fs 文件夾，包含你要打包的代碼或資源文件內(nèi)容。
• 執(zhí)行python gen_spiffs_image.py ../../projects/maixpy_k210/config_defaults.mk 即可得到 maixpy_spiffs.img 二進制文件。
• 將上述得到的 img 燒入到 0xD00000 就恢復 micropython 的文件系統(tǒng)里的內(nèi)容。

如果你做了一些小系統(tǒng)，用這樣的方式發(fā)布，用戶拿到你提供的 img 文件，燒入就可以立刻得到和你一樣的環(huán)境啦，這其實和基于 Linux 系統(tǒng)發(fā)布某系統(tǒng)鏡像的結(jié)構(gòu)是一樣的。

現(xiàn)在，你學會了嗎？

2.3. MaixPy 的持續(xù)集成服務（Travis CI）

Travis CI 提供的是持續(xù)集成服務（Continuous Integration，簡稱 CI）。它綁定 Github 上面的項目，只要有新的代碼，就會自動抓取。然后，提供一個運行環(huán)境，執(zhí)行測試，完成構(gòu)建，還能部署到服務器。

提及一下 MaixPy 是有借助 travis + tools/release.sh 完成項目的編譯后，將編譯目錄上傳到了發(fā)布服務器上從而完成了每日構(gòu)建，這常見于各類包的自動化構(gòu)建與編譯，感興趣不妨自己親手試試。

持續(xù)集成服務 Travis CI 教程

2.4. 如何更好的閱讀開源項目源代碼

說到這里，以個人的角度來看，基于閱讀代碼這種基本功要求之外，想要更好的閱讀源代碼，對于不同的項目有不同的組織架構(gòu)，任何一位剛進入這個行業(yè)的初學者，可以用親身經(jīng)歷的項目作為切入點，逐漸從項目架構(gòu)、源碼、編譯、測試、發(fā)布軟件等方面建立起完整的軟件工程意識，圍繞此進行知識的深入學習也是一種不錯的手段，希望你能通過這篇文章建立起完整的軟件工程體系吧。

3. 最后的參考資料

• bing.com + keyword + yourself