Arduino USB Business Card

USB Business Card

有人做這樣的生意，叫作 USB Business Card，中文稱作 USB 名片或是隨身碟名片：

▲ 圖片來源: http://www.andreonicards.com

USB Business Card 既是名片，又是一個隨身碟，所以很適合隨身攜帶又可以拿來儲存資料，把它當作禮品送給客戶，是一個很聰明的形象推銷工具。

▲ 圖片來源: http://www.andreonicards.com

Arduino 滑鼠自動點擊器

承上篇，這次我們來做個 Arduino 滑鼠自動點擊器。

接線

我們用個可變電阻來調整滑鼠點擊的速度：

• 可變電阻中間腳位接到類比輸入 (Analog Input) pin3，剩下的兩支腳位，一支接到 5V，另外一支接到 GND

▲ 完成圖

Arduino Uno Mouse

這次我們將使用 darran 所寫的 Arduino UNO MouseHID 讓 Arduino 變身成電腦滑鼠。我假設你已經知道如何更新 atmega8u2 的韌體，相關文章請參考「如何讓 Arduino Uno 進入 DFU mode」跟「如何用 FLIP 更新 Atmega8u2 的韌體 」。

準備設備

你需要一張 Arduino Uno 或是 Mega 2560 的板子，還有一條單蕊線：

▲ 用單蕊線主要目的是把 Arduino 切到 DFU mode

下載

請連到底下的網址取得 Arduino Uno Mouse HID:

http://goo.gl/RvNvP

下載解壓縮後，把 Arduino-mouse 資料夾放到 Arduino 速寫簿 (Sketchbook) 資料夾底下。Arduino 速寫簿 (Sketchbook) 資料夾的預設位置是在「我的文件 > Arduino」這個地方。

IR2Keystroke

實驗目的

我們將做一個紅外線轉成按鍵敲擊動作 (keystroke) 的應用，我們把它稱之為 IR2Keystroke。IR2Keystroke 會用到 USBKeyboard Library，因此請參見 USBKeyboard Library 先把 library 安裝起來。

材料

• 麵包板 x 1
• Arduino 主板 x 1
• 38 kHz 紅外線接收器 (例如 TSOP2438,TSOP4438, PNA4602, FM-8038TM2-5DN) x 1
• 單蕊線 x N

接線

• 照下表連接 Arduino 跟紅外線接收器:

紅外線接收器接腳	Arduino 接腳
Vcc(+ 或 V+)	+5V
GND(-)	GND
Vout(或 OUT)	pin 2。也可以接到其它 Digital pin，但程式要配合修改

▲ 有些紅外線接收器 GND 和 Vcc 是相反的，接線時請查閱你的 datasheet

USBKeyboard Library

簡介

USBKeyboard 是專門為 darran Arduino UNO Keyboard HID 而寫的一個 library。有了 USBKeyboard library，要讓 Arduino 送出鍵盤敲擊動作 (keystrokes) 給電腦會變得很簡單。我假設你已經學會「如何讓 Arduino Uno 進入 DFU mode」而且也已經知道「如何用 FLIP 更新 Atmega8u2 的韌體」，並且已讀過文後的參考資料。

安裝

USBKeyboard library 可以在底下的網址取得:

https://github.com/coopermaa/USBKeyboard

安裝方法很簡單，把檔案解壓縮放到 Arduino 速寫簿 (Sketchbook) 資料夾的 Libraries 資料夾底下或 arduino-00xx\libraries 資料夾下即可。Arduino 速寫簿 (Sketchbook) 資料夾的預設位置是在「我的文件 > Arduino」這個地方。

讀取鍵盤燈號狀態

承上篇，Arduino Uno Keyboard 除了可以讓 Arduino 送出按鍵敲擊動作 (keystroke) 給電腦外，還可以讀取鍵盤上的燈號狀態 (keyboard LEDs status)，例如 Num Lock, Caps Lock 和 Scroll Lock。接著我們就來看個簡單範例，學習如何用 Arduino 讀取鍵盤的燈號狀態。

程式碼

這個範例程式放在 Arduino Keyboard 裏。請打開 Arduino IDE， 載入 "File > Sketchbook > Arduino-keyboard > ledStatus" 然後把程式上傳到 Arduino 板子上：

送出按鍵敲擊動作 (Send a keystroke)

