Functions which handle the wheel encoders. More...

Modules
	Advanced informations

Enumerations
enum	eEncoderSelectMask
	clusters bit masks for the requests of the encoders More...

enum	eEncoderGet
	clusters select values for reading data from the encoders More...

Functions
void	encoders_clear (void)
	Clears the encoder values. More...

Request Funktions
void	encoders_request (eEncoderSelectMask bitmask, eRequestType request)
	Requests new data from the encoders. More...

eEncoderSelectMask	encoders_received (eEncoderSelectMask bitmask)
	Indicates if new data for the selected data blocks were received. More...

eEncoderSelectMask	encoders_changed (eEncoderSelectMask bitmask)
	Indicates if new data changed the selected data blocks. More...

Access Funktions
int32_t	encoders_get (eEncoderGet select)
	Returns the last stored version of the selected value. More...

Detailed Description

Functions which handle the wheel encoders.

The encoders are part of the driving module. All actions, like reading their current value or reseting them, involve internal TWI communication. This may take some milliseconds (delay time).

After requesting kEncoderSelectAbs the encoder values can be regularly read with encoders_get().

In a similar way the speed of the wheels can be measured by requesting kEncoderSelectSpeed. The speed of the wheels is calculated within the drive module of the TUC-Bot. In order to allow the maximum possible precision, there are two ways of doing that:

If requested very often (within 65ms, e.g. through continuous request), the speed is sampled every 10ms and filtered with a ring buffer. This leads to a window size of 50ms.
If only requested once in a while, no filtering is done and the intervals are indirectly defined by the time between two consecutive requests.

The clearing of the encoder values is done by calling encoders_clear(). The last stored values can be read afterwards with encoders_get().

snippets

Reading the latest absolute encoder values. The request function will wait until new encoder data is received. This might take some milliseconds.
// latest values

encoders_request(kEncoderSelectAbs, kRequestWait);

int32_t left = encoders_get(kEncoderGetLeft );

int32_t right = encoders_get(kEncoderGetRight);
Reading absolute encoder values. There will be no delay during the execution in the main loop. However, the returned encoder values might be outdated by some milliseconds.
// init

encoders_request(kEncoderSelectAbs, kRequestContinuous);

...

// within main loop

int32_t left = encoders_get(kEncoderGetLeft );

int32_t right = encoders_get(kEncoderGetRight);
Clear encoders and return their last values. This might take some milliseconds.
Do not read the current absolute encoder values instead. They are most likely outdated.
// reset encoders and store last values

encoders_clear();

int16_t left = encoders_get(kEncoderGetClearedLeft );

int16_t right = encoders_get(kEncoderGetClearedRight);

example

/*******************************************************************************
* examples/encoderSimple.c                                                     *
* ========================                                                     *
*                                                                              *
* Version: 1.1.4                                                               *
* Date   : 09.11.17                                                            *
* Author : Peter Weissig                                                       *
*******************************************************************************/
 
//*********************************<Included files>*****************************
#include <tucbot/tucbot.h>
 
//*********************************<Methods>************************************
void testEncoder(void);
int main(void);
 
//*********************************[testEncoder]********************************
void testEncoder(void) {
 
    lcdclr();
    lcdstr_p(PSTR("Encoder"         ));
    lcdxy(0,1);
    lcdstr_p(PSTR("L:#####  R:#####"));
 
    encoders_request(kEncoderSelectAbs, kRequestContinuous);
 
    while (1) {
        if (buttons_get(kButtonMiddle)) {
            leds_set(kLedMiddle, kLedOn );
            mdelay(100);
            leds_set(kLedMiddle, kLedOff);
 
            encoders_clear();
 
            mdelay(400);
        } else if (buttons_get(kButtonRight)) {
            leds_set(kLedRight , kLedOn );
            mdelay(100);
            leds_set(kLedRight , kLedOff);
 
            encoders_clear();
 
            mdelay(400);
        }
 
        if (encoders_changed(kEncoderSelectAbs)) {
            lcdxy( 2,1); int16tostr(lcdout,encoders_get(kEncoderGetLeft ),5);
            lcdxy(11,1); int16tostr(lcdout,encoders_get(kEncoderGetRight),5);
 
            mdelay(250);
        }
    }
}
 
