Main Page | Modules | Data Structures | Directories | File List | Data Fields | Globals | Related Pages

# stxetx.h

Go to the documentation of this file.

    00001 /*! \file stxetx.h \brief STX/ETX Packet Protocol Implementation Library. */
    00002 //*****************************************************************************
    00003 //
    00004 // File Name    : 'stxetx.h'
    00005 // Title        : STX/ETX Packet Protocol Implementation Library
    00006 // Author       : Pascal Stang - Copyright (C) 2002-2003
    00007 // Created      : 10/9/2002
    00008 // Revised      : 02/10/2003
    00009 // Version      : 0.1
    00010 // Target MCU   : any
    00011 // Editor Tabs  : 4
    00012 //
    00013 /// \ingroup general
    00014 /// \defgroup stxetx STX/ETX Packet Protocol Library (stxetx.c)
    00015 /// \code #include "stxetx.h" \endcode
    00016 /// \par Overview
    00017 ///     This library provides functions needed to transmit and receive STX/ETX
    00018 /// packets over any interface which can send and receive bytes.  STX/ETX is a
    00019 /// simple packet protocol for serial data streams and offers packetization,
    00020 /// type tagging, and checksum protection for user data.  Common uses of STX/ETX
    00021 /// might include radio communications were it can improve data reliability over
    00022 /// lossy channels.  STX/ETX may also be used effectively anywhere multiple
    00023 /// access to the communication medium is required.  The packets can be made
    00024 /// to contain destination addresses or routing information as well as data.
    00025 ///
    00026 /// \par STX/ETX Details
    00027 ///     STX/ETX is a simple packet protocol that can be wrapped around user
    00028 /// data for one or more of the following reasons:
    00029 ///         1. packetization is needed
    00030 ///             - Using packets can be helpful if your data naturally forms
    00031 ///             little "bunches" or if different types of data must be sent
    00032 ///             over the same channel (a serial cable, for example).  If your
    00033 ///             data forms "bunches", you can send user data inside STX/ETX
    00034 ///             packets with a predetermined structure, like an array of A/D
    00035 ///             conversion results.  If you need a way to tell the receiver
    00036 ///             what kind of data you're sending, you can use the TYPE field
    00037 ///             in the STX/ETX packet.
    00038 ///         2. error checking is needed
    00039 ///             - STX/ETX packets will add a checksum to your data.  This
    00040 ///             allows the receiver to verify that data was received correctly
    00041 ///             and is error-free.  Packets which are corrupted in transmission
    00042 ///             and fail the the checksum test are automatically discarded.
    00043 ///             Error checking is especially useful when the data transmission
    00044 ///             channel is unreliable or noisy (examples: radio, infrared, long
    00045 ///             cables, etc)
    00046 ///
    00047 ///     STX/ETX packets have the following structure:
    00048 ///
    00049 ///     [STX][status][type][length][user data...][checksum][ETX]
    00050 ///
    00051 ///     All fields are 1 byte except for user data which may be 0-255 bytes.
    00052 ///     Uppercase fields are constant (STX=0x02, ETX=0x03), lowercase fields
    00053 ///     vary.  The length field is the number of bytes in the user data area.
    00054 ///     The checksum is the 8-bit sum of all bytes between but not including
    00055 ///     STX/ETX.
    00056 //
    00057 // This code is distributed under the GNU Public License
    00058 //      which can be found at http://www.gnu.org/licenses/gpl.txt
    00059 //
    00060 //*****************************************************************************
    00061 //@{
    00062
    00063 #ifndef STXETX_H
    00064 #define STXETX_H
    00065
    00066 #include "buffer.h"
    00067
    00068 // include project-dependent configuration options
    00069 #include "stxetxconf.h"
    00070
    00071 // constants
    00072 // packet markers
    00073 #define STX     0x02                // start transmission marker
    00074 #define ETX     0x03                // end transmission marker
    00075 // packet length parameters
    00076 #define STXETX_HEADERLENGTH     4   // number of bytes required for packet header
    00077 #define STXETX_TRAILERLENGTH    2   // number of bytes required for packet trailer
    00078 // packet field offsets
    00079 #define STXETX_STATUSOFFSET     1   // number of bytes from STX to STATUS
    00080 #define STXETX_TYPEOFFSET       2   // number of bytes from STX to TYPE
    00081 #define STXETX_LENGTHOFFSET     3   // number of bytes from STX to LENGTH
    00082 #define STXETX_DATAOFFSET       4   // number of bytes from STX to the data
    00083 #define STXETX_CHECKSUMOFFSET   4   // number of bytes from STX+[length] to CHECKSUM
    00084 #define STXETX_NOETXSTXCHECKSUM 3   // number of bytes used by STX,ETX,CHECKSUM
    00085
    00086
    00087 // function prototypes
    00088
    00089 //! Initialize STX/ETX packet protocol library
    00090 void stxetxInit(void (*dataout_func)(unsigned char data));
    00091
    00092 //! Send/Create STX/ETX packet
    00093 void stxetxSend(unsigned char status, unsigned char type, unsigned char datalength, unsigned char* dataptr);
    00094
    00095 //! Process a buffer containing STX/ETX packets
    00096 unsigned char stxetxProcess(cBuffer* rxBuffer);
    00097
    00098 //! Returns the received packet's status
    00099 unsigned char stxetxGetRxPacketStatus(void);
    00100
    00101 //! Returns the received packet's type
    00102 unsigned char stxetxGetRxPacketType(void);
    00103
    00104 //! Returns the received packet's datalength
    00105 unsigned char stxetxGetRxPacketDatalength(void);
    00106
    00107 //! Returns pointer to the received packet's data
    00108 unsigned char* stxetxGetRxPacketData(void);
    00109
    00110
    00111 #endif
    00112 //@}