承上篇，接著我們來看個很簡單的範例，來學習如何讓 Arduino 送出一個按鍵敲擊動作 (keystroke) 給電腦。

 

程式碼

這個範例程式放在 Arduino Keyboard 裏。請打開 Arduino IDE， 載入 "File > Sketchbook > Arduino-keyboard > senda" 然後把程式上傳到 Arduino 板子上：

Arduino Uno Keyboard

在看過前兩篇文章後，相信你已經學會「如何讓 Arduino Uno 進入 DFU mode」而且也已經知道「如何用 FLIP 更新 Atmega8u2 的韌體 」。接下來我們來玩 Arduino Keyboard，我們將使用 darran 所寫的 Arduino UNO Keyboard HID 並且試著跑一支範例程式讓 Arduino 送出按鍵敲擊動作 (Keystroke) 給電腦。

準備設備

你需要一張 Arduino Uno 或是 Mega 2560 的板子，還有一條單蕊線：

▲ 用單蕊線主要目的是把 Arduino 切到 DFU mode

下載

請連到底下的網址取得 Arduino Keyboard 韌體:

http://goo.gl/EdSW2

下載解壓縮後，把 Arduino-keyboard 資料夾放到 Arduino 速寫簿 (Sketchbook) 資料夾底下。Arduino 速寫簿 (Sketchbook) 資料夾的預設位置是在「我的文件 > Arduino」這個地方。

如何用 FLIP 更新 Atmega8u2 的韌體

在前一篇中，我們已經知道如何讓 Arduino Uno 進入 DFU mode，這一篇我們來學習如何用 FLIP 更新 Atmega8U2 的韌體。我將以 Arduino-usbserial 示範如何燒錄韌體。

準備韌體檔

Arduino-usbserial 的韌體檔座落於 "arduino-00xx\hardware\arduino\firmwares\arduino-usbserial\" 這個資料夾：

▲ Arduino-usbserial-uno.hex  是給 Uno 用，而 Arduino-usbserial-mega 則是供 Mega 2560 使用

你也可以連到底下的網址，直接從網路下載 hex 檔：

http://goo.gl/OipyJ

下載畫面：

我的板子是 Uno，所以我選擇 Arduino-usbserial-uno.hex。

如何讓 Arduino Uno 進入 DFU mode

ATmega8U2 晶片簡介

Arduino Uno 跟先前的板子最大的不同，是不再使用 FTDI 的 USB-to-serial 晶片，取而代之的，是改用 Atmega8U2 這顆晶片當作 USB-to-serial 的轉換器，它的角色是扮演電腦 USB port 跟 Arduino 主控制器 Atmega328p serial port 之間的橋梁。。

▲  Atmega8U2 所在的位置

Atmega8U2 上面有韌體，出廠預設燒錄的是 Arduino-usbserial，功能就是做 USB-to-serial 的轉接，然而我們可以透過一個 叫作 DFU (Device Firmware Upgrade) 的 USB 協定來更新 Atmega8U2 的韌體。

所以，如果你要更新 Atmega8U2 的韌體，就得先讓 Atmega8U2 進入 DFU mode，然後再利用專屬的軟體來燒錄韌體，一般而言，在 Windows 上會用 FLIP，而在 MAC & Linux 則是使用 dfu-programmer。這篇我們先說明如何讓 Arduino 進入 DFU mode，下一篇接著介紹如何用 FLIP 更新 Atmega8U2 的韌體。

什麼情況下會需要更新 Atmega8U2 的韌體? 嗯，因為 Atmega8U2 很有彈性，它可以讓你更換成其它韌體，所以你的 Arduino 板子就可以搖身一變變成不同的 USB 裝置，例如 MIDI controller, HID 裝置 (Keyboard, Mouse, Joystick 等等)。

UsbKeypad for Arduino

在上一篇中我們自製了一個 USBKeyboard，這次來自製一個 USB 數字鍵盤 (Numeric USB Keypad)。

▲ USBKeypad: 照片來源

準備材料

除了 Arduino 板子和 USB Shield 外，你還需要一個 Keypad:

關於 Keypad 的介紹與使用方法，請參考我寫的「Arduino 筆記 – Lab18 讀取 3x4 Keypad 的輸入」這篇筆記。

v-usb for arduino USBKeyboard

