Merge pull request #146 from SummerGGift/update_micropython_docs

[update] micropython docs

Author: armink

docs/assets/en_connect_board.gif

@@ -0,0 +1,53 @@
+# 为 MicroPython 扩展 C 模块
+
+当使用原生 MicroPython 进行开发时，你可能会遇到这样一些限制，比如官方没有实现自己想要的功能，或者你觉得这些实现不符合自己的工作需求。此时，添加自己的 C 模块到 MicroPython 中是一个不错的选择，你可以按照自己的想法，设计适合自己的 Python 函数调用。
+
+为了帮助各位开发者快速添加 C 模块，RT-Thread 提供了相应的辅助工具 [C 绑定代码自动生成器](https://summerggift.github.io/Micropython-C-Generator/)。该工具可以帮助开发者自动生成 C 代码和 MicroPython 之间的接口层，开发者只需将 C 语言编写的功能代码添加到指定位置，MicroPython 即可直接调用该功能。
+
+## Python 调用 C 函数的实现原理
+
+C 语言和 Python 是两种完全不同的语言，如何使用 MicroPython 来调用 C 语言所实现的函数是许多小伙伴非常疑惑的地方。简单来说，这个问题的关键点在于，如何用 C 语言的形式在 MicroPython 源代码中**表述函数的入参和出参**。我举一个例子来讲解这个问题， 请观察如下 Python 函数：
+
+```python
+def add(a, b):
+    return a + b
+```
+
+该函数有两个入参，返回一个参数。此时如果能用 C 语言表示该 **Python 函数的输入输出参数**，就可以将一个实现该功能的 C 函数对接到 MicroPython 中。
+
+### 添加用户函数到 MicroPython
+
+假设上述函数的参数类型都为整形，通过自动生成器可以得到如下样板函数：
+
+```c
+STATIC mp_obj_t add(
+    mp_obj_t arg_1_obj,
+    mp_obj_t arg_2_obj) {
+    mp_int_t arg_1 = mp_obj_get_int(arg_1_obj);  /* 通过 Python 获取的第一个整形参数 arg_1 */
+    mp_int_t arg_2 = mp_obj_get_int(arg_2_obj);  /* 通过 Python 获取的第二个整形参数 arg_2 */
+    mp_int_t ret_val;
+
+    /* Your code start! */
+
+    ret_val = arg_1 + arg_2;  /* 处理入参 arg_1 和 arg_2，并将结果赋给返回值 ret_val */
+
+    /* Your code end! */
+
+    return mp_obj_new_int(ret_val);               /* 向 python 返回整形参数 ret_val */
+}
+MP_DEFINE_CONST_FUN_OBJ_2(add_obj, add);
+```
+
+生成器会处理好需要导出到 MicroPython 的函数的入参和出参，而开发者只需要编写相应的代码来处理这些输入参数，并且把返回值赋给输出参数即可。 通过包含头文件的方式，可以调用先前编写的 C 函数来对输入参数进行处理，或者根据输入参数来执行相应的动作，添加控制硬件的驱动的原理也是一样的。
+
+最终使用 Python 调用 C 函数的效果如下：  
+
+```python
+>>> import userfunc
+>>> userfunc.add(666,777)
+1443
+```
+
+### 添加用户模块到 MicroPython
+
+添加用户模块到 MicroPython 中也不难，首先应当熟练掌握上述添加 C 函数的过程，然后参考 PR [add module userfunc to MicroPython](https://github.com/RT-Thread-packages/micropython/pull/144) 来添加属于自己的模块，该 PR 实现了添加 `userfunc` 模块到 MicroPython 的功能，你可以按照同样的方式将自己编写的模块注册到 MicroPython 中，要注意仔细查看这个 PR 中修改的 4 个文件，不要漏掉修改的细节。

docs/external_c_modules.md

@@ -1,6 +1,6 @@
 ## MicroPython 固件开发指南
 
-如果手上没有官方支持固件的开发板，就需要自己来动手制作 MicroPython 固件了。由于 RT-Thread 官方提供了 MicroPython 软件包，并且 MicroPython 底层和硬件绑定时对接了 RT-Thread 驱动框架，所以我们可以很方便地在运行了 RT-Thread 的板卡上将  MicroPython 跑起来。
+如果手上没有官方支持固件的开发板，就需要自己来动手制作 MicroPython 固件了。由于 RT-Thread 官方提供了 [MicroPython 软件包](https://github.com/RT-Thread-packages/micropython)，并且 MicroPython 底层和硬件绑定时对接了 RT-Thread 驱动框架，因此可以很方便地在运行了 RT-Thread 的板卡上将 MicroPython 跑起来。
 
 **注意**：RT-Thread MicroPython 需要运行在 **RT-Thread 3.0** 版本以上。
 
@@ -53,12 +53,7 @@ RT-Thread MicroPython mini 版本占用资源最大不超过：
 
 ### 在 main 线程中启动 MicroPython 
 
-最后要在 main 线程中启动 MicroPython，需要完成的功能如下：
-
-1. 挂载文件系统到 `/` 目录
-2. 启动 MicroPython
-
-上述功能可以通过修改 main 函数来实现，修改 main 代码如下所示：
+最后要在 main 线程中启动 MicroPython，代码修改如下所示：
 
 ```c
 #include <rtthread.h>
@@ -67,42 +62,43 @@ RT-Thread MicroPython mini 版本占用资源最大不超过：
 #include <dfs_fs.h>
 #include <rtdevice.h>
 
+/* 文件系统所在分区名称，根据实际情况填写 */
 #define FS_PARTITION_NAME     "W25Q128"
 
-/* defined the LED0 pin: PF9 */
-#define LED0_PIN    GET_PIN(F, 9)
-
 int main(void)
 {
-    /* 挂载 elm 文件系统到 / 目录 */
-    if (dfs_mount(FS_PARTITION_NAME, "/", "elm", 0, 0) == 0) 
+    /* 挂载 elm 文件系统到 / 目录，如果你所使用的开发板没有文件系统也可以跳过这一步 */
+    if (dfs_mount(FS_PARTITION_NAME, "/", "elm", 0, 0) == 0)
     {
         rt_kprintf("Filesystem initialized!");
     }
     else
     {
-        rt_kprintf("Filesystem initialization failed!");
+        /* 如果挂载失败，则尝试在文件系统分区重新创建文件系统 */
+        dfs_mkfs("elm", FS_PARTITION_NAME);
+        /* 尝试重新挂载文件系统 */
+        if (dfs_mount(FS_PARTITION_NAME, "/", "elm", 0, 0) == 0)
+        {
+            /* 仍然挂载文件系统失败，请自行检查失败原因 */
+            rt_kprintf("Failed to initialize filesystem!");
+        }
     }
 
     rt_thread_mdelay(100);
 
-    /* 运行 MicroPython 启动函数 */
-    extern void mpy_main(const char *filename);
-    mpy_main(NULL);
-
-    rt_kprintf("You can enter repl mode by typing python commands.");
+    while(1)
+    {
+        /* 在这里让程序进入循环，通过这种方式实现 MicroPython 的软复位*/
+        extern void mpy_main(const char *filename);
+         /* 启动 MicroPython */
+        mpy_main(NULL);
+    }
 
-    /* 如果想要在 REPL 环境按下 CTRL+D 重启系统可以加上下面这一句 */
-    /* rt_hw_cpu_reset(); */    
+    return RT_EOK;
 }
 ```
 
-重新编译工程下载到板卡中，就会在 main 线程中自动进入 MicroPython 的交互环境 REPL。此时如果先前没有在存储器上创建相应的文件系统，可能会导致文件系统挂载失败。此时可以使用如下两种方法在存储设备上创建文件系统：
-
-- 按下 `CTRL + D` 进入 msh 使用 `mkfs -t elm W25Q128` 命令创建文件系统
-- 在 REPL 交互环境中输入 `import os`，`os.mkfs("elm", "W25Q128")` 命令来创建文件系统
-
-注意： **W25Q128** 是本次示例中将要创建文件系统的块设备名称，并不是固定填写该名称。因此在使用上述命令创建文件系统前，需要确定当前系统中块设备的实际名称。
+重新编译工程并下载程序到板卡中，就会在 main 线程中自动启动 MicroPython，接下来就可以使用 [**RT-Thread MicroPython 开发环境**](https://marketplace.visualstudio.com/items?itemName=RT-Thread.rt-thread-micropython) 来进行应用开发了。 通过开发环境连接到开发板，即可看到 MicroPython 的交互环境 REPL，如下图所示：
 
-成功创建文件系统后，就可以使用 [ **MicroPython 开发环境**](https://marketplace.visualstudio.com/items?itemName=RT-Thread.rt-thread-micropython) 来进行应用开发了。
+![en_connect_board](assets/en_connect_board.gif)
 

docs/firmware-develop.md

@@ -11,7 +11,7 @@ RT-Thread 为广大开发者提供了 VSCode 最好用的 MicroPython 插件 来
 - 支持在内存中快速运行代码文件功能
 - 支持运行代码片段功能
 - 支持多款主流 MicroPython 开发板
-- 支持 windows 及 ubuntu 操作系统
+- 支持 Windows、Ubuntu、Mac 操作系统
 
 ### 安装 IDE 开发环境
 
@@ -21,4 +21,4 @@ RT-Thread 为广大开发者提供了 VSCode 最好用的 MicroPython 插件 来
 
 可通过查看如下文档进一步了解并使用 RT-Thread MicroPython IDE：
 
-- [RT-Thread MicroPython develop environment](https://marketplace.visualstudio.com/items?itemName=RT-Thread.rt-thread-micropython)
+- [RT-Thread MicroPython Develop Environment](https://marketplace.visualstudio.com/items?itemName=RT-Thread.rt-thread-micropython)