Handshaking – di-ce.de

Description

Handshaking ensures that two communication partners have knowledge about their partners status such as
– is the partner present
– is the partner ready to receive data or not (e.g. if its receive buffer is full)
The CAN2SER protocol implementation allows to use it by setting the handshake parameter during creation of the instance (call of the constructor). If handshake is selected then our instance will be sending out handshake messages (500 ms intervals). It does not yet has any meaning whatsoever how the communication partner ‘behaves’. The partner may choose not to send handshake which would be fine too. The default object’s Serial communication to the PC is an example of a typical ‘unbalanced’ handshaking setup. The PC sends out handshake signals by default to signal to the device that the PC is present and ready to receive data.
On the other hand the default setting of the Serial object of the device is handshaking switched off. This means that the device will not send out any handshake messages to the PC. These are only the default settings for Serial and can be changed by the application (and PC) during its run time. For example the ‘file transfer’ library would enable the handshaking on the Serial link to ensure that no buffer overrun can happen on either side.

Control our handshaking with the following functions and settings:

CAN2SER constructor – sets handshake when creating the CAN2SER instance
set_handshake() – switches our handshake on/off during run time

Work with the partners handshaking:

bool() – checks the presents of handshake messages from the peer
i_HANDSHAKE_TIMEOUT – is the time [ms] to understand that the handshaking partner is not available (default 10000 ms)

Example Code

void setup()
{  
  // Wait for the PC can2ser-monitor to send handshakes
  while(!Serial) {;}
  Serial.println("Hello. Here is the device, I received your handshaking.");
  Serial.i_HANDSHAKE_TIMEOUT = 5000; // interval that we expect handshake/alive mesg.
}
void loop () 
{
  if(Serial) // LED indicates the PC handshake is OK
    digitalWrite(LED_BUILTIN, HIGH);
  else       // LED indicates the PC handshake got lost (no handshake mesg. 
             // received within the last i_HANDSHAKE_TIMEOUT milliseconds)
    digitalWrite(LED_BUILTIN, LOW);
}

Read / write, buffers and handshaking

The most important reason for using handshaking is to synchronise the data transmission between partners which ensures that no buffer overrun occurs and that no data would get lost.
The CAN2SER implementation as well as the CAN bus core code employs buffers to receive and to send the serial data. In situations that one communication partner sends data at a faster rate then the other side can process it, the handshaking mechanism makes sure to signal the sending partner to pause the transmission. This is all handled within the library. Still the user should use the provided measures for serial communication interfaces (e.g. UART etc.)
– available() – is the communication partner present (did we receive handshake / alive mesg. in time)
– availableForWrite() – space left in the send buffer
– peek() – get one byte from the receive buffer without removing it from the buffer
– flush() – sends all data in the send buffer before it returns (or i_BLOCKING_TIMEOUT expires)
– read() / write() – read / write from / to the buffers (consider the return value!)
– u8_rxStatus – indicates a receive buffer overflow or a corrupted message order during reception
– b_O_NONBLOCK – if true (default) = not blocking: Means writes() return straight a way (-> check write() return values)
– i_BLOCKING_TIMEOUT – time [ms] after which a ‘blocking’ read(), write() or flush() would return

Further details can also be found in the Arduino reference for the Serial interface.

Notes

If you plan to use your application also in situations without a peer (e.g. without PC can2ser monitor connected), then make sure that your sketch does not get stuck due to not receiving any handshake messages from e.g. the PC-can2ser monitor.

The CAN communication is handled by the core code which needs to regularly been given processing time. This happens during ‘delay(), ‘yield()’ and at the end of a ‘loop()’ iteration. So always use one of these functions when in a for or while loop.

while(1);               don't
while(1) { yield(); }   do

Note: As a fall back, the CAN2SER class has the i_HANDSHAKE_TIMEOUT property which defines the time that may pass waiting for handshake messages from the peer. After this time passed will we resume the communication without considering handshakes from the peer (anymore).

Compatibility

At least during development most Arduino sketches use Serial to send and receive text to the user (PC). ‘Normal’ Arduinos are using a USB-Serial converter on their boards. Since the PC needs time to enumerate the USB device, the sketch would wait for this to happen by making use of the bool method. For the CAN2SER object this is similar. It gives the can2ser monitor time to be started so that the user never misses out any data from the device. This the reason why the can2ser monitor starts with sending ‘handshake’ messages by default.

Description

Example Code

Read / write, buffers and handshaking

Notes

Compatibility

See also