//*********************************[main]***************************************
int main (void) {
 
    init_tucbot(0xFF);
 
    buttons_request(kRequestContinuous);
 
    testEncoder();
 
    return (0);
}

Enumeration Type Documentation

◆ eEncoderGet

enum eEncoderGet

clusters select values for reading data from the encoders

See also: encoders_get() and encoders_clear()

Enumerator
kEncoderGetLeft	constant (1): left encoder (32-bit)
kEncoderGetRight	constant (2): right encoder (32-bit)
kEncoderGetSpeedLeft	constant (3): left speed in ticks/s
kEncoderGetSpeedRight	constant (4): right speed in ticks/s
kEncoderGetClearedLeft	constant (5): left encoder before it was cleared (16-bit)
kEncoderGetClearedRight	constant (6): right encoder before it was cleared (16-bit)

◆ eEncoderSelectMask

enum eEncoderSelectMask

clusters bit masks for the requests of the encoders

See also: encoders_request(), encoders_received() and encoders_changed()

Enumerator
kEncoderSelectNone	bit mask (0x00): select no data block
kEncoderSelectAbs	bit mask (0x01): select absolute encoder values (32-bit) see also sMD_Encoder
kEncoderSelectSpeed	bit mask (0x02): select wheel speed in ticks per second see also sMD_SpeedRaw
kEncoderSelectAll	bit mask (0x03): select all data blocks (except for clear)

Function Documentation

◆ encoders_changed()

eEncoderSelectMask encoders_changed ( eEncoderSelectMask bitmask )

Indicates if new data changed the selected data blocks.

Parameters

bitmask bit mask of the selected data blocks - see also eEncoderSelectMask
The parameter is used to only return the value of the masked changed-bits. All other values(bits) are set to 0.

Returns: bitfield of the selected data blocks - see also eEncoderSelectMask
If a data block is changed its related bit will be 1, otherwise 0.
If only one data block is selected the return value can be interpreted as a boolean expression.

See also: encoders_received(), encoders_request(), encoders_get()

Examples: encoderComplex.c, and encoderSimple.c.

◆ encoders_clear()

void encoders_clear ( void )

Clears the encoder values.

This function waits until the encoder values within the drive module were cleared.

The last values of the encoders, before clearing, are stored in data block sMD_EncoderClear and can be read afterwards with encoders_get():

Involved data blocks are:
sMD_EncoderClear

Note: This function does not update the current absolute encoder values within sMD_Encoder. This must be separably requested, if needed.; Keep also in mind, that all data blocks are independent. Therefore, reading the current absolute encoder values right after clearing them, will most likely return old values, instead of zeros.

Examples: encoderComplex.c, and encoderSimple.c.

◆ encoders_get()

int32_t encoders_get ( eEncoderGet select )

Returns the last stored version of the selected value.

This function relies on the internal data blocks sMD_Encoder, sMD_SpeedRaw and sMD_EncoderClear - for new data use encoders_request() or encoders_clear().

Parameters

select value of the selected data - see also eEncoderGet

Returns

32-bit integer

select	decription	result
kEncoderGetLeft kEncoderGetRight	current encoder value in ticks	32-bit
kEncoderGetSpeedLeft kEncoderGetSpeedRight	current encoder speed in ticks/s	16-bit
kEncoderGetClearedLeft kEncoderGetClearedRight	last encoder value before reset in ticks	16-bit

See also: encoders_request() and encoders_clear()

Examples: encoderComplex.c, and encoderSimple.c.

◆ encoders_received()

eEncoderSelectMask encoders_received ( eEncoderSelectMask bitmask )

Indicates if new data for the selected data blocks were received.

Parameters

bitmask bit mask of the selected data blocks - see also eEncoderSelectMask
The parameter is used to only return the value of the masked received-bits. All other values(bits) are set to 0.

Returns: bitfield of the selected data blocks - see also eEncoderSelectMask
If a data block is received its related bit will be 1, otherwise 0.
If only one data block is selected the return value can be interpreted as a boolean expression.