1.3 HID Basic Keyboard Example (hid_basic_keyboard)

This application demonstrates the ability of the MPLAB Harmony USB Host HID Client Driver to support to enumerate and operate a HID keyboard device.

Description

This application creates a USB Host application that uses the USB Host Layer, HID Client driver and HID Keyboard Usage driver to enumerate a USB keyboard and understand keyboard press release events. The keyboard events are displayed using a terminal emulator on a personal computer.

Downloading and building the application

To clone or download this application from Github, go to the main page of this repository and then click Clone button to clone this repository or download as zip file. This content can also be downloaded using content manager by following these instructions.

Path of the application within the repository is usb_apps_host/apps/hid_basic_keyboard.

Following table gives the details of project configurations, target device used, hardware and its IDE. Open the project using the respective IDE and build it.

Project NameIDETarget DeviceHardware / Configuration
pic32cm_le00_curiosity_pro.XMPLABXPIC32CM5164LE00100PIC32CM Lx Curiosity Pro Board
pic32mz_ef_curiosity_2_0.XMPLABXPIC32MZ2048EFM144Curiosity PIC32MZ EF 2.0 Development Board
sam_9x60_ek.XMPLABXSAM9X60SAM9X60-EK Evaluation Board
sam_9x60_ek_freertos.XMPLABXSAM9X60SAM9X60-EK Evaluation Board
sam_9x75_eb.XMPLABXSAM9X75SAM9X75-DDR3-EB Evaluation Board
sam_9x60_curiosity.XMPLABXSAM9X60SAM9X60 Curiosity Development Board
sam_9x60_curiosity_freertos.XMPLABXSAM9X60SAM9X60 Curiosity Development Board
sam_a5d2_xult.XMPLABXATSAMA5D27CSAMA5D2 Xplained Ultra Board
sam_a5d2_xult_freertos.XMPLABXATSAMA5D27CSAMA5D2 Xplained Ultra Board
sam_a5d27_som1_ek.XMPLABXATSAMA5D27CSAMA5D27 SOM1 Kit1
sam_a5d27_som1_ek_freertos.XMPLABXATSAMA5D27CSAMA5D27 SOM1 Kit1
sam_a5d27_wlsom1_ek1.XMPLABXATSAMA5D27CATSAMA5D27 WLSOM1 EK1
sam_a5d27_wlsom1_ek1_freertos.XMPLABXATSAMA5D27CATSAMA5D27 WLSOM1 EK1
sam_a7g5_ek.XMPLABXSAMA7G54SAMA7G5 EK Board
sam_d21_xpro.XMPLABXATSAMD21J18ASAMD21 Xplained Pro Board
sam_e54_xpro.XMPLABXATSAME54P20ASAME54 Xplained Pro Board
sam_e70_xult.XMPLABXATSAME70Q21BSAME70 Xplained Ultra Board
sam_e70_xult_freertos.XMPLABXATSAME70Q21BSAME70 Xplained Ultra Board
sam_g55_xpro.XMPLABXATSAMG55J19SAMG55 Xplained Pro Board
sam_g55_xpro_freertos.XMPLABXATSAMG55J19SAMG55 Xplained Pro Board
pic32cz_ca80_curiosity_ultra.XMPLABXPIC32CZ8110CA80208PIC32CZ Curiosity Development Board
pic32ck_gc01_curiosity_ultra_freertos.XMPLABXPIC32CK2051GC01144PIC32CK GC Curiosity Ultra Development Board
pic32cx_sg41_curiosity_ultra.XMPLABXPIC32CX1025SG41128PIC32CX SG41 Curiosity Ultra Evaluation Board
sam_a5d29_curiosity.XMPLABXATSAMA5D29SAMA5D29 Curiosity Development Board
sam_9x75_curiosity.XMPLABXSAM9X75D2GSAM9X75-Curiosity Development Board
sam_a7d65_curiosity.XMPLABXSAMA7D65 SAMA7D65 Curiosity Development Board
wbz653_curiosity.XMPLABXWBZ653WBZ653 Curiosity Board

Configuring the Hardware

