Functions
void	QEIEnable (uint32_t ui32Base)

void	QEIDisable (uint32_t ui32Base)

void	QEIConfigure (uint32_t ui32Base, uint32_t ui32Config, uint32_t ui32MaxPosition)

uint32_t	QEIPositionGet (uint32_t ui32Base)

void	QEIPositionSet (uint32_t ui32Base, uint32_t ui32Position)

int32_t	QEIDirectionGet (uint32_t ui32Base)

bool	QEIErrorGet (uint32_t ui32Base)

void	QEIFilterEnable (uint32_t ui32Base)

void	QEIFilterDisable (uint32_t ui32Base)

void	QEIFilterConfigure (uint32_t ui32Base, uint32_t ui32FiltCnt)

void	QEIVelocityEnable (uint32_t ui32Base)

void	QEIVelocityDisable (uint32_t ui32Base)

void	QEIVelocityConfigure (uint32_t ui32Base, uint32_t ui32PreDiv, uint32_t ui32Period)

uint32_t	QEIVelocityGet (uint32_t ui32Base)

void	QEIIntRegister (uint32_t ui32Base, void(*pfnHandler)(void))

void	QEIIntUnregister (uint32_t ui32Base)

void	QEIIntEnable (uint32_t ui32Base, uint32_t ui32IntFlags)

void	QEIIntDisable (uint32_t ui32Base, uint32_t ui32IntFlags)

uint32_t	QEIIntStatus (uint32_t ui32Base, bool bMasked)

void	QEIIntClear (uint32_t ui32Base, uint32_t ui32IntFlags)

Detailed Description

Introduction

The quadrature encoder API provides a set of functions for dealing with the Quadrature Encoder with Index (QEI). Functions are provided to configure and read the position and velocity captures, register a QEI interrupt handler, and handle QEI interrupt masking/clearing.

The quadrature encoder module provides hardware encoding of the two channels and the index signal from a quadrature encoder device into an absolute or relative position. There is additional hardware for capturing a measure of the encoder velocity, which is simply a count of encoder pulses during a fixed time period; the number of pulses is directly proportional to the encoder speed. Note that the velocity capture can only operate when the position capture is enabled.

The QEI module supports two modes of operation: phase mode and clock/direction mode. In phase mode, the encoder produces two clocks that are 90 degrees out of phase; the edge relationship is used to determine the direction of rotation. In clock/direction mode, the encoder produces a clock signal to indicate steps and a direction signal to indicate the direction of rotation.

When in phase mode, edges on the first channel or edges on both channels can be counted; counting edges on both channels provides higher encoder resolution if required. In either mode, the input signals can be swapped before being processed, allowing wiring mistakes to be corrected without modifying the circuit board.

The index pulse can be used to reset the position counter, allowing the position counter to maintain the absolute encoder position. Otherwise, the position counter maintains the relative position and is never reset.

The velocity capture has a timer to measure equal periods of time. The number of encoder pulses over each time period is accumulated as a measure of the encoder velocity. The running total for the current time period and the final count for the previous time period are available to be read. The final count for the previous time period is usually used as the velocity measure.

The QEI module generates interrupts when the index pulse is detected, when the velocity timer expires, when the encoder direction changes, and when a phase signal error is detected. These interrupt sources can be individually masked so that only the events of interest cause a processor interrupt.

API Functions

The quadrature encoder API is broken into three groups of functions: those that deal with position capture, those that deal with velocity capture, and those that deal with interrupt handling.

The position capture is managed with QEIEnable(), QEIDisable(),QEIConfigure(), and QEIPositionSet(). The positional information is retrieved with QEIPositionGet(), QEIDirectionGet(), and QEIErrorGet().

The velocity capture is managed with QEIVelocityEnable(), QEIVelocityDisable(), and QEIVelocityConfigure(). The computed encoder velocity is retrieved with QEIVelocityGet().

The interrupt handler for the QEI interrupt is managed with QEIIntRegister() and QEIIntUnregister(). The individual interrupt sources within the QEI module are managed with QEIIntEnable(), QEIIntDisable(), QEIIntStatus(), and QEIIntClear().

Programming Example

The following example shows how to use the Quadrature Encoder API to configure the quadrature encoder read back an absolute position.

