# PIP: PISerial Class Reference

PISerial Class Reference

Serial device. More...

Inheritance diagram for PISerial:
[legend]

## Public Types

enum | Parameters { ParityControl = 0x1, ParityOdd = 0x2, TwoStopBits = 0x4 }
| Parameters of PISerial. More...

enum

Speed {
S50 = 50, S75 = 75, S110 = 110, S300 = 300,
S600 = 600, S1200 = 1200, S2400 = 2400, S4800 = 4800,
S9600 = 9600, S19200 = 19200, S38400 = 38400, S57600 = 57600,
S115200 = 115200, S230400 = 230400, S460800 = 460800, S500000 = 500000,
S576000 = 576000, S921600 = 921600, S1000000 = 1000000, S1152000 = 1152000,
S1500000 = 1500000, S2000000 = 2000000, S2500000 = 2500000, S3000000 = 3000000,
S3500000 = 3500000, S4000000 = 4000000
}

| Speed of PISerial. More...
Public Types inherited from PIIODevice
enum | DeviceMode { ReadOnly = 0x01, WriteOnly = 0x02, ReadWrite = 0x03 }
| Open modes for PIIODevice. More...
Public Types inherited from PIThread
enum | Priority { piLowerst, piLow, piNormal, piHigh, piHighest }
| Priority of thread. More...

## Public Member Functions

