Making changes to the Canute's software - Bristol-Braille/canute-ui GitHub Wiki

To make a change to the Canute's files can be done two ways. Please note that any action taken by either method below which damages the functionality of the Canute is not covered by warranty.

We do not encourage users to modify the Canute's code by any means unless they are proficient in programming. When changing files on the Canute it is possible to render the Canute unusable so caution is advised. Any changes made to the Canute's software will be un-done when installing BBT official upgrades so should be backed up so they can be reapplied after an upgrade.

  1. Create a custom 'upgrade' script in the Bash scripting language and inserting it on a USB stick. Please do not attempt this without prior consultation with BBT, who can explain the process.

  2. NOT RECOMMENDED: Unscrew the bottom panel to access the micro-SD card. Doing this will void your warranty, regardless of if any damage is done, unless doing it after receiving prior agreement from BBT, training and disassembly manuals. See Accessing the micro SD for the Raspberry Pi Zero.

If you are using method no.1 then here is an example of how to change the Canute-UI software to add custom TTS support:

  • For a developer to install a TTS on the system they will need to create an upgrade shell script called upgrade.sh which is then put on an SD card inserted into the Canute 360. This upgrade script can be run from the Canute's system menu. This is briefly discussed here: https://github.com/Bristol-Braille/canute-ui/wiki/Making-changes-to-the-Canute%27s-software
  • For an example of the upgrade script they should download this ZIP bundle: https://bristolbraille.org/fw
  • The upgrade procedure is explained in more depth here: https://github.com/Bristol-Braille/canute-ui/wiki/Upgrade-your-Canute-360-to-the-latest-software
  • The Canute runs on a version of Raspian called Raspberry Pi OS Lite (Legacy), AKI 'Buster'. This is available here: https://downloads.raspberrypi.org/raspios_oldstable_lite_armhf_latest. They don't need to upgrade this system when making their custom upgrade script (they shouldn't upgrade the system), but they do need to make sure that the software they are bundling is compatible with this system. They should also assume they only have 8GiB of space available. (In practice they will have more space available.)
  • They will need to bundle the correct liblouis .deb file on the SD card, which the upgrade script will then install.
  • They will also need to bundle the .deb or .tar.gz file for the TTS they intend to run and have the upgrade script install that too.
  • Currently the canute-ui Python software on the Canute 360 reads text from a BRF file one page at a time and sends this to the Braille display via a custom USB protocol. It also prints a Unicode version of the Braille to the HDMI out. This latter process is the best string to intercept to hook the TTS to.
  • To achieve this the developers will need to create a custom version of the HDMI-out Python script and have the upgrade script copy it (archiving the the original). The Python script in question is here: https://github.com/Bristol-Braille/canute-ui/blob/main/ui/driver/qt_display.py
  • This next step is one suggestion for how to achieve it:
    • Add extra functionality to the print_braillefunction in qt_display.py. The purpose is to take all the Unicode Braille rows and send them as a string to Liblouis, then take Liblouis's output and send that to the TTS.
    • Therefore add a line after the loop (so on line 118) that concatenates all the self.label_rows of Braille, then calls a system sub process to pipes the string to Liblouis and pipe that to the TTS. As to how to handle the back-translation, they will probably want to use this table: https://github.com/liblouis/liblouis/blob/master/tables/mn-MN-g2.ctb
  • Note that in the example table given above the author of that contracted Mongolian table note they have not sufficiently tested it on back-translation so it may produce bad results. If it does produce bad results the developers will need to improve the table before rolling out the upgrade (at which point they should also submit the proved table to the Liblouis developers so everyone can benefit from it, as Liblouis is an open source project).