Arduino Serial finduntil Function and its Application with Example

What is Arduino Serial findUntil Function

• Arduino Serial findUntil Function reads the received buffer and test for specified string or word present or not.
• If specified string is present in the buffer than the function return the true, otherwise return false.
• By default the findUntil function wait for terminating character before it return false.
• The Serial.findUntil() function wait for one second or timeout time, but findUntil function return false immediately as soon as it receive the terminating character.
• You can consider the terminating character as command end symbol, like in c language compiler look for “;” for end of statement.

To test for word with the help of Serial.find() is having an issue. If you have entered the complete command still it will wait for the one second, in case target string is not found in the command.

The concept of terminating character in findUntil solve this problem of delay in the false. As soon as the function receive terminating character it will return true or false, depends upon target string is found in the buffer or not.

If “on$” received the function return true, otherwise return false.

The findUntil function is mostly used with the if logic, to perform some task in case target string received.

How findUntil Function Works

The function continuously read the received data from the buffer until receive terminating character. And if target string found in the serial buffer it return true.

And if the target string is not received until terminating character, it will return false. It means the function will wait for end character.

And one more important fact is that, the function findUntil() also exit after one second with return false even if it does not receive terminating character.

It means it will exit by two events, first after it receive terminating character, second after completing wait time or timeout (by default one second).

Arduino Serial findUntil Example

In this small project code we will on the LED on pin number 13 when we receive the “on$”. And turn off the LED if received anything else.

In this example we are using “$” as terminating command character.

/*
    Control the LED on pin 13 with PC from serial monitor with findUntil function.
	Author: Nilesh Chaurasia
    https://elextutorial.com
*/
void setup() 
{
	Serial.begin(9600); // Set the baud rate to 9600
	setMode(13,OUTPUT);
}
void loop() 
{
	if(Serial.available()) // Check if received
	{
		if(Serial.findUntil("on","$"))// test the received buffer for "on$"
		{
			digitalWrite(13,HIGH);
		}else
		{
			digitalWrite(13,LOW);
		}
	}
}   
				 

Serial Serial.setTimeout() Function

The default wait time of the Serial.findUntil() function is one second, with the help of Serial.setTimeout() you can modify the timeout of serial functions.

In the set timeout function you have to specify the time in milli-seconds ( ms ). The default value is 1000 for timeout.

Using Newline “\n” as Terminating Character in findUntil()

In the previous example we have used “$” as terminating character, but there is a better option for terminating character. You can use “\n” Newline or Line Feed as terminating character.

In the serial monitor tool there is an option to select line ending character, by default it is “No line ending”.

In the serial monitor tool if you select “Newline”, than serial monitor automatically send Newline “\n” every time you send any command or string.

Fig.2 shows how to set serial monitor to send Newline as command end. This is much more practical use of the terminating character in the findUntil function, because you don’t have to type “$” every time you send a command to Arduino. Serial monitor insert “\n” in every command it sends.