Using Serial.read() with Arduino

Most people stumble across the Arduino Serial.read() function pretty early on in the Arduino learning curve.

Which makes sense!

Serial communication is a great way to see what’s going on after you compile and upload a new sketch, and it gets some early runs on the board. The problem is, a lot of coders then go off to learn all about the exciting stuff that goes beep and boop without getting a firm grasp of how serial communication really works and why it’s important.

Let’s fix that!

In this lesson, you’ll learn exactly how to use Serial.read() to receive data from the serial port and stitch it together as one value. We’ll cover this in two parts.

Part 1:

• The big picture of serial communication
• The serial buffer
• Serial.read and Serial.available
• Developing a protocol and strategy for reading in data from the serial port

Part 2:

• Implementing the strategy in Arduino code
• BONUS: How to convert the serial data from a string to an integer

The big picture of serial communication

Let’s take a step back from Serial.read(), and talk about serial communication.

What is serial data?

Serial communication is the process of sending one bit of data at a time, sequentially, from one place to another. For example, using serial data, you could send data from your Raspberry Pi to a connected Arduino, or vice versa.

How is serial data transferred?

USB is one of the most common ways to transmit serial communication — hence the name Universal Serial Bus. Using Arduino, we can easily send and receive data over a USB cable with the built-in Arduino Serial Library.

What is the Arduino Serial Library?

First, I’ll give you a quick rundown on libraries.

An Arduino library is basically a bunch of code that has been bundled together to make your life easier. So, imagine you’re a barber, and you want to cut hair as efficiently as possible. A good way to do that would be to set up a drawer in your barber shop to hold all your hair-cutting tools in one place.

Every time a customer walks into your fine establishment for a haircut, all you need to do is open your drawer, and everything you need is right there in easy reach. And, of course, you may have a whole bunch of similar drawers. One might be for dying hair. Another might be for polishing the heads of bald folks to a high glossy shine.

It’s the same thing with Arduino libraries. Arduino libraries bring together a bunch of software functions that help you with specific tasks. The Arduino Serial library is just one of the many libraries you can use.

Serial Library Functions

So what tools live inside this library? The Serial library has functions like:

• Serial.begin()
• Serial.read()
• Serial.available()
• Serial.parseInt()
• Serial.parseString()
• Serial.parseFloat()
• Serial.print()
• Serial.captCrunch()

Don’t worry about what each of these functions does for now. Just bear in mind that the Serial.read() function is part of a larger Arduino Serial Library.

The Serial Buffer

OK, we know that serial communication over USB is how one device can talk to another. We also know that the Arduino Serial Library is a set of serial communication tools. But when data arrives at your Arduino, where does it go? The answer is the serial buffer — or more precisely, the serial receive buffer.

When bits of data start streaming in from your computer, a piece of hardware on your Arduino called a universal asynchronous receiver/transmitter (which can be shortened, thankfully, to UART) will assemble each of the 8 bits into a byte. The UART will then store those bytes (up to 64 bytes, in fact) in the serial receive buffer.

So, mystery solved. The data you send to your Arduino ends up in the serial receive buffer.

But then a new question bubbles up to the surface. Once the data is in the serial receive buffer, how do you access it?

This is where Serial.read() comes in.

Serial.read()

Serial.read()’s job, not all that surprisingly, is to read from the serial receive buffer. However, it’s important to understand that it reads in a very specific way. It’ll read out the first available byte from the serial receive buffer and then remove that byte from the buffer.

Let’s say you sent the phrase “Sub Sandwich” to your Arduino; this means you put 12 bytes into your serial receive buffer. Then let’s assume you typed the following code into a sketch.

char myFirstCharacter = Serial.read();

Serial.read() would scurry off to look at your phrase. It’d return the first available character in the serial receive buffer: A letter “S.” It’d leave “ub Sandwich” in the Serial receive buffer. Now the value “S” will be stored in the variable myFirstCharacter, and there will only be 11 bytes left in the serial buffer….

But what if we performed the same function again, this time entering the following code into a sketch:

char mySecondCharacter = Serial.read();

Now mySecondCharacter will be holding the value “u”, and “b Sandwich” is going to be left in the serial receive buffer.  You get the idea. Serial.read() takes one byte at a time from the serial receive buffer.

But before we move on, there’s a slight complication to consider

Now there is a little gotcha here that you need to look out for. When you’re sending data over serial, an invisible terminating character will often be added to the end of the transmission.

This could be a CR (Carriage Return) or a LF (Line Feed).  Both add an additional byte to the serial receive buffer. In fact, adding to the complexitudinosity (totally made up word), both a CR and an LF might be added, increasing your buffer size by two bytes. But don’t despair. There’s a workaround if you need it. Down at the bottom right of the Serial Monitor window, you’ll see options to either add these terminating characters every time you press the send button or omit them by selecting the No Line Ending option.

