Occurity

What it is

Occurity is a fully-featured patient visual acuity test software designed for use on the RaspBerry Pi hardware platform. It enables you to built an affordable visual acuity test system using a few pieces of hardware and basically any remote control. If you do not have the option to buy the infrared receiver, it can also be used with a keyboard.

Included tests

• ETDRS, HOTV, numbers, Landolt C and Tumbling E charts
• Astigmatism dots and astigmatism rays charts
• Coincidence, Worth 4 dots and mirrored RED / GREEN charts

License

Occurity is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

What you need

Hardware

In order to install a system running Occurity you need the following hardware:

Required

• A Raspberry Pi (3 or 4, 4 required for attention video support)
• At least a 2 GB SD flash card
• A monitor with at least 300 cd/m² brightness (preferably 350 cd/m²)

Optional

• A Flirc infrared reciever
  • A remote control that works with flirc. Most do.

Monitor

Resolution

Occurity displays correctly on any monitor using any resolution provided the following two requirements are met:

• The physical length of the blue ruler must be set correctly in the Occurity Preferences dialog.
• The physical distance from the patients eyes to the monitor must be set correctly in the Occurity Preferences dialog.

To test if the monitor you are using reports its resolution correctly to the Occurity software, please set the physical width of the blue ruler in the Preferences dialog. Then temporarily set the patient distance to 400 cm and 600 cm respectively and make sure the width of the optotype symbols match with the table below. If they do your monitor will work correctly with Occurity. |Patient distance|Chart size|Expected symbol width| |----------------|----------|---------------------| |600 |0.1 |87 mm | |600 |0.25 |35 mm | |400 |0.1 |58 mm | |400 |0.25 |23 mm |

Brightness calibration

DISCLAIMER!!! This is only a guideline: Using a lux meter pushed up against the monitor surface, you should have a readout of about 260 lux. Hence the need for a monitor that is capable of a high brightness level.

Power delivery

A useful feature to look out for when choosing a monitor is the support for USB-C PD (Power Delivery). With this feature there is a good chance you will be able to power the Raspberry Pi directly from the monitor using a USB-C cable. This removes the need for a separate Raspberry Pi power supply making the entire solution more self-contained.

Tested working with the following monitor

• 24" AOC Basic-line 24B3CF2

Remote controls

Tested working with the following remote controls

• LG AKB75095344
• Samsung AA59-00818A

In theory most remote controls you might have lying around should work with the disclaimer that there are some remotes that use dual-output signals which makes them hard to use with the flirc interface. Only way to know is to just try.

Note! The Flirc infrared reciever emulates a keyboard. For the remote to work, you need to install the Flirc software on a supported OS and configure the buttons on your remote to correspond with these keyboard keys.

How to install Occurity

You have two options for installing and running Occurity. Either use the pre-built SDCard images or built one yourself from scratch.

Option 1: Using a pre-built SDCard image

