explain read/write timeout

Troubleshooting.md

@@ -51,7 +51,27 @@ You need to account for this problem when designing your protocol. Some common t
 * Newline-terminated messages: Read until you see a `\n` (or any other "terminal" character).
 
 
-## How to eliminate continuous *D/UsbRequestJNI* messages in logcat output for FTDI devices
+## How to set timeout in `read`/`write` methods?
+
+You should avoid too short timeouts, as they can cause data loss!
+
+* `write` timeout should be significantly larger than the required send time
+* `read` timeout should not be shorter then 200 to 500 milliseconds, if possible use infinite timeout
+
+`read` with infinite timeout blocks until data is available, so it should be avoided in the UI thread, instead use `SerialInputOutputManager` to be notified on new data.
+ 
+`read` with timeout is typically used in the UI thread, if you send a request and know that there is a timely response and the blocking time is acceptable.
+ 
+**Background:**
+
+If you `write` a larger block, e.g. 10kB at 115200 baud, it will take roughly 1 second. USB packets are typically 64 byte long and `bulkTransfer` aborts after the `write` timeout is reached, so with 500 msec timeout roughly 5kB are written, but `bulkTransfer` returns -1 instead of the written size, so there is no chance to resume writing.
+
+If you `read` with very short timeout, e.g. 10 msec, the actual USB transfer might already be finished, but some upper Android layer checks the timeout and discards the already read data. *This data is lost!* 
+ 
+Android is not a realtime OS, e.g. garbage collection can easily take 100 msec. 
+
+
+## How to eliminate continuous *D/UsbRequestJNI* messages in logcat output for FTDI devices?
 
 FTDI devices send the control line status each 16 ms. You can reduce the tracing level with `adb shell setprop log.tag.UsbRequestJNI info`. There have been reports this this does not work on older Android versions.