feat(twai): add cybergear example

Author: Kainarx

docs/en/api-reference/peripherals/twai.rst

@@ -375,6 +375,7 @@ Application Examples
     - :example:`peripherals/twai/twai_utils` demonstrates how to use the TWAI (Two-Wire Automotive Interface) APIs to create a command-line interface for TWAI bus communication, supporting frame transmission/reception, filtering, monitoring, and both classic and FD formats for testing and debugging TWAI networks.
     - :example:`peripherals/twai/twai_error_recovery` demonstrates how to recover nodes from the bus-off state and resume communication, as well as bus error reporting, node state changes, and other event information.
     - :example:`peripherals/twai/twai_network` using 2 nodes with different roles: transmitting and listening, demonstrates how to use the driver for single and bulk data transmission, as well as configure filters to receive these data.
+    - :example:`peripherals/twai/cybergear` demonstrates how to control XiaoMi CyberGear motors via TWAI interface.
 
 API Reference
 -------------

docs/zh_CN/api-reference/peripherals/twai.rst

@@ -375,6 +375,7 @@ TWAI控制器能够检测由于总线干扰产生的/损坏的不符合帧格式
     - :example:`peripherals/twai/twai_utils` 演示了如何使用 TWAI（Two-Wire Automotive Interface，双线汽车接口）API 创建一个命令行工具，用于 TWAI 总线通信，支持帧的发送/接收、过滤、监控，以及经典和 FD 格式，以便测试和调试 TWAI 网络。
     - :example:`peripherals/twai/twai_error_recovery` 演示了总线错误上报，节点状态变化等事件信息，以及如何从离线状态恢复节点并重新进行通信。
     - :example:`peripherals/twai/twai_network` 通过发送、监听， 2 个不同角色的节点，演示了如何使用驱动程序进行单次的和大量的数据发送，以及配置过滤器以接收这些数据。
+    - :example:`peripherals/twai/cybergear` 演示了如何通过 TWAI 接口控制 XiaoMi CyberGear 电机。
 
 API 参考
 --------

examples/peripherals/.build-test-rules.yml

@@ -503,6 +503,12 @@ examples/peripherals/touch_sensor/touch_sens_sleep:
   depends_components:
     - esp_driver_touch_sens
 
+examples/peripherals/twai/cybergear:
+  disable:
+    - if: SOC_TWAI_SUPPORTED != 1
+  depends_components:
+    - esp_driver_twai
+
 examples/peripherals/twai/twai_error_recovery:
   disable:
     - if: SOC_TWAI_SUPPORTED != 1

examples/peripherals/twai/cybergear/CMakeLists.txt

@@ -0,0 +1,8 @@
+# The following lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.16)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+# "Trim" the build. Include the minimal set of components, main, and anything it depends on.
+idf_build_set_property(MINIMAL_BUILD ON)
+project(cybergear_example)

examples/peripherals/twai/cybergear/README.md

