ofSerial

class methods

ofSerial provides a cross platform system for interfacing with the serial port. You can choose the port and baud rate, and then read and send data. Please note that the port must be set manually in the code, so you should be clear what port your device is on. For example, Arduino users should check the arduino app to see what port their device is on. Alternatively the ofSerial class can attempt to communicate with the first available device it finds.

To start up a serial connection to another device you do the following:


serial.listDevices();
vector <ofSerialDeviceInfo> deviceList = serial.getDeviceList();

int baud = 57600;
serial.setup(0, 57600); //open the first device and talk to it at 57600 baud

available()

int ofSerial::available()

The available method is useful when you want to know how many bytes are available in the serial port. For instance, if you only want to read when there are 8 bytes waiting for you, you would do:

if(device.available() > 8) {
  device.readBytes(buffer, 8);
}

This is useful when you know how long a complete message from a device is going to be.

close()

void ofSerial::close()

Closes the connection to the serial device.

drain()

void ofSerial::drain()

drain is only available on OSX and Linux and is very similar to flush(), but blocks until all the data has been written to or read from the serial port.

flush(...)

void ofSerial::flush(bool flushIn=true, bool flushOut=true)

Clears data from one or both of the serial buffers. Any data in the cleared buffers is discarded. flushIn = true clears the incoming data buffer and fluhOut = true clear the outcoming data buffer.

getDeviceList()

vector< ofSerialDeviceInfo > ofSerial::getDeviceList()

This returns a vector of ofSerialDeviceInfo instances with the devicePath, deviceName, deviceID set.

isInitialized()

bool ofSerial::isInitialized()

listDevices()

void ofSerial::listDevices()

This lists out all the available serial devices to the console or standard output. On OSX and Linux this will return all the devices listed in /dev tty and cu, so you might want to compare it against a list of devices that you're expecting if you want to use it to dynamically connect to a device.

readByte()

int ofSerial::readByte()

Reads and returns a single byte from the requested device. 


ofSerial mySerial;
mySerial.setup(0, 57600);
int myByte = 0;
myByte = mySerial.readByte();
if ( myByte == OF_SERIAL_NO_DATA )
  printf("no data was read");
else if ( myByte == OF_SERIAL_ERROR )
  printf("an error occurred");
else
  printf("myByte is %d", myByte);

readBytes(...)

long ofSerial::readBytes(char *buffer, size_t length)

readBytes(...)

long ofSerial::readBytes(ofBuffer &buffer, size_t length)

readBytes(...)

long ofSerial::readBytes(unsigned char *buffer, size_t length)

Tries to read 'length' bytes from the connected serial device. In some cases it may read less than 'length' bytes, so for reliable reading of >1 bytes of data the return value must be checked against the number of bytes requested, and if fewer bytes than requested were read then the call must be tried again.

This function should only be called when Serial.available() is reporting >0 bytes available.

An example of how to reliably read 8 bytes:


// we want to read 8 bytes
int bytesRequired = 8;
unsigned char bytes[bytesRequired];
int bytesRemaining = bytesRequired;
// loop until we've read everything
while ( bytesRemaining > 0 )
{
  // check for data
  if ( serial.available() > 0 )
  {
    // try to read - note offset into the bytes[] array, this is so
    // that we don't overwrite the bytes we already have
    int bytesArrayOffset = bytesRequired - bytesRemaining;
    int result = serial.readBytes( &bytes[bytesArrayOffset],
      bytesRemaining );

    // check for error code
    if ( result == OF_SERIAL_ERROR )
    {
      // something bad happened
      ofLog( OF_LOG_ERROR, "unrecoverable error reading from serial" );
      // bail out
      break;
    }
    else if ( result == OF_SERIAL_NO_DATA )
    {
      // nothing was read, try again
    }
    else
    {
      // we read some data!
      bytesRemaining -= result;
    }
  }
}

Be aware that the type of your buffer can only be unsigned char. If you're trying to receieve ints or signed chars over a serial connection you'll need to do some bit manipulation to correctly interpret that values.

setup()

bool ofSerial::setup()

Attempts to setup the first available device at a baud rate of 9600. 


ofSerial mySerial;
if( mySerial.setup() ){
    printf("serial is setup!
"); 
}

setup(...)

bool ofSerial::setup(int deviceNumber, int baudrate)

Opens the serial port based on the order in which is listed and sets the baud rate. The code bellow would open the first serial device found by the system:


ofSerial mySerial;
mySerial.setup(0, 9600);

setup(...)

bool ofSerial::setup(string portName, int baudrate)

Opens the serial port, with the given name and baud rate. On mac and linux, it might look like:


ofSerial mySerial;
mySerial.setup("/dev/cu.USA19H181P1.1", 57600);

and on a pc, like:


ofSerial mySerial;
mySerial.setup("COM4", 57600);

writeByte(...)

bool ofSerial::writeByte(char singleByte)

writeByte(...)

bool ofSerial::writeByte(unsigned char singleByte)

Writes a single byte to the connected serial device. Check the return value to be sure the data was written.


ofSerial mySerial;
mySerial.setup(0, 57600);
unsigned char myByte = 225;
bool byteWasWritten = mySerial.writeByte(myByte);
if ( !byteWasWritten )
  printf("byte was not written to serial port");

writeBytes(...)

long ofSerial::writeBytes(const char *buffer, size_t length)

writeBytes(...)

long ofSerial::writeBytes(const ofBuffer &buffer)

writeBytes(...)

long ofSerial::writeBytes(const unsigned char *buffer, size_t length)

This writes bytes into the serial buffer from the buffer pointer passed in:

unsigned char buf[3] = {'o', 'f', '!'};
device.writeBytes(&buf[0], 3);

If you have any doubt about the usage of this module you can ask in the forum.

If you want to contribute better documentation or start documenting this section you can do so here

If you find anything wrong with this docs you can report any error by opening an issue