Skip to content

Native braille display drivers: provide a generic way to handle acknowledgement packets. #7721

@LeonarddeR

Description

@LeonarddeR

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.

  1. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions