Knob

[English]

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.

Hardware Design

The reference design for the rotary encoder is shown below:

../_images/knob_hardware.png

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, "KNOB: KNOB_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);

Low Power Support

In light_sleep mode, the esp_timer wakes up the CPU, resulting in high power consumption. The Knob component offers a low power solution through GPIO level wake-up.

Required Configuration:

  • Enable the enable_power_save option in knob_config_t.

Power Consumption Comparison:

  • Without low power mode, one rotation within 250ms

    One rotation without low power mode
  • With low power mode, one rotation within 250ms

    One rotation with low power mode
  • With low power mode, ten rotations within 4.5s

    Ten rotations with low power mode

The knob is responsive and consumes less power in low power mode.

Enable and Disable

The component supports enabling and disabling at any time.

// Stop knob
iot_knob_stop();
// Resume knob
iot_knob_resume();

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

esp_err_t iot_knob_resume(void)

resume knob timer, if knob timer is stopped. Make sure iot_knob_create() is called before calling this API.

Returns

  • ESP_OK on success

  • ESP_ERR_INVALID_STATE timer state is invalid.

esp_err_t iot_knob_stop(void)

stop knob timer, if knob timer is running. Make sure iot_knob_create() is called before calling this API.

Returns

  • ESP_OK on success

  • ESP_ERR_INVALID_STATE timer state is invalid

Structures

struct knob_config_t

Knob config.

Public Members

uint8_t default_direction

0:positive increase 1:negative increase

uint8_t gpio_encoder_a

Encoder Pin A

uint8_t gpio_encoder_b

Encoder Pin B

bool enable_power_save

Enable power save mode

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_NONE

EVENT: No event