| PISerial ()
| Contructs an empty PISerial.
| PISerial (const PIString &device, PISerial::Speed speed=S115200, PIFlags< PISerial::Parameters > params=0)
| Contructs PISerial with device name "device", speed "speed" and parameters "params".
void | setSpeed (PISerial::Speed speed)
| Set both input and output speed to "speed".
void | setOutSpeed (PISerial::Speed speed)
| Set output speed to "speed".
void | setInSpeed (PISerial::Speed speed)
| Set input speed to "speed".
void | setDevice (const PIString &dev)
| Set device name to "dev".
void | setParameters (PIFlags< PISerial::Parameters > parameters_)
| Set parameters to "parameters_".
void | setParameter (PISerial::Parameters parameter, bool on=true)
| Set parameter "parameter" to "on" state.
bool | isParameterSet (PISerial::Parameters parameter) const
| Returns if parameter "parameter" is set.
PIFlags< PISerial::Parameters > | parameters () const
| Returns parameters.
void | setDataBitsCount (int bits)
| Set data bits count. Valid range is from 5 to 8, befault is 8.
int | dataBitsCount () const
| Returns data bits count.
bool | setPin (int number, bool on)
| Set pin number "number" to logic level "on". Valid numbers are 4 (DTR) and 7 (RTS)
bool | isPin (int number) const
| Returns pin number "number" logic level. Valid numbers range is from 1 to 9.
void | setReadIsBlocking (bool yes)
| Set read is blocking for function read(void * read_to, int max_size)
PIString | device () const
| Returns device name.
PISerial::Speed | outSpeed () const
| Returns output speed.
PISerial::Speed | inSpeed () const
| Returns input speed.
void | flush ()
| Discard all buffered input and output data.
int | read (void *read_to, int max_size)
| Basic read function. More...
bool | read (void *read_to, int max_size, double timeout_ms)
| Advanced read function. More...
PIString | read (int size=-1, double timeout_ms=1000.)
| Advanced read function. More...
PIByteArray | readData (int size=-1, double timeout_ms=1000.)
| Advanced read function. More...
int | write (const void *data, int max_size, bool wait=false)
| Write to device data "data" with maximum size "max_size" and wait for data written if "wait" is true. More...
bool | send (const void *data, int size, bool wait=false)
| Write to device data "data" with maximum size "size" and wait for data written if "wait" is true. More...
bool | send (const PIString &data, bool wait=false)
| Write to device string "data" and wait for data written if "wait" is true. More...
bool | send (const PIByteArray &data, bool wait=false)
| Write to device byte array "data" and wait for data written if "wait" is true. More...
PIString | constructFullPath () const
| Reimplement to construct full unambiguous string, describes this device, default returns fullPathPrefix() + "://" + path()
Public Member Functions inherited from PIIODevice
| PIIODevice ()
| Constructs a empty PIIODevice.
| PIIODevice (const PIString &path, DeviceMode mode=ReadWrite)
| Constructs a PIIODevice with path and mode. More...
DeviceMode | mode () const
| Current open mode of device.
void | setMode (DeviceMode m)
| Set open mode of device.
PIString | path () const
| Current path of device.
void | setPath (const PIString &path)
| Set path of device.
bool | isReadable () const
| Return true if mode is ReadOnly or ReadWrite.
bool | isWriteable () const
| Return true if mode is WriteOnly or ReadWrite.
bool | isOpened () const
| Return true if device is successfully opened.
bool | isClosed () const
| Return true if device is closed.
virtual bool | canRead () const
| Return true if device can read now.
virtual bool | canWrite () const
| Return true if device can write now.
void | setReopenEnabled (bool yes=true)
| Set execution of open enabled while threaded read on closed device.
void | setReopenTimeout (int msecs)
| Set timeout in milliseconds between open tryings if reopen is enabled.
bool | isReopenEnabled () const
| Return reopen enable.
int | reopenTimeout ()
| Return reopen timeout.
void | setThreadedReadSlot (ReadRetFunc func)
| Set "threaded read slot". More...
void | setThreadedReadData (void *d)
| Set custom data that will be passed to "threaded read slot".
void | setThreadedReadBufferSize (int new_size)
| Set size of threaded read buffer. More...
int | threadedReadBufferSize () const
| Return size of threaded read buffer.
const uchar * | threadedReadBuffer () const
| Return content of threaded read buffer.
void * | threadedReadData () const
| Return custom data that will be passed to "threaded read slot".
bool | isThreadedRead () const
| Return true if threaded read is started.
void | startThreadedRead ()
| Start threaded read.
void | startThreadedRead (ReadRetFunc func)
| Start threaded read and assign "threaded read slot" to "func".
void | stopThreadedRead ()
| Stop threaded read.
bool | isThreadedWrite () const
| Return true if threaded write is started.
void | startThreadedWrite ()
| Start threaded write.
void | stopThreadedWrite ()
| Stop threaded write.
void | clearThreadedWriteQueue ()
| Clear threaded write task queue.
void | start ()
| Start both threaded read and threaded write.
void | stop (bool wait=false)
| Stop both threaded read and threaded write and if "wait" block until both threads are stop.
PIByteArray | read (int max_size)
| Read from device maximum "max_size" bytes and return them as PIByteArray.
PIByteArray | readForTime (double timeout_ms)
| Read from device for "timeout_ms" milliseconds and return readed data as PIByteArray. Timeout should to be greater than 0.
int | write (const PIByteArray &data)
| Write "data" to device.
ullong | writeThreaded (const void *data, int max_size)
| Add task to threaded write queue and return task ID.
ullong | writeThreaded (const PIByteArray &data)
| Add task to threaded write queue and return task ID.
bool | configure (const PIString &config_file, const PIString &section, bool parent_section=false)
| Configure device from section "section" of file "config_file", if "parent_section" parent section also will be read.
bool | open ()
| Open device.
bool | open (const PIString &_path)
| Open device with path "path".
bool | open (const DeviceMode &_mode)
| Open device with mode "mode".
bool | open (const PIString &_path, const DeviceMode &_mode)
| Open device with path "path" and mode "mode".
bool | close ()
| Close device.
bool | initialize ()
| Initialize device.
void | opened ()
| Raise if succesfull open.
void | closed ()
| Raise if succesfull close.
void | threadedReadEvent (uchar *readed, int size)
| Raise if read thread succesfull read some data.
void | threadedWriteEvent (ullong id, int written_size)
| Raise if write thread succesfull write some data of task with ID "id".
Public Member Functions inherited from PIThread
| PIThread (void *data, ThreadFunc func, bool startNow=false, int loop_delay=-1)
| Contructs thread with custom data "data", external function "func" and main loop delay "loop_delay".
| PIThread (bool startNow=false, int loop_delay=-1)
| Contructs thread with main loop delay "loop_delay".
void | setData (void *d)
| Set common data passed to external function.
void | setSlot (ThreadFunc func)
| Set external function that will be executed after every run()
void | setPriority (PIThread::Priority prior)
| Set priority of thread.
void * | data () const
| Returns common data passed to external function.
PIThread::Priority | priority () const
| Return priority of thread.
bool | isRunning () const
| Return `true` if thread is running.
void | needLockRun (bool need)
| Set necessity of lock every run with internal mutex.
PIMutex & | mutex ()
| Return internal mutex.
bool | start (int timer_delay)
| Start thread. More...
bool | start (ThreadFunc func, int timer_delay)
| Start thread. More...
bool | startOnce ()
| Start thread without internal loop. More...
bool | startOnce (ThreadFunc func)
| Start thread without internal loop. More...
void | stop (bool wait)
| Stop thread. More...
void | terminate ()
| Strongly stop thread. More...
bool | waitForStart (int timeout_msecs)
| Wait for thread start. More...
bool | waitForFinish (int timeout_msecs)
| Wait for thread finish. More...
void | lock ()
| Lock internal mutex.
void | unlock ()
| Unlock internal mutex.
void | started ()
| Raise on thread start.
void | stopped ()
| Raise on thread stop.
Public Member Functions inherited from PIObject
| PIObject (const PIString &name=PIString())
| Contructs PIObject with name "name".
PIString | name () const
| Returns object name.
virtual const char * | className () const
| Returns object class name.
virtual const char * | superClassName () const
| Returns object superclass name.
bool | debug () const
| Return if debug of this object is active.
void | setName (const PIString &name)
| Set object name.
void | setDebug (bool debug)
| Set object debug active.
const PIMap< PIString, PIVariant > & | properties () const
| Returns properties of the object.
int | propertiesCount () const
| Returns properties count of the object.
PIVariant | property (const PIString &name) const
| Returns property with name "name".
void | setProperty (const PIString &name, const PIVariant &value)
| Set property with name "name" to "value". If there is no such property in object it will be added.
bool | isPropertyExists (const PIString &name) const
| Returns if property with name "name" exists.

