Files | Data Structures | Macros | Typedefs | Enumerations | Functions
Quadrature Decoder (QDEC)
Drivers » Peripheral Driver Interface

Low-level QDEC peripheral driver. More...

Detailed Description

Low-level QDEC peripheral driver.

This file was inspired by pwm.h written by : Hauke Petersen hauke.nosp@m..pet.nosp@m.ersen.nosp@m.@fu-.nosp@m.berli.nosp@m.n.de

QDEC interface enables access to CPU peripherals acquiring quadrature signals. On most platforms, this interface will be implemented based on hardware timers.

A quadrature encoder outputs two wave forms that are 90 degrees out of phase.

*
* Clockwise (C) :              Counter-clockwise (CC) :
*  ___________________          ___________________
* | Phase |  A  |  B  |        | Phase |  A  |  B  |
* |-------------------|        |-------------------|
* |   1   |  0  |  0  |        |   1   |  0  |  0  |
* |-------------------|        |-------------------|
* |   2   |  0  |  1  |        |   2   |  1  |  0  |
* |-------------------|        |-------------------|
* |   3   |  1  |  1  |        |   3   |  1  |  1  |
* |-------------------|        |-------------------|
* |   4   |  1  |  0  |        |   4   |  0  |  1  |
*  -------------------          -------------------
*         __    __                   __    __
*      __|  |__|  |_               _|  |__|  |__
*        __    __                     __    __
*      _|  |__|  |__               __|  |__|  |_
*
* These signals are decoded to produce a count up or a count down.
* On rising or falling edge of one signal, other signal state is checked to
* determine direction.
*
*  1. Rising edge on A and signal B is up       => (C)  => increment counter
*  2. Rising edge on A and signal B is down     => (CC) => decrement counter
*  3. Falling edge on A and signal B is up      => (C)  => decrement counter
*  4. Falling edge on A and signal B is down    => (CC) => increment counter
*  5. Rising edge on B and signal A is up       => (C)  => decrement counter
*  6. Rising edge on B and signal A is down     => (CC) => increment counter
*  7. Falling edge on B and signal A is up      => (C)  => increment counter
*  8. Falling edge on B and signal A is down    => (CC) => decrement counter
*

According to these cases, three modes are available :

The mapping/configuration of QDEC devices (timers) and the used pins has to be done in the board configuration (the board's `periph_conf.h).

When using the QDEC interface, first thing you have to do is initialize the QDEC device with the targeted mode. Once the device is initialized, it will start counting quadrature signals on all configured pins immediately.

Files

file  qdec.h
 Low-level QDEC peripheral driver interface definitions.
 

Data Structures

struct  qdec_isr_ctx_t
 Default interrupt context entry holding callback and argument. More...
 

Macros

#define QDEC_DEV(x)   (x)
 Default QDEC access macro.
 
#define QDEC_UNDEF   (UINT_MAX)
 Default QDEC undefined value.
 

Typedefs

typedef unsigned int qdec_t
 Default QDEC type definition.
 
typedef void(* qdec_cb_t) (void *arg)
 Signature of event callback functions triggered from interrupts. More...
 

Enumerations

enum  qdec_mode_t { QDEC_X1, QDEC_X2, QDEC_X4 }
 Default QDEC mode definition.
 

Functions

int32_t qdec_init (qdec_t dev, qdec_mode_t mode, qdec_cb_t cb, void *arg)
 Initialize a QDEC device. More...
 
int32_t qdec_read (qdec_t dev)
 Read the current value of the given qdec device. More...
 
int32_t qdec_read_and_reset (qdec_t dev)
 Read the current value of the given qdec device and reset it. More...
 
void qdec_start (qdec_t qdec)
 Start the given qdec timer. More...
 
void qdec_stop (qdec_t qdec)
 Stop the given qdec timer. More...
 

Typedef Documentation

◆ qdec_cb_t

typedef void(* qdec_cb_t) (void *arg)

Signature of event callback functions triggered from interrupts.

Parameters
[in]argoptional context for the callback

Definition at line 127 of file qdec.h.

Function Documentation

◆ qdec_init()

int32_t qdec_init ( qdec_t  dev,
qdec_mode_t  mode,
qdec_cb_t  cb,
void *  arg 
)

Initialize a QDEC device.

The QDEC module is based on virtual QDEC devices. The QDEC devices can be configured to run in three modes :

  • X1
  • X2
  • X4 See description above for more details about modes.

On QDEC counter overflow, an interrupt is triggered. The interruption calls the callback defined.

Parameters
[in]devQDEC device to initialize
[in]modeQDEC mode : X1, X2 or X4
[in]cbCallback on QDEC timer overflow
[in]argCallback arguments
Returns
error code on error
0 on success

◆ qdec_read()

int32_t qdec_read ( qdec_t  dev)

Read the current value of the given qdec device.

Parameters
[in]devthe qdec to read the current value from
Returns
the qdecs current value

◆ qdec_read_and_reset()

int32_t qdec_read_and_reset ( qdec_t  dev)

Read the current value of the given qdec device and reset it.

Parameters
[in]devthe qdec to read the current value from
Returns
the qdecs current value

◆ qdec_start()

void qdec_start ( qdec_t  qdec)

Start the given qdec timer.

This function is only needed if the qdec timer was stopped manually before.

Parameters
[in]qdecthe qdec device to start

◆ qdec_stop()

void qdec_stop ( qdec_t  qdec)

Stop the given qdec timer.

This will effect all of the timer's channels.

Parameters
[in]qdecthe qdec device to stop