PIC32CZ CA80 Curiosity Development Board
  • A commercially available USB Keyboard is required to run this demonstration application.
  • Connect the USB Keyboard to the connector (J102) using a USB Type-A Female to micro-B male cable (This cable is not included in the kit).
  • The demonstration uses the PKOB4 Serial Interface to transfer messages on a PC.
  • LED0 indicates a Device Connection. (Attached device has been successfully enumerated and configured).
  • The LED on the keyboard toggles on Keyboard "CapsLock" press event.
PIC32CX SG41 Curiosity Ultra Evaluation Board
  • A commercially available USB Keyboard is required to run this demonstration application.
  • Connect the USB Keyboard to the connector (J200) using a USB Type-A Female to micro-B male cable (This cable is not included in the kit).
  • The demonstration uses the PKOB4 Serial Interface to transfer messages on a PC.
  • LED2 indicates a Device Connection. (Attached device has been successfully enumerated and configured).
  • The LED on the keyboard toggles on Keyboard "CapsLock" press event.
PIC32CK GC Curiosity Ultra Development Board
  • An external power supply (6.5V to 14V) must be connected through the J200 connector.
  • A commercially available USB Keyboard is required to run this demonstration application.
  • Connect the USB Keyboard to the USB Type-C connector (J202). A USB Type-C to Type-A Female adapter is required to connect the USB device to the board (This cable is not included in the kit).
  • The demonstration uses the PKOB4 Serial Interface to transfer messages on a PC.
  • LED1 indicates a Device Connection. (Attached device has been successfully enumerated and configured).
  • The LED on the keyboard toggles on Keyboard "CapsLock" press event.
SAM9X75-DDR3-EB Evaluation Board

  • Powered the board with an external power supply (or use the micro AB connector).

  • Setup the SD card (Note: exFAT formatted SD Cards are not supported)

    • Download harmony MPU bootstrap loader from this location.
    • Copy the downloaded boot loader binary (boot.bin) and generated application binary (harmony.bin) into the SD card.
    • Insert the SD card into the SDMMC connector (SDMMC0) on the board.
    • Reset the board by pressing the Push Button RESET, then START.

  • Connect an USB to serial cable to DBGU0 (to enable debug com port).

  • Connect the USB device to the Type-A connector or to the micro AB with a specific dongle (in these case the need to be powered by the external power supply).

  • LED near VDDCORE inscription on the board is controlled by the attached USB CDC device.
    SAMD21 Xplained Pro Board
    • A commercially available USB Keyboard is required to run this demonstration application.
    • Jumper titled "PA03 SELECT" must be shorted between PA03 and USB_ID (positions 2 and 3)
    • Use "TARGET USB" connector on the board to connect the USB Keyboard to the USB Host. A USB Type-A Female to micro-B male cable will be needed to connect the device (This cable is not included in the kit).
    • The demonstration uses the EDBG Serial Interface to transfer demonstration application messages on a PC.
    • LED0 indicates a Device Connection. (Attached device has been successfully enumerated and configured).
    • The LED on the keyboard toggles on Keyboard "CapsLock" press event.

      Note: Note: An unexpected behavior may be observed if the attached USB device draws an excess amount of current from the board and the Vdd voltage drops below 2.7 volts. The demo has the wait states (NVM_CTRLB <RWS[3:0]>) value set to '1'.

    SAME54 Xplained Pro Board
    • A commercially available USB Keyboard is required to run this demonstration application.
    • Use "TARGET USB" connector on the board to connect the USB Keyboard to the USB Host. A USB Type-A Female to micro-B male cable will be needed to connect the device (This cable is not included in the kit).
    • The demonstration uses the EDBG Serial Interface to transfer demonstration application messages on a PC.
    • LED0 indicates a Device Connection. (Attached device has been successfully enumerated and configured).
    • The LED on the keyboard toggles on Keyboard "CapsLock" press event.
    SAME70 Xplained Ultra Board
    • A commercially available USB Keyboard is required to run this demonstration application.
    • Jumper J203 must be shorted between PB08 and LED2 (positions 1 and 2).
    • Use "TARGET USB" J200 connector on the board to connect the USB Keyboard to the USB Host. A USB Type-A Female to micro-B male cable will be needed to connect the device (This cable is not included in the kit).
    • The demonstration uses the EDBG Serial Interface to transfer demonstration application messages on a PC.
    • LED3 indicates a Device Connection. (Attached device has been successfully enumerated and configured).
    • The LED on the keyboard toggles on Keyboard "CapsLock" press event.
    SAMG55 Xplained Pro Board
    • A commercially available USB Keyboard is required to run this demonstration application.
    • Chip Erase Jumper must be open.
    • Use TARGET USB connector on the board to connect the USB keyboard to the USB Host. A USB Type-A Female to micro-B male cable will be needed to connect the device (This cable is not included in the kit).
    • The demonstration uses the EDBG Serial Interface to transfer demonstration application messages on a PC.
    • LED0 indicates a Device Connection. (Attached device has been successfully enumerated and configured).
    • The LED on the keyboard toggles on Keyboard "CapsLock" press event.
    SAM9X60-EK Evaluation Board

    • A commercially available USB Keyboard is required to run this demonstration application.

    • Setup the SD card (Note: exFAT formatted SD Cards are not supported)

      • Download harmony MPU bootstrap loader from this location.
      • Copy the downloaded boot loader binary (boot.bin) and generated application binary (harmony.bin) into the SD card.
      • Insert the SD card into the SDMMC connector J4 on the board.
      • Reset the board by pressing the Push Button SW3.

    • Jumpers J20, J21, and J13 must be open.

    • Jumper J2 and J3 must be shorted.

    • Connect the USB Micro-B port (J22) on board to the computer using a micro USB cable (to enable debug com port).

    • Connect the USB Micro-B Connector (J7) on the board to the computer using a micro USB cable to power up the board.

    • Connect the USB device to the Type-A connector (J8).

    • LED D1 indicates a Device Connection (Attached device has been successfully enumerated and configured).

    • The LED on the keyboard toggles on Keyboard "CapsLock" press event.

      Note: Reset push button on SAM9X60 EK is labeled as SW3

