SerialCommand.cpp

/**
 * SerialCommand - A Wiring/Arduino library to tokenize and parse commands
 * received over a serial port.
 * 
 * Copyright (C) 2015 Craig Versek
 * Copyright (C) 2012 Stefan Rado
 * Copyright (C) 2011 Steven Cogswell <steven.cogswell@gmail.com>
 *                    http://husks.wordpress.com
 * 
 * 
 * This library is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with this library.  If not, see <http://www.gnu.org/licenses/>.
 */
#include "SerialCommand.h"

/**
 * Constructor makes sure some things are set.
 */
SerialCommand::SerialCommand(Stream &port,
                             int maxCommands
                            )
  : _port(port),           // reference must be initialized right away
    _commandList(NULL),
    _commandCount(0),
    _term('\n'),           // default terminator for commands, newline character
    _last(NULL)
{
  _maxCommands = maxCommands;
  strcpy(_delim, " "); // strtok_r needs a null-terminated string
  clearBuffer();
  //allocate memory for the command list
  _commandList = (CommandInfo *) calloc(maxCommands, sizeof(CommandInfo));
  //NULL the default handler
  _default_command.function = NULL;
}

/**
 * Adds a "command" and a handler function to the list of available commands.
 * This is used for matching a found token in the buffer, and gives the pointer
 * to the handler function to deal with it.
 */
void SerialCommand::addCommand(const char *name, void (*function)(SerialCommand)) {
  // #if defined(SERIALCOMMAND_DEBUG_L1) || defined(SERIALCOMMAND_DEBUG_L2)
  //   DEBUG_PORT.print(F("SerialCommand::addCommand, count="));
  //   DEBUG_PORT.print(_commandCount);
  //   DEBUG_PORT.print(F(", name="));
  //   DEBUG_PORT.println(name);
  // #endif
  if (_commandCount >= _maxCommands){
      #if defined(SERIALCOMMAND_DEBUG_L1) || defined(SERIALCOMMAND_DEBUG_L2)
      DEBUG_PORT.print("SerialCommand::addCommand, ERROR: maxCommands was exceeded");
      #endif
      return;
    }
  //make a new callback
  struct CommandInfo new_command;
  new_command.name  = name;
  new_command.function = function;
  _commandList[_commandCount] = new_command;
  _commandCount++;
}

/**
 * This sets up a handler to be called in the event that the receveived command string
 * isn't in the list of commands.
 */
void SerialCommand::setDefaultHandler(void (*function)(SerialCommand)) {
  _default_command.function = function;
}

void SerialCommand::lookupCommandByName(char *name) {
  if (name != NULL) {
    bool matched = false;
    for (int i = 0; i < _commandCount; i++) {
      // FIXME too many debugging prints here causes mysterious crash in readSerial 
      // #if defined(SERIALCOMMAND_DEBUG_L1) || defined(SERIALCOMMAND_DEBUG_L2)
      //   DEBUG_PORT.print(F("SerialCommand::lookupCommandByName, comparing ["));
      //   DEBUG_PORT.print(name);
      //   DEBUG_PORT.print(F("] to ["));
      //   DEBUG_PORT.print(_commandList[i].name);
      //   DEBUG_PORT.println(F("]"));
      // #endif

      // Compare the found command against the list of known commands for a match
      if (strcmp(name, _commandList[i].name) == 0) {
        // FIXME too many debugging prints here causes mysterious crash in readSerial 
        // #if defined(SERIALCOMMAND_DEBUG_L1) || defined(SERIALCOMMAND_DEBUG_L2)
        // DEBUG_PORT.print(F("SerialCommand::lookupCommandByName, matched command: "));
        // DEBUG_PORT.println(name);
        // #endif
        _current_command = _commandList[i]; 
        matched = true;
        #if defined(SERIALCOMMAND_DEBUG_L1) || defined(SERIALCOMMAND_DEBUG_L2)
        DEBUG_PORT.print(F("M: "));
        DEBUG_PORT.println(i);
        #endif
        break;
      }
    }
    if (!matched) {
      #if defined(SERIALCOMMAND_DEBUG_L1) || defined(SERIALCOMMAND_DEBUG_L2)
      DEBUG_PORT.println(F("lCBN, FM"));
      // DEBUG_PORT.print(F("lookupCommandByName, failed to match command with name: "));
      // DEBUG_PORT.println(name);
      #endif
      _current_command = _default_command;
      _current_command.name = name;        //store the name
    }
  } else{ //name was null
    _current_command = _default_command;
    _current_command.name = "NULL";        //use the null name
  }
}


