Joseph Ellsworth / multi-serial-command-listener

Command listener for serial ports capable of listening to multiple ports simultaneously. It considered \n \r command terminators and will make callback to client code when it detects completed commands. Uses serial interrupts to receive the data.

Dependents:   xj-multi-serial-command-listener-example xej-Nucleo-F401RE-and-HC05-Bluetooth data_log

You are viewing an older revision! See the latest version

Homepage

Table of Contents

  1. Event based serial command listener
  2. Sample Use
  3. Basic Therory of Operation
  4. Multiple Listeners
  5. Known limitations
  6. References
  7. Disclaimer

Event based serial command listener

*

Sample Use

Sample Use Example: https://developer.mbed.org/users/joeata2wh/code/xj-multi-serial-command-listener-example/

sample code

multi serial uart command listener with callback

  #include "mbed.h"
  #include "multi-serial-command-listener.h"

  Serial pc(USBTX, USBRX);
  char myCommand[SCMD_MAX_CMD_LEN+1];

  void commandCallback(char *cmdIn) {
    strcpy(myCommand, cmdIn);
    // all our commands will be recieved async in commandCallback
    // we don't want to do time consuming things since it could
    // block the reader and allow the uart to overflow so we simply 
    // copy it out in the callback and then process it latter. 
  }

  int main() {
    pc.baud(9600);
    pc.printf("Demo multi-serial-command-listener\r\n");
    
    // Instantiate our command processor for the 
    // USB serial line. 
    struct SCMD *cmdProc = scMake(&pc, commandCallback)  ;
    
    while(1) {        
        if (myCommand[0] != 0) {     
          pc.printf("Command Recieved =%s\r\n", myCommand);
          myCommand[0] = 0; // clear until we recieve the next one
        }
        wait(0.05);
    }
  }

Basic Therory of Operation

The operation is the system will append new characters to the buffer until it hits the end. Whenever it sees a \r or \n will insert a \000 (null) so the previous characters can be used safely in strcpy.

It will then set up a null terminator and call the user specified callback.

To minimize risk of invalid data it is recomended the caller copies the last_cmd to local buffer using the sc_last_cmd_copy(char *dest) which disables interupts performs the copy and then re-enables the interupts. Otherwise a new character inbound could cause the command data to change out from under the user.

If the buffer fills up with more than SC_MAX_CMD_LEN characters what is already present will be treated as if it had encountered a \r or \n.

A cmd must contain at least 1 charcter or it will be ignored.

Multiple Listeners

The system will allow upto 10 serial listeners to each be processing new character. It will automatically multi-plex between these listeners. as needed. Each listner can have it's own cmd callback.

Known limitations

  1. If data arrives fast enough we could have sufficient data in uart buffer to contain multiple commands. In that instnace it is possible that commands before the last command could be over-written before calling code can process them.
  1. Can have SCMD_MAX_LISTENERS and no current report if new listener overflow is provied but it can be checked with sc_listener_ndx() which will return the index of the listener in queue or SCMD_LISTENER_NOT_FOUND
  1. it takes some time to multi-plex across the listeners and check each one for a new character. Under very fast connection speeds it is possible that arriving data could overflow the uart buffer before we can copy the data out.
  1. There is no provision to detect the same Serial connection being used by more than one command listener. This is a problem because the first one in the listener queue will get all the data.
  1. No current detach processed for listener in sc_delete_listener which could increase interupt callback overhead. Need to research what happens with multiple attach calls.
  1. Consumes at least SCMD_MAX_CMD_LEN memory one for inbound buffer.

References

https://developer.mbed.org/cookbook/Serial-Interrupts

Disclaimer

NOTE: I am using a struct instead of a class here because I may need to port to PSoC in near future and it is unclear when they will get full C++.

All wikipages