diff --git a/docs/source/api/api_device.rst b/docs/source/api/api_device.rst index 60d1d888..ea243edc 100644 --- a/docs/source/api/api_device.rst +++ b/docs/source/api/api_device.rst @@ -29,7 +29,7 @@ CORE - **ep_addr** 端点地址（带方向） - **ep_cb** 端点中断回调函数。 -.. note:: 注册 IN 方向则表示发送完成后触发，注册 OUT 中断则表示有数据就触发。 +.. note:: 注册 IN 方向则表示发送完成后触发，类似于 dma 完成中断。注册 OUT 中断则表示有数据就触发，类似于 fifo 不为空中断。 接口结构体 """""""""""""""""""""""""""""""""""" diff --git a/docs/source/index.rst b/docs/source/index.rst index 66670705..add562ae 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -8,6 +8,22 @@ CherryUSB 使用指南 CherryUSB 是一个小而美的、可移植性高的、用于嵌入式系统的 USB 主从协议栈。 +**小在哪？** + +代码中基本不使用全局的数组，使用链表的方式由用户动态的添加。并且基本不占用很大的 ram，flash 的占用也非常小。 + +**美在哪？** + +代码从上到下是逐次递进的过程，不存在什么跳到其他文件，或者顺序倒换的问题，也就是说当你从上往下把代码看完，你也就知道 usb 协议栈是如何工作的了。 + +**可移植性高在哪？** + +根据 usb ip 的特点，定义了标准的 dcd 和 hcd 的 porting 接口，只要依次实现，就可以使用 usb 协议栈了。 + +最重要的一点，无论从机还是主机协议栈，协议栈只做枚举过程的操作，其余所有应用层操作，协议栈不会做。比如使用从机时，触发了其他端点的 out 中断，那么将直接调用到用户注册的函数中，由用户自己读取，而协议栈并不会使用类似 ringbuffer 的形式读取到一块 buffer上先存着，减少 copy 次数。而类似 msc 和 rndis 这种已经成标准的则由协议栈进行操作。 +此外，使用从机协议栈过程中你就发现，out 中断就像串口接收中断一样，in 中断就像 dma 完成中断一样。而主机协议栈则是在枚举完成后提供了注册的 **devname** ，用户通过 **devname** 得到收发时需要的句柄，从而进行数据的收发，无需知道收发设备的端点和地址，用户也不想知道这么多信息，太过复杂。 + + - 从机协议栈视频教程：https://www.bilibili.com/video/BV1Ef4y1t73d - 主机协议栈视频教程：TODO - github ：https://github.com/sakumisu/CherryUSB @@ -19,7 +35,7 @@ CherryUSB 是一个小而美的、可移植性高的、用于嵌入式系统的 quick_start/bl702 quick_start/stm32f429 quick_start/es32f369 - quick_start/rt-thread/rt-thread_zh + quick_start/rt-thread/rtthread quick_start/other_chip .. toctree:: diff --git a/docs/source/quick_start/es32f369.rst b/docs/source/quick_start/es32f369.rst index fdf68525..f0e0e7a7 100644 --- a/docs/source/quick_start/es32f369.rst +++ b/docs/source/quick_start/es32f369.rst @@ -3,25 +3,33 @@ ES32F3xx 系列单片机中 USB 外设使用标准的 musb ip，并且拥有 usb device 和 usb host 功能。本章主要介绍如何在东软载波的 ES32F369x 开发板中使用 CherryUSB。 -首先需要从 essemi 官网下载 `keil 芯片支持包 `_ 并安装，下载 `ES32 SDK `_ ，并进入 ES32 SDK 中，复制 `Drivers` 到 如图所示目录下： +在使用之前需要从 essemi 官网下载 `keil 芯片支持包 `_ 并安装， -.. figure:: img/1.png -进入 MDK-ARM 目录下，双击 `example.uvprojx` 打开工程，选择好调试器后，编译烧录即可。 -如果是从机，默认提供的是 cdc acm 的示例，代码烧录以后，将 usb 线插到 板子的丝印为 USB-OTG 口，并接上电脑，按下复位键，电脑便会枚举出一个串口。打开串口，勾选 DTR 可以接收数据，在发送缓冲区填入数据并发送，调试器的串口便可以打印出接收的长度和数据。 -如果是主机，则需要一个 usb 母口转接线，并接入相关 usb 设备，就可以进行测试了。比如接上 鼠标、U盘、4G 网卡等等。 +工程样例试用 +----------------------- + +在 CherryUSB demo 目录下已经有主机跟从机的样例，在有板子的情况下，可以先跑工程样例，试用一下。 +- 试用之前，需要先下载 `ES32 SDK `_ ，并进入 ES32 SDK 中，复制 `Drivers` 到 如图所示目录下： + +.. figure:: img/es321.png + +- 然后进入 MDK-ARM 目录下，双击 `example.uvprojx` 打开工程，选择好调试器后，编译烧录即可。 +- 如果是从机，默认提供的是 cdc acm 的示例，代码烧录以后，将 usb 线插到 板子的丝印为 USB-OTG 口，并接上电脑，按下复位键，电脑便会枚举出一个串口。打开串口，勾选 DTR 可以接收数据，在发送缓冲区填入数据并发送，调试器的串口便可以打印出接收的长度和数据。 +- 如果是主机，则需要一个 usb 母口转接线，并接入相关 usb 设备，就可以进行测试了。比如接上鼠标、U盘、4G 网卡等等。 USB Device 移植要点 ----------------------- -针对自定义的工程移植，需要以下步骤： +针对自定义的工程移植，需要按照以下步骤： -- 准备好可以进行调试打印的工程，并且实现 `printf`。 +- 准备好可以进行调试打印的工程，并且实现 `printf`、 `malloc` 、 `free` 函数（也可以直接勾选 Use microlib 来使用）。 - 拷贝 CherryUSB 源码到工程里 - 添加 CherryUSB 源码和头文件路径，其中 `usbd_core.c` 和 `usb_dc_musb.c` 为必须添加项。 +- 拷贝 `usb_config.h` 文件到自己工程目录下，并添加相应的目录头文件路径。所以根目录下的文件仅作为参考，不要添加根目录下的头文件。 -.. figure:: img/2.png -.. figure:: img/3.png +.. figure:: img/es322.png +.. figure:: img/es323.png - 实现 `usb_dc_low_level_init` 函数，该函数主要负责 USB 时钟、引脚、中断的初始化。例如 @@ -51,10 +59,11 @@ USB Host 移植要点 - 准备好可以进行调试打印的带 FreeRTOS 或者 RT-Thread 的工程，并且实现 `printf`、 `malloc` 、 `free` 函数（也可以直接勾选 Use microlib 来使用）。 - 拷贝 CherryUSB 源码到工程里 -- 添加 CherryUSB 源码和头文件路径，其中 `usbh_core.c` 和 `usb_hc_musb.c` 、 osal 下的文件为必须添加项。 +- 添加 CherryUSB 源码和头文件路径，其中 `usbh_core.c` 和 `usb_hc_musb.c` 、 osal 下的文件为必须添加项，根据不同的 os 添加对应的文件。 +- 拷贝 `usb_config.h` 文件到自己工程目录下，并添加相应的目录头文件路径。所以根目录下的文件仅作为参考，不要添加根目录下的头文件。 -.. figure:: img/4.png -.. figure:: img/5.png +.. figure:: img/es324.png +.. figure:: img/es325.png - 由于是作为主机，推荐添加所有的 class，功能全面。当然如果只用一个 class ，就添加一个。 - 实现 `usb_hc_low_level_init` 函数，该函数主要负责 USB 时钟、引脚、中断的初始化。例如 diff --git a/docs/source/quick_start/img/1.png b/docs/source/quick_start/img/es321.png similarity index 100% rename from docs/source/quick_start/img/1.png rename to docs/source/quick_start/img/es321.png diff --git a/docs/source/quick_start/img/2.png b/docs/source/quick_start/img/es322.png similarity index 100% rename from docs/source/quick_start/img/2.png rename to docs/source/quick_start/img/es322.png diff --git a/docs/source/quick_start/img/3.png b/docs/source/quick_start/img/es323.png similarity index 100% rename from docs/source/quick_start/img/3.png rename to docs/source/quick_start/img/es323.png diff --git a/docs/source/quick_start/img/4.png b/docs/source/quick_start/img/es324.png similarity index 100% rename from docs/source/quick_start/img/4.png rename to docs/source/quick_start/img/es324.png diff --git a/docs/source/quick_start/img/5.png b/docs/source/quick_start/img/es325.png similarity index 100% rename from docs/source/quick_start/img/5.png rename to docs/source/quick_start/img/es325.png diff --git a/docs/source/quick_start/other_chip.rst b/docs/source/quick_start/other_chip.rst index d183c5fb..9685442c 100644 --- a/docs/source/quick_start/other_chip.rst +++ b/docs/source/quick_start/other_chip.rst @@ -6,12 +6,13 @@ USB Device 移植要点 ----------------------- -- 拷贝 CherryUSB 源码到工程里 -- 添加 `usbd_core.c` -- 添加 `usb_dc_xxx.c`，它是芯片所对应的 USB IP dcd 部分驱动，如果不知道自己芯片属于那个 USB IP，参考 **port** 目录下的不同 USB IP 的 readme。如果使用的 USB IP 没有支持，只能自己实现了 -- 添加 `USBD_IRQHandler=xxxx` 和 `USB_NUM_BIDIR_ENDPOINTS=x` 的 CFLAG，如果没有添加则使用 `usb_dc_xxx.c` 默认配置 -- 添加 CherryUSB 源码中使用到的源文件的对应头文件路径，不要添加CherryUSB 根目录路径 -- 根据自己的需求添加 对应 **class** 目录下的文件，并且添加的文件形似 `usbd_xxx.c` +- 拷贝 CherryUSB 源码到工程目录下 +- 添加 `usbd_core.c` 参与编译 +- 根据自己的需求添加对应 **class** 目录下的文件参与编译，并且添加的文件形似 `usbd_xxx.c` +- 添加 `usb_dc_xxx.c` 参与编译，它是芯片所对应的 USB IP dcd 部分驱动，如果不知道自己芯片属于那个 USB IP，参考 **port** 目录下的不同 USB IP 的 readme。如果使用的 USB IP 没有支持，只能自己实现了 +- 添加 `USBD_IRQHandler=xxxx` 、 `USB_NUM_BIDIR_ENDPOINTS=x` 以及 `USB_BASE=0xxxxx` 的 CFLAG，如果没有添加则使用 `usb_dc_xxx.c` 中默认配置 +- 添加 CherryUSB 源码中使用到的头文件路径 +- 拷贝 `usb_config.h` 文件到自己工程目录下，并添加相应的目录头文件路径。所以根目录下的文件仅作为参考，不要添加根目录下的头文件 - 实现 `usb_dc_low_level_init` 函数，该函数主要负责 USB 时钟、引脚、中断的初始化（此函数在对应的 `usb_dc_xxx.c` 中为弱定义）。该函数可以放在你想要放的任何参与编译的 c 文件中。如何进行 USB 的时钟、引脚、中断等初始化，请自行根据你使用的芯片原厂提供的源码中进行添加。 - 描述符的注册、class的注册、接口的注册、端点中断的注册。不会的参考 demo 下的 template - 调用 `usbd_initialize` 初始化 usb 硬件 @@ -23,12 +24,12 @@ USB Host 移植要点 - 拷贝 CherryUSB 源码到工程里 - 添加 `usbh_core.c` +- 根据自己的需求添加对应 **class** 目录下的文件参与编译，并且添加的文件形似 `usbh_xxx.c`。推荐全部添加，这样可以支持很多 class - 添加 `usb_hc_xxx.c`，它是芯片所对应的 USB IP hcd 部分驱动，如果不知道自己芯片属于那个 USB IP，参考 **port** 目录下的不同 USB IP 的 readme。如果使用的 USB IP 没有支持，只能自己实现了 -- 添加 `USBH_IRQHandler=xxxx` 的 CFLAG，如果没有添加则使用 `usb_hc_xxx.c` 默认配置 -- 拷贝一份 `usb_config.h` 文件到自己的工程中，根据实际情况修改主机相关的 CONFIG 宏。CherryUSB 根目录下的为 template，不要使用 -- 添加 **osal** 目录下文件，不同 os 只能选择一个 -- 添加 CherryUSB 源码中使用到的源文件的对应头文件路径，不要添加CherryUSB 根目录路径 -- 根据自己的需求添加 对应 **class** 目录下的文件，并且添加的文件形似 `usbh_xxx.c`。推荐全部添加。 +- 添加 `USBH_IRQHandler=xxxx` 、 `USB_BASE=0xxxxx` 的 CFLAG，如果没有添加则使用 `usb_hc_xxx.c` 中默认配置 +- 添加 **osal** 目录下文件，根据不同的 os 选择对应的源文件 +- 添加 CherryUSB 源码中使用到的头文件路径 +- 拷贝 `usb_config.h` 文件到自己工程目录下，并添加相应的目录头文件路径。所以根目录下的文件仅作为参考，不要添加根目录下的头文件 - 实现 `usb_hc_low_level_init` 函数，该函数主要负责 USB 时钟、引脚、中断的初始化（此函数在对应的 `usb_hc_xxx.c` 中为弱定义）。该函数可以放在你想要放的任何参与编译的 c 文件中。如何进行 USB 的时钟、引脚、中断等初始化，请自行根据你使用的芯片原厂提供的源码中进行添加。 - 调用 `usbh_initialize` 初始化 usb 硬件 - 如果使用的是 GCC，需要在链接脚本中添加如下代码： diff --git a/docs/source/quick_start/rt-thread/img/demo1.png b/docs/source/quick_start/rt-thread/img/demo1.png deleted file mode 100644 index 5176a02c..00000000 Binary files a/docs/source/quick_start/rt-thread/img/demo1.png and /dev/null differ diff --git a/docs/source/quick_start/rt-thread/img/demo2.png b/docs/source/quick_start/rt-thread/img/demo2.png deleted file mode 100644 index 29d30734..00000000 Binary files a/docs/source/quick_start/rt-thread/img/demo2.png and /dev/null differ diff --git a/docs/source/quick_start/rt-thread/img/demo3.png b/docs/source/quick_start/rt-thread/img/demo3.png deleted file mode 100644 index 82bb35ff..00000000 Binary files a/docs/source/quick_start/rt-thread/img/demo3.png and /dev/null differ diff --git a/docs/source/quick_start/rt-thread/img/env1.png b/docs/source/quick_start/rt-thread/img/env1.png new file mode 100644 index 00000000..f8fcb33e Binary files /dev/null and b/docs/source/quick_start/rt-thread/img/env1.png differ diff --git a/docs/source/quick_start/rt-thread/img/env2.png b/docs/source/quick_start/rt-thread/img/env2.png new file mode 100644 index 00000000..2adc4d7b Binary files /dev/null and b/docs/source/quick_start/rt-thread/img/env2.png differ diff --git a/docs/source/quick_start/rt-thread/img/env3.png b/docs/source/quick_start/rt-thread/img/env3.png new file mode 100644 index 00000000..af69dd75 Binary files /dev/null and b/docs/source/quick_start/rt-thread/img/env3.png differ diff --git a/docs/source/quick_start/rt-thread/img/env4.png b/docs/source/quick_start/rt-thread/img/env4.png new file mode 100644 index 00000000..36c4e53c Binary files /dev/null and b/docs/source/quick_start/rt-thread/img/env4.png differ diff --git a/docs/source/quick_start/rt-thread/img/env5.png b/docs/source/quick_start/rt-thread/img/env5.png new file mode 100644 index 00000000..85de879a Binary files /dev/null and b/docs/source/quick_start/rt-thread/img/env5.png differ diff --git a/docs/source/quick_start/rt-thread/img/env6.png b/docs/source/quick_start/rt-thread/img/env6.png new file mode 100644 index 00000000..20a57d07 Binary files /dev/null and b/docs/source/quick_start/rt-thread/img/env6.png differ diff --git a/docs/source/quick_start/rt-thread/img/env7.png b/docs/source/quick_start/rt-thread/img/env7.png new file mode 100644 index 00000000..d304afc3 Binary files /dev/null and b/docs/source/quick_start/rt-thread/img/env7.png differ diff --git a/docs/source/quick_start/rt-thread/img/rtt_cdc_demo.png b/docs/source/quick_start/rt-thread/img/rtt_cdc_demo.png deleted file mode 100644 index 861669e1..00000000 Binary files a/docs/source/quick_start/rt-thread/img/rtt_cdc_demo.png and /dev/null differ diff --git a/docs/source/quick_start/rt-thread/img/rtt_libc.png b/docs/source/quick_start/rt-thread/img/rtt_libc.png deleted file mode 100644 index 7fd5f00c..00000000 Binary files a/docs/source/quick_start/rt-thread/img/rtt_libc.png and /dev/null differ diff --git a/docs/source/quick_start/rt-thread/img/rtt_menuconfig1.png b/docs/source/quick_start/rt-thread/img/rtt_menuconfig1.png deleted file mode 100644 index 24caa9c7..00000000 Binary files a/docs/source/quick_start/rt-thread/img/rtt_menuconfig1.png and /dev/null differ diff --git a/docs/source/quick_start/rt-thread/img/rtt_menuconfig2.png b/docs/source/quick_start/rt-thread/img/rtt_menuconfig2.png deleted file mode 100644 index fbf49ab4..00000000 Binary files a/docs/source/quick_start/rt-thread/img/rtt_menuconfig2.png and /dev/null differ diff --git a/docs/source/quick_start/rt-thread/img/stm32_init.png b/docs/source/quick_start/rt-thread/img/stm32_init.png new file mode 100644 index 00000000..3ce57201 Binary files /dev/null and b/docs/source/quick_start/rt-thread/img/stm32_init.png differ diff --git a/docs/source/quick_start/rt-thread/img/stm32cubemx0.png b/docs/source/quick_start/rt-thread/img/stm32cubemx0.png new file mode 100644 index 00000000..1ea33e04 Binary files /dev/null and b/docs/source/quick_start/rt-thread/img/stm32cubemx0.png differ diff --git a/docs/source/quick_start/rt-thread/img/stm32cubemx.png b/docs/source/quick_start/rt-thread/img/stm32cubemx1.png similarity index 100% rename from docs/source/quick_start/rt-thread/img/stm32cubemx.png rename to docs/source/quick_start/rt-thread/img/stm32cubemx1.png diff --git a/docs/source/quick_start/rt-thread/rt-thread.md b/docs/source/quick_start/rt-thread/rt-thread.md deleted file mode 100644 index 7c57a47c..00000000 --- a/docs/source/quick_start/rt-thread/rt-thread.md +++ /dev/null @@ -1,84 +0,0 @@ -# RT-Thread based Software Package Development Guide - -[中文版](rt-thread_zh.md) - -To use CherryUSB package, you need to select it in the RT-Thread package manager. The specific path is as follows: - -``` --> RT-Thread online packages - -> system packages - --- CherryUSB: tiny and portable USB stack for embedded system with USB IP - - CherryUSB Options ----> - USB Speed (FS) ---> - [*] Enable usb device mode - [*] Enable usb cdc acm device - [ ] Enable usb hid device - [ ] Enable usb dfu device - [ ] Enable usb msc device - [ ] Enable usb hub device - [ ] Enable usb audio device - [ ] Enable usb video device - - Version (latest) ---> -``` - -## Based ON STM32 Platform - -Please note that stm32 series have two usb ip. For usb ip, like stm32f0、stm32f1、stm32f3, for usb otg ip(as we know it is from **synopsys**),like stm32f4、stm32f7 and so on. - -### Use USB Device - -- Firstly,you should have a bsp project,and then go to `board\CubeMX_Config` directory, open file that suffix name with `.ioc` in **STM32CubeMX**. -- Enable **USB** or **USB_OTG_FS** or **USB_OTG_HS** in **Connectivity** List,enable USB IRQ in **NVIC Setting**. - -![STM32CubeMX USB setting](img/stm32cubemx.png) - -- Enable USB Clock for 48Mhz in **Clock configuration**. - -![STM32CubeMX USB clock](img/stm32cubemx_clk.png) - -- Generate code. -- Copy **SystemClock_Config** into **board.c**. -- ~~Copy **MX_USB_OTG_FS_PCD_Init** or **MX_USB_OTG_HS_PCD_Init** into **main.c** if you use **usb_dc_hal.c**.Also, USB Irq from **it.c** needs the same.~~ -- Implement **usb_dc_low_level_init** and copy codes in from ``HAL_PCD_MspInit``. - -``` -void usb_dc_low_level_init(void) -{ - /* Peripheral clock enable */ - __HAL_RCC_USB_CLK_ENABLE(); - /* USB interrupt Init */ - HAL_NVIC_SetPriority(USB_LP_CAN1_RX0_IRQn, 0, 0); - HAL_NVIC_EnableIRQ(USB_LP_CAN1_RX0_IRQn); - -} -``` - -- Implement **printf** or modify with **rt_kprintf** in **usb_utils.h**, usb stack needs. -- Now we can call some functions provided by **usb_stack**.Your should register descriptors、interfaces and endpoint callback firstly, and then call `usb_dc_init`. Example is as follows: - -``` -int main(void) -{ - extern void cdc_init(void); - cdc_init(); - usb_dc_init(); - while (1) - { - uint8_t data_buffer[10] = { 0x31, 0x32, 0x33, 0x34, 0x35, 0x31, 0x32, 0x33, 0x34, 0x35 }; - usbd_ep_write(0x81, data_buffer, 10, NULL); - rt_thread_mdelay(500); - } -} -``` - -- How to register class you can go to [stm32 class examples](https://github.com/sakumisu/usb_stack/tree/master/demo/stm32/stm32f103c8t6/example) for a reference. - -### CDC Demo Demonstration - -![CDC Demo](img/rtt_cdc_demo.png) - -### Video manual - -If you have problem from steps above, you can see this video：[Use USB Stack in RT-Thread package manager](https://www.bilibili.com/video/BV1Ef4y1t73d?p=26)。 \ No newline at end of file diff --git a/docs/source/quick_start/rt-thread/rt-thread_zh.md b/docs/source/quick_start/rt-thread/rt-thread_zh.md deleted file mode 100644 index e9bff015..00000000 --- a/docs/source/quick_start/rt-thread/rt-thread_zh.md +++ /dev/null @@ -1,148 +0,0 @@ -# 基于 RT-Thread 软件包开发指南 - -[English Version](rt-thread.md) - -使用 CherryUSB package 需要在 RT-Thread 的包管理器中选择它，具体路径如下： - -``` --> RT-Thread online packages - -> system packages - --- CherryUSB: tiny and portable USB stack for embedded system with USB IP - - CherryUSB Options ----> - USB Speed (FS) ---> - [*] Enable usb device mode - [ ] Enable usb host mode - [*] Enable usb cdc acm device - [ ] Enable usb hid device - [ ] Enable usb dfu device - [ ] Enable usb msc device - [ ] Enable usb hub device - [ ] Enable usb audio device - [ ] Enable usb video device - - Version (latest) ---> -``` - -## 基于 STM32 平台 - -STM32 系列单片机有两种 USB IP,分别是 USB IP 和 USB OTG IP。其中 USB IP，例如 STM32F0、STM32F1、STM32F3等等，USB OTG IP(我们都知道用的是 **synopsys** 公司的)的有 STM32F4、STM32F7、STM32H7等等。当前如果你需要使用 USB Device 功能，porting 接口提供了两种，一种是适配 USB IP的 **fsdev**,另一种是适配 USB OTG IP 的 **synopsys**。 - -### 使用 USB Device 功能 - -- 首先，你需要有一个 bsp 工程，之后进入到 `board\CubeMX_Config` 目录下，使用 **STM32CubeMX** 打开后缀名为 `.ioc` 的文件。 -- 进入 **Connectivity** 选项，选择 **USB** 或者 **USB_OTG_FS** 或者 **USB_OTG_HS**，并使能 device 功能，在 **NVIC Setting** 中开启 USB 中断。 - -![STM32CubeMX USB setting](img/stm32cubemx.png) - -- 在 **Clock configuration** 栏配置 USB 时钟为 48Mhz. - -![STM32CubeMX USB clock](img/stm32cubemx_clk.png) - -- 点击 **Generate code**。 -- 复制 **SystemClock_Config** 函数内容到 **board.c** 中。 -- 实现 ``usb_dc_low_level_init``，并将 ``HAL_PCD_MspInit`` 里面内容复制进来，例如： - -``` -void usb_dc_low_level_init(void) -{ - /* Peripheral clock enable */ - __HAL_RCC_USB_CLK_ENABLE(); - /* USB interrupt Init */ - HAL_NVIC_SetPriority(USB_LP_CAN1_RX0_IRQn, 0, 0); - HAL_NVIC_EnableIRQ(USB_LP_CAN1_RX0_IRQn); - -} -``` - -- 由于协议栈默认使用 `printf` 和 `malloc` 和 `free`,所以需要开启 libc 支持或者自己实现。 -![libc](img/rtt_libc.png) - -- 使用 **menuconfig** 配置 **CherryUSB** 软件包，使能 usb device 并勾选需要的 device class。 -![usb host](img/rtt_menuconfig1.png) - -- 现在我们可以调用 CherryUSB 中的函数来注册描述符、接口、端点中断，并调用 `usb_dc_init`，示例如下： - -``` -#include -#include -#include -#include - -extern void usb_dc_init(void); -int main(void) -{ - extern void cdc_init(void); - cdc_init(); - usb_dc_init(); - while (1) - { - uint8_t data_buffer[10] = { 0x31, 0x32, 0x33, 0x34, 0x35, 0x31, 0x32, 0x33, 0x34, 0x35 }; - usbd_ep_write(0x81, data_buffer, 10, NULL); - rt_thread_mdelay(500); - } -} - -``` - -- 关于如何注册 class 类可以参考 [stm32 class examples](https://github.com/sakumisu/usb_stack/tree/master/demo/stm32/stm32f103c8t6/example)。 - -### 使用 USB Host 功能 - -- 首先，你需要有一个 bsp 工程，之后进入到 `board\CubeMX_Config` 目录下，使用 **STM32CubeMX** 打开后缀名为 `.ioc` 的文件。 -- 进入 **Connectivity** 选项，选择 **USB_OTG_FS** 或者 **USB_OTG_HS**，并使能 **host only** 功能，在 **NVIC Setting** 中开启 OTG GLOBAL 中断，其余两个端点中断不需要。 - -![STM32CubeMX USB setting](img/stm32cubemx2.png) - -- 在 **Clock configuration** 栏配置 USB 时钟为 48Mhz. -- 点击 **Generate code**。 -- 复制 **SystemClock_Config** 函数内容到 **board.c** 中。 -- 修改 **usb_hc_synopsys.c** 中 HAL 库头文件包含，例如 `#include "stm32f4xx_hal.h"`。 -- 手动增加 **xxx_hal_hcd.c** 和 **xxx_ll_usb.c** 文件 -- 由于协议栈默认使用 `printf` 和 `malloc` 和 `free`,所以需要开启 libc 支持或者自己实现。 -![libc](img/rtt_libc.png) - -- 使用 **menuconfig** 配置 **CherryUSB** 软件包，使能 usb host（默认加载所有支持的 class）。 -![usb host](img/rtt_menuconfig2.png) - -- `main.c` 中调用 `usbh_initialize` 初始化 host 协议栈。 - -``` -#include -#include -#include -#include "usbh_core.h" -/* defined the LED0 pin: PH10 */ -#define LED0_PIN GET_PIN(H, 10) - -int main(void) -{ - /* set LED0 pin mode to output */ - rt_pin_mode(LED0_PIN, PIN_MODE_OUTPUT); - usbh_initialize(); - while (1) - { - rt_pin_write(LED0_PIN, PIN_HIGH); - rt_thread_mdelay(500); - rt_pin_write(LED0_PIN, PIN_LOW); - rt_thread_mdelay(500); - } -} - - -``` - -### Demo 演示 - -- cdc acm device demo - -![CDC Device Demo](img/rtt_cdc_demo.png) -- host demo - -![USB Host Demo1](img/demo1.png) -![USB Host Demo2](img/demo2.png) -![USB Host Demo3](img/demo3.png) - -### 视频教程 - -如果对上述步骤还有问题，可以参考 [协议栈在 RT-Thread 包管理器中的使用](https://www.bilibili.com/video/BV1Ef4y1t73d?p=26)。 \ No newline at end of file diff --git a/docs/source/quick_start/rt-thread/rtthread.rst b/docs/source/quick_start/rt-thread/rtthread.rst new file mode 100644 index 00000000..8ec5c6c9 --- /dev/null +++ b/docs/source/quick_start/rt-thread/rtthread.rst @@ -0,0 +1,62 @@ +基于 RT-Thread 软件包开发指南 +=============================== + +本节主要介绍使用 RT-Thread 提供的软件包管理器来配置工程，以 env 作为演示。本节操作不同芯片都一样，后续不再重复讲解。打开 env 以后使用 menuconfig 进入包管理器，并在如图所示路径中选择 CherryUSB。 + +.. figure:: img/env1.png + + +从机配置 +-------------------------- + +* 选择 Enable usb device mode 并敲回车进入。 + +.. figure:: img/env2.png + +* 首先第一个配置是配置 USB 的速度，分为 **FS、HIGH_IN_FULL、HS**,。其中， **HIGH_IN_FULL** 表示设备使用支持高速的 USB IP，但是工作在全速模式下，这里仅使用 **synopsys ip** 时使用。 + +.. figure:: img/env3.png + +* 其次第二个配置则是选择 USB device ip，不清楚自己芯片是哪个 ip的可以参考 **port** 目录下对应的 readme。 + +.. figure:: img/env4.png + +* 选择好 USB device ip 以后，还需要选择是哪款芯片，第三个配置则是用来选择芯片，选择以后会帮忙配置相对应的 ip 的一些信息，比如 `USB_BASE` 、 `USBD_Handler` 以及特殊的一些配置等等，如果没找到自己的芯片，可以手动在 `usb_dc_xxx.c` 中修改。 + +.. figure:: img/env5.png + +* 接下来是 class 的选择，用哪个 class 勾选哪个就可以了，使能 class 以后，双击进入可以选择一个 demo 的模板参与编译，当然也可以不选，自己写。 + +.. figure:: img/env6.png + +* 最后退出保存即可。 +* 退出以后不急着编译，需要在代码中实现 `usb_dc_low_level_init` 函数。最后使用芯片能够接受的编译方式进行编译。 + + +主机配置 +-------------------------- + +* 选择 Enable usb host mode 并敲回车进入。 + +.. figure:: img/env7.png + +* 和 device 配置一样，需要选择对应的 host ip，以及使用对应 ip 的芯片，如果没找到自己的芯片，可以手动在 `usb_hc_xxx.c` 中修改。 +* 默认使用除了 hub 之外的所有 class 驱动。 +* 设置 psc 线程的线程栈以及线程优先级。 +* 最后退出保存即可。 +* 退出以后不急着编译，需要在代码中实现 `usb_hc_low_level_init` 函数。最后使用芯片能够接受的编译方式进行编译。 + + +借助 STM32CubeMX 生成 USB 初始化 +---------------------------------- + +使用 STM32CubeMX 主要是用来生成 usb 时钟、引脚、中断的配置。我们需要点击如图所示文件，并配置好 USB 的时钟、中断，点击 `Generate Code`。生成的时钟配置在 `main.c` 中的 `SystemClock_Config` 文件，将其拷贝到 `board.c` 中。 + +.. figure:: img/stm32cubemx0.png +.. figure:: img/stm32cubemx1.png +.. figure:: img/stm32cubemx2.png +.. figure:: img/stm32cubemx_clk.png + +然后将 `stm32xxxx_hal_msp.c` 中的 `HAL_PCD_MspInit` 或者是 `HAL_HCD_MspInit` 中的内容复制到 `usb_dc_low_level_init` 和 `usb_hc_low_level_init` 函数中，举例如下： + +.. figure:: img/stm32_init.png \ No newline at end of file