//
// Enable the QEI0 peripheral
//
SysCtlPeripheralEnable(SYSCTL_PERIPH_QEI0);
//
// Wait for the QEI0 module to be ready.
//
while(!SysCtlPeripheralReady(SYSCTL_PERIPH_QEI0))
{
}
//
// Configure the quadrature encoder to capture edges on both signals and
// maintain an absolute position by resetting on index pulses.  Using a
// 1000 line encoder at four edges per line, there are 4000 pulses per
// revolution; therefore set the maximum position to 3999 as the count
// is zero based.
//
QEIConfigure(QEI_BASE, (QEI_CONFIG_CAPTURE_A_B | QEI_CONFIG_RESET_IDX |
                        QEI_CONFIG_QUADRATURE | QEI_CONFIG_NO_SWAP), 3999);
//
// Enable the quadrature encoder.
//
QEIEnable(QEI_BASE);
//
// Delay for some time...
//
//
// Read the encoder position.
//
QEIPositionGet(QEI_BASE);

Function Documentation

§ QEIEnable()

void QEIEnable ( uint32_t ui32Base )

Enables the quadrature encoder.

Parameters

ui32Base is the base address of the quadrature encoder module.

This function enables operation of the quadrature encoder module. The module must be configured before it is enabled.

See also: QEIConfigure()

Returns: None.

References ASSERT, HWREG, QEI_CTL_ENABLE, and QEI_O_CTL.

§ QEIDisable()

void QEIDisable ( uint32_t ui32Base )

Disables the quadrature encoder.

Parameters

ui32Base is the base address of the quadrature encoder module.

This function disables operation of the quadrature encoder module.

Returns: None.

References ASSERT, HWREG, QEI_CTL_ENABLE, and QEI_O_CTL.

§ QEIConfigure()

void QEIConfigure	(	uint32_t	ui32Base,
		uint32_t	ui32Config,
		uint32_t	ui32MaxPosition
	)

Configures the quadrature encoder.

Parameters

ui32Base	is the base address of the quadrature encoder module.
ui32Config	is the configuration for the quadrature encoder. See below for a description of this parameter.
ui32MaxPosition	specifies the maximum position value.

This function configures the operation of the quadrature encoder. The ui32Config parameter provides the configuration of the encoder and is the logical OR of several values:

QEI_CONFIG_CAPTURE_A or QEI_CONFIG_CAPTURE_A_B specify if edges on channel A or on both channels A and B should be counted by the position integrator and velocity accumulator.
QEI_CONFIG_NO_RESET or QEI_CONFIG_RESET_IDX specify if the position integrator should be reset when the index pulse is detected.
QEI_CONFIG_QUADRATURE or QEI_CONFIG_CLOCK_DIR specify if quadrature signals are being provided on ChA and ChB, or if a direction signal and a clock are being provided instead.
QEI_CONFIG_NO_SWAP or QEI_CONFIG_SWAP to specify if the signals provided on ChA and ChB should be swapped before being processed.

ui32MaxPosition is the maximum value of the position integrator and is the value used to reset the position capture when in index reset mode and moving in the reverse (negative) direction.

Returns: None.

References ASSERT, HWREG, QEI_CTL_CAPMODE, QEI_CTL_RESMODE, QEI_CTL_SIGMODE, QEI_CTL_SWAP, QEI_O_CTL, and QEI_O_MAXPOS.

§ QEIPositionGet()

uint32_t QEIPositionGet ( uint32_t ui32Base )

Gets the current encoder position.

Parameters

ui32Base is the base address of the quadrature encoder module.

This function returns the current position of the encoder. Depending upon the configuration of the encoder, and the incident of an index pulse, this value may or may not contain the expected data (that is, if in reset on index mode, if an index pulse has not been encountered, the position counter is not yet aligned with the index pulse).

Returns: The current position of the encoder.

References ASSERT, HWREG, and QEI_O_POS.

§ QEIPositionSet()

void QEIPositionSet	(	uint32_t	ui32Base,
		uint32_t	ui32Position
	)

Sets the current encoder position.

Parameters

ui32Base	is the base address of the quadrature encoder module.
ui32Position	is the new position for the encoder.

This function sets the current position of the encoder; the encoder position is then measured relative to this value.

Returns: None.

References ASSERT, HWREG, and QEI_O_POS.

§ QEIDirectionGet()

int32_t QEIDirectionGet ( uint32_t ui32Base )

Gets the current direction of rotation.

Parameters

ui32Base is the base address of the quadrature encoder module.

This function returns the current direction of rotation. In this case, current means the most recently detected direction of the encoder; it may not be presently moving but this is the direction it last moved before it stopped.

Returns: Returns 1 if moving in the forward direction or -1 if moving in the reverse direction.

References ASSERT, HWREG, QEI_O_STAT, and QEI_STAT_DIRECTION.

§ QEIErrorGet()

bool QEIErrorGet ( uint32_t ui32Base )