If you require no customization of the image (you probably don't) this is the easiest way to get up and running. Simply download the SDCard image corresponding to your Raspberry Pi from the latest release files. Decompress the gzipped image and flash it to an SDCard (the Raspberry Pi Imager works well for this task, just choose Use custom image and set it to show All files to choose the image). Insert the SDCard in your Raspberry Pi and you are done! Be sure to check the rest of the documentation on how to use Occurity.

Option 2: Building a custom Occurity SDCard image

The step-by-step procedure for building an Occurity image that can be flashed to an SDCard for the Raspberry Pi hardware platform is described in detail below. The build is currently based on the scarthgap release of the very popular Yocto embedded platform.

The only pre-requisite is a recent working Ubuntu installation with at least 150 GB available harddrive space. The final SDCard image will be about 1 GB. You might also be able to make this work on any previous or later Ubuntu LTS release. The main difference will probably be the package pre-requisites. Refer to the official Yocto documentation for further information.

Package pre-requisites

Install the required packages by running the following two commands:

$ sudo apt install gawk wget git diffstat unzip texinfo gcc build-essential chrpath socat cpio python3 python3-pip python3-pexpect xz-utils debianutils iputils-ping python3-git python3-jinja2 python3-subunit zstd liblz4-tool file locales libacl1
$ sudo locale-gen en_US.UTF-8

If some or more of these packages do not exist on your system they might be different for your specific version of Ubuntu. Please read the official Yocto documentation if that is the case.

Setting up Yocto

Run the following commands to clone Yocto and the required layers. The source command sets up the environment required for building the image. If you wish to rebuilt the image later you need to re-run this source command in order for the bitbake related tools to be available and configured:

$ cd
$ git clone https://git.yoctoproject.org/poky
$ cd poky/
$ git checkout -t origin/scarthgap -b occurity
$ git clone -b scarthgap https://git.yoctoproject.org/meta-raspberrypi
$ git clone -b scarthgap https://github.com/openembedded/meta-openembedded
$ git clone https://code.qt.io/yocto/meta-qt6
$ git clone https://github.com/muldjord/meta-occurity
$ source oe-init-build-env
$ bitbake-layers add-layer ../meta-raspberrypi
$ bitbake-layers add-layer ../meta-openembedded/meta-oe
$ bitbake-layers add-layer ../meta-openembedded/meta-python
$ bitbake-layers add-layer ../meta-qt6
$ bitbake-layers add-layer ../meta-occurity

Add required Yocto configs

You should now be at the poky/build directory. Edit conf/local.conf and add the following lines to the very top of the file:

LICENSE_FLAGS_ACCEPTED = "synaptics-killswitch commercial"
WKS_FILE = "sdimage-raspberrypi.wks"
IMAGE_FSTYPES += "wic.gz wic.bmap"
DISABLE_OVERSCAN = "1"
MACHINE ?= "raspberrypi4-64"

NOTE!!! If you are building for a Raspberry Pi 3 change the MACHINE to raspberrypi3-64.

Build the image

You are now ready to build the image. Depending on your host machine this can take a long time (several hours). Run the following commands to start the build. You should run this command from the poky/build directory:

$ bitbake core-image-sato

Bitbake is Yocto's build system. It pulls in all required source code and compiles and configures everything needed for an embedded Linux system running Occurity on a Raspberry Pi.

Troubleshooting

If you get an error when running the bitbake core-image-sato command your system might have a strict App-Armor setup that disallows Bitbake to run well in user-space (this has been observed on a clean Ubuntu 24.40 installation). You need to create a special rule for it before it will work. To fix this, you can create the file /etc/apparmor.d/bitbake with the following contents:

abi <abi/4.0>,
include <tunables/global>
profile bitbake /**/bitbake/bin/bitbake flags=(unconfined) {
        userns,
}

Then restart the apparmor service and you should be able to built the image.

$ sudo systemctl restart apparmor

Flash the final image to an SDCard

If everything went well you will now have a working Occurity image at poky/build/tmp/deploy/images/raspberrypi4-64/core-image-sato-raspberrypi4-64.rootfs.wic.gz. Be aware that this is a symbolic link - the actual file is placed in the same directory but has a timestamp in the filename.

Decompress the gzipped image and flash it to an SDCard using your favorite SDCard flashing tool (the Raspberry Pi Imager works well for this task, just choose Use custom image and set it to show All files to choose the image). Insert the card into your Raspberry Pi and boot it up. After a little while Occurity will be automatically launched. Be sure to check the rest of the documentation on how to use Occurity.

Building Occurity on Ubuntu 24.04

NOTE!!! If you've already downloaded or built the Raspberry Pi Yocto image as documented above you do not need to continue with these instructions. The following describes how to compile and run Occurity on Ubuntu for anyone who wishes to do so.

Software prerequisites

Run the following commands in a terminal on Ubuntu to install the prerequisites needed for Occurity to function correctly.

$ sudo apt update
$ sudo apt install build-essential git cmake qt6-base-dev qt6-svg-dev qt6-multimedia-dev qt6-tools-dev