## Static Public Member Functions

static PIVector< int > | availableSpeeds ()
| Returns all available speeds for serial devices.
static PIStringList | availableDevices (bool test=false)
| Returns all available system devices. If "test" each device will be tried to open.
Static Public Member Functions inherited from PIIODevice
static PIIODevice * | createFromFullPath (const PIString &full_path)
| Try to determine suitable device, create new one, configure it with configureFromFullPath() and returns it. More...
Static Public Member Functions inherited from PIObject
static void | piDisconnect (PIObject *src, const PIString &sig)
| Disconnect object "src" from all connections with event name "sig".
static void | piDisconnect (PIObject *src)
| Disconnect object "src" from all connections, i.e. all connections where object "src" is emitter.
static PIObject * | findByName (const PIString &name)
| Returns PIObject* with name "name" or 0, if there is no object found.

## Protected Member Functions

PIString | fullPathPrefix () const
| Reimplement to construct full unambiguous string prefix. Creating devices by unambiguous string.
void | configureFromFullPath (const PIString &full_path)
| Reimplement to configure your device with parameters of full unambiguous string. Default implementation does nothing.
bool | configureDevice (const void *e_main, const void *e_parent=0)
| Reimplement to configure device from entries "e_main" and "e_parent", cast arguments to PIConfig::Entry*.
int | write (const void *data, int max_size)
| Reimplement this function to write to your device.
virtual void | received (const void *data, int size)
| Executes when any read function was successful. Default implementation does nothing.
bool | openDevice ()
| Reimplement to open device, return value will be set to "opened_" variable.
bool | closeDevice ()
| Reimplement to close device, inverse return value will be set to "opened_" variable.
Protected Member Functions inherited from PIIODevice
virtual bool | init ()
| Function executed before first openDevice() or from constructor.
virtual bool | threadedRead (uchar *readed, int size)
| Function executed when thread read some data, default implementation execute external slot "ret_func_".
Protected Member Functions inherited from PIObject
PIObject * | emitter () const
| Returns PIObject* which has raised an event. This value is correct only in definition of some event handler.
virtual void | propertyChanged (const PIString &name)
| Virtual function executes after property with name "name" has been changed.
void | deleted ()
| Raise before object delete. More...

