Library function directory
if (Serial)
available()
availableForWrite()
begin()
end()
find()
findUntil()
flush()
parseFloat()
parseInt()
peek()
print()
println()
read()
readBytes()
readBytesUntil()
readString()
readStringUntil()
setTimeout()
write()
serialEvent()
Detailed explanation of library functions
if (Serial)
Description
Indicates if the specified Serial port is ready. Indicates the serial port Are you ready
On 32u4 based boards (Leonardo, Yùn, ecc), if (Serial) indicates wether or not the USB CDC serial connection is open. For all other instances, including if ( Serial1) on the Leonardo, this will always returns true.
This was introduced in Arduino 1.0.1.
Syntax
All boards:< /em>
if (Serial)
Arduino Leonardo specific:
if (Serial1)
Arduino Mega spec ific:
if (Serial1)
if (Serial2)
if (Serial3)
Parameters
none
Returns
boolean: returns true if the specified serial port is available. This will only return false if querying the Leonardo’s USB CDC serial connection before it is ready.
Serial.available()
Description Get the number of bytes read back from the serial port
Get the number of bytes (characters) available for reading from the serial port. This is data that’s already arrived and stored in the serial receive buffer (which holds 64 bytes). available() inherits from the Stream utility class.
Syntax
Serial.available()
Arduino Mega only:
Serial1.available()
Serial2.available( )
Serial3.available()
Parameters
none
Returns
the number of bytes available to read
Example
int incomingByte = 0; // for incoming serial data
void setup< /stron g>()
{
Serial.begin(9600); // opens serial port, sets data rate to 9600 bps
}
void loop ()
{
// send data only when you receive data:
if (Serial.available()> 0)
{
// read the incoming byte:
.print(“I received: “);
Serial.println(incomingByte, DEC);
}
}
Arduino Mega example :
void setup()
{
Serial.begin(9600);
Serial1.begin(9600) ;
}
void loop()
{
// read from port 0, send to port 1:< /em>
if (Serial.available())
{
int inByte = Serial.read();
Serial1.print(inByte, BYTE);
}
// read from port 1, send to port 0:
if (Serial1.available())
{
int inByte = Serial1.read();
Serial.print(inByte, BYTE);
}
}
availableForWrite()
Description Get the number of bytes that can be written in the cache
Get the number of bytes (characters) available for writing in the serial buffer without blocking the write operation.
Syntax
Serial.availableForWrite()
Arduino Mega only:
Serial1.availableForWrite()
Serial2.availableForWrite()
Serial3.availableForWrite()
Parameters
none
Returns
the number of bytes available to write
begin()
Description Set the baud rate< /strong>
Sets the data rate in bits per second (baud) for serial data transmission. For communicating with the computer, use one of these rates: 300, 600, 1200, 2400, 4800, 9600, 14400, 19200, 28800, 38400, 57600, or 115200. You can, however, specify other rates-for example, to communicate over pins 0 and 1 with a component that requires a particular baud rate.
An optional second argument configures the data, parity, and stop bits. The default is 8 data bits, no parity, one stop bit.
Syntax
Serial.begin(speed)
Serial.begin(speed, config)
Arduino Mega only:
Serial1.begin(speed )
Serial2.begin(speed)
Serial3.begin(speed)
Serial1.begin(speed, config)
Serial2.begin(speed, config)
Serial3.begin(speed, config)
Parameters
speed: in bits per second (baud)-long
config: sets data, parity, and stop bits. < strong>Set data length, polarity, stop bit. Valid values are:
SERIAL_5N1
SERIAL_6N1
SERIAL_7N1
SERIAL_8N1 (the default) Default configuration:8bit data, no check digit,1stop bits
SERIAL_5N2
SERIAL_6N2
SERIAL_7N2
SERIAL_8N2
SERIAL_5E1
SERIAL_6E1
SERIAL_7E1
SERIAL_8E1
SERIAL_5E2
SERIAL_6E2
SERIAL_7E2
SERIAL_8E2
SERIAL_5O1
SERIAL_6O1
SERIAL_7O1
SERIAL_8O1
SERIAL_5O2
SERIAL_6O2
SERIAL_7O2
SERIAL_8O2
Returns
nothing
Example:
void < strong>setup()
{
Serial.begin(9600); // opens serial port, sets data rate to 9600 bps
}
void loop() {}
Arduino Mega example:
< p>// Arduino Mega using all four of its Serial ports
// (Serial, Serial1, Se rial2, Serial3),
// with different baud rates:
void setup()
{
Serial.begin(9600);
Serial1.begin(38400);
Serial2.begin(19200);
Serial3.begin(4800);
Serial.println(“Hello Computer”);
Serial1.println(“Hello Serial 1”);
Serial2.println(“Hello Serial 2”);
Serial3.println(“Hello Serial 3”);
}
void loop() {}
Thanks to Jeff Gray for the mega example
< /p>
end()
Description Prohibit serial communication, releaseRXand< /strong>TXPins
Disables serial communication, allowing the RX and TX pins to be used for general input and output. To re-enable serial communication, call Serial.begin().
Syntax
Serial.end()
Arduino Mega only:
Serial1.end()
Serial2.end()
Serial3.end()
Parameters
none
Returns
nothing
Serial.find()
Description Read data from the serial buffer until the target string is found
Serial.find() reads data from the serial buffer until the target string of given length is found. The function returns true if target string is found, false if it times out.
Serial.find() inherits from the Stream utility class.
Syntax
Serial.find(target)
Parameters
< em>target: the string to search for (char)
Returns
boolean
Serial .findUntil()
Description Read data from the serial buffer until the target string or stop character is found
Serial.findUntil() reads data from the serial buffer until a target string of given length or terminator string is found.
The function returns true if the target string is found, false if it times out.
Serial.findUntil() inherits from the Stream utility class.
Syntax
Serial.findUntil(target, terminal)< /p>
Parameters
target: the string to search for (char)
terminal: the terminal string in the search (char)
Returns
boolean
flush()
DescriptionWait for data sending to complete
Waits for the transmission of outgoing serial data to complete. (Prior to Arduino 1.0, this instead removed any buffered incoming serial data.)
flush() inherits from the Stream utility class.
Syntax< /p>
Serial.flush()
Arduino Mega only:
Serial1.flush()
Serial2.flush()
Serial3. flush()
Parameters
none
Returns
nothing
< strong>parseFloat()
Description Returns the first valid floating point data from the buffer
Serial.parseFloat() returns the first valid floating point number from the Serial buffer. Characters that are not digits (or the minus sign) are skipped. parseFloat() is terminated by the first character that is not a floating point number.
Serial.parseFloat () inheri ts from the Stream utility class.
Syntax
Serial.parseFloat()
Parameters
none
Returns
float
parseInt()
Description From the new serial data Find the next valid integer
Looks for the next valid integer in the incoming serial stream. parseInt() inherits from the Stream utility class.
In particular: < /p>
Initial characters that are not digits or a minus sign, are skipped;
Parsing stops when no characters have been read for a configurable time-out value, or a non-digit is read ;
If no valid digits were read when the time-out (see Serial.setTimeout()) occurs, 0 is returned;
Syntax
Serial. parseInt()
Serial.parseInt(char skipChar)
Arduino Mega only:
Serial1.parseInt()
Serial2.parseInt( )
Serial3.parseInt()
Parameters
skipChar: used to skip the indicated char in the search. Used for example to skip thousands divider.
Ret urns
long: the next valid integer
peek()
Description Read Take the next byte of data and not delete it from the cache after reading it
Returns the next byte (character) of incoming serial data without removing it from the internal serial buffer. That is, successive calls to peek() will return the same character, as will the next call to read(). peek() inherits from the Stream utility class.
Syntax
Serial.peek ()
Arduino Mega only:
Serial1.peek()
Serial2.peek()
Serial3.peek()
Parameters
None
Returns
the first byte of incoming serial data available (or -1 if no data is available)-int
print()
Description outputs data in the form of ASCII Serial port. The sending method is: data is converted into characters, and the corresponding ASCIIcode of the character is sent, and then converted into characters when displayed.
Prints data to the serial port as human-readable ASCII text. This command can take many forms. Numbers are printed using an ASCII character for each digit. Floats are similarly printed as ASCII digits, defaulting to two decimal places. Bytes are sent as a single character. Characters and strings are sent as is. For example:
Serial.print(78) gives “78”
Serial .print(1.23456) gives “1.23”
Serial.print(‘N’) gives “N”
Serial.print(“Hello world.”) gives “Hello world. “
An optional second parameter specifies the base (format) to use; permitted values are BIN (binary, or base 2), OCT (octal, or base 8), DEC (decimal, or base 10) , HEX (hexadecimal, or base 16). For floating point numbers, this parameter specifies the number of decimal places to use. For example:
Serial.print(78, BIN) gives “1001110”
Serial.print(78, OCT) gives “116”
Serial.print(78, DEC) gives “78”
Serial.print(78, HEX ) gives “4E”
Se rial.println(1.23456, 0) gives “1”
Serial.println(1.23456, 2) gives “1.23”
Serial.println(1.23456, 4) gives “1.2346”
You can pass flash-memory based strings to Serial.print() by wrapping them with F(). For example:
Serial.print(F(“Hello World”) )
To send a single byte, use Serial.write().
Syntax
Serial.print(val)
Serial.print(val , format)
Parameters
val: the value to print-any data type
format: specifies the number base (for integral data types) or number of decimal places (for floating point types)
Returns
size_t (long): print() returns the number of bytes written, though reading that number is optional
Example:
/*
Uses a FOR loop for data and prints a number in various formats.
*/
int x = 0; // variable
void setup()
{
Serial.begin(9600); // open the serial port at 9600 bps:
}
void loop()
{
// print labels
Serial.print(“NF”); // prints a label no format
Serial.print(“\t”); // prints a tab
Serial.print(“DEC”);
Serial.print(“\t”);
Serial.print(“HEX”);
Serial.print(” \t”);
Serial.print(“OCT”);
Serial.print(“\t”);
< p>
Serial.print(“BIN”);
Serial.print(“\t”);
Serial .println(); Add a carriage return to switch to the next line
for(x=0; x<16; x++)
{// only part of the ASCII chart, change to suit
// print it out in many formats:
Serial.print (x); // print as an ASCII-encoded decimal-same as “DEC”
Serial.print(“\t”); // prints a tab
p>
Serial.print(x, DEC); // print as an ASCII-encoded decimal
Serial.print(“\t”); // prints a tab
< p>
Serial.print(x, HEX); // prin t as an ASCII-encoded hexadecimal
Serial.print(“\t”); // prints a tab
Serial.print(x, OCT ); // print as an ASCII-encoded octal
Serial.print(“\t”); // prints a tab
Serial.println (x, BIN); // print as an ASCII-encoded binary
// // Delay 200 milliseconds then add the carriage return
}
Serial.println(“”); // prints another carriage return Add a carriage return to switch to the next line
< p> while(1)
{}
}
The running result is as follows
Programming Tips
As of version 1.0, serial transmission is asynchronous; Serial.print( ) will return before any characters are transmitted.
println()
Description InASCII
Syntax
Serial.println( val)
Serial.println(val, format)
Parameters
val: the value to print-any data type
format: specifies the number base (for integral data types) or number of decimal places (for floating point types)
Returns
size_t (long): println() returns the number of bytes written, though reading that number is optional
Example:
/*
Analog input
reads an analog input on analog in 0, prints the value out.
created 24 March 2006
by Tom Igoe
*/
int analogValue = 0; // variable to hold the analog value
void setup()
{
// open the serial port at 9600 bps:
Serial.begin(9600);
}
void loop()
{
// read the analog input on pin 0:
analogValue = analogRead(0);
// print it out in many formats:< br> Serial.println(analogValue); // print as an ASCII-encoded decimal
Serial.println(analogValue, DEC); // print as an ASCII-encoded decimal< /em>
Serial.println(analogValue, HEX); // print as an ASCII-encoded hexadecimal
Serial.println(analogValue, OCT); // print as an ASCII-encoded octal
Serial.println(analogValue, BIN); // print as an ASCII-encoded binary
// delay 10 milliseconds before the next reading:
delay(10);
}
read()
Description Read data from the serial port, each read1bytes. After reading the data, delete the data from the cache.
Reads incoming serial data. read() inherits from the Stream utility class.
Syntax
Serial.read()
Arduino Mega only:
Serial1.read()
Serial2.read()
Serial3.read()
Parameters
None
Returns
the first byte of incoming serial data available (or -1 if no data is available)-int
Example
int incomingByte = 0; // for incoming serial data
void setup()
{
Serial.begin(9600); // opens serial port, sets data rate to 9600 bps
}
void loop()
{
// send data only when you receive data:
if (Serial.available()> 0)
{
// read the incoming byte:
em>// say what you got:
Serial.print(“I received: “);
Serial.println(incomingByte, DEC);
}
}
Serial.readBytes()
Description Read characters of the specified length from the buffer
Serial.readBytes() reads characters from the serial port into a buffer. The function terminates if the determined length has been read, or it times out (see Serial.setTimeout()).
Serial.readBytes() returns the number of characters placed in the buffer. A 0 means no valid data was found.
Serial.readBytes() inherits from the Stream utility class.
Syntax
Serial.readBytes(buffer, length)
Parameters
buffer: the buffer to store the bytes in (char[] or byte[])
length: the number of bytes to read (int)
Returns
byte < /p>
Serial.readBytesUntil()
Description Read characters of specified length into an array
Serial.readBytesUntil() reads characters from the serial buffer into an array. The function terminates if the terminator character is d etected, the determined length has been read, or it times out (see Serial.setTimeout()).
Serial.readBytesUntil() returns the number of characters read into the buffer . A 0 means no valid data was found.
Serial.readBytesUntil() inherits from the Stream utility class.
Syntax
Serial.readBytesUntil(character, buffer, length)
Parameters
character: the character to search for (char)
buffer: the buffer to store the bytes in (char[] or byte[])
length : the number of bytes to read (int)
Returns
byte
readString()
Description Read characters into a string until timeout
Serial.readString() reads characters from the serial buffer into a string. The function terminates if it times out (see setTimeout()).
This function is part of the Stream class, and is called by any class that inherits from it (Wire, Serial, etc) . See the Stream class main page for more information.
Syntax
Serial.readString()
Parameters
none
Returns
A string read from the serial buffer
readStringUntil()
Description Read characters from the serial buffer into a string. Stop reading when it encounters a stop character
readStringUntil() reads characters from the serial buffer into a string. The function terminates if the terminator character is detected or it times out (see setTimeout()).
This function is part of the Stream class, and is called by any class that inherits from it (Wire, Serial , etc). See the Stream class main page for more information.
Syntax
Serial.readStringUntil(terminator) < /p>
Parameters
terminator: the character to search for (char)
Returns
The entire string< /p>
Serial.setTimeout()
DescriptionThe maximum time (in milliseconds) waiting to read data. The provincial value is1000
S erial.setTimeout() sets the maximum milliseconds to wait for serial data when using Serial.readBytesUntil(), Serial.readBytes(), Serial.parseInt() or Serial.parseFloat(). It defaults to 1000 milliseconds.
Serial.setTimeout() inherits from the Stream utility class.
Syntax
Serial.setTimeout(time)
Parameters
time: timeout duration in milliseconds (long).
Parameters
None
p>
write()
DescriptionOutput binary data to the serial port. Send the data itself. When the data is received, the data will be displayed as ASCIIcode and the corresponding characters will be displayed
Writes binary data to the serial port. This data is sent as a byte or series of bytes; to send the characters representing the digits of a number use the print() function instead.
Syntax
< p>Serial.write(val)
Serial.write(str)
Serial.write(buf, len)
Arduino Mega also supports: Serial1, Serial2 , Serial3 (in place of Serial)
Parameters
val: a value to send as a single byte
str: a string to send as a series of bytes
buf: an array to send as a series of bytes
len: the length of the buffer
Returns
byte< br>write() will return the number of bytes written, though reading that number is optional
Example
byte BYTE [3]={49,50,51};
void setup()
{
Serial.begin(9600);
< p>}
void loop()
{
Serial.write(45); // send a byte with the value 4 5
Serial.println();
Serial.write(BYTE,3); // send a byte with the value 45
Serial.println( );
int bytesSent = Serial.write(“hello”); //send the string “hello” and return the length of the string.
Serial.println();
while(1)
{}
}
The running results are as follows
The ASCII character corresponding to the decimal number 45 is “-“, the decimal number 49,50, The corresponding ASCII characters of 51 are 1, 2, 3, and the original code of the character “HELLO” is output.
serialEvent()
Description Execute this function if there is data in the serial buffer p>
Called when data is available. Use Serial.read() to capture this data.
NB: Currently, serialEvent() is not compatible with the Esplora, Leonardo, or Micro
Syntax
void serialEvent()
{
//statements
}
Arduino Mega only:
void serialEvent1()
{
< em>//statements
}
void serialEvent2()
{
//statements< br>}
void serialEvent3()
{
//statements
}
Parameters
statements: any valid statements