Mistake on this page?
Report an issue in GitHub or email us
USBHID.h
1 /*
2  * Copyright (c) 2018-2019, Arm Limited and affiliates.
3  * SPDX-License-Identifier: Apache-2.0
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 
18 #ifndef USB_HID_H
19 #define USB_HID_H
20 
21 /* These headers are included for child class. */
22 #include "USBDescriptor.h"
23 #include "USBDevice.h"
24 
25 #include "USBHID_Types.h"
26 #include "OperationList.h"
27 
28 /**
29  * \defgroup drivers_USBHID USBHID class
30  * \ingroup drivers-public-api-usb
31  * @{
32  */
33 
34 /**
35  * USBHID example
36  * @code
37  * #include "mbed.h"
38  * #include "USBHID.h"
39  *
40  * USBHID hid;
41  * HID_REPORT recv;
42  * BusOut leds(LED1,LED2,LED3,LED4);
43  *
44  * int main(void) {
45  * while (1) {
46  * hid.read(&recv);
47  * leds = recv.data[0];
48  * }
49  * }
50  * @endcode
51  */
52 
53 class USBHID: public USBDevice {
54 public:
55 
56  /**
57  * Basic constructor
58  *
59  * Construct this object optionally connecting and blocking until it is ready.
60  *
61  * @note Do not use this constructor in derived classes.
62  *
63  * @param connect_blocking true to perform a blocking connect, false to start in a disconnected state
64  * @param output_report_length Maximum length of a sent report (up to 64 bytes)
65  * @param input_report_length Maximum length of a received report (up to 64 bytes)
66  * @param vendor_id Your vendor_id
67  * @param product_id Your product_id
68  * @param product_release Your product_release
69  */
70  USBHID(bool connect_blocking = true, uint8_t output_report_length = 64, uint8_t input_report_length = 64, uint16_t vendor_id = 0x1234, uint16_t product_id = 0x0006, uint16_t product_release = 0x0001);
71 
72  /**
73  * Fully featured constructor
74  *
75  * Construct this object with the supplied USBPhy and parameters. The user
76  * this object is responsible for calling connect() or init().
77  *
78  * @note Derived classes must use this constructor and call init() or
79  * connect() themselves. Derived classes should also call deinit() in
80  * their destructor. This ensures that no interrupts can occur when the
81  * object is partially constructed or destroyed.
82  *
83  * @param phy USB phy to use
84  * @param output_report_length Maximum length of a sent report (up to 64 bytes)
85  * @param input_report_length Maximum length of a received report (up to 64 bytes)
86  * @param vendor_id Your vendor_id
87  * @param product_id Your product_id
88  * @param product_release Your product_release
89  */
90  USBHID(USBPhy *phy, uint8_t output_report_length, uint8_t input_report_length, uint16_t vendor_id, uint16_t product_id, uint16_t product_release);
91 
92  /**
93  * Destroy this object
94  *
95  * Any classes which inherit from this class must call deinit
96  * before this destructor runs.
97  */
98  virtual ~USBHID();
99 
100  /**
101  * Check if this class is ready
102  *
103  * @return true if the device is in the configured state
104  */
105  bool ready();
106 
107  /**
108  * Block until this HID device is in the configured state
109  */
110  void wait_ready();
111 
112  /**
113  * Send a Report. warning: blocking
114  *
115  * @param report Report which will be sent (a report is defined by all data and the length)
116  * @returns true if successful
117  */
118  bool send(const HID_REPORT *report);
119 
120 
121  /**
122  * Send a Report. warning: non blocking
123  *
124  * @param report Report which will be sent (a report is defined by all data and the length)
125  * @returns true if successful
126  */
127  bool send_nb(const HID_REPORT *report);
128 
129  /**
130  * Read a report: blocking
131  *
132  * @param report pointer to the report to fill
133  * @returns true if successful
134  */
135  bool read(HID_REPORT *report);
136 
137  /**
138  * Read a report: non blocking
139  *
140  * @param report pointer to the report to fill
141  * @returns true if successful
142  */
143  bool read_nb(HID_REPORT *report);
144 
145 protected:
146  uint16_t reportLength;
147  uint8_t reportDescriptor[27];
148 
149  /*
150  * Get the Report descriptor
151  *
152  * @returns pointer to the report descriptor
153  */
154  virtual const uint8_t *report_desc();
155 
156  /*
157  * Get the length of the report descriptor
158  *
159  * @returns the length of the report descriptor
160  */
161  virtual uint16_t report_desc_length();
162 
163  /*
164  * Get string product descriptor
165  *
166  * @returns pointer to the string product descriptor
167  */
168  virtual const uint8_t *string_iproduct_desc();
169 
170  /*
171  * Get string interface descriptor
172  *
173  * @returns pointer to the string interface descriptor
174  */
175  virtual const uint8_t *string_iinterface_desc();
176 
177  /*
178  * Get configuration descriptor
179  *
180  * @returns pointer to the configuration descriptor
181  */
182  virtual const uint8_t *configuration_desc(uint8_t index);
183 
184 
185  /*
186  * HID Report received by SET_REPORT request. Warning: Called in ISR context
187  * First byte of data will be the report ID
188  *
189  * @param report Data and length received
190  */
191  virtual void HID_callbackSetReport(HID_REPORT *report) {};
192 
193  /**
194  * Called when USB changes state
195  *
196  * @param new_state The new state of the USBDevice
197  *
198  * Warning: Called in ISR context
199  */
200  virtual void callback_state_change(DeviceState new_state);
201 
202  /*
203  * This is used to handle extensions to standard requests
204  * and class specific requests
205  */
206  virtual void callback_request(const setup_packet_t *setup);
207 
208  /*
209  * This is used to handle extensions to standard requests
210  * and class specific requests with a data phase
211  */
212  virtual void callback_request_xfer_done(const setup_packet_t *setup, bool aborted);
213 
214 
215  /*
216  * Called by USBDevice layer. Set configuration of the device.
217  * For instance, you can add all endpoints that you need on this function.
218  *
219  * @param configuration Number of the configuration
220  * @returns true if class handles this request
221  */
222  virtual void callback_set_configuration(uint8_t configuration);
223 
224  /*
225  * Called by USBDevice layer in response to set_interface.
226  *
227  * Upon reception of this command endpoints of any previous interface
228  * if any must be removed with endpoint_remove and new endpoint added with
229  * endpoint_add.
230  *
231  * @param configuration Number of the configuration
232  *
233  * Warning: Called in ISR context
234  */
235  virtual void callback_set_interface(uint16_t interface, uint8_t alternate);
236 
237  /*
238  * Called when there is a hid report that can be read
239  */
240  virtual void report_rx() {}
241 
242  /*
243  * Called when there is space to send a hid report
244  */
245  virtual void report_tx() {}
246 
247 protected:
248  usb_ep_t _int_in;
249  usb_ep_t _int_out;
250 
251 private:
252  void _init(uint8_t output_report_length, uint8_t input_report_length);
253  void _send_isr();
254  void _read_isr();
255 
256  class AsyncSend;
257  class AsyncRead;
258  class AsyncWait;
259 
260  OperationList<AsyncWait> _connect_list;
261  OperationList<AsyncSend> _send_list;
262  bool _send_idle;
263  OperationList<AsyncRead> _read_list;
264  bool _read_idle;
265 
266  uint8_t _configuration_descriptor[41];
267  HID_REPORT _input_report;
268  HID_REPORT _output_report;
269  uint8_t _output_length;
270  uint8_t _input_length;
271 
272 
273 };
274 
275 /** @}*/
276 
277 #endif
USBHID example.
Definition: USBHID.h:53
virtual void callback_request_xfer_done(const setup_packet_t *setup, bool aborted)
Called by USBDevice on data stage completion.
bool send(const HID_REPORT *report)
Send a Report.
virtual void callback_state_change(DeviceState new_state)
Called when USB changes state.
bool read(HID_REPORT *report)
Read a report: blocking.
virtual ~USBHID()
Destroy this object.
void wait_ready()
Block until this HID device is in the configured state.
bool ready()
Check if this class is ready.
bool read_nb(HID_REPORT *report)
Read a report: non blocking.
Abstract interface to physical USB hardware.
Definition: USBPhy.h:82
Core USB Device driver.
Definition: USBDevice.h:38
USBHID(bool connect_blocking=true, uint8_t output_report_length=64, uint8_t input_report_length=64, uint16_t vendor_id=0x1234, uint16_t product_id=0x0006, uint16_t product_release=0x0001)
Basic constructor.
virtual void callback_request(const setup_packet_t *setup)
Called by USBDevice on Endpoint0 request.
bool send_nb(const HID_REPORT *report)
Send a Report.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.