Bootstrap (or resurrect) a cross-platform port-to-port serial transmit/receive test application

[jerrywrice]

I'll review existing examples and formulate/generate a two port (cross connected) send/receive test application for cross-platform usage. Initial goal is to allow assessment of existing functional behavior and timing, in order to assist in planning issue fix priorities and future evolution of the library. Goal is to have something to share early the week of June 12th.

[sirhcel]

I worked on examples/hardware_check.rs a while ago but stalled due to lack of time.

[jerrywrice]

Sirhcel,

Based on your feedback, I understand that the immediate plan for crate 'serialport-rs' is to cleanup existing examples and library logic so they function robustly, but without significantly modifying existing example functionality.

I'll proceed to generate a new test example application (named 'bulk_xfr.rs') which transmits a specified quantity of sequenced serial data, and where the receiver verifies all transmitted data in-fact is received correctly. The 'bulk_xfr' example test will require running two instances, with command line arguments that indicate if the instance is the transmitter (XMT) or the receiver (RCV).

When each instance is launched and before their full transfer begins, the XMT and RCV instances shall perform an initial pre-defined bi-directional handshake sequence (protocol) in which the RCV and XMT instances confirm they are ready to proceed with the initial test buffer transfer. The startup handshake sequence permits the XMT and RCV example instances to be launched in either order, with some reasonable time-period in seconds permitted after the first instance launches until the second instance launches. If this initial startup handshake is unsuccessful for any reason, then the instances report an informative error message and exit.

The core bulk transfer data pattern will be an auto-generated byte stream consisting of an ascending binary byte-sequence repeated cycling between 0 and 255 which satisfies the user designated transfer length. The receiver is provided the designated transfer length and repeat count values by the transmitter instance during the launch-time initial handshake sequence. Details of this handshake shall be documented in the example source code.

Both port flow control settings will default to 'None'.
Both port read timeout's will be set as 'TBD'.

There will be command line arguments which specify:

1. The transfer port name (for example --PORT="/dev/ttyUSB1"),
2. The current role, either (--role="XMT") or (--role="RCV"),
3. The number of sequenced value bytes for the transmit (for example --XFRLEN="50_000"),
4. The baud rate (for example --BAUD="250_000").
5. An optional repeat receive count value (for example --REPEAT="10"). Default repeat value will be 1.

This test example may involve two 'bulk_xfr' instances (and serial ports) executing on the same (platform) computer system, or otherwise a pair of instances each executing on distinct computer systems with either the same or different OSes.

Once I code and verify the new example with a connected Windows and Linux test system, we can then request someone with a Mac verify it as well.

Additional functionality, such as timeout testing and flow-control. could be added to this or another new example once the core ''bulk_xfr.rs' example is working as described above.

Does this sound reasonable - your thoughts?

[sirhcel]

Further reading: We had some serious amount of discussion in #107

[jerrywrice]

I've generated and tested a serialport crate stand-alone test and characterization application, named 'receive_timing_info', which characterizes the write() and read() trait methods timing under various operating conditions. I've built and tested it on both Windows 10 and Ubuntu 22.04 LTS, using two FTDI USB serial port cables. The test currently accepts ten (10) command line arguments which allows multiple testing scenarios. I've written a corresponding support document "SerialPort_rs Receive_Timing_Info Test Description.pdf" which details this. I've also generated and tested, the test application's source file, named 'receive_timing_info.rs'. The document describes building the test application from the serialport-rs crate's examples folder with cargo build. This test application saves all of its run-time metrics data in a log-file, since there is impractical to display it all on the console (and this would significantly slow down the run-time execution. Finally, since developing this test I've used it to characterize the Windows write() and read() behavior, especially its blocking and time-out characteristics, and have identified some clear differences between the Windows and Linux crate behavior, which is described in the document. I've also generated and tested a simple patch to the crates' Windows version of 'set_timeout()' which eliminates a fairly important problem with the current windows timeout logic. I would like to cover this (in summary) at the planned August 17 crate planning meeting.