EncoderInterface.h

/*******************************************************************************
* Digital Encoder Library -- By: Andrew Farris                                 *
*                                                                              *
* This library is intended to provide easy access to the AMT203-V absolute     *
* encoder.                                                                     *
*                                                                              *
* This file sets up function prototypes for the actual library.                *
*                                                                              *
* Data flow for the encoder:                                                   *
*     The host issues a command, receives zero or more wait sequence (0xA5),   *
*     then the echo of the command followed by an optional payload.            *
*                                                                              *
*   The sequence for RD_POS goes as follows (from AMT203 datasheet):           *
*       1) issue read command, receive idle character                          *
*       2) issue NOP, receive idle character 0xA5 or 0x10                      *
*       3) repeat step 2 if it is 0xA5                                         *
*       4) issue NOP and receive MSB position (4 bits valid data)              *
*       5) issue NOP and receive LSB position (8 bits valid data)              *
*                                                                              *
* NOTE: Debugging program execution over serial terminal is supported. To turn *
*       on debug messages, add the line #define DEBUG_ENCODER in the program.  *
*       Note that doing so assumes the AVR-Serial library is already loaded    *
*       and initialized.                                                       *
*                                                                              *
*******************************************************************************/

#include <WProgram.h>
#include <SPI.h>


// These are the SPI codes that the Encoder supports
#define NOP_A5          0x00        // Command causes the next data to be read (reply is usually 1 or more WAITs) or an echo of NOP_A5 if there's nothing to do
#define RD_POS          0x10        // Command to Read position.
#define WAIT            0xA5        // This is basically a 'standby' signal from the encoder... it means it's trying to do something
#define SET_ZERO_POINT  0x70        // Sending this command causes us to read from the
#define ZERO_POINT_SET  0x80        // The encoder returns this signal when the zero-point is successfully set (note, it sends WAIT signals until then)
#define NO_CHIP_SELECT  0xFF        // This code is returned by the SPI link if a command is sent, but no chip is selected/responding.


// Constants for declaring encoder state
#define ENCODER_INACTIVE    0
#define ENCODER_ACTIVE      1
#define ENCODER_NEED_FLUSH  2


float map_value( float x, float in_min, float in_max, float out_min, float out_max );
    /*
        This function works as a linear interpolator, and returns a floating
        point value.

        WARNING: This function does no bounds checking! It is possible for x to
                 be larger than in_max, or smaller than in_min.
    */


int Test_encoder_SPI_link( int CSBpin );
    /*
        This function tests if a link with a particular Encoder is active by
        sending a null operation, and looking for a known response.

        WARNING: This function expects the AVR-SPI library to be active already.
        DO NOT USE BEFORE SETTING UP THE SPI LIBRARY.

        The three possible responses are as follows:
            ENCODER_INACTIVE -
                Value: 0
                Meaning: The selected encoder is disconnected, or unresponsive.
            ENCODER_ACTIVE -
                Value: 1
                Meaning: The selected encoder is ready to send/recieve data.
            ENCODER_NEED_FLUSH -
                Value: 2
                Meaning: The selected encoder responded, but has data waiting to
                         be flushed from queue before it can be used.
    */


int Flush_encoder_cache( int CSBpin );
    /*
        This function should be used to flush any stray data from the encoder
        buffer. The function will cease flush attempts after 100 failures to
        recieve the appropriate response, indicating an issue with the encoder.
        TODO: Change attempt number to account for clearing the encoder's entire
              buffer, not just 'sufficiently large' arbitrary value.

        The intended use of this function is to clear leftover position
        data from the encoder after unexpected power loss, disconnection, or
        other operational interuption, which may result in stray data being left
        in the encoder's FIFO.

        Returns and their meanings:
            ENCODER_INACTIVE -
                Value: 0
                Meaning: The selected encoder is disconnected, or unresponsive.
            ENCODER_ACTIVE -
                Value: 1
                Meaning: The selected encoder's FIFO is clear, and
                         is ready to send/recieve data.
            ENCODER_NEED_FLUSH -
                Value: 2
                Meaning: The selected encoder responded, either had too much
                         waiting in queue, or
    */


float Encoder_read_angle( int CSBpin );
    /*
        This function reads the position of the encoder, and returns it as a
        floating point number between 0 and 360.

        Return value will be < 0 if an issue occurred.
    */


void Encoder_setup();
    /*
        This function does some basic setup activities needed to properly use
        the encoder, particularly multiple encoders.
    */