Skip to content

Commit 99bdc16

Browse files
hlym123lbuque
hlym123
authored and
lbuque
committed
libs/module: Add Module USB Support.
Signed-off-by: hlym123 <[email protected]>
1 parent 64686eb commit 99bdc16

28 files changed

+5757
-258
lines changed

‎docs/en/module/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,4 +29,5 @@ Module
2929
rs232.rst
3030
servo2.rst
3131
step_motor_driver.rst
32+
usb.rst
3233
zigbee.rst

‎docs/en/module/usb.rst‎

Lines changed: 246 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,246 @@
1+
USB Module
2+
=====================================
3+
4+
.. include:: ../refs/module.usb.ref
5+
6+
The USB Module is a module that uses the SPI interface to expand USB functionality, implemented with the MAX3421E.
7+
8+
Support the following products:
9+
10+
|USB Module|
11+
12+
13+
Micropython Example
14+
--------------------------------
15+
16+
.. note:: Before using the following examples, please check the DIP switches on the module to ensure that the pins used in the example match the DIP switch positions. For specific configurations, please refer to the product manual page. The SPI configuration has been implemented internally, so users do not need to worry about it.
17+
18+
Input/Output Pin Control
19+
++++++++++++++++++++++++++++
20+
The module exposes 5 IN (input) pins and 5 OUT (output) pins through headers. This example demonstrates controlling the high and low level switching of the output pins, as well as reading and printing the level status of the input pins.
21+
22+
.. literalinclude:: ../../../examples/module/usb/cores3_module_usb_gpio_example.py
23+
:language: python
24+
:linenos:
25+
26+
Mouse
27+
++++++++++++++++++++++++++++
28+
Implementing USB host to capture mouse input
29+
30+
.. literalinclude:: ../../../examples/module/usb/cores3_module_usb_mouse_example.py
31+
:language: python
32+
:linenos:
33+
34+
Keyboard
35+
++++++++++++++++++++++++++++
36+
Implementing USB host to capture keyboard input
37+
38+
.. literalinclude:: ../../../examples/module/usb/cores3_module_usb_kb_example.py
39+
:language: python
40+
:linenos:
41+
42+
43+
UIFlow2.0 Example
44+
--------------------------------
45+
46+
Input/Output Pin Control
47+
++++++++++++++++++++++++++++
48+
49+
50+
|gpio_example.png|
51+
52+
.. only:: builder_html
53+
54+
|cores3_module_usb_gpio_example.m5f2|
55+
56+
57+
Mouse
58+
++++++++++++++++++++++++++++
59+
60+
|mouse_example.png|
61+
62+
.. only:: builder_html
63+
64+
|cores3_module_usb_mouse_example.m5f2|
65+
66+
Keyboard
67+
++++++++++++++++++++++++++++
68+
69+
|kb_example.png|
70+
71+
.. only:: builder_html
72+
73+
|cores3_module_usb_kb_example.m5f2|
74+
75+
76+
77+
78+
class USBModule
79+
------------------------------
80+
81+
Constructors
82+
------------------------------
83+
84+
.. class:: USBModule(pin_cs: int = 1, pin_int: int = 10)
85+
86+
:param int pin_cs: (RST) 复位引脚
87+
:param int pin_irq: (INT) 中断引脚
88+
89+
UIFLOW2:
90+
91+
|init.png|
92+
93+
.. method:: poll_data()
94+
95+
poll data
96+
97+
**Note**: It needs to be called in the main loop
98+
99+
UIFlow2.0
100+
101+
|poll_data.png|
102+
103+
104+
.. method:: is_left_btn_pressed() -> bool
105+
106+
Check if the left mouse button is pressed.
107+
108+
UIFlow2.0
109+
110+
|is_left_btn_pressed.png|
111+
112+
.. method:: is_right_btn_pressed() -> bool
113+
114+
Check if the right mouse button is pressed.
115+
116+
UIFlow2.0
117+
118+
|is_right_btn_pressed.png|
119+
120+
.. method:: is_middle_btn_pressed() -> bool
121+
122+
Check if the middle mouse button is pressed.
123+
124+
UIFlow2.0
125+
126+
|is_middle_btn_pressed.png|
127+
128+
.. method:: is_forward_btn_pressed() -> bool
129+
130+
Check if the forward mouse button is pressed.
131+
132+
UIFlow2.0
133+
134+
|is_forward_btn_pressed.png|
135+
136+
.. method:: is_back_btn_pressed() -> bool
137+
138+
Check if the back mouse button is pressed.
139+
140+
UIFlow2.0
141+
142+
|is_back_btn_pressed.png|
143+
144+
145+
.. method:: read_mouse_move() -> tuple[int, int]
146+
147+
Read Mouse Cursor Movement
148+
149+
Returns a tuple (x, y) containing the horizontal displacement x and vertical displacement y of the mouse;
150+
x range: -127 to 127; 0 indicates no movement, negative values indicate movement to the left, and positive values indicate movement to the right;
151+
y range: -127 to 127; 0 indicates no movement, negative values indicate movement upward, and positive values indicate movement downward.
152+
153+
**Example:**
154+
155+
::
156+
157+
move = usb_module.read_mouse_move()
158+
x = move[0]
159+
y = move[1]
160+
161+
162+
UIFlow2.0
163+
164+
|read_mouse_move.png|
165+
166+
.. method:: read_wheel_move() -> int
167+
168+
Read Mouse Wheel Movement
169+
170+
Returns a value in the range of -127 to 127, 0 indicates no movement, Positive values indicate forward scrolling, Negative values indicate backward scrolling.
171+
172+
UIFlow2.0
173+
174+
|read_wheel_move.png|
175+
176+
177+
.. method:: read_kb_input(convert: bool = True) -> list
178+
179+
Read keyboard input
180+
181+
- ``convert`` Whether to convert HID Keycode to the corresponding string.
182+
183+
Returns a list containing keyboard inputs (up to 6 elements, meaning a maximum of 6 key values can be input at once).
184+
185+
**Example:**
186+
187+
::
188+
189+
res = usb_module.read_kb_input(convert=True)
190+
# output ['a', 'b', 'Enter']
191+
192+
res = usb_module.read_kb_input(convert=False)
193+
# output [0x04, 0x05, 0x28]
194+
195+
UIFlow2.0
196+
197+
|read_kb_input.png|
198+
199+
.. method:: read_kb_modifier() -> int
200+
201+
Read the keyboard modifier keys, namely "Ctrl", "Shift", "Alt", and "Win" keys.
202+
203+
- ``Return``: The status of the keyboard modifier keys, usually represented by a bit mask to indicate the status of different modifier keys.
204+
- 0x01: Left Control key
205+
- 0x02: Left Shift key
206+
- 0x04: Left Alt key
207+
- 0x08: Left Windows key (Left GUI)
208+
- 0x10: Right Control key
209+
- 0x20: Right Shift key
210+
- 0x40: Right Alt key
211+
- 0x80: Right Windows key (Right GUI)
212+
213+
**Example:**
214+
215+
::
216+
217+
modifier = module_usb.read_kb_modifier()
218+
if modifier & 0x01:
219+
print("left ctrl key pressed")
220+
221+
UIFlow2.0
222+
223+
|read_kb_modifier.png|
224+
225+
.. method:: read_gpin(pin) -> int
226+
227+
Read input pin value
228+
229+
- ``pin`` pin number
230+
- ``Return`` 1 represents high level, and 0 represents low level.
231+
232+
UIFlow2.0
233+
234+
|read_gpin.png|
235+
236+
.. method:: write_gpout(pin, value)
237+
238+
Write output pin value
239+
240+
- ``pin`` pin number
241+
- ``Return`` 1 represents high level, and 0 represents low level.
242+
243+
UIFlow2.0
244+
245+
|write_gpout.png|
246+

