diff --git a/Troubleshooting.md b/Troubleshooting.md deleted file mode 100644 index f3e0f69..0000000 --- a/Troubleshooting.md +++ /dev/null @@ -1,95 +0,0 @@ -This is a collection of FAQ-style troubleshooting tips. - -## My USB device is not recognized - -Check with an App that uses this library and shows all USB devices, e.g. [Serial USB Terminal](https://play.google.com/store/apps/details?id=de.kai_morich.serial_usb_terminal). -The *Serial Example* app in this project is not sufficient , as it does not show devices where no driver is detected. - -If still no USB device is shown, check the web for [USB Host Mode](https://developer.android.com/guide/topics/connectivity/usb/host.html) aka. [USB OTG](https://en.wikipedia.org/wiki/USB_On-The-Go) support for your Android device. -Missing support is more likely for older devices. - -For an incomplete list of Android devices with known issues look [[here|Compatible-Android-Devices]]. - - -## My USB device is recognized, but no driver is detected - -The library includes a list of USB vendor and device ID's (VID/PID) that are typically used by the supported chips. In case of unusual ID's, use a [Custom Prober](https://github.com/mik3y/usb-serial-for-android#probing-for-unrecognized-devices) or specify a fixed driver. - -Non USB-to-Serial devices like mass-storage, mouse, GPC receivers, ... and rarely used USB-to-Serial chips including Hoitek HE2325U and FTDI FT312D are not supported. - - -## My device is connected, but I receive no / wrong data - -A common issue is wrong baud rate. - - -## I am using an Arduino Uno, Sparkfun Pro Micro, or other Arduino and `if (Serial)` doesn't work. - -Most Arduinos with CDC driver use the DTR line to determine serial channel readiness. In your Android code, call `setDTR(true);` - - -## How do I access `/dev/ttyUSB0`? - -You don't. `/dev/tty*` is the Linux kernel's driver interface to various serial devices. Certain devices and custom ROMs *may* expose serial devices this way, but this library does not use this interface. - - -## When reading a message, why don't all bytes arrive at the same time? - -The protocol layer does not guarantee that all bytes will arrive in a single message. In fact the protocol layer doesn't have any knowledge of what your "message" is — it is just an interface for sending a serial stream of bytes. - -To reduce the number of USB requests, devices usually buffer data until some size or idle time is reached. Therefore request sizes heavily depend on the device type and actual data transfer pattern. - -For example, to receive a 100 byte string, you might read 64 bytes, then 36 bytes, instead of a single message of 100 bytes. You need to account for this problem when designing your protocol. Some common techniques: - -* Fixed length messages: If you a message is always going to be 100 bytes, just keep reading until you have all 100. -* Length-prefixed messages: Prefix every message with a fixed-length `size` value; your message is complete after you've read `size` more bytes. -* Newline-terminated messages: Read until you see a `\n` (or any other "terminal" character). - - -## I observed read _data loss_ with continuous transfer at high baud rates - -Android is not a real time OS. The thread responsible for receiving data might not be scheduled by the OS or garbage collection might be ongoing or … -Therefore data loss can happen for continues read at high baud rates. If data is lost, typically some smaller fragments in the middle of the data are missing. - -This effect is more likely for slower Android device and USB devices with smaller buffer size and typically starts with higher baud rates like 115k2 baud, but is hardly predictable. For low baud rates or non-continuous transfers this issue was not observed as the USB device will not run into a read buffer overflow before the next USB read transfer. - -Using a higher thread priority for `SerialInputOutputManager` (as used [here](https://github.com/mik3y/usb-serial-for-android/blob/73d669c4dc9af4bccdfdd35b1ff4d8e6c9c16ce9/usbSerialForAndroid/src/androidTest/java/com/hoho/android/usbserial/util/UsbWrapper.java#L164)) and offloading work from `onNewData` to other threads sometimes mitigates the issue. - - -## Is `write` synchronous? - -It's typically not. - -Write consists of 2 phases: - -1) from android to usb device -2) from usb device to serial port - -If the send buffer on the usb device is not full, the write call returns after phase 1. If the buffer is full, e.g. your write is larger or older data is still to be send, the write call returns when enough data has been send over the serial port and the rest is in the buffer. - -Waiting for write completion is typically done with application specific protocols, like request-response pattern. - - -## 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. - - -## Does this library work with Ionic/Cordova/Xamarin/App Inventor/... development framework? - -If your framework can import Java .jar files, look [[here|Build-Variants#Jar]] for instructions about creating a .jar file. diff --git a/Troubleshooting.mediawiki b/Troubleshooting.mediawiki new file mode 100644 index 0000000..de05f89 --- /dev/null +++ b/Troubleshooting.mediawiki @@ -0,0 +1,95 @@ +This is a collection of FAQ-style troubleshooting tips. + +== My USB device is not recognized == + +Check with an App that uses this library and shows all USB devices, e.g. [https://play.google.com/store/apps/details?id=de.kai_morich.serial_usb_terminal Serial USB Terminal]. +The ''Serial Example'' app in this project is not sufficient, as it does not show devices where no driver is detected. + +If still no USB device is shown, check the web for [https://developer.android.com/guide/topics/connectivity/usb/host.html USB Host Mode] aka. [https://en.wikipedia.org/wiki/USB_On-The-Go USB OTG] support for your Android device. +Missing support is more likely for older devices. + +For an incomplete list of Android devices with known issues look [[Compatible-Android-Devices|here]]. + + +== My USB device is recognized, but no driver is detected == + +The library includes a list of USB vendor and device ID's (VID/PID) that are typically used by the supported chips. In case of unusual ID's, use a [https://github.com/mik3y/usb-serial-for-android#probing-for-unrecognized-devices Custom Prober] or specify a fixed driver. + +Non USB-to-Serial devices like mass-storage, mouse, GPC receivers, ... and rarely used USB-to-Serial chips including Hoitek HE2325U and FTDI FT312D are not supported. + + +== My device is connected, but I receive no / wrong data == + +A common issue is wrong baud rate. + + +== I am using an Arduino Uno, Sparkfun Pro Micro, or other Arduino and if (Serial) doesn't work. == + +Most Arduinos with CDC driver use the DTR line to determine serial channel readiness. In your Android code, call setDTR(true); + + +== How do I access /dev/ttyUSB0? == + +You don't. /dev/tty* is the Linux kernel's driver interface to various serial devices. Certain devices and custom ROMs ''may'' expose serial devices this way, but this library does not use this interface. + + +== When reading a message, why don't all bytes arrive at the same time? == + +The protocol layer does not guarantee that all bytes will arrive in a single message. In fact the protocol layer doesn't have any knowledge of what your "message" is — it is just an interface for sending a serial stream of bytes. + +To reduce the number of USB requests, devices usually buffer data until some size or idle time is reached. Therefore request sizes heavily depend on the device type and actual data transfer pattern. + +For example, to receive a 100 byte string, you might read 64 bytes, then 36 bytes, instead of a single message of 100 bytes. You need to account for this problem when designing your protocol. Some common techniques: + +* Fixed length messages: If you a message is always going to be 100 bytes, just keep reading until you have all 100. +* Length-prefixed messages: Prefix every message with a fixed-length size value; your message is complete after you've read size more bytes. +* Newline-terminated messages: Read until you see a \n (or any other "terminal" character). + + +== I observed read ''data loss'' with continuous transfer at high baud rates == + +Android is not a real time OS. The thread responsible for receiving data might not be scheduled by the OS or garbage collection might be ongoing or … +Therefore data loss can happen for continues read at high baud rates. If data is lost, typically some smaller fragments in the middle of the data are missing. + +This effect is more likely for slower Android device and USB devices with smaller buffer size and typically starts with higher baud rates like 115k2 baud, but is hardly predictable. For low baud rates or non-continuous transfers this issue was not observed as the USB device will not run into a read buffer overflow before the next USB read transfer. + +Using a higher thread priority for SerialInputOutputManager (as used [https://github.com/mik3y/usb-serial-for-android/blob/73d669c4dc9af4bccdfdd35b1ff4d8e6c9c16ce9/usbSerialForAndroid/src/androidTest/java/com/hoho/android/usbserial/util/UsbWrapper.java#L164 here] and offloading work from onNewData to other threads sometimes mitigates the issue. + + +== Is write synchronous? == + +It's typically not. + +Write consists of 2 phases: + +# from android to usb device +# from usb device to serial port + +If the send buffer on the usb device is not full, the write call returns after phase 1. If the buffer is full, e.g. your write is larger or older data is still to be send, the write call returns when enough data has been send over the serial port and the rest is in the buffer. + +Waiting for write completion is typically done with application specific protocols, like request-response pattern. + + +== 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. + + +== Does this library work with 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.