stxetx.c

Go to the documentation of this file.

/*! \file stxetx.c \brief STX/ETX Packet Protocol Implementation Library. */
//*****************************************************************************
//
// File Name    : 'stxetx.c'
// Title        : STX/ETX Packet Protocol Implementation Library
// Author       : Pascal Stang - Copyright (C) 2002
// Created      : 10/9/2002
// Revised      : 6/30/2003
// Version      : 0.1
// Target MCU   : any
// Editor Tabs  : 4
//
// Description  : This library provides a set of functions needed to send and
//      receive STX/ETX packets.  STX/ETX is a simple packet protocol that can
//      be wrapped around user data for one or more of the following reasons:
//
//          1. packetization is needed
//              - Using packets can be helpful if your data naturally forms 
//              little "bunches" or if different types of data must be sent
//              over the same channel (a serial cable, for example).  If your
//              data forms "bunches", you can send user data inside STX/ETX
//              packets with a predetermined structure, like an array of A/D
//              conversion results.  If you need a way to tell the receiver
//              what kind of data you're sending, you can use the TYPE field
//              in the STX/ETX packet.
//          2. error checking is needed
//              - STX/ETX packets will add a checksum to your data.  This
//              allows the receiver to verify that data was received correctly
//              and is error-free.  Packets which are corrupted in transmission
//              and fail the the checksum test are automatically discarded.
//              Error checking is especially useful when the data transmission
//              channel is unreliable or noisy (examples: radio, infrared, long
//              cables, etc)
//  
//      STX/ETX packets have the following structure:
//
//      [STX][status][type][length][user data...][checksum][ETX]
//
//      All fields are 1 byte except for user data which may be 0-255 bytes.
//      Uppercase fields are constant (STX=0x02, ETX=0x03), lowercase fields
//      vary.  The length field is the number of bytes in the user data area.
//      The checksum is the 8-bit sum of all bytes between but not including
//      STX/ETX.
//
// This code is distributed under the GNU Public License
//      which can be found at http://www.gnu.org/licenses/gpl.txt
//
//*****************************************************************************

#include "global.h"
#include "stxetx.h"
//#include "rprintf.h"

// function pointer to data output routine
static void (*stxetxDataOut)(unsigned char data);

// received packet data buffer
unsigned char stxetxRxPacket[STXETX_MAXRXPACKETSIZE];

// functions


// Initialize STX/ETX packet protocol library
void stxetxInit(void (*dataout_func)(unsigned char data))
{
    stxetxDataOut = dataout_func;
}

// Send/Create STX/ETX packet
void stxetxSend(unsigned char status, unsigned char type, unsigned char datalength, unsigned char* dataptr)
{
    unsigned char checksum = 0;
    unsigned short i;
    
    // write packet header
    stxetxDataOut(STX);
    stxetxDataOut(status);
    stxetxDataOut(type);
    stxetxDataOut(datalength);
    // update checksum
    checksum += status + type + datalength;
    // copy data into packet
    for(i = 0; i < datalength; i++)
    {
        stxetxDataOut(*dataptr);
        checksum += *dataptr;
        dataptr++;
    }
    // write packet trailer
    stxetxDataOut(checksum);
    stxetxDataOut(ETX);
}

// process buffer containing STX/ETX packets
unsigned char stxetxProcess(cBuffer* rxBuffer)
{
    unsigned char foundpacket = FALSE;
    unsigned short i;
    unsigned char length, checksum;
    //unsigned char type;

    // process the buffer
    // go through buffer looking for packets
    // the STX must be located at least STXETX_HEADERLENGTH+STXETX_TRAILERLENGTH from end
    // otherwise we must not have a complete packet
    while( rxBuffer->datalength >= ((u16)STXETX_HEADERLENGTH+(u16)STXETX_TRAILERLENGTH) )
    {
        // look for a potential start of packet
        if(bufferGetAtIndex(rxBuffer, 0) == STX)
        {
            // if this is a start, then get the length
            length = bufferGetAtIndex(rxBuffer, STXETX_LENGTHOFFSET);

            // now we must have at least STXETX_HEADERLENGTH+length+STXETX_TRAILERLENGTH in buffer to continue
            if(rxBuffer->datalength >= ((u16)STXETX_HEADERLENGTH+length+(u16)STXETX_TRAILERLENGTH))
            {
                // check to see if ETX is in the right position
                if(bufferGetAtIndex(rxBuffer, STXETX_HEADERLENGTH+length+STXETX_TRAILERLENGTH-1) == ETX)
                {
                    // found potential packet
                    // test checksum
                    checksum = 0;
                    // sum data between STX and ETX, not including checksum itself
                    // (u16) casting needed to avoid unsigned/signed mismatch
                    for(i = 0; i<((u16)STXETX_HEADERLENGTH+length+(u16)STXETX_TRAILERLENGTH-(u16)STXETX_NOETXSTXCHECKSUM); i++)
                    {
                        checksum += bufferGetAtIndex(rxBuffer, i+STXETX_STATUSOFFSET);
                    }
                    // compare checksums
                    if(checksum == bufferGetAtIndex(rxBuffer, STXETX_CHECKSUMOFFSET+length))
                    {
                        //we have a packet!
                        foundpacket = TRUE;
                    
                        // copy data to buffer
                        // (don't copy STX, ETX, or CHECKSUM)
                        for(i = 0; i < ((u16)STXETX_HEADERLENGTH+length-1); i++)
                        {
                            stxetxRxPacket[i] = bufferGetAtIndex(rxBuffer, i+1);
                        }

                        // debug
                        //rprintf("STXETX Received packet type: 0x%x\n", bufferGetAtIndex(rxBuffer, STXETX_TYPEOFFSET));

                        // dump this packet from the
                        bufferDumpFromFront(rxBuffer, STXETX_HEADERLENGTH+length+STXETX_TRAILERLENGTH);

                        // done with this processing session
                        break;
                    }
                    else
                    {
                        // checksum bad
                        //rprintf("STXETX Received packet with bad checksum\r\n");
                        // for now, we dump these
                        // dump this STX
                        bufferGetFromFront(rxBuffer);
                    }
                }
                else
                {
                    // no ETX or ETX in wrong position
                    // dump this STX
                    bufferGetFromFront(rxBuffer);
                }
            }
            else
            {
                // not enough data in buffer to decode pending packet
                // wait until next time
                break;
            }
        }
        else
        {
            // this is not a start, dump it
            bufferGetFromFront(rxBuffer);
        }
    }

    // check if receive buffer is full with no packets decoding
    // (ie. deadlocked on garbage data or packet that exceeds buffer size)
    if(!bufferIsNotFull(rxBuffer))
    {
        // dump receive buffer contents to relieve deadlock
        bufferFlush(rxBuffer);
    }
    
    return foundpacket;
}

unsigned char stxetxGetRxPacketStatus(void)
{
    // return the packet's status
    // (subtract 1 from the offset because the STX has already been discarded)
    return stxetxRxPacket[STXETX_STATUSOFFSET-1];
}

unsigned char stxetxGetRxPacketType(void)
{
    // return the packet's type
    // (subtract 1 from the offset because the STX has already been discarded)
    return stxetxRxPacket[STXETX_TYPEOFFSET-1];
}

unsigned char stxetxGetRxPacketDatalength(void)
{
    // return the packet's datalength
    // (subtract 1 from the offset because the STX has already been discarded)
    return stxetxRxPacket[STXETX_LENGTHOFFSET-1];
}

unsigned char* stxetxGetRxPacketData(void)
{
    // return a pointer to the packet's data payload
    // (subtract 1 from the offset because the STX has already been discarded)
    return stxetxRxPacket+STXETX_DATAOFFSET-1;
}

---