Merge branch 'feature/example-focknob' into 'master'

feat: add foc knob example

Closes AEG-910

See merge request ae_group/esp-iot-solution!882

.gitlab/ci/build.yml

@@ -338,6 +338,16 @@ build_example_motor_foc_velocity_control:
   variables:
     EXAMPLE_DIR: examples/motor/foc_velocity_control
 
+build_example_motor_foc_knob:
+  extends:
+    - .build_examples_template
+    - .rules:build:example_motor_foc_knob
+  parallel:
+    matrix:
+      - IMAGE: espressif/idf:release-v5.0
+  variables:
+    EXAMPLE_DIR: examples/motor/foc_knob_example
+
 build_example_ota_simple_ota_example:
   extends:
     - .build_examples_template

.gitlab/ci/rules.yml

@@ -316,6 +316,9 @@
 .patterns-example_motor_foc_velocity_control: &patterns-example_motor_foc_velocity_control
   - "examples/motor/foc_velocity_control/**/*"
 
+.patterns-example_motor_foc_knob: &patterns-example_motor_foc_knob
+  - "examples/motor/foc_knob_example/**/*"
+
 .patterns-example_ota_simple_ota_example: &patterns-example_ota_simple_ota_example
   - "examples/ota/simple_ota_example/**/*"
 
@@ -690,6 +693,18 @@
     - <<: *if-dev-push
       changes: *patterns-example_motor_foc_velocity_control
 
+.rules:build:example_motor_foc_knob:
+  rules:
+    - <<: *if-protected
+    - <<: *if-label-build
+    - <<: *if-trigger-job
+    - <<: *if-dev-push
+      changes: *patterns-build_system
+    - <<: *if-dev-push
+      changes: *patterns-components_motor_esp_simplefoc
+    - <<: *if-dev-push
+      changes: *patterns-example_motor_foc_knob
+
 .rules:build:example_ota_simple_ota_example:
   rules:
     - <<: *if-protected

components/motor/esp_simplefoc/idf_component.yml

@@ -20,3 +20,4 @@ dependencies:
 examples:
   - path: ../../../examples/motor/foc_openloop_control
   - path: ../../../examples/motor/foc_velocity_control
+  - path: ../../../examples/motor/foc_knob_example

examples/.build-rules.yml

@@ -103,6 +103,10 @@ examples/motor/foc_velocity_control:
   disable:
     - if: IDF_TARGET == "esp32c2"
 
+examples/motor/foc_knob_example:
+  enable:
+    - if: IDF_TARGET in ["esp32","esp32s3"]
+
 examples/ota/simple_ota_example:
   enable:
     - if: IDF_TARGET in ["esp32c2","esp32c3","esp32"] and (IDF_VERSION_MAJOR == 5 and IDF_VERSION_MINOR == 0)

examples/motor/foc_knob_example/CMakeLists.txt

@@ -0,0 +1,9 @@
+# For more information about build system see
+# https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html
+# The following five 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)
+add_compile_options(-fdiagnostics-color=always)
+project(foc_knob_example)

examples/motor/foc_knob_example/README.md

