uTerminal.h

00001 /** 
00002  *  @file uTerminal.h
00003  *  @brief uTerminal is a simple AT-command style terminal processor,
00004  *  simplifying the work to send and parse COMMAND=value pairs to a
00005  *  microcontroller.
00006  * 
00007  *  You can use COMMAND=value syntax, as well as
00008  *  COMMAND=value1,value2,value3,... to sendo multiple parameters.
00009  *  Commands and values can be any string, as long as they do not contain
00010  *  the following chars: '=', '\n', '\r' or ','.
00011  *
00012  *  @author  Fernando Cosentino
00013  */
00014 
00015 #ifndef _UTERMINAL
00016 #define _UTERMINAL
00017 
00018 #include "mbed.h"
00019 #include "USBSerial.h"
00020 
00021 #define UTERMINAL_BUF_SIZE 512
00022 
00023 /** uTerminal processes messages from a serial port,
00024  * parsing as a "COMMAND=value" pair,
00025  * or "COMMAND=value1,value2,value3,..." set.
00026  */
00027 class uTerminal {
00028 public:
00029 
00030     /** Instances an uTerminal object.
00031      * @param PinTX TX pin for the serial port.
00032      * @param PinRX RX pin for the serial port.
00033      */
00034     uTerminal(PinName PinTX, PinName PinRX);
00035     /** Instances an uTerminal object.
00036      * @param serial_object An instance of a Serial object
00037      */
00038     uTerminal(Serial * serial_object);
00039     /** Instances an uTerminal object.
00040      * @param usbserial_object An instance of a USBSerial object
00041      */
00042     uTerminal(USBSerial * usbserial_object);
00043     
00044     
00045     /** Attaches an external function to be called whenever a new command
00046      * is received. Format for the callback is: void function_name()
00047      * @param callback The callback function to attach to
00048      */
00049     void attach( void (*callback)() );
00050     
00051     /** Process the internal buffer and check for complete messages.
00052      *  Invokes the callback as appropriate.
00053      *  @returns
00054      *    0 if command not yet present
00055      *    1 if a command is present ended by a new line
00056      *    2 if there is content filling the entire buffer
00057      */
00058     int Process();
00059     
00060     /** Sets automatic mode: whenever a message is ready, Process() is
00061      *  automatically called. Use in conjunction with your own interrupt
00062      * service routine, attached as callback via attach().
00063      */
00064     void ModeAuto();
00065 
00066     /** Sets manual mode: whenever a message is ready, you have to call 
00067      *  Process() to prepare the message before acting on it. This way
00068      *  you can decide the best time to poll Process() (useful in
00069      *  time-consuming code).
00070      *  This is the default mode.
00071      */
00072     void ModeManual();
00073 
00074     /** Retrieves the first or next parameter from the received message.
00075      * In the first call, fetches the first parameter. All subsequent calls
00076      * will return the next parameter.
00077      * @returns pointer to first char (that is, a C string)
00078      */
00079     char* GetParam();
00080     
00081     /** When a new message is received, NumParams contains the
00082      * number of parameters available to be read. If it is zero,
00083      * the received message is just a command
00084      */
00085      int NumParams;
00086      
00087     /** String buffer (array of char) containing the received command
00088      *  (in a message like "BAUD=9600,1" the command would be "BAUD")
00089      */
00090     char Command[UTERMINAL_BUF_SIZE+1];
00091     
00092     /** String buffer (array of char) containing the received value
00093      *  (in a message like "BAUD=9600,1" the value would be "9600,1")
00094      */
00095     char Value[UTERMINAL_BUF_SIZE+1];
00096 
00097     /** String buffer (array of char) containing the current parameter taken
00098      * from the value. (In a message like "BAUD=9600,1", after the first call to
00099      * GetParam() Param would be "9600", and after the second call Param 
00100      * would be "1".)
00101      */
00102     char Param[UTERMINAL_BUF_SIZE+1];
00103     
00104     /** Length of useful data in Param.
00105      * Param is actually safe to be used as a null-terminated string,
00106      * but if the length of actual data in it is required this is it.
00107      */
00108     int ParamLen;
00109     
00110     /** Prints a string to serial port.
00111      *  If you want to use printf formatting functionalities, use sprintf
00112      *  to output your formatted data into a string buffer and then call
00113      * this method passing your buffer as parameter.
00114      * @param str String to be sent to serial port
00115      */
00116     void print(char* str);
00117     void print(const char* str);
00118       
00119 private:
00120     Serial * _serial;
00121     USBSerial * _usbserial;
00122     void init();
00123     bool readable();
00124     unsigned char getc();
00125     void (*_callback)();
00126     void _rx_irq();
00127     void transfer_buffers();
00128     
00129     char _buffer[UTERMINAL_BUF_SIZE+1];
00130     int buffer_len;
00131     int params_len;
00132     int cursor;
00133     int param_cursor;
00134     int has_command;
00135     int auto_mode;
00136     int is_usb;
00137 };
00138 
00139 #endif