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 //@}