Whew, what a rollercoaster of discoveries this has been. Let’s move on shall we?

Serial.available() – the Serial Spy

Now’s a good time to introduce you to the nosy aunt of the serial communication world: Serial.available(). You can use this function to sniff out the serial receive buffer to see if there is anything in there available to read. The function will return the remaining bytes as a number value.

For example, imagine our whole phrase, “Sub Sandwich” is still sitting there in the serial receive buffer. Serial.available() would return the number 12 — that’s 1 for each remaining character in the buffer. If all you had in the serial receive buffer was “andwich” (I guess that’s like a bit more than half a sandwich?) then serial.available() would return the value 7.

Why is that useful?

Serial.available() is a quick and easy way to know if you have data in the serial receive buffer. The logic would look like this:

IF the return value of Serial.available() is greater than 0, THEN part of our message is still sitting in the serial receive buffer.

Does that mean you’re stuck dealing with one character at a time?

Thankfully, no. All this Serial.read() and Serial.available() stuff is great, but they’re not exactly convenient if you want to send the entire phrase “sub sandwich” to your Arduino and save it to a string. Nor are these functions ideal if you want to send a value like 462 to your Arduino and save that to an integer.

For these tasks, you’re far better off corraling all those bytes together into one string variable, or an integer, or whatever datatype floats your boat.

We’ll look at that next.

How to send integers, strings, or whatever over serial

OK, let’s roll up our sleeves and come up with a strategy…

Things are about to get a little technical here but don’t worry. You’ll have a blast!

And remember, if you are new to Arduino programming and want to learn how to do stuff just like this, then make sure to check out the Programming Electronics Academy membership. In our membership area we have video courses that walk you step-by-step through how to program Arduino. It’s a great resource to help you learn to prototype your own projects.

OK, back to our strategy…

First, we need to decide how we are going to send our data (which I will be calling “messages”) – that is, we need to decide on a protocol to follow.

Our Serial.read() protocol

Let’s make these the protocol rules that we’ll enforce in our Arduino program.

• New messages will be read as soon as they arrive
• Messages will be no longer than 12 bytes
• Every message will end with a newline character ‘\n’ – which we will call our terminating character

This is a pretty basic protocol, but it will help us with our strategy.

First, we need a place to store the incoming bytes from the serial receive buffer. We can use a char array for that. Then we need to check if anything is even available in the serial receive buffer. We can use Serial.available to make that happen. Then we need to actually read in a byte. We have Serial.read() in our back pocket for that task.

Before we put the byte into our char array, we’ll need to check the incoming byte to make sure it is not a terminating character.

So here’s what that looks like when we lay it out as a list:

1. Create a character array to store incoming bytes
2. Check to see if there is anything in the serial receive buffer to be read – Serial.available()
3. While there is something to be read then…
   • Read in the byte to a temporary variable – Serial.read()
   • Check to see if what we read is part of our message OR a terminating character
   • If it is part of our message, then save it to a character array
   • If it is a terminating character, then output the message and prepare for the next message
   • If the message has exceeded the max message length in the protocol, then stop reading in more bytes and output the message (or do something else with it).

Bare Minimum Arduino Sketch

Let’s get a bare minimum Arduino program started with setup() and loop(). We’ll add Serial.begin() to the loop to establish Serial Communication.

Notice in Serial.begin() we pass in the value 9600.  This is called the baud rate – it sets the speed of the serial communication, and represents bits per second. Both devices must have the same baud rate selected for Serial Communication to work.  If you’re using the Arduino IDE Serial Monitor window to send data, the baud rate can be set using a drop down menu.

void setup() {
  Serial.begin(9600);
}

void loop() {

}

Now let’s tackle the first step of our algorithm – we create a character array to hold the incoming message and a position variable to help us move through each element in the array. We’ll also create a constant to hold the max length of our message and use this to initialize the character array.

const unsigned int MAX_MESSAGE_LENGTH = 12;

void setup() {
 Serial.begin(9600);
}

void loop() {
 //Create a place to hold the incoming message
 static char message[MAX_MESSAGE_LENGTH];
 static unsigned int message_pos = 0;
}

Now we need to check if any bytes are available in the serial receive buffer. While there are, we need to read in the bytes and save them to a temporary variable. We can combine a while loop, Serial.available, and Serial.read() to make this happen.

const unsigned int MAX_MESSAGE_LENGTH = 12;

void setup() {
 Serial.begin(9600);
}

