HF Interface Wrapper 0.1.0-dev
Embedded C++ hardware abstraction layer
Loading...
Searching...
No Matches
EspTypes_GPIO.h
Go to the documentation of this file.
1
15#pragma once
16
17#include "BaseGpio.h" // For hf_gpio_err_t
18#include "EspTypes_Base.h"
19#include "HardwareTypes.h"
20#include "McuSelect.h" // Central MCU platform selection (includes all ESP-IDF)
21
22#ifdef HF_MCU_FAMILY_ESP32
23
24//==============================================================================
25// ESSENTIAL GPIO TYPES (ESP32)
26//==============================================================================
27
31using hf_gpio_num_t = hf_pin_num_t;
32
37enum class hf_gpio_mode_t : uint8_t {
38 HF_GPIO_MODE_DISABLE = 0,
39 HF_GPIO_MODE_INPUT = 1,
40 HF_GPIO_MODE_OUTPUT = 2,
41 HF_GPIO_MODE_OUTPUT_OD = 3,
42 HF_GPIO_MODE_INPUT_OUTPUT = 4,
43 HF_GPIO_MODE_INPUT_OUTPUT_OD = 5
44};
45
50enum class hf_gpio_pull_t : uint8_t {
51 HF_GPIO_PULL_NONE = 0,
52 HF_GPIO_PULL_UP = 1,
53 HF_GPIO_PULL_DOWN = 2,
54 HF_GPIO_PULL_UP_DOWN = 3
55};
56
61enum class hf_gpio_intr_type_t : uint8_t {
62 HF_GPIO_INTR_DISABLE = 0,
63 HF_GPIO_INTR_POSEDGE = 1,
64 HF_GPIO_INTR_NEGEDGE = 2,
65 HF_GPIO_INTR_ANYEDGE = 3,
66 HF_GPIO_INTR_LOW_LEVEL = 4,
67 HF_GPIO_INTR_HIGH_LEVEL = 5
68};
69
74enum class hf_gpio_drive_cap_t : uint8_t {
75 HF_GPIO_DRIVE_CAP_WEAK = 0,
76 HF_GPIO_DRIVE_CAP_STRONGER = 1,
77 HF_GPIO_DRIVE_CAP_MEDIUM = 2,
78 HF_GPIO_DRIVE_CAP_STRONGEST = 3
79};
80
85enum class hf_rtc_gpio_mode_t : uint8_t {
86 HF_RTC_GPIO_MODE_INPUT_ONLY = 0,
87 HF_RTC_GPIO_MODE_OUTPUT_ONLY = 1,
88 HF_RTC_GPIO_MODE_INPUT_OUTPUT = 2,
89 HF_RTC_GPIO_MODE_DISABLED = 3,
90 HF_RTC_GPIO_MODE_OUTPUT_OD = 4,
91 HF_RTC_GPIO_MODE_INPUT_OUTPUT_OD = 5
92};
93
94//==============================================================================
95// ADVANCED GPIO FEATURES (ESP32)
96//==============================================================================
97
102enum class hf_gpio_glitch_filter_type_t : uint8_t {
103 HF_GPIO_GLITCH_FILTER_NONE = 0,
104 HF_GPIO_GLITCH_FILTER_PIN = 1,
105 HF_GPIO_GLITCH_FILTER_FLEX = 2,
106 HF_GPIO_GLITCH_FILTER_BOTH = 3
107};
108
113enum class hf_gpio_glitch_filter_clk_src_t : uint8_t {
114 HF_GLITCH_FILTER_CLK_SRC_APB = 0,
115 HF_GLITCH_FILTER_CLK_SRC_RC_FAST = 1,
116 HF_GLITCH_FILTER_CLK_SRC_XTAL = 2
117};
118
123struct hf_lp_io_config_t {
124 hf_gpio_mode_t mode;
125 hf_gpio_pull_t pull_mode;
126 hf_gpio_drive_cap_t drive_strength;
127 bool input_enable;
128 bool output_enable;
129 bool hold_enable;
130 bool force_hold;
131};
132
137struct hf_gpio_flex_filter_config_t {
138 uint32_t window_width_ns;
139 uint32_t window_threshold_ns;
140 hf_gpio_glitch_filter_clk_src_t clk_src;
141 bool enable_on_init;
142};
143
148struct hf_gpio_pin_filter_config_t {
149 hf_gpio_glitch_filter_clk_src_t clk_src;
150 bool enable_on_init;
151};
152
157struct hf_gpio_sleep_config_t {
158 hf_gpio_mode_t sleep_mode;
159 hf_gpio_mode_t sleep_direction;
160 hf_gpio_pull_t sleep_pull_mode;
161 hf_gpio_drive_cap_t sleep_drive_strength;
162 bool sleep_output_enable;
163 bool sleep_input_enable;
164 bool hold_during_sleep;
165 bool rtc_domain_enable;
166 bool slp_sel_enable;
167 bool enable_sleep_retain;
168};
169
174struct hf_gpio_wakeup_config_t {
175 hf_gpio_intr_type_t wake_trigger;
176 bool enable_rtc_wake;
177 bool enable_ext1_wake;
178 uint8_t wake_level;
179 bool internal_pullup_enable;
180 bool internal_pulldown_enable;
181 bool iso_en;
182};
183
188struct hf_gpio_advanced_config_t {
189 hf_pin_num_t gpio_num;
190 hf_gpio_mode_t mode;
191 hf_gpio_pull_t pull_mode;
192 hf_gpio_intr_type_t intr_type;
193 hf_gpio_drive_cap_t drive_strength;
194 hf_gpio_glitch_filter_type_t glitch_filter_type;
195 hf_gpio_flex_filter_config_t flex_filter_config;
196 hf_gpio_pin_filter_config_t pin_filter_config;
197 hf_gpio_sleep_config_t sleep_config;
198 hf_gpio_wakeup_config_t wakeup_config;
199 bool enable_hold_function;
200 bool enable_rtc_gpio;
201};
202
207struct hf_gpio_status_info_t {
208 uint8_t pin_number;
209 hf_gpio_mode_t current_mode;
210 hf_gpio_pull_t current_pull_mode;
211 hf_gpio_drive_cap_t current_drive_cap;
212 hf_gpio_intr_type_t interrupt_type;
213 bool input_enabled;
214 bool output_enabled;
215 bool open_drain;
216 bool sleep_sel_enabled;
217 bool hold_enabled;
218 bool rtc_enabled;
219 uint32_t function_select;
220 hf_gpio_glitch_filter_type_t filter_type;
221 bool glitch_filter_enabled;
222 uint32_t interrupt_count;
223 bool is_wake_source;
224 bool sleep_hold_active;
225 uint32_t last_interrupt_time_us;
226};
227
232typedef struct {
233 uint8_t pin_number;
234 bool is_valid_gpio;
235 bool supports_input;
236 bool supports_output;
237 bool supports_pullup;
238 bool supports_pulldown;
239 bool supports_adc;
240 bool supports_rtc;
241 bool is_strapping_pin;
242 bool is_usb_jtag_pin;
243 bool is_spi_pin;
244 bool supports_glitch_filter;
245} hf_gpio_pin_capabilities_t;
246
247// Only define each macro once, use 'pin' as the parameter name
248#ifndef HF_GPIO_IS_ADC_CAPABLE
249#define HF_GPIO_IS_ADC_CAPABLE(pin) (false)
250#endif
251#ifndef HF_GPIO_IS_SPI_PIN
252#define HF_GPIO_IS_SPI_PIN(pin) (false)
253#endif
254#ifndef HF_GPIO_IS_RTC_GPIO
255#define HF_GPIO_IS_RTC_GPIO(pin) (false)
256#endif
257#ifndef HF_GPIO_IS_STRAPPING_PIN
258#define HF_GPIO_IS_STRAPPING_PIN(pin) (false)
259#endif
260#ifndef HF_GPIO_IS_USB_JTAG_PIN
261#define HF_GPIO_IS_USB_JTAG_PIN(pin) (false)
262#endif
263#ifndef HF_GPIO_SUPPORTS_GLITCH_FILTER
264#define HF_GPIO_SUPPORTS_GLITCH_FILTER(pin) (false)
265#endif
266
267//==============================================================================
268// END OF ESPGPIO TYPES - MINIMAL AND ESSENTIAL ONLY
269//==============================================================================
270
271//==============================================================================
272// ESP32 GPIO VALIDATION MACROS AND CONSTANTS
273//==============================================================================
274
279#define HF_GPIO_IS_VALID_GPIO(gpio_num) \
280 ((gpio_num) >= 0 && (gpio_num) <= HF_MCU_GPIO_MAX_PIN_NUMBER)
281
282#define HF_GPIO_IS_VALID_PIN(gpio_num) HF_GPIO_IS_VALID_GPIO(gpio_num)
283
284#define HF_GPIO_IS_VALID_OUTPUT_GPIO(gpio_num) \
285 (HF_GPIO_IS_VALID_GPIO(gpio_num) && !HF_GPIO_IS_INPUT_ONLY_PIN(gpio_num))
286
287// RTC GPIO validation (variant-aware)
288#if defined(HF_MCU_ESP32C6)
289#define HF_GPIO_IS_VALID_RTC_GPIO(gpio_num) ((gpio_num) >= 0 && (gpio_num) <= 7)
290#define HF_GPIO_IS_VALID_LP_IO(gpio_num) ((gpio_num) >= 0 && (gpio_num) <= 7)
291#define HF_GPIO_SUPPORTS_ADC(gpio_num) ((gpio_num) >= 0 && (gpio_num) <= 6)
292#define HF_GPIO_IS_SPI_FLASH_PIN(gpio_num) ((gpio_num) >= 24 && (gpio_num) <= 30)
293#define HF_GPIO_IS_INPUT_ONLY_PIN(gpio_num) (false)
294#elif defined(HF_MCU_ESP32S3)
295#define HF_GPIO_IS_VALID_RTC_GPIO(gpio_num) ((gpio_num) >= 0 && (gpio_num) <= 21)
296#define HF_GPIO_IS_VALID_LP_IO(gpio_num) (false)
297#define HF_GPIO_SUPPORTS_ADC(gpio_num) (((gpio_num) >= 1 && (gpio_num) <= 10) || ((gpio_num) >= 11 && (gpio_num) <= 20))
298#define HF_GPIO_IS_SPI_FLASH_PIN(gpio_num) ((gpio_num) >= 26 && (gpio_num) <= 32)
299#define HF_GPIO_IS_INPUT_ONLY_PIN(gpio_num) (false)
300#elif defined(HF_MCU_ESP32)
301#define HF_GPIO_IS_VALID_RTC_GPIO(gpio_num) (((gpio_num) >= 0 && (gpio_num) <= 5) || ((gpio_num) >= 12 && (gpio_num) <= 15) || ((gpio_num) >= 25 && (gpio_num) <= 27) || ((gpio_num) >= 32 && (gpio_num) <= 39))
302#define HF_GPIO_IS_VALID_LP_IO(gpio_num) (false)
303#define HF_GPIO_SUPPORTS_ADC(gpio_num) (((gpio_num) >= 32 && (gpio_num) <= 39) || ((gpio_num) >= 0 && (gpio_num) <= 9) || ((gpio_num) >= 25 && (gpio_num) <= 27))
304#define HF_GPIO_IS_SPI_FLASH_PIN(gpio_num) ((gpio_num) >= 6 && (gpio_num) <= 11)
305#define HF_GPIO_IS_INPUT_ONLY_PIN(gpio_num) ((gpio_num) >= 34 && (gpio_num) <= 39)
306#elif defined(HF_MCU_ESP32S2)
307#define HF_GPIO_IS_VALID_RTC_GPIO(gpio_num) ((gpio_num) >= 0 && (gpio_num) <= 21)
308#define HF_GPIO_IS_VALID_LP_IO(gpio_num) (false)
309#define HF_GPIO_SUPPORTS_ADC(gpio_num) (((gpio_num) >= 1 && (gpio_num) <= 10) || ((gpio_num) >= 11 && (gpio_num) <= 20))
310#define HF_GPIO_IS_SPI_FLASH_PIN(gpio_num) ((gpio_num) >= 26 && (gpio_num) <= 32)
311#define HF_GPIO_IS_INPUT_ONLY_PIN(gpio_num) ((gpio_num) == 46)
312#elif defined(HF_MCU_ESP32C3)
313#define HF_GPIO_IS_VALID_RTC_GPIO(gpio_num) ((gpio_num) >= 0 && (gpio_num) <= 5)
314#define HF_GPIO_IS_VALID_LP_IO(gpio_num) (false)
315#define HF_GPIO_SUPPORTS_ADC(gpio_num) ((gpio_num) >= 0 && (gpio_num) <= 4)
316#define HF_GPIO_IS_SPI_FLASH_PIN(gpio_num) ((gpio_num) >= 12 && (gpio_num) <= 17)
317#define HF_GPIO_IS_INPUT_ONLY_PIN(gpio_num) (false)
318#elif defined(HF_MCU_ESP32H2)
319#define HF_GPIO_IS_VALID_RTC_GPIO(gpio_num) ((gpio_num) >= 7 && (gpio_num) <= 14)
320#define HF_GPIO_IS_VALID_LP_IO(gpio_num) ((gpio_num) >= 7 && (gpio_num) <= 14)
321#define HF_GPIO_SUPPORTS_ADC(gpio_num) ((gpio_num) >= 0 && (gpio_num) <= 4)
322#define HF_GPIO_IS_SPI_FLASH_PIN(gpio_num) ((gpio_num) >= 15 && (gpio_num) <= 21)
323#define HF_GPIO_IS_INPUT_ONLY_PIN(gpio_num) (false)
324#elif defined(HF_MCU_ESP32C2)
325#define HF_GPIO_IS_VALID_RTC_GPIO(gpio_num) ((gpio_num) >= 0 && (gpio_num) <= 4)
326#define HF_GPIO_IS_VALID_LP_IO(gpio_num) (false)
327#define HF_GPIO_SUPPORTS_ADC(gpio_num) ((gpio_num) >= 0 && (gpio_num) <= 4)
328#define HF_GPIO_IS_SPI_FLASH_PIN(gpio_num) ((gpio_num) >= 12 && (gpio_num) <= 17)
329#define HF_GPIO_IS_INPUT_ONLY_PIN(gpio_num) (false)
330#else
331#define HF_GPIO_IS_VALID_RTC_GPIO(gpio_num) (false)
332#define HF_GPIO_IS_VALID_LP_IO(gpio_num) (false)
333#define HF_GPIO_SUPPORTS_ADC(gpio_num) (false)
334#define HF_GPIO_IS_SPI_FLASH_PIN(gpio_num) (false)
335#define HF_GPIO_IS_INPUT_ONLY_PIN(gpio_num) (false)
336#endif
337
338#define HF_GPIO_SUPPORTS_PULL_UP(gpio_num) (HF_GPIO_IS_VALID_GPIO(gpio_num))
339
340#define HF_GPIO_SUPPORTS_PULL_DOWN(gpio_num) (HF_GPIO_IS_VALID_GPIO(gpio_num))
341
342#define HF_GPIO_SUPPORTS_OPEN_DRAIN(gpio_num) (HF_GPIO_IS_VALID_OUTPUT_GPIO(gpio_num))
343
347#define HF_GPIO_TO_ADC_UNIT(gpio_num) (HF_GPIO_SUPPORTS_ADC(gpio_num) ? 1 : 0xFF)
348
349#define HF_GPIO_TO_ADC_CHANNEL(gpio_num) (HF_GPIO_SUPPORTS_ADC(gpio_num) ? (gpio_num) : 0xFF)
350
354#define HF_GPIO_TO_RTC_GPIO(gpio_num) (HF_GPIO_IS_VALID_RTC_GPIO(gpio_num) ? (gpio_num) : 0xFF)
355
356#define HF_GPIO_TO_LP_IO(gpio_num) (HF_GPIO_IS_VALID_LP_IO(gpio_num) ? (gpio_num) : 0xFF)
357
361#define HF_GPIO_IS_SAFE_FOR_GENERAL_USE(gpio_num) \
362 (HF_GPIO_IS_VALID_GPIO(gpio_num) && !HF_GPIO_IS_STRAPPING_PIN(gpio_num) && \
363 !HF_GPIO_IS_SPI_FLASH_PIN(gpio_num) && !HF_GPIO_IS_USB_JTAG_PIN(gpio_num))
364
365//==============================================================================
366// CONVENIENCE TYPES AND UTILITY FUNCTIONS
367//==============================================================================
368
374using hf_gpio_isr_callback_t = void (*)(uint32_t gpio_num, void* user_data);
375
379enum class hf_gpio_config_result_t : uint8_t {
380 HF_GPIO_CONFIG_OK = 0,
381 HF_GPIO_CONFIG_INVALID_PIN = 1,
382 HF_GPIO_CONFIG_INVALID_MODE = 2,
383 HF_GPIO_CONFIG_INVALID_PULL = 3,
384 HF_GPIO_CONFIG_INVALID_DRIVE = 4,
385 HF_GPIO_CONFIG_STRAPPING_WARNING = 5,
386 HF_GPIO_CONFIG_FLASH_WARNING = 6,
387 HF_GPIO_CONFIG_JTAG_WARNING = 7
388};
389
393struct hf_gpio_pin_info_t {
394 uint8_t gpio_num;
395 const char* pin_name;
396 const char* alt_functions[4];
397 hf_gpio_pin_capabilities_t capabilities;
398 const char* usage_notes;
399};
400
406extern const hf_gpio_pin_info_t HF_GPIO_PIN_INFO_TABLE[HF_MCU_GPIO_PIN_COUNT];
407
413inline const hf_gpio_pin_info_t* hf_gpio_get_pin_info(uint8_t gpio_num) {
414 if (!HF_GPIO_IS_VALID_GPIO(gpio_num)) {
415 return nullptr;
416 }
417 return &HF_GPIO_PIN_INFO_TABLE[gpio_num];
418}
419
425hf_gpio_config_result_t hf_gpio_validate_config(const hf_gpio_advanced_config_t* config);
426
433hf_gpio_drive_cap_t hf_gpio_get_optimal_drive_strength(uint32_t frequency_hz, uint8_t gpio_num);
434
441uint32_t hf_gpio_calc_glitch_filter_window(uint32_t noise_duration_ns,
442 uint8_t safety_margin_percent);
443
444//==============================================================================
445// ERROR HANDLING AND DEBUGGING SUPPORT
446//==============================================================================
447
451enum class hf_gpio_result_t : uint8_t {
452 GPIO_OK = 0,
453 GPIO_ERR_INVALID_ARG = 1,
454 GPIO_ERR_INVALID_STATE = 2,
455 GPIO_ERR_NOT_SUPPORTED = 3,
456 GPIO_ERR_NO_MEM = 4,
457 GPIO_ERR_TIMEOUT = 5,
458 GPIO_ERR_HW_FAULT = 6,
459 GPIO_ERR_BUSY = 7,
460 GPIO_ERR_NOT_FOUND = 8
461};
462
468constexpr const char* hf_gpio_result_to_string(hf_gpio_result_t result) {
469 switch (result) {
470 case hf_gpio_result_t::GPIO_OK:
471 return "Success";
472 case hf_gpio_result_t::GPIO_ERR_INVALID_ARG:
473 return "Invalid argument";
474 case hf_gpio_result_t::GPIO_ERR_INVALID_STATE:
475 return "Invalid state";
476 case hf_gpio_result_t::GPIO_ERR_NOT_SUPPORTED:
477 return "Not supported";
478 case hf_gpio_result_t::GPIO_ERR_NO_MEM:
479 return "Out of memory";
480 case hf_gpio_result_t::GPIO_ERR_TIMEOUT:
481 return "Timeout";
482 case hf_gpio_result_t::GPIO_ERR_HW_FAULT:
483 return "Hardware fault";
484 case hf_gpio_result_t::GPIO_ERR_BUSY:
485 return "Resource busy";
486 case hf_gpio_result_t::GPIO_ERR_NOT_FOUND:
487 return "Resource not found";
488 default:
489 return "Unknown error";
490 }
491}
492
493//==============================================================================
494// COMPILE-TIME CONFIGURATION VALIDATION
495//==============================================================================
496
497// Compile-time assertions to ensure configuration consistency (variant-aware)
498#if defined(HF_MCU_ESP32C6)
499static_assert(HF_MCU_GPIO_PIN_COUNT == 31, "ESP32-C6 should have 31 GPIO pins");
500static_assert(HF_MCU_GPIO_MAX_PIN_NUMBER == 30, "ESP32-C6 max GPIO should be 30");
501#elif defined(HF_MCU_ESP32S3)
502static_assert(HF_MCU_GPIO_PIN_COUNT == 49, "ESP32-S3 should have 49 GPIO pins");
503static_assert(HF_MCU_GPIO_MAX_PIN_NUMBER == 48, "ESP32-S3 max GPIO should be 48");
504#elif defined(HF_MCU_ESP32)
505static_assert(HF_MCU_GPIO_PIN_COUNT == 40, "ESP32 should have 40 GPIO pins");
506static_assert(HF_MCU_GPIO_MAX_PIN_NUMBER == 39, "ESP32 max GPIO should be 39");
507#elif defined(HF_MCU_ESP32S2)
508static_assert(HF_MCU_GPIO_PIN_COUNT == 47, "ESP32-S2 should have 47 GPIO pins");
509static_assert(HF_MCU_GPIO_MAX_PIN_NUMBER == 46, "ESP32-S2 max GPIO should be 46");
510#elif defined(HF_MCU_ESP32C3)
511static_assert(HF_MCU_GPIO_PIN_COUNT == 22, "ESP32-C3 should have 22 GPIO pins");
512static_assert(HF_MCU_GPIO_MAX_PIN_NUMBER == 21, "ESP32-C3 max GPIO should be 21");
513#elif defined(HF_MCU_ESP32C2)
514static_assert(HF_MCU_GPIO_PIN_COUNT == 21, "ESP32-C2 should have 21 GPIO pins");
515static_assert(HF_MCU_GPIO_MAX_PIN_NUMBER == 20, "ESP32-C2 max GPIO should be 20");
516#elif defined(HF_MCU_ESP32H2)
517static_assert(HF_MCU_GPIO_PIN_COUNT == 28, "ESP32-H2 should have 28 GPIO pins");
518static_assert(HF_MCU_GPIO_MAX_PIN_NUMBER == 27, "ESP32-H2 max GPIO should be 27");
519#endif
520static_assert(HF_MCU_GPIO_RTC_PIN_COUNT >= 0, "RTC pin count must be non-negative");
521static_assert(HF_MCU_GPIO_ADC_PIN_COUNT >= 0, "ADC pin count must be non-negative");
522static_assert(HF_MCU_GPIO_FLEX_FILTER_COUNT >= 0, "Flex filter count must be non-negative");
523
524#ifdef GPIO_MODE_INPUT
525static_assert(static_cast<int>(hf_gpio_mode_t::HF_GPIO_MODE_INPUT) == GPIO_MODE_INPUT,
526 "GPIO mode values must match ESP-IDF");
527#endif
528
529#ifdef GPIO_PULLUP_ONLY
530static_assert(static_cast<int>(hf_gpio_pull_t::HF_GPIO_PULL_UP) == GPIO_PULLUP_ONLY,
531 "GPIO pull mode values must match ESP-IDF");
532#endif
533
534#endif // HF_MCU_FAMILY_ESP32
BaseGpio.h
Unified GPIO base class for all digital GPIO implementations.
EspTypes_Base.h
ESP32 base type definitions for hardware abstraction.
HardwareTypes.h
Platform-agnostic hardware type definitions for the HardFOC system.
hf_pin_num_t
hf_i32_t hf_pin_num_t
Platform-agnostic GPIO pin number type.
Definition HardwareTypes.h:99
McuSelect.h
Centralized MCU platform selection and configuration header.
hf_gpio_err_t::GPIO_ERR_TIMEOUT
@ GPIO_ERR_TIMEOUT
hf_gpio_err_t::GPIO_ERR_INVALID_ARG
@ GPIO_ERR_INVALID_ARG
hf_gpio_err_t::GPIO_ERR_NOT_SUPPORTED
@ GPIO_ERR_NOT_SUPPORTED
hf_gpio_err_t::GPIO_ERR_INVALID_STATE
@ GPIO_ERR_INVALID_STATE