USBKeyboard 是 V-USB for arduino 這個計畫所提供的一個範例，它實作了一個很簡單的 USB 鍵盤裝置。

這個範例名字其實取得不好，因為它並沒有真正做出一個 USB 鍵盤，事實上這個範例只用到一個按鈕，程式會在按鈕被按下時，送出 "hello world" 跟一個 Enter 的鍵盤訊息給電腦，所以也許應該把它稱作 USB Helloworld Button 比較恰當。先不管這個問題，我們還是繼續沿用 USBKeyboard 這個名字。

接下來，我們就來自製這個 USBKeyboard 吧。

硬體電路

首先，你必須為 Arduino 做個 USB Shield，底下是一個參考電路，由於 USB D+ 和 D- 用 3.3V 的電壓，因此在 D+ 和 D- 上使用稽納二極體 (Zener diodes)。你必須確保 D- 準位在 2.5V 與 3.6V 之間。

V-USB examples for Arduino

我把 V-USB 提供的 4 支範例程式 (custom-class, hid-mouse, hid-custom-rq, hid-data) 移植到 Arduino 上了，現在你只要用 Arduino IDE 就可以上傳這 4 支範例程式:

在你開始之前，我希望你已經看過「V-USB 簡介」一文，知道 V-USB 是什麼，而且也希望你看過底下這幾篇，因為這 4 支範例程式的使用方法都寫在這幾篇裏，在這我就不再重述了:

• V-USB custom-class
• V-USB hid-mouse
• V-USB hid-custom-rq
• V-USB hid-data

準備硬體

要在 Arduino 上跑 V-USB 這 4 支範例程式，首先你必須準備一張 USB Shield。底下是一個參考電路，由於 USB D+ 和 D- 用 3.3V 的電壓，因此在 D+ 和 D- 上使用稽納二極體 (Zener diodes)。你必須確保 D- 準位在 2.5V 與 3.6V 之間。

實物照片：

▲ 圖片來源: galileo  的 USB Shield

下載與安裝範例程式

Arduino 版的 V-USB 範例程式可以在底下的鏈結中取得:

• custom_class.zip
• hid_mouse.zip
• hid_custom_rq.zip
• hid_data.zip

下載後把檔案解壓縮到 Arduino-00xx\libraries 資料夾下，或是放到 Arduino 速寫簿(Sketchbook)資料夾的 Libraries 資料夾底下也行。

韌體調整

接著韌體要做兩個調整:

1. 修改 usbconfig.h:  定義所用的 D+ 和 D- data lines 腳位。必須根據你的硬體調整 USB_CFG_IOPORTNAME, USB_CFG_DMINUS_BIT 和 USB_CFG_DPLUS_BIT。其它不需要修改。 
2. 這點很重要！由於 Arduino 的 timer0 ISR 執行時間太久，會影響 V-USB 的運作，所以你必須修改 Arduino-00xx\hardware\arduino\cores\arduino\wiring.c 的 Timer0 ISR，把 "sei();" 加到 ISR 的第一行，像這樣子:

完成之後，你就可以用 Arduino IDE 打開範例程式並且上傳到 Arduino 板子上執行。

就這樣！

希望你可以順利使用這四支範例程式。如果你遇到什麼困難，歡迎留言或寫信來詢問。

延伸閱讀

• V-USB (Virtual USB port for AVR microcontrollers)

V-USB hid-data 範例解說

承上篇，這篇將摘要說明 V-USB hid-data 範例程式。

hid-data 分成韌體和指令列工具 (commandline) 兩個部份。

韌體

usbconfig.h

底下是 hid-data 對 usbconfig.h 所做的調整：

• USB_CFG_IOPORTNAME, USB_CFG_DMINUS_BIT 與 USB_CFG_DPLUS_BIT

這些設定 USB bus D+ 和 D- 所用的接腳。預設是：

#define USB_CFG_IOPORTNAME      D
#define USB_CFG_DMINUS_BIT      4
#define USB_CFG_DPLUS_BIT       2

• #define USB_CFG_HAVE_INTRIN_ENDPOINT    1

這個設定 interrupt-in endpoint 1，這是 HID device 的必要選項。

• #define USB_CFG_INTR_POLL_INTERVAL      100

這個設定 interrupt-in endpoint 1 的 poll interval，單位為 miliseconds，不能小於 10 ms。