SAM9X60-Curiosity Board

  • Setup the SD card (Note: exFAT formatted SD Cards are not supported)

    • Download harmony MPU bootstrap loader from this location.
    • Copy the downloaded boot loader binary (boot.bin) and generated application binary (harmony.bin) into the SD card.
    • Insert the SD card into the SDMMC0 connector J3 on the board.
    • Reset the board by pressing the Push Button RESET.

  • Jumper J4 must be shorted.

  • Connect the USB Micro-B Connector (J1) on the board to the computer using a micro USB cable.

  • Connect the USB device to the Type-A connector (J10).

  • LED D1 indicates a Device Connection (Attached device has been successfully enumerated and configured).

  • The LED on the keyboard toggles on Keyboard "CapsLock" press event.

SAMA5D2 Xplained Ultra Board
  • A commercially available USB Keyboard is required to run this demonstration application.
  • Setup the SD card (Note: exFAT formatted SD Cards are not supported)
    • Download harmony MPU bootstrap loader from this location.
    • Copy the downloaded boot loader binary (boot.bin) and generated application binary (harmony.bin) into the SD card.
    • Insert the SD card into the SDMMC1 slot on the board.
    • Reset the board by pressing the Push Button BP3.
  • Connect the EDBG USB Micro-B port J14 on the board to the computer using a micro USB cable.
  • Connect the USB device to the USB Type-A connector "A5-USB-B" (J13).
  • The demonstration uses the EDBG USB Micro-B port J14 to transfer demonstration application messages on a PC.
  • RGB LED indicates a Device Connection (Attached device has been successfully enumerated and configured).
  • The LED on the keyboard toggles on Keyboard "CapsLock" press event.
Curiosity PIC32MZ EF 2.0 Development Board
  • A commercially available USB Keyboard is required to run this demonstration application.
  • Connect the USB Keyboard to the "TARGET USB" connector (J201) using a USB Type-A Female to micro-B male cable (This cable is not included in the kit).
  • The demonstration uses the PKOB4 Serial Interface to transfer messages on a PC.
  • LED1 indicates a Device Connection (Attached device has been successfully enumerated and configured).
  • The LED on the keyboard toggles on Keyboard "CapsLock" press event.
