Sending simple serial commands to an Arduino

Don't send words when characters will do

sending simple serial commands arduino

Sending simple serial commands to an Arduino is the easiest way to communicate between an Arduino and a computer. The computer could be a PC, a Raspberry Pi, or any device that communicates with serial.

By sending and “decoding” a single character it is easy to add a simple debug menu or even serial menu. Plus, it is easy to extend.

Single Character vs. Full Words

The mistake I see many people make is that they try to send full-text strings as serial commands. For example, to turn on a LED, I have seen (silly) commands like “RED LED ON” or “RED LED OFF.” While you could use something like strcmp(), as I showed on the Multiple MQTT Topics example, that tends to be overkill for most serial commands.

Humans like words, computers like binary. Just send one character over serial.

switch (variable) {
  case ‘a’:
	// A Stuff

  case ‘b’:
  case ‘c’:
	// B and C Stuff
  break;
}

Serial is asynchronous

It is easy to get caught in the trap of thinking that typing a full word in the Serial Monitor and then clicking Send, means the entire word is sent immediately. However, it is not. Only one character gets sent at a time. Depending on the line ending settings, a few extra characters might be sent automatically.

Asynchronous sending means that to capture multiple character commands requires you to buffer incoming characters. While not difficult, it does tend to start getting complicated.

Using switch statement

In C, the switch statement executes code based on the value of a variable. The structure is much cleaner than endless if-else statements and even allows a limited amount of “stacking.”

switch (variable) {
  case ‘K’:
	// Do something
  break;

  case ‘m’:
  case ‘M’:
	// Do something with either character
  break;

  default:
	// When all else fails
  break;
}

The conditions for the switch-statement are wrapped in curly braces. Each “case” is like saying “if (variable==case).” Inside of the switch block, any code matching the switch case executes and continues to run until the end of the block or a “break” statement.

Stacking Cases

It is also possible to “stack” case. In the example above both, the characters ‘m’ and ‘M’ will execute the same code. You could also repeat cases if you want multiple actions to happen based on a character.

You must include a “break” at the end of the “case.” The code will not check any more conditions until the next time it sees a “break!”

switch (variable) {
  case ‘a’:
	// A Stuff

  case ‘b’:
  case ‘c’:
	// B and C Stuff
  break;
}

In this example, if “variable” contains the character ‘a,’ then the code for “A Stuff” will execute, but so will “B and C Stuff!”

Sending Simple Serial Commands to Arduino

Using a switch-block, sending simple commands is easy. In my code, I always create a function called “handleSerial()” and then in the loop() I call handleSerial() on each iteration.

This bit is a style choice, but I like to put my handleSerial() at the bottom of my code. It makes adding new commands easy since I can just scroll to the bottom of the screen.

void loop() {
   handleSerial();
   // Everything else loop() does…
}

void handleSerial() {
 while (Serial.available() > 0) {
   char incomingCharacter = serial.read();
   switch (incomingCharacter) {
     case ‘+’:
      pwmValue = pwmValue + 5;
      If (pwmValue >= pwmMax)
         pwmValue = pwmMax;
      break;

     case ‘-’:
      pwmValue = pwmValue - 5;
      If (pwmValue <= 0)
         pwmValue = 0;
      break;
    }
 }
}

First, handleSerial() checks for any received characters. If there is nothing in the receive buffer, then the while-loop exits immediately. Why a while-loop()? Style choice, explained later.

Next, we capture a character from the buffer. You do not need to put the character into a variable; you could put the serial.Read() inside of the switch() statement. However, if you want to do any debugging with the received character, it is easier to have a variable setup ahead of time.

Now the switch-block will execute any code that matches the received character. If none of the code matches, then the character is dropped and the while-loop continues. One critical advantage here is that if you have “line endings” turned on in the serial monitor, this code ignores them!

Why a while()-loop?

For me, it is a style choice. I’d rather handle all of the serial characters at once. However, in a program where I have “time sensitive code”, I’ll only process 1 character each time handleSerial() is called. Just change the while-loop into an if-statement.

Couple of notes

Make sure you call handleSerial() often to check for commands. For example if you have a very long loop, call handleSerial() every so often inside that loop.

One simple trick

One simple serial command trick you won’t believe

Here is a neat little trick when modifying values. In this Larson Scanner Tutorial, I am modifying a variable called pwmValue. So I tend to send multiple characters in a row.

In the serial monitor, I will often put multiple characters in before hitting send.

Arduino Serial Monitor Multiple Command Trick

While they will not all send immediately, it just saves me some time.

Conclusion

Limiting serial commands to a single character could mean limiting your commands. However, the tradeoff is the code to handle these commands is very simple. Check out my tutorial on Measuring PWM Current with a modified moving average. I used handleSerial() in that one.

Your questions, comments, and even corrections are encouraged and very much appreciated! However. I have zero-tolerance for inappropriate or harassing comments. I try to reply to everyone... -James

Leave a comment

7 thoughts on “Sending simple serial commands to an Arduino

    • SerialEvent is called with each iteration of loop(). In fact if you look at the C-Code that the IDE compiles, it looks something like this:

      while(1) {
       serialEvent();
       loop();
      }
      

      (Not the exact code, it is actually a for-loop.)

      Checking the serial buffer at least once from loop(), or from a function called on each iteration of loop(), like in my example is no different from using SerialEvent. In my code, handleSerial() is called each iteration of loop, just like serialEvent().

      That being the case, there is almost no reason to ever use “SerialEvent”.

  1. Nice post and I like the idea of using switch case for serial handling—think I’ll give it a shot.

    There are a few small capitalization typos in the handleSerial codeblock: line 7 Serial.read replaces serial.read; lines 11 and 17 the ifs have to be lowercased or it won’t compile.

  2. spot on. a variant would be when you don’t control both ends and you need to look for a string (e.g “RED LED ON”) in the incoming stream. in this case you may want to have a FIFO stack of the appropriate length into which goes the serial data and on every received character, you check the string starting at the top of the stack against the list of commands/strings you want to capture. the length of the stack should be at least as much as your longest command + 1 (in case there’s a null terminator).

  3. I think I would prefer an line input programme that buffers each character until a CR/LF is detected…One can use the programme then to read single character and longer lines. I like using a longer word to describe an action like
    LR11 for red led 1 on (LR10 for off) This makes the documentation later much easier. Perhaps send a special sequence to start single char processing (X) to stop/start the buffering so one has the best of both worlds.

    I want to use the Arduino with a Raspberry Pi to access sensor data from the Arduino. Perhaps the serial communication would be the best method.

    • I only use CR/LF (or any delimiter) detection when single characters won’t work. (e.g. sending the value of a LED.) Then my preference is to use fixed lengths with a delimiter. If you get the delimiter before the “buffer” is filled, you know a character was dropped.