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 #ifndef STXETX_H
00063 #define STXETX_H
00064 
00065 #include "buffer.h"
00066 
00067 // include project-dependent configuration options
00068 #include "stxetxconf.h"
00069 
00070 // constants
00071 // packet markers
00072 #define STX     0x02                // start transmission marker
00073 #define ETX     0x03                // end transmission marker
00074 // packet length parameters
00075 #define STXETX_HEADERLENGTH     4   // number of bytes required for packet header
00076 #define STXETX_TRAILERLENGTH    2   // number of bytes required for packet trailer
00077 // packet field offsets
00078 #define STXETX_STATUSOFFSET     1   // number of bytes from STX to STATUS
00079 #define STXETX_TYPEOFFSET       2   // number of bytes from STX to TYPE
00080 #define STXETX_LENGTHOFFSET     3   // number of bytes from STX to LENGTH
00081 #define STXETX_DATAOFFSET       4   // number of bytes from STX to the data
00082 #define STXETX_CHECKSUMOFFSET   4   // number of bytes from STX+[length] to CHECKSUM
00083 #define STXETX_NOETXSTXCHECKSUM 3   // number of bytes used by STX,ETX,CHECKSUM
00084 
00085 
00086 // function prototypes
00087 
00088 //! Initialize STX/ETX packet protocol library
00089 void stxetxInit(void (*dataout_func)(unsigned char data));
00090 
00091 //! Send/Create STX/ETX packet
00092 void stxetxSend(unsigned char status, unsigned char type, unsigned char datalength, unsigned char* dataptr);
00093 
00094 //! Process a buffer containing STX/ETX packets
00095 unsigned char stxetxProcess(cBuffer* rxBuffer);
00096 
00097 //! Returns the received packet's status
00098 unsigned char stxetxGetRxPacketStatus(void);
00099 
00100 //! Returns the received packet's type
00101 unsigned char stxetxGetRxPacketType(void);
00102 
00103 //! Returns the received packet's datalength
00104 unsigned char stxetxGetRxPacketDatalength(void);
00105 
00106 //! Returns pointer to the received packet's data
00107 unsigned char* stxetxGetRxPacketData(void);
00108 
00109 
00110 #endif

Generated on Tue Sep 20 03:11:43 2005 for Procyon AVRlib by  doxygen 1.4.2