Interface definitions for the ESP32-compatible Incremental Rotary Encoder component. More...

#include <stdbool.h>
#include <stdint.h>
#include "freertos/FreeRTOS.h"
#include "freertos/queue.h"
#include "esp_err.h"
#include "driver/gpio.h"

Data Structures
struct	rotary_encoder_state_t
	Struct represents the current state of the device in terms of incremental position and direction of last movement. More...

struct	rotary_encoder_info_t
	Struct carries all the information needed by this driver to manage the rotary encoder device. The fields of this structure should not be accessed directly. More...

struct	rotary_encoder_event_t
	Struct represents a queued event, used to communicate current position to a waiting task. More...

Typedefs
typedef int32_t	rotary_encoder_position_t

Enumerations
enum	rotary_encoder_direction_t { ROTARY_ENCODER_DIRECTION_NOT_SET = 0, ROTARY_ENCODER_DIRECTION_CLOCKWISE, ROTARY_ENCODER_DIRECTION_COUNTER_CLOCKWISE }
	Enum representing the direction of rotation. More...

Functions
esp_err_t	rotary_encoder_init (rotary_encoder_info_t *info, gpio_num_t pin_a, gpio_num_t pin_b)
	Initialise the rotary encoder device with the specified GPIO pins and full step increments. This function will set up the GPIOs as needed, Note: this function assumes that gpio_install_isr_service(0) has already been called. More...

esp_err_t	rotary_encoder_enable_half_steps (rotary_encoder_info_t *info, bool enable)
	Enable half-stepping mode. This generates twice as many counted steps per rotation. More...

esp_err_t	rotary_encoder_flip_direction (rotary_encoder_info_t *info)
	Reverse (flip) the sense of the direction. Use this if clockwise/counterclockwise are not what you expect. More...

esp_err_t	rotary_encoder_uninit (rotary_encoder_info_t *info)
	Remove the interrupt handlers installed by rotary_encoder_init. Note: GPIOs will be left in the state they were configured by rotary_encoder_init. More...

QueueHandle_t	rotary_encoder_create_queue (void)
	Create a queue handle suitable for use as an event queue. More...

esp_err_t	rotary_encoder_set_queue (rotary_encoder_info_t *info, QueueHandle_t queue)
	Set the driver to use the specified queue as an event queue. It is recommended that a queue constructed by rotary_encoder_create_queue is used. More...

esp_err_t	rotary_encoder_get_state (const rotary_encoder_info_t info, rotary_encoder_state_t state)
	Get the current position of the rotary encoder. More...

esp_err_t	rotary_encoder_reset (rotary_encoder_info_t *info)
	Reset the current position of the rotary encoder to zero. More...

Detailed Description

Interface definitions for the ESP32-compatible Incremental Rotary Encoder component.

This component provides a means to interface with a typical rotary encoder such as the EC11 or LPD3806. These encoders produce a quadrature signal on two outputs, which can be used to track the position and direction as movement occurs.

This component provides functions to initialise the GPIOs and install appropriate interrupt handlers to track a single device's position. An event queue is used to provide a way for a user task to obtain position information from the component as it is generated.

Note that the queue is of length 1, and old values will be overwritten. Using a longer queue is possible with some minor modifications however newer values are lost if the queue overruns. A circular buffer where old values are lost would be better (maybe StreamBuffer in FreeRTOS 10.0.0?).

Enumeration Type Documentation

enum rotary_encoder_direction_t

Enum representing the direction of rotation.

Enumerator
ROTARY_ENCODER_DIRECTION_NOT_SET	Direction not yet known (stationary since reset)

Function Documentation

esp_err_t rotary_encoder_init	(	rotary_encoder_info_t *	info,
		gpio_num_t	pin_a,
		gpio_num_t	pin_b
	)

Initialise the rotary encoder device with the specified GPIO pins and full step increments. This function will set up the GPIOs as needed, Note: this function assumes that gpio_install_isr_service(0) has already been called.

Parameters

[in,out]	info	Pointer to allocated rotary encoder info structure.
[in]	pin_a	GPIO number for rotary encoder output A.
[in]	pin_b	GPIO number for rotary encoder output B.

Returns: ESP_OK if successful, ESP_FAIL or ESP_ERR_* if an error occurred.

esp_err_t rotary_encoder_enable_half_steps	(	rotary_encoder_info_t *	info,
		bool	enable
	)

Enable half-stepping mode. This generates twice as many counted steps per rotation.

Parameters

[in]	info	Pointer to initialised rotary encoder info structure.
[in]	enable	If true, count half steps. If false, only count full steps.

Returns: ESP_OK if successful, ESP_FAIL or ESP_ERR_* if an error occurred.

esp_err_t rotary_encoder_flip_direction ( rotary_encoder_info_t * info )

Reverse (flip) the sense of the direction. Use this if clockwise/counterclockwise are not what you expect.

Parameters

[in] info Pointer to initialised rotary encoder info structure.

Returns: ESP_OK if successful, ESP_FAIL or ESP_ERR_* if an error occurred.

esp_err_t rotary_encoder_uninit ( rotary_encoder_info_t * info )

Remove the interrupt handlers installed by rotary_encoder_init. Note: GPIOs will be left in the state they were configured by rotary_encoder_init.

Parameters

[in] info Pointer to initialised rotary encoder info structure.

Returns: ESP_OK if successful, ESP_FAIL or ESP_ERR_* if an error occurred.

QueueHandle_t rotary_encoder_create_queue ( void )

Create a queue handle suitable for use as an event queue.

Returns: A handle to a new queue suitable for use as an event queue.

esp_err_t rotary_encoder_set_queue	(	rotary_encoder_info_t *	info,
		QueueHandle_t	queue
	)

Set the driver to use the specified queue as an event queue. It is recommended that a queue constructed by rotary_encoder_create_queue is used.

Parameters

[in]	info	Pointer to initialised rotary encoder info structure.
[in]	queue	Handle to queue suitable for use as an event queue. See rotary_encoder_create_queue.

Returns: ESP_OK if successful, ESP_FAIL or ESP_ERR_* if an error occurred.

esp_err_t rotary_encoder_get_state	(	const rotary_encoder_info_t *	info,
		rotary_encoder_state_t *	state
	)

Get the current position of the rotary encoder.

Parameters

[in]	info	Pointer to initialised rotary encoder info structure.
[in,out]	state	Pointer to an allocated rotary_encoder_state_t struct that will

Returns: ESP_OK if successful, ESP_FAIL or ESP_ERR_* if an error occurred.

esp_err_t rotary_encoder_reset ( rotary_encoder_info_t * info )

Reset the current position of the rotary encoder to zero.

Parameters

[in] info Pointer to initialised rotary encoder info structure.

Returns: ESP_OK if successful, ESP_FAIL or ESP_ERR_* if an error occurred.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation