update quick start, add readthedocs yaml

.readthedocs.yaml

@@ -0,0 +1,35 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+    # You can also specify other tool versions:
+    # nodejs: "20"
+    # rust: "1.70"
+    # golang: "1.20"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
+  # builder: "dirhtml"
+  # Fail on all warnings to avoid broken references
+  # fail_on_warning: true
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+   - requirements: docs/requirements.txt

docs/source/index.rst

@@ -53,10 +53,7 @@ CherryUSB 是一个小而美的、可移植性高的、用于嵌入式系统的
    :maxdepth: 1
    :caption: 快速上手
 
-   quick_start/bl702
-   quick_start/stm32
-   quick_start/hpm
-   quick_start/es32
+   quick_start/index
    quick_start/rt-thread/rtthread
    quick_start/other_chip
 

docs/source/quick_start/bl702.rst

@@ -1,6 +0,0 @@
-基于 BL 系列开发指南
-=========================
-
-BL 系列 USB 的开发主要使用 bl_mcu_sdk，参考 `bl_mcu_sdk <https://github.com/bouffalolab/bl_mcu_sdk>`_。
-
-USB 的相关应用位于 `examples/usbdev` 和 `examples/usbhost` 目录下，环境搭建完成后，即可编译使用。

docs/source/quick_start/es32.rst

@@ -1,84 +0,0 @@
-基于 ES32F369 开发指南
-=========================
-
-ES32F3xx 系列单片机中 USB 外设使用标准的 musb ip，并且拥有 usb device 和 usb host 功能。本章主要介绍如何在东软载波的 ES32F369x 开发板中使用 CherryUSB。
-
-在使用之前需要从 essemi 官网下载 `keil 芯片支持包 <http://www.essemi.com/index/product/detail?id=796>`_ 并安装，
-
-
-工程样例试用
------------------------
-
-在 CherryUSB demo 目录下已经有主机跟从机的样例，在有板子的情况下，可以先跑工程样例，试用一下。
-
-- 进入 MDK-ARM 目录下，双击 `example.uvprojx` 打开工程，选择好调试器后，编译烧录即可。
-- 如果是从机，默认提供的是 cdc acm 的示例，代码烧录以后，将 usb 线插到 板子的丝印为 USB-OTG 口，并接上电脑，按下复位键，电脑便会枚举出一个串口。打开串口，勾选 DTR 可以接收数据，在发送缓冲区填入数据并发送，调试器的串口便可以打印出接收的长度和数据。
-- 如果是主机，则需要一个 usb 母口转接线，并接入相关 usb 设备，就可以进行测试了。比如接上鼠标、U盘、4G 网卡等等。
-
-USB Device 移植要点
------------------------
-
-针对自定义的工程移植，需要按照以下步骤：
-
-- 准备好可以进行调试打印的工程，并且实现 `printf`、 `malloc` 、 `free` 函数（也可以直接勾选 Use microlib 来使用）。
-- 拷贝 CherryUSB 源码到工程里
-- 添加 CherryUSB 源码和头文件路径，其中 `usbd_core.c` 和 `usb_dc_musb.c` 为必须添加项。
-- 拷贝 `cherryusb_config_template.h` 文件到自己工程目录下，命名为 `usb_config.h`，并添加相应的目录头文件路径。所以根目录下的文件仅作为参考，不要添加根目录下的头文件。
-
-.. figure:: img/es322.png
-.. figure:: img/es323.png
-
-- 实现 `usb_dc_low_level_init` 函数，该函数主要负责 USB 时钟、引脚、中断的初始化。例如
-
-.. code-block:: C
-
-    void usb_dc_low_level_init(void)
-    {
-        ald_pmu_perh_power_config(PMU_POWER_USB, ENABLE);
-        ald_cmu_perh_clock_config(CMU_PERH_USB, ENABLE);
-        ald_cmu_perh_clock_config(CMU_PERH_GPIO, ENABLE);
-        ald_cmu_usb_clock_config(CMU_USB_CLOCK_SEL_HOSC, CMU_USB_DIV_1);
-        ald_rmu_reset_periperal(RMU_PERH_USB);
-        ald_mcu_irq_config(USB_INT_IRQn, 2, 2, ENABLE);
-        ald_mcu_irq_config(USB_DMA_IRQn, 2, 2, ENABLE);
-        usb_pin_init();
-    }
-
-- 描述符的注册、class的注册、接口的注册、端点中断的注册。不会的参考 demo 下的 template 。
-- 调用 `usbd_initialize` 初始化 usb 硬件。
-- 正常使用。
-
-
-USB Host 移植要点
------------------------
-
-针对自定义的工程移植，需要以下步骤：
-
-- 准备好可以进行调试打印的带 FreeRTOS 或者 RT-Thread 的工程，并且实现 `printf`、 `malloc` 、 `free` 函数（也可以直接勾选 Use microlib 来使用）。
-- 拷贝 CherryUSB 源码到工程里
-- 添加 CherryUSB 源码和头文件路径，其中 `usbh_core.c` 和 `usb_hc_musb.c` 、 osal 下的文件为必须添加项，根据不同的 os 添加对应的文件。
-- 拷贝 `cherryusb_config_template.h` 文件到自己工程目录下，命名为 `usb_config.h` ,并添加相应的目录头文件路径。所以根目录下的文件仅作为参考，不要添加根目录下的头文件。
-
-.. figure:: img/es324.png
-.. figure:: img/es325.png
-
-- 由于是作为主机，推荐添加所有的 class，功能全面。当然如果只用一个 class ，就添加一个。
-- 实现 `usb_hc_low_level_init` 函数，该函数主要负责 USB 时钟、引脚、中断的初始化。例如
-
-.. code-block:: C
-
-    void usb_hc_low_level_init(void)
-    {
-        ald_pmu_perh_power_config(PMU_POWER_USB, ENABLE);
-        ald_cmu_perh_clock_config(CMU_PERH_USB, ENABLE);
-        ald_cmu_perh_clock_config(CMU_PERH_GPIO, ENABLE);
-        ald_cmu_usb_clock_config(CMU_USB_CLOCK_SEL_HOSC, CMU_USB_DIV_1);
-        ald_rmu_reset_periperal(RMU_PERH_USB);
-        ald_mcu_irq_config(USB_INT_IRQn, 2, 2, ENABLE);
-        ald_mcu_irq_config(USB_DMA_IRQn, 2, 2, ENABLE);
-        usb_pin_init();
-    }
-
-- 调用 `usbh_initialize` 初始化 usb 硬件。
-- 此时编译会报错，因为协议栈中为每个 class 都添加了测试 demo，文件在 `usb_host.c` 中，如果不想要，可以直接删除。
-- 正常使用。

