Driver for Tivomatic Caiku Albatross 46/80 displays #13045
Conversation
…ic detection. English and Finnish user guides, and bdDetect.py updated.
…ection initialization.
|
@burmancomp Please fill out the PR template and revert changes to the Finnish user guide edits to the translated documentation are handled separately via SVN. |
See test results for failed build of commit 1bc7e5c706 |
|
No idea how to modify information on pr template.
|
|
@burmancomp Click the context menu button (labelled by NVDA as "show options") above the first comment in this thread, then click "edit comment" from the revealed menu. In the edit field:
|
There was a problem hiding this comment.
User Guide changes look fine. Is there a website for the display manufacturer or its documentation? If so, I'd request adding a link (I didn't find one from a quick look myself, and your use of the past tense "...these displays were manufactured by..." suggests there might not be much online, so that's fine.
Note: Just approving for the user guide change, check the requested changes from others.
|
Unfortunately there is no online resources anymore. |
|
@burmancomp Would you mint resolving conflicts here? @michaelDCurran Is this on your radar? |
feerrenrut
added
the
conceptApproved
|
Maybe this could be reviewed in the near future? |
Other changes include: - When connection was disabled, numCells was set to 0, and it was then used in efforts to block some useless write operations. Due to changes in braille.py, setting numCells to 0 caused issue where display was not updated properly when switching device off and back on. In this context numCells is replaced with _disabledConnection boolean variable. - Modified comment in _threading.py.
There was a problem hiding this comment.
Once all these outstanding review comments are resolved, I think this can be merged.
Thanks for all your hard work on this @burmancomp
Thank you @seanbudd. This is my first open source and python work and as such very useful. |
As part of Pull request #14531, I ordered display order in bdDetect alphabetically. However, it seems that querying Albatross first has a major negative impact on detecting other displays using the same Serial to USB converter (see Pull request #13045) Description of user facing changes Handy Tech displays such as the Modular Evolution instantly auto detect again. Description of development approach Restored the order, Albatross is last in the dictionary again. I'm pretty unhappy with how these displays work, but it looks like it's a design thing in the displays itself.
Follow-up of #13045 Summary of the issue: Driver sent to Albatross display byte string b"\xfe\xfd\xfe\xfd" to tell device that there is active connection and it should not send init packets anymore. Byte string contained two establishment packets, and one should be enough. It should not cause harm to send two packets because display ignores latter one but it is redundant anyway. In stead of b"\xfe\xfd\xfe\xfd" driver sends now b"\xfe\xfd" to display.
Link to issue number:
Summary of the issue:
No support for Tivomatic Caiku Albatross 46/80 braille display models.
Description of how this pull request fixes the issue:
General
Different to many other displays, Albatross models do not wait for the driver to send a query of their presence to the device. Instead, the device continuously sends initialization packets until driver requests to them quit, as the connection has been established.
These displays also expect regular data packets, with frequency of at least one every 2 seconds. Otherwise they fall back to "wait for connection" state and start sending the initialization packets until the driver sends a quit packet.
Similarly, if the user enters the device internal menu, after exiting, initialization packets are continuously sent until driver sends quit packet.
Init packets are also sent when device is powered off and then on.
Display init packets consist of two bytes: the first one is \xff which tells that this is an init packet. The second one is a settings byte which contains display settings like length of display and number of status cells. The most meaningful setting is the length of display. Other settings contained by settings byte can be regarded as notes to screenreader, and it is screenreader or driver job to use them when applicable. For example, there are no separate status cells in the device but if screenreader supports using status cells, it can be notified to use them by settings byte.
The settings byte can be anything between \x00 and \xff. Thus it could be the same as init byte.
It is possible that settings byte may have same value with any display buttons. Because init packets may be sent also during session (user exits display internal menu for example), it is essential to know if byte is button press or part of init packet.
When display is in "wait for connection" state, it sends init packets continuously. As such, there may be hundreds of bytes to handle. There are several rx buffers between device and driver which seems to cause situation that all data cannot be read with one read operation. It cannot be known when all data has been read. This is the case with init packets but also with key combinations.
There are other devices with same PID&VID. When automatic braille display detection is used, other displays with same PID&VID are tried before Albatross. Those drivers try to send queries to the port to detect their own displays. These queries may cause Albatross to send unexpected init packets which in turn could disturb this driver - it could get inappropriate settings byte. This is tried to prevent by resetting I/O buffers so that strange packets would be discarded.
If however, there are still strange init packets, Albatross should be manually selected from the display list.
To reduce complexity of data handling this driver accepts only settings bytes <= \xfe. From user perspective this means that with 80 model user can ask screenreader to use at most 14 status cells when without limitation user could ask 15. Limitation is applied only if user has switched all other settings to values that cause value of byte to be \xff. From settings byte for status cells there are reserved the most right 4 bits. Limitation does not affect on 46 cells model because the most left bit of byte defines the length of display (0 for 46 and 1 for 80 cells model).
Note: This driver ignores status cells related settings because NVDA does not use status cells at the moment.
Driver requirements
Design
Driver has modular structure:
constants.pycontains all the constant definitions, for example button values and names.driver.pyis the main part of the code. It implementsBrailleDisplayDriverclass which is in response of all read and write operations. It also takes care to format data which is meant to be displayed on the braille line.Important main functions of
BrailleDisplayDriverare:_readHandling; performs connecting/reconnecting to the device, and all read operations during connection_somethingToWrite; performs all write operations to the displaydisplay; prepares data to be displayed on the braille lineIn
gestures.pynumeric values of pressed buttons are interpreted as gestures so that they can be forwarded to NVDA input system._threads.pydefines two threads. Thread called albatross_read callsBrailleDisplayDriver_readHandlingfunction when it gets signaled that port has data to be read. Idea is somewhat similar tohwIoonReceivefunction. For deeper read and write operations control own thread was implemented. In addition, it calls_readHandlingif it detects port problems so that_readHandlingcan try to reconnect. Albatross_read thread sleeps most of the time because user does not press buttons continuously, and connection problems occur rarely.The second thread is timer which checks periodically (after approximately 1.5 seconds) that some data has been sent to display so that it keeps connected.
_SomethingToWritefunction updates time of last write operation. If there is at least 1.5 seconds from last write operation, display is feeded data packet containingSTART_BYTEandEND_BYTEwhich enclose data which is sent to be displayed on the braille line.Testing strategy:
Daily use testing in Windows 7/10.
Known issues with pull request:
Braille Extender addon may not be compatible with this driver at the moment.
Change log entries:
New features
"Added support for Tivomatic Caiku Albatross 46/80 braille displays.
Changes
Bug fixes
For Developers
Code Review Checklist: