* update hid doc and example

Author: lxowalle

docs/doc/en/peripheral/hid.md

@@ -0,0 +1,96 @@
+---
+title: Introduction to Using MaixCAM MaixPy HID Device
+---
+
+
+## 简介
+
+MaixPy currently supports the use of keyboards, mice, and touchscreens, and the following is a guide on how to use maixPy to control your PC via HID.
+
+## Preparation
+
+> MaixPy firmware version should be > 4.1.22 (not included).
+
+You must enable the HID device before operating HID, there are two ways:
+1. Open the `Settings` application that comes with MaixCAM, click `USB Settings` in turn -> tick the required HID devices, such as `Keyboard`, `Mouse`, `Touchscreen`, and then click `Confirm` , then restart MaixCAM.
+2. Through the `Examples/tools/maixcam_switch_usb_mode.py` in MaixVision, modify the HID devices that need to be switched on in the `device_list`, run it and restart MaixCAM.
+Note: Since only 4 USB devices are supported, only 4 devices can be started at the same time among `ncm`, `rndis`, `keyboard`, `mouse`, `touchpad`, choose according to the actual demand, among them, `ncm` and `rndis` are the USB network protocol devices, you can turn them off if you don't need them, by default, they are turned on.
+
+## Write a keyboard in MaixPy.
+
+You need to enable `HID Keyboard` to run it.
+
+The following example sends `rstuv` four characters through the keyboard and then releases the key.
+
+```python
+from maix import hid, time
+
+keyboard = hid.Hid(hid.DeviceType.DEVICE_KEYBOARD)
+
+# Refer to the `Universal Serial Bus HID Usage Tables` section of the [USB HID Documentation](https://www.usb.org) for key numbers.
+keys = [21, 22, 23, 24, 25, 0]   # means [r, s, t, u, v, 0], 0 means release key.
+
+for key in keys:
+    keyboard.write([0, 0, key, 0, 0, 0, 0, 0])
+
+```
+
+## Write a mouse in MaixPy.
+
+You need to enable `HID Mouse` to run it.
+
+The following example moves the mouse 5 pixels every 100ms.
+
+```python
+from maix import hid, time
+
+mouse = hid.Hid(hid.DeviceType.DEVICE_MOUSE)
+
+button = 0      # button state, 0 means release, 1 means left button pressed, 2 means right button pressed, 4 means wheel button pressed
+x_oft = 0       # offset relative to current position, value range is -127~127
+y_oft = 0       # offset relative to current position, value range is -127~127
+wheel_move = 0  # The distance the wheel has moved, the range of values is -127~127
+
+count = 0
+while True:
+    x_oft += 5
+    y_oft += 5
+    mouse.write([button, x_oft, y_oft, wheel_move])
+    time.sleep_ms(100)
+    count += 1
+    if count > 50:
+        break
+```
+
+## Write a touchpad in MaixPy.
+
+The `HID Touchpad` needs to be enabled to run.
+
+In the following example, move the touchscreen 150 units every 100ms. Note that the coordinate system of the touchscreen is absolute, not relative, and that you need to map the actual size of the screen to the interval [1, 0x7FFF], the coordinates (1,1) means the upper left corner, the coordinates (0x7FFF,0x7FFF) means the lower right corner.
+
+```python
+from maix import hid, time
+
+touchpad = hid.Hid(hid.DeviceType.DEVICE_TOUCHPAD)
+
+def touchpad_set(button, x_oft, y_oft, wheel_move):
+    touchpad.write([button,                             # button state, 0 means release, 1 means left button pressed, 2 means right button pressed, 4 means wheel button pressed
+                    x_oft & 0xff, (x_oft >> 8) & 0xff,  # Absolute position, the leftmost is 1, the rightmost is 0x7fff, 0 means no operation, the value range is 0 to 0x7fff.
+                    y_oft & 0xff, (y_oft >> 8) & 0xff,  # Absolute position, the topmost is 1, the bottom is 0x7fff, 0 means no operation, the value range is 0 to 0x7fff
+                    wheel_move])                        # wheel move distance, value range is -127~127
+button = 0
+x_oft = 0
+y_oft = 0
+wheel_move = 0
+count = 0
+while True:
+    x_oft += 150
+    y_oft += 150
+    touchpad_set(button, x_oft, y_oft, wheel_move)
+    time.sleep_ms(100)
+    count += 1
+    if count > 50:
+        break
+```
+
+