## Configurable parameters

string | device
| device, default ""
int | speed
| input/output speed, default 115200
int | dataBitsCount
| dataBitsCount, default 8
bool | parityControl
| parityControl, default false
bool | parityOdd
| parityOdd, default false
bool | twoStopBits
| twoStopBits, default false

## Additional Inherited Members

Public Attributes inherited from PIIODevice
bool | reopenEnabled
| setReopenEnabled, default "true"
int | reopenTimeout
| setReopenTimeout in ms, default 1000
int | threadedReadBufferSize
| setThreadedReadBufferSize in bytes, default 4096
Related Functions inherited from PIIODevice
template<typename T >
T | readDeviceSetting (const PIString &name, const T &def, const PIConfig::Entry *em, const PIConfig::Entry *ep)
| Service function. useful for configuring devices. More...
#define | REGISTER_DEVICE(class)
| Use this macro to enable automatic creation instances of your class with createFromFullPath() function.
#define | PIIODEVICE(class)
| Use this macro instead of PIOBJECT when describe your own PIIODevice.
Related Functions inherited from PIObject
#define | piCoutObj
| Macro used for conditional (piDebug and PIObject::debug()) output to PICout for subclasses of PIObject.
#define | PIOBJECT(name)
| you should use this macro after class declaration to use EVENT and EVENT_HANDLER and correct piCoutObj output
#define | PIOBJECT_SUBCLASS(name, parent)
| you should use this macro after class declaration to use EVENT and EVENT_HANDLER of parent class
#define | EVENT_HANDLER0(ret, name) ret name()
| declare event handler "event" with name "name" and return type "ret", ret name()
#define | EVENT_HANDLER1(ret, name, type0, var0) ret name(type0 var0)
| declare event handler "event" with name "name" and return type "ret", ret name(type0 var0)
#define | EVENT_HANDLER2(ret, name, type0, var0, type1, var1) ret name(type0 var0, type1 var1)
| declare event handler "event" with name "name" and return type "ret", ret name(type0 var0, type1 var1)
#define | EVENT_HANDLER3(ret, name, type0, var0, type1, var1, type2, var2) ret name(type0 var0, type1 var1, type2 var2)
| declare event handler "event" with name "name" and return type "ret", ret name(type0 var0, type1 var1, type2 var2)
#define | EVENT_HANDLER4(ret, name, type0, var0, type1, var1, type2, var2, type3, var3) ret name(type0 var0, type1 var1, type2 var2, type3 var3)
| declare event handler "event" with name "name" and return type "ret", ret name(type0 var0, type1 var1, type2 var2, type3 var3)
#define | EVENT_HANDLER EVENT_HANDLER0
| EVENT_HANDLER is synonym of EVENT_HANDLER0.
#define | EVENT_VHANDLER0(ret, name) virtual ret name()
| declare virtual event handler "event" with name "name" and return type "ret", virtual ret name()
#define | EVENT_VHANDLER1(ret, name, type0, var0) virtual ret name(type0 var0)
| declare virtual event handler "event" with name "name" and return type "ret", virtual ret name(type0 var0)
#define | EVENT_VHANDLER2(ret, name, type0, var0, type1, var1) virtual ret name(type0 var0, type1 var1)
| declare virtual event handler "event" with name "name" and return type "ret", virtual ret name(type0 var0, type1 var1)
#define | EVENT_VHANDLER3(ret, name, type0, var0, type1, var1, type2, var2) virtual ret name(type0 var0, type1 var1, type2 var2)
| declare virtual event handler "event" with name "name" and return type "ret", virtual ret name(type0 var0, type1 var1, type2 var2)
#define | EVENT_VHANDLER4(ret, name, type0, var0, type1, var1, type2, var2, type3, var3) virtual ret name(type0 var0, type1 var1, type2 var2, type3 var3)
| declare virtual event handler "event" with name "name" and return type "ret", virtual ret name(type0 var0, type1 var1, type2 var2, type3 var3)
#define | EVENT_VHANDLER EVENT_VHANDLER0
| EVENT_VHANDLER is synonym of EVENT_VHANDLER0.
#define | EVENT0(name) void name();
| declare event "event" with name "name", void name();
#define | EVENT1(name, type0, var0) void name(type0 var0);
| declare event "event" with name "name", void name(type0 var0);
#define | EVENT2(name, type0, var0, type1, var1) void name(type0 var0, type1 var1);
| declare event "event" with name "name", void name(type0 var0, type1 var1);
#define | EVENT3(name, type0, var0, type1, var1, type2, var2) void name(type0 var0, type1 var1, type2 var2);
| declare event "event" with name "name", void name(type0 var0, type1 var1, type2 var2);
#define | EVENT4(name, type0, var0, type1, var1, type2, var2, type3, var3) void name(type0 var0, type1 var1, type2 var2, type3 var3);
| declare event "event" with name "name", void name(type0 var0, type1 var1, type2 var2, type3 var3);
#define | EVENT EVENT0
| EVENT is synonym of EVENT0.
#define | CONNECTU(src, event, dest, handler)
| connect event "event" from object "src" to event handler "handler". "Event" and "handler" must has equal argument lists.
#define | CONNECT0(ret, src, event, dest, handler)
| connect event "event" from object "src" to event handler "handler" with return type "ret" from object "dest" with check of event and handler exists
#define | CONNECT1(ret, type0, src, event, dest, handler)
| connect event "event" from object "src" to event handler "handler" with return type "ret" from object "dest" with check of event and handler exists
#define | CONNECT2(ret, type0, type1, src, event, dest, handler)
| connect event "event" from object "src" to event handler "handler" with return type "ret" from object "dest" with check of event and handler exists
#define | CONNECT3(ret, type0, type1, type2, src, event, dest, handler)
| connect event "event" from object "src" to event handler "handler" with return type "ret" from object "dest" with check of event and handler exists
#define | CONNECT4(ret, type0, type1, type2, type3, src, event, dest, handler)
| connect event "event" from object "src" to event handler "handler" with return type "ret" from object "dest" with check of event and handler exists
#define | CONNECT CONNECT0
| CONNECT is synonym of CONNECT0.
#define | WEAK_CONNECT0(ret, src, event, dest, handler)
| connect event "event" from object "src" to event handler "handler" with return type "ret" from object "dest" without check of event exists
#define | WEAK_CONNECT1(ret, type0, src, event, dest, handler)
| connect event "event" from object "src" to event handler "handler" with return type "ret" from object "dest" without check of event exists
#define | WEAK_CONNECT2(ret, type0, type1, src, event, dest, handler)
| connect event "event" from object "src" to event handler "handler" with return type "ret" from object "dest" without check of event exists
#define | WEAK_CONNECT3(ret, type0, type1, type2, src, event, dest, handler)
| connect event "event" from object "src" to event handler "handler" with return type "ret" from object "dest" without check of event exists
#define | WEAK_CONNECT4(ret, type0, type1, type2, type3, src, event, dest, handler)
| connect event "event" from object "src" to event handler "handler" with return type "ret" from object "dest" without check of event exists
#define | WEAK_CONNECT WEAK_CONNECT0
| WEAK_CONNECT is synonym of WEAK_CONNECT0.
#define | DISCONNECT0(ret, src, event, dest, handler)
| piDisconnect event "event" from object "src" from event handler "handler" with return type "ret" from object "dest"
#define | DISCONNECT1(ret, type0, src, event, dest, handler)
| piDisconnect event "event" from object "src" from event handler "handler" with return type "ret" from object "dest"
#define | DISCONNECT2(ret, type0, type1, src, event, dest, handler)
| piDisconnect event "event" from object "src" from event handler "handler" with return type "ret" from object "dest"
#define | DISCONNECT3(ret, type0, type1, type2, src, event, dest, handler)
| piDisconnect event "event" from object "src" from event handler "handler" with return type "ret" from object "dest"
#define | DISCONNECT4(ret, type0, type1, type2, type3, src, event, dest, handler)
| piDisconnect event "event" from object "src" from event handler "handler" with return type "ret" from object "dest"
#define | DISCONNECT DISCONNECT0
| DISCONNECT is synonym of DISCONNECT0.
#define | HANDLER(handler)
| Returns pointer to events handler "handler".

