LsrModule.h

00001 /**
00002  * @file LsrModule.h
00003  * @author LS Research LLC
00004  * @version 1.0
00005  *
00006  * @section LICENSE
00007  *
00008  * This program is free software; you can redistribute it and/or
00009  * modify it under the terms of the GNU General Public License as
00010  * published by the Free Software Foundation; either version 2 of
00011  * the License, or (at your option) any later version.
00012  * 
00013  * This program is distributed in the hope that it will be useful, but
00014  * WITHOUT ANY WARRANTY; without even the implied warranty of
00015  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
00016  * General Public License for more details at
00017  * http://www.gnu.org/copyleft/gpl.html
00018  *
00019  * @section DESCRIPTION
00020  *
00021  * UART communication API for LS Research's ProFLEX01 and SiFLEX02 ModFLEX Shields.
00022  */
00023 
00024 /**
00025  * Modified by Mark Harris at SAIT.ca
00026  * Improved functionality for mbed
00027  */
00028 
00029 #ifndef LsrModule_h
00030 #define LsrModule_h
00031 
00032 #include <inttypes.h>
00033 #include "mbed.h"
00034 
00035 #ifndef NULL
00036     #define NULL    0
00037 #endif
00038 
00039 #define SIFLEX02  ///< Use with a SiFLEX02 ModFLEX Shield (900MHz)
00040 //#define PROFLEX01  ///< Use with a ProFLEX01 ModFLEX Shield (2.4GHz)
00041 
00042 /**
00043 * Message Index Defintions.
00044 *
00045 */
00046 #define LSR_MODULE_MSG_START_BYTE_INDEX                                 0
00047 #define LSR_MODULE_MSG_LENGTH_BYTE_INDEX                                1
00048 #define LSR_MODULE_MSG_TYPE_BYTE_INDEX                                  2
00049 
00050 /**
00051 * Message Byte Types.
00052 *
00053 */
00054 #define LSR_MODULE_SERIAL_MSG_START_BYTE                                0x01
00055 #define LSR_MODULE_SERIAL_MSG_END_BYTE                                  0x04
00056 
00057 /**
00058 * Rx Message Type Limits.
00059 *
00060 */
00061 #define LSR_MODULE_MIN_SERIAL_RX_MSG_TYPE                               0x81
00062 #define LSR_MODULE_MAX_SERIAL_RX_MSG_TYPE                               0xC5
00063 
00064 /**
00065 * LSR Module Host TX Message Definitions.
00066 *
00067 */
00068 #define LSR_MODULE_QUERY_VERSION_MSG_TYPE                               0x01
00069 #define LSR_MODULE_SET_SECURITY_TX_FRAME_COUNTER_MSG_TYPE               0x0C
00070 #define LSR_MODULE_QUERY_SECURITY_TX_FRAME_COUNTER_MSG_TYPE             0x0D
00071 #define LSR_MODULE_SET_BASIC_RF_SETTINGS_MSG_TYPE                       0x10
00072 #define LSR_MODULE_QUERY_BASIC_RF_SETTINGS_MSG_TYPE                     0x11
00073 #define LSR_MODULE_SAVE_SETTINGS_TO_NV_MEMORY_MSG_TYPE                  0x12
00074 #define LSR_MODULE_RESET_REQUEST_MSG_TYPE                               0x13
00075 #define LSR_MODULE_QUERY_SUPPLY_VOLTAGE_MSG_TYPE                        0x14
00076 #define LSR_MODULE_QUERY_STATISTICS_MSG_TYPE                            0x15
00077 #define LSR_MODULE_CLEAR_STATISTICS_MSG_TYPE                            0x16
00078 #define LSR_MODULE_SET_HOST_DATA_RATE_MSG_TYPE                          0x18
00079 #define LSR_MODULE_SET_RF_DATA_RATE_MSG_TYPE                            0x19
00080 #define LSR_MODULE_SEND_SIMPLE_SHORT_RF_DATA_PACKET_MSG_TYPE            0x20
00081 #define LSR_MODULE_SEND_ADVANCED_SHORT_RF_DATA_PACKET_MSG_TYPE          0x22
00082 #define LSR_MODULE_SEND_SIMPLE_LONG_RF_DATA_PACKET_MSG_TYPE             0x24
00083 #define LSR_MODULE_SEND_ADVANCED_LONG_RF_DATA_PACKET_MSG_TYPE           0x26
00084 #define LSR_MODULE_SEND_SIMPLE_REPEATED_RF_DATA_PACKET_MSG_TYPE         0x2A
00085 #define LSR_MODULE_CHANNEL_ENERGY_SCAN_MSG_TYPE                         0x44
00086 #define LSR_MODULE_QUERY_HOST_INTERFACE_CONFIGURATION                   0x51
00087 
00088 
00089 /**
00090 * LSR Module Host RX Message Definitions.
00091 *
00092 */
00093 #define LSR_MODULE_RESPONSE_HOST_INTERFACE_CONFIGURATION                0xD1
00094 
00095 
00096 /**
00097 * LSR Module Settings Definitions.
00098 *
00099 */
00100 #define LSR_MODULE_TX_POWER_LEVEL_MIN                                   0
00101 #define LSR_MODULE_SECURITY_OVERHEAD                                    14
00102 #define LSR_MODULE_MIN_SERIAL_RX_MSG_LENGTH                             5
00103 #define LSR_MODULE_MAX_SERIAL_RX_MSG_LENGTH                             131
00104 
00105 #ifdef PROFLEX01
00106     #define LSR_MODULE_RF_CHANNEL_MIN                                   11
00107     #define LSR_MODULE_RF_CHANNEL_MAX                                   25
00108     #define LSR_MODULE_TX_POWER_LEVEL_MAX                               19
00109     #define LSR_MODULE_SIMPLE_SHORT_RF_DATA_LENGTH                      98
00110     #define LSR_MODULE_ADVANCED_SHORT_RF_DATA_LENGTH                    98
00111     #define LSR_MODULE_SIMPLE_LONG_RF_DATA_LENGTH                       98
00112     #define LSR_MODULE_ADVANCED_LONG_RF_DATA_LENGTH                     98
00113     #define LSR_MODULE_MAX_SERIAL_TX_MSG_LENGTH                         115
00114 #elif defined SIFLEX02
00115     #define LSR_MODULE_RF_CHANNEL_MIN                                   1
00116     #define LSR_MODULE_RF_CHANNEL_MAX                                   10
00117     #define LSR_MODULE_TX_POWER_LEVEL_MAX                               21
00118     #define LSR_MODULE_SIMPLE_SHORT_RF_DATA_LENGTH                      112
00119     #define LSR_MODULE_ADVANCED_SHORT_RF_DATA_LENGTH                    110
00120     #define LSR_MODULE_SIMPLE_LONG_RF_DATA_LENGTH                       100
00121     #define LSR_MODULE_ADVANCED_LONG_RF_DATA_LENGTH                     98
00122     #define LSR_MODULE_MAX_SERIAL_TX_MSG_LENGTH                         121
00123 #else
00124     #error "Incorrect module type"
00125 #endif
00126 
00127 /**
00128 * Receiver ConfigurationBitmask Definitions.
00129 *
00130 */
00131 #define LSR_MODULE_RX_CONFIG_ALLOW_BROADCAST_ADDRESS_BITMASK            0x01
00132 #define LSR_MODULE_RX_CONFIG_ALLOW_BROADCAST_PAN_BITMASK                0x02
00133 #define LSR_MODULE_RX_CONFIG_PROMISCUOUS_MODE_BITMASK                   0x04
00134 #define LSR_MODULE_RX_CONFIG_ALLOW_SECURED_PACKETS_MODE_BITMASK         0x08
00135 #define LSR_MODULE_RX_CONFIG_MAX                                        (LSR_MODULE_RX_CONFIG_ALLOW_BROADCAST_ADDRESS_BITMASK + LSR_MODULE_RX_CONFIG_ALLOW_BROADCAST_PAN_BITMASK + LSR_MODULE_RX_CONFIG_PROMISCUOUS_MODE_BITMASK + LSR_MODULE_RX_CONFIG_ALLOW_SECURED_PACKETS_MODE_BITMASK)
00136 
00137 /**
00138 * Transmit Options Bitmask Definitions.
00139 *
00140 */
00141 #define LSR_MODULE_TX_OPTIONS_RETRIES_ACKS_BITMASK                      0x01
00142 #define LSR_MODULE_TX_OPTIONS_USE_SECURITY_BITMASK                      0x02
00143 #define LSR_MODULE_TX_OPTIONS_MAX                                       (LSR_MODULE_TX_OPTIONS_RETRIES_ACKS_BITMASK + LSR_MODULE_TX_OPTIONS_USE_SECURITY_BITMASK)
00144 
00145 /**
00146 * Host UART Data Rate Definitions.
00147 *
00148 */
00149 #define LSR_MODULE_HOST_DATA_RATE_1200                                  0
00150 #define LSR_MODULE_HOST_DATA_RATE_2400                                  1
00151 #define LSR_MODULE_HOST_DATA_RATE_4800                                  2
00152 #define LSR_MODULE_HOST_DATA_RATE_9600                                  3
00153 #define LSR_MODULE_HOST_DATA_RATE_19200                                 4
00154 #define LSR_MODULE_HOST_DATA_RATE_38400                                 5
00155 #define LSR_MODULE_HOST_DATA_RATE_57600                                 6
00156 #define LSR_MODULE_HOST_DATA_RATE_115200                                7
00157 #define LSR_MODULE_HOST_DATA_RATE_230400                                8
00158 #define LSR_MODULE_HOST_DATA_RATE_460800                                9
00159 #define LSR_MODULE_HOST_DATA_RATE_921600                                10
00160 #define LSR_MODULE_HOST_DATA_RATE_MAX                                   LSR_MODULE_HOST_DATA_RATE_921600
00161 #define LSR_MODULE_10MS_UART_TIMEOUT                                    239
00162 
00163 /**
00164 * RF Data Rate Definitions.
00165 *
00166 */
00167 #define LSR_MODULE_RF_DATA_RATE_BPSK_40KBPS             0
00168 #define LSR_MODULE_RF_DATA_RATE_OQPSK_SIN_250KBPS       1
00169 #define LSR_MODULE_RF_DATA_RATE_OQPSK_SIN_1MBPS         2
00170 #define LSR_MODULE_RF_DATA_RATE_MAX                     LSR_MODULE_RF_DATA_RATE_OQPSK_SIN_1MBPS
00171 
00172 /**
00173 * Channel Energy Scan Duration Definitions.
00174 *
00175 */
00176 #define LSR_MODULE_SCAN_DURATION_MAX                                    14
00177 
00178 /**
00179 * Type Defintions.
00180 *
00181 */
00182 typedef unsigned int    word_t;
00183 
00184 /**
00185 * Word structure.
00186 *
00187 */
00188 typedef struct _words
00189 {
00190     uint8_t lb; ///< Low byte.
00191     uint8_t hb; ///< High byte.
00192 } Words_t;
00193 
00194 /**
00195 * Word union.
00196 *
00197 */
00198 typedef union _wordu
00199 {
00200     word_t   w; ///< Word.
00201     uint16_t    u16; ///< Unsigned 16.
00202     Words_t  ws; ///< Word structure.
00203 } Wordu_t;
00204 
00205 /**
00206 * Word structure.
00207 *
00208 */
00209 typedef struct _dwords
00210 {
00211     uint8_t lb; ///< Low byte.
00212     uint8_t mlb; ///< Middle low byte.
00213     uint8_t mhb; ///< Middle high byte.
00214     uint8_t hb; ///<  High byte.
00215 } DWords_t;
00216 
00217 /**
00218 * Double word union.
00219 *
00220 */
00221 typedef union _dwordu
00222 {
00223     uint32_t u32; ///< Unsigned 32.
00224     DWords_t dws; ///< Double word structure.
00225 } DWordu_t;
00226 
00227 
00228 class LsrModule : Serial
00229 {
00230     public:
00231     uint8_t* pu8RxBuffer; ///< Pointer to private UART receive buffer.
00232     uint8_t u8RxMsgLength; ///< Length of private UART receive buffer.
00233     //Functions:
00234     LsrModule(PinName tx, PinName rx, int baudRate = 19200);
00235     ~LsrModule();
00236     bool SubscribeRxMsgCallback(uint8_t u8RxMsgType, void (*callback)(void)); 
00237     bool UnsubscribeRxMsgCallback(uint8_t u8RxMsgType); 
00238     void RunHostRxStateMachine(void);
00239     // Tx Messages:
00240     // 0x01
00241     void QueryVersionMsg(void);
00242     // 0x0C
00243     void SetSecurityTransmitFrameCounterMsg(uint32_t* pu32FrameCounter);
00244     // 0x0D
00245     void QuerySecurityTransmitFrameCounterMsg(void);
00246     // 0x10
00247     void SetBasicRfSettingsMsg(uint16_t u16PanId, uint16_t u16AddrShort, uint8_t* pu8AddrLong, uint8_t u8RfChannel, uint8_t u8TxPowerLevel, uint8_t u8ReceiverConfig, uint8_t* pu8SecurityKey);
00248     // 0x11
00249     void QueryBasicRfSettingsMsg(void);
00250     // 0x12
00251     void SaveSettingsToNVMemoryMsg(void);
00252     // 0x13
00253     void ResetRequestMsg(void);
00254     // 0x14
00255     void QuerySupplyVoltageMsg(void);
00256     // 0x15
00257     void QueryStatisticsMsg(void);
00258     // 0x16
00259     void ClearStatisticsMsg(void);
00260     // 0x18
00261     void SetHostDataRateMsg(uint8_t u8HostDataRate);
00262     // 0x18
00263     void SetRfDataRateMsg(uint8_t u8RfDataRate);
00264     // 0x20
00265     void SendSimpleShortAddrRfDataPacketMsg(uint8_t* pu8Data, uint8_t u8DataLength, uint16_t u16DestAddress, uint8_t u8TxOptions, uint8_t u8PacketId);
00266     // 0x22
00267     void SendAdvancedShortAddrRfDataPacketMsg(uint8_t* pu8Data, uint8_t u8DataLength, uint16_t u16DestPanId, uint16_t u16DestAddress, uint8_t u8TxOptions, uint8_t u8PacketId);
00268     // 0x24
00269     void SendSimpleLongAddrRfDataPacketMsg(uint8_t* pu8Data, uint8_t u8DataLength, uint8_t* pu8DestAddress, uint8_t u8TxOptions, uint8_t u8PacketId);
00270     // 0x26
00271     void SendAdvancedLongAddrRfDataPacketMsg(uint8_t* pu8Data, uint8_t u8DataLength, uint16_t u16DestPanId, uint8_t* pu8DestAddress, uint8_t u8TxOptions, uint8_t u8PacketId);
00272     // 0x44
00273     void ChannelEnergyScanMsg(uint16_t u16ChannelMask, uint8_t u8ScanDuration);
00274     // 0x51
00275     void QueryHostInterfaceConfiguration(void);
00276 
00277     private:
00278     // Variables
00279     uint8_t u8RxReadByte;
00280     uint8_t u8ForLoopCounter;
00281     uint8_t u8UartRxBufferIndex;
00282     uint8_t u8UartTxBufferIndex;
00283     uint8_t u8TxMsgChecksum;///< Transmit message checksum.
00284     uint8_t au8UartRxBuffer[LSR_MODULE_MAX_SERIAL_RX_MSG_LENGTH];///< Receive buffer for UART communication from module.
00285     uint8_t au8UartTxBuffer[LSR_MODULE_MAX_SERIAL_TX_MSG_LENGTH];///< Transmit buffer for UART communication to module.
00286     bool bUartMethodFlag;
00287 
00288     
00289     // Function Pointers
00290     void (LsrModule::*ptrHostState)(void);///< Runs uart UART receive state machine.
00291     void (LsrModule::*ptrHostProcessCallbackState)(uint8_t*);///< Used to process received UART messages.
00292     
00293     
00294     // Functions
00295     void AddSerialMsgHeader(uint8_t u8MsgType, uint8_t u8MsgLength);
00296     void AddSerialByteToMsgBuffer(uint8_t u8Data);
00297     void AddSerialMsgTrailer(void);
00298     void WriteSerialMsg(void);
00299     void HostProcessCallbackMsgStart (uint8_t* pu8MsgBuffer, uint8_t u8Length);
00300     // Rx Message Callbacks
00301     
00302 
00303     // Rx functions
00304     bool ValidMsgLengthAndType(uint8_t u8MsgType, uint8_t u8MsgLength);
00305     bool ValidRxChecksum(uint8_t* pu8MsgBuffer, uint8_t u8MsgLength);
00306     void SerialFlush(void);
00307     bool SerialAvailable(void);
00308     uint8_t SerialRead(void);
00309     
00310     
00311     // Rx State Machine States
00312     void SerialRxCleanupRestart(void);
00313     void HostRxWaitForMsgStartByteState(void);
00314     void HostRxGetMsgLengthState(void);
00315     void HostRxGetMsgTypeState(void);
00316     void HostRxWaitToGetRestOfMsgState(void);
00317     void HostRxValidateMsgState(void);
00318     void HostRxGoodMsgState(void);
00319 };
00320 
00321 #endif