Description
CAN2SER objects (like Serial) provide the following properties to let the user control its behaviour:
u8_rxStatus – indicates any problems that occurred during data reception
b_O_NONBLOCK – controls if write(), print(), flush() etc. functions return straight away or if they block until all data could be send out
i_BLOCKING_TIMEOUT – time that write-functions actually block if in blocking mode (b_O_NONBLOCK = false)
i_HANDSHAKE_TIMEOUT – time within we expect handshake / alive messages from the peers before we declare it to be lost
Syntax
myExampleSerial.u8_rxStatusmyExampleSerial.b_O_NONBLOCK
myExampleSerial.i_BLOCKING_TIMEOUT
myExampleSerial.i_HANDSHAKE_TIMEOUT
Values
u8_rxStatus: 0x00 after start (begin()) of the communication
bit 0: receive buffer overflow
bit 1: message order error
If u8_rxStatus != 0 then an error occured during data reception. This means that there might be corrupted or incomplete data in the receive buffer. Call end() and begin() in order to restart the communication channel which also synchronises the fresh start with the communication peer.
b_O_NONBLOCK: default is true
If b_O_NONBLOCK = true – write, flush, print etc. calls will not block. Theses functions would only put the write data into the tx-buffer and return. If the tx-buffer is full or the space is not enough for the desired amount of data to be send, then the write() functions behave like if it was in blocking mode.
If b_O_NONBLOCK = false– write() functions will put the data into the tx buffer and will attempt to flush the
buffer (for max. i_BLOCKING_TIMEOUT ms) straight away. If this is still not successful then the write() function returns with the amount of data that could be put into the buffer.
This procedure is common for traditional serial communication interface implementations (e.g. UART). It is advisable to always check the space that is left in the TX buffer before writing to it (availableForWrite()). Applications should always make use of the return value of write() functions to be able to react in cases where not all data could be send. (also see write())
i_BLOCKING_TIMEOUT: default value 20000 (20 sec)
this is the maximal time that blocking function calls (like write(), flush() etc.) will remain in the function before it returns.
The i_BLOCKING_TIMEOUT is a fall back mechanism in situations where e.g. the can-bus is in bus-off or blocked, so that the application is getting a chance to react and does not get stuck forever. This property was introduced because of its importance for remote and unsupervised applications.
i_HANDSHAKE_TIMEOUT – default value 10000 (10 sec)
if our communication partner sends handshakes / alive messages then this would happen in a 500 ms interval. If we don’t see theses messages on the bus for more then i_HANDSHAKE_TIMEOUT milliseconds then we would not longer wait for it.
This means e.g. available() would return false and write() calls would send out the data without considering handshakes from the peer anymore.
Notes and Warnings
The properties above mainly handle the TX side of the communication and the handshake behaviour. The base classes (e.g. Stream, print etc.) also provide the property _timeout, controlled with setTimeout(). This value comes into play when reading from serial buffers (like the CAN2SER object Serial). It is basically the maximal time a read() function would wait for data to be received over the interface.
See also
Example to create a serial link between two devices
Example to create an additional link to the PC
CAN2SER Class
begin()
set_handshake()
Handshaking