‎docs/en/refs/module.usb.ref‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
.. |USB Module| image:: https://static-cdn.m5stack.com/resource/docs/products/module/USB%20v1.2%20Module/img-2b9ca068-4799-46ee-a4f1-e7abc5314e7a.webp
2+
:target: https://docs.m5stack.com/zh_CN/module/USB%20v1.2%20Module
3+
:height: 200px
4+
:width: 200px
5+
6+
.. |init.png| image:: https://static-cdn.m5stack.com/mpy_docs/module/usb/init.png
7+
.. |read_gpin.png| image:: https://static-cdn.m5stack.com/mpy_docs/module/usb/read_gpin.png
8+
.. |poll_data.png| image:: https://static-cdn.m5stack.com/mpy_docs/module/usb/poll_data.png
9+
.. |write_gpout.png| image:: https://static-cdn.m5stack.com/mpy_docs/module/usb/write_gpout.png
10+
.. |is_left_btn_pressed.png| image:: https://static-cdn.m5stack.com/mpy_docs/module/usb/is_left_btn_pressed.png
11+
.. |is_right_btn_pressed.png| image:: https://static-cdn.m5stack.com/mpy_docs/module/usb/is_right_btn_pressed.png
12+
.. |is_middle_btn_pressed.png| image:: https://static-cdn.m5stack.com/mpy_docs/module/usb/is_middle_btn_pressed.png
13+
.. |is_forward_btn_pressed.png| image:: https://static-cdn.m5stack.com/mpy_docs/module/usb/is_forward_btn_pressed.png
14+
.. |is_back_btn_pressed.png| image:: https://static-cdn.m5stack.com/mpy_docs/module/usb/is_back_btn_pressed.png
15+
.. |read_mouse_move.png| image:: https://static-cdn.m5stack.com/mpy_docs/module/usb/read_mouse_move.png
16+
.. |read_wheel_move.png| image:: https://static-cdn.m5stack.com/mpy_docs/module/usb/read_wheel_move.png
17+
.. |read_kb_input.png| image:: https://static-cdn.m5stack.com/mpy_docs/module/usb/read_kb_input.png
18+
.. |read_kb_modifier.png| image:: https://static-cdn.m5stack.com/mpy_docs/module/usb/read_kb_modifier.png
19+
.. |gpio_example.png| image:: https://static-cdn.m5stack.com/mpy_docs/module/usb/gpio_example.png
20+
.. |kb_example.png| image:: https://static-cdn.m5stack.com/mpy_docs/module/usb/kb_example.png
21+
.. |mouse_example.png| image:: https://static-cdn.m5stack.com/mpy_docs/module/usb/mouse_example.png
22+
23+
.. |cores3_module_usb_gpio_example.m5f2| raw:: html
24+
25+
<a
26+
href="https://uiflow2.m5stack.com/?example=https://raw.githubusercontent.com/m5stack/uiflow-micropython/develop/examples/module/usb/cores3_module_usb_gpio_example.m5f2"
27+
target="_blank"
28+
>
29+
cores3_module_usb_gpio_example.m5f2
30+
</a>
31+
32+
.. |cores3_module_usb_mouse_example.m5f2| raw:: html
33+
34+
<a
35+
href="https://uiflow2.m5stack.com/?example=https://raw.githubusercontent.com/m5stack/uiflow-micropython/develop/examples/module/usb/cores3_module_usb_mouse_example.m5f2"
36+
target="_blank"
37+
>
38+
cores3_module_usb_mouse_example.m5f2
39+
</a>
40+
41+
.. |cores3_module_usb_kb_example.m5f2| raw:: html
42+
43+
<a
44+
href="https://uiflow2.m5stack.com/?example=https://raw.githubusercontent.com/m5stack/uiflow-micropython/develop/examples/module/usb/cores3_module_usb_kb_example.m5f2"
45+
target="_blank"
46+
>
47+
cores3_module_usb_kb_example.m5f2
48+
</a>
49+

0 commit comments

Comments
 (0)