## Detailed Description

Serial device.

# Synopsis

This class provide access to serial device, e.g. COM port. It can read, write, wait for write. There are several read and write functions.

## Member Enumeration Documentation

enum PISerial::Parameters

Parameters of PISerial.

Enumerator
ParityControl | Enable parity check and generate
ParityOdd | Parity is odd instead of even
TwoStopBits | Two stop bits instead of one

enum PISerial::Speed

Speed of PISerial.

Enumerator
S50 | 50 baud
S75 | 75 baud
S110 | 110 baud
S300 | 300 baud
S600 | 600 baud
S1200 | 1200 baud
S2400 | 2400 baud
S4800 | 4800 baud
S9600 | 9600 baud
S19200 | 19200 baud
S38400 | 38400 baud
S57600 | 57600 baud
S115200 | 115200 baud
S230400 | 230400 baud
S460800 | 460800 baud
S500000 | 500000 baud
S576000 | 576000 baud
S921600 | 921600 baud
S1000000 | 1000000 baud
S1152000 | 1152000 baud
S1500000 | 1500000 baud
S2000000 | 2000000 baud
S2500000 | 2500000 baud
S3000000 | 3000000 baud
S3500000 | 3500000 baud
S4000000 | 4000000 baud

## Member Function Documentation

int PISerial::read | ( | void * | read_to,
|  | int | max_size
| ) |  |

