flow control

FAQ.mediawiki

@@ -129,7 +129,7 @@ USB data transfers have a fixed packet size which is 64 for most devices. You ca
 
 A smaller buffer size is ok, as long as the received messages fits into the buffer. If it doesn't fit into the buffer, <code>read</code> returns an empty result. Due to poor error propagation in Android USB code, this cannot be distinguished from timeout or real communication errors.
 
-A larger buffer size can make your app lagging. In particular FTDI devices tend to queue data until the buffer is completely filled on continous transfer at higher baud rates. This can be mitigated by choosing appropriate buffer size and setting the latency timer as also recommended by [http://www.ftdichip.com/Support/Documents/AppNotes/AN232B-04_DataLatencyFlow.pdf FTDI].
+A larger buffer size can make your app lagging. In particular FTDI devices tend to queue data until the buffer is completely filled on continuous transfer at higher baud rates. This can be mitigated by choosing appropriate buffer size and setting the latency timer as also recommended by [http://www.ftdichip.com/Support/Documents/AppNotes/AN232B-04_DataLatencyFlow.pdf FTDI].
 
 When using smaller buffer sizes with FTDI devices, you have to take into account that each response starts with 2 header bytes.
 The header bytes will be stripped from the final result. 
@@ -163,6 +163,25 @@ If the send buffer on the usb device is not full, the write call returns after p
 Waiting for write completion is typically done with application specific protocols, like request-response pattern.
 
 
+== How to use flow control with control lines RTS/CTS or DTR/DSR ==
+
+When <code>getCTS()</code> or <code>getDSR()</code> return <code>false</code> you can continue writing until the send buffer is full, then <code>write()</code> will return a <code>SerialTimeoutException</code>, but typically it's better to immediately stop writing.
+
+If your App is not reading data fast enough, the RTS or DTR lines are reset when the receive buffer is over 50~80% full.
+
+== How to use flow control with XON/XOFF characters ==
+
+Some devices return XON/XOFF state with <code>getXON()</code> method, others return XON/XOFF characters inline in received data. The supported variant is reflected by different <code>FlowControl</code> modes. The inline data can be filtered out with <code>XonXoffFilter</code> helper class, which provides a <code>getXON()</code> method similar to the <code>UsbSerialPort</code> classes.
+
+When the appropriate <code>getXON()</code> method returns <code>false</code> you can continue writing until the send buffer is full, then <code>write()</code> will return a <code>SerialTimeoutException</code>, but typically it's better to immediately stop writing.
+
+If your App is not reading data fast enough, <code>CHAR_XOFF</code> is send when the receive buffer gets 50~80% full, and <code>CHAR_XON</code> when below that threshold.
+
+== How to use flow control with unsupported devices ==
+
+Some devices do not have hardware support for flow control. You can check the control line or XON/XOFF characters yourself and can stop writing, but this could still cause data loss if not done sufficiently early.
+
+
 == Does this library work with Unity/Ionic/Cordova/Xamarin/App Inventor/... development framework? ==
 
 If your framework can import Java .jar files, look [[Build-Variants#Jar|here]] for instructions about creating a .jar file. 
@@ -196,18 +215,13 @@ Some Features are not supported by all drivers / devices
 |-
 | set/get flow control lines RTS, CTS, DTR, DSR, CD, RI || 🟢 || 🟢 || 🟢 || 🟢 || 🟡 only output lines RTS, DTR
 |-
+| flow control with control lines || 🟢 RTS/CTS, DTR/DSR || n.a. || 🟢 RTS/CTS, DTR/DSR || 🟢 RTS/CTS || n.a. 
+|-
+| flow control with XON/XOFF characters || 🟢 || n.a. || 🟢 || 🟢  || n.a. 
+|-
 | <code>purgeHwBuffers</code> || 🟢 || 🔴 || 🟢 || 🟢 || 🟢
 |-
 | multi port devices || 🟢 || n.a. || 🟢 ||n.a. || 🟢
 |-
 | device specific methods || <code>get/setLatencyTimer</code> || - || - || - || -
 |}
-
-
-Some Features are not implemented (yet)
-
-{|
-! Feature !! Supported
-|-
-| flow control (RTS/CTS or DTS/DTR or XON/XOFF based flow control) || 🔴 
-|}