USB開發(fā)實(shí)戰(zhàn)：從HID到CDC虛擬串口)
1. 項(xiàng)目概述為什么STM32的USB開發(fā)值得深究如果你玩過STM32大概率用過串口打印調(diào)試信息或者通過串口和上位機(jī)通信。但當(dāng)你需要高速、穩(wěn)定地傳輸大量數(shù)據(jù)時(shí)比如傳輸攝像頭圖像、音頻流或者想做一個(gè)看起來更專業(yè)的設(shè)備插上USB線就能識(shí)別為一個(gè)特定設(shè)備而不是一個(gè)串口USB就成了繞不開的話題。而HAL庫(kù)作為ST官方主推的硬件抽象層它把USB這個(gè)復(fù)雜的協(xié)議棧封裝起來讓我們這些應(yīng)用開發(fā)者能更專注于業(yè)務(wù)邏輯而不是去死磕USB協(xié)議手冊(cè)里那些令人頭禿的細(xì)節(jié)。我最初接觸STM32的USB是想做一個(gè)自定義的HID人機(jī)接口設(shè)備控制器用來傳輸游戲搖桿的數(shù)據(jù)。當(dāng)時(shí)在標(biāo)準(zhǔn)庫(kù)和HAL庫(kù)之間糾結(jié)了很久最終還是選擇了HAL庫(kù)。原因很簡(jiǎn)單ST未來的新芯片幾乎只提供HAL庫(kù)支持生態(tài)在往這邊遷移而且HAL庫(kù)的結(jié)構(gòu)更統(tǒng)一雖然初期覺得有些“臃腫”但熟悉之后移植和跨項(xiàng)目復(fù)用代碼的效率高得多。這個(gè)項(xiàng)目標(biāo)題“STM32 HAL庫(kù)之USB”聽起來像是一個(gè)技術(shù)模塊但背后實(shí)際是一整套從硬件連接、協(xié)議棧配置、到驅(qū)動(dòng)編寫和上位機(jī)聯(lián)調(diào)的完整工程實(shí)踐。它解決的不僅僅是“通信”問題更是如何讓一個(gè)嵌入式設(shè)備以更標(biāo)準(zhǔn)、更高效的方式融入現(xiàn)代計(jì)算機(jī)體系的問題。2. 核心思路與框架設(shè)計(jì)HAL庫(kù)如何“抽象”USB很多新手拿到STM32CubeMX生成的一大堆USB代碼會(huì)感到迷茫感覺像在看天書。要理清頭緒關(guān)鍵在于理解HAL庫(kù)為USB設(shè)計(jì)的分層架構(gòu)。它不是一坨不可分割的代碼而是一個(gè)精心設(shè)計(jì)的“洋蔥”每一層都有明確的職責(zé)。2.1 HAL庫(kù)USB驅(qū)動(dòng)框架的三層模型我們可以把HAL庫(kù)的USB支持分為三層從下到上依次是硬件抽象層HAL/PLL Driver這是最底層直接操作STM32內(nèi)部的USB外設(shè)寄存器。它負(fù)責(zé)處理最基礎(chǔ)的USB電氣信號(hào)、端點(diǎn)緩沖區(qū)管理、中斷觸發(fā)等。這部分代碼通常是stm32f4xx_hal_pcd.c/.h對(duì)于設(shè)備模式或stm32f4xx_hal_hcd.c/.h對(duì)于主機(jī)模式。作為應(yīng)用開發(fā)者我們幾乎不直接調(diào)用這一層的函數(shù)HAL庫(kù)已經(jīng)幫我們封裝好了。USB設(shè)備協(xié)議棧層USB Device/Core Library這是核心層實(shí)現(xiàn)了USB 2.0規(guī)范中設(shè)備端的基本協(xié)議。它管理設(shè)備描述符告訴主機(jī)“我是什么”、處理標(biāo)準(zhǔn)的設(shè)備請(qǐng)求如獲取描述符、設(shè)置地址、設(shè)置配置、管理各個(gè)端點(diǎn)的數(shù)據(jù)流狀態(tài)。這一層的代碼位于Middlewares/ST/STM32_USB_Device_Library/目錄下。它提供了一套回調(diào)函數(shù)接口我們需要填充這些回調(diào)函數(shù)來定義設(shè)備的行為。USB設(shè)備類層USB Device Class這是應(yīng)用層基于協(xié)議棧層實(shí)現(xiàn)具體的USB設(shè)備類別功能。比如你想做一個(gè)USB虛擬串口CDC類就使用CDC類庫(kù)想做一個(gè)人機(jī)接口設(shè)備HID如鍵盤、鼠標(biāo)就使用HID類庫(kù)想實(shí)現(xiàn)大容量存儲(chǔ)MSC模擬一個(gè)U盤就使用MSC類庫(kù)。ST提供了這些常用類的實(shí)現(xiàn)模板位于Middlewares/ST/STM32_USB_Device_Library/Class/目錄下。我們的主要工作就是基于某個(gè)類模板進(jìn)行修改和適配。為什么這樣設(shè)計(jì)這種分層最大的好處是解耦和復(fù)用。協(xié)議棧層是通用的不管你做鍵盤還是U盤處理標(biāo)準(zhǔn)請(qǐng)求的邏輯都一樣。類層是可選的你可以用ST提供的也可以自己實(shí)現(xiàn)一個(gè)自定義類。而我們的應(yīng)用代碼只需要關(guān)心“數(shù)據(jù)來了怎么處理”和“數(shù)據(jù)怎么發(fā)出去”無需關(guān)心底層數(shù)據(jù)包是如何被拆解、CRC校驗(yàn)、發(fā)送的。這極大地降低了開發(fā)門檻。2.2 關(guān)鍵概念端點(diǎn)、管道與描述符在深入代碼前必須吃透這三個(gè)概念否則配置起來就是盲人摸象。端點(diǎn)Endpoint可以理解為USB設(shè)備上的“數(shù)據(jù)收發(fā)信箱”。每個(gè)端點(diǎn)都有一個(gè)唯一的地址和方向。地址0是默認(rèn)的控制端點(diǎn)用于傳輸配置、命令等關(guān)鍵信息。其他端點(diǎn)如0x81, 0x01用于傳輸應(yīng)用數(shù)據(jù)。IN端點(diǎn)設(shè)備到主機(jī)和OUT端點(diǎn)主機(jī)到設(shè)備通常是成對(duì)出現(xiàn)的。管道Pipe邏輯上的數(shù)據(jù)傳輸通道建立在主機(jī)和設(shè)備上的某個(gè)端點(diǎn)之間。你可以把它想象成連接主機(jī)和端點(diǎn)“信箱”的“郵路”。描述符Descriptor一組定義設(shè)備屬性、能力和配置的數(shù)據(jù)結(jié)構(gòu)。它是USB設(shè)備的“身份證”和“說明書”。主機(jī)在枚舉設(shè)備時(shí)會(huì)一步步讀取這些描述符從而知道該如何與設(shè)備通信。主要描述符包括設(shè)備描述符描述設(shè)備的總體信息如廠商IDVID、產(chǎn)品IDPID、設(shè)備版本、支持的配置數(shù)量等。配置描述符描述設(shè)備的一種工作模式如高功耗模式、低功耗模式包括接口數(shù)量、最大功耗等。接口描述符描述設(shè)備提供的一種功能。一個(gè)配置可以包含多個(gè)接口。例如一個(gè)帶音頻功能的USB攝像頭可能有視頻捕獲接口和音頻流接口。端點(diǎn)描述符描述某個(gè)端點(diǎn)的屬性如端點(diǎn)地址、方向、傳輸類型控制、中斷、批量、同步、最大包大小等。字符串描述符可選的提供人類可讀的設(shè)備名稱、廠商字符串等。在HAL庫(kù)項(xiàng)目中這些描述符通常以常量數(shù)組的形式定義在一個(gè)獨(dú)立的文件如usbd_desc.c中。通過STM32CubeMX配置USB設(shè)備時(shí)它會(huì)自動(dòng)生成這些描述符的框架我們只需要修改里面的VID、PID、字符串等關(guān)鍵信息即可。注意VID/PID非常重要。如果只是個(gè)人學(xué)習(xí)可以使用ST的測(cè)試ID如VID0x0483 PID0x5740。但如果產(chǎn)品要上市必須向USB-IF申請(qǐng)屬于自己的VID并為每個(gè)產(chǎn)品分配唯一的PID否則可能會(huì)與系統(tǒng)已有的設(shè)備沖突導(dǎo)致無法識(shí)別。3. 從零構(gòu)建一個(gè)USB HID設(shè)備以自定義報(bào)告設(shè)備為例理論講得再多不如動(dòng)手做一遍。我們以創(chuàng)建一個(gè)自定義的USB HID設(shè)備為例它不模擬鍵盤鼠標(biāo)而是傳輸我們自定義格式的數(shù)據(jù)比如傳感器數(shù)據(jù)包。這種設(shè)備在需要PC軟件與STM32進(jìn)行實(shí)時(shí)、雙向、小數(shù)據(jù)量通信的場(chǎng)景下非常有用因?yàn)镠ID類設(shè)備的驅(qū)動(dòng)在Windows、macOS、Linux上都是系統(tǒng)自帶的無需額外安裝驅(qū)動(dòng)。3.1 環(huán)境準(zhǔn)備與CubeMX工程配置首先確保你有一個(gè)支持USB Device功能的STM32開發(fā)板如STM32F103、F407、F429等并且板載了USB Micro-B或Type-C接口或者你通過跳線正確連接了USB的DM/DP線到芯片對(duì)應(yīng)引腳。啟動(dòng)STM32CubeMX選擇你的芯片型號(hào)。配置時(shí)鐘樹USB模塊需要精確的48MHz時(shí)鐘。對(duì)于STM32F4系列通常由主PLL分頻得到。在Clock Configuration標(biāo)簽頁確保USB OTG FS或USB OTG HS取決于你使用的USB接口的時(shí)鐘源被正確配置為48MHz。這是最容易出錯(cuò)的一步時(shí)鐘不對(duì)USB根本無法工作。使能USB外設(shè)在Pinout Configuration標(biāo)簽頁找到Connectivity-USB_OTG_FS以全速USB為例。將Mode設(shè)置為Device_Only。此時(shí)對(duì)應(yīng)的USB DMPA11和 DPPA12引腳會(huì)被自動(dòng)分配。配置USB中間件切換到Middleware區(qū)域激活USB_DEVICE。在Class For FS IP下拉菜單中選擇Human Interface Device Class (HID)。配置HID參數(shù)在Configuration標(biāo)簽頁下找到USB_DEVICE-HID。這里需要設(shè)置HID Report Descriptor。報(bào)告描述符是HID設(shè)備的核心它定義了設(shè)備上報(bào)的數(shù)據(jù)格式。對(duì)于初學(xué)者可以先使用一個(gè)簡(jiǎn)單的示例。你可以點(diǎn)擊Use custom report descriptor然后粘貼一個(gè)簡(jiǎn)單的描述符。例如下面這個(gè)描述符定義了一個(gè)包含4字節(jié)輸入報(bào)告和4字節(jié)輸出報(bào)告的設(shè)備__ALIGN_BEGIN static uint8_t HID_CUSTOM_ReportDesc[] __ALIGN_END { 0x06, 0x00, 0xFF, // Usage Page (Vendor Defined 0xFF00) 0x09, 0x01, // Usage (0x01) 0xA1, 0x01, // Collection (Application) 0x15, 0x00, // Logical Minimum (0) 0x26, 0xFF, 0x00, // Logical Maximum (255) 0x75, 0x08, // Report Size (8 bits) 0x95, 0x04, // Report Count (4) 0x09, 0x01, // Usage (0x01) 0x81, 0x02, // Input (Data, Var, Abs) - 4字節(jié)輸入報(bào)告 0x09, 0x01, // Usage (0x01) 0x91, 0x02, // Output (Data, Var, Abs) - 4字節(jié)輸出報(bào)告 0xC0 // End Collection };設(shè)置HID Polling Interval為10即10ms這是主機(jī)輪詢?cè)O(shè)備獲取輸入報(bào)告的間隔。生成工程設(shè)置好你的IDEKeil、IAR、STM32CubeIDE和工程名生成代碼。3.2 剖析生成的代碼結(jié)構(gòu)與關(guān)鍵回調(diào)函數(shù)CubeMX生成的代碼結(jié)構(gòu)非常清晰。我們重點(diǎn)關(guān)注以下幾個(gè)文件Core/Inc/usbd_conf.h和Core/Src/usbd_conf.cUSB設(shè)備底層配置如端點(diǎn)緩沖區(qū)大小、內(nèi)存管理函數(shù)等。一般無需修改。Core/Inc/usbd_desc.h和Core/Src/usbd_desc.c設(shè)備描述符定義。你需要在這里修改USBD_VID、USBD_PID、USBD_PRODUCT_STRING等。USB_DEVICE/App/usbd_hid.c和USB_DEVICE/App/usbd_hid.hHID類應(yīng)用層代碼的核心。我們需要修改的就是這里。打開usbd_hid.c找到幾個(gè)關(guān)鍵的回調(diào)函數(shù)static int8_t HID_Init_FS(void)HID設(shè)備初始化函數(shù)。在這里你可以初始化你的應(yīng)用相關(guān)變量。static int8_t HID_DeInit_FS(void)反初始化函數(shù)。static int8_t HID_OutEvent_FS(uint8_t event_idx, uint8_t state)這個(gè)函數(shù)在HID類模板中可能不存在。實(shí)際上對(duì)于自定義HID接收主機(jī)發(fā)來的數(shù)據(jù)輸出報(bào)告通常是通過另一個(gè)機(jī)制。ST的HID類庫(kù)提供了一個(gè)函數(shù)USBD_HID_ReceivePacket來啟動(dòng)接收并在接收到數(shù)據(jù)后會(huì)調(diào)用一個(gè)名為HID_OutEvent_FS的回調(diào)如果實(shí)現(xiàn)的話或者更常見的是我們需要在應(yīng)用層主動(dòng)輪詢或在一個(gè)全局回調(diào)里處理。這是一個(gè)常見的困惑點(diǎn)。 更標(biāo)準(zhǔn)的做法是在main.c或你的應(yīng)用文件中調(diào)用USBD_HID_SendReport發(fā)送數(shù)據(jù)并處理接收。接收數(shù)據(jù)通常通過端點(diǎn)OUT中斷回調(diào)來處理。但HAL庫(kù)的HID類已經(jīng)封裝了這部分。查看usbd_hid.c你會(huì)發(fā)現(xiàn)一個(gè)函數(shù)static int8_t USBD_HID_Setup (USBD_HandleTypeDef *pdev, USBD_SetupReqTypedef *req)它處理HID特定的SETUP請(qǐng)求。對(duì)于OUT數(shù)據(jù)數(shù)據(jù)會(huì)被接收到類庫(kù)內(nèi)部的一個(gè)緩沖區(qū)。因此我們的主要任務(wù)變?yōu)榘l(fā)送數(shù)據(jù)設(shè)備-主機(jī)在需要的時(shí)候例如定時(shí)器中斷、傳感器數(shù)據(jù)準(zhǔn)備好時(shí)調(diào)用USBD_HID_SendReport(hUsbDeviceFS, report_buf, report_size)。其中report_buf是你的數(shù)據(jù)緩沖區(qū)report_size必須與報(bào)告描述符中定義的輸入報(bào)告大小一致本例中為4。接收數(shù)據(jù)主機(jī)-設(shè)備主機(jī)發(fā)送的輸出報(bào)告數(shù)據(jù)會(huì)存放在HID類庫(kù)內(nèi)部。我們需要周期性地檢查或在一個(gè)回調(diào)中處理。一個(gè)簡(jiǎn)單可靠的方法是在main函數(shù)的while(1)循環(huán)中調(diào)用一個(gè)處理函數(shù)來檢查是否有新數(shù)據(jù)。但更優(yōu)雅的方式是利用HAL庫(kù)提供的機(jī)制。實(shí)際上在usbd_hid.c中有一個(gè)函數(shù)USBD_HID_DataOut它在OUT端點(diǎn)接收到數(shù)據(jù)后被底層調(diào)用。我們可以修改這個(gè)函數(shù)將接收到的數(shù)據(jù)拷貝到我們的應(yīng)用緩沖區(qū)并設(shè)置一個(gè)標(biāo)志位。3.3 實(shí)現(xiàn)自定義數(shù)據(jù)收發(fā)修改HID類模板讓我們動(dòng)手修改實(shí)現(xiàn)一個(gè)明確的收發(fā)機(jī)制。步驟一定義應(yīng)用緩沖區(qū)在usbd_hid.h中添加以下外部變量聲明/* USER CODE BEGIN EXPORTED_VARIABLES */ extern uint8_t UserRxBufferFS[4]; // 接收緩沖區(qū)大小與輸出報(bào)告一致 extern volatile uint8_t UserRxReady; // 接收完成標(biāo)志 /* USER CODE END EXPORTED_VARIABLES */在usbd_hid.c文件頂部定義這些變量/* USER CODE BEGIN PV */ uint8_t UserRxBufferFS[4] {0}; volatile uint8_t UserRxReady 0; /* USER CODE END PV */步驟二修改數(shù)據(jù)接收回調(diào)在usbd_hid.c中找到函數(shù)static int8_t USBD_HID_DataOut (USBD_HandleTypeDef *pdev, uint8_t epnum)。這個(gè)函數(shù)在OUT端點(diǎn)有數(shù)據(jù)到達(dá)時(shí)被調(diào)用。修改它static int8_t USBD_HID_DataOut (USBD_HandleTypeDef *pdev, uint8_t epnum) { /* Get the received data length */ uint32_t recv_len USBD_LL_GetRxDataSize(pdev, epnum); if(recv_len 4) // 確保長(zhǎng)度符合預(yù)期 { /* Copy data to user buffer */ // 這里假設(shè)pdev-pClassData指向HID句柄我們需要獲取接收緩沖區(qū)地址。 // 更直接的方式是HAL庫(kù)的HID類將接收到的數(shù)據(jù)放在一個(gè)內(nèi)部結(jié)構(gòu)體中。 // 查看USBD_HID_HandleTypeDef結(jié)構(gòu)體定義在usbd_hid.h它有一個(gè)成員uint8_t Report_buf[USBD_HID_REPORT_MAX_SIZE]。 // 實(shí)際上數(shù)據(jù)已經(jīng)在這個(gè)緩沖區(qū)里了。我們需要從類句柄中獲取它。 USBD_HID_HandleTypeDef *hhid (USBD_HID_HandleTypeDef *)pdev-pClassData; if(hhid ! NULL) { memcpy(UserRxBufferFS, hhid-Report_buf, recv_len); UserRxReady 1; // 設(shè)置標(biāo)志位 } } /* Prepare next OUT transfer */ // 這句很關(guān)鍵它重新啟動(dòng)OUT端點(diǎn)的接收等待主機(jī)下一次發(fā)送數(shù)據(jù)。 USBD_LL_PrepareReceive(pdev, HID_EPOUT_ADDR, hhid-Report_buf, USBD_HID_REPORT_MAX_SIZE); return USBD_OK; }實(shí)操心得USBD_LL_PrepareReceive這個(gè)調(diào)用至關(guān)重要。USB通信是主機(jī)主導(dǎo)的輪詢機(jī)制。設(shè)備在接收到一次數(shù)據(jù)后必須明確告知底層驅(qū)動(dòng)“我準(zhǔn)備好接收下一次數(shù)據(jù)了”否則主機(jī)后續(xù)發(fā)送的數(shù)據(jù)將無法被接收導(dǎo)致通信中斷。這是很多USB通信“只能收一次”問題的根源。步驟三在應(yīng)用中發(fā)送和接收數(shù)據(jù)現(xiàn)在你可以在主循環(huán)或中斷服務(wù)程序中輕松地處理USB數(shù)據(jù)了。發(fā)送數(shù)據(jù)到PCuint8_t sensor_report[4] {0xAA, 0xBB, 0xCC, 0xDD}; // 模擬傳感器數(shù)據(jù) if(USBD_HID_SendReport(hUsbDeviceFS, sensor_report, 4) ! USBD_OK) { // 處理發(fā)送錯(cuò)誤 } // 注意此函數(shù)是非阻塞的。它把數(shù)據(jù)放入發(fā)送FIFO后立即返回。 // 實(shí)際發(fā)送由USB中斷在后臺(tái)完成。接收并處理數(shù)據(jù)來自PCwhile (1) { /* USER CODE END WHILE */ if(UserRxReady) { UserRxReady 0; // 清除標(biāo)志 // 處理UserRxBufferFS中的數(shù)據(jù) // 例如控制一個(gè)LED if(UserRxBufferFS[0] 0x01) { HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, GPIO_PIN_SET); } else { HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, GPIO_PIN_RESET); } } /* USER CODE BEGIN 3 */ }3.4 上位機(jī)測(cè)試使用Python或Bus Hound設(shè)備端代碼寫好了如何測(cè)試你需要一個(gè)上位機(jī)程序。簡(jiǎn)單測(cè)試Bus Hound這是一個(gè)強(qiáng)大的USB協(xié)議分析工具。插上你的設(shè)備在Bus Hound中選擇對(duì)應(yīng)的USB設(shè)備就能看到所有USB通信的原始數(shù)據(jù)包包括描述符請(qǐng)求、SETUP事務(wù)、IN/OUT數(shù)據(jù)。你可以用它來驗(yàn)證設(shè)備枚舉是否成功以及報(bào)告描述符是否正確。發(fā)送數(shù)據(jù)測(cè)試則需要編寫上位機(jī)。Python上位機(jī)推薦使用pywinusbWindows或hidapi跨平臺(tái)庫(kù)可以非常方便地與HID設(shè)備通信。import hid # 需要安裝 pip install hidapi # 根據(jù)你的VID/PID打開設(shè)備 VID 0x0483 PID 0x5740 device hid.device() device.open(VID, PID) # 打開設(shè)備 # 發(fā)送數(shù)據(jù)輸出報(bào)告 data_to_send [0x00, 0x01, 0x02, 0x03] # 第一個(gè)字節(jié)通常是報(bào)告ID我們沒定義報(bào)告ID所以從0開始或忽略 device.write(data_to_send) # 接收數(shù)據(jù)輸入報(bào)告 data_received device.read(4) # 讀取4個(gè)字節(jié) print(fReceived: {data_received}) device.close()運(yùn)行這個(gè)Python腳本你就能實(shí)現(xiàn)PC與STM32的雙向通信了。4. 進(jìn)階實(shí)現(xiàn)USB虛擬串口CDCHID適合小數(shù)據(jù)量、實(shí)時(shí)性要求高的場(chǎng)景。如果你需要兼容傳統(tǒng)的串口調(diào)試工具如Putty、串口助手或者傳輸?shù)臄?shù)據(jù)流更像文件那么USB虛擬串口CDC類是更好的選擇。CDC設(shè)備在主機(jī)上會(huì)顯示為一個(gè)COM口所有現(xiàn)有的串口軟件都能直接使用。4.1 CubeMX配置CDC配置過程與HID類似但在Middleware中選擇Communication Device Class (Virtual Port Com)。CubeMX會(huì)自動(dòng)幫你生成一個(gè)功能完整的虛擬串口設(shè)備代碼包括printf重定向到USB的代碼usbd_cdc_if.c中的CDC_Transmit_FS。關(guān)鍵的回調(diào)函數(shù)在usbd_cdc_if.c中static int8_t CDC_Control_FS(uint8_t cmd, uint8_t* pbuf, uint16_t length)處理CDC特定控制請(qǐng)求如設(shè)置串口波特率雖然USB通信本身與波特率無關(guān)但這是為了兼容上位機(jī)設(shè)置。static int8_t CDC_Receive_FS(uint8_t* Buf, uint32_t *Len)這是最重要的回調(diào)。當(dāng)主機(jī)通過虛擬串口發(fā)送數(shù)據(jù)下來時(shí)這個(gè)函數(shù)被調(diào)用。Buf是數(shù)據(jù)指針Len是數(shù)據(jù)長(zhǎng)度。你需要在這里處理接收到的數(shù)據(jù)。uint8_t CDC_Transmit_FS(uint8_t* Buf, uint16_t Len)發(fā)送數(shù)據(jù)到主機(jī)。你可以直接調(diào)用它就像調(diào)用HAL_UART_Transmit一樣。4.2 CDC使用注意事項(xiàng)與性能調(diào)優(yōu)緩沖區(qū)與阻塞CDC_Transmit_FS函數(shù)內(nèi)部有一個(gè)發(fā)送緩沖區(qū)。如果上一次的數(shù)據(jù)還沒發(fā)送完再次調(diào)用可能會(huì)返回USBD_BUSY。好的做法是實(shí)現(xiàn)一個(gè)簡(jiǎn)單的發(fā)送狀態(tài)機(jī)或隊(duì)列而不是盲目重試或死等。// 示例非阻塞發(fā)送檢查 if(CDC_Transmit_FS(tx_buffer, length) USBD_OK) { // 發(fā)送成功啟動(dòng) } else { // 發(fā)送忙將數(shù)據(jù)存入應(yīng)用層隊(duì)列稍后重試 }接收速率匹配在CDC_Receive_FS回調(diào)中處理數(shù)據(jù)要快。如果你在這里進(jìn)行復(fù)雜的運(yùn)算或阻塞操作可能會(huì)導(dǎo)致USB端點(diǎn)緩沖區(qū)滿造成數(shù)據(jù)丟失。最佳實(shí)踐是在這個(gè)回調(diào)里只做最少的操作比如將數(shù)據(jù)拷貝到一個(gè)環(huán)形緩沖區(qū)然后設(shè)置一個(gè)標(biāo)志在主循環(huán)中處理這個(gè)環(huán)形緩沖區(qū)里的數(shù)據(jù)。大流量傳輸對(duì)于高速連續(xù)數(shù)據(jù)流如音頻要確保端點(diǎn)的最大包大小wMaxPacketSize設(shè)置得足夠大全速USB最大64字節(jié)高速USB最大512字節(jié)并合理使用多個(gè)IN端點(diǎn)進(jìn)行同步傳輸以提高吞吐量。5. 常見問題排查與調(diào)試心得實(shí)錄玩USB沒有不踩坑的。下面是我和很多同行在實(shí)踐中總結(jié)出來的“血淚史”。5.1 設(shè)備無法識(shí)別或枚舉失敗這是最常見的問題現(xiàn)象是插上USB線電腦沒反應(yīng)或者提示“未知設(shè)備”。檢查清單硬件連接DM/DP線是否接反是否接了上拉電阻1.5kΩ接DP到3.3V對(duì)于全速設(shè)備這是必須的很多開發(fā)板已經(jīng)集成自制板子容易忽略。電源USB的5V電源是否穩(wěn)定STM32的3.3V供電是否正?？梢杂萌f用表測(cè)量。時(shí)鐘配置重中之重用CubeMX的時(shí)鐘圖反復(fù)核對(duì)USB時(shí)鐘必須是精確的48MHz。使用外部晶振時(shí)檢查PLL倍頻分頻設(shè)置?？梢允褂肧ystemCoreClock變量打印系統(tǒng)主頻并用邏輯分析儀或示波器測(cè)量PA8MCO輸出的時(shí)鐘來間接驗(yàn)證。描述符錯(cuò)誤描述符數(shù)據(jù)結(jié)構(gòu)有誤比如長(zhǎng)度字段寫錯(cuò)、描述符順序不對(duì)、總數(shù)不匹配。使用USBlyzer或Wireshark配合USBPcap驅(qū)動(dòng)抓取USB枚舉過程的通信包對(duì)比標(biāo)準(zhǔn)請(qǐng)求和設(shè)備的回應(yīng)能精準(zhǔn)定位問題所在。例如主機(jī)發(fā)送Get_Descriptor(Device)請(qǐng)求你回應(yīng)的設(shè)備描述符第8個(gè)字節(jié)bMaxPacketSize0應(yīng)該是64如果你填了0就會(huì)導(dǎo)致枚舉失敗。堆棧大小USB中斷服務(wù)程序以及HAL庫(kù)的中間件需要一定的?？臻g。如果Stack_Size在啟動(dòng)文件或IDE的鏈接器配置中設(shè)置得太小比如默認(rèn)的0x400可能在枚舉過程中發(fā)生棧溢出導(dǎo)致程序跑飛。建議將棧大小至少設(shè)置為0x800或更大。5.2 通信不穩(wěn)定時(shí)斷時(shí)續(xù)或數(shù)據(jù)錯(cuò)誤問題能識(shí)別但傳輸數(shù)據(jù)時(shí)偶爾丟失或者上位機(jī)收到亂碼。排查端點(diǎn)緩沖區(qū)溢出檢查你的發(fā)送代碼。是否在上一次USBD_HID_SendReport或CDC_Transmit_FS還沒完成返回USBD_BUSY時(shí)就強(qiáng)行發(fā)送了新數(shù)據(jù)必須等待發(fā)送完成或?qū)崿F(xiàn)發(fā)送隊(duì)列。接收未重啟對(duì)于OUT傳輸你是否在每次接收回調(diào)USBD_HID_DataOut或CDC_Receive_FS的最后調(diào)用了USBD_LL_PrepareReceive來重新使能接收如果沒有設(shè)備只會(huì)在第一次接收數(shù)據(jù)。數(shù)據(jù)對(duì)齊與長(zhǎng)度確保你發(fā)送的數(shù)據(jù)長(zhǎng)度嚴(yán)格等于報(bào)告描述符中定義的報(bào)告長(zhǎng)度。對(duì)于CDC也要注意單次發(fā)送的數(shù)據(jù)不要超過端點(diǎn)最大包大小。中斷優(yōu)先級(jí)USB中斷如OTG_FS_IRQn應(yīng)該有較高的優(yōu)先級(jí)避免被其他長(zhǎng)時(shí)間的中斷如某些定時(shí)器中斷阻塞導(dǎo)致數(shù)據(jù)無法及時(shí)處理而丟失。在CubeMX的NVIC配置中調(diào)整。電源噪聲如果電路板上有電機(jī)、繼電器等大功率器件可能會(huì)干擾USB通信的差分信號(hào)。確保電源去耦良好USB數(shù)據(jù)線走線盡量短且等長(zhǎng)必要時(shí)在DM/DP線上串聯(lián)小電阻22Ω并并聯(lián)對(duì)地電容如15pF進(jìn)行阻抗匹配和濾波。5.3 從標(biāo)準(zhǔn)庫(kù)移植到HAL庫(kù)的注意事項(xiàng)很多老項(xiàng)目用的是標(biāo)準(zhǔn)庫(kù)遷移到HAL庫(kù)時(shí)USB部分幾乎是重寫。架構(gòu)差異標(biāo)準(zhǔn)庫(kù)的USB驅(qū)動(dòng)更“裸”你需要手動(dòng)處理更多底層細(xì)節(jié)。HAL庫(kù)封裝得更好但抽象層次更高理解其回調(diào)機(jī)制是關(guān)鍵。描述符定義兩者描述符的結(jié)構(gòu)體定義可能略有不同但內(nèi)容本質(zhì)一樣。需要將舊描述符數(shù)組按照HAL庫(kù)示例的格式移植過來?；卣{(diào)函數(shù)名標(biāo)準(zhǔn)庫(kù)的回調(diào)函數(shù)名如EP1_IN_Callback與HAL庫(kù)的如HAL_PCD_DataInCallback完全不同。需要仔細(xì)閱讀HAL庫(kù)的USB文檔將業(yè)務(wù)邏輯移植到正確的新回調(diào)函數(shù)中。工具鏈確保你的HAL庫(kù)版本與STM32CubeMX版本、芯片支持包DFP版本兼容。不匹配的版本是很多詭異問題的源頭。調(diào)試USB一個(gè)好的習(xí)慣是充分利用LED和串口如果還有其他串口的話進(jìn)行狀態(tài)指示。比如在HAL_PCD_ConnectCallback設(shè)備連接和HAL_PCD_DisconnectCallback設(shè)備斷開中翻轉(zhuǎn)一個(gè)LED在描述符請(qǐng)求回調(diào)中打印日志能讓你快速了解設(shè)備枚舉到了哪一步。當(dāng)硬件工具不足時(shí)這種“土法調(diào)試”往往最有效。 STM32 HAL庫(kù)USB開發(fā)實(shí)戰(zhàn)：從HID到CDC虛擬串口
1. 項(xiàng)目概述為什么STM32的USB開發(fā)值得深究如果你玩過STM32大概率用過串口打印調(diào)試信息或者通過串口和上位機(jī)通信。但當(dāng)你需要高速、穩(wěn)定地傳輸大量數(shù)據(jù)時(shí)比如傳輸攝像頭圖像、音頻流或者想做一個(gè)看起來更專業(yè)的設(shè)備插上USB線就能識(shí)別為一個(gè)特定設(shè)備而不是一個(gè)串口USB就成了繞不開的話題。而HAL庫(kù)作為ST官方主推的硬件抽象層它把USB這個(gè)復(fù)雜的協(xié)議棧封裝起來讓我們這些應(yīng)用開發(fā)者能更專注于業(yè)務(wù)邏輯而不是去死磕USB協(xié)議手冊(cè)里那些令人頭禿的細(xì)節(jié)。我最初接觸STM32的USB是想做一個(gè)自定義的HID人機(jī)接口設(shè)備控制器用來傳輸游戲搖桿的數(shù)據(jù)。當(dāng)時(shí)在標(biāo)準(zhǔn)庫(kù)和HAL庫(kù)之間糾結(jié)了很久最終還是選擇了HAL庫(kù)。原因很簡(jiǎn)單ST未來的新芯片幾乎只提供HAL庫(kù)支持生態(tài)在往這邊遷移而且HAL庫(kù)的結(jié)構(gòu)更統(tǒng)一雖然初期覺得有些“臃腫”但熟悉之后移植和跨項(xiàng)目復(fù)用代碼的效率高得多。這個(gè)項(xiàng)目標(biāo)題“STM32 HAL庫(kù)之USB”聽起來像是一個(gè)技術(shù)模塊但背后實(shí)際是一整套從硬件連接、協(xié)議棧配置、到驅(qū)動(dòng)編寫和上位機(jī)聯(lián)調(diào)的完整工程實(shí)踐。它解決的不僅僅是“通信”問題更是如何讓一個(gè)嵌入式設(shè)備以更標(biāo)準(zhǔn)、更高效的方式融入現(xiàn)代計(jì)算機(jī)體系的問題。2. 核心思路與框架設(shè)計(jì)HAL庫(kù)如何“抽象”USB很多新手拿到STM32CubeMX生成的一大堆USB代碼會(huì)感到迷茫感覺像在看天書。要理清頭緒關(guān)鍵在于理解HAL庫(kù)為USB設(shè)計(jì)的分層架構(gòu)。它不是一坨不可分割的代碼而是一個(gè)精心設(shè)計(jì)的“洋蔥”每一層都有明確的職責(zé)。2.1 HAL庫(kù)USB驅(qū)動(dòng)框架的三層模型我們可以把HAL庫(kù)的USB支持分為三層從下到上依次是硬件抽象層HAL/PLL Driver這是最底層直接操作STM32內(nèi)部的USB外設(shè)寄存器。它負(fù)責(zé)處理最基礎(chǔ)的USB電氣信號(hào)、端點(diǎn)緩沖區(qū)管理、中斷觸發(fā)等。這部分代碼通常是stm32f4xx_hal_pcd.c/.h對(duì)于設(shè)備模式或stm32f4xx_hal_hcd.c/.h對(duì)于主機(jī)模式。作為應(yīng)用開發(fā)者我們幾乎不直接調(diào)用這一層的函數(shù)HAL庫(kù)已經(jīng)幫我們封裝好了。USB設(shè)備協(xié)議棧層USB Device/Core Library這是核心層實(shí)現(xiàn)了USB 2.0規(guī)范中設(shè)備端的基本協(xié)議。它管理設(shè)備描述符告訴主機(jī)“我是什么”、處理標(biāo)準(zhǔn)的設(shè)備請(qǐng)求如獲取描述符、設(shè)置地址、設(shè)置配置、管理各個(gè)端點(diǎn)的數(shù)據(jù)流狀態(tài)。這一層的代碼位于Middlewares/ST/STM32_USB_Device_Library/目錄下。它提供了一套回調(diào)函數(shù)接口我們需要填充這些回調(diào)函數(shù)來定義設(shè)備的行為。USB設(shè)備類層USB Device Class這是應(yīng)用層基于協(xié)議棧層實(shí)現(xiàn)具體的USB設(shè)備類別功能。比如你想做一個(gè)USB虛擬串口CDC類就使用CDC類庫(kù)想做一個(gè)人機(jī)接口設(shè)備HID如鍵盤、鼠標(biāo)就使用HID類庫(kù)想實(shí)現(xiàn)大容量存儲(chǔ)MSC模擬一個(gè)U盤就使用MSC類庫(kù)。ST提供了這些常用類的實(shí)現(xiàn)模板位于Middlewares/ST/STM32_USB_Device_Library/Class/目錄下。我們的主要工作就是基于某個(gè)類模板進(jìn)行修改和適配。為什么這樣設(shè)計(jì)這種分層最大的好處是解耦和復(fù)用。協(xié)議棧層是通用的不管你做鍵盤還是U盤處理標(biāo)準(zhǔn)請(qǐng)求的邏輯都一樣。類層是可選的你可以用ST提供的也可以自己實(shí)現(xiàn)一個(gè)自定義類。而我們的應(yīng)用代碼只需要關(guān)心“數(shù)據(jù)來了怎么處理”和“數(shù)據(jù)怎么發(fā)出去”無需關(guān)心底層數(shù)據(jù)包是如何被拆解、CRC校驗(yàn)、發(fā)送的。這極大地降低了開發(fā)門檻。2.2 關(guān)鍵概念端點(diǎn)、管道與描述符在深入代碼前必須吃透這三個(gè)概念否則配置起來就是盲人摸象。端點(diǎn)Endpoint可以理解為USB設(shè)備上的“數(shù)據(jù)收發(fā)信箱”。每個(gè)端點(diǎn)都有一個(gè)唯一的地址和方向。地址0是默認(rèn)的控制端點(diǎn)用于傳輸配置、命令等關(guān)鍵信息。其他端點(diǎn)如0x81, 0x01用于傳輸應(yīng)用數(shù)據(jù)。IN端點(diǎn)設(shè)備到主機(jī)和OUT端點(diǎn)主機(jī)到設(shè)備通常是成對(duì)出現(xiàn)的。管道Pipe邏輯上的數(shù)據(jù)傳輸通道建立在主機(jī)和設(shè)備上的某個(gè)端點(diǎn)之間。你可以把它想象成連接主機(jī)和端點(diǎn)“信箱”的“郵路”。描述符Descriptor一組定義設(shè)備屬性、能力和配置的數(shù)據(jù)結(jié)構(gòu)。它是USB設(shè)備的“身份證”和“說明書”。主機(jī)在枚舉設(shè)備時(shí)會(huì)一步步讀取這些描述符從而知道該如何與設(shè)備通信。主要描述符包括設(shè)備描述符描述設(shè)備的總體信息如廠商IDVID、產(chǎn)品IDPID、設(shè)備版本、支持的配置數(shù)量等。配置描述符描述設(shè)備的一種工作模式如高功耗模式、低功耗模式包括接口數(shù)量、最大功耗等。接口描述符描述設(shè)備提供的一種功能。一個(gè)配置可以包含多個(gè)接口。例如一個(gè)帶音頻功能的USB攝像頭可能有視頻捕獲接口和音頻流接口。端點(diǎn)描述符描述某個(gè)端點(diǎn)的屬性如端點(diǎn)地址、方向、傳輸類型控制、中斷、批量、同步、最大包大小等。字符串描述符可選的提供人類可讀的設(shè)備名稱、廠商字符串等。在HAL庫(kù)項(xiàng)目中這些描述符通常以常量數(shù)組的形式定義在一個(gè)獨(dú)立的文件如usbd_desc.c中。通過STM32CubeMX配置USB設(shè)備時(shí)它會(huì)自動(dòng)生成這些描述符的框架我們只需要修改里面的VID、PID、字符串等關(guān)鍵信息即可。注意VID/PID非常重要。如果只是個(gè)人學(xué)習(xí)可以使用ST的測(cè)試ID如VID0x0483 PID0x5740。但如果產(chǎn)品要上市必須向USB-IF申請(qǐng)屬于自己的VID并為每個(gè)產(chǎn)品分配唯一的PID否則可能會(huì)與系統(tǒng)已有的設(shè)備沖突導(dǎo)致無法識(shí)別。3. 從零構(gòu)建一個(gè)USB HID設(shè)備以自定義報(bào)告設(shè)備為例理論講得再多不如動(dòng)手做一遍。我們以創(chuàng)建一個(gè)自定義的USB HID設(shè)備為例它不模擬鍵盤鼠標(biāo)而是傳輸我們自定義格式的數(shù)據(jù)比如傳感器數(shù)據(jù)包。這種設(shè)備在需要PC軟件與STM32進(jìn)行實(shí)時(shí)、雙向、小數(shù)據(jù)量通信的場(chǎng)景下非常有用因?yàn)镠ID類設(shè)備的驅(qū)動(dòng)在Windows、macOS、Linux上都是系統(tǒng)自帶的無需額外安裝驅(qū)動(dòng)。3.1 環(huán)境準(zhǔn)備與CubeMX工程配置首先確保你有一個(gè)支持USB Device功能的STM32開發(fā)板如STM32F103、F407、F429等并且板載了USB Micro-B或Type-C接口或者你通過跳線正確連接了USB的DM/DP線到芯片對(duì)應(yīng)引腳。啟動(dòng)STM32CubeMX選擇你的芯片型號(hào)。配置時(shí)鐘樹USB模塊需要精確的48MHz時(shí)鐘。對(duì)于STM32F4系列通常由主PLL分頻得到。在Clock Configuration標(biāo)簽頁確保USB OTG FS或USB OTG HS取決于你使用的USB接口的時(shí)鐘源被正確配置為48MHz。這是最容易出錯(cuò)的一步時(shí)鐘不對(duì)USB根本無法工作。使能USB外設(shè)在Pinout Configuration標(biāo)簽頁找到Connectivity-USB_OTG_FS以全速USB為例。將Mode設(shè)置為Device_Only。此時(shí)對(duì)應(yīng)的USB DMPA11和 DPPA12引腳會(huì)被自動(dòng)分配。配置USB中間件切換到Middleware區(qū)域激活USB_DEVICE。在Class For FS IP下拉菜單中選擇Human Interface Device Class (HID)。配置HID參數(shù)在Configuration標(biāo)簽頁下找到USB_DEVICE-HID。這里需要設(shè)置HID Report Descriptor。報(bào)告描述符是HID設(shè)備的核心它定義了設(shè)備上報(bào)的數(shù)據(jù)格式。對(duì)于初學(xué)者可以先使用一個(gè)簡(jiǎn)單的示例。你可以點(diǎn)擊Use custom report descriptor然后粘貼一個(gè)簡(jiǎn)單的描述符。例如下面這個(gè)描述符定義了一個(gè)包含4字節(jié)輸入報(bào)告和4字節(jié)輸出報(bào)告的設(shè)備__ALIGN_BEGIN static uint8_t HID_CUSTOM_ReportDesc[] __ALIGN_END { 0x06, 0x00, 0xFF, // Usage Page (Vendor Defined 0xFF00) 0x09, 0x01, // Usage (0x01) 0xA1, 0x01, // Collection (Application) 0x15, 0x00, // Logical Minimum (0) 0x26, 0xFF, 0x00, // Logical Maximum (255) 0x75, 0x08, // Report Size (8 bits) 0x95, 0x04, // Report Count (4) 0x09, 0x01, // Usage (0x01) 0x81, 0x02, // Input (Data, Var, Abs) - 4字節(jié)輸入報(bào)告 0x09, 0x01, // Usage (0x01) 0x91, 0x02, // Output (Data, Var, Abs) - 4字節(jié)輸出報(bào)告 0xC0 // End Collection };設(shè)置HID Polling Interval為10即10ms這是主機(jī)輪詢?cè)O(shè)備獲取輸入報(bào)告的間隔。生成工程設(shè)置好你的IDEKeil、IAR、STM32CubeIDE和工程名生成代碼。3.2 剖析生成的代碼結(jié)構(gòu)與關(guān)鍵回調(diào)函數(shù)CubeMX生成的代碼結(jié)構(gòu)非常清晰。我們重點(diǎn)關(guān)注以下幾個(gè)文件Core/Inc/usbd_conf.h和Core/Src/usbd_conf.cUSB設(shè)備底層配置如端點(diǎn)緩沖區(qū)大小、內(nèi)存管理函數(shù)等。一般無需修改。Core/Inc/usbd_desc.h和Core/Src/usbd_desc.c設(shè)備描述符定義。你需要在這里修改USBD_VID、USBD_PID、USBD_PRODUCT_STRING等。USB_DEVICE/App/usbd_hid.c和USB_DEVICE/App/usbd_hid.hHID類應(yīng)用層代碼的核心。我們需要修改的就是這里。打開usbd_hid.c找到幾個(gè)關(guān)鍵的回調(diào)函數(shù)static int8_t HID_Init_FS(void)HID設(shè)備初始化函數(shù)。在這里你可以初始化你的應(yīng)用相關(guān)變量。static int8_t HID_DeInit_FS(void)反初始化函數(shù)。static int8_t HID_OutEvent_FS(uint8_t event_idx, uint8_t state)這個(gè)函數(shù)在HID類模板中可能不存在。實(shí)際上對(duì)于自定義HID接收主機(jī)發(fā)來的數(shù)據(jù)輸出報(bào)告通常是通過另一個(gè)機(jī)制。ST的HID類庫(kù)提供了一個(gè)函數(shù)USBD_HID_ReceivePacket來啟動(dòng)接收并在接收到數(shù)據(jù)后會(huì)調(diào)用一個(gè)名為HID_OutEvent_FS的回調(diào)如果實(shí)現(xiàn)的話或者更常見的是我們需要在應(yīng)用層主動(dòng)輪詢或在一個(gè)全局回調(diào)里處理。這是一個(gè)常見的困惑點(diǎn)。 更標(biāo)準(zhǔn)的做法是在main.c或你的應(yīng)用文件中調(diào)用USBD_HID_SendReport發(fā)送數(shù)據(jù)并處理接收。接收數(shù)據(jù)通常通過端點(diǎn)OUT中斷回調(diào)來處理。但HAL庫(kù)的HID類已經(jīng)封裝了這部分。查看usbd_hid.c你會(huì)發(fā)現(xiàn)一個(gè)函數(shù)static int8_t USBD_HID_Setup (USBD_HandleTypeDef *pdev, USBD_SetupReqTypedef *req)它處理HID特定的SETUP請(qǐng)求。對(duì)于OUT數(shù)據(jù)數(shù)據(jù)會(huì)被接收到類庫(kù)內(nèi)部的一個(gè)緩沖區(qū)。因此我們的主要任務(wù)變?yōu)榘l(fā)送數(shù)據(jù)設(shè)備-主機(jī)在需要的時(shí)候例如定時(shí)器中斷、傳感器數(shù)據(jù)準(zhǔn)備好時(shí)調(diào)用USBD_HID_SendReport(hUsbDeviceFS, report_buf, report_size)。其中report_buf是你的數(shù)據(jù)緩沖區(qū)report_size必須與報(bào)告描述符中定義的輸入報(bào)告大小一致本例中為4。接收數(shù)據(jù)主機(jī)-設(shè)備主機(jī)發(fā)送的輸出報(bào)告數(shù)據(jù)會(huì)存放在HID類庫(kù)內(nèi)部。我們需要周期性地檢查或在一個(gè)回調(diào)中處理。一個(gè)簡(jiǎn)單可靠的方法是在main函數(shù)的while(1)循環(huán)中調(diào)用一個(gè)處理函數(shù)來檢查是否有新數(shù)據(jù)。但更優(yōu)雅的方式是利用HAL庫(kù)提供的機(jī)制。實(shí)際上在usbd_hid.c中有一個(gè)函數(shù)USBD_HID_DataOut它在OUT端點(diǎn)接收到數(shù)據(jù)后被底層調(diào)用。我們可以修改這個(gè)函數(shù)將接收到的數(shù)據(jù)拷貝到我們的應(yīng)用緩沖區(qū)并設(shè)置一個(gè)標(biāo)志位。3.3 實(shí)現(xiàn)自定義數(shù)據(jù)收發(fā)修改HID類模板讓我們動(dòng)手修改實(shí)現(xiàn)一個(gè)明確的收發(fā)機(jī)制。步驟一定義應(yīng)用緩沖區(qū)在usbd_hid.h中添加以下外部變量聲明/* USER CODE BEGIN EXPORTED_VARIABLES */ extern uint8_t UserRxBufferFS[4]; // 接收緩沖區(qū)大小與輸出報(bào)告一致 extern volatile uint8_t UserRxReady; // 接收完成標(biāo)志 /* USER CODE END EXPORTED_VARIABLES */在usbd_hid.c文件頂部定義這些變量/* USER CODE BEGIN PV */ uint8_t UserRxBufferFS[4] {0}; volatile uint8_t UserRxReady 0; /* USER CODE END PV */步驟二修改數(shù)據(jù)接收回調(diào)在usbd_hid.c中找到函數(shù)static int8_t USBD_HID_DataOut (USBD_HandleTypeDef *pdev, uint8_t epnum)。這個(gè)函數(shù)在OUT端點(diǎn)有數(shù)據(jù)到達(dá)時(shí)被調(diào)用。修改它static int8_t USBD_HID_DataOut (USBD_HandleTypeDef *pdev, uint8_t epnum) { /* Get the received data length */ uint32_t recv_len USBD_LL_GetRxDataSize(pdev, epnum); if(recv_len 4) // 確保長(zhǎng)度符合預(yù)期 { /* Copy data to user buffer */ // 這里假設(shè)pdev-pClassData指向HID句柄我們需要獲取接收緩沖區(qū)地址。 // 更直接的方式是HAL庫(kù)的HID類將接收到的數(shù)據(jù)放在一個(gè)內(nèi)部結(jié)構(gòu)體中。 // 查看USBD_HID_HandleTypeDef結(jié)構(gòu)體定義在usbd_hid.h它有一個(gè)成員uint8_t Report_buf[USBD_HID_REPORT_MAX_SIZE]。 // 實(shí)際上數(shù)據(jù)已經(jīng)在這個(gè)緩沖區(qū)里了。我們需要從類句柄中獲取它。 USBD_HID_HandleTypeDef *hhid (USBD_HID_HandleTypeDef *)pdev-pClassData; if(hhid ! NULL) { memcpy(UserRxBufferFS, hhid-Report_buf, recv_len); UserRxReady 1; // 設(shè)置標(biāo)志位 } } /* Prepare next OUT transfer */ // 這句很關(guān)鍵它重新啟動(dòng)OUT端點(diǎn)的接收等待主機(jī)下一次發(fā)送數(shù)據(jù)。 USBD_LL_PrepareReceive(pdev, HID_EPOUT_ADDR, hhid-Report_buf, USBD_HID_REPORT_MAX_SIZE); return USBD_OK; }實(shí)操心得USBD_LL_PrepareReceive這個(gè)調(diào)用至關(guān)重要。USB通信是主機(jī)主導(dǎo)的輪詢機(jī)制。設(shè)備在接收到一次數(shù)據(jù)后必須明確告知底層驅(qū)動(dòng)“我準(zhǔn)備好接收下一次數(shù)據(jù)了”否則主機(jī)后續(xù)發(fā)送的數(shù)據(jù)將無法被接收導(dǎo)致通信中斷。這是很多USB通信“只能收一次”問題的根源。步驟三在應(yīng)用中發(fā)送和接收數(shù)據(jù)現(xiàn)在你可以在主循環(huán)或中斷服務(wù)程序中輕松地處理USB數(shù)據(jù)了。發(fā)送數(shù)據(jù)到PCuint8_t sensor_report[4] {0xAA, 0xBB, 0xCC, 0xDD}; // 模擬傳感器數(shù)據(jù) if(USBD_HID_SendReport(hUsbDeviceFS, sensor_report, 4) ! USBD_OK) { // 處理發(fā)送錯(cuò)誤 } // 注意此函數(shù)是非阻塞的。它把數(shù)據(jù)放入發(fā)送FIFO后立即返回。 // 實(shí)際發(fā)送由USB中斷在后臺(tái)完成。接收并處理數(shù)據(jù)來自PCwhile (1) { /* USER CODE END WHILE */ if(UserRxReady) { UserRxReady 0; // 清除標(biāo)志 // 處理UserRxBufferFS中的數(shù)據(jù) // 例如控制一個(gè)LED if(UserRxBufferFS[0] 0x01) { HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, GPIO_PIN_SET); } else { HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, GPIO_PIN_RESET); } } /* USER CODE BEGIN 3 */ }3.4 上位機(jī)測(cè)試使用Python或Bus Hound設(shè)備端代碼寫好了如何測(cè)試你需要一個(gè)上位機(jī)程序。簡(jiǎn)單測(cè)試Bus Hound這是一個(gè)強(qiáng)大的USB協(xié)議分析工具。插上你的設(shè)備在Bus Hound中選擇對(duì)應(yīng)的USB設(shè)備就能看到所有USB通信的原始數(shù)據(jù)包包括描述符請(qǐng)求、SETUP事務(wù)、IN/OUT數(shù)據(jù)。你可以用它來驗(yàn)證設(shè)備枚舉是否成功以及報(bào)告描述符是否正確。發(fā)送數(shù)據(jù)測(cè)試則需要編寫上位機(jī)。Python上位機(jī)推薦使用pywinusbWindows或hidapi跨平臺(tái)庫(kù)可以非常方便地與HID設(shè)備通信。import hid # 需要安裝 pip install hidapi # 根據(jù)你的VID/PID打開設(shè)備 VID 0x0483 PID 0x5740 device hid.device() device.open(VID, PID) # 打開設(shè)備 # 發(fā)送數(shù)據(jù)輸出報(bào)告 data_to_send [0x00, 0x01, 0x02, 0x03] # 第一個(gè)字節(jié)通常是報(bào)告ID我們沒定義報(bào)告ID所以從0開始或忽略 device.write(data_to_send) # 接收數(shù)據(jù)輸入報(bào)告 data_received device.read(4) # 讀取4個(gè)字節(jié) print(fReceived: {data_received}) device.close()運(yùn)行這個(gè)Python腳本你就能實(shí)現(xiàn)PC與STM32的雙向通信了。4. 進(jìn)階實(shí)現(xiàn)USB虛擬串口CDCHID適合小數(shù)據(jù)量、實(shí)時(shí)性要求高的場(chǎng)景。如果你需要兼容傳統(tǒng)的串口調(diào)試工具如Putty、串口助手或者傳輸?shù)臄?shù)據(jù)流更像文件那么USB虛擬串口CDC類是更好的選擇。CDC設(shè)備在主機(jī)上會(huì)顯示為一個(gè)COM口所有現(xiàn)有的串口軟件都能直接使用。4.1 CubeMX配置CDC配置過程與HID類似但在Middleware中選擇Communication Device Class (Virtual Port Com)。CubeMX會(huì)自動(dòng)幫你生成一個(gè)功能完整的虛擬串口設(shè)備代碼包括printf重定向到USB的代碼usbd_cdc_if.c中的CDC_Transmit_FS。關(guān)鍵的回調(diào)函數(shù)在usbd_cdc_if.c中static int8_t CDC_Control_FS(uint8_t cmd, uint8_t* pbuf, uint16_t length)處理CDC特定控制請(qǐng)求如設(shè)置串口波特率雖然USB通信本身與波特率無關(guān)但這是為了兼容上位機(jī)設(shè)置。static int8_t CDC_Receive_FS(uint8_t* Buf, uint32_t *Len)這是最重要的回調(diào)。當(dāng)主機(jī)通過虛擬串口發(fā)送數(shù)據(jù)下來時(shí)這個(gè)函數(shù)被調(diào)用。Buf是數(shù)據(jù)指針Len是數(shù)據(jù)長(zhǎng)度。你需要在這里處理接收到的數(shù)據(jù)。uint8_t CDC_Transmit_FS(uint8_t* Buf, uint16_t Len)發(fā)送數(shù)據(jù)到主機(jī)。你可以直接調(diào)用它就像調(diào)用HAL_UART_Transmit一樣。4.2 CDC使用注意事項(xiàng)與性能調(diào)優(yōu)緩沖區(qū)與阻塞CDC_Transmit_FS函數(shù)內(nèi)部有一個(gè)發(fā)送緩沖區(qū)。如果上一次的數(shù)據(jù)還沒發(fā)送完再次調(diào)用可能會(huì)返回USBD_BUSY。好的做法是實(shí)現(xiàn)一個(gè)簡(jiǎn)單的發(fā)送狀態(tài)機(jī)或隊(duì)列而不是盲目重試或死等。// 示例非阻塞發(fā)送檢查 if(CDC_Transmit_FS(tx_buffer, length) USBD_OK) { // 發(fā)送成功啟動(dòng) } else { // 發(fā)送忙將數(shù)據(jù)存入應(yīng)用層隊(duì)列稍后重試 }接收速率匹配在CDC_Receive_FS回調(diào)中處理數(shù)據(jù)要快。如果你在這里進(jìn)行復(fù)雜的運(yùn)算或阻塞操作可能會(huì)導(dǎo)致USB端點(diǎn)緩沖區(qū)滿造成數(shù)據(jù)丟失。最佳實(shí)踐是在這個(gè)回調(diào)里只做最少的操作比如將數(shù)據(jù)拷貝到一個(gè)環(huán)形緩沖區(qū)然后設(shè)置一個(gè)標(biāo)志在主循環(huán)中處理這個(gè)環(huán)形緩沖區(qū)里的數(shù)據(jù)。大流量傳輸對(duì)于高速連續(xù)數(shù)據(jù)流如音頻要確保端點(diǎn)的最大包大小wMaxPacketSize設(shè)置得足夠大全速USB最大64字節(jié)高速USB最大512字節(jié)并合理使用多個(gè)IN端點(diǎn)進(jìn)行同步傳輸以提高吞吐量。5. 常見問題排查與調(diào)試心得實(shí)錄玩USB沒有不踩坑的。下面是我和很多同行在實(shí)踐中總結(jié)出來的“血淚史”。5.1 設(shè)備無法識(shí)別或枚舉失敗這是最常見的問題現(xiàn)象是插上USB線電腦沒反應(yīng)或者提示“未知設(shè)備”。檢查清單硬件連接DM/DP線是否接反是否接了上拉電阻1.5kΩ接DP到3.3V對(duì)于全速設(shè)備這是必須的很多開發(fā)板已經(jīng)集成自制板子容易忽略。電源USB的5V電源是否穩(wěn)定STM32的3.3V供電是否正?？梢杂萌f用表測(cè)量。時(shí)鐘配置重中之重用CubeMX的時(shí)鐘圖反復(fù)核對(duì)USB時(shí)鐘必須是精確的48MHz。使用外部晶振時(shí)檢查PLL倍頻分頻設(shè)置?？梢允褂肧ystemCoreClock變量打印系統(tǒng)主頻并用邏輯分析儀或示波器測(cè)量PA8MCO輸出的時(shí)鐘來間接驗(yàn)證。描述符錯(cuò)誤描述符數(shù)據(jù)結(jié)構(gòu)有誤比如長(zhǎng)度字段寫錯(cuò)、描述符順序不對(duì)、總數(shù)不匹配。使用USBlyzer或Wireshark配合USBPcap驅(qū)動(dòng)抓取USB枚舉過程的通信包對(duì)比標(biāo)準(zhǔn)請(qǐng)求和設(shè)備的回應(yīng)能精準(zhǔn)定位問題所在。例如主機(jī)發(fā)送Get_Descriptor(Device)請(qǐng)求你回應(yīng)的設(shè)備描述符第8個(gè)字節(jié)bMaxPacketSize0應(yīng)該是64如果你填了0就會(huì)導(dǎo)致枚舉失敗。堆棧大小USB中斷服務(wù)程序以及HAL庫(kù)的中間件需要一定的?？臻g。如果Stack_Size在啟動(dòng)文件或IDE的鏈接器配置中設(shè)置得太小比如默認(rèn)的0x400可能在枚舉過程中發(fā)生棧溢出導(dǎo)致程序跑飛。建議將棧大小至少設(shè)置為0x800或更大。5.2 通信不穩(wěn)定時(shí)斷時(shí)續(xù)或數(shù)據(jù)錯(cuò)誤問題能識(shí)別但傳輸數(shù)據(jù)時(shí)偶爾丟失或者上位機(jī)收到亂碼。排查端點(diǎn)緩沖區(qū)溢出檢查你的發(fā)送代碼。是否在上一次USBD_HID_SendReport或CDC_Transmit_FS還沒完成返回USBD_BUSY時(shí)就強(qiáng)行發(fā)送了新數(shù)據(jù)必須等待發(fā)送完成或?qū)崿F(xiàn)發(fā)送隊(duì)列。接收未重啟對(duì)于OUT傳輸你是否在每次接收回調(diào)USBD_HID_DataOut或CDC_Receive_FS的最后調(diào)用了USBD_LL_PrepareReceive來重新使能接收如果沒有設(shè)備只會(huì)在第一次接收數(shù)據(jù)。數(shù)據(jù)對(duì)齊與長(zhǎng)度確保你發(fā)送的數(shù)據(jù)長(zhǎng)度嚴(yán)格等于報(bào)告描述符中定義的報(bào)告長(zhǎng)度。對(duì)于CDC也要注意單次發(fā)送的數(shù)據(jù)不要超過端點(diǎn)最大包大小。中斷優(yōu)先級(jí)USB中斷如OTG_FS_IRQn應(yīng)該有較高的優(yōu)先級(jí)避免被其他長(zhǎng)時(shí)間的中斷如某些定時(shí)器中斷阻塞導(dǎo)致數(shù)據(jù)無法及時(shí)處理而丟失。在CubeMX的NVIC配置中調(diào)整。電源噪聲如果電路板上有電機(jī)、繼電器等大功率器件可能會(huì)干擾USB通信的差分信號(hào)。確保電源去耦良好USB數(shù)據(jù)線走線盡量短且等長(zhǎng)必要時(shí)在DM/DP線上串聯(lián)小電阻22Ω并并聯(lián)對(duì)地電容如15pF進(jìn)行阻抗匹配和濾波。5.3 從標(biāo)準(zhǔn)庫(kù)移植到HAL庫(kù)的注意事項(xiàng)很多老項(xiàng)目用的是標(biāo)準(zhǔn)庫(kù)遷移到HAL庫(kù)時(shí)USB部分幾乎是重寫。架構(gòu)差異標(biāo)準(zhǔn)庫(kù)的USB驅(qū)動(dòng)更“裸”你需要手動(dòng)處理更多底層細(xì)節(jié)。HAL庫(kù)封裝得更好但抽象層次更高理解其回調(diào)機(jī)制是關(guān)鍵。描述符定義兩者描述符的結(jié)構(gòu)體定義可能略有不同但內(nèi)容本質(zhì)一樣。需要將舊描述符數(shù)組按照HAL庫(kù)示例的格式移植過來?；卣{(diào)函數(shù)名標(biāo)準(zhǔn)庫(kù)的回調(diào)函數(shù)名如EP1_IN_Callback與HAL庫(kù)的如HAL_PCD_DataInCallback完全不同。需要仔細(xì)閱讀HAL庫(kù)的USB文檔將業(yè)務(wù)邏輯移植到正確的新回調(diào)函數(shù)中。工具鏈確保你的HAL庫(kù)版本與STM32CubeMX版本、芯片支持包DFP版本兼容。不匹配的版本是很多詭異問題的源頭。調(diào)試USB一個(gè)好的習(xí)慣是充分利用LED和串口如果還有其他串口的話進(jìn)行狀態(tài)指示。比如在HAL_PCD_ConnectCallback設(shè)備連接和HAL_PCD_DisconnectCallback設(shè)備斷開中翻轉(zhuǎn)一個(gè)LED在描述符請(qǐng)求回調(diào)中打印日志能讓你快速了解設(shè)備枚舉到了哪一步。當(dāng)硬件工具不足時(shí)這種“土法調(diào)試”往往最有效。