1.. zephyr:code-sample:: legacy-usb-hid-mouse
2   :name: Legacy USB HID mouse
3   :relevant-api: _usb_device_core_api usb_hid_device_api input_interface
4
5   Implement a basic HID mouse device.
6
7Overview
8********
9
10This sample app demonstrates use of a USB Human Interface Device (HID) driver
11by the Zephyr project. This very simple driver enumerates a board with a button
12into a mouse that has a left mouse button and optionally (depending on
13the number of buttons on the board) a right mouse button, X-axis movement,
14and Y-axis movement.
15If the USB peripheral driver supports remote wakeup feature, wakeup request
16will be performed on every button click if the bus is in suspended state.
17This sample can be found under :zephyr_file:`samples/subsys/usb/legacy/hid-mouse` in the
18Zephyr project tree.
19
20.. note::
21   This samples demonstrate deprecated :ref:`usb_device_stack`.
22
23Requirements
24************
25
26This project requires an USB device driver and uses the :ref:`input` API.
27There must be a :dtcompatible:`gpio-keys` group of buttons or keys defined at
28the board level that can generate input events, otherwise the example will build
29but not work as expected.
30
31The key mapping in the sample is as follows:
32
33- ``INPUT_KEY_0``: left button
34- ``INPUT_KEY_1``: right button
35- ``INPUT_KEY_2``: move the mouse along the x-axis
36- ``INPUT_KEY_3``: move the mouse along the y-axis
37
38An LED must also be configured via the ``led0`` devicetree alias. You may also
39see this error if you try to build this sample for an unsupported board:
40
41.. code-block:: none
42
43   Unsupported board: led0 devicetree alias is not defined
44
45Building and Running
46********************
47
48This sample can be built for multiple boards, in this example we will build it
49for the nucleo_f070rb board:
50
51.. zephyr-app-commands::
52   :zephyr-app: samples/subsys/usb/legacy/hid-mouse
53   :board: nucleo_f070rb
54   :goals: build
55   :compact:
56
57After you have built and flashed the sample app image to your board, plug the
58board into a host device, for example, a PC running Linux.
59The board will be detected as shown by the Linux dmesg command:
60
61.. code-block:: console
62
63    dmesg | tail -10
64    usb 2-2: new full-speed USB device number 2 using at91_ohci
65    usb 2-2: New USB device found, idVendor=2fe3, idProduct=0007, bcdDevice= 2.03
66    usb 2-2: New USB device strings: Mfr=1, Product=2, SerialNumber=3
67    usb 2-2: Product: Zephyr HID mouse sample
68    usb 2-2: Manufacturer: ZEPHYR
69    usb 2-2: SerialNumber: 86FE679A598AC47A
70    input: ZEPHYR Zephyr HID mouse sample as /devices/soc0/ahb/600000.ohci/usb2/2-2/2-2:1.0/0003:2FE3:0100.0001/input/input0
71    hid-generic 0003:2FE3:0100.0001: input: USB HID v1.10 Mouse [ZEPHYR Zephyr HID mouse sample] on usb-at91-2/input0
72
73You can also monitor mouse events by using the standard Linux ``evtest`` command
74(see the `Ubuntu evtest man page`_ for more information about this tool):
75
76.. _Ubuntu evtest man page:
77   http://manpages.ubuntu.com/manpages/trusty/man1/evtest.1.html
78
79.. code-block:: console
80
81    sudo evtest /dev/input/event0
82    Input driver version is 1.0.1
83    Input device ID: bus 0x3 vendor 0x2fe3 product 0x7 version 0x110
84    Input device name: "ZEPHYR Zephyr HID mouse sample"
85    Supported events:
86      Event type 0 (EV_SYN)
87      Event type 1 (EV_KEY)
88        Event code 272 (BTN_LEFT)
89        Event code 273 (BTN_RIGHT)
90        Event code 274 (BTN_MIDDLE)
91      Event type 2 (EV_REL)
92        Event code 0 (REL_X)
93        Event code 1 (REL_Y)
94        Event code 8 (REL_WHEEL)
95      Event type 4 (EV_MSC)
96        Event code 4 (MSC_SCAN)
97    Properties:
98    Testing ... (interrupt to exit)
99
100When you press the button on your board, it will act as if the left
101mouse button was pressed, and this information will be displayed
102by ``evtest``:
103
104.. code-block:: console
105
106    Event: time 1167609663.618515, type 4 (EV_MSC), code 4 (MSC_SCAN), value 90001
107    Event: time 1167609663.618515, type 1 (EV_KEY), code 272 (BTN_LEFT), value 1
108    Event: time 1167609663.618515, -------------- SYN_REPORT ------------
109    Event: time 1167609663.730510, type 4 (EV_MSC), code 4 (MSC_SCAN), value 90001
110    Event: time 1167609663.730510, type 1 (EV_KEY), code 272 (BTN_LEFT), value 0
111    Event: time 1167609663.730510, -------------- SYN_REPORT ------------
112
113If your board has more than one button, they will act as right mouse button,
114X-axis movement, and Y-axis movement.
115