Gets the encoder error indicator.

Parameters

ui32Base is the base address of the quadrature encoder module.

This function returns the error indicator for the quadrature encoder. It is an error for both of the signals of the quadrature input to change at the same time.

Returns: Returns true if an error has occurred and false otherwise.

References ASSERT, HWREG, QEI_O_STAT, and QEI_STAT_ERROR.

§ QEIFilterEnable()

void QEIFilterEnable ( uint32_t ui32Base )

Enables the input filter.

Parameters

ui32Base is the base address of the quadrature encoder module.

This function enables operation of the input filter in the quadrature encoder module. The module must be configured before input filter is enabled.

See also: QEIFilterConfigure() and QEIEnable()

Returns: None.

References ASSERT, HWREG, QEI_CTL_FILTEN, and QEI_O_CTL.

§ QEIFilterDisable()

void QEIFilterDisable ( uint32_t ui32Base )

Disables the input filter.

Parameters

ui32Base is the base address of the quadrature encoder module.

This function disables operation of the input filter in the quadrature encoder module.

Returns: None.

References ASSERT, HWREG, QEI_CTL_FILTEN, and QEI_O_CTL.

§ QEIFilterConfigure()

void QEIFilterConfigure	(	uint32_t	ui32Base,
		uint32_t	ui32FiltCnt
	)

Configures the input filter.

Parameters

ui32Base is the base address of the quadrature encoder module.

ui32FiltCnt specifies the filter count applied to the input quadrature signal before it is counted; can be one of QEI_FILTCNT_2, QEI_FILTCNT_3, QEI_FILTCNT_4, QEI_FILTCNT_5, QEI_FILTCNT_6, QEI_FILTCNT_7, QEI_FILTCNT_8, QEI_FILTCNT_9, QEI_FILTCNT_10, QEI_FILTCNT_11, QEI_FILTCNT_12, QEI_FILTCNT_13, QEI_FILTCNT_14, QEI_FILTCNT_15, QEI_FILTCNT_16 or QEI_FILTCNT_17

This function configures the operation of the input filter prescale count. as specified by ui32FiltCnt before the input signals are sent to the quadrature encoder module.

Returns: None.

References ASSERT, HWREG, QEI_CTL_FILTCNT_M, and QEI_O_CTL.

§ QEIVelocityEnable()

void QEIVelocityEnable ( uint32_t ui32Base )

Enables the velocity capture.

Parameters

ui32Base is the base address of the quadrature encoder module.

This function enables operation of the velocity capture in the quadrature encoder module. The module must be configured before velocity capture is enabled.

See also: QEIVelocityConfigure() and QEIEnable()

Returns: None.

References ASSERT, HWREG, QEI_CTL_VELEN, and QEI_O_CTL.

§ QEIVelocityDisable()

void QEIVelocityDisable ( uint32_t ui32Base )

Disables the velocity capture.

Parameters

ui32Base is the base address of the quadrature encoder module.

This function disables operation of the velocity capture in the quadrature encoder module.

Returns: None.

References ASSERT, HWREG, QEI_CTL_VELEN, and QEI_O_CTL.

§ QEIVelocityConfigure()

void QEIVelocityConfigure	(	uint32_t	ui32Base,
		uint32_t	ui32PreDiv,
		uint32_t	ui32Period
	)

Configures the velocity capture.

Parameters

ui32Base	is the base address of the quadrature encoder module.
ui32PreDiv	specifies the predivider applied to the input quadrature signal before it is counted; can be one of QEI_VELDIV_1, QEI_VELDIV_2, QEI_VELDIV_4, QEI_VELDIV_8, QEI_VELDIV_16, QEI_VELDIV_32, QEI_VELDIV_64, or QEI_VELDIV_128.
ui32Period	specifies the number of clock ticks over which to measure the velocity; must be non-zero.

This function configures the operation of the velocity capture portion of the quadrature encoder. The position increment signal is predivided as specified by ui32PreDiv before being accumulated by the velocity capture. The divided signal is accumulated over ui32Period system clock before being saved and resetting the accumulator.

Returns: None.

References ASSERT, HWREG, QEI_CTL_VELDIV_M, QEI_O_CTL, and QEI_O_LOAD.

§ QEIVelocityGet()

uint32_t QEIVelocityGet ( uint32_t ui32Base )

Gets the current encoder speed.

Parameters

ui32Base is the base address of the quadrature encoder module.

This function returns the current speed of the encoder. The value returned is the number of pulses detected in the specified time period; this number can be multiplied by the number of time periods per second and divided by the number of pulses per revolution to obtain the number of revolutions per second.