void SerialCommand::runCommand() {
    // Execute the stored handler function for the command,
    // passing in the "this" current SerialCommand object
    if (_current_command.function != NULL){
        (*_current_command.function)(*this);
    }
}



/**
 * This checks the Serial stream for characters, and assembles them into a buffer.
 * When the terminator character (default '\n') is seen, it starts parsing the
 * buffer for a prefix command, and calls handlers setup by addCommand() member
 */
int SerialCommand::readSerial() {
  // #if defined(SERIALCOMMAND_DEBUG_L2) //this code will get called frequently in typical loop
  // DEBUG_PORT.println("SerialCommand::readSerial() enter");
  // #endif
  while (_port.available() > 0) {
    char inChar = _port.read();   // Read single available character, there may be more waiting
    // #if defined(SERIALCOMMAND_DEBUG_L2)
    //   DEBUG_PORT.print(inChar);       // Echo back to serial stream
    // #endif
    if (inChar == _term) {        // Check for the terminator (default '\r') meaning end of command
      //_buffer[_bufPos] = '\0';      // Null terminate
      #if defined(SERIALCOMMAND_DEBUG_L1) || defined(SERIALCOMMAND_DEBUG_L2)
        DEBUG_PORT.print(F("SerialCommand::readSerial, _buffer="));
        DEBUG_PORT.println(_buffer);
        DEBUG_PORT.print(F("\t_bufPos="));
        DEBUG_PORT.println(_bufPos);
      #endif
      return _bufPos;
    }
    else if (isprint(inChar)) {       // Only printable characters into the buffer
      if (_bufPos < SERIALCOMMAND_BUFFER) {
        _buffer[_bufPos++] = inChar;  // Put character into buffer
        _buffer[_bufPos] = '\0';      // Null terminate
      } else {
        // #if defined(SERIALCOMMAND_DEBUG_L1) || defined(SERIALCOMMAND_DEBUG_L2)
        //   DEBUG_PORT.println(F("SerialCommand::readSerial, ERROR Line buffer is full - increase SERIALCOMMAND_BUFFER"));
        // #endif
      }
    }
  }
  return 0;  //return zero until terminator encountered
}

void SerialCommand::matchCommand() {
  char *name = strtok_r(_buffer, _delim, &_last);   // Search for command_name at start of buffer
  #if defined(SERIALCOMMAND_DEBUG_L1) || defined(SERIALCOMMAND_DEBUG_L2)
    DEBUG_PORT.println(F("MC"));
    //delay(1000);
  #endif
  lookupCommandByName(name);
}

/**
 * This checks the Serial stream for characters, and assembles them into a buffer.
 * When the terminator character (default '\n') is seen, it starts parsing the
 * buffer for a prefix command, and calls handlers setup by addCommand() member
 */
void SerialCommand::processCommand() {
  matchCommand();
  runCommand();
  clearBuffer();
}

/*
 * Set up the buffer with a command string
 */
void SerialCommand::setBuffer(char *text_line) {
  int  index = 0;
  char inChar = text_line[index];
  clearBuffer();
  while (inChar != '\0'){ //NULL terminated string
    if (inChar == _term) { // Check for the terminator (default '\r') meaning end of command
      return;
    }
    else if (isprint(inChar)) {     // Only printable characters into the buffer
      if (_bufPos < SERIALCOMMAND_BUFFER) {
        _buffer[_bufPos++] = inChar;  // Put character into buffer
        _buffer[_bufPos] = '\0';      // Null terminate
      } else {
        #if defined(SERIALCOMMAND_DEBUG_L1) || defined(SERIALCOMMAND_DEBUG_L2)
        DEBUG_PORT.println(F("SerialCommand::readSerial, ERROR Line buffer is full - increase SERIALCOMMAND_BUFFER"));
        #endif
        return;
      }
    }
    index++;
    inChar = text_line[index];
  }
}

/*
 * Clear the input buffer.
 */
void SerialCommand::clearBuffer() {
  _buffer[0] = '\0';
  _bufPos = 0;
}

/**
 * Retrieve the next token ("word" or "argument") from the command buffer.
 * Returns NULL if no more tokens exist.
 */
char *SerialCommand::next() {
  return strtok_r(NULL, _delim, &_last);
}

/*
 * forward all writes to the encapsulated "port" Stream object
 */
size_t SerialCommand::write(uint8_t val) {
  return _port.write(val);
}