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

Event based serial command listener

By Joseph Ellsworth CTO of A2WH Take a look at A2WH.com Producing Water from Air using Solar Energy March-2016 License: https://developer.mbed.org/handbook/MIT-Licence Please contact us http://a2wh.com for help with custom design projects.

Sample Use

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

sample code

  #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 Theory 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 recommended the caller copies the last_cmd to local buffer using the sc_last_cmd_copy(char *dest) which disables interrupts performs the copy and then re-enables the interrupts. 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 command must contain at least 1 character or it will be ignored.

Multiple Listeners

The system will allow up-to 10 serial listeners to each be processing new character. It will automatically multiplex between these listeners. as needed. Each listener can have it's own command callback.

Known limitations

1. If data arrives fast enough we could have sufficient data in UART buffer to contain multiple commands. In that instance 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 provided 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 multiplex 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 interrupt 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++.

update comments for minor API change