TEXT   41

BRLTTY on Android

Guest on 13th May 2022 01:56:20 AM

  1. ~~~~~~~~~~~~~~~~~
  2. BRLTTY on Android
  3. ~~~~~~~~~~~~~~~~~
  5. .. |SDK build tools version| replace:: 29.0.3
  6. .. |NDK version| replace:: r21e (21.4.7075529)
  7. .. |JDK version| replace:: 1.7
  9. .. _BRLTTY on Google Play: https://play.google.com/store/apps/details?id=org.a11y.brltty.android
  11. .. include:: prologue.rst
  13. Using BRLTTY
  14. ============
  16. Activation and Configuration
  17. ----------------------------
  19. At this point, BRLTTY has been installed. Next, you'll need to go into
  20. ``Settings`` -> ``Accessibility`` -> ``BRLTTY`` in order to start the ``BRLTTY``
  21. accessibility service, adjust its settings, and select your braille device.
  23. If you'll be connecting to your braille device via Bluetooth,
  24. see `Connecting Via Bluetooth`_.
  26. If you'll be connecting to your braille device via USB,
  27. see `Connecting Via USB`_.
  29. If your braille device has a braille keyboard,
  30. see `Using a Braille Keyboard`_.
  32. Starting and Stopping BRLTTY
  33. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  35. BRLTTY isn't a regular Android application - it's an accessibility service. As
  36. such, it can't be started and stopped in the usual way, i.e. from the launcher.
  37. In fact, it can't even be found within the applications list.
  39. BRLTTY must be started and stopped from the ``Accessibility Settings`` screen.
  40. To get there, launch the ``Settings`` application, and then tap on
  41. ``Accessibility`` (near the bottom). This screen contains a "Services" section
  42. that lists all of the accessibility services that are currently installed on
  43. the device. For each installed accessibility service, there's an associated
  44. indicator that says ``On`` if that service is currently running, and ``Off`` if
  45. it isn't.
  47. Find ``BRLTTY`` and tap on it. This brings up a window with two items in it.
  48. One is a "switch" for turning BRLTTY on and off. The other is a button that
  49. takes you to BRLTTY's ``Settings`` screen. You can go through BRLTTY's
  50. settings, making changes as desired, as well as define your braille device(s),
  51. either before starting BRLTTY or while it's running.
  53. Connecting Your Braille Device
  54. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  56. Connecting Via Bluetooth
  57. ````````````````````````
  59. In order to use a Bluetooth braille device, you'll need to first "pair" it with
  60. your Android device. Go into ``Settings`` -> ``Bluetooth``. If your braille
  61. device is already listed within the ``Paired Devices`` section of that screen
  62. then it has already been paired. If you still need to pair it then tap
  63. ``Search for Devices``. This will add an ``Available Devices`` section to the
  64. screen. If your braille device isn't listed then you'll probably need to
  65. perform a model-specific action on it in order to make it visible
  66. (also known as discoverable) - see its manual for details. After doing that,
  67. tap ``Search for Devices`` again. Tap on your braille device to begin the
  68. Bluetooth Pairing Request, enter its PIN (see its manual for details), and tap
  69. ``OK``.
  71. Connecting Via USB
  72. ``````````````````
  74. In order to use a USB braille device, you'll need a special cable known as a
  75. "Micro USB Host Adapter". The reason for this is that the USB port on an
  76. Android device usually acts as a "device" (rather than as a "host") port. This
  77. is so that, for example, you can control your Android device from your
  78. computer. The Micro USB Host Adapter has a special plug, known as an OTG
  79. (on-the-go) connector, that, when inserted into the Android device's USB port,
  80. instructs Android to act as the USB host.
  82. The Micro USB Host Adapter also allows you to connect any other USB
  83. device (keyboard, mouse, printer, hub, etc) to your Android device. Be aware,
  84. though, that if any such device, including your braille device, draws power via
  85. its USB port then your Android device's battery will become the source of that
  86. power. If portability isn't an issue, you may wish to consider using your Micro
  87. USB Host Adapter to connect your Android device to a powered hub so that your
  88. USB devices will draw power from the hub rather than from your Android device's
  89. battery. You may also wish to consider disabling USB charging on any devices
  90. that offer this capability.
  92. Defining Your Braille Device
  93. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  95. You don't actually need to define your braille device, but BRLTTY will connect
  96. to it much faster if you do. If you don't, BRLTTY will search through all of
  97. the devices that have been connected via either Bluetooth or USB
  98. (see `Connecting Your Braille Device`_) for one that it recognizes. If there's
  99. more than one, it'll select the first one that it finds.
  101. To define your braille device, go to BRLTTY's ``Settings`` screen, tap on
  102. ``Manage Devices``, and then on ``Add Device``. From there, find your braille
  103. device, and then tap ``Add``. To find your braille device:
  105. 1) Select its communication method (Bluetooth, USB).
  107. 2) Select your device from the list that's presented.
  109. 3) Select the correct braille driver.
  110.    This step is optional, i.e. you can usually leave it set to ``autodetect``.
  111.    Going through the effort of selecting the correct driver, however,
  112.    ensures a fast and reliable connection.
  114. After you've added your braille device to BRLTTY, tap on ``Selected Device``
  115. and select it from the list of devices that BRLTTY knows about.
  117. Using a Braille Keyboard
  118. ~~~~~~~~~~~~~~~~~~~~~~~~
  120. Braille device keyboard input is supported, but, like all Android input
  121. methods, it must be explicitly enabled, and then explicitly selected. Android
  122. doesn't permit BRLTTY to do either of these automatically on your behalf.
  123. Although it's inconvenient, Android imposes this manual process so that you're
  124. very consciously aware of which input methods can process, and which input
  125. method is currently processing, whatever you're typing. Such applications,
  126. after all, handle extremely sensitive personal data (such as passwords, credit
  127. card numbers, etc), so it's crucial that you make your own decisions regarding
  128. which of them you're willing to trust.
  130. If you type on your braille device's keyboard when BRLTTY's input method is
  131. either disabled or enabled but not selected, then BRLTTY will alert you to this
  132. fact via a message on your braille display. You may wish to enable BRLTTY's
  133. keyboard support ahead of time, but you probably don't want to select it ahead
  134. of time. The reason for this is that Android only allows exactly one input
  135. method to be in use at a time. When you explicitly select BRLTTY's input
  136. method, therefore, you're also implicitly deselecting the on-screen keyboard.
  138. You can enable BRLTTY's keyboard support in one of the following ways:
  140. * Launch Android's ``Settings`` application and tap on ``Language and Input``.
  141.   The ``Keyboard and Input Methods`` section of this screen shows the
  142.   ``Default`` (currently selected) input method, and contains a check box for
  143.   each installed input method. An input method is enabled if its check box is
  144.   checked, so, to enable BRLTTY's keyboard support, check the box labelled
  145.   ``BRLTTY Input Service``. Once it's been enabled, you can select it at any
  146.   time by adjusting the ``Default`` setting.
  148. * If BRLTTY is running then switching between input methods is much easier.
  149.   Go to BRLTTY's `Actions screen`_ and tap ``Switch Input Method``. This
  150.   brings up Android's Input Method Picker, which presents a set of radio
  151.   buttons - one for each enabled input method. If there's no radio button for
  152.   BRLTTY's input method then it hasn't been enabled yet. To enable it, tap the
  153.   button labelled ``Set up input methods``. This screen contains a check box for
  154.   each installed input method. Check the box labelled ``BRLTTY Input Service``.
  155.   Then tap the ``Back`` button to return to the ``Language and Input`` screen,
  156.   find the ``Keyboard and Input Methods`` section, and set the ``Default``
  157.   input method to BRLTTY's input method.
  159. Actions Screen
  160. ~~~~~~~~~~~~~~
  162. BRLTTY's Actions screen presents several common actions that you may wish to perform:
  164. * Switch Input Method
  165. * BRLTTY Settings
  166. * View User Guide
  167. * Browse Web Site
  168. * Browse Community Messages
  169. * Post Community Message
  170. * Manage Community Membership
  171. * Update Application
  172. * About Application
  174. You can get to this screen using any of the following methods:
  176. * From your braille device via global action #5.
  177.   See `Global Actions`_ for details.
  179. * From the notifications shade.
  180.   Open it by dragging the status bar downward:
  182.   * With two fingers if Explore By Touch is active.
  183.   * With one finger if Explore By Touch isn't active.
  185.   Then find BRLTTY's service notification and tap it.
  187. * Via the Accessibility button within the system navigation area.
  188.   This capability was introduced in Android 8.0 (Oreo).
  189.   The button may not be visible for a number of reasons, for example:
  191.   * The device's system navigation area isn't rendered via software.
  192.   * An application has chosen to hide the system navigation area.
  194. Customized Data Files
  195. ~~~~~~~~~~~~~~~~~~~~~
  197. You can customize any of BRLTTY's data files,
  198. e.g. a text, contraction, or key table or subtable.
  199. To do this, add a file with the same name directly into a folder named ``brltty``
  200. at the top-level of your Android device's primary shared/external storage area.
  201. This area might be internal (on the device itself)
  202. or external (on a removal storage device, e.g. an SD card).
  203. Normally, it's the area that ``/sdcard`` is symbolically linked to.
  205. BRLTTY won't be aware of your customized data files
  206. if this area has been mounted by a computer.
  208. It's safe to include the original data file from your customized copy.
  209. If you're only adding lines, therefore, then your customized copy
  210. need only contain those additions and the include statement.
  212. Navigating the Screen
  213. ---------------------
  215. Using Multiple Hosts
  216. ~~~~~~~~~~~~~~~~~~~~
  218. BRLTTY only remains connected to your braille device while your Android device
  219. is unlocked or while its screen is on. If your Android device is locked and its
  220. screen is off then BRLTTY automatically disconnects from your braille device.
  221. This is so that you can easily share your braille device amongst multiple
  222. hosts.
  224. Pressing your Android device's power button (or similar action) to wake it up,
  225. even though it may still be locked, is sufficient to cause BRLTTY to
  226. automatically reconnect to your braille device. This allows you to enter your
  227. password or PIN via your braille keyboard.
  229. You can continue using your braille device even though your Android device's
  230. screen may have turned off, as long as its lock timer hasn't yet expired.
  231. Pressing keys on your braille device resets your Android device's lock timer in
  232. the same way that pressing its keys, touching its screen, etc does. This means
  233. that your Android device will stay awake and unlocked even though you're only
  234. controlling it from your braille device, and that it'll also still
  235. automatically lock once you're no longer using it.
  237. Accessibility Focus
  238. ~~~~~~~~~~~~~~~~~~~
  240. The "accessibility focus" feature of Android is used for cursor tracking and
  241. routing. It's a soft cursor, not visible on the screen, that can be
  242. programmatically associated with any screen element. All screen readers that
  243. use it to define the current element for actions (like tapping) will implicitly
  244. cooperate reasonably seamlessly with one another.
  246. The cursor is usually placed on the first character of the screen element that
  247. currently has accessibility focus. The one exception to this is within an
  248. input area. If that area has input focus then the cursor is placed at
  249. the location within it where input will be inserted.
  251. When a home screen folder is opened, BRLTTY automatically sets accessibility
  252. focus to that folder's first entry. This eliminates the need to search for it.
  254. The Cursor Routing Keys
  255. ~~~~~~~~~~~~~~~~~~~~~~~
  257. The cursor routing keys of your braille device perform their usual function when
  258. within an input area if it has input focus - the key above a given
  259. character brings the cursor to that character. In any other context, however, a
  260. cursor routing key performs an action on the screen element under it. Starting
  261. with the leftmost routing key over a screen element, which we'll call key #1,
  262. these actions are as follows:
  264. 1) Bring accessibility focus (cursor)
  265. 2) tap (click)
  266. 3) hold (long click)
  267. 4) scroll backward (up or left)
  268. 5) scroll forward (down or right)
  269. 6) context click
  270. 7) accessibility actions
  272. A range control (progress bar, volume slider, etc) can be adjusted up/down
  273. via the scroll forward/backward actions.
  275. Input Areas
  276. ~~~~~~~~~~~
  278. When an input area has input focus, BRLTTY's attribute underlining
  279. feature is used to highlight the selected text region.
  281. Widget Representations
  282. ~~~~~~~~~~~~~~~~~~~~~~
  284. Check Boxes
  285. ```````````
  287. A check box is rendered as a three-cell symbol:
  289. 1) dots 123478 (the left side of the box)
  290. 2) dots 2356 (the check mark)
  291. 3) dots 145678 (the right side of the box)
  293. The check mark is present if the box is checked and absent if it isn't.
  294. If the check box has a label then it appears to the right of the symbol.
  295. The braille representations are:
  297. * ⣏⠶⣹ checked
  298. * ⣏ ⣹ not checked
  300. Radio Buttons
  301. `````````````
  303. A radio button is rendered as a three-cell symbol:
  305. 1) dots 2348 (the left side of the button)
  306. 2) dots 2356 (the check mark)
  307. 3) dots 1567 (the right side of the button)
  309. The check mark shows which of the radio buttons is currently selected.
  310. The label for each radio button appears to the right of its symbol.
  311. The braille representations are:
  313. * ⢎⠶⡱ selected
  314. * ⢎ ⡱ not selected
  316. Switches
  317. ````````
  319. A (two-position) switch is rendered as a three-cell symbol:
  321. 1) dots 4568 (the left side of the switch)
  322. 2) dots 1478 (the top and bottom of the switch)
  323. 3) dots 1237 (the right side of the switch)
  325. Dots 25 are added to the middle cell if the switch is on,
  326. and dots 36 are added to the middle cell if the switch is off.
  327. In other words, the switch is up when on and down when off.
  328. The label for the switch's current state appears to the right of the symbol.
  329. The braille representations are:
  331. * ⢸⣛⡇ on
  332. * ⢸⣭⡇ off
  334. Range Controls
  335. ``````````````
  337. A range control is one which can be adjusted (rather than set or edited).
  338. They include widgets like progress bars, volume sliders, etc.
  339. They're rendered as a three-value summary::
  341. * An at sign followed by the current setting.
  342. * The minimum and maximum settings, separated by a dash, within parentheses.
  344. The developer of an application can choose which value range a given control uses.
  345. For example, a 16-position volume control currently set to 75% might look like this::
  347.   @11 (0 - 15)
  349. It could, however, also look like this::
  351.   @75% (0% - 100%)
  353. Disabled Controls
  354. `````````````````
  356. If a control is currently disabled then the word ``disabled``,
  357. enclosed within parentheses, appears to the right of its label.
  358. For example::
  360.   Connect (disabled)
  362. When There's No Text
  363. ````````````````````
  365. A screen element that has no text of its own,
  366. and that BRLTTY doesn't explicitly support,
  367. is normally not rendered.
  368. Examples of these include:
  370. * A graphic (e.g. an image view).
  371. * A container used to construct the screen's layout (e.g. a frame layout).
  373. It's still necessary to render it, however, if it implements
  374. an action (e.g. a tap) which the user needs to be able to perform.
  376. If the application's developer has provided descriptive text
  377. then that text is rendered.
  378. If not, then BRLTTY renders a generic description within (parentheses).
  379. It contains the widget's type, and, if available, it's source code identifier.
  381. Global Actions
  382. ~~~~~~~~~~~~~~
  384. Android supports a number of global actions that can be performed by pressing
  385. special hardware buttons and/or by touching reserved areas on the screen.
  386. BRLTTY also offers a way to perform these actions from your braille device.
  387. While a better way may be developed in the future, this is how it can be done
  388. right now.
  390. * Since Android doesn't use the keyboard function keys
  391.   (commonly named ``F1`` through ``F12``),
  392.   BRLTTY uses them to perform the global actions.
  393.   The way a braille device emulates keyboard function keys
  394.   differs from model to model,
  395.   so you should check the BRLTTY documentation for your braille device.
  396.   The most common way is to press the corresponding cursor routing key
  397.   along with some other key or key combination.
  398.   For braille devices that have a braille keyboard,
  399.   the most common key to be used in conjunction with a cursor routing key
  400.   in order to emulate a keyboard function key is the space bar.
  402. * If your braille device has a braille keyboard
  403.   then you can perform the global actions
  404.   via chords that also include dots 7 and 8.
  405.   For example, Space + Dots78 + Dots125 (h) goes to the home screen.
  407. .. table:: Global Android Actions
  409.   =======  =========  =====================================  =====================
  410.   FN-Key   Chord78+   Action                                 As of Android Release
  411.   -------  ---------  -------------------------------------  ---------------------
  412.   ``F1``   125 (h)    go to the Home screen                  4.1 (Jelly Bean)
  413.   ``F2``   12 (b)     tap the Back button                    4.1 (Jelly Bean)
  414.   ``F3``   1345 (n)   go to the Notifications screen         4.1 (Jelly Bean)
  415.   ``F4``   1235 (r)   tap the Recent Apps (Overview) button  4.1 (Jelly Bean)
  416.   ``F5``   123456     go to BRLTTY's `Actions screen`_       \*
  417.   ``F6``   23         move to the first item                 \*
  418.   ``F7``   2          move to the previous item              \*
  419.   ``F8``   5          move to the next item                  \*
  420.   ``F9``   56         move to the last item                  \*
  421.   ``F10``  134 (m)    tap the Menu button                    \*
  422.   ``F11``  36         return to the active window            4.0 (Kitkat)
  423.   ``F12``  3          switch to the previous window          4.0 (Kitkat)
  424.   ``F13``  6          switch to the next window              4.0 (Kitkat)
  425.   ``F14``  2345 (t)   show the window title                  6.0 (Nougat)
  426.   ``F15``  24 (i)     show various device status indicators           \*
  427.   ``F16``  234 (s)    go to the Quick Settings screen        4.2 (Jelly Bean MR1)
  428.   ``F17``  135 (o)    go to the Device Options screen        5.0 (Lollipop)
  429.   =======  =========  =====================================  =====================
  431. Text Selection and the Clipboard
  432. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  434. As with the `global actions`_,
  435. if your braille device has a braille keyboard
  436. then you can perform text selection actions
  437. via chords that also include dots 7 and 8.
  438. For example, Space + Dots78 + Dots14 (c)
  439. copies the selected text to Adroid's clipboard.
  440. This works as of Android release 4.3 (Jelly Bean MR2).
  442. .. table:: Text Selection and Clipboard Actions
  444.   ========  =======================================
  445.   Chord78+  Action
  446.   --------  ---------------------------------------
  447.   1 (a)     select all of the text
  448.   4         clear the text selection
  449.   14 (c)    copy the selected text to the clipboard
  450.   1236 (v)  paste the text on the clipboard
  451.   1346 (x)  cut the selected text to the clipboard
  452.   ========  =======================================
  454. The text selection extends inclusively
  455. from its first endpoint through its second one.
  456. The attribute underlining feature (see the Show Attributes preference)
  457. is used to show which text has currently been selected.
  458. It may be helpful to set the attribute underline to blink
  459. if the cursor isn't set to blink, and vice versa.
  461. In addition to being able to select all of the text,
  462. there are ways to select a specific portion of the text.
  463. Exactly how this is done depends on which braille device you're using.
  464. There is, however, one way to do it that works
  465. on any braille device that has cursor routing keys.
  467. The cursor routing key where the cursor is
  468. normally doesn't serve any useful purpose.
  469. If, however, you enable the Start Text Selection preference
  470. (which can be found within the Navigation Options submenu),
  471. then it enters `text selection mode`_
  472. with that character being both the first and second endpoints.
  473. This method has the constraint that the first endpoint of the text selection
  474. must be a character that the cursor can get to.
  476. .. _Text Selection Mode:
  478. When in text selection mode,
  479. pressing a cursor routing key changes the second endpoint of the selection.
  480. This may be done any number of times.
  481. The second endpoint may be either after or before the first one.
  483. Commands
  484. ````````
  486. HOST_COPY
  487.   Copy the selected text to the host clipboard
  488.   and then deselect it.
  490. HOST_CUT
  491.   Copy the selected text to the host clipboard
  492.   and then delete it.
  495.   Insert the text on the host clipboard after the screen cursor.
  498.   Select all of the text.
  501.   Clear (deselect) the current text selection.
  504.   Select a specific portion of the text.
  505.   This command requires that both endpoints of the text
  506.   are within the current braille window.
  507.   The key combination needs two cursor routing (or equivalent) keys.
  508.   We recommend a long press of two cursor routing keys
  509.   (if the braille device supports it).
  512.   Enter `text selection mode`_ with that character being both endpoints.
  513.   With this method, the first endpoint of the text selection can be anywehre,
  514.   i.e. it isn't constrained to be a character that the cursor can get to.
  515.   The key combination needs a cursor routing (or equivalent) key.
  516.   We recommend a long press of a cursor routing key
  517.   (if the braille device supports it).
  519. Web Pages
  520. ~~~~~~~~~
  522. Element Annotations
  523. ```````````````````
  525. A number of elements within a web page are annotated
  526. in order to help distinguish them from the surrounding text.
  527. Each annotation is placed immediately before
  528. the text of the element that it describes.
  529. It consists of a three-letter tag,
  530. optionally followed by descriptivE data,
  531. all enclosed within (parentheses).
  532. Here are some examples:
  534. .. table:: Web Page Element Annotation Examples
  536.   =================  ====================================================
  537.   Example            Meaning
  538.   -----------------  ----------------------------------------------------
  539.   (btn) Submit       a Submit button
  540.   (lnk https://...)  the target URL of a link
  541.   (tbl 4x9)          the start of a table with four columns and nine rows
  542.   (col 2@3)          the second column of the third row of a table
  543.   =================  ====================================================
  545. The following table lists all of the annotations:
  547. .. table:: Web Page Element Annotations
  549.   ==========  =====================================  ===========
  550.   Annotation  Meaning                                Data
  551.   ----------  -------------------------------------  -----------
  552.   btn         button
  553.   cap         table caption
  554.   col         column in table row                    coordinates
  555.   frm         start of form
  556.   hdg         heading (unspecified level)
  557.   hd1         level one heading
  558.   hd2         level two heading
  559.   hd3         level three heading
  560.   hd4         level four heading
  561.   hd5         level five heading
  562.   hd6         level six heading
  563.   hdr         header of table column                 coordinates
  564.   lnk         target of link                         URL
  565.   lsi         list item                              coordinates
  566.   lsm         list marker
  567.   lst         start of list                          dimensions
  568.   pop         combo box (single or Multiple choice)
  569.   pwd         password field
  570.   row         start of table row
  571.   tbl         start of table                         dimensions
  572.   txt         text field or area
  573.   \--------   horizontal divider
  574.   ==========  =====================================  ===========
  576. Structural Navigation
  577. `````````````````````
  579. Pressing Dots2578 enters Structural navigation mode.
  580. When in this mode,
  581. a web page, when being browsed with Chrome, can be structurally navigated
  582. by pressing dot combinations on your braille device.
  583. Press Dots78 (without Space) to return to the default key bindings.
  585. When in this mode,
  586. combinations of dots 1 through 6 specify the type of element
  587. that you'd like to navigate to.
  588. Adding dot 7 means move to the previous element of that type,
  589. and adding dot 8 means move to the next element of that type.
  590. If neither dot 7 nor dot 8 is added then the current direction is used.
  592. The current direction defaults to (starts out as) ``next``.
  593. Pressing dot 7 by itself sets it to ``previous``,
  594. and pressing dot 8 by itself sets it to ``next``.
  596. If the key table for your braille device defines
  597. a key to be the Left Alt (meta) modifier
  598. then you don't need to switch to/from structural navigation mode.
  599. Just hold that key while pressing
  600. the desired structural navigation dot combination.
  602. The following element types are supported
  603. (where possible, a hopefully easy-to-remember character has been chosen):
  605. .. table:: Structurally Navigable Web Page Elements
  607.   ======  ====  =====================================
  608.   Dots    Char  Go to the Previous/Next
  609.   ------  ----  -------------------------------------
  610.   1       a     article
  611.   12      b     button
  612.   14      c     control
  613.   145     d     ARIA landmark
  614.   15      e     editable text
  615.   124     f     focusable item
  616.   1245    g     graphic
  617.   125     h     heading (any level)
  618.   24      i     list item
  619.   123     l     link (visited or unvisited)
  620.   134     m     media
  621.   135     o     list (ordered or unordered)
  622.   1235    r     radio button
  623.   234     s     section
  624.   2345    t     table
  625.   136     u     unvisited link
  626.   1236    v     visited link
  627.   1346    x     check box
  628.   1356    z     combo box (single or multiple choice)
  629.   2       1     level one heading
  630.   23      2     level two heading
  631.   25      3     level three heading
  632.   256     4     level four heading
  633.   26      5     level five heading
  634.   235     6     level six heading
  635.   ======  ====  =====================================
  637. When BRLTTY Crashes
  638. -------------------
  640. We hope, of course, that BRLTTY won't crash. If it does, though, we want to
  641. know about it.
  643. If BRLTTY does crash, you'll get a dialog with a message like this::
  645.    Unfortunately, BRLTTY has stopped.
  647. This dialog will stay on the screen until you dismiss it by tapping its ``OK``
  648. button. Android will then try to automatically restart BRLTTY, so don't be
  649. overly concerned if this dialog comes up again. Android will eventually give up
  650. if, after a few automatic restart attempts, it decides that BRLTTY simply won't
  651. stay running.
  653. If this ever happens, then, if you can, connect your device to your host via
  654. USB as soon as possible in order to capture a debug log. To capture a debug
  655. log, use this command::
  657.    adb logcat -v time -d >/path/to/logfile
  659. The ``-v time`` option means to add a timestamp to each log record. The ``-d``
  660. option means to dump the current Android system log. The ``adb logcat`` command
  661. writes the log to its standard output, so you need to redirect its standard
  662. output (with ``>``) to wherever you'd like the log to be written.
  664. The reason for capturing the log as soon as possible after a problem is that
  665. Android imposes limits on its log storage so that the log can't consume too
  666. much of your device's resources. If the log becomes too large, Android
  667. automatically removes older entries from it. If you wait too long, therefore,
  668. the part of it that shows how BRLTTY crashed may already have been
  669. automatically removed.
  671. Known Issues
  672. ------------
  674. Serial devices aren't supported. Even though Android devices don't have serial
  675. ports, serial devices still can be connected via a USB to Serial adapter. Users
  676. who have older, serial-only braille devices should still be able to use them
  677. with their Android devices.
  679. Installing BRLTTY
  680. =================
  682. BRLTTY has been designed to run on at least Android 4.1 (Jelly Bean).
  683. While it does run on Android 4.0 (Ice Cream Sandwich),
  684. many of its highly desirable features won't work.
  686. BRLTTY can be installed via Google Play.
  687. You can either search for it by name
  688. or go directly to `BRLTTY on Google Play`_.
  690. Required Permissions
  691. --------------------
  693. BRLTTY requires access to a number of privileged
  694. Android operating system capabilities.
  695. The required permissions are as follows:
  697. .. include:: android-permissions.rst
  699. The Old Way
  700. -----------
  702. Before it was on Google Play, BRLTTY had to be installed and updated manually.
  703. For now, this way still works.
  705. These instructions are from the perspective of a Firefox user on Windows,
  706. but the process should be much the same when using a different web browser and/or operating system.
  708. On Your Computer
  709. ~~~~~~~~~~~~~~~~
  711. 1) Go to `BRLTTY's web site`_.
  713. 2) Find the ``Download`` link and press Enter on it.
  715. 3) Go to the ``Android`` section, down-arrow from there to the link that says
  716.    ``Latest APK``, and press Enter on it.
  718. 4) You'll be prompted to open or save the file at this point. Save it.
  720. 5) Go to your ``Downloads`` folder (or wherever you save downloads), and
  721.    find the ``brltty-latest.apk`` file.
  723. 6) If the file has been saved on your computer as ``brltty-latest.zip``,
  724.    then press the ``Context`` key, arrow to and press Enter on ``Rename``,
  725.    and change the file extension from ``zip`` to ``apk``. Don't worry if you
  726.    get a warning about the possibility of rendering the file unusable. Go
  727.    ahead with the rename.
  729. On Your Android Device
  730. ~~~~~~~~~~~~~~~~~~~~~~
  732. 1) Go into ``Settings`` -> ``Security``, and ensure that ``Unknown Sources``
  733.    is enabled. This option says something like:
  735.       Allow the installation of apps from unknown sources
  737.    This is a one-time step. Once the box has been checked, it stays checked.
  739. 2) Copy the ``apk`` file to your device. There are a number of ways to do this:
  741.    * The easiest way may be to email it to yourself as a file attachment so
  742.      that it will go to the email on your Android device.
  744.    * Another option is to save the file in Dropbox on your computer, and
  745.      then wait for it to show up in Dropbox on your Android device.
  747.    * Another option is to connect your Android device to your computer via
  748.      a USB cable, and then to copy the file to it in the same way that
  749.      you'd copy a file to a thumb drive.
  751. 3) Tap the ``brltty-latest.apk`` file to start its installation, and answer any
  752.    prompts. If you use the Dropbox method, you might need to tap on the file
  753.    twice - once to download it, and a second time to install it.
  755. 4) Tap ``OK`` when installation is complete.
  757. Building BRLTTY
  758. ===============
  760. Preparing Your Host Environment
  761. -------------------------------
  763. BRLTTY is currently being built using:
  765. * Version |SDK build tools version| of the Android SDK build tools.
  766. * Version |NDK version| of the Android NDK.
  767. * Version |JDK version| of OpenJDK.
  769. You need the Android SDK (Software Development Kit) for:
  771. * installing an application onto your device
  772. * removing an application from your device
  774. You can get it from `The Android SDK Web Page`_.
  776. You need the Android NDK (Native Development Kit) if you want to do your own
  777. builds. You can get it from `The Android NDK Web Page`_.
  779. The SDK initially only includes support for the current Android API
  780. (Application Programming Interface) level. BRLTTY, however, needs to support
  781. earlier API levels so that it can run on older releases of Android. Support for
  782. any missing API levels is added whenever the SDK is updated. To do this, use
  783. the following command::
  785.   android update sdk -u
  787. The ``-u`` option, which is the short form of the ``--no-ui`` option, means to
  788. bypass the graphical interface.
  790. There may be password prompts for installing packages that are provided by
  791. various vendours. Any of these can be easily skipped.
  793. The 64-bit versions of the SDK and NDK depend on 32-bit system libraries. If
  794. you're using a 64-bit version then you need to first ensure that these are
  795. installed on your system. This at least includes:
  797. * libc6 (or glibc)
  798. * libz (or zlib)
  799. * libstdc++6 (or libstdc++)
  800. * libncurses
  802. If you're using a modern Debian GNU/Linux system (``Wheezy`` or later), you can
  803. install these packages for a foreign architecture (in this case, i386) with the
  804. following commands (as root)::
  806.    dpkg --add-architecture i386
  807.    apt-get install libncurses5:i386 libstdc++6:i386 zlib1g:i386 libc6:i386
  809. Installing and Preparing the BRLTTY Source Tree
  810. -----------------------------------------------
  812. Choose the directory that should contain BRLTTY's source tree (which needn't
  813. yet exist). Then extract the latest BRLTTY source into it with the following
  814. command::
  816.    git clone https://github.com/brltty/brltty.git /path/to/brltty
  818. The directory operand (of ``git clone``) is optional. If you don't specify it
  819. then the directory named ``brltty`` within the current working directory is
  820. assumed.
  822. Next, you need to prepare the source tree. This is done as follows::
  824.    cd /path/to/brltty
  825.    ./autogen
  827. At this point, the source tree is essentially just like what you'd get were you
  828. to unpack an officially released BRLTTY archive. It doesn't yet know anything
  829. about the specifics of your system. It also doesn't yet know anything about the
  830. platform you intend to build BRLTTY for.
  832. Adding information to BRLTTY's source tree regarding the specifics of your
  833. system, as well as of your intent to build BRLTTY for Android, is done as
  834. follows::
  836.    export ANDROID_NDK=/path/to/Android/NDK
  837.    ./cfg-android -q
  839. The ``-q`` option, which is the short form of the ``configure`` command's
  840. ``--quiet`` option, means to not display any progress information (there's
  841. usually quite a lot of it) - only warnings and errors are displayed.
  843. All of the options you give to the ``cfg-android`` command are passed directly
  844. through to the ``configure`` command. So, while ``cfg-android`` supplies a
  845. default set of options to ``configure``, it's easy for you to do your own
  846. customization.
  848. Building BRLTTY for Android
  849. ---------------------------
  851. In order to be able to build an Android application, a number of Android build
  852. tools need to be added to your command search path. This is done via the
  853. following command::
  855.    export PATH="/path/to/Android/SDK/tools:/path/to/Android/SDK/platform-tools:$PATH"
  857. The final step is to build the BRLTTY service for Android. This is done as
  858. follows::
  860.    cd /path/to/brltty/Android/Application
  861.    make -s
  863. The ``-s`` option of the ``make`` command, which is short for its ``--silent``
  864. option, means to not display any progress information (there's usually quite a
  865. lot of it) - only warnings and errors are displayed.
  867. The result of the build is the file ``BRLTTY_App-debug.apk``. It will be in the
  868. ``bin/`` subdirectory of BRLTTY's Android Application directory::
  870.    /path/to/brltty/Android/Application/bin/BRLTTY_App-debug.apk
  872. ``apk`` is the file extension used for an installable Android package.
  874. Preparing Your Android Device
  875. -----------------------------
  877. You need ``USB Debugging`` to be enabled. This is done from the ``Developer
  878. Options`` screen. You can get to it from the ``Settings`` screen.
  880. Launch the ``Settings`` application, and look, near the bottom, for ``Developer
  881. Options``. If you can't find it, the most likely cause is a new feature that
  882. was introduced in Android 4.2 (Jelly Bean). If you need to enable it, tap on
  883. ``About Phone``, which, again, can be found near the bottom of the ``Settings``
  884. screen. Then, on the ``About Phone`` screen, look for the ``Build Number``
  885. line. Tap on ``Build Number`` seven times and your device will officially
  886. declare you to be a developer. You should then be able to find ``Developer
  887. Options`` on the ``Settings`` screen.
  889. There's a check box at the top-right of the ``Developer Options`` screen. It
  890. needs to be checked so that all of the other controls on that screen will be
  891. enabled. After doing that, check the ``USB Debugging`` check box (which can be
  892. found within the ``Debugging`` section). This enables the ``adb`` (Android
  893. Debug Bridge) tool to perform functions on your Android device.
  895. Installing BRLTTY on Your Android Device
  896. ----------------------------------------
  898. In order to install BRLTTY onto your device, or to remove it from your device,
  899. you need to be in BRLTTY's Android Application directory::
  901.    cd /path/to/brltty/Android/Application
  903. You also need to connect your device to your host via USB.
  905. To install BRLTTY, use this command::
  907.    make -s install
  909. To remove BRLTTY, use this command::
  911.    make -s uninstall
  913. The ``make install`` command will fail if BRLTTY is already installed. If
  914. you're wanting to upgrade BRLTTY, however, then removing it first is probably
  915. what you don't want to be doing. This is because removing BRLTTY also causes
  916. its settings to be lost. What you should do instead is reinstall it. You can do
  917. this with the following command::
  919.    make -s reinstall
  921. If you've obtained your Android package file (``apk``) for BRLTTY from some
  922. other source (than building it for yourself), then it may have a different name
  923. than the make file is expecting. It's useful, therefore, to know what the
  924. actual host commands are for installing and removing Android applications.
  926. The host command for installing an Android application is::
  928.    adb install /path/to/file
  930. The host command for reinstalling an Android application is::
  932.    adb install -r /path/to/file
  934. The host command for removing an Android application is::
  936.    adb uninstall application.package.name
  938. So, to remove BRLTTY, the host command is::
  940.    adb uninstall org.a11y.brltty.android
  942. If any of these ``make`` or ``adb`` commands fails with an error like ``device
  943. not found``, it's probably because your host's USB device permissions are
  944. requiring root access. The solution to this problem is to restart the ``adb``
  945. server such that it is running as root. With this done, you yourself will still
  946. be able to use ``adb`` as a regular user.
  948. The commands to restart the ``adb`` server such that it's running as root are
  949. as follows::
  951.    su
  952.    cd /path/to/Android/SDK/platform-tools
  953.    ./adb kill-serv

Raw Paste

Login or Register to edit or fork this paste. It's free.