virtual

Basic read function.

Read to pointer "read_to" no more than "max_size". If read is set to blocking this function will be wait at least one byte.

Returns
  Readed bytes count

See also
  readData()

Reimplemented from PIIODevice.

bool PISerial::read | ( | void * | data,
|  | int | size,
|  | double | timeout_ms
| ) |  |

Advanced read function.

Read to pointer "read_to" no more than "max_size" and no longer than "timeout_ms" milliseconds. If "timeout_ms" < 0 function will be wait forever until "max_size" will be readed. If size <= 0 function immediate returns false. For read data with unknown size use function readData().

Returns
  True if readed bytes count = "max_size", else false

See also
  readData()

PIString PISerial::read | ( | int | size = `-1`,
|  | double | timeout_ms = `1000.`
| ) |  |

Advanced read function.

Read all or no more than "size" and no longer than "timeout_ms" milliseconds. If "timeout_ms" < 0 function will be wait forever until "size" will be readed. If "size" <= 0 function will be read all until "timeout_ms" elaped.
If size <= 0 and "timeout_ms" <= 0 function immediate returns empty string.
This function similar to readData() but returns data as string.

See also
  readData()

PIByteArray PISerial::readData | ( | int | size = `-1`,
|  | double | timeout_ms = `1000.`
| ) |  |

Advanced read function.

Read all or no more than "size" and no longer than "timeout_ms" milliseconds. If "timeout_ms" < 0 function will be wait forever until "size" will be readed. If "size" <= 0 function will be read all until "timeout_ms" elaped.
If size <= 0 and "timeout_ms" <= 0 function immediate returns empty byte array.
This function similar to read() but returns data as byte array.

See also
  read()

int PISerial::write | ( | const void * | data,
|  | int | max_size,
|  | bool | wait = `false`
| ) |  |

Write to device data "data" with maximum size "max_size" and wait for data written if "wait" is true.

Returns
  sended bytes count

bool PISerial::send | ( | const void * | data,
|  | int | size,
|  | bool | wait = `false`
| ) |  |

inline

Write to device data "data" with maximum size "size" and wait for data written if "wait" is true.

Returns
  true if sended bytes count = "size"

bool PISerial::send | ( | const PIString & | data,
|  | bool | wait = `false`
| ) |  |

inline

Write to device string "data" and wait for data written if "wait" is true.

Returns
  true if sended bytes count = size of string

bool PISerial::send | ( | const PIByteArray & | data,
|  | bool | wait = `false`
| ) |  |

inline

Write to device byte array "data" and wait for data written if "wait" is true.

Returns
  true if sended bytes count = size of string