=============================================================================== W A V E C O M =============================================================================== OPEN AT V1.10 Updated : April 26th, 2002 =============================================================================== (To print this file : use Notepad and remove all margins and default header.) --------------------------------- Content of this file --------------------------------- All sample applications use functions defined in the Wavecom sample library (WmSampleLib.lib). These functions are separated in several source files : * functions related to AT commands and responses, in at_com.c & .h * standard AT strings definitions, in atstrings.c & .h * functions related to I2C and SPI bus management, in bus.c & .h * functions related to some peripheral drivers, in drivers.c & .h * functions related to error management, in error.c & .h * functions related to FCM operations, in fcm.c & .h * functions related to flash objects management, in flash.c & .h * fonts definitions for graphical LCD, in fonts.c & .h * functions related to gpio management, in gpio.c & .h * functions related to timer management, in timer.c & .h * functions related to string or memory management, in utils.c & .h This file describes these functions, and the global functionning of the sample applications. The sample library files are in the "\SampleLib" directory. An empty project is provided in the "\Empty Project" directory, containing the minimum application code to build an application based on the sample library. I. Changes II. Application States and Flags III. AT Common functions (at_com.c & .h files) IV. Useful functions (utils.c & .h files) V. Specific processing modules I - Changes =========== * 01/11/06 - V1.00 Initial revision. * 02/04/26 - V1.10 New Wavecom sample library. II - Application States and Flags ================================= 1- Internal Application State ----------------------------- All the sample applications use the same automaton. The current application State is affected to the "AppliState" global variable. This variable is defined in the "at_com.h" file. Whenever the application sends an AT command, waits for a timer to expire or waits for an unsolicited response, it should set "AppliState" to the right state in order to process the event properly. Some states are already defined for the (standard) initialization phase (see AT Common functions) : APP_ST_INIT -> Initial State after a reset of the product APP_ST_IDLE -> Application Idle State, waiting for some event APP_ST_ERROR -> Error State reached by calling the "at_Error()" function (see AT Common functions) APP_ST_PIN_INT -> PIN code interrogation State (the product has sent an "AT+CPIN?" command) APP_ST_NO_SIM -> No SIM is inserted, wait for the "+WIND: 1" unsolicited response APP_ST_ENTER_PIN -> PIN code must be entered APP_ST_WAIT_WIND4 -> After the PIN code has been entered, wait for the "+WIND: 4" unsolicited response, then switch to Idle State 2- External Application State ----------------------------- Using the command pre-parsing mechanism, the embedded application can know the external application State. This State is affected to the "ExtCmdState" global variable, defined in the "appli.h" file. Whenever the external application sends an AT command to the embedded application, this one should set ExtCmdState to the right State in order to process further responses for this command. Some states are already defined for the initialization phase (see AT Common functions) : EXT_ST_IDLE -> Normal external application State, no AT command has been sent EXT_ST_ERROR -> Error State reached by calling the "at_Error()" function (see AT Common functions) EXT_ST_CPIN -> The external application sent an "AT+CPIN=xxxx" command to enter the PIN code. 3- Application Flags -------------------- The "at_com.h" file provides a Flag mechanism that can be used by the embedded application. The 32 bits "AppFlags" global variable is used, with "RESET_APP_FLAG", "SET_APP_FLAG" and "GET_APP_FLAG" macros, which respectively reset, set or get the requested flag state. The following flags are already defined : APP_FLAG_NEED_WIND4 -> This flag is set if the application needs the "+WIND: 4" indication to reach idle state (see at_Init() function) APP_FLAG_TERM_RSP -> This is set when the received response is a "terminal" one. APP_FLAG_TRANSMIT -> This flag is set when the "AT event" (command, response, ...) must be forwarded to Wavecom software or external application. APP_FLAG_WAIT_CREDIT_DATA APP_FLAG_WAIT_CREDIT_V24 -> These flags are used when the application uses the Flow Control Manager API (see fcm_SndData() function) The 16 less significant bits are available for specific application processing. 4- Trace Levels --------------- The __DEBUG_APP__ option flag is defined in the "options" file. When this option is removed, the macro DBG_TRACE_ is replaced by an empty string when the application is compiled. It can be usefull to decrease the application binary size. The following trace levels are defined in the "traces.h" file : 1 - In/Out Messages, and Application current state 2 - Timer traces 3 - AT events traces 4 - Memory traces 5 - Flash traces 6 - FCM traces 7 - Init phase traces 8 - Flags modification traces 9 - Gpio traces 10 - Bus traces 11 - Driver traces The application can use from 12 to 32 trace levels for specific traces. III - AT Common functions (at_com.c & .h files) =============================================== 1- Operation of the Application ------------------------------- The functions provided by the "at_com.c" file allow the standard application to operate as described here-below : * wm_apmAppliInit --> call "at_Init" for a standard initialization --> initialize global variables for the "appli.c" file * wm_apmAppliParser --> call "at_PreParse()" for a message pre-parsing --> if message was not processed by "at_PreParse()", it should be processed by the "appli.c" provided functions : "parse_ResponseToEmbeddedCmd()" "parse_ResponseToExternalCmd()" "parse_UnsolicitedToEmbedded()" "parse_IntermediateToEmbedded()" "parse_PreCommandToEmbedded()" "parse_Timer()" "parse_FCMEvents()" Excepted the parse_Timer() and parse_FCMEvents() functions, each of these function should return TRUE when the embedded application wants to transmit the command to AT, or the response to the external application. --> call "at_PostParse()" for a message post-parsing a. void at_Init ( wm_apmInitType_e InitType, bool bWind4Needed ) ---------------------------------------------------------------- * if the InitType is WM_APM_REBOOT_FROM_EXCEPTION, do nothing. * initializes the standard application variables * subscribes to all services in "pre-embedded" treatment mode. * if the application needs the "+WIND: 4" to run, set the APP_FLAG_NEED_WIND4 flag b. bool at_PreParse ( wm_apmMsg_t * pMessage ) ---------------------------------------------- * traces the message type and content, and the current application state * for responses, preparsed responses, preparsed commands, unsoliciteds and intermediates responses, remove the CR and LF characters from the response/command string, and copy it to pBuffer global variable * for data received from the Data or the V24 flow, the string is copied to pBuffer without removing any character * for responses or preparsed responses, check if the response string is one of those defined in the cRspTab table. In this case, the global CurrRspType variable takes the corresponding value of app_ExtRspTypes_t type. If the response is "+CME ERROR: XXX" or "+CMS ERROR: XXX", the global CurrErrorNb variable take the error number value. * for unsolicited responses, check if the response string is one of those defined in the cUnsTab table. In this case, the global CurrUnsType variable takes the corresponding value of app_ExtUnsTypes_t type. * for intermediate responses, check if the response string is one of those defined in the cIntTab table. In this case, the global CurrIntType variable takes the corresponding value of app_ExtIntTypes_t type. * for preparsed commands, check if the command string matches one of the application defined command strings. In this case, the command type, the command parameters and the application state are checked to know if this command may be executed. If all checkings are OK, the global variables are updated : - CurrCmdType contains the current command type : ATCMD_ACTION for "AT+CMD" command string ATCMD_READ for "AT+CMD?" command string ATCMD_TEST for "AT+CMD=?" command string ATCMD_PARAM for "AT+CMD=XX,XX..." command string - CurrCmdNbParams contains the current parameter number. - P0, P1, ... contain the parameters strings Then the command function, set in the CommandTab table, is executed. Some commands are filtered in all applications : * "AT+WIND=XXX", to avoid the external application to change the +WIND value ; returns "+CME ERROR: 600" * "AT+CMEE=XXX", to avoid the external application to change the +CMEE value ; returns "+CME ERROR: 600" * "AT+WHO", returns the Application name string and version. * manages all the initialization phase, until the IDLE state, using the following automaton states : ******** * INIT * 0.5s Timer, Send "AT+WIND=4095;+CMEE=1;+CMGR" command, ******** to get the product type. | | Send "AT+CPIN?" command | V *********** * PIN_INT * Wait for PIN status *********** | ********** +-> +CME ERROR: 10 --> * NO SIM * Wait for +WIND: 1, and return to | ********** *PIN_INT* State | | +-> +CME ERROR: 515 --> Wait for 1s, and return to *PIN_INT* State | | | ************* +-> +CPIN: SIM PIN --> * ENTER PIN * Wait for the user enter PIN | ************* code | | | +CPIN: READY | AT+CPIN=XXXX, OK response | | +------------+--------------+ | +-----------+ if +WIND: 4 not | | if +WIND: 4 needed needed | V | *************** | * WAIT WIND 4 * | *************** | | | | +WIND: 4 +-----------+ | | V ******** * IDLE * display "READY" ******** * At any time, a removal of the SIM card will set the Application state to *NO SIM*, waiting for the "+WIND: 1" indication. c. void at_PostParse ( bool bTransmit, wm_apmMsg_t * pMessage ) --------------------------------------------------------------- * if bTransmit is set, sends the command to Wavecom AT interface, or the response to the external application. * releases the pBuffer string. * traces the new application state after the message treatment. 2- AT common functions ---------------------- void at_SndCmd ( ascii * CmdStr ) ********************************* Send an AT command in WM_AT_SEND_RSP_TO_EMBEDDED mode. void at_SndTxt ( ascii * CmdStr ) ********************************* Send a Text, after have sending a "Text" command, as "AT+CMGS". bool at_AppCmdStackUpd() ************************ Updates the command stack ; the further responses to this command will not be parsed. void at_SndRsp ( ascii * RspStr ) ********************************* Trace the response string and send it to the external application. void at_SndStdRsp ( app_RspTypes_t RspType ) ******************************************** Send standard responses (as OK or errors, defined in app_RspTypes_t type) to the external application. void at_SndUnsRsp ( ascii * RspStr ) ************************************ Trace the unsolicited response string and send it to the external application. void at_SndIntRsp ( ascii * RspStr ) ************************************ Trace the intermediate response string and send it to the external application. IV - Useful functions (utils.c & .h files) ========================================== 1- String functions ------------------- char * str_RemoveCrLf ( char *dst, const char *src, u16 size ) ************************************************************** Removes all CR and LF characters of "src" string and copy it to "dst" string. Return a pointer on "dst" string. u16 str_StrSwitchN ( const char *strTest, ... ) *********************************************** Returns the index of the argument similar to the strTest string. Strings to test are passed as paramters. u16 str_TabStrSwitchN ( const char *strTest, ascii ** RspTab ) ************************************************************** Returns the index of the argument similar to the strTest string. Strings to test are passed as a constant string table. char * str_GetParameterString ( char *dst, const char *src, u8 Position ) ************************************************************************* Returns the parameter string of "src" at index "Position", and copy it in "dst" string. Returns NULL if the parameter n°Position does not exist. u8 str_GetParameters ( ascii * string ) *************************************** Gets the command parameters and returns their number. P0, P1, ... variables are pointers on the different parameters. bool str_IsNumString ( ascii * string ) *************************************** Checks if the string contains only digits. bool str_IsHexaChar ( ascii Ch ) ******************************** Checks if the character is an hexadecimal one. bool str_IsValidParam ( ascii * string ) **************************************** Checks if the string is a valid AT command parameter : * only digits * ascii string delimited by "" * digits preceded by '+' character for phone numbers void str_itoHex ( ascii * dst, u8 Nb ) ************************************** Converts a u8 to a hexadecimal string ascii * str_iBuftoHex ( ascii * dst, u8 * src, u16 len ) ******************************************************** Convert a u8* buffer to a hexadecimal string u32 str_HexAToI ( ascii * src ) ******************************* Convert hexadecimal string to u32 u8 * str_HexAToIBuf ( u8 * dst, ascii * src ) ********************************************* Convert hexadecimal string to u8 * buffer void str_GetStrWithoutLF ( ascii * dst, ascii * src , u8 Position ) ******************************************************************* Copies part n°"Position" of "src" into "dst". "Parts" are separated by LF character. u8 str_sprintf ( ascii * buffer, ascii * fmt, ... ) *************************************************** "Light version" of the C sprintf 2- Memory functions ------------------- void * mem_AppGetMemory ( u16 Size ) ************************************ Standard Get Memory, go to Error state if cannot get memory. bool mem_AppReleaseMemory ( void ** Ptr ) ***************************************** Standard Release Memory, set Ptr to NULL after release. Go to Error state if cannot get memory. 3- Integers manipulation Functions ---------------------------------- u32 int_Div ( u32 iToDiv, u32 iDivsr ) ************************************** Integer "/" u32 int_Mod ( u32 iToDiv, u32 iDivsr ) ************************************** Integer "%" u8 int_SetBitCount ( u32 Nb ) ***************************** Count the set bits of the parameter V - Specific processing modules =============================== The other files of the Wavecom sample library provide specific processing functions for each Open-AT API. 1 - Bus and drivers ------------------- The "bus.*" and "drivers.*" files provide functions to handle bus operations (via the BUS API, or the bus related AT commands), and to drive two specifics LCD : * Samsung KS0719 SPI LCD driver, using SPI bus, a specific GPIO to handle RS signal, and the SPI_EN or SPI_AUX chip select signal. * Parallel Text LCD (as Powertip PC 1602-C, for example), plugged on the Philips PCF8574 remote I/O I2C expander. The expander I2C bus use two GPIOs, and the LCD is plugged on the expander as following : Expander LCD IO 0 D4 IO 1 D5 IO 2 D6 IO 3 D7 IO 4 NC IO 5 RS IO 6 R/W IO 7 E The "font.*" files provide fonts, usable with a graphical LCD. 2 - Errors ---------- The "error.*" files provide an error processing system. Errors can be fatal or not ; the fatal ones will cause the reset of the product, and the wm_apmAppliInit() function will be call with the InitType parameter set to the WM_APM_REBOOT_FROM_EXCEPTION value. 3 - FCM ------- The "fcm.*" files provide a flow control basic management. All FCM events are pre-parsed, and then forwarded to the parse_FCMEvents() function of the application. 4 - Flash objects ----------------- The "flash.*" files provide simple functions to handle flash objects. 5 - Gpio -------- The "gpio.*" files provide an interface to handle Gpio Read/Write operations, via the GPIO API, or the gpio related AT commands. 6 - Timers ---------- The "timer.*" files provide an interface to handle timers with dynamic IDs. When the application wants to start a timer, the tmr_Start() function returns the ID of the started timer, that the application should store in a global variable to correctly handle the further WM_OS_TIMER messages.