@@ -0,0 +1,174 @@
+| Supported Targets | ESP32 | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-H2 | ESP32-H21 | ESP32-P4 | ESP32-S2 | ESP32-S3 |
+| ----------------- | ----- | -------- | -------- | -------- | -------- | --------- | -------- | -------- | -------- |
+
+# CyberGear Motor Control Example
+
+This example demonstrates how to control [XiaoMi CyberGear motors](https://www.mi.com/cyber-gear) using ESP32's TWAI interface. It provides a complete console interface for motor control with support for enable/disable, mode setting, speed and position control, and real-time status monitoring.
+
+> [!NOTE]
+> For simplicity, this console example can only control one motor.
+
+## How to use example
+
+### Hardware Required
+
+* A development board with any supported Espressif SOC chip (see `Supported Targets` table above)
+* XiaoMi CyberGear motor
+* CAN transceiver (e.g., SN65HVD230)
+* Connecting wires
+
+### Hardware Connection
+
+The CAN bus connection requires a CAN transceiver to convert between the ESP32's TWAI signals and the CAN bus differential signals.
+
+```
+ESP32 Pin      CAN Transceiver     CyberGear Motor
+---------      ---------------     ---------------
+GPIO TX   --->  CTX  
+GPIO RX   <---  CRX 
+GND       --->  GND                 GND       <--- Separate power supply 
+VCC(3.3V) --->  VCC(3.3V)           VCC (24V) <--- Separate power supply 
+                CAN_H         <-->  CAN_H
+                CAN_L         <-->  CAN_L  
+---------     ---------------      ---------------
+```
+
+### Configure the project
+
+Before project configuration and build, be sure to set the correct chip target using `idf.py set-target <chip_name>`.
+
+```bash
+idf.py set-target esp32
+idf.py menuconfig
+```
+
+In the `Example Configuration` menu:
+
+* Set `TWAI TX GPIO number` - GPIO pin for TWAI TX
+* Set `TWAI RX GPIO number` - GPIO pin for TWAI RX
+* Set `ESP Node ID`  - TWAI node identifier
+* Set `Motor ID` - Motor identifier
+* Set `Motor bitrate` - Motor bitrate
+
+### Build and Flash
+
+Build the project and flash it to the board, then run monitor tool to view serial output:
+
+```bash
+idf.py build
+idf.py -p PORT flash monitor
+```
+
+(Replace PORT with the name of the serial port to use.)
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
+
+## Example Output
+
+```
+I (330) Cybergear: CyberGear node started, TX: GPIO0, RX: GPIO2
+I (340) Cybergear: CyberGear console started
+
+Type 'help' to get the list of commands.
+Use UP/DOWN arrows to navigate through command history.
+Press TAB when typing command name to auto-complete.
+I (350) main_task: Returned from app_main()
+cybergear>
+```
+
+## Console Commands
+
+The example provides an interactive console with the following commands:
+
+### Control Commands
+
+```bash
+# Enable motor
+enable
+
+# Disable motor and clear fault
+disable
+
+# Set control mode (0:Motion, 1:Location, 2:Speed, 3:Current)
+mode <mode>
+
+# Motion control
+motion -t <torque> -l <location> -s <speed> -p <kp> -d <kd>
+
+# Set motor speed (rad/s)
+speed -s <speed>
+
+# Set motor location (rad)  
+loc -s <location>
+
+# Set motor current (A)
+current -s <current>
+
+# Set current location as zero
+zero
+
+# Set motor ID
+setid <id>
+
+# Get motor ID
+getid
+
+# Show motor status
+status
+
+```
+
+### Usage Examples
+
+```bash
+cybergear> enable                    # Enable motor
+cybergear> mode 1                    # Set location control mode
+cybergear> loc -s 1.57               # Set location to π/2 rad
+cybergear> status                    # Check motor status
+cybergear> mode 2                    # Set speed control mode
+cybergear> speed -s 5.0              # Set speed to 5 rad/s
+cybergear> disable                   # Disable motor
+```
+
+### Note
+
+Command **setid**: The motor ID can not be changed when the motor is running, please disable the motor and set motor id.  
+Command **getid**: If you forget the motor ID you set previously, you can run getid cmd first. And then power off the motor and power it on again. Then it will broadcast its motor ID.
+
+### Technical Specifications
+
+- **TWAI Bitrate**: 125 Kbps, 250 Kbps, 500 Kbps or 1 Mbps (default 1 Mbps)
+- **Position Range**: ±12.5 rad
+- **Speed Range**: ±30.0 rad/s
+- **Torque Range**: ±12.0 Nm  
+- **Current Range**: 0-23.0 A
+
+
+### Motor Status Display
+
+The `status` command shows detailed motor information:
+
+```
+===== Motor Status =====
+Motor ID: 127
+Fault Status: 0
+State: 2
+Location: 0.125000
+Speed: 2.000000
+Torque: 0.300000
+Temperature: 36.500000
+========================
+```
+
+## Troubleshooting
+
+**If Motor not responding**
+
+   - Check CAN transceiver connections
+   - Verify motor ID settings are correct
+   - Confirm CAN bus bitrate matches (1Mbps)
+   - Check motor power supply
+
+For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon.

examples/peripherals/twai/cybergear/main/CMakeLists.txt

@@ -0,0 +1,4 @@
+idf_component_register(SRCS "cybergear_example_main.c" "cybergear.c" "cybergear_console.c"
+                    REQUIRES console esp_driver_twai
+                    INCLUDE_DIRS "."
+                    )

examples/peripherals/twai/cybergear/main/Kconfig.projbuild

@@ -0,0 +1,59 @@
+menu "Example Configuration"
+
+    orsource "$IDF_PATH/examples/common_components/env_caps/$IDF_TARGET/Kconfig.env_caps"
+
+    config EXAMPLE_TWAI_TX_GPIO_NUM
+        int "TX GPIO number"
+        range ENV_GPIO_RANGE_MIN ENV_GPIO_OUT_RANGE_MAX
+        default 0
+        help
+            This option selects the GPIO pin used for the TWAI TX signal. Connect the
+            TWAI TX signal to your transceiver.
+
+    config EXAMPLE_TWAI_RX_GPIO_NUM
+        int "RX GPIO number"
+        range ENV_GPIO_RANGE_MIN ENV_GPIO_IN_RANGE_MAX
+        default 2
+        help
+            This option selects the GPIO pin used for the TWAI RX signal. Connect the
+            TWAI RX signal to your transceiver.
+
+    config EXAMPLE_TWAI_ESP_NODE_ID
+        int "TWAI ESP Node ID"
+        range 0 256
+        default 254
+        help
+            This option selects the ESP Node ID of the ESP Controller.
+
+    config EXAMPLE_TWAI_MOTOR_ID
+        int "TWAI CyberGear motor ID"
+        range 0 256
+        default 127
+        help
+            This option selects the motor ID of the CyberGear. 127 is the factory value.
+            Check the README if you don't know how to get the motor ID.
+
+    choice EXAMPLE_TWAI_MOTOR_BITRATE_CHOICE
+        prompt "TWAI CyberGear motor bitrate"
+        default EXAMPLE_TWAI_MOTOR_BITRATE_1M
+        help
+            This option selects the bitrate of the CyberGear.
+
+        config EXAMPLE_TWAI_MOTOR_BITRATE_1M
+            bool "1M"
+        config EXAMPLE_TWAI_MOTOR_BITRATE_500K
+            bool "500K"
+        config EXAMPLE_TWAI_MOTOR_BITRATE_250K
+            bool "250K"
+        config EXAMPLE_TWAI_MOTOR_BITRATE_125K
+            bool "125K"
+    endchoice
+
+    config EXAMPLE_TWAI_MOTOR_BITRATE
+        int
+        default 1000000 if EXAMPLE_TWAI_MOTOR_BITRATE_1M
+        default 500000 if EXAMPLE_TWAI_MOTOR_BITRATE_500K
+        default 250000 if EXAMPLE_TWAI_MOTOR_BITRATE_250K
+        default 125000 if EXAMPLE_TWAI_MOTOR_BITRATE_125K
+
+endmenu