Returns: Returns the number of pulses captured in the given time period.

References ASSERT, HWREG, and QEI_O_SPEED.

§ QEIIntRegister()

void QEIIntRegister	(	uint32_t	ui32Base,
		void(*)(void)	pfnHandler
	)

Registers an interrupt handler for the quadrature encoder interrupt.

Parameters

ui32Base	is the base address of the quadrature encoder module.
pfnHandler	is a pointer to the function to be called when the quadrature encoder interrupt occurs.

This function registers the handler to be called when a quadrature encoder interrupt occurs. This function enables the global interrupt in the interrupt controller; specific quadrature encoder interrupts must be enabled via QEIIntEnable(). It is the interrupt handler's responsibility to clear the interrupt source via QEIIntClear().

See also: IntRegister() for important information about registering interrupt handlers.

Returns: None.

References ASSERT.

§ QEIIntUnregister()

void QEIIntUnregister ( uint32_t ui32Base )

Unregisters an interrupt handler for the quadrature encoder interrupt.

Parameters

ui32Base is the base address of the quadrature encoder module.

This function unregisters the handler to be called when a quadrature encoder interrupt occurs. This function also masks off the interrupt in the interrupt controller so that the interrupt handler no longer is called.

See also: IntRegister() for important information about registering interrupt handlers.

Returns: None.

References ASSERT.

§ QEIIntEnable()

void QEIIntEnable	(	uint32_t	ui32Base,
		uint32_t	ui32IntFlags
	)

Enables individual quadrature encoder interrupt sources.

Parameters

ui32Base	is the base address of the quadrature encoder module.
ui32IntFlags	is a bit mask of the interrupt sources to be enabled. Can be any of the QEI_INTERROR, QEI_INTDIR, QEI_INTTIMER, or QEI_INTINDEX values.

This function enables the indicated quadrature encoder interrupt sources. Only the sources that are enabled can be reflected to the processor interrupt; disabled sources have no effect on the processor.

Returns: None.

References ASSERT, HWREG, and QEI_O_INTEN.

§ QEIIntDisable()

void QEIIntDisable	(	uint32_t	ui32Base,
		uint32_t	ui32IntFlags
	)

Disables individual quadrature encoder interrupt sources.

Parameters

ui32Base	is the base address of the quadrature encoder module.
ui32IntFlags	is a bit mask of the interrupt sources to be disabled. This parameter can be any of the QEI_INTERROR, QEI_INTDIR, QEI_INTTIMER, or QEI_INTINDEX values.

This function disables the indicated quadrature encoder interrupt sources. Only the sources that are enabled can be reflected to the processor interrupt; disabled sources have no effect on the processor.

Returns: None.

References ASSERT, HWREG, and QEI_O_INTEN.

§ QEIIntStatus()

uint32_t QEIIntStatus	(	uint32_t	ui32Base,
		bool	bMasked
	)

Gets the current interrupt status.

Parameters

ui32Base	is the base address of the quadrature encoder module.
bMasked	is false if the raw interrupt status is required and true if the masked interrupt status is required.

This function returns the interrupt status for the quadrature encoder module. Either the raw interrupt status or the status of interrupts that are allowed to reflect to the processor can be returned.

Returns: Returns the current interrupt status, enumerated as a bit field of QEI_INTERROR, QEI_INTDIR, QEI_INTTIMER, and QEI_INTINDEX.

References ASSERT, HWREG, QEI_O_ISC, and QEI_O_RIS.

§ QEIIntClear()

void QEIIntClear	(	uint32_t	ui32Base,
		uint32_t	ui32IntFlags
	)

Clears quadrature encoder interrupt sources.

Parameters

ui32Base	is the base address of the quadrature encoder module.
ui32IntFlags	is a bit mask of the interrupt sources to be cleared. This parameter can be any of the QEI_INTERROR, QEI_INTDIR, QEI_INTTIMER, or QEI_INTINDEX values.

The specified quadrature encoder interrupt sources are cleared, so that they no longer assert. This function must be called in the interrupt handler to keep the interrupt from being triggered again immediately upon exit.

Note: Because there is a write buffer in the Cortex-M processor, it may take several clock cycles before the interrupt source is actually cleared. Therefore, it is recommended that the interrupt source be cleared early in the interrupt handler (as opposed to the very last action) to avoid returning from the interrupt handler before the interrupt source is actually cleared. Failure to do so may result in the interrupt handler being immediately reentered (because the interrupt controller still sees the interrupt source asserted).

Returns: None.

References ASSERT, HWREG, and QEI_O_ISC.