3.18 QEI Driver

Overview

The Quadrature Encoder Interface (QEI) provides the interface to incremental encoders for obtaining mechanical position data. Detects position and speed of rotating motion systems.

Features

Configurable QEI operation mode.
Configurable Digital noise filter clock frequency.
Configurable Index and Home pulse polarity.
QEI input clock prescalar value is user configurable in the Hardware Dependency module (PLIB).

3.18.1 Module Documentation

3.18.1.1 QEI Driver

The Quadrature Encoder Interface (QEI) driver provides the interface to incremental encoders for obtaining mechanical position data and Also Detects position and speed of rotating motion systems using dsPIC MCUs.

3.18.1.1.1 Module description

Data structures

struct QEI_INTERFACE

Structure containing the function pointers of QEI driver.

Enumerations

enum QEI_MODE { QEI_MODE_FREE_RUNNING = 0, QEI_MODE_RESET_ON_INDEX = 1, QEI_MODE_2 = 2, QEI_MODE_3 = 3, QEI_MODE_4 = 4, QEI_MODE_5 = 5, QEI_MODE_MODULO_COUNT = 6 }

Defines the QEI operating mode.
enum QEI_IMV_STATE { QEI_IMV_STATE_A0B0 = 0, QEI_IMV_STATE_A1B0 = 1, QEI_IMV_STATE_A0B1 = 2, QEI_IMV_STATE_A1B1 = 3, QEI_MAX_IMV_STATE }

Defines the QEI Index Match Value states.

Functions

static void QEI1_Disable (void)

This inline function disables the QEI1 module.
static void QEI1_Enable (void)

This inline function enables the QEI1 module.
static uint32_t QEI1_PositionCountRead (void)

This inline function returns the 32-bit position count value.
static uint16_t QEI1_PositionCount16bitRead (void)

This inline function returns the 16-bit position count value from the QEI1 position count register.
static void QEI1_PositionCountWrite (uint32_t positionCount)

This inline function sets the QEI1 position count value.
static void QEI1_ModuloRangeSet (uint32_t countsPerRevolution)

This inline function sets the 32bit modulo count value when QEI is configured to operate in 'Modulo Count' mode. The lower bound controlled by the QEILEC register is set to 0.
static bool QEI1_PhaseInputSwappedGet (void)

This inline function gets the status of QEI input phase swap configuration
static void QEI1_PhaseInputSwappedSet (bool swapEnabled)

This inline function sets whether the QEA and QEB pins are swapped prior to quadrature decoder logic.
static void QEI1_PositionCaptureEnable (void)

This inline function enables the QEI position count capture on an index event.
static void QEI1_PositionCaptureDisable (void)

This inline function disables the QEI position count capture on an index event.
static uint32_t QEI1_PositionCaptureGet (void)

This inline function reads the 32-bit position capture value from the QEIICx 32 bit register.
static uint16_t QEI1_PositionCapture16bitGet (void)

This inline function returns the 16-bit position capture value from QEIGEC position count capture register.
static void QEI1_PositionCaptureSet (uint32_t initValue)

This inline function initializes the 32 bit position capture register value.
static void QEI1_CounterModeSet (enum QEI_MODE mode)

This inline function sets the QEI Counter mode.
static void QEI1_IMVGatedValueSet (enum QEI_IMV_STATE state)

This inline function sets the QEI Index Match Value.
void QEI1_Initialize (void)

Initializes the QEI module.
void QEI1_Deinitialize (void)

Deinitializes the QEI1 to POR values.

Variables

const struct QEI_INTERFACE QEI1

Structure object of type QEI_INTERFACE with the custom name given by the user in the Melody Driver User interface. The default name e.g. QEI1 can be changed by the user in the QEI user interface. This allows defining a structure with application specific name using the 'Custom Name' field. Application specific name allows the API Portability.

3.18.1.1.2 Function Documentation

QEI1_CounterModeSet()

inline static void QEI1_CounterModeSet (enum QEI_MODE mode)

This inline function sets the QEI Counter mode.

Parameters:
in	mode	- Sets the QEI counter mode

Returns:
none

QEI1_Deinitialize()

void QEI1_Deinitialize (void )

Deinitializes the QEI1 to POR values.

Parameters:
none

Returns:
none

QEI1_Disable()

inline static void QEI1_Disable (void )

This inline function disables the QEI1 module.

Parameters:
none

Returns:
none

QEI1_Enable()

inline static void QEI1_Enable (void )

This inline function enables the QEI1 module.

Parameters:
none

Returns:
none

QEI1_IMVGatedValueSet()

inline static void QEI1_IMVGatedValueSet (enum QEI_IMV_STATE state)

This inline function sets the QEI Index Match Value.

Parameters:
in	mode	- Sets the QEI Index Match Value

Returns:
none

QEI1_Initialize()