• USB_CFG_VENDOR_ID 與 USB_CFG_DEVICE_ID

這些設定 VID 和 PID。預設是：

#define  USB_CFG_VENDOR_ID       0xc0, 0x16
#define  USB_CFG_DEVICE_ID       0xdf, 0x05

資料表示方式是 low byte first，VID 0x16c0 和 PID 0x05df 是 obdev 提供的共享 VID/PID。

• USB_CFG_DEVICE_NAME and USB_CFG_DEVICE_NAME_LEN

這些設定 Device Name 和資料長度，hid-data 把 Device Name 設成 "DataStore"，資料長度是 9：

#define USB_CFG_DEVICE_NAME     'D', 'a', 't', 'a', 'S', 't', 'o', 'r', 'e'
#define USB_CFG_DEVICE_NAME_LEN 9

• USB_CFG_DEVICE_CLASS 與 USB_CFG_INTERFACE_CLASS

這些設定 Device Class 和 Interface Class。hid-mouse 的設定為:

#define USB_CFG_DEVICE_CLASS        0
#define USB_CFG_INTERFACE_CLASS     3

USB 有定義一些常用的 device class，可在 USB Class Codes 這個頁面中找到，0 代表由 interface 指定。而 interface class 定義 3 代表這個是 HID Class。

• #define USB_CFG_HID_REPORT_DESCRIPTOR_LENGTH    22

這個設定 HID report descriptor 的資料長度。你必須在程式裏定義一個叫 usbHidReportDescriptor 的陣列，用來存放 report descriptor，而且陣列 size 要跟這個設定一致為 22 bytes 才行。

• USB_CFG_IMPLEMENT_FN_READ 與 USB_CFG_IMPLEMENT_FN_WRITE  

這會設定呼叫 usbFunctionWrite() 來處理 control-out transfer，而用 usbFunctionRead() 來處理 control-in transfer:

#define USB_CFG_IMPLEMENT_FN_WRITE      1
#define USB_CFG_IMPLEMENT_FN_READ       1

main.c

主程式分成 main() 和 usbFunctionSetup() 兩個函式。關於 main() 和 usbFunctionSetup() 兩個函式的說明，請參考「V-USB custom-class 範例解說」一文。

在這個範例程式中，main loop 的工作很單純，只是不斷呼叫 usbPoll() 讓 driver 處理工作。根據 V-USB 的說明，usbPoll() 至少每 50 ms 要跑一次。

底下是 hid-data的 usbFunctionSetup():

程式的邏輯是透過 bRequestRequest 判斷是不是 class request，假如是，再依 bRequest 判斷是哪一種 class request (Get Report, Set Report, Get Idle, Set Idle, Get Protocol 或 Set Protocol)。hid-data 只處 Get Report 和 Set Report 兩個 requests。在這個範例中，Get Report 是傳回 feature report 給 Host，而 Set Report 則是接收來自 host 端的 feature report。因為只有一個 feature report，所以 Get/Set Reports 沒有進一步判斷 ReportType (wValue high byte) 和 Report ID (wValue low byte)。

當收到 Get Report 或 Set Report 的 request 時，usbFunctionSet() 並沒有馬上把資料傳給 Host，而是回傳 USB_NO_MSG 讓 V-USB Driver 呼叫 usbFunctionRead() 和 usbFunctionWrite() 來處理。

usbFunctionRead() 的實作如下:

只是單純從 eeprom 讀取一塊資料 (data chunk) 並放到 buffer 給 Driver 處理。

而 usbFunctionWrite() 的實作如下:

也只是單純把從 host 收到的一塊資料 (data chunk) 寫到 eeprom。

HID Report  Descriptor

底下是 hid-data 所定義的 HID Report Descriptor:

上列定義一個 Feature Report，資料長度為 128 bytes。

指令列工具 (commandline)

指令列工具包含 hiddata.c 和 hidtool.c。hid-data 把開啟 USB device 以及 Get Report 和 Set Report 的功能集中到 hiddata.c。

主程式 hidtool.c 只是間接呼叫 hiddata.c 中的 usbhidGetReport() 和 usbhidSetReport()，假如是 usbhidGetReport() 會將收到的資料以 hex format 印出，除此之外，沒有值得一提的地方。

hid-data 利用 usb_control_msg() 發送 control message，usb_control_msg() 的原型為：

