SoftwareSerial

From chipKIT
Jump to: navigation, search
SoftwareSerial
Quick Look
Hardware (External hardware)
Include SoftwareSerial.h

The SoftwareSerial library allows serial communication using GPIO

Detailed Introduction

The SoftwareSerial library allows you to specify any available set of digital pins to use for serial communication. This library emulates a UART in software.

There are some major limitation involved with using it. You should be aware that currently it always turns all interrupts off when transmitting and receiving a byte. There are speed limitations as well which will depend on the speed of the board you are using. On a 48Mhz board you should limit your baudrate to 115,200 or slower.

Another known issue is that sometimes avilable() will return true, but there will no bytes in the buffer. Not sure why this happens, but it's easy to test again for available() The second time will always be correct.


Introductory Programs

Software Serial Example

This example receives from the hardware serial port and sends to the software serial port and vice versa.

/*
  Software serial multple serial test (For chipKIT)
 
 Receives from the hardware serial, sends to software serial.
 Receives from software serial, sends to hardware serial.
 
 The circuit:
 * RX is digital pin 10 (connect to TX of other device)
 * TX is digital pin 11 (connect to RX of other device)
 
 created back in the mists of time
 modified 25 May 2012
 by Tom Igoe
 based on Mikal Hart's example
 Modified on Aug 31,2015 by Brian Schmalz for chipKIT
 
 This example code is in the public domain.
 
 */
#include <SoftwareSerial.h>
 
SoftwareSerial mySerial(10, 11); // RX, TX
 
void setup()
{
  // Open serial communications and wait for port to open:
  Serial.begin(57600);
  while (!Serial) {
    ;
  }
 
  Serial.println("Goodnight moon!");
 
  // set the data rate for the SoftwareSerial port
  mySerial.begin(115200);
  mySerial.println("Hello, world?");
}
 
void loop() // run over and over
{
  if (mySerial.available())
    Serial.write(mySerial.read());
  if (Serial.available())
    mySerial.write(Serial.read());
}


Full library usage

SoftwareSerial

Parent class: Stream

Constructor

SoftwareSerial(uint8_t receivePin, uint8_t transmitPin, bool inverted_logic = false)

 
SoftwareSerial(uint8_t receivePin, uint8_t transmitPin, bool inverted_logic = false);

Creates a SoftwareSerial object while assigning the RX and TX pins.

Public Functions


begin(long speed)

 
void begin(long speed);

Open the serial port at the specified speed.


void begin(long speed, uint32_t RX_buffer_size)

 
void begin(long speed, uint32_t RX_buffer_size);

Open the serial port at the specified speed and set the RX buffer size. RX buffer size is only used if the RX pin is on a Change Notification pin.


listen()

 
bool listen();

Returns False. Appears to not be implemented fully.


readByte(void)

 
int32_t readByte(void);

This function reads in a byte from an arbitrary GPIO pin. It gets called from one of two places. If the sketch calls read() and the RX pin is not a CN pin, then this function will sit and block until a byte is read in on the RX pin. The other way it gets called is if the RX pin is a CN pin, and a start bit happens, triggering the CN ISR, then this function gets called to read in the byte that just started appearing on the RX pin. It disables interrupts to get accurate timing.


end()

 
void end();

Tell's the serial object that we are done with it and to stop listening.


isListening()

 
bool isListening() { return this == active_object; }

Returns true if the SoftwareSerial object is active.

stopListening()

 
bool stopListening();

Returns False. Appears to not be implemented fully.


overflow()

 
bool overflow() { bool ret = _RX_buffer_overflow; if (ret) _RX_buffer_overflow = false; return ret; }

Tests to see if a software serial buffer overflow has occurred.


available(uint32_t timeout_ms)

int available(uint32_t timeout_ms);

Get the number of bytes available on the RX port.

Virtual Private Functions

available()

virtual int available();

Get the number of bytes available on the RX port.


peek()

virtual int peek();

Returns a character from the receive buffer without removing it from the buffer.


write(uint8_t byte)

virtual size_t write(uint8_t byte);

Prints a charager on the TX pin.

read()

virtual int read();

Returns a charater received on the RX pin.

Conversion Operator

operator bool()

explicit operator bool() { return true; }


External Links