【完善】micropython 固件开发指南

docs/MicroPythonPlug-in/MicroPython 固件开发指南.md

@@ -2,50 +2,91 @@
 
 如果手上没有官方支持固件的开发板，就需要自己来动手制作 MicroPython 固件了。由于 RT-Thread 官方提供了 MicroPython 软件包，并且 MicroPython 底层和硬件绑定时对接了 RT-Thread 驱动框架，所以我们可以很方便地在运行了 RT-Thread 的板卡上将  MicroPython 跑起来。
 
-接下来我们以 `rt-thread\bsp\stm32\stm32f407-atk-explorer` 为例，讲解如何在 BSP 的基础上制作 MicroPython 固件。
+接下来我们以 `rt-thread\bsp\stm32\stm32f407-atk-explorer` 上的 MDK 工程为例，讲解如何在 BSP 的基础上制作 MicroPython 固件。
 
 ### 获取 MicroPython 软件包
 
-先使用 `pkgs --upgrade` 命令更新软件包列表，然后通过 env 工具获取 MicroPython 软件包。
+先使用 `pkgs --upgrade` 命令更新软件包列表，然后通过 env 工具选中 MicroPython 软件包，最后使用 `pkgs -update` 命令将软件包拉取到本地。
 
 ![1564476611502](assets/1564476611502.png)
 
-软件包配置完成后记得使用 `pkgs -update` 命令将软件包更新到本地。
-
 ### 增大 main 线程栈
 
-为了能正常运行 MicroPython，需要增大 main 线程的栈大小，这里我们将栈大小增加到 8k。
+为了能后续在 main 线程中启动 MicroPython 运行时环境，需要增大 main 线程的栈大小，这里我们将栈大小增加到 8k。
 
 ![1564476903287](assets/1564476903287.png)
 
 ### 配置 MicroPython 运行环境堆大小
 
-接下来需要根据板卡实际剩余 RAM 的情况来给 MicroPython 运行环境分配运行时内存，这里填写的数值越大，就能运行更多代码量的 Python 程序。在本次示例中，由于 RAM 剩余充足，我们在此填写 70k。
+接下来根据板卡内存实际剩余情况来给 MicroPython 运行环境分配内存，这里填写的数值越大，就能运行更大代码量的 Python 程序。但是如果这里填写的数值超过了实际可分配内存，就可能会出现无法分配内存而报错。因此在配置此项目之前，需要对系统 RAM 资源的分配情况有一定了解。
+
+#### 查看系统剩余内存
+
+重新生成工程，编译下载后通过 `msh` 的 `free` 命令来查看内存使用情况。
 
-如果这里填写的数值过大，可能会出现无法分配内存而报错。所以在配置此项目之前，可以先通过 `msh` 的 `free` 命令来查看内存使用情况，对系统 RAM 资源的使用情况有一定了解。
+![1564628226157](assets/1564628226157.png)
+
+#### 配置系统
+
+通过上一步查询的内存分配情况，可以看到系统 RAM 资源较为剩余充足。因此我们决定分配 70k 内存给 MicroPython 运行时环境，配置如下图所示：
 
 ![1564476923786](assets/1564476923786.png)
 
 ### 在根目录挂载文件系统
 
-最后要确保系统中 `/` 目录挂载了文件系统，有了文件系统，我们后续才能使用 [ **MicroPython 开发环境**](https://marketplace.visualstudio.com/items?itemName=RT-Thread.rt-thread-micropython) 将 Python 代码文件同步到板卡中来运行。本次示例中，我们配置使用 elm-fat 文件系统。如果对文件系统相关概念有疑问，可以参考 [文件系统说明文档](https://www.rt-thread.org/document/site/programming-manual/filesystem/filesystem/) 进行配置。
+最后要确保系统中 `/` 目录挂载了文件系统。有了文件系统，后续才能使用 [**MicroPython 开发环境**](https://marketplace.visualstudio.com/items?itemName=RT-Thread.rt-thread-micropython) 将 Python 代码文件同步到板卡中来运行，本次示例中将使用 elm-fat 文件系统，需要对系统进行如下配置：
 
 ![1564480676371](assets/1564480676371.png)
 
-配置完成后，记得要使用 env 工具重新生成工程，使配置生效。
+配置完成后，记得要使用 `scons --target=mkd5` 重新生成工程，使配置在工程中生效。
+
+### 在 main 线程中启动 MicroPython 
+
+最后要在 main 线程中启动 MicroPython，需要完成的功能如下：
+
+1. 挂载文件系统到 `/` 目录
+2. 启动 MicroPython
+
+上述功能可以通过修改 main 函数来实现，修改 main 代码如下所示：
+
+```c
+#include <rtthread.h>
+#include <rtdevice.h>
+#include <board.h>
+#include <dfs_fs.h>
+#include <rtdevice.h>
+
+#define FS_PARTITION_NAME     "W25Q128"
+
+/* defined the LED0 pin: PF9 */
+#define LED0_PIN    GET_PIN(F, 9)
 
-### 修改 main 线程启动代码
+int main(void)
+{
+    /* 挂载 elm 文件系统到 / 目录 */
+    if (dfs_mount(FS_PARTITION_NAME, "/", "elm", 0, 0) == 0) 
+    {
+        rt_kprintf("Filesystem initialized!");
+    }
+    else
+    {
+        rt_kprintf("Filesystem initialization failed!");
+    }
 
-在 main 线程中需要做两件事：
+    rt_thread_mdelay(100);
 
-- 挂载文件系统到 `\` 目录
-- 在 main 线程中启动 MicroPython
+    /* 运行 MicroPython 启动函数 */
+    extern void mpy_main(const char *filename);
+    mpy_main(NULL);
 
-修改 main 线程的代码如下图所示：
+    rt_kprintf("You can enter repl mode by typing python commands.");
 
-![modify_main_thread](assets/1564481108595.png)
+    /* 如果想要在 REPL 环境按下 CTRL+D 重启系统可以加上下面这一句 */
+    /* rt_hw_cpu_reset(); */    
+}
+```
 
-重新编译工程，并下载到板卡中，就会在 main() 线程中自动进入 MicroPython 的交互环境 REPL。此时如果先前没有在存储器上创建相应的文件系统，可能会导致文件系统挂载失败。此时可以使用如下两种方法在存储设备上创建文件系统：
+重新编译工程下载到板卡中，就会在 main 线程中自动进入 MicroPython 的交互环境 REPL。此时如果先前没有在存储器上创建相应的文件系统，可能会导致文件系统挂载失败。此时可以使用如下两种方法在存储设备上创建文件系统：
 
 - 按下 `CTRL + D` 进入 msh 使用 `mkfs -t elm W25Q128` 命令创建文件系统
 - 在 REPL 交互环境中输入 `import os`，`os.mkfs("elm", "W25Q128")` 命令来创建文件系统