void loop() {

 //Check to see if anything is available in the serial receive buffer
 while (Serial.available() > 0)
 {
   //Create a place to hold the incoming message
   static char message[MAX_MESSAGE_LENGTH];
   static unsigned int message_pos = 0;

   //Read the next available byte in the serial receive buffer
   char inByte = Serial.read();
 }
}

Now we need to check to see if the byte we read is a terminating character or not… We can use an if-else statement for that. If it’s not a terminating character we’ll do one thing, and if it is a terminating character we’ll do something else.

//Message coming in (check not terminating character)
if ( inByte != '\n')
{
//Do Something
}
//Full message received...
else
{
//Do Something else
}

If it is part of our message, then save it to a character array. We’ll also need to increment our position in the char array for the next byte.

//Message coming in (check not terminating character)
if ( inByte != '\n')
{
 //Add the incoming byte to our message
 message[message_pos] = inByte;
 message_pos++;
}
//Full message received...
else
{
 //Do Something
}

Let’s take a closer look at what we are doing with the terminating character. If we do get the terminating character, that means we have received our entire message. We’re using the character to identify when we can actually do something with the message or data we received. In this example, we’ll print the message to the Serial Monitor window. We’ll also need to reset our character array to prepare for the next message.

//Full message received...
else
{
 //Add null character to string
 message[message_pos] = '\0';

 //Print the message (or do other things)
 Serial.println(message);

 //Reset for the next message
 message_pos = 0;
}

Before we can call this complete, we need to enforce the max message length in the protocol. This will prevent us from exceeding the space that we allotted in our character array. We can add this guard to our existing if statement.

if ( inByte != '\n' && (message_pos < MAX_MESSAGE_LENGTH - 1) )

Full Serial.read() Code

Here is the complete code to use Serial.read() to read in the entire message:

//Many thanks to Nick Gammon for the basis of this code
//http://www.gammon.com.au/serial

const unsigned int MAX_MESSAGE_LENGTH = 12;

void setup() {
 Serial.begin(9600);
}

void loop() {

 //Check to see if anything is available in the serial receive buffer
 while (Serial.available() > 0)
 {
   //Create a place to hold the incoming message
   static char message[MAX_MESSAGE_LENGTH];
   static unsigned int message_pos = 0;

   //Read the next available byte in the serial receive buffer
   char inByte = Serial.read();

   //Message coming in (check not terminating character) and guard for over message size
   if ( inByte != '\n' && (message_pos < MAX_MESSAGE_LENGTH - 1) )
   {
     //Add the incoming byte to our message
     message[message_pos] = inByte;
     message_pos++;
   }
   //Full message received...
   else
   {
     //Add null character to string
     message[message_pos] = '\0';

     //Print the message (or do other things)
     Serial.println(message);

     //Reset for the next message
     message_pos = 0;
   }
 }
}

OK, are you feeling a bit overwhelmed? When you’re starting out, this can feel like a ton of information to absorb, I know! Take your time, go back and read it a few times, and above all, be patient with yourself. If you return to this page after a bit more experimentation, there’s a great chance a lot of this stuff will just click into place.

Now before we call it quits with Serial.read(), I want to show you how to return this c string into an integer.

How to Convert a char to an Int with Arduino

What if instead of sending words or letters with the serial port, perhaps you are sending numerical values, like 42, or 314. How can you convert these digits into integers?

Well, there’s a super cool function called atoi(). This will take a null-terminated string and convert it to an integer.

Strings in the c programming language are null-terminated, meaning they end with the character ‘\0’.  The atoi() function will not work unless the string you pass in has the null-terminating character!

In our current code all we would have to do is add something like this:

else
{
 //Add null character to string
 message[message_pos] = '\0';

 //Print the message (or do other things)
 Serial.println(message);

 //Or convert to integer and print
 int number = atoi(message);
 Serial.println(number);

 //Reset for the next message
 message_pos = 0;
}

That’s it, now the serial message has been converted from a c string into an integer!

Review of Serial.read() Lesson

Let’s do a quick review.

First, we talked generally about Serial Communication – it’s a means of sending data ______________ .  We talked about the Serial Receive Buffer – do you remember how many bytes it can hold?

We discussed the basics of Serial.read() and Serial.available().

Serial.read() removes a byte from the ________________.  The function _________________ returns how many bytes are in the serial receive buffer.

We developed a simple _____________ and strategy for getting messages from our serial port.

Then we implemented the strategy in Arduino code. Finally, we talked about using the function atoi() to convert from a c string to an integer.

You made it!

If you liked this page, you’re going to love the next lesson. Next in this series, you’ll learn how to cut code down to just a couple of lines using some other built-in Serial library functions.