reference

This documentation is automatically generated from the openFrameworks source code using doxygen and refers to the most recent release, version 0.12.0.

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. More...

#include <ofSerial.h>

Public Member Functions

Constructor and Destructor
 ofSerial ()
 
virtual ~ofSerial ()
 
List Devices
void listDevices ()
 This lists all the available serial devices to the console or standard output.
 
 OF_DEPRECATED_MSG ("Use listDevices() instead", void enumerateDevices())
 Prints out the available serial devices.
 
std::vector< ofSerialDeviceInfogetDeviceList ()
 Returns a vector of ofSerialDeviceInfo instances with the devicePath, deviceName, deviceID set.
 
Serial Connection
bool setup ()
 Attempts to setup the first available device at a baud rate of 9600.
 
bool setup (std::string portName, int baudrate)
 Opens the serial port, with the given name and baud rate.
 
bool setup (int deviceNumber, int baudrate)
 Opens the serial port based on the order in which is listed and sets the baud rate.
 
bool isInitialized () const
 
void close ()
 Closes the connection to the serial device.
 
Read Data
int 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:
 
long readBytes (unsigned char *buffer, size_t length)
 Reads 'length' bytes from the connected serial device.
 
long readBytes (char *buffer, size_t length)
 
long readBytes (ofBuffer &buffer, size_t length)
 
int readByte ()
 Reads and returns a single byte from the requested device.
 
Write Data
long writeBytes (const unsigned char *buffer, size_t length)
 This writes bytes into the serial buffer from the buffer pointer passed in.
 
long writeBytes (const char *buffer, size_t length)
 
long writeBytes (const ofBuffer &buffer)
 
bool writeByte (unsigned char singleByte)
 Writes a single byte to the connected serial device.
 
bool writeByte (char singleByte)
 
Clear Data
void flush (bool flushIn=true, bool flushOut=true)
 Clears data from one or both of the serial buffers.
 
void 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.
 

Protected Member Functions

void buildDeviceList ()
 Enumerate all devices attached to a serial port.
 

Protected Attributes

std::string deviceType
 
std::vector< ofSerialDeviceInfodevices
 <
 
bool bHaveEnumeratedDevices
 < This vector stores information about all serial devices found.
 
bool bInited
 <
 
int fd
 <
 
struct termios oldoptions
 This is the set of (current) terminal attributes to be reused when changing a subset of options.
 

Detailed Description

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();
// Open the first device and talk to it at 57600 baud
serial.setup(0, 57600);

Constructor & Destructor Documentation

◆ ofSerial()

ofSerial::ofSerial ( )

Initializes the serial connection, but doesn't actually open the connection to any devices. You'll need to use the setup() method before doing that.

◆ ~ofSerial()

ofSerial::~ofSerial ( )
virtual

Member Function Documentation

◆ 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);
}
map< string, int > device
Definition ofAppEGLWindow.cpp:36

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

◆ buildDeviceList()

void ofSerial::buildDeviceList ( )
protected

Enumerate all devices attached to a serial port.

This method tries to collect basic information about all devices attached to a serial port.

See also
ofSerial::listDevices()
enumerateWin32Ports()

◆ 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.

Parameters
flushInIf true then it clears the incoming data buffer
flushOutIf true then it clears the outgoing data buffer.

◆ getDeviceList()

vector< ofSerialDeviceInfo > ofSerial::getDeviceList ( )

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

◆ isInitialized()

bool ofSerial::isInitialized ( ) const

◆ listDevices()

void ofSerial::listDevices ( )

This lists 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.

◆ OF_DEPRECATED_MSG()

ofSerial::OF_DEPRECATED_MSG ( "Use listDevices() instead"  ,
void   enumerateDevices() 
)

Prints out the available serial devices.

On OSX and Linux it might list something like this:

device 0 - cu.modem
device 1 - cu.USA19H181P1.1

And on Windows, like:

device 0 - COM2
device 1 - COM4

◆ readByte()

int ofSerial::readByte ( )

Reads and returns a single byte from the requested device.

ofSerial mySerial;
mySerial.setup(0, 57600);
int 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);
}
ofSerial provides a cross platform system for interfacing with the serial port. You can choose the po...
Definition ofSerial.h:113
bool setup()
Attempts to setup the first available device at a baud rate of 9600.
Definition ofSerial.cpp:267
int readByte()
Reads and returns a single byte from the requested device.
Definition ofSerial.cpp:575
#define OF_SERIAL_NO_DATA
Definition ofSerial.h:28
#define OF_SERIAL_ERROR
Definition ofSerial.h:29
Returns
The single byte as integer. If there is no data it will return OF_SERIAL_NO_DATA, and on error it returns OF_SERIAL_ERROR

◆ readBytes() [1/3]

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

◆ readBytes() [2/3]

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

◆ readBytes() [3/3]

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

Reads '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" );
break;
} else if ( result == OF_SERIAL_NO_DATA ){
// nothing was read, try again
} else {
// we read some data!
bytesRemaining -= result;
}
}
}
A C++ stream-style logging interface.
Definition ofLog.h:299
@ OF_LOG_ERROR
Definition ofLog.h:120

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() [1/3]

bool ofSerial::setup ( )

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

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

◆ setup() [2/3]

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() [3/3]

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

Opens the serial port, with the given name and baud rate.

On OSX and Linux, it might look like:

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

On Windows, like:

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

◆ writeByte() [1/2]

bool ofSerial::writeByte ( char  singleByte)

◆ writeByte() [2/2]

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 )
ofLog(OF_LOG_ERROR, "Byte was not written to serial port");
bool writeByte(unsigned char singleByte)
Writes a single byte to the connected serial device.
Definition ofSerial.cpp:566

◆ writeBytes() [1/3]

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

◆ writeBytes() [2/3]

long ofSerial::writeBytes ( const ofBuffer buffer)

◆ writeBytes() [3/3]

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);

Member Data Documentation

◆ bHaveEnumeratedDevices

bool ofSerial::bHaveEnumeratedDevices
protected

< This vector stores information about all serial devices found.

◆ bInited

bool ofSerial::bInited
protected

<

Indicate having enumerated devices (serial ports) available.

◆ devices

std::vector<ofSerialDeviceInfo> ofSerial::devices
protected

<

Name of the device on the other end of the serial connection.

◆ deviceType

std::string ofSerial::deviceType
protected

◆ fd

int ofSerial::fd
protected

<

Indicate the successful initialization of the serial connection.

File descriptor for the serial port.

◆ oldoptions

struct termios ofSerial::oldoptions
protected

This is the set of (current) terminal attributes to be reused when changing a subset of options.


The documentation for this class was generated from the following files:
  • /Users/icq4ever/Desktop/oF0120/libs/openFrameworks/communication/ofSerial.h
  • /Users/icq4ever/Desktop/oF0120/libs/openFrameworks/communication/ofSerial.cpp