int usb_control_msg(usb_dev_handle *dev, int requesttype, int request, int value, int index, char *bytes, int size, int timeout);

以 Get Feature Report 為例，呼叫方法為：

其中 USB_TYPE_CLASS 指定 Class request，USB_RECIP_DEVICE 指定接收者為 Device，而 USB_ENDPOINT_IN 則是指定 Control-IN transfer。USBRQ_HID_GET_REPORT 表示 Get Report 的 request，而 wValue 高位元組為 USB_HID_REPORT_TYPE_FEATURE 表示要取 Feature Report，而低元組是 report number，在此為 0。

而 Set Feature Report 的呼叫方法則為:

其中 USB_ENDPOINT_OUT 指定 Control-OUT transfer。

延伸閱讀

• V-USB (Virtual USB port for AVR microcontrollers)
• HID Information
• HID Descriptor Tool
• USnooBie’s USB HID Report Descriptor Tutorial 1

V-USB hid-custom-rq 範例解說

承上篇，這篇將摘要說明 V-USB hid-custom-rq 範例程式。

hid-customer-rq 分成兩個部份：韌體和 PC 端的指令列工具 (commandline)。

hid-custom-rq 的功能跟 custom-class 範例一樣，因此底下的內容大部份都跟 custom-class 雷同。hid-custom-rq 跟 custom-class 不一樣的地方，在於 hid-custom-rq 是宣告成 HID device。

韌體

usbconfig.h

底下是 hid-custom-rq 對 usbconfig.h 所做的調整：

• USB_CFG_IOPORTNAME, USB_CFG_DMINUS_BIT 與 USB_CFG_DPLUS_BIT

這些設定 USB bus D+ 和 D- 所用的接腳。預設是：

#define USB_CFG_IOPORTNAME      D
#define USB_CFG_DMINUS_BIT      4
#define USB_CFG_DPLUS_BIT       2

• #define USB_CFG_HAVE_INTRIN_ENDPOINT    1

這個設定 interrupt-in endpoint 1，這是 HID device 的必要選項。

• #define USB_CFG_INTR_POLL_INTERVAL      100

這個設定 interrupt-in endpoint 1 的 poll interval，單位為 miliseconds，不能小於 10 ms。

• USB_CFG_VENDOR_ID 與 USB_CFG_DEVICE_ID

這些設定 VID 和 PID。預設是：

#define  USB_CFG_VENDOR_ID       0xc0, 0x16
#define  USB_CFG_DEVICE_ID       0xdf, 0x05

資料表示方式是 low byte first，VID 0x16c0 和 PID 0x05df 是 obdev 提供的共享 VID/PID。

• USB_CFG_DEVICE_NAME and USB_CFG_DEVICE_NAME_LEN

這些設定 Device Name 和資料長度，hid-custom-rq 把 Device Name 設成 "LEDCtlHID"，資料長度是 9：

#define USB_CFG_DEVICE_NAME     'L', 'E', 'D', 'C', 't', 'l', 'H', 'I', 'D'
#define USB_CFG_DEVICE_NAME_LEN 9

• USB_CFG_DEVICE_CLASS 與 USB_CFG_INTERFACE_CLASS

這些設定 Device Class 和 Interface Class。hid-custom-rq 的設定為:

#define USB_CFG_DEVICE_CLASS        0
#define USB_CFG_INTERFACE_CLASS     3

USB 有定義一些常用的 device class，可在 USB Class Codes 這個頁面中找到，0 代表由 interface 指定。而 interface class 定義 3 代表這個是 HID Class。

• #define USB_CFG_HID_REPORT_DESCRIPTOR_LENGTH    22

這個設定 HID report descriptor 的資料長度。你必須在程式裏定義一個叫 usbHidReportDescriptor 的陣列，用來存放 report descriptor，而且陣列 size 要跟這個設定一致為 22 bytes 才行。

V-USB hid-mouse 範例解說

承上篇，這篇將摘說明 V-USB hid-mouse 範例程式。

usbconfig.h

底下是 hid-mouse 對 usbconfig.h 所做的調整：

• USB_CFG_IOPORTNAME, USB_CFG_DMINUS_BIT 與 USB_CFG_DPLUS_BIT

這些設定 USB bus D+ 和 D- 所用的接腳。預設是：