docs/doc/en/sidebar.yaml

@@ -148,6 +148,8 @@ items:
         label: WDT watchdog
     -   file: peripheral/adc.md
         label: ADC
+    -   file: peripheral/hid.md
+        label: HID
 
 -   label: Off-chip modules
     items:

docs/doc/zh/peripheral/hid.md

@@ -0,0 +1,93 @@
+---
+title: MaixCAM MaixPy 使用 HID 设备
+---
+
+## 简介
+
+HID（Human Interface Device）设备是一类计算机外围设备，用于向计算机传输输入数据，或从计算机接收输出数据。HID 设备最常见的例子包括键盘、鼠标、游戏控制器、触摸屏、和手写板等。HID 协议是一种用于人机交互设备的通信协议，它允许这些设备通过 USB、蓝牙或其他连接方式与主机进行数据交换。MaixPy目前支持作为键盘、鼠标和触摸屏来使用，下面将会介入如何使用MaixPy通过HID来控制你的个人电脑～
+
+## 一定要操作的前期准备
+
+> MaixPy 固件版本应该 > 4.1.22(不包含)
+
+在操作HID前一定要先使能HID设备，有两种方法：
+1. 打开MaixCAM自带的`Settings`应用，依次点击`USB Settings`->勾选需要的HID设备，如`Keyboard`、`Mouse`、`Touchscreen`，然后点击`Confirm`后重启MaixCAM
+2. 通过MaixVision中的`Examples/tools/maixcam_switch_usb_mode.py`示例，修改代码`device_list`中需要开启的HID设备，运行后重启MaixCAM
+注意：由于最多只支持4个USB设备，因此在`ncm`，`rndis`，`keyboard`，`mouse`，`touchpad`之中只能同时启动4个设备，根据实际需求选择，其中`ncm`和`rndis`是USB网络协议设备，如果不需要可以关掉，默认是打开的。
+
+## 用MaixPy编写一个键盘
+
+需要使能了`HID Keyboard`后才能运行。
+
+下面示例中，通过键盘发送`rstuv`四个字符，然后松开按键。
+
+```python
+from maix import hid, time
+
+keyboard = hid.Hid(hid.DeviceType.DEVICE_KEYBOARD)
+
+# 按键编号参考[USB HID文档](https://www.usb.org))的"Universal Serial Bus HID Usage Tables"部分
+keys = [21, 22, 23, 24, 25, 0]    # 表示[r, s, t, u, v, 0], 0表示松开按键
+
+for key in keys:
+    keyboard.write([0, 0, key, 0, 0, 0, 0, 0])
+
+```
+
+## 用MaixPy编写一个鼠标
+
+需要使能了`HID Mouse`后才能运行。
+
+下面示例中，每隔100ms移动鼠标5个像素。
+
+```python
+from maix import hid, time
+
+mouse = hid.Hid(hid.DeviceType.DEVICE_MOUSE)
+
+button = 0      # 按键状态，0表示松开，1表示按下左键，2表示按下右键，4表示按下滚轮键
+x_oft = 0       # 相对当前位置的偏移量，数值范围是-127~127
+y_oft = 0       # 相对当前位置的偏移量，数值范围是-127~127
+wheel_move = 0  # 滚轮移动距离，数值范围是-127~127
+
+count = 0
+while True:
+    x_oft += 5
+    y_oft += 5
+    mouse.write([button, x_oft, y_oft, wheel_move])
+    time.sleep_ms(100)
+    count += 1
+    if count > 50:
+        break
+```
+
+## 用MaixPy编写一个触摸屏
+
+需要使能了`HID Touchpad`后才能运行。
+
+下面示例中，每隔100ms移动触摸屏150个单位，注意触摸屏的坐标系是绝对坐标，而不是相对坐标，另外需要将屏幕实际尺寸映射到[1, 0x7FFF]区间，坐标(1,1)表示左上角，坐标(0x7FFF,0x7FFF)表示右下角。
+
+```python
+from maix import hid, time
+
+touchpad = hid.Hid(hid.DeviceType.DEVICE_TOUCHPAD)
+
+def touchpad_set(button, x_oft, y_oft, wheel_move):
+    touchpad.write([button,                             # 按键状态，0表示松开，1表示按下左键，2表示按下右键，4表示按下滚轮键
+                    x_oft & 0xff, (x_oft >> 8) & 0xff,  # 绝对位置，最左为1, 最右为0x7fff，0表示不操作，数值范围是0～0x7fff
+                    y_oft & 0xff, (y_oft >> 8) & 0xff,  # 绝对位置，最上为1, 最下为0x7fff，0表示不操作，数值范围是0～0x7fff
+                    wheel_move])                        # 滚轮移动距离，数值范围是-127~127
+button = 0
+x_oft = 0
+y_oft = 0
+wheel_move = 0
+count = 0
+while True:
+    x_oft += 150
+    y_oft += 150
+    touchpad_set(button, x_oft, y_oft, wheel_move)
+    time.sleep_ms(100)
+    count += 1
+    if count > 50:
+        break
+```