SAMA5D27 SOM1 Kit1

  • A commercially available USB Keyboard is required to run this demonstration application.

  • Setup the SD card (Note: exFAT formatted SD Cards are not supported)

    • Jumper J9 must be removed to have the JTAG-CDC enable.
    • Download harmony MPU bootstrap loader from this location.
    • Copy the downloaded boot loader binary (boot.bin) and generated application binary (harmony.bin) into the SD card.
    • Insert the SD card into the SDMMC0 slot (J12) on the board.
    • Reset the board by pressing the Push Button PB1.

  • Connect the USB Micro-AB port (J10) on the board to the computer using a micro USB cable.

  • Connect the USB device to the USB-B Type-C connector (J19) on the board.

  • The demonstration uses the USB Micro-AB port (J10) to transfer demonstration application messages on a PC.

  • RGB LED indicates a Device Connection (Attached device has been successfully enumerated and configured).

  • The LED on the keyboard toggles on Keyboard "CapsLock" press event.

ATSAMA5D27-WLSOM1 Evaluation Kit
  • A commercially available USB Keyboard is required to run this demonstration application.
  • Setup the SD card (Note: exFAT formatted SD Cards are not supported)
    • Download harmony MPU bootstrap loader from this location.
    • Copy the downloaded boot loader binary (boot.bin) and generated application binary (harmony.bin) into the SD card.
    • Insert the SD card into the SDMMC0 Card Connector (J9) on the board.
    • Reset the board by pressing the Reset Button (SW2)
  • Connect the USB-A Micro-AB connector (J10) on the board to the computer using a micro USB cable.
  • Press the "START_SOM" button to activate board start-up.
  • Connect the USB device to the USB Type-A connector (J11) on the board.
  • The demonstration uses the Debug UART port (J26) to transfer demonstration application messages on a PC. A USB/Serial converter is required to connect the J26 to a PC (The USB/Serial converter is not included in the kit).
  • RGB LED indicates a Device Connection (Attached device has been successfully enumerated and configured).

  • The LED on the keyboard toggles on Keyboard "CapsLock" press event.

SAMA7G5-EK Evaluation Kit
  • A commercially available USB Keyboard is required to run this demonstration application.
  • Powered the board with an external power supply (J1).
  • Setup the SD card (Note: exFAT formatted SD Cards are not supported)
    • Download harmony MPU bootstrap loader from this location.
    • Copy the downloaded boot loader binary (boot.bin) and generated application binary (harmony.bin) into the SD card.
    • Insert the SD card into the SD Card Connector (J4) on the board.
    • Reset the board by pressing the Reset Button (nRST)
  • Press the "nSTART" button to activate board start-up.
  • Connect the USB device to the USB Host Type-A connector (J9) on the board. Alternatively, the USB Device could be connected to the Type-C connector (J8) or micro A/B connector (J7).
  • The demonstration uses the Debug UART port (J24) to transfer demonstration application messages on a PC.
  • RGB LED indicates a Device Connection (Attached device has been successfully enumerated and configured).
  • The LED on the keyboard toggles on Keyboard "CapsLock" press event.
Curiosity Pro PIC32CM LE00 Development Board
  • Power the board by connecting an host to "DEBUG USB" (J300) connector.
  • Connect the USB device to the USB Host "TARGET USB" (J200) using a USB Type-A Female to micro-B male cable (This cable is not included in the kit).
  • LED0 indicates a Device Connection (Attached device has been successfully enumerated and configured).
  • The LED on the keyboard toggles on Keyboard "CapsLock" press event.