#define USB_CFG_IOPORTNAME      D
#define USB_CFG_DMINUS_BIT      4
#define USB_CFG_DPLUS_BIT       2

• #define USB_CFG_HAVE_INTRIN_ENDPOINT    1

這個設定 interrupt-in endpoint 1，這是 HID device 的必要選項。

• #define USB_CFG_INTR_POLL_INTERVAL      100

這個設定 interrupt-in endpoint 1 的 poll interval，單位為 miliseconds，不能小於 10 ms。

• USB_CFG_VENDOR_ID 與 USB_CFG_DEVICE_ID

這些設定 VID 和 PID。預設是：

#define  USB_CFG_VENDOR_ID       0xc0, 0x16
#define  USB_CFG_DEVICE_ID       0xe8, 0x03

資料表示方式是 low byte first，VID 0x16c0 和 PID 0x03e8 是 obdev 提供的共享 VID/PID。

• USB_CFG_DEVICE_NAME and USB_CFG_DEVICE_NAME_LEN

這些設定 Device Name 和資料長度，hid-mouse 把 Device Name 設成 "Mouse"，資料長度是 5：

#define USB_CFG_DEVICE_NAME     'M', 'o', 'u', 's', 'e'
#define USB_CFG_DEVICE_NAME_LEN 5

• USB_CFG_DEVICE_CLASS 與 USB_CFG_INTERFACE_CLASS

這些設定 Device Class 和 Interface Class。hid-mouse 的設定為:

#define USB_CFG_DEVICE_CLASS        0
#define USB_CFG_INTERFACE_CLASS     3

USB 有定義一些常用的 device class，你可以在 USB Class Codes 這個頁面中找到，0 代表由 interface 指定。而 interface class 定義成 3 代表這個是 HID Class。

• #define USB_CFG_HID_REPORT_DESCRIPTOR_LENGTH    52

這個設定 HID report descriptor 的資料長度。你必須在程式裏定義一個叫 usbHidReportDescriptor 的陣列，用來存放 report descriptor，而且陣列 size 要跟這個設定一致為 52 bytes 才行。

main.c

主程式分成 main() 和 usbFunctionSetup() 兩個函式。關於 main() 和 usbFunctionSetup() 兩個函式的說明，請參考「V-USB custom-class 範例解說」一文。

在這個範例程式中，main loop 利用 usbInterruptIsReady() 檢查 Interrupt-In endpoint 1 的 buffer 是否可用，假如可以，便呼叫 advanceCircleByFixedAngle() 計算新的滑鼠座標，接著再呼叫 usbSetInterrupt() 把 reportBuffer 傳給 Host:

底下是 hid-mouse 的 usbFunctionSetup():

程式的邏輯是透過 bRequestType 判斷是不是 class request，假如是就依 bRequest 判斷是哪一種 class request (Get Report, Set Report, Get Idle, Set Idle, Get Protocol 或 Set Protocol)。hid-mouse 只處理 Get Report, Get Idle 和 Set Idle 這三個 requests。除了 Get Report 是必要的外，其它兩個 requests 可以省略不寫。事實上因為 Host 端的 HID Driver 已經知道 report 的格式，所以其實 host 也不會發出這些 requests。

HID Report  Descriptor

底下是 hid-mouse 所定義的 HID Report Descriptor:

上列定義一個標準滑鼠，有三個按鈕，X 和 Y 軸的相對座標，以及一個滾輪 (wheel)。而 report 的資料結構如下:

底下簡單說明這個 Report Descriptor 的結構:

首先，必須先定義 Buttons，總共有 3 個 Button:

每個 Button 狀態不是 0 就是 1:

3 個 Button 總共是 3 個位元:

這 3 個位元是 INPUT report:

其它 5 個位元是填充位元 (padding bits):

最後定義 X, Y 和滾輪:

把它們全當成 1 byte 的 signed integer，值域為 -127  到 +127:

每個 8 位元，總共 3 個:

把它們宣告成 INPUT report:

最後告訴電腦這是一個滑鼠:

就這樣。關於 HID Report Descriptor，你也可以參考「HID Report Descriptor 教學」這幾篇文章。

延伸閱讀

• V-USB (Virtual USB port for AVR microcontrollers)
• HID Information
• HID Descriptor Tool
• HID Report Descriptor 教學 #1 #2 #3

V-USB custom-class 範例解說