docs/doc/zh/sidebar.yaml

@@ -148,6 +148,8 @@ items:
         label: WDT 看门狗使用
     -   file: peripheral/adc.md
         label: ADC 使用
+    -   file: peripheral/hid.md
+        label: HID Device 使用
 
 -   label: 片外模块
     items:

examples/peripheral/usb/hid_keyboard.py

@@ -0,0 +1,19 @@
+from maix import hid, time
+
+keyboard = None
+try:
+    keyboard = hid.Hid(hid.DeviceType.DEVICE_KEYBOARD)
+except Exception as e:
+    print(e)
+    print('The HID evice is not enabled')
+    print('Try: Use the application Settings -> USB Settings -> HID Keyboard, then click Confirm, and restart the system.')
+    print('You can also use examples/tools/maixcam_switch_usb_mode.py to enable the HID Keyboard, then restart the system.')
+    exit(0)
+
+# Refer to the "Universal Serial Bus HID Usage Tables" section of the official documentation(https://www.usb.org).
+keys = [21, 22, 23, 24, 25, 0]    # [r, s, t, u, v, 0], 0 means release. 
+
+for key in keys:
+    keyboard.write([0, 0, key, 0, 0, 0, 0, 0])
+
+print('OK')

examples/peripheral/usb/hid_mouse.py

@@ -0,0 +1,28 @@
+from maix import hid, time
+
+mouse = None
+try:
+    mouse = hid.Hid(hid.DeviceType.DEVICE_MOUSE)
+except Exception as e:
+    print(e)
+    print('The HID evice is not enabled')
+    print('Try: Use the application Settings -> USB Settings -> HID Mouse, then click Confirm, and restart the system.')
+    print('You can also use examples/tools/maixcam_switch_usb_mode.py to enable the HID Mouse, then restart the system.')
+    exit(0)
+
+button = 0
+x_oft = 0
+y_oft = 0
+wheel_move = 0
+
+count = 0
+while True:
+    x_oft += 5
+    y_oft += 5
+    mouse.write([button, x_oft, y_oft, wheel_move])
+    time.sleep_ms(100)
+    count += 1
+    if count > 50:
+        break
+
+print('OK')

examples/peripheral/usb/hid_touchpad.py

@@ -0,0 +1,33 @@
+from maix import hid, time
+
+touchpad = None
+try:
+    touchpad = hid.Hid(hid.DeviceType.DEVICE_TOUCHPAD)
+except Exception as e:
+    print(e)
+    print('The HID evice is not enabled')
+    print('Try: Use the application Settings -> USB Settings -> HID Touchpad, then click Confirm, and restart the system.')
+    print('You can also use examples/tools/maixcam_switch_usb_mode.py to enable the HID Touchpad, then restart the system.')
+    exit(0)
+
+def touchpad_set(button, x_oft, y_oft, wheel_move):
+    touchpad.write([button,
+                    x_oft & 0xff, (x_oft >> 8) & 0xff,
+                    y_oft & 0xff, (y_oft >> 8) & 0xff, 
+                    wheel_move])
+button = 0
+x_oft = 0
+y_oft = 0
+wheel_move = 0
+
+count = 0
+while True:
+    x_oft += 150
+    y_oft += 150
+    touchpad_set(button, x_oft, y_oft, wheel_move)
+    time.sleep_ms(100)
+    count += 1
+    if count > 50:
+        break
+
+print('OK')