feat: add direction controller component

components/direction_controller/include/direction_controller.h

@@ -0,0 +1,126 @@
+/*
+ * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include <stdbool.h>
+#include <stddef.h>
+#include "esp_err.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* ========== Direction Definitions ========== */
+/**
+ * @brief Direction definition entry
+ */
+typedef struct {
+    const char *name_cn;        /* Chinese name */
+    const char *name_en;        /* English abbreviation */
+    float angle;                /* Angle relative to South */
+} direction_controller_direction_t;
+
+/**
+ * @brief Direction controller configuration
+ */
+typedef struct {
+    const direction_controller_direction_t *directions; /* Custom direction list, NULL to use default */
+    size_t direction_count;                             /* Number of directions */
+    float initial_angle;                                /* Initial angle relative to South */
+    int rotate_speed_us;                                /* Rotation speed (microseconds per step) */
+    bool init_stepper_gpio;                             /* Initialize stepper GPIO in init */
+} direction_controller_config_t;
+
+/**
+ * @brief Parsed command types
+ */
+typedef enum {
+    DIRECTION_CONTROLLER_CMD_UNKNOWN = 0,
+    DIRECTION_CONTROLLER_CMD_HELP,
+    DIRECTION_CONTROLLER_CMD_POSITION,
+    DIRECTION_CONTROLLER_CMD_DIRECTION
+} direction_controller_cmd_t;
+
+/**
+ * @brief Initialize direction controller
+ *
+ * @param config Optional configuration, NULL uses defaults
+ */
+void direction_controller_init(const direction_controller_config_t *config);
+
+/**
+ * @brief Parse a command string
+ *
+ * @param input Input string (null-terminated)
+ * @param out_direction Output matched direction when command type is DIRECTION_CONTROLLER_CMD_DIRECTION
+ * @return Parsed command type
+ */
+direction_controller_cmd_t direction_controller_parse_command(const char *input,
+        const direction_controller_direction_t **out_direction);
+
+/**
+ * @brief Find direction by name
+ *
+ * @param input Direction name (Chinese or English abbreviation)
+ * @return Matched direction pointer, or NULL if not found
+ */
+const direction_controller_direction_t *direction_controller_find_direction(const char *input);
+
+/**
+ * @brief Rotate to specified angle
+ *
+ * @param target_angle Target angle relative to South
+ * @return ESP_OK on success
+ */
+esp_err_t direction_controller_rotate_to_angle(float target_angle);
+
+/**
+ * @brief Rotate to specified direction by name
+ *
+ * @param input Direction name (Chinese or English abbreviation)
+ * @return ESP_OK on success, ESP_ERR_NOT_FOUND if name is unknown
+ */
+esp_err_t direction_controller_rotate_to_direction(const char *input);
+
+/**
+ * @brief Get current angle
+ */
+float direction_controller_get_current_angle(void);
+
+/**
+ * @brief Set current angle (does not move motor)
+ */
+void direction_controller_set_current_angle(float angle);
+
+/**
+ * @brief Get current direction if it matches a defined direction
+ */
+const direction_controller_direction_t *direction_controller_get_current_direction(void);
+
+/**
+ * @brief Get direction count
+ */
+size_t direction_controller_get_direction_count(void);
+
+/**
+ * @brief Get direction by index
+ */
+const direction_controller_direction_t *direction_controller_get_direction(size_t index);
+
+/**
+ * @brief Get rotation speed (microseconds per step)
+ */
+int direction_controller_get_rotate_speed_us(void);
+
+/**
+ * @brief Set rotation speed (microseconds per step)
+ */
+void direction_controller_set_rotate_speed_us(int rotate_speed_us);
+
+#ifdef __cplusplus
+}
+#endif