這篇將摘要說明 V-USB custom-class 範例的程式碼。要讀這篇，讀者必須對 USB 有足夠的認識。

customer-class 分成兩個部份：韌體和 PC 端的指令列工具 (commandline)

韌體

usbconfig.h

usbconfig.h 是 V-USB 的設定檔，每個 V-USB 的程式都會從 V-USB 的 usbconfig-prototype.h 複製過來並改名為 usbconfig.h 然後根據自己的硬體調整設定。

底下是 custom-class 對 usbconfig.h 所做的調整：

• USB_CFG_IOPORTNAME, USB_CFG_DMINUS_BIT and USB_CFG_DPLUS_BIT

這些設定 USB bus D+ 和 D- 所用的接腳。預設是：

#define USB_CFG_IOPORTNAME      D
#define USB_CFG_DMINUS_BIT      4
#define USB_CFG_DPLUS_BIT       2

• USB_CFG_VENDOR_ID and USB_CFG_DEVICE_ID

這些設定 VID 和 PID。預設是：

#define  USB_CFG_VENDOR_ID       0xc0, 0x16
#define  USB_CFG_DEVICE_ID       0xdc, 0x05

資料表示方式是 low byte first，VID 0x16c0 和 PID 0x05dc 是 obdev 提供的共享 VID/PID。

• USB_CFG_DEVICE_NAME and USB_CFG_DEVICE_NAME_LEN

這些設定 Device Name 和資料長度，custom-class 把 Device Name 設成 "LEDControl"，資料長度是 10：

#define USB_CFG_DEVICE_NAME     'L', 'E', 'D', 'C', 'o', 'n', 't', 'r', 'o', 'l'
#define USB_CFG_DEVICE_NAME_LEN 10

• USB_CFG_DEVICE_CLASS = 0xff

這個設定 Device Class。USB 定義了一些常用的 device class，你可以在 USB Class Codes 這個頁面中找到。0xff 代表的是 "Vendor Specific"，也就是廠商自行定義的 function。

V-USB hid-data

hid-data 是 V-USB 所附的一個範例，它示範如何透過 HID feature report 傳送固定大小的資料區塊 (blocks of data) 以讀取或寫入 eeprom 裏的內容。由於 Windows 內建 HID driver，因此 Windows 不會要求安裝驅動程式。這個範例同時也示範如何用 usbFunctionWrite() 和 usbFunctionRead() 傳送資料。

下載

hid-data 包在 V-USB 套件裏:

http://www.obdev.at/products/vusb/download.html

韌體調整

hid-data 需要調整的地方跟 hid-custom-rq 一樣:

● usbconfig.h:

定義所用的 D+ 和 D- data lines 腳位。必須根據你的硬體調整 USB_CFG_IOPORTNAME, USB_CFG_DMINUS_BIT 和 USB_CFG_DPLUS_BIT。

● Makefile:

定義所用的 MCU 以及時脈頻率，必須根據你的硬體調整 DEVICE 和 F_CPU。

編譯韌體

下指令編譯韌體，你會需要 WinAVR:

cd hid-data/firmware 
make hex

接著把韌體燒錄到板子上，讓裝置重新上電，然後，「裝置管理員」視窗裏就會出現剛剛安裝的裝置，不用安裝驅動程式:

▲ Windows 會將新裝置當成「HID-compliant device」

編譯 PC 端指令列工具 (commandline)

下指令編譯 PC 端指令列工具，你會需要 MingGW 和 MSYS：

cd hid-custom-rq/commandline 
make -f Makefile.windows

這會產生 hid-tool.exe。

使用 hid-tool

底下示範 hid-tool 的用法：

讀取 eeprom：

寫資料到 eeprom：

 

hid-data 所用的資料區塊大小為 128 bytes。

延伸閱讀

• V-USB (Virtual USB port for AVR microcontrollers)
• V-USB hid-custom-rq
• V-USB custom-class
• V-USB hid-mouse

V-USB hid-custom-rq

hid-custom-rq 是 V-USB 所附的一個範例，它示範如何定義 HID class device。hid-custom-rq 功能跟 custom-class 範例一樣，不過它宣告成 HID device，由於 Windows 內建 HID driver，因此 Windows 不會要求安裝驅動程式。

hid-custom-rq 一樣可以用 custom-data 所附的 commandline 工具，透過 libusb-win32 來控制裝置。libusb-win32 dll 必須跟 commandline 工具放在同一個資料夾。