docs/source/quick_start/hpm.rst

@@ -1,6 +0,0 @@
-基于 HPM 系列开发指南
-=========================
-
-HPM 系列 USB 的开发主要使用 hpm_sdk ，参考 `hpm sdk <https://github.com/hpmicro/hpm_sdk>`_。
-
-USB 的相关应用位于 `samples/cherryusb` 目录下，环境搭建完成后，即可编译使用。

docs/source/quick_start/stm32.rst → docs/source/quick_start/index.rst

@@ -1,13 +1,41 @@
-基于 STM32F1/F4/H7 开发指南
-=============================
+基于现有 demo 快速验证
+=========================
 
-本节是基于 STM32 三个系列芯片的使用，涵盖 F1/F4/H7，其余芯片基本类似，不再赘述，具体区别有：
+在学习 USB 或者是学习 CherryUSB 代码之前，我们需要先基于现有的 demo 进行快速验证，为什么？是为了提升对 USB 的兴趣，能有信心进行下一步的动作，如果 demo 都跑不起来，或者自己摸索写代码，或者先看 USB 基本概念，结果看到最后，
+发现一点都看不懂，概念好多，根本记不住，从而丧失对 USB 的兴趣。因此，先跑 demo 非常重要。下面我将给大家罗列目前支持的 demo 仓库。
+
+
+基于 bouffalolab 系列芯片
+---------------------------
+
+仓库参考：https://github.com/CherryUSB/cherryusb_bouffalolab
+
+- BL702 是一个 USB2.0 全速芯片，共 8 个端点（包含端点0）。仅支持从机。
+- BL616/BL808 是一个 USB2.0 并且内置高速 PHY 芯片，共 5个端点（包含端点0）。支持主从机。
+- USB 的相关应用位于 `examples/usbdev` 和 `examples/usbhost` 目录下，根据官方环境搭建完成后，即可编译使用。 
+
+
+基于 ST 系列芯片
+---------------------------
+
+仓库参考：https://github.com/CherryUSB/cherryusb_stm32
+
+默认提供以下 demo 工程：
+
+- F103 使用 fsdev ip
+- F429 主从使用 hs port,并且均用 dma 模式
+- H7 设备使用 fs port，主机使用 hs port，并且主机带 cache 支持
+
+默认删除 Drivers ，所以需要使用 stm32cubemx 生成一下 Drivers 目录下的文件，demo 底下提供了 **stm32xxx.ioc** 文件，双击打开，点击 **Generate Code** 即可。
+
+.. caution:: 生成完以后，请使用 git reset 功能将被覆盖的 `main.c` 和 `stm32xxx_it.c` 文件撤回，禁止被 cubemx 覆盖。
+
+涵盖 F1/F4/H7，其余芯片基本类似，不再赘述，具体区别有：
 
 - usb ip 区别：F1使用 fsdev，F4/H7使用 dwc2
 - dwc2 ip 区别： fs port(引脚是 PA11/PA12) 和 hs port(引脚是 PB14/PB15), 其中 hs port 默认全速，可以接外部PHY 形成高速主机，并且带 dma 功能
 - F4 与 H7 cache 区别、USB BASE 区别
 