SAMA5D29 Curiosity Development Board
  • Setup the SD card (Note: exFAT formatted SD Cards are not supported)
    • Download harmony MPU bootstrap loader from this location.
    • Copy the downloaded boot loader binary (boot.bin) and generated application binary (harmony.bin) into the SD card.
    • Insert the SD card into the μSD-CARD connector J6 on the board.(This connector is present on the bottom face of the board)
    • Reset the board by pressing the Push Button RESET.
  • Press the "START" button to activate board start-up.
  • Connect the USB device to the USB_B Type-A connector (J11) on the board.
  • RGB LED (D5) on the board indicates a Device Connection (Attached device has been successfully enumerated and configured).
  • The LED on the keyboard toggles on Keyboard "CapsLock" press event.

SAM9X75-Curiosity Development Board

  • Setup the SD card (Note: exFAT formatted SD Cards are not supported)
    • Download harmony MPU bootstrap loader from this location.
    • Copy the downloaded boot loader binary (boot.bin) and generated application binary (harmony.bin) into the SD card.
    • Insert the SD card into the μSD-CARD connector (J14) on the board.(This connector is present on the bottom face of the board)
    • Reset the board by pressing the Push Button RESET.
  • Press the "START" button to activate board start-up.
  • Connect the USB device to the USB_B Type-A connector (J15) or USB_C Type-A connector (J16) on the board.
  • RGB LED (LD1) on the board indicates a Device Connection (Attached device has been successfully enumerated and configured).
  • The LED on the keyboard toggles on Keyboard "CapsLock" press event.
  • The demonstration uses the UART DEBUG port (J35) to transfer demonstration application messages on a PC. A USB/Serial converter is required to connect the J35 to a PC (The USB/Serial converter is not included in the kit).

SAMA7D65 Curiosity Development Board

  • Setup the SD card (Note: exFAT formatted SD Cards are not supported)
    • Download harmony MPU bootstrap loader from this location.
    • Copy the downloaded boot loader binary (boot.bin) and generated application binary (harmony.bin) into the SD card.
    • Insert the SD card into the SD-CARD connector (J10) on the board.
    • Reset the board by pressing the Push Button RESET.
  • Press the "START" button to activate board start-up.
  • Connect the USB device to the USB_B Type-A connector (J23) or USB_C Type-A connector (J24) on the board.
  • RGB LED on the board indicates a Device Connection (Attached device has been successfully enumerated and configured).
  • The LED on the keyboard toggles on Keyboard "CapsLock" press event.
  • The demonstration uses the UART DEBUG port (J35) to transfer demonstration application messages on a PC. A USB/Serial converter is required to connect the J35 to a PC (The USB/Serial converter is not included in the kit).

WBZ653 Curiosity Board
  • Connect a Type-C cable between the DBG USB (J100) port on the board and the PC to power up the board.
  • The Jumper J102 must be shorted between 5V and VBUS.
  • The Jumper J104 must be connected between VBUSON and EN (Positions 2 and 3).
  • A commercially available USB Keyboard is required to run this demonstration application.
  • Connect the USB Keyboard to the USB Type-C connector TARGET USB (J103). A USB Type-C to Type-A Female adapter is required to connect the USB device to the board (This cable is not included in the kit).
  • The demonstration uses the PKOB4 (DBG USB J100) Serial Interface to transfer messages on a PC.
  • The RGB_LED (D800) turning Green indicates a Device Connection. (Attached device has been successfully enumerated and configured).
  • The LED on the keyboard toggles on Keyboard "CapsLock" press event.

Running the Application

  1. Open the project with appropriate IDE. Compile the project and program the target device.

  2. Connect the serial interface on the board to a PC. On the PC, launch a terminal emulator, such as Tera Term, and select the appropriate COM port and set the serial port settings to 115200-N-1.

  3. If a USB keyboard is not connected to the Embedded USB Host, the terminal emulator window will show the Connect Keyboard prompt.

  4. Attach a USB keyboard to the Host connector of the target hardware. The message, Keyboard Connected, will appear in the terminal emulator window. Refer to the Configuring the Hardware section for any converter requirements.

  5. Begin typing on the keyboard and the appropriate keys should be displayed on the serial terminal. Subsequent press and release of modifier keys (i.e., CAPS LOCK, NUM LOCK, etc.) will result in the appropriate keyboard LEDs to turning ON and OFF.

  6. Disconnecting the keyboard will result in the message, Connect Keyboard.