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