@@ -0,0 +1,59 @@
+# ESP FOC Knob
+This example demonstrates the application of the ESP32-S3 microcontroller to control a motor, effectively transforming it into a knob-like interface.
+
+## Modes supported
+
+|            Mode             |                                                    Description                                                     |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| 0. unbound no detents       | Motor can be unbounded with fine rotation and no dent points.                                                      |
+| 1. Unbounded Fine detents   | Motor can be unbounded with fine rotation and fine dent points.                                                    |
+| 2. Unbounded Strong detents | Motor can be unbound with fine rotation and noticeable dent points.                                                |
+| 3. Bounded No detents       | Motor will be constrained within a specific range (0-360) with fine rotation and no detent points.                 |
+| 4. Bounded Fine detents     | Motor can be constrained with coarser rotation and fine dent points.                                               |
+| 5. Bounded Strong detents   | Motor can be constrained with coarser rotation and strong dent points.                                             |
+| 6. On/Off strong detents    | Motor will be constrained within a specific range presents a On/off functionality with noticeable stopping points. |
+
+However, users have the flexibility to adjust mode parameters to attain various responses. Within the following structure, users can modify these values to customize the functionality according to their specific requirements.
+
+```c
+typedef struct {
+    int32_t num_positions;        // Number of positions
+    int32_t position;             // Current position
+    float position_width_radians; // Width of each position in radians
+    float detent_strength_unit;   // Strength of detent during normal rotation
+    float endstop_strength_unit;  // Strength of detent when reaching the end
+    float snap_point;             // Snap point for each position
+    const char *descriptor;       // Description
+} knob_param_t;
+
+```
+
+### Hardware Required
+This example is specifically designed for ESP32-S3-Motor-LCDkit.
+
+Other components
+1. The BLDC Motor Model 5v 2804 is compatible and can be employed.
+2. A Position Sensor (Hall-based) such as MT6701 or AS5600 is suitable for use.
+
+### Configure the project
+
+step1: chose your target chip.
+
+````
+idf.py set-target esp32s3
+````
+
+step2: build the project
+
+```
+idf.py build
+```
+
+step 3: Flash and monitor
+Flash the program and launch IDF Monitor:
+
+```bash
+idf.py flash monitor
+```
+
+![FOC Knob exmaple](https://dl.espressif.com/ae/esp-iot-solution/foc_knob.gif)

examples/motor/foc_knob_example/components/foc_knob/CMakeLists.txt

@@ -0,0 +1,11 @@
+set(srcs "foc_knob.c"
+        "foc_knob_default.c"
+        )
+
+set(includes
+        "include"
+    )
+
+idf_component_register(SRCS ${srcs}
+                        INCLUDE_DIRS "${includes}"
+                        REQUIRES driver esp_timer)

examples/motor/foc_knob_example/components/foc_knob/Kconfig

@@ -0,0 +1,10 @@
+menu "FOC Knob"
+
+    config FOC_KNOB_MAX_VELOCITY
+        int "FOC Knob Max Velocity"
+        range 1 100
+        default 23
+        help
+            When the maximum velocity is smaller, the rebound velocity will also be smaller.
+
+endmenu

examples/motor/foc_knob_example/components/foc_knob/README.md

@@ -0,0 +1,39 @@
+# Component FOC Knob
+The FOC knob is a component that offers an extensive API, empowering the user to define various modes of operation. Users have the flexibility to employ different types of BLDC motors to achieve the desired functionality of a haptic feedback knob.
+
+## Modes supported
+By default, certain modes are pre-defined in the **foc_knob_default.c** file. Users have the option to leverage these default modes for their applications.
+
+|            Mode             |                                                    Description                                                     |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| 0. unbound no detents       | Motor can be unbounded with fine rotation and no dent points.                                                      |
+| 1. Unbounded Fine detents   | Motor can be unbounded with fine rotation and fine dent points.                                                    |
+| 2. Unbounded Strong detents | Motor can be unbound with fine rotation and noticeable dent points.                                                |
+| 3. Bounded No detents       | Motor will be constrained within a specific range (0-360) with fine rotation and no detent points.                 |
+| 4. Bounded Fine detents     | Motor can be constrained with coarser rotation and fine dent points.                                               |
+| 5. Bounded Strong detents   | Motor can be constrained with coarser rotation and strong dent points.                                             |
+| 6. On/Off strong detents    | Motor will be constrained within a specific range presents a On/off functionality with noticeable stopping points. |
+
+However, users have the flexibility to adjust mode parameters to attain various responses. Within the following structure, users can modify these values to customize the functionality according to their specific requirements.
+
+```c
+typedef struct {
+    int32_t num_positions;        // Number of positions
+    int32_t position;             // Current position
+    float position_width_radians; // Width of each position in radians
+    float detent_strength_unit;   // Strength of detent during normal rotation
+    float endstop_strength_unit;  // Strength of detent when reaching the end
+    float snap_point;             // Snap point for each position
+    const char *descriptor;       // Description
+} foc_knob_param_t;
+
+```
+### Hardware Required
+This example is specifically designed for ESP32-S3-Motor-LCDkit.
+
+Other components
+1. The BLDC Motor Model 5v 2804 is compatible and can be employed.
+2. A Position Sensor (Hall-based) such as MT6701 or AS5600 is suitable for use.
+
+### Example
+[FOC_knob_example](../../../foc_knob_example/)