From 0dbe2e3e3329c2eb01d9417b201f575dd546555f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karl=20S=C3=B6derby?= <35461661+karlsoderby@users.noreply.github.com> Date: Thu, 27 Jan 2022 17:26:14 +0100 Subject: [PATCH 1/4] add pdm --- .../learn/07.built-in-libraries/01.pdm/pdm.md | 300 ++++++++++++++++++ .../built-in-libraries.md | 3 + 2 files changed, 303 insertions(+) create mode 100644 content/learn/07.built-in-libraries/01.pdm/pdm.md create mode 100644 content/learn/07.built-in-libraries/built-in-libraries.md diff --git a/content/learn/07.built-in-libraries/01.pdm/pdm.md b/content/learn/07.built-in-libraries/01.pdm/pdm.md new file mode 100644 index 0000000000..1ccb0c8c71 --- /dev/null +++ b/content/learn/07.built-in-libraries/01.pdm/pdm.md @@ -0,0 +1,300 @@ +--- +title: PDM Library +description: The PDM library allows you to use Pulse-density modulation microphones, found onboard the Nano RP2040 Connect & Nano 33 BLE Sense boards. +author: 'Arduino' +tags: [Microphone, PDM] +--- + +## Overview + +The PDM library allows you to use PDM ([Pulse-density modulation](https://en.wikipedia.org/wiki/Pulse-density_modulation)) microphones, such as the onboard MP34DT05 on the Arduino Nano 33 BLE Sense. + +To use this library: + +``` +#include +``` + +The library takes care of the audio that will be accessible also through the [ArduinoSound](https://www.arduino.cc/en/Reference/ArduinoSound) library. + + +## Functions + +### `begin()` + +#### Description + +Initialize the PDM interface. + +#### Syntax + +``` +PDM.begin(channels, sampleRate) + +``` + +#### Parameters +- channels: the number of channels, 1 for mono, 2 for stereo +- sampleRate: the sample rate to use in Hz + +#### Returns +1 on success, 0 on failure + +#### Example + +``` + if (!PDM.begin(1, 16000)) { + Serial.println("Failed to start PDM!"); + while (1); + } + + +``` + +### `end()` + +#### Description + +De-initialize the PDM interface. + +#### Syntax + +``` +PDM.end() + +``` + +#### Parameters +None + +#### Returns +Nothing + +#### Example + +``` + if (!PDM.begin(1, 16000)) { + Serial.println("Failed to start PDM!"); + while (1); + } + + + // + + PDM.end(); + + +``` + +### `available()` + +#### Description + +Get the number of bytes available for reading from the PDM interface. This is data that has already arrived and was stored in the PDM receive buffer. + +#### Syntax + +``` +PDM.available() + +``` + +#### Parameters +None + +#### Returns +The number of bytes available to read + +#### Example + +``` +// buffer to read samples into, each sample is 16-bits +short sampleBuffer[256]; + +// number of samples read +volatile int samplesRead; + +// + + // query the number of bytes available + int bytesAvailable = PDM.available(); + + // read into the sample buffer + PDM.read(sampleBuffer, bytesAvailable); + + +``` + +### `read()` + +#### Description + +Read data from the PDM into the specified buffer. + +#### Syntax + +``` +PDM.read(buffer, size) + +``` + +#### Parameters +- buffer: array to store the PDM data into +- size: number of bytes to read + +#### Returns +The number of bytes read + +#### Example + +``` +// buffer to read samples into, each sample is 16-bits +short sampleBuffer[256]; + +// number of samples read +volatile int samplesRead; + +// + + // query the number of bytes available + int bytesAvailable = PDM.available(); + + // read into the sample buffer + Int bytesRead = PDM.read(sampleBuffer, bytesAvailable); + + // 16-bit, 2 bytes per sample + samplesRead = bytesRead / 2; + + +``` + +### `onReceive()` + +#### Description + +Set the callback function that is called when new PDM data is ready to be read. + +#### Syntax + +``` + +PDM.onReceive(callback) + +``` + +#### Parameters +callback: function that is called when new PDM data is ready to be read + +#### Returns +Nothing + +#### Example + +``` +// buffer to read samples into, each sample is 16-bits +short sampleBuffer[256]; + +// number of samples read +volatile int samplesRead; + +// + + // configure the data receive callback + PDM.onReceive(onPDMdata); + + // initialize PDM with: + // - one channel (mono mode) + // - a 16 kHz sample rate + if (!PDM.begin(1, 16000)) { + Serial.println("Failed to start PDM!"); + while (1); + } + + + // + +void onPDMdata() { + // query the number of bytes available + int bytesAvailable = PDM.available(); + + // read into the sample buffer + Int bytesRead = PDM.read(sampleBuffer, bytesAvailable); + + // 16-bit, 2 bytes per sample + samplesRead = bytesRead / 2; +} + + + +``` + +### `setGain()` + +#### Description + +Set the gain value used by the PDM interface. + +#### Syntax + +``` +PDM.setGain(gain) + +``` + +#### Parameters +gain: gain value to use, 0 - 255, defaults to 20 if not specified. + +#### Returns +Nothing + +#### Example + +``` + // optionally set the gain, defaults to 20 + PDM.setGain(30); + + // initialize PDM with: + // - one channel (mono mode) + // - a 16 kHz sample rate + if (!PDM.begin(1, 16000)) { + Serial.println("Failed to start PDM!"); + while (1); + } + + + +``` + +### `setBufferSize()` + +#### Description + +Set the buffer size (in bytes) used by the PDM interface. Must be called before PDM.begin(...), a default buffer size of 512 is used if not called. This is enough to hold 256 16-bit samples. + +#### Syntax + +``` +PDM.setBufferSize(size) + +``` + +#### Parameters +size: buffer size to use in bytes + +#### Returns +Nothing + +#### Example + +``` + PDM.setBufferSize(1024); + + // initialize PDM with: + // - one channel (mono mode) + // - a 16 kHz sample rate + if (!PDM.begin(1, 16000)) { + Serial.println("Failed to start PDM!"); + while (1); + } + +``` \ No newline at end of file diff --git a/content/learn/07.built-in-libraries/built-in-libraries.md b/content/learn/07.built-in-libraries/built-in-libraries.md new file mode 100644 index 0000000000..c67b9de42d --- /dev/null +++ b/content/learn/07.built-in-libraries/built-in-libraries.md @@ -0,0 +1,3 @@ +--- +title: Built-in Libraries +--- \ No newline at end of file From fe4c2a7c8342183d59245549aeb5ad1e61f65fe5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karl=20S=C3=B6derby?= <35461661+karlsoderby@users.noreply.github.com> Date: Fri, 28 Jan 2022 11:15:19 +0100 Subject: [PATCH 2/4] add i2s --- .../learn/07.built-in-libraries/02.i2s/i2s.md | 175 ++++++++++++++++++ 1 file changed, 175 insertions(+) create mode 100644 content/learn/07.built-in-libraries/02.i2s/i2s.md diff --git a/content/learn/07.built-in-libraries/02.i2s/i2s.md b/content/learn/07.built-in-libraries/02.i2s/i2s.md new file mode 100644 index 0000000000..7cd879d4a9 --- /dev/null +++ b/content/learn/07.built-in-libraries/02.i2s/i2s.md @@ -0,0 +1,175 @@ +--- +title: 'I2S Library' +description: 'Documentation for usage of the I2S (Inter-IC Sound) protocol on SAMD21 boards.' +author: 'Arduino' +--- + +## Overview + +This library allows you to use the I2S protocol on SAMD21 based boards (i.e Arduino or Genuino Zero, MKRZero or MKR1000 Board). + +To use this library + +``` +#include +``` + +I2S (Inter-IC Sound), is an electrical serial bus interface standard used for connecting digital audio devices together. It is used to communicate PCM audio data between integrated circuits in an electronic device. + +An I2S bus that follows the Philips standard is made up of at least three wires: + +- **SCK** (Serial Clock): is the clock signal also referred as **BCLK** (Bit Clock Line); +- **FS** (Frame Select): used to discriminate Right or Left Channel data also referred **WS** (Word Select); +- **SD** (Serial Data): the serial data to be transmitted; + +As detailed below, the device who generates **SCK** and **WS** is the Controller. + +The SCK line has a frequency that depends on the sample rate, the number of bits for channel and the number of channels in the following way: + +- **Frequency = SampleRate x BitsPerChannel x numberOfChannels** + +In a typical setup, the sender of audio data is called a Transmitter and it transfers data to a Receiver at the other end. The device that controls the bus clock, SCK, together with the Word Select - WS - signal is the Controller in the network and in any network just one device can be Controller at any given time; all the other devices connected are in Peripheral mode. The Controller can be the Transmitter, or the Receiver, or a standalone controller. The digitized audio data sample can have a size ranging from 4 bits up to 32. + +As a general rule of thumb, the higher the sample rate (kHz) and bits per sample, the better audio quality (when the digital data is converted back to analog audio sound). + +## I2S Class + +### `begin()` + +#### Description +Initializes the I2S interface with the given parameters to enable communication. + +#### Syntax + +``` +I2S.begin(mode, sampleRate, bitsPerSample); // controller device +I2S.begin(mode, bitsPerSample); // peripheral device + +``` + +#### Parameters +mode: one between I2S_PHILIPS_MODE, I2S_RIGHT_JUSTIFIED_MODE or I2S_LEFT_JUSTIFIED_MODE +sampleRate: the desired sample rate in Hz - long +bitsPerSample: the desired bits per sample (i.e 8, 16, 32) + +#### Returns +1 if initialization is ok, 0 otherwise + +### `end()` + +#### Description +Disables I2S communication, allowing the I2S pins to be used for general input and output. To re-enable I2S communication, call I2S.begin(). + +#### Syntax + +``` +I2S.end() + +``` + +#### Parameters +none + +#### Returns +nothing + +### `available()` + +#### Description +Get the number of bytes available for reading from the I2S interface. This is data that has already arrived and was stored in the I2S receive buffer. available() inherits from the Stream utility class. + +#### Syntax + +``` +I2S.available() + +``` + +#### Parameters +none + +#### Returns +the number of bytes available to read + +### `peek()` + +#### Description +Returns the next sample of incoming I2S data without removing it from the internal I2S buffer. That is, successive calls to peek() will return the same sample, as will the next call to read(). peek() inherits from the Stream utility class. + +#### Syntax + +``` +I2S.peek() + +``` + +#### Parameters +None + +#### Returns +The next sample of incoming I2S data available (or 0 if no data is available) + +### `write()` + +#### Description +Writes binary data to the I2S interface. This data is sent as a sample or series of samples. + +#### Syntax + +``` +I2S.write(val) // blocking +I2S.write(buf, len) // not blocking + +``` + +#### Parameters +val: a value to send as a single sample + +buf: an array to send as a series of samples + +len: the length of the buffer + +#### Returns +byte +- write() will return the number of bytes written, though reading that number is optional. + +### `availableForWrite()` + +#### Description +Get the number of bytes available for writing in the buffer without blocking the write operation. + +#### Syntax + +``` +I2S.availableForWrite() + +``` + +#### Parameters +none + +#### Returns +the number of bytes available to write. + +### `onTransmit(handler)` + +#### Description +Registers a function to be called when a block of data has been transmitted. + +#### Parameters +handler: the function to be called when data is sent and return nothing, e.g.: void myHandler() + +#### Returns +None + +### `onReceive(handler)` + +#### Description +Registers a function to be called when a block of data has been received. + +#### Parameters +handler: the function to be called when the device receives data and return nothing, e.g.: void myHandler() + +#### Returns +None + From 740c3aeb668ecc8be4b24cd01eacb37b8656eaab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karl=20S=C3=B6derby?= <35461661+karlsoderby@users.noreply.github.com> Date: Fri, 28 Jan 2022 11:22:10 +0100 Subject: [PATCH 3/4] add eeprom --- .../learn/07.built-in-libraries/02.i2s/i2s.md | 1 + .../07.built-in-libraries/03.eeprom/eeprom.md | 332 ++++++++++++++++++ 2 files changed, 333 insertions(+) create mode 100644 content/learn/07.built-in-libraries/03.eeprom/eeprom.md diff --git a/content/learn/07.built-in-libraries/02.i2s/i2s.md b/content/learn/07.built-in-libraries/02.i2s/i2s.md index 7cd879d4a9..3f9e299fd5 100644 --- a/content/learn/07.built-in-libraries/02.i2s/i2s.md +++ b/content/learn/07.built-in-libraries/02.i2s/i2s.md @@ -2,6 +2,7 @@ title: 'I2S Library' description: 'Documentation for usage of the I2S (Inter-IC Sound) protocol on SAMD21 boards.' author: 'Arduino' +tags: [I2S, Audio, SAMD] --- ## Overview diff --git a/content/learn/07.built-in-libraries/03.eeprom/eeprom.md b/content/learn/07.built-in-libraries/03.eeprom/eeprom.md new file mode 100644 index 0000000000..3464cb13d1 --- /dev/null +++ b/content/learn/07.built-in-libraries/03.eeprom/eeprom.md @@ -0,0 +1,332 @@ +--- +title: EEPROM Library +description: Documentation for usage of the EEPROM library. EEPROM is a memory whose values are kept when the board is powered off. +author: 'Arduino' +tags: [EEPROM] +--- + +The microcontroller on the Arduino and Genuino AVR based board has EEPROM: memory whose values are kept when the board is turned off (like a tiny hard drive). This library enables you to read and write those bytes. + +The supported micro-controllers on the various Arduino and Genuino boards have different amounts of EEPROM: 1024 bytes on the ATmega328P, 512 bytes on the ATmega168 and ATmega8, 4 KB (4096 bytes) on the ATmega1280 and ATmega2560. The Arduino and Genuino 101 boards have an emulated EEPROM space of 1024 bytes. + +To use this library + +``` +#include +``` + +## Examples + +To see a list of examples for the EEPROM library, click the link below: + +- [A Guide to EEPROM](/learn/programming/eeprom-guide) + +## Functions + +### `read()` + +#### Description +Reads a byte from the EEPROM. Locations that have never been written to have the value of 255. + +#### Syntax + +``` +EEPROM.read(address) +``` + +#### Parameters +address: the location to read from, starting from 0 (int) + +#### Returns +the value stored in that location (byte) + +#### Example + +``` +#include + +int a = 0; +int value; + +void setup() +{ + Serial.begin(9600); +} + +void loop() +{ + value = EEPROM.read(a); + + Serial.print(a); + Serial.print("\t"); + Serial.print(value); + Serial.println(); + + a = a + 1; + + if (a == 512) + a = 0; + + delay(500); +} +``` + +### `write()` + +#### Description +Write a byte to the EEPROM. + +#### Syntax + +``` +EEPROM.write(address, value) +``` + +#### Parameters +address: the location to write to, starting from 0 (int) + +value: the value to write, from 0 to 255 (byte) + +#### Returns +none + +Note: An EEPROM write takes 3.3 ms to complete. The EEPROM memory has a specified life of 100,000 write/erase cycles, so you may need to be careful about how often you write to it. + +#### Example + +``` + +#include + +void setup() +{ + for (int i = 0; i < 255; i++) + EEPROM.write(i, i); +} + +void loop() +{ +} + +``` + +### `update()` + +#### Description +Write a byte to the EEPROM. The value is written only if differs from the one already saved at the same address. + +#### Syntax + +``` +EEPROM.update(address, value) + +``` + +#### Parameters +address: the location to write to, starting from 0 (int) + +value: the value to write, from 0 to 255 (byte) + +#### Returns +none + +>Note: An EEPROM write takes 3.3 ms to complete. The EEPROM memory has a specified life of 100,000 write/erase cycles, so using this function instead of write() can save cycles if the written data does not change often + +#### Example + +``` + +#include + +void setup() +{ + for (int i = 0; i < 255; i++) { + // this performs as EEPROM.write(i, i) + EEPROM.update(i, i); + } + for (int i = 0; i < 255; i++) { + // write value "12" to cell 3 only the first time + // will not write the cell the remaining 254 times + EEPROM.update(3, 12); + } +} + +void loop() +{ +} + +``` + +### `get()` + +#### Description +Read any data type or object from the EEPROM. + +#### Syntax + +``` +EEPROM.get(address, data) + +``` + +#### Parameters +address: the location to read from, starting from 0 (int) + +data: the data to read, can be a primitive type (eg. float) or a custom struct + +#### Returns +A reference to the data passed in + +#### Example + +``` + +#include + +struct MyObject{ + float field1; + byte field2; + char name[10]; +}; + +void setup(){ + + float f = 0.00f; //Variable to store data read from EEPROM. + int eeAddress = 0; //EEPROM address to start reading from + + Serial.begin( 9600 ); + while (!Serial) { + ; // wait for serial port to connect. Needed for Leonardo only + } + Serial.print( "Read float from EEPROM: " ); + + //Get the float data from the EEPROM at position 'eeAddress' + EEPROM.get( eeAddress, f ); + Serial.println( f, 3 ); //This may print 'ovf, nan' if the data inside the EEPROM is not a valid float. + + // get() can be used with custom structures too. + eeAddress = sizeof(float); //Move address to the next byte after float 'f'. + MyObject customVar; //Variable to store custom object read from EEPROM. + EEPROM.get( eeAddress, customVar ); + + Serial.println( "Read custom object from EEPROM: " ); + Serial.println( customVar.field1 ); + Serial.println( customVar.field2 ); + Serial.println( customVar.name ); +} + +void loop(){ /* Empty loop */ } + +``` + +### `put()` + +#### Description +Write any data type or object to the EEPROM. + +#### Syntax + +``` +EEPROM.put(address, data) + +``` + +#### Parameters +address: the location to write to, starting from 0 (int) + +data: the data to write, can be a primitive type (eg. float) or a custom struct + +#### Returns +A reference to the data passed in + +>Note: This function uses EEPROM.update() to perform the write, so does not rewrites the value if it didn't change. + +#### Example + +``` + +#include + +struct MyObject { + float field1; + byte field2; + char name[10]; +}; + +void setup() { + + Serial.begin(9600); + while (!Serial) { + ; // wait for serial port to connect. Needed for native USB port only + } + + float f = 123.456f; //Variable to store in EEPROM. + int eeAddress = 0; //Location we want the data to be put. + + + //One simple call, with the address first and the object second. + EEPROM.put(eeAddress, f); + + Serial.println("Written float data type!"); + + /** Put is designed for use with custom structures also. **/ + + //Data to store. + MyObject customVar = { + 3.14f, + 65, + "Working!" + }; + + eeAddress += sizeof(float); //Move address to the next byte after float 'f'. + + EEPROM.put(eeAddress, customVar); + Serial.print("Written custom data type! \n\nView the example sketch eeprom_get to see how you can retrieve the values!"); +} + +void loop() { /* Empty loop */ } + +``` + +### `EEPROM[]` +Description +This operator allows using the identifier `EEPROM` like an array. EEPROM cells can be read and written directly using this method. + +#### Syntax + +``` +EEPROM[address] + +``` + +#### Parameters +address: the location to read/write from, starting from 0 (int) + +#### Returns +A reference to the EEPROM cell + +#### Example + +``` + +#include + +void setup(){ + + unsigned char val; + + //Read first EEPROM cell. + val = EEPROM[ 0 ]; + + //Write first EEPROM cell. + EEPROM[ 0 ] = val; + + //Compare contents + if( val == EEPROM[ 0 ] ){ + //Do something... + } +} + +void loop(){ /* Empty loop */ } + +``` \ No newline at end of file From ea7c92a0abbeac520c839da3763c445c383b6552 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karl=20S=C3=B6derby?= <35461661+karlsoderby@users.noreply.github.com> Date: Fri, 28 Jan 2022 11:28:45 +0100 Subject: [PATCH 4/4] add softwareserial --- .../04.software-serial/software-serial.md | 671 ++++++++++++++++++ 1 file changed, 671 insertions(+) create mode 100644 content/learn/07.built-in-libraries/04.software-serial/software-serial.md diff --git a/content/learn/07.built-in-libraries/04.software-serial/software-serial.md b/content/learn/07.built-in-libraries/04.software-serial/software-serial.md new file mode 100644 index 0000000000..59defba09a --- /dev/null +++ b/content/learn/07.built-in-libraries/04.software-serial/software-serial.md @@ -0,0 +1,671 @@ +--- +title: SoftwareSerial Library +description: The SoftwareSerial library allows serial communication on other digital pins of an Arduino board. +author: 'Arduino' +tags: [Serial] +--- + +The SoftwareSerial library allows serial communication on other digital pins of an Arduino board, using software to replicate the functionality (hence the name "SoftwareSerial"). It is possible to have multiple software serial ports with speeds up to 115200 bps. A parameter enables inverted signaling for devices which require that protocol. + +The version of SoftwareSerial included in 1.0 and later is based on the [NewSoftSerial library](http://arduiniana.org/libraries/newsoftserial/) by Mikal Hart. + +To use this library: + +``` +#include +``` + +## Limitations of This Library + +SoftwareSerial library has the following known limitations: + +* If using multiple software serial ports, only one can receive data at a time. +* Not all pins on the Mega and Mega 2560 boards support change interrupts, so only the following can be used for RX: 10, 11, 12, 13, 14, 15, 50, 51, 52, 53, A8 (62), A9 (63), A10 (64), A11 (65), A12 (66), A13 (67), A14 (68), A15 (69). +Not all pins on the Leonardo and Micro boards support change interrupts, so only the following can be used for RX: 8, 9, 10, 11, 14 (MISO), 15 (SCK), 16 (MOSI). +* On Arduino or Genuino 101 boards the current maximum RX speed is 57600bps. +* On Arduino or Genuino 101 boards RX doesn't work on digital pin 13. + +If your project requires simultaneous data flows, see Paul Stoffregen's [AltSoftSerial library](https://www.pjrc.com/teensy/td_libs_AltSoftSerial.html). + +## Examples + +* [SoftwareSerial example](/tutorials/communication/SoftwareSerialExample): sometimes one serial port just isn't enough! +* [Two port receive](/tutorials/communication/TwoPortReceive): Work with multiple software serial ports. + +## Methods + +### `SoftwareSerial()` + +Create an instance of a SoftwareSerial object. Multiple SoftwareSerial objects may be created, however only one can be active at a given moment. + +#### Syntax + +``` +SoftwareSerial(rxPin, txPin, inverse_logic) +``` + +#### Parameters + +* _rxPin_: the pin on which to receive serial data. +* _txPin_: the pin on which to transmit serial data. +* _inverse_logic_: used to invert the sense of incoming bits (the default is normal logic). If set, SoftwareSerial treats a LOW (0v on the pin, normally) on the RX pin as a 1-bit (the idle state) and a HIGH (5V on the pin, normally) as a 0-bit. It also affects the way that it writes to the TX pin. Default value is false. + +#### Returns + +None. + +#### Example + +```arduino +#include + +const byte rxPin = 2; +const byte txPin = 3; + +// Set up a new SoftwareSerial object +SoftwareSerial mySerial (rxPin, txPin); +``` + +#### See also + +* [available()](#available) +* [begin()](#begin) +* [isListening()](#islistening) +* [overflow()](#overflow) +* [peek()](#peek) +* [read()](#read) +* [print()](#print) +* [println()](#println) +* [listen()](#listen) +* [write()](#write) + +### `available()` + +Get the number of bytes (characters) available for reading from a software serial port. This is data that has already arrived and stored in the serial receive buffer. + +#### Syntax + +``` +mySerial.available() +``` + +#### Parameters + +None. + +#### Returns + +The number of bytes available to read. + +#### Example + +```arduino +#include + +#define rxPin 10 +#define txPin 11 + +// Set up a new SoftwareSerial object +SoftwareSerial mySerial = SoftwareSerial(rxPin, txPin); + +void setup() { + // Define pin modes for TX and RX + pinMode(rxPin, INPUT); + pinMode(txPin, OUTPUT); + + // Set the baud rate for the SoftwareSerial object + mySerial.begin(9600); +} + +void loop() { + if (mySerial.available() > 0) { + mySerial.read(); + } +} +``` + +#### See also + +* [SoftwareSerial()](#softwareserial) +* [begin()](#begin) +* [isListening()](#islistening) +* [overflow()](#overflow) +* [peek()](#peek) +* [read()](#read) +* [print()](#print) +* [println()](#println) +* [listen()](#listen) +* [write()](#write) + +### `begin()` + +Sets the speed (baud rate) for the serial communication. Supported baud rates are: 300, 600, 1200, 2400, 4800, 9600, 14400, 19200, 28800, 31250, 38400, 57600, and 115200 bauds. + +#### Syntax + +``` +mySerial.begin(speed) +``` + +#### Parameters + +* _speed_: the desired baud rate (long). Supported baud rates are: 300, 600, 1200, 2400, 4800, 9600, 14400, 19200, 28800, 31250, 38400, 57600, and 115200 bauds. + +#### Returns + +None. + +#### Example + +```arduino +#include + +#define rxPin 10 +#define txPin 11 + +// Set up a new SoftwareSerial object +SoftwareSerial mySerial = SoftwareSerial(rxPin, txPin); + +void setup() { + // Define pin modes for TX and RX + pinMode(rxPin, INPUT); + pinMode(txPin, OUTPUT); + + // Set the baud rate for the SoftwareSerial object + mySerial.begin(9600); +} + +void loop() { + // ... +} +``` + +#### See also + +* [SoftwareSerial()](#softwareserial) +* [available()](#available) +* [isListening()](#islistening) +* [overflow()](#overflow) +* [peek()](#peek) +* [read()](#read) +* [print()](#print) +* [println()](#println) +* [listen()](#listen) +* [write()](#write) + +### `isListening()` + +Tests to see if requested software serial object is actively listening. + +#### Syntax + +``` +mySerial.isListening() +``` + +#### Parameters + +None. + +#### Returns + +Boolean. + +#### Example + +```arduino +#include + +// Set up a new SoftwareSerial object with RX in digital pin 10 and TX in digital pin 11 +SoftwareSerial portOne(10, 11); + +void setup() { + // Set the baud rate for the Serial port + Serial.begin(9600); + + // Set the baud rate for the SerialSoftware object + portOne.begin(9600); +} + +void loop() { + if (portOne.isListening()) { + Serial.println("portOne is listening!"); + } + + // ... +``` + +#### See also + +* [SoftwareSerial()](#softwareserial) +* [available()](#available) +* [begin()](#begin) +* [overflow()](#overflow) +* [peek()](#peek) +* [read()](#read) +* [print()](#print) +* [println()](#println) +* [listen()](#listen) +* [write()](#write) + +### `overflow()` + +Tests to see if a SoftwareSerial buffer overflow has occurred. Calling this function clears the overflow flag, meaning that subsequent calls will return false unless another byte of data has been received and discarded in the meantime. The SoftwareSerial buffer can hold up to 64 bytes. + +#### Syntax + +``` +mySerial.overflow() +``` + +#### Parameters + +None. + +#### Returns + +Boolean. + +#### Example + +```arduino +#include + +// Set up a new SoftwareSerial object with RX in digital pin 10 and TX in digital pin 11 +SoftwareSerial portOne(10, 11); + +void setup() { + // Set the baud rate for the Serial port + Serial.begin(9600); + + // Set the baud rate for the SerialSoftware object + portOne.begin(9600); +} + +void loop() { + if (portOne.overflow()) { + Serial.println("portOne overflow!"); + } + + // ... +``` + +#### See also + +* [SoftwareSerial()](#softwareserial) +* [available()](#available) +* [begin()](#begin) +* [isListening()](#islistening) +* [peek()](#peek) +* [read()](#read) +* [print()](#print) +* [println()](#println) +* [listen()](#listen) +* [write()](#write) + +### `peek()` + +Return a character that was received on the RX pin of the software serial port. Unlike read(), however, subsequent calls to this function will return the same character. Note that only one SoftwareSerial object can receive incoming data at a time (select which one with the listen() function). + +#### Syntax + +``` +mySerial.peek() +``` + +#### Parameters + +None. + +#### Returns + +The character read or -1 if none is available. + +#### Example + +```arduino +#include + +// Set up a new SoftwareSerial object with RX in digital pin 10 and TX in digital pin 11 +SoftwareSerial mySerial(10, 11); + +void setup() { + // Set the baud rate for the SerialSoftware object + mySerial.begin(9600); +} + +void loop() { + char c = mySerial.peek(); +} +``` + +#### See also + +* [SoftwareSerial()](#softwareserial) +* [available()](#available) +* [begin()](#begin) +* [isListening()](#islistening) +* [overflow()](#overflow) +* [read()](#read) +* [print()](#print) +* [println()](#println) +* [listen()](#listen) +* [write()](#write) + +### `read()` + +Return a character that was received on the RX pin of the SoftwareSerial objecto. Note that only one SoftwareSerial object can receive incoming data at a time (select which one with the listen() function). + +#### Syntax + +``` +mySerial.read() +``` + +#### Parameters + +None. + +#### Returns + +The character read or -1 if none is available. + +#### Example + +```arduino +#include + +// Set up a new SoftwareSerial object with RX in digital pin 10 and TX in digital pin 11 +SoftwareSerial mySerial(10, 11); + +void setup() { + // Set the baud rate for the SerialSoftware object + mySerial.begin(9600); +} + +void loop() { + char c = mySerial.read(); +} +``` + +#### See also + +* [SoftwareSerial()](#softwareserial) +* [available()](#available) +* [begin()](#begin) +* [isListening()](#islistening) +* [overflow()](#overflow) +* [peek()](#peek) +* [print()](#print) +* [println()](#println) +* [listen()](#listen) +* [write()](#write) + +### `print()` + +Prints data to the transmit pin of the SoftwareSerial object. Works the same as the Serial.print() function. + +#### Syntax + +``` +mySerial.print(val) +``` + +#### Parameters + +* _val_: the value to print. + +#### Returns + +The number of bytes written (reading this number is optional). + +#### Example + +```arduino +#include + +// Set up a new SoftwareSerial object with RX in digital pin 10 and TX in digital pin 11 +SoftwareSerial mySerial(10, 11); + +int analogValue; + +void setup() { + // Set the baud rate for the SerialSoftware object + mySerial.begin(9600); +} + +void loop() { + // Read the analog value on pin A0 + analogValue = analogRead(A0); + + // Print analogValue in the Serial Monitor in many formats: + mySerial.print(analogValue); // Print as an ASCII-encoded decimal + mySerial.print("\t"); // Print a tab character + mySerial.print(analogValue, DEC); // Print as an ASCII-encoded decimal + mySerial.print("\t"); // Print a tab character + mySerial.print(analogValue, HEX); // Print as an ASCII-encoded hexadecimal + mySerial.print("\t"); // Print a tab character + mySerial.print(analogValue, OCT); // Print as an ASCII-encoded octal + mySerial.print("\t"); // Print a tab character + mySerial.print(analogValue, BIN); // Print as an ASCII-encoded binary + mySerial.print("\t"); // Print a tab character + mySerial.print(analogValue/4, BYTE); // Print as a raw byte value (divide the + // value in 4 because analogRead() function returns numbers + // from 0 to 1023, but a byte can only hold values up to 255) + + mySerial.print("\t"); // Print a tab character + mySerial.println(); // Print a line feed character + + // Pause for 10 milliseconds before the next reading + delay(10); +} +``` + +#### See also + +* [SoftwareSerial()](#softwareserial) +* [available()](#available) +* [begin()](#begin) +* [isListening()](#islistening) +* [overflow()](#overflow) +* [peek()](#peek) +* [read()](#read) +* [print()](#print) +* [println()](#println) +* [listen()](#listen) +* [write()](#write) + +### `println()` + +Prints data to the transmit pin of the SoftwareSerial object followed by a carriage return and line feed. Works the same as the Serial.println() function. + +#### Syntax + +``` +mySerial.println(val) +``` + +#### Parameters + +* _val_: the value to print. + +#### Returns + +The number of bytes written (reading this number is optional). + +#### Example + +```arduino +#include + +// Set up a new SoftwareSerial object with RX in digital pin 10 and TX in digital pin 11 +SoftwareSerial mySerial(10, 11); + +int analogValue; + +void setup() { + // Set the baud rate for the SerialSoftware object + mySerial.begin(9600); +} + +void loop() { + // Read the analog value on pin A0 + analogValue = analogRead(A0); + + // Print analogValue in the Serial Monitor in many formats: + mySerial.print(analogValue); // Print as an ASCII-encoded decimal + mySerial.print("\t"); // Print a tab character + mySerial.print(analogValue, DEC); // Print as an ASCII-encoded decimal + mySerial.print("\t"); // Print a tab character + mySerial.print(analogValue, HEX); // Print as an ASCII-encoded hexadecimal + mySerial.print("\t"); // Print a tab character + mySerial.print(analogValue, OCT); // Print as an ASCII-encoded octal + mySerial.print("\t"); // Print a tab character + mySerial.print(analogValue, BIN); // Print as an ASCII-encoded binary + mySerial.print("\t"); // Print a tab character + mySerial.print(analogValue/4, BYTE); // Print as a raw byte value (divide the + // value in 4 because analogRead() function returns numbers + // from 0 to 1023, but a byte can only hold values up to 255) + + mySerial.print("\t"); // Print a tab character + mySerial.println(); // Print a line feed character + + // Pause for 10 milliseconds before the next reading + delay(10); +} +``` + +#### See also + +* [SoftwareSerial()](#softwareserial) +* [available()](#available) +* [begin()](#begin) +* [isListening()](#islistening) +* [overflow()](#overflow) +* [peek()](#peek) +* [read()](#read) +* [print()](#print) +* [listen()](#listen) +* [write()](#write) + +### `listen()` + +Enables the selected SoftwareSerial object to listen. Only one SoftwareSerial object can listen at a time; data that arrives for other ports will be discarded. Any data already received is discarded during the call to listen() function (unless the given instance is already listening). + +#### Syntax + +``` +mySerial.listen() +``` + +#### Parameters + +None. + +#### Returns + +Returns true if it replaces another. + +#### Example + +```arduino +#include + +// Set up a new SoftwareSerial object with RX in digital pin 10 and TX in digital pin 11 +SoftwareSerial portOne(10, 11); + +// Set up a new SoftwareSerial object with RX in digital pin 8 and TX in digital pin 9 +SoftwareSerial portTwo(8, 9); + +void setup() { + // Set the baud rate for the Serial object + Serial.begin(9600); + + // Set the baud rate for the SerialSoftware objects + portOne.begin(9600); + portTwo.begin(9600); +} + +void loop() { + // Enable SoftwareSerial object to listen + portOne.listen(); + + if (portOne.isListening()) { + Serial.println("portOne is listening!"); + } else { + Serial.println("portOne is not listening!"); + } + + if (portTwo.isListening()) { + Serial.println("portTwo is listening!"); + } else { + Serial.println("portTwo is not listening!"); + } +} +``` + +#### See also + +* [SoftwareSerial()](#softwareserial) +* [available()](#available) +* [begin()](#begin) +* [isListening()](#islistening) +* [overflow()](#overflow) +* [peek()](#peek) +* [read()](#read) +* [print()](#print) +* [println()](#println) +* [write()](#write) + +### `write()` + +Prints data to the transmit pin of the SoftwareSerial object as raw bytes. Works the same as the Serial.write()function. + +#### Syntax + +``` +mySerial.write(val) +``` + +#### Parameters + +* _val_: the binary value to print. + +#### Returns + +The number of bytes written (reading this number is optional). + +#### Example + +```arduino +#include + +// Set up a new SoftwareSerial object with RX in digital pin 10 and TX in digital pin 11 +SoftwareSerial mySerial(10, 11); + +void setup() { + // Set the baud rate for the SerialSoftware object + mySerial.begin(9600); +} + +void loop() { + // Send a byte with the value 45 + mySerial.write(45); + + //Send the string “hello” and return the length of the string. + int bytesSent = mySerial.write(“hello”); +} +``` + +#### See also + +* [SoftwareSerial()](#softwareserial) +* [available()](#available) +* [begin()](#begin) +* [isListening()](#islistening) +* [overflow()](#overflow) +* [peek()](#peek) +* [read()](#read) +* [print()](#print) +* [println()](#println) +* [listen()](#listen) \ No newline at end of file