-
 如果是 STM32F7/STM32H7 这种带 cache 功能，需要将 usb 使用到的 ram 定位到 no cache ram 区域。举例如下
 
 .. code-block:: C
@@ -38,22 +66,8 @@
 
 .. figure:: img/keil.png
 
-工程样例试用
------------------------
-
-默认提供以下 demo 工程：
-
-- F103 使用 fsdev ip
-- F429 主从使用 hs port,并且均用 dma 模式
-- H7 设备使用 fs port，主机使用 hs port，并且主机带 cache 支持
-
-
-默认删除 Drivers ，所以需要使用 stm32cubemx 生成一下 Drivers 目录下的文件，demo 底下提供了 **stm32xxx.ioc** 文件，双击打开，点击 **Generate Code** 即可。
-
-.. caution:: 生成完以后，请使用 git reset 功能将被覆盖的 `main.c` 和 `stm32xxx_it.c` 文件撤回，禁止被 cubemx 覆盖。
-
 USB Device 移植要点
------------------------
+^^^^^^^^^^^^^^^^^^^^^^
 
 - 使用 **stm32cubemx** 创建工程，配置基本的 RCC、UART (作为log使用)
 
@@ -106,7 +120,7 @@ USB Device 移植要点
 .. figure:: img/stm32_15.png
 
 USB Host 移植要点
------------------------
+^^^^^^^^^^^^^^^^^^^^^^
 
 前面 7 步与 Device 一样。需要注意，host 驱动只支持带 dma 的 hs port (引脚是 PB14/PB15)，所以 fs port (引脚是 PA11/PA12)不做支持（没有 dma 你玩什么主机）。
 
@@ -131,4 +145,12 @@ USB Host 移植要点
 
 - 如果使用 **msc**，并且带文件系统，需要自行添加文件系统文件了，对应的 porting 编写参考 **fatfs_usbh.c** 文件。
 
-.. figure:: img/stm32_21.png
+.. figure:: img/stm32_21.png
+
+基于 HPMicro 系列芯片
+---------------------------
+
+仓库参考：https://github.com/CherryUSB/cherryusb_hpmicro
+
+- HPM 系列芯片均 USB 2.0 并且内置高速 PHY，支持主从机
+- USB 的相关应用位于 `samples/cherryusb` ，根据官方环境搭建完成后，即可编译使用。