does setDTR() make actual DTR pin LOW or HIGH?

[jskubick]

I suppose this could be considered both a question and a request for documentation enhancement.

When JSerialComm is used with something like a USB-UART bridge (like the cp210x), is a call to setDTR() expected to make the physical DTR line on the other side of the USB port go...

• HIGH (because most modern programmers intuitively associate 'set' with 'high', a '1' bit instead of a '0' bit, and 'true')?

or

• LOW (because in RS232, DTR and RTS are "active low"... so if the API's developer decided "set" is synonymous with "assert", setDTR() would logically be expected to make the pin go low)?

Thanks! I'm writing a program that has to interact with an esp32 bootloader, and struggling to find a clear, unambiguous answer about whether set means 'high', or whether set means 'low' (and thus, asserted).

[jskubick]

Update: I managed to confirm independently that when used with a CP210x USB-UART bridge, setDTR() asserts the line by making the pin LOW, and clearDTR() clears the line by making the pin HIGH.

On a "real" RS-232 port, asserting DTR and RTS makes the pin output positive RS232 voltage, and clearing/de-asserting them makes the pin output negative RS232 voltage.

I tried to submit an update to jSerialComm, but it was blocked because I'm not authorized. If you want to grab the changes (purely to the Javadoc text for setDTR(), clearDTR(), setRTS(), clearRTS() )yourself, you can find them at https://github.com/jskubick/jSerialComm/blob/dtr_rts_javadoc_update/src/main/java/com/fazecast/jSerialComm/SerialPort.java

Update 2: I improved the Javadoc for SerialPort.isOpen() as well, to clarify that it might not (probably won't?) return 'false' if a previously-open USB serial interface is unplugged, and included example code to show how to use the event interface to catch unplugging and close the port so its removal can be detected and it can be later reopened when/if it it gets plugged back in. It also looks like the pull request is in the official review queue with all the subsequent commits I made.

The Javadoc additions I made might also be applicable to the other control lines as well (DCD, RI, etc), but I refrained from changing anything I wasn't able to personally verify as correct. On my esp32 board, the CP2102's other control lines aren't connected to anything accessible & I don't have multimeter probes small enough (or the required manual dexterity and a benchtop microscope) to check the state of pins the approximate width of human hair on the chip itself. ;-)

Update 3: I decided to enhance the Javadoc for SerialPort.setBaudRate() as well, adding a caution about baud rates above 230400 on Macintosh computers and a few paragraphs elaborating on the not-necessarily-obvious relationship between baud rate and USB serial adapters.

It's your call about whether you want to include the extra content, but I honestly think it'll be useful to people using JSerialComm. That said, I'm still debating whether I might have worded it a bit too strongly (possibly giving users the impression that 512kbps is an insurmountable speed limit, vs a mere consequence of the way most of their kernel drivers were implemented). That said, I'm pretty sure it applies to the overwhelming majority of cheap, common USB-serial bridge chips.

[NorbertSandor]

I tried to submit an update to jSerialComm

Maybe try to create a pull request instead of a direct commit...

[NorbertSandor]

SerialPort.isOpen() does not return false if a previously-open USB serial interface is unplugged

Yes, it would be good if the javadoc would mention this behaviour, especially because it is not a bug: https://github.com/Fazecast/jSerialComm/issues/481#issuecomment-1598069815

[jskubick]

Maybe try to create a pull request instead of a direct commit...

I'm pretty sure it was a pull request, and I just described it badly. It's been a couple of years since the last time I contributed to someone else's project, and I'm a little rusty with the process & nomenclature.

TBH, all the Javadoc updates I submitted were for things that had me frustrated & going in circles for the past few days until I managed to stumble over the answers. The fact that SerialPort.isOpen() returns true after a USB serial port gets unplugged (at least, on the computer running Windows 10 I'm using right now... I think it did actually return false on a Macbook Pro I tested) stopped me dead in my tracks for almost 2 days until I stumbled over the solution.

Likewise, the bits of knowledge I gained about how USB serial ports work took several days to piece together. Prior to yesterday, I never really understood how a port theoretically capable of 20gbps could nevertheless overflow at 1mbps when even slow USB is ~11mbps. Once you know there's a 64-byte per millisecond implied speed limit caused by the way the driver communicates with Windows, it suddenly makes perfect sense. Ditto, for OSX's baudrate pain.

[hedgecrw]

This is all absolutely fantastic. Thank you so much for taking the time to integrate all of this knowledge into the javadocs! I'm sure this will greatly help many users in the future. I've just merged your pull request into the repo, so these docs should be visible with the upcoming 2.10.5 release. Thanks again for all your work on this!