optimize examples and add key documentation

docs/doc/en/gui/i18n.md

@@ -19,6 +19,7 @@ The general user process is as follows:
 
 For applications, the tricky part is the third step, which involves looking up the corresponding strings based on the locale settings. Here are two methods to achieve this, depending on your needs:
 
+Full example code in [MaixPy](https://github.com/sipeed/MaixPy) `examples/gui/i18n`.
 ### Using a Dictionary Directly Without Translation Files
 
 If your program only has a few strings, you can manually specify the translation dictionary:

docs/doc/en/modules/pmu.md

@@ -65,7 +65,7 @@ while not app.need_exit():
     time.sleep_ms(1000)
 ```
 
-> You can also use the `AXP2101` module to configure the power management unit. The usage is similar to the `PMU` module, and you can refer to the example script [axp2101_example.py](https://github.com/sipeed/MaixPy/blob/main/examples/ext_dev/others/pmu_axp2101/axp2101_example.py) for guidance.
+> You can also use the `AXP2101` module to configure the power management unit. The usage is similar to the `PMU` module, and you can refer to the example script [axp2101_example.py](https://github.com/sipeed/MaixPy/blob/main/examples/ext_dev/pmu/pmu_axp2101/axp2101_example.py) for guidance.
 
 Initialize the `PMU` object, and call `get_bat_percent()` to get the current battery level. Call `set_bat_charging_cur()` to set the maximum charging current.
 

docs/doc/en/peripheral/hid.md

@@ -1,11 +1,13 @@
 ---
-title: Introduction to Using MaixCAM MaixPy HID Device
+title: Introduction to Using MaixCAM MaixPy USB HID (as 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.
+MaixPy currently supports simulate as USB HID device like keyboards, mice, and touchscreens, and the following is a guide on how to use maixPy to control your PC via HID.
+
+> If you want to use USB as host to connect HID devices into MaixCAM, set USB mode to HOST mode in `settings`.
 
 ## Preparation
 

docs/doc/en/peripheral/key.md

@@ -0,0 +1,98 @@
+---
+title: Using Key Events in MaixCAM MaixPy
+update:
+  - date: 2025-01-08
+    version: v1.0
+    author: neucrack
+    content: Added documentation
+---
+
+## Introduction
+
+MaixCAM is equipped with built-in buttons, including the user/ok button and the power button.  
+By default, the user/ok button acts as an exit button in MaixPy. Pressing it automatically calls `maix.app.set_exit_flag(True)`.  
+If your program relies on `maix.app.need_exit()` to determine when to exit, pressing the button will cause the program to terminate.
+
+Additionally, you can customize the button's behavior. Once customized, the default behavior of setting the exit flag will be disabled.
+
+## Reading Key Events in MaixCAM MaixPy
+
+### Default Behavior: Exit Flag Set When Button is Pressed
+
+The default behavior works without explicit function calls:
+```python
+from maix import app, time
+
+cout = 0
+while not app.need_exit():
+    time.sleep(1)
+    print(cout)
+    cout += 1
+```
+Pressing the button will exit the loop.
+
+### Reading Key Events and Customizing Callback Functions
+
+You can use the `key.Key` class to handle key events. The callback function takes two parameters:
+- `key_id`: The key's ID. Refer to [maix.key.Keys API Documentation](/api/maix/peripheral/key.html#Keys). For custom drivers, the ID depends on the driver.
+- `state`: The key's state. Refer to [maix.key.State API Documentation](/api/maix/peripheral/key.html#State).
+
+Example:
+```python
+from maix import key, app
+
+def on_key(self, key_id, state):
+    '''
+        This function is called in a single thread
+    '''
+    print(f"key: {key_id}, state: {state}") # e.g., key.c or key.State.KEY_RELEASED
+
+key_obj = key.Key(on_key)
+
+while not app.need_exit():
+    time.sleep(1)
+```
+
+A more complete example:
+```python
+from maix import image, key, app, display
+
+class App:
+    def __init__(self):
+        self.key_obj = key.Key(self.on_key)
+        self.disp = display.Display()
+        self.key_id = 0
+        self.state = 0
+
+    def on_key(self, key_id, state):
+        '''
+            This function is called in a single thread
+        '''
+        print(f"key: {key_id}, state: {state}") # e.g., key.c or key.State.KEY_RELEASED
+        self.key_id = key_id
+        self.state = state
+
+    def run(self):
+        while not app.need_exit():
+            img = image.Image(self.disp.width(), self.disp.height(), image.Format.FMT_RGB888)
+            msg = f"key: {self.key_id}, state: {self.state}"
+            img.draw_string(0, 10, msg, image.Color.from_rgb(255, 255, 255), 1.5)
+            self.disp.show(img)
+
+App().run()
+```
+
+## Customizing Key Drivers
+
+MaixPy is based on a Linux system, allowing you to write custom key drivers. You can add your custom key devices to the `key_devices` field in `/boot/board`. Multiple devices are supported and can be separated by commas, e.g.:  
+`key_devices:/dev/my_keys1,/dev/my_keys2`.
+
+### Driver Development Methods
+
+1. **Kernel Driver**  
+   Follow the standard Linux driver development process, using a cross-compilation toolchain to compile a `.ko` driver file. Load the driver automatically at boot via `/etc/init.d`.
+
+2. **User-Space Driver**  
+   For buttons connected to GPIO pins, you can write a user-space driver using the GPIO API. Use `/dev/uinput` to export a device file.  
+   - This approach requires a program to continuously read GPIO inputs.  
+   - The program can be integrated into your main application or run as a standalone background process, offering flexibility.

docs/doc/zh/gui/i18n.md

@@ -22,6 +22,8 @@ i18n 是国际化单词（internationalization）的简称，目的在与根据
 
 对于应用程序来说，比较麻烦的地方就在这里的第三步，即根据地域设置查表获取对应的字符串，下面提供两种方法，根据自己的需求选择：
 
+完整的例程源码在[MaixPy](https://github.com/sipeed/MaixPy) `examples/gui/i18n`中。
+
 ### 不使用翻译文件，直接使用字典
 
 如果你的程序只有几个字符串，可以直接手动指定翻译字典：

docs/doc/zh/modules/pmu.md

@@ -65,7 +65,7 @@ while not app.need_exit():
     time.sleep_ms(1000)
 ```
 
-> 也可以使用 `AXP2101` 模块对电源管理单元进行设置。使用方法和 `PMU` 模块类似，可以参考例程 [axp2101_example.py](https://github.com/sipeed/MaixPy/blob/main/examples/ext_dev/others/pmu_axp2101/axp2101_example.py)
+> 也可以使用 `AXP2101` 模块对电源管理单元进行设置。使用方法和 `PMU` 模块类似，可以参考例程 [axp2101_example.py](https://github.com/sipeed/MaixPy/blob/main/examples/ext_dev/pmu/pmu_axp2101/axp2101_example.py)
 
 初始化 `PMU` 对象，调用 `get_bat_percent()` 即可获取当前电池电量。调用 `set_bat_charging_cur()` 可以设置最大充电电流。
 

docs/doc/zh/peripheral/hid.md

@@ -1,10 +1,13 @@
 ---
-title: MaixCAM MaixPy 使用 HID 设备
+title: MaixCAM MaixPy 使用 USB HID（作为设备）
 ---
 
 ## 简介
 
-HID（Human Interface Device）设备是一类计算机外围设备，用于向计算机传输输入数据，或从计算机接收输出数据。HID 设备最常见的例子包括键盘、鼠标、游戏控制器、触摸屏、和手写板等。HID 协议是一种用于人机交互设备的通信协议，它允许这些设备通过 USB、蓝牙或其他连接方式与主机进行数据交换。MaixPy目前支持作为键盘、鼠标和触摸屏来使用，下面将会介入如何使用MaixPy通过HID来控制你的个人电脑～
+HID（Human Interface Device）设备是一类计算机外围设备，用于向计算机传输输入数据，或从计算机接收输出数据。HID 设备最常见的例子包括键盘、鼠标、游戏控制器、触摸屏、和手写板等。HID 协议是一种用于人机交互设备的通信协议，它允许这些设备通过 USB、蓝牙或其他连接方式与主机进行数据交换。
+MaixPy目前支持作为 USB HID 设备，比如作为键盘、鼠标和触摸屏给电脑使用，下面将会介入如何使用 MaixPy 通过 HID 来控制你的个人电脑～
+
+> 如果你想将 USB 作为 host 模式以连接 HID 设备到 MaixCAM, 则在 `设置` 应用中将 USB 模式设置为 `host`模式即可。
 
 ## 一定要操作的前期准备
 

docs/doc/zh/peripheral/key.md

@@ -0,0 +1,96 @@
+---
+title: MaixCAM MaixPy 按键事件使用
+update:
+  - date: 2025-01-08
+    version: v1.0
+    author: neucrack
+    content: 添加文档
+---
+
+## 简介
+
+MaixCAM 机身自带了按键，包括 user/ok 按键，电源按键等。
+默认 user/ok 按键在 MaixPy 中是退出按钮，按下会自动调用`maix.app.set_exit_flag(True)`，如果你的程序调用了`maix.app.need_exit()`作为退出依据，则按下按键就会退出程序。
+
+另外，你也可以自定义按键的作用，自定义后上面说的默认的设置退出标志行为就会取消。
+
+
+## MaixCAM MaixPy 中读取按键
+
+### 默认行为，即按下会设置程序退出标志
+
+无需显示调用，默认就有：
+```python
+from maix import app, time
+
+cout = 0
+while not app.need_exit():
+    time.sleep(1)
+    print(cout)
+    cout +=1
+```
+按下按键就会退出循环了。
+
+### 读取按键事件和自定义回调函数
+
+使用`key.Key`类即可，回调函数有两个参数：
+* `key_id`: 按键 ID，取值看[maix.key.Keys API 文档](/api/maix/peripheral/key.html#Keys)，自定义的驱动由驱动决定。
+* `state`: 按键状态，取值看[maix.key.State API 文档](/api/maix/peripheral/key.html#State)。
+
+
+```python
+from maix import key, app
+
+def on_key(self, key_id, state):
+    '''
+        this func called in a single thread
+    '''
+    print(f"key: {key_id}, state: {state}") # key.c or key.State.KEY_RELEASED
+
+key_obj = key.Key(on_key)
+
+while not app.need_exit():
+    time.sleep(1)
+```
+
+完善一些的例程：
+
+```python
+from maix import image, key, app, display
+
+class App:
+    def __init__(self):
+        self.key_obj = key.Key(self.on_key)
+        self.disp = display.Display()
+        self.key_id = 0
+        self.state = 0
+
+    def on_key(self, key_id, state):
+        '''
+            this func called in a single thread
+        '''
+        print(f"key: {key_id}, state: {state}") # key.c or key.State.KEY_RELEASED
+        self.key_id = key_id
+        self.state = state
+
+    def run(self):
+        while not app.need_exit():
+            img = image.Image(self.disp.width(), self.disp.height(), image.Format.FMT_RGB888)
+            msg = f"key: {self.key_id}, state: {self.state}"
+            img.draw_string(0, 10, msg, image.Color.from_rgb(255, 255, 255), 1.5)
+            self.disp.show(img)
+
+App().run()
+
+```
+
+## 自定义按键驱动
+
+MaixPy 基于 Linux 系统，你可以给系统编写按键驱动，然后在`/boot/board` 里面将自己的按键设备添加到`key_devices`键值中，支持多个设备，多个设备用逗号隔开，比如：
+`key_devices:/dev/my_keys1,/dev/my_keys2`。
+
+驱动编写方法：
+* 方法一：内核驱动，按照通用的 Linux 驱动开发方法，使用交叉编译工具链编译出 `ko`驱动文件，开机在`/etc/init.d` 中自动加载。
+* 方法二：用户层驱动，比如你的按键接到了 GPIO 上，可以直接基于 GPIO API 编写，使用`/dev/uinput`导出一个设备文件即可，具体方法可以自行搜索，这种方法需要有读取 GPIO 代码一直在运行，可以和你的程序写到一起，也可以单独写一个程序运行在后台，比较灵活。
+
+

examples/basic/0_hello.py

@@ -0,0 +1,3 @@
+
+print("hello MaixPy!")
+