void QEI1_Initialize (void )

Initializes the QEI module.

Parameters:
none

Returns:
none

QEI1_ModuloRangeSet()

inline static void QEI1_ModuloRangeSet (uint32_t countsPerRevolution)

This inline function sets the 32bit modulo count value when QEI is configured to operate in 'Modulo Count' mode. The lower bound controlled by the QEILEC register is set to 0.

Parameters:
in	countsPerRevolution	- Modulus number of counts per wraparound

Returns:
none

QEI1_PhaseInputSwappedGet()

inline static bool QEI1_PhaseInputSwappedGet (void )

This inline function gets the status of QEI input phase swap configuration

Parameters:
none

Returns:
true - Phase inputs are swapped false - Phase inputs are not swapped

QEI1_PhaseInputSwappedSet()

inline static void QEI1_PhaseInputSwappedSet (bool swapEnabled)

This inline function sets whether the QEA and QEB pins are swapped prior to quadrature decoder logic.

Parameters:
in	swapEnabled	- specifies whether QEA and QEB pins need to be swapped prior to quadrature decoder logic

Returns:
none

QEI1_PositionCapture16bitGet()

inline static uint16_t QEI1_PositionCapture16bitGet (void )

This inline function returns the 16-bit position capture value from QEIGEC position count capture register.

Parameters:
none

Returns:
Returns the LSB 16 bits of position capture value

QEI1_PositionCaptureDisable()

inline static void QEI1_PositionCaptureDisable (void )

This inline function disables the QEI position count capture on an index event.

Parameters:
none

Returns:
none

QEI1_PositionCaptureEnable()

inline static void QEI1_PositionCaptureEnable (void )

This inline function enables the QEI position count capture on an index event.

Parameters:
none

Returns:
none

QEI1_PositionCaptureGet()

inline static uint32_t QEI1_PositionCaptureGet (void )

This inline function reads the 32-bit position capture value from the QEIICx 32 bit register.

Parameters:
none

Returns:
Returns position capture value

QEI1_PositionCaptureSet()

inline static void QEI1_PositionCaptureSet (uint32_t initValue)

This inline function initializes the 32 bit position capture register value.

Parameters:
in	initValue	- 32 bit position capture register value

Returns:
none

QEI1_PositionCount16bitRead()

inline static uint16_t QEI1_PositionCount16bitRead (void )

This inline function returns the 16-bit position count value from the QEI1 position count register.

Parameters:
none

Returns:
Returns the LSB 16 bits of the QEI1 position count register.

QEI1_PositionCountRead()

inline static uint32_t QEI1_PositionCountRead (void )

This inline function returns the 32-bit position count value.

Parameters:
none

Returns:
Returns the 32-bit position count register value

QEI1_PositionCountWrite()

inline static void QEI1_PositionCountWrite (uint32_t positionCount)

This inline function sets the QEI1 position count value.

Parameters:
in	positionCount	- 32-bit position count value

Returns:
none

3.18.1.1.3 Enumeration Type Documentation

QEI_IMV_STATE

enum QEI_IMV_STATE

Defines the QEI Index Match Value states.


QEI_IMV_STATE_A0B0	Index Match Value State : QEA = 0 and QEB = 0
QEI_IMV_STATE_A1B0	Index Match Value State : QEA = 1 and QEB = 0
QEI_IMV_STATE_A0B1	Index Match Value State : QEA = 0 and QEB = 1
QEI_IMV_STATE_A1B1	Index Match Value State : QEA = 1 and QEB = 1
QEI_MAX_IMV_STATE	Maximum configurable Index Match Value State

QEI_MODE

enum QEI_MODE

Defines the QEI operating mode.


QEI_MODE_FREE_RUNNING	Index input event does not affect position counter
QEI_MODE_RESET_ON_INDEX	Every index input event resets the position counter
QEI_MODE_2	Next index input event initializes the position counter with contents of QEI1IC register
QEI_MODE_3	First index event after home event initializes position counter with contents of QEI1IC register
QEI_MODE_4	Second index event after home event initializes position counter with contents of QEI1IC register
QEI_MODE_5	Resets the position counter when the position counter equals QEI1GEC register
QEI_MODE_MODULO_COUNT	Modulo Count mode for position counter

3.18.1.1.4 Variable Documentation

QEI1

const struct QEI_INTERFACE QEI1

Structure object of type QEI_INTERFACE with the custom name given by the user in the Melody Driver User interface. The default name e.g. QEI1 can be changed by the user in the QEI user interface. This allows defining a structure with application specific name using the 'Custom Name' field. Application specific name allows the API Portability.

3.18.2 Data Structure Documentation

3.18.2.1 QEI_INTERFACE Struct Reference

Structure containing the function pointers of QEI driver.

3.18.2.1.1 Detailed Description