下載

hid-custom-rq 包在 V-USB 套件裏:

http://www.obdev.at/products/vusb/download.html

韌體調整

hid-custom-rq 需要調整的地方跟 custom-data 一樣:

● usbconfig.h:

定義所用的 D+ 和 D- data lines 腳位。必須根據你的硬體調整 USB_CFG_IOPORTNAME, USB_CFG_DMINUS_BIT 和 USB_CFG_DPLUS_BIT。

● Makefile:

定義所用的 MCU 跟時脈頻率，必須根據你的硬體調整 DEVICE 和 F_CPU。

• main.c

定義所用的 LED 接腳，必須根據你的硬體調整 LED_PORT_DDR, LED_PORT_OUTPUT 和 LED_BIT。

編譯韌體

下指令編譯韌體，你會需要 WinAVR:

cd hid-custom-rq/firmware 
make hex

接著把韌體燒錄到板子上，讓裝置重新上電，然後，「裝置管理員」視窗裏就會出現剛剛安裝的裝置，不用安裝驅動程式:

▲ Windows 會將新裝置當成「HID-compliant device」

編譯 PC 端指令列工具 (commandline)

下指令編譯 PC 端指令列工具，你會需要 MingGW, MSYS 和 libusb-win32 函式庫：

cd hid-custom-rq/commandline 
make -f Makefile.windows

這會產生 set-led.exe。

註：libusb-win32 函式庫的安裝方法為，把 include\usb.h 複製到 C:\MingW\include\，而把 lib\gcc\libusb.a 複製到 C:\MingW\lib。

使用 hid-custom-rq

hid-custom-rq 的用法跟 custom-class 一樣：

打開 LED：

set-led on

關閉 LED：

set-led off

查詢 LED 狀態

set-led status

假如 LED 是開的，set-led status 會顯示 "LED is on"，否則的話會顯示 "LED is off"。

註：雖然指令列工具是同一支，但因為 hid-custom-rq 用的 VID/PID 跟 custom-data 不一樣，custom-data 用的是 0x16c0/0x05dc，而 hid-custom-rq 的是 0x16c0/0x05df，所以 set-led 指令列工具必須重新編譯才行，不然執行時會找不到 device。

延伸閱讀

• V-USB (Virtual USB port for AVR microcontrollers)
• V-USB custom-class
• V-USB hid-mouse

V-USB custom-class

custom-class 是 V-USB 所附的一個 custom class device 範例，它示範如何直接使用 default control pipe 傳送與接收小量的資料。

下載

custom-class 包在 V-USB 套件裏:

http://www.obdev.at/products/vusb/download.html

韌體調整

● usbconfig.h:

定義所用的 D+ 和 D- data lines 腳位。必須根據你的硬體調整 USB_CFG_IOPORTNAME, USB_CFG_DMINUS_BIT 和 USB_CFG_DPLUS_BIT。

● Makefile:

定義所用的 MCU 跟時脈頻率，必須根據你的硬體調整 DEVICE 和 F_CPU。

• main.c

定義所用的 LED 接腳，必須根據你的硬體調整 LED_PORT_DDR, LED_PORT_OUTPUT 和 LED_BIT。

編譯韌體

下指令編譯韌體，你會需要 WinAVR:

cd custom-class/firmware 
make hex

接著把韌體燒錄到板子上，讓裝置重新上電，安裝 libusb driver，然後「裝置管理員」視窗裏就會出現剛剛安裝的裝置:

編譯 PC 端指令列工具 (commandline)

下指令編譯 PC 端指令列工具，你會需要 MingGW, MSYS 和 libusb-win32 函式庫：

cd custom-class/commandline 
make -f Makefile.windows

這會產生 set-led.exe。

註：libusb-win32 函式庫的安裝方法為，把 include\usb.h 複製到 C:\MingW\include\，而把 lib\gcc\libusb.a 複製到 C:\MingW\lib。

使用 custom-class

custom-class 範例的使用方法為：

打開 LED：

set-led on

關閉 LED：

set-led off

查詢 LED 狀態

set-led status

假如 LED 是開的，set-led status 會顯示 "LED is on"，否則的話會顯示 "LED is off"。

延伸閱讀

• V-USB (Virtual USB port for AVR microcontrollers)