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 
30 /**
31  * USBHID example
32  * @code
33  * #include "mbed.h"
34  * #include "USBHID.h"
35  *
36  * USBHID hid;
37  * HID_REPORT recv;
38  * BusOut leds(LED1,LED2,LED3,LED4);
39  *
40  * int main(void) {
41  * while (1) {
42  * hid.read(&recv);
43  * leds = recv.data[0];
44  * }
45  * }
46  * @endcode
47  */
48 
49 class USBHID: public USBDevice {
50 public:
51 
52  /**
53  * Basic constructor
54  *
55  * Construct this object optionally connecting and blocking until it is ready.
56  *
57  * @note Do not use this constructor in derived classes.
58  *
59  * @param connect_blocking true to perform a blocking connect, false to start in a disconnected state
60  * @param output_report_length Maximum length of a sent report (up to 64 bytes)
61  * @param input_report_length Maximum length of a received report (up to 64 bytes)
62  * @param vendor_id Your vendor_id
63  * @param product_id Your product_id
64  * @param product_release Your product_release
65  */
66  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);
67 
68  /**
69  * Fully featured constructor
70  *
71  * Construct this object with the supplied USBPhy and parameters. The user
72  * this object is responsible for calling connect() or init().
73  *
74  * @note Derived classes must use this constructor and call init() or
75  * connect() themselves. Derived classes should also call deinit() in
76  * their destructor. This ensures that no interrupts can occur when the
77  * object is partially constructed or destroyed.
78  *
79  * @param phy USB phy to use
80  * @param output_report_length Maximum length of a sent report (up to 64 bytes)
81  * @param input_report_length Maximum length of a received report (up to 64 bytes)
82  * @param vendor_id Your vendor_id
83  * @param product_id Your product_id
84  * @param product_release Your product_release
85  */
86  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);
87 
88  /**
89  * Destroy this object
90  *
91  * Any classes which inherit from this class must call deinit
92  * before this destructor runs.
93  */
94  virtual ~USBHID();
95 
96  /**
97  * Check if this class is ready
98  *
99  * @return true if the device is in the configured state
100  */
101  bool ready();
102 
103  /**
104  * Block until this HID device is in the configured state
105  */
106  void wait_ready();
107 
108  /**
109  * Send a Report. warning: blocking
110  *
111  * @param report Report which will be sent (a report is defined by all data and the length)
112  * @returns true if successful
113  */
114  bool send(const HID_REPORT *report);
115 
116 
117  /**
118  * Send a Report. warning: non blocking
119  *
120  * @param report Report which will be sent (a report is defined by all data and the length)
121  * @returns true if successful
122  */
123  bool send_nb(const HID_REPORT *report);
124 
125  /**
126  * Read a report: blocking
127  *
128  * @param report pointer to the report to fill
129  * @returns true if successful
130  */
131  bool read(HID_REPORT *report);
132 
133  /**
134  * Read a report: non blocking
135  *
136  * @param report pointer to the report to fill
137  * @returns true if successful
138  */
139  bool read_nb(HID_REPORT *report);
140 
141 protected:
142  uint16_t reportLength;
143  uint8_t reportDescriptor[27];
144 
145  /*
146  * Get the Report descriptor
147  *
148  * @returns pointer to the report descriptor
149  */
150  virtual const uint8_t *report_desc();
151 
152  /*
153  * Get the length of the report descriptor
154  *
155  * @returns the length of the report descriptor
156  */
157  virtual uint16_t report_desc_length();
158 
159  /*
160  * Get string product descriptor
161  *
162  * @returns pointer to the string product descriptor
163  */
164  virtual const uint8_t *string_iproduct_desc();
165 
166  /*
167  * Get string interface descriptor
168  *
169  * @returns pointer to the string interface descriptor
170  */
171  virtual const uint8_t *string_iinterface_desc();
172 
173  /*
174  * Get configuration descriptor
175  *
176  * @returns pointer to the configuration descriptor
177  */
178  virtual const uint8_t *configuration_desc(uint8_t index);
179 
180 
181  /*
182  * HID Report received by SET_REPORT request. Warning: Called in ISR context
183  * First byte of data will be the report ID
184  *
185  * @param report Data and length received
186  */
187  virtual void HID_callbackSetReport(HID_REPORT *report) {};
188 
189  /**
190  * Called when USB changes state
191  *
192  * @param new_state The new state of the USBDevice
193  *
194  * Warning: Called in ISR context
195  */
196  virtual void callback_state_change(DeviceState new_state);
197 
198  /*
199  * This is used to handle extensions to standard requests
200  * and class specific requests
201  */
202  virtual void callback_request(const setup_packet_t *setup);
203 
204  /*
205  * This is used to handle extensions to standard requests
206  * and class specific requests with a data phase
207  */
208  virtual void callback_request_xfer_done(const setup_packet_t *setup, bool aborted);
209 
210 
211  /*
212  * Called by USBDevice layer. Set configuration of the device.
213  * For instance, you can add all endpoints that you need on this function.
214  *
215  * @param configuration Number of the configuration
216  * @returns true if class handles this request
217  */
218  virtual void callback_set_configuration(uint8_t configuration);
219 
220  /*
221  * Called by USBDevice layer in response to set_interface.
222  *
223  * Upon reception of this command endpoints of any previous interface
224  * if any must be removed with endpoint_remove and new endpoint added with
225  * endpoint_add.
226  *
227  * @param configuration Number of the configuration
228  *
229  * Warning: Called in ISR context
230  */
231  virtual void callback_set_interface(uint16_t interface, uint8_t alternate);
232 
233  /*
234  * Called when there is a hid report that can be read
235  */
236  virtual void report_rx() {}
237 
238  /*
239  * Called when there is space to send a hid report
240  */
241  virtual void report_tx() {}
242 
243 protected:
244  usb_ep_t _int_in;
245  usb_ep_t _int_out;
246 
247 private:
248  void _init(uint8_t output_report_length, uint8_t input_report_length);
249  void _send_isr();
250  void _read_isr();
251 
252  class AsyncSend;
253  class AsyncRead;
254  class AsyncWait;
255 
256  OperationList<AsyncWait> _connect_list;
257  OperationList<AsyncSend> _send_list;
258  bool _send_idle;
259  OperationList<AsyncRead> _read_list;
260  bool _read_idle;
261 
262  uint8_t _configuration_descriptor[41];
263  HID_REPORT _input_report;
264  HID_REPORT _output_report;
265  uint8_t _output_length;
266  uint8_t _input_length;
267 
268 
269 };
270 
271 #endif
USBHID example.
Definition: USBHID.h:49
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:43
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.