Structure containing the function pointers of QEI driver.

#include <qei_interface.h>

Data Fields

void(* Initialize )(void)

Pointer to QEIx_Initialize e.g. QEI1_Initialize.
void(* Deinitialize )(void)

Pointer to QEIx_Deinitialize e.g. QEI1_Deinitialize.
void(* Enable )(void)

Pointer to QEIx_Enable e.g. QEI1_Enable.
void(* Disable )(void)

Pointer to QEIx_Disable e.g. QEI1_Disable.
uint32_t(* PositionCountRead )(void)

Pointer to QEIx_PositionCountRead e.g. QEI1_PositionCountRead.
uint16_t(* PositionCount16bitRead )(void)

Pointer to QEIx_PositionCount16bitRead e.g. QEI1_PositionCount16bitRead.
void(* PositionCountWrite )(uint32_t positionCount)

Pointer to QEIx_PositionCountWrite e.g. QEI1_PositionCountWrite.
void(* ModuloRangeSet )(uint32_t countsPerRevolution)

Pointer to QEIx_ModuloRangeSet e.g. QEI1_ModuloRangeSet.
bool(* PhaseInputSwappedGet )(void)

Pointer to QEIx_PhaseInputSwappedGet e.g. QEI1_PhaseInputSwappedGet.
void(* PhaseInputSwappedSet )(bool swapEnabled)

Pointer to QEIx_PhaseInputSwappedSet e.g. QEI1_PhaseInputSwappedSet.
void(* PositionCaptureEnable )(void)

Pointer to QEIx_PositionCaptureEnable e.g. QEI1_PositionCaptureEnable.
void(* PositionCaptureDisable )(void)

Pointer to QEIx_PositionCaptureDisable e.g. QEI1_PositionCaptureDisable.
uint32_t(* PositionCaptureGet )(void)

Pointer to QEIx_PositionCaptureGet e.g. QEI1_PositionCaptureGet.
uint16_t(* PositionCapture16bitGet )(void)

Pointer to QEIx_PositionCapture16bitGet e.g. QEI1_PositionCapture16bitGet.
void(* PositionCaptureSet )(uint32_t initValue)

Pointer to QEIx_PositionCaptureSet e.g. QEI1_PositionCaptureSet.
void(* CounterModeSet )(enum QEI_MODE mode)

Pointer to QEIx_CounterModeSet e.g. QEI1_CounterModeSet.
void(* IMVGatedValueSet )(enum QEI_IMV_STATE state)

Pointer to QEIx_IMVGatedValueSet e.g. QEI1_IMVGatedValueSet.

3.18.2.1.2 Field Documentation

The documentation for this struct was generated from the following file:

source/

qei_interface.h

CounterModeSet

void(* CounterModeSet) (enum QEI_MODE mode)

Pointer to QEIx_CounterModeSet e.g. QEI1_CounterModeSet.

Deinitialize

void(* Deinitialize) (void)

Pointer to QEIx_Deinitialize e.g. QEI1_Deinitialize.

Disable

void(* Disable) (void)

Pointer to QEIx_Disable e.g. QEI1_Disable.

Enable

void(* Enable) (void)

Pointer to QEIx_Enable e.g. QEI1_Enable.

IMVGatedValueSet

void(* IMVGatedValueSet) (enum QEI_IMV_STATE state)

Pointer to QEIx_IMVGatedValueSet e.g. QEI1_IMVGatedValueSet.

Initialize

void(* Initialize) (void)

Pointer to QEIx_Initialize e.g. QEI1_Initialize.

ModuloRangeSet

void(* ModuloRangeSet) (uint32_t countsPerRevolution)

Pointer to QEIx_ModuloRangeSet e.g. QEI1_ModuloRangeSet.

PhaseInputSwappedGet

bool(* PhaseInputSwappedGet) (void)

Pointer to QEIx_PhaseInputSwappedGet e.g. QEI1_PhaseInputSwappedGet.

PhaseInputSwappedSet

void(* PhaseInputSwappedSet) (bool swapEnabled)

Pointer to QEIx_PhaseInputSwappedSet e.g. QEI1_PhaseInputSwappedSet.

PositionCapture16bitGet

uint16_t(* PositionCapture16bitGet) (void)

Pointer to QEIx_PositionCapture16bitGet e.g. QEI1_PositionCapture16bitGet.

PositionCaptureDisable

void(* PositionCaptureDisable) (void)

Pointer to QEIx_PositionCaptureDisable e.g. QEI1_PositionCaptureDisable.

PositionCaptureEnable

void(* PositionCaptureEnable) (void)

Pointer to QEIx_PositionCaptureEnable e.g. QEI1_PositionCaptureEnable.

PositionCaptureGet

uint32_t(* PositionCaptureGet) (void)

Pointer to QEIx_PositionCaptureGet e.g. QEI1_PositionCaptureGet.

PositionCaptureSet

void(* PositionCaptureSet) (uint32_t initValue)

Pointer to QEIx_PositionCaptureSet e.g. QEI1_PositionCaptureSet.

PositionCount16bitRead

uint16_t(* PositionCount16bitRead) (void)

Pointer to QEIx_PositionCount16bitRead e.g. QEI1_PositionCount16bitRead.

PositionCountRead

uint32_t(* PositionCountRead) (void)

Pointer to QEIx_PositionCountRead e.g. QEI1_PositionCountRead.

PositionCountWrite

void(* PositionCountWrite) (uint32_t positionCount)

Pointer to QEIx_PositionCountWrite e.g. QEI1_PositionCountWrite.

3.18.3 File Documentation

3.18.3.1 source/qei1.h File Reference

This is the generated driver header file for the QEI1 driver.

#include <xc.h>
#include <stdbool.h>
#include <stdint.h>
#include "qei_types.h"
#include "qei_interface.h"

3.18.3.1.1 Functions

static void QEI1_Disable (void)

This inline function disables the QEI1 module.
static void QEI1_Enable (void)

This inline function enables the QEI1 module.
static uint32_t QEI1_PositionCountRead (void)

This inline function returns the 32-bit position count value.
static uint16_t QEI1_PositionCount16bitRead (void)

This inline function returns the 16-bit position count value from the QEI1 position count register.
static void QEI1_PositionCountWrite (uint32_t positionCount)

This inline function sets the QEI1 position count value.
static void QEI1_ModuloRangeSet (uint32_t countsPerRevolution)

This inline function sets the 32bit modulo count value when QEI is configured to operate in 'Modulo Count' mode. The lower bound controlled by the QEILEC register is set to 0.
static bool QEI1_PhaseInputSwappedGet (void)

This inline function gets the status of QEI input phase swap configuration
static void QEI1_PhaseInputSwappedSet (bool swapEnabled)

This inline function sets whether the QEA and QEB pins are swapped prior to quadrature decoder logic.
static void QEI1_PositionCaptureEnable (void)

This inline function enables the QEI position count capture on an index event.
static void QEI1_PositionCaptureDisable (void)

This inline function disables the QEI position count capture on an index event.
static uint32_t QEI1_PositionCaptureGet (void)

This inline function reads the 32-bit position capture value from the QEIICx 32 bit register.
static uint16_t QEI1_PositionCapture16bitGet (void)

This inline function returns the 16-bit position capture value from QEIGEC position count capture register.
static void QEI1_PositionCaptureSet (uint32_t initValue)

This inline function initializes the 32 bit position capture register value.
static void QEI1_CounterModeSet (enum QEI_MODE mode)

This inline function sets the QEI Counter mode.
static void QEI1_IMVGatedValueSet (enum QEI_IMV_STATE state)

This inline function sets the QEI Index Match Value.
void QEI1_Initialize (void)

Initializes the QEI module.
void QEI1_Deinitialize (void)

Deinitializes the QEI1 to POR values.

3.18.3.1.2 Variables

const struct QEI_INTERFACE QEI1

Structure object of type QEI_INTERFACE with the custom name given by the user in the Melody Driver User interface. The default name e.g. QEI1 can be changed by the user in the QEI user interface. This allows defining a structure with application specific name using the 'Custom Name' field. Application specific name allows the API Portability.

3.18.3.1.3 Detailed Description

This is the generated driver header file for the QEI1 driver.

QEI1 Generated Driver Header File

3.18.3.2 source/qei_interface.h File Reference

#include <stdbool.h>
#include <stdint.h>
#include "qei_types.h"

3.18.3.2.1 Data structures

struct QEI_INTERFACE

Structure containing the function pointers of QEI driver.

3.18.3.2.2 Detailed Description

QEI Generated Driver Interface Header File

3.18.3.3 source/qei_types.h File Reference

This is the generated driver types header file for the QEI driver.

3.18.3.3.1 Enumerations

enum QEI_MODE { QEI_MODE_FREE_RUNNING = 0, QEI_MODE_RESET_ON_INDEX = 1, QEI_MODE_2 = 2, QEI_MODE_3 = 3, QEI_MODE_4 = 4, QEI_MODE_5 = 5, QEI_MODE_MODULO_COUNT = 6 }

Defines the QEI operating mode.
enum QEI_IMV_STATE { QEI_IMV_STATE_A0B0 = 0, QEI_IMV_STATE_A1B0 = 1, QEI_IMV_STATE_A0B1 = 2, QEI_IMV_STATE_A1B1 = 3, QEI_MAX_IMV_STATE }

Defines the QEI Index Match Value states.

3.18.3.3.2 Detailed Description

This is the generated driver types header file for the QEI driver.

QEI Generated Driver Types Header File