Issue summary
For several braille displays, when sending a packet, the display acknowledges the receipt of a packet. This is a mechanism to make sure that a packet has been delivered to a braille display in a correct way. Several displays have such a feature, including Handy Tech, Eurobraille and Freedom Scientific displays.
Proposal
Since there are multiple drivers with the need of proper ACK handling, I propose creating a generic system for this.
- Add three extra properties to the braille.BrailleDisplayDriver class.
#: Whether displays for this driver return acknowledgements for sent packets.
#: L{_handleAck} should be called when an ACK is received.
#: Note that thread safety is required for the generic implementation to function properly.
#: If a display is not thread safe, a driver should manually implement ACK processing.
#: @type: bool
receivesAckPackets = False
#: Whether this driver is awaiting an Ack for a connected display.
#: This is set to C{True} after displaying cells when L{receivesAckPackets} is True,
#: and set to C{False} by L{_handleAck} or when C{timeout} has elapsed.
awaitingAck = False
#: Maximum timeout to use for communication with a device (in seconds).
#: This can be used for serial connections.
#: Furthermore, it is used by L{braille._BgThread} to stop waiting for missed acknowledgement packets.
#: @type: float
timeout = 0.2
Note that we can also put awaitingAck on the background thread.
2. in BrailleHandler._writeCells, check for not self.display.awaitingAck, and only queue the executor if we aren't waiting for an ACK and there is no queued write.
3. The executor should set awaitingAck to True whenever a succesful write has been made. Furthermore, it should start a waitable timer that, if not canceled by BrailleDisplayDriver._handleAck, logs the fact that an ACK has been missed, resets awaitingAck to False and queues the executor APC to the background thread.
4. BrailleDisplayDriver._handleAck should set awaitingAck to False and queue the executor APC to the background thread.
Thoughts from @jcsteh, @michaelDCurran and @bramd are appreciated.
Issue summary
For several braille displays, when sending a packet, the display acknowledges the receipt of a packet. This is a mechanism to make sure that a packet has been delivered to a braille display in a correct way. Several displays have such a feature, including Handy Tech, Eurobraille and Freedom Scientific displays.
Proposal
Since there are multiple drivers with the need of proper ACK handling, I propose creating a generic system for this.
Note that we can also put awaitingAck on the background thread.
2. in BrailleHandler._writeCells, check for not self.display.awaitingAck, and only queue the executor if we aren't waiting for an ACK and there is no queued write.
3. The executor should set awaitingAck to True whenever a succesful write has been made. Furthermore, it should start a waitable timer that, if not canceled by BrailleDisplayDriver._handleAck, logs the fact that an ACK has been missed, resets awaitingAck to False and queues the executor APC to the background thread.
4. BrailleDisplayDriver._handleAck should set awaitingAck to False and queue the executor APC to the background thread.
Thoughts from @jcsteh, @michaelDCurran and @bramd are appreciated.