Knob
Knob is the component that provides the software PCNT, it can be used on chips(esp32c2, esp32c3) that do not have PCNT hardware capabilities. By using knob you can quickly use a physical encoder, such as the EC11 encoder.
Applicable Scenarios
This is suitable for low-speed rotary knob counting scenarios where the pulse rate is less than 30 pulses per second, such as the EC11 encoder. It is suitable for scenarios where 100% accuracy of pulse counting is not required.
Note
For precise or fast pulse counting, please use the hardware PCNT function. The hardware PCNT is supported by ESP32, ESP32-C6, ESP32-H2, ESP32-S2, ESP32-S3 chips.
Knob Event
Each knob has the 5 events in the following table.
Events |
Trigger Conditions |
|---|---|
KNOB_LEFT |
Left |
KNOB_RIGHT |
Right |
KNOB_H_LIM |
Count reaches maximum limit |
KNOB_L_LIM |
Count reaches the minimum limit |
KNOB_ZERO |
Count back to 0 |
Each knob can have Callback usage.
Callbacks: Each event of a knob can have a callback function registered for it, and the callback function will be called when the event is generated. This approach is efficient and real-time, and no events are lost.
Attention
No blocking operations such as TaskDelay in the callback function
Configuration items
KNOB_PERIOD_TIME_MS : Scan cycle
KNOB_DEBOUNCE_TICKS : Number of de-shaking
KNOB_HIGH_LIMIT : The highest number that can be counted by the knob
KNOB_LOW_LIMIT : The lowest number that can be counted by the knob
Application Examples
Create Knob
// create knob
knob_config_t cfg = {
.default_direction =0,
.gpio_encoder_a = GPIO_KNOB_A,
.gpio_encoder_b = GPIO_KNOB_B,
};
s_knob = iot_knob_create(&cfg);
if(NULL == s_knob) {
ESP_LOGE(TAG, "knob create failed");
}
Register callback function
static void _knob_left_cb(void *arg, void *data)
{
ESP_LOGI(TAG, "KONB: KONB_LEFT,count_value:%"PRId32"",iot_knob_get_count_value((button_handle_t)arg));
}
iot_knob_register_cb(s_knob, KNOB_LEFT, _knob_left_cb, NULL);
API Reference
Header File
Functions
-
knob_handle_t iot_knob_create(const knob_config_t *config)
create a knob
- Parameters
config – pointer of knob configuration
- Returns
A handle to the created knob
-
esp_err_t iot_knob_delete(knob_handle_t knob_handle)
Delete a knob.
- Parameters
knob_handle – A knob handle to delete
- Returns
ESP_OK Success
ESP_FAIL Failure
-
esp_err_t iot_knob_register_cb(knob_handle_t knob_handle, knob_event_t event, knob_cb_t cb, void *usr_data)
Register the knob event callback function.
- Parameters
knob_handle – A knob handle to register
event – Knob event
cb – Callback function
usr_data – user data
- Returns
ESP_OK Success
ESP_FAIL Failure
-
esp_err_t iot_knob_unregister_cb(knob_handle_t knob_handle, knob_event_t event)
Unregister the knob event callback function.
- Parameters
knob_handle – A knob handle to register
event – Knob event
- Returns
ESP_OK Success
ESP_FAIL Failure
-
knob_event_t iot_knob_get_event(knob_handle_t knob_handle)
Get knob event.
- Parameters
knob_handle – A knob handle to register
- Returns
knob_event_t Knob event
-
int iot_knob_get_count_value(knob_handle_t knob_handle)
Get knob count value.
- Parameters
knob_handle – A knob handle to register
- Returns
int count_value
-
esp_err_t iot_knob_clear_count_value(knob_handle_t knob_handle)
Clear knob cout value to zero.
- Parameters
knob_handle – A knob handle to register
- Returns
ESP_OK Success
ESP_FAIL Failure
Structures
-
struct knob_config_t
Knob config.
Type Definitions
-
typedef void (*knob_cb_t)(void*, void*)
-
typedef void *knob_handle_t
Enumerations
-
enum knob_event_t
Knob events.
Values:
-
enumerator KNOB_LEFT
EVENT: Rotate to the left
-
enumerator KNOB_RIGHT
EVENT: Rotate to the right
-
enumerator KNOB_H_LIM
EVENT: Count reaches maximum limit
-
enumerator KNOB_L_LIM
EVENT: Count reaches the minimum limit
-
enumerator KNOB_ZERO
EVENT: Count back to 0
-
enumerator KNOB_EVENT_MAX
EVENT: Number of events
-
enumerator KNOB_LEFT