This guide is intended for those who are more experienced (or are not very experienced but want to learn more technically advanced things), about the F123Light operating system. Should you need information about the overall strategy of the project, our motivations, or other non-technical matters, please read our general project guide.

Should you have suggestions, corrections, new content, new code, or other contributions to this project, please join one of our e-mail lists and let us know about it.

1 Building Your Own F123Light Image

Experienced users have the option of generating or building their own image. Every copy of F123Light includes the command “build-f123light”, which automatically generates the image file, which can then be burned or flashed to a MicroSD card for use.

To build a new image, you will need to make sure you have at least 8GB of free space. You may need aditional space for the work directory. If you try to build an image with out enough free space the script will alert you to the issue and stop.

To build an image with all default parameters, go to the command line and enter the following:

build-f123light

1.1 Burning/Flashing Your New Image Using the Command Line

Experienced or ambitious users can burn the image they have just built on their own Raspberry Pi by using the “sudo fdisk -l” command to identify which device or drive name to use, after plugging-in the USB adapter containing the target MicroSD card.

Warning: This is a risky procedure, so it should not be attempted by inexperienced users or those with valuable information on their computers, or who do not have an up-to-date backup of same.

Once the user has identified what device holds his or her operating system, and which device will be used to burn the image, the user can type something like the following to actually flash the image which was just created:

sudo dd if=filename of=device-path bs=2M

The “sudo” string is used for important commands which require admin powers. The “dd” command is also called disk-dump, and it is used to make exact copies of disks or to burn images on same. The “if” and “of” parameters, stand for input file and output file, and the “bs” parameter stands for block size. Specifying block size is optional, but we have found that using “2M” speeds-up the process. Do note that the “M” in this parameter must be capitalized.

1.2 Updating F123Light on the Command Line

Advanced users can perform an update from the command line with the command:

update-f123light

If such a user is helping us test recent changes to the code, he or she can use a special parameter to update from the development branch. To specify the development branch, the correct command would be:

update-f123light -b dev

1.3 Build a Custom Image

To build a new image, you will need to make sure you have at least 8GB of free space. You may need aditional space for the work directory. If you try to build an image with out enough free space the script will alert you to the issue and stop.

You can customize your image by passing special parameters to it. Here is a list of things you can customize about your image:

Here are a couple of examples of building an image with some parameters given on the command line:

build-f123light --output-file custom.img

This will make an image called custom.img.

build-f123light -n wifi-network-name -w 'your-password'

This example creates an image which already contains your Wifi login, so you will not have to re-enter your WiFi password at boot time. Just like the two examples above, you can enter all the parameters listed above and the image will be built with all that information already included.

1.4 Important locations and File Structure

With the exceptions of update-f123light, build-f123light, and first-boot, the scripts that power F123Light reside in the /usr/lib/F123-wrappers and /usr/lib/F123-includes directories.

Each file is named according to what it does, and there is a brief description at the top of the file with the copyright notice. The files in /usr/lib/F123-wrappers are the end product that present information to the user. The files in /usr/lib/F123-includes are functions and code that gets reused almost everywhere to make things easier to extend.

So, to have menus and input boxes, etc, similar to what we use, you can include something like the following in your scripts:

# Load F123 includes
if [[ -d /usr/lib/F123-includes/ ]]; then
for i in /usr/lib/F123-includes/*.sh ; do
        source $i
done
fi

If you need to interact with the preferences, which include such things as tip display options, preferred browser, email client, etc, you can get access to it by sourcing the ~/.preferences file like so:

source ~/.preferences

Preferences are stored in an associative array. In order to keep the preferences file well formatted and readable, when writing new preferences please use the write_preferences function defined in /usr/lib/F123-includes/preferences-manager.sh.

F123Light specific overwrites for applications are in /etc/F123-Config/. This allows different behavior for applications such as irssi when called from the help menu as apposed to when it is called by the user specifically. Users will be able to customize their day to day copy of irssi as much as they want, and the chat support option from the menu will still work as designed when needed.

Also in /etc/F123-Config/ is a subdirectory called backup. This contains a copy of speechd.conf and any other files that may be necessary to reset something vital to a working state.

2 Fenrir - A Modern Console Screen Reader

2.1 Selecting Fenrir Screen Reader Branches

Sometimes you may want to try a new feature in Fenrir that has not made it to the stable release. For this, you can exit to the command line, then run the following command:

select-fenrir

You will be presented with a list of branches in the git repository. Simply select the branch you want a and press enter. The current version of Fenrir will shut down and the version from the selected branch will start.

There are safeguards in place to make sure you do not end up with a broken Fenrir. If you hear Fenrir speaking, you can press enter to use the selected version. If you do not press enter with in 30 seconds, the computer will restart and you will be using the stable, installed version.

You can get back to your installed copy of Fenrir by selecting “stable” from the list of branches or by restarting your computer. Also, if you already know the branch you want, you can specify it on the command line and skip the menu system altogether. For example, type the following to launch Fenrir from the master branch:

select-fenrir master

2.2 Fenrir Virtual Menus

Fenrir has a new feature that will perform key presses for you. This feature is very powerful, because it can provide easy to use shortcuts and menus that work the same across applications.

For example, if you have two editors, Nano and Vim, they save files in different ways. In F123Light, to save a file in Nano, you press control+s. In Vim, however, you must make sure you are in command mode by pressing the escape key, then enter the command :w. If Fenrir has a menu defined for both text editors, you could simply activate the menu by pressing Fenrir+F10 or Fenrir+Alt, then press f for files, and s for save.

You can also use the arrow keys and enter to select menu choices. If you open the menu and change your mind, simply press escape to close it. If you type a letter that does not exist as a menu option, Fenrir will make an error sound.

You can already try virtual menus on the Nano text editor.

2.3 Creating a Virtual menu in Fenrir

Since F123Light uses many console applications with non-standard keybindings, the virtual menu is a Fenrir add on which will translate more conventional key combinations into those unusual ones, so the end-user does not have to worry about learning entirely new keyboard shortcuts.

Fenrir is a flexible framework to create screenreaders for the commandline. It is entirely plugin driven. The virtual menu is no different, as it uses the same simple structure. Its a class named command() with 3 funktions:

  1. initialize(environment) Is invoked by fenrir while loading. The Parameter „environment“ is the complete fenrir runtime, drivers, managers, settings and all kinds of data. Its like the engine in an car. This is the most complex part. Anybody interested in additional details in this area should ask about it in: <mumble.linux-a11y.org> or <irc.linux-a11y.org>.

  2. getDescription() returns a text spoken in tutorial mode or is used as menu entry name.

  3. run, this is fired on activation. It can access all kind of information and functionality with environment.

Especially for virtual menu, we have created a key sequencer that uses evdev key names with states. A special sequence name with the name sleep gives a small break.

The menu by itself is structured by folders. With KEY (for key devices) and BYTE for terminal emulation (using escape sequences). Above those folders is a folder per application, as shown below. The user can be locked in those applications menus using the remote manager so they will not get confused by wrong entrys)

For F123Light, the code for virtual menus resides in: /usr/share/fenrirscreenreader/menus/KEY/

Inside this directory is the actual macro structure. The Directories directly under KEY are application names that contain the menu for the application.

% ls
vim/  nano/  mutt/  mc/

Inside those directories are the actual virtual menu directories, so “file”, “Tools”, etc.

Here, from the File directory for Nano, is the save command. This activates control+S which is the Fenrir command for Nano. Description is the help text for it if you are trying to learn the keys.

# Code

#!/usr/bin/env python
# -*- encoding: utf-8
from fenrirscreenreader.core import debug


class command():
    def __init__(self):
        pass

    def initialize(self, environment):
        self.env = environment
        self.keyMakro = [[1, 'KEY_LEFTCTRL'],
                         [1, 'KEY_S'],
                         [0.05, 'SLEEP'],
                         [0, 'KEY_S'],
                         [0, 'KEY_LEFTCTRL']]

    def shutdown(self):
        pass

    def getDescription(self):
        return "Save your work."

    def run(self):
        self.env['runtime']['outputManager'].presentText(
            "Okay, you will now be asked to save your work.", interrupt=True)
        if self.env['runtime']['inputManager'].getShortcutType() in ['KEY']:
            self.env['runtime']['inputManager'].sendKeys(self.keyMakro)
        elif self.env['runtime']['inputManager'].getShortcutType() in ['BYTE']:
            self.env['runtime']['byteManager'].sendBytes(self.byteMakro)

    def setCallback(self, callback):
        pass

# End Code

2.4 Fenrir Resources and Contacting Developers

The best places to find Fenrir contributors are:

3 Customizing the F123Light Menus

You may want to add your favorite application to the menu system for easy launching. To do this, create a file called menu under ~/.config/F123 like this:

mkdir -p ~/.config/F123
nano ~/.config/F123/menu

The process for adding a command line based application is pretty straight forward. This, for example, will add vim:

exec:Vim Text Editor::vim

Some applications require special directives to pdmenu, those that do not stay open for example, may need the pause flag. For more information, please read:

man pdmenurc

Adding graphical applications, such as chromium takes a bit more work. To do this, we have to suspend Fenrir so that it and Orca aren’t trying to read at the same time. We then have to call the graphical application with a special script that loads all the X session components and starts the Orca screen reader. Here is an example to add lxterminal to your personal menu:

group:LXTerminal
exec:::python /usr/share/fenrirscreenreader/tools/fenrir-ignore-screen &> /dev/null
exec:::echo -n "setting set screen#suspendingScreen=$(</tmp/fenrirSuspend)" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
exec:::startx /usr/lib/F123-wrappers/xlauncher lxterminal
exec:::python /usr/share/fenrirscreenreader/tools/fenrir-unignore-screen &> /dev/null
exec:::echo -n "setting set screen#suspendingScreen=$(</tmp/fenrirSuspend)" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
endgroup

Notice that there are some execs even after the lxterminal application is called. This is to restore Fenrir so it will begin reading again after the X session closes.

3.0.1 Finding Binary Application Files

You will usually find binary application files at: /usr/bin

If you are ever unsure though, the following command will show you where it is, assuming it is in your executable path:

command -v application-name

For example:

% command -v firefox
/usr/bin/firefox

Please note that the “$” symbol is usually used to indicate the command line prompt. In F123Light, we use the “%” symbol, but this can be easily changed.

4 F123Light Modes

in order to help keep clutter down, and to make things more efficient, F123Light offers modes that change the way it presents information. For now, this mostly means different menus, but as this service grows, it could potentially change nearly every aspect of the system.

Only someone with administrative access can change modes, and only by running a command from the command line. To change modes, run the following command:

sudo /usr/lib/F123-wrappers/change-mode.sh

You will be presented with a menu of all available modes. Just arrow to the one you want and press enter to activate it. If you already know the mode you want, simply specify it at the end of the command above.

The idea behind modes is to have a “default” mode, which only shows the most user-friendly software; a “test” mode, which might be used to administer tests in schools; and “admin” or “advanced” mode, which will give full access for those who are sophisticated users of technology; and other modes such as games, will certainly be suggested by our users.

5 Troubleshooting Problems

In this section we have suggestions regarding how you may investigate problems with your software. The idea is to help you figure things out on your own, or at the very least, help you find information which might allow others to help you more rapidly.

5.1 Troubleshooting update-f123light

5.1.1 Update Problems with Version 19.02.04 of F123Light

For some users, it was necessary to run the update option under the ‘Settings’ menu, twice, and then their version got correctly updated. If that does not solve your problem, you might want to research further.

5.1.2 Logs and More

You will probably find helpful details in this log:

/var/log/update-f123light.log

You might also want to try this command for more potentially useful information:

pacman -Qi update-f123light-git

Finally, this command might help with updates, and if there are none, then that is good to know as well:

yay -Syu

5.2 WiFi Issues

The Raspberry Pi 3B+ works with WiFi channels 1 through 11, but some networks are configured to use channels 12 or 13. Please check if this is the case with the network giving you problems. The solution would be changing the configuration of the WiFi router so it can operate with channels 1 through 11.

Another potential problem is the frequency being used by your WiFi network. If your WiFi router uses the 5GHz band only, older Raspberry Pi models will not see it. Only the Raspberry Pi 3B Plus, is capable of handling both 2.4GHz and 5GHz. Although our software is developed and supported for the Model 3B+, sometimes people use it on older Raspberry Pis, which in this case, prevents them from accessing 5GHz WiFi networks.

6 Source Code for F123Light

F123Light is based on Arch Linux, so the following address is only relevant for the customizations our team has made to that distribution:
https://gitlab.com/f123/

This work by F123 Consulting is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. We also have another way for you to freely use our content, if this license does not meet your needs. Contact us for alternative licensing options.