Note: Folk is in a pre-alpha state and isn't yet well-documented or well-exampled.

We're making Folk's source code free and available to the public, in case you're already excited about trying it, but we haven't formally announced it or made it ready for public use. We make no guarantee of support, of usability, or of continuing backward compatibility. Try at your own risk!

We're working on a more formal announcement, which will talk more about the goals of the project & provide canonical examples/demos to show what's possible. If you don't know what this is, then you might want to wait for that release.

---

Folk

Folk is a physical computing system: reactive database, programming environment, projection mapping. Instead of a phone/laptop/touchscreen/mouse/keyboard, your computational objects are physical objects in the real world, and you can program them inside the system itself. Folk is written in a mix of C and Tcl.

Installation

Hardware

You'll need to set up a dedicated PC to run Folk and connect to webcam+projector+printer+etc.

We tend to recommend a Beelink mini-PC (or maybe a Pi 5).

See https://folk.computer/pilot/

Manual Linux tabletop installation

On an Intel/AMD PC, set up Ubuntu Server 24.04 LTS (Noble Numbat).

(if you have an NVIDIA GPU, don't install the drivers in the Ubuntu OS installer. we'll install manually later. or if you do, install driver version 570 or newer)

(for a Pi 4/5, use Raspberry Pi Imager and get Raspberry Pi OS Lite 64-bit version [also see this issue if flashing from a Mac] -- Ubuntu doesn't have a good kernel for Pi 5)

1. Install Linux with username folk, hostname folk-SOMETHING? (check hosts.tcl in this repo to make sure you're not reusing one)

   If no folk user, then:

    sudo useradd -m folk; sudo passwd folk
   

   Add the folk user to groups:

    for group in adm dialout cdrom sudo audio video plugdev games users input tty render netdev lpadmin gpio i2c spi; do sudo usermod -a -G $group folk; done; groups folk
   

2. sudo apt update

3. Set up OpenSSH server if needed; connect to network. To ssh into folk@folk-WHATEVER.local by name, sudo apt install avahi-daemon and then on your laptop: ssh-copy-id folk@folk-WHATEVER.local

4. Install dependencies: sudo apt install rsync git cmake patchelf libturbojpeg0-dev libpng-dev libdrm-dev pkg-config v4l-utils vulkan-tools libvulkan-dev libvulkan1 meson libgbm-dev glslc vulkan-validationlayers ghostscript console-data kbd psmisc zlib1g-dev libssl-dev automake libtool autoconf-archive

   (When prompted while installing console-data for Policy for handling keymaps type 3 (meaning 3. Keep kernel keymap) and press Enter)

   1. on a non-NVIDIA GPU: sudo apt install mesa-vulkan-drivers
   2. on an NVIDIA GPU: run sudo ubuntu-drivers install nvidia:580
   3. for debugging: elfutils (provides eu-stack), google-perftools, libgoogle-perftools-dev

5. Vulkan testing (optional):

   1. Try vulkaninfo and see if it works.

      1. On a Pi, if vulkaninfo reports "Failed to detect any valid GPUs in the current config", add dtoverlay=vc4-kms-v3d to the bottom of /boot/firmware/config.txt. (https://raspberrypi.stackexchange.com/questions/116507/open-dev-dri-card0-no-such-file-or-directory-on-rpi4)

   2. Try vkcube:

      git clone https://github.com/krh/vkcube
      cd vkcube
      mkdir build; cd build; meson .. && ninja
      ./vkcube -m khr -k 0:0:0
      

      If vkcube says Assertion ``vc->image_count > 0' failed, you might be able to still skip vkcube and continue the install process. See this bug

   3. See notes and Naveen's notes.

6. sudo sh -c 'echo SUBSYSTEM=="input", GROUP="input", MODE="0666" > /etc/udev/rules.d/99-input.rules && udevadm control --reload-rules && udevadm trigger'

7. Add the systemd service so it starts on boot and can be managed when you run it from laptop. On Ubuntu Server or Raspberry Pi OS (as root) (from here):

   # cat >/etc/systemd/system/folk.service
   [Unit]
   Description=Folk service
   After=network.target
   StartLimitIntervalSec=0
   
   [Service]
   Type=simple
   Restart=always
   RestartSec=1
   User=folk
   WorkingDirectory=/home/folk/folk
   ExecStart=make -C /home/folk/folk start
   
   [Install]
   WantedBy=multi-user.target
   

   Run these commands as root after editing the file above:

   # chmod 644 /etc/systemd/system/folk.service
   # systemctl start folk
   # systemctl enable folk
   

Use visudo to add folk ALL=(ALL) NOPASSWD: /usr/bin/systemctl to the bottom of /etc/sudoers on the tabletop. (This lets the make scripts from your laptop manage the Folk service by running systemctl without needing a password.)

To compile and run Folk:

$ make deps
$ make && ./folk

or (if remote machine):

$ make remote FOLK_REMOTE_NODE=<your-remote-hostname-here>

On your laptop Web browser, go to http://<your-remote-hostname>.local:4273 -- you should see all active Folk programs. Check out the Statements page as well to see all statements in the database.

Printer support

On the tabletop:

$ sudo apt update
$ sudo apt install cups cups-bsd
$ sudo usermod -a -G lpadmin folk

(cups-bsd provides the lpr command that we use to print)

ssh tunnel to get access to CUPS Web UI: run on your laptop ssh -L 6310:localhost:631 folk@folk-WHATEVER.local, leave it open

Go to http://localhost:6310 on your computer, go to Printers, hopefully it shows up there automatically, try printing test page. I could not get that implicitclass:// automatically-added printer in CUPS to work for my printer at all, so I did the below:

If job is paused due to cups-browsed issue or otherwise doesn't work, try https://askubuntu.com/questions/1128164/no-suitable-destination-host-found-by-cups-browsed : remove cups-browsed sudo apt-get purge --autoremove cups-browsed then add printer manually via IPP in Add Printer in Administration tab of CUPS Web UI (it might automatically show up under Discovered Network Printers there using dnssd)

Once printer is working, go to Administration dropdown on printer page and Set as Server Default.

Try printing from Folk!

You can also test printing again with lpr ~/folk-data/program/SOMETHING.pdf (you have to print the PDF and not the PS for it to work, probably)

Projector-camera setup and calibration

1. Make sure Folk is running. Go to your Folk server's Web page http://whatever.local:4273/setup . Select your camera and projector, using as high framerate and resolution as you're comfortable with.

2. You should see a live preview of the camera. Reposition your camera to cover your table closely (try not to waste too much of the camera viewport on pixels that the projector won't be able to hit)

3. Select your camera and projector at the bottom and then click Calibrate. Follow the calibration instructions.

After calibrating, on http://whatever.local:4273/ : click New Program, hit Save, drag it around. You should see the program move on your table as you drag it around on your laptop.

Connect a keyboard

Follow the instructions on this Folk wiki page to connect a new keyboard to your system.

Bluetooth keyboards

Install bluetoothctl. Follow the instructions in https://wiki.archlinux.org/title/bluetooth_keyboard to pair and trust and connect.

(FIXME: Write down the Bluetooth MAC address of your keyboard. We'll proceed as though it's "f4:73:35:93:7f:9d" (it's important that you turn it into lowercase).)

Python support

To use the Python FFI and the builtin recognition programs (CRAFT, TrOCR, SAM2), you should install uv such that the uvx command is available.

Development tools

Address Sanitizer

Address Sanitizer (ASan) support can be enabled by setting the ASAN_ENABLE environment variable:

make ASAN_ENABLE=1

Then when running:

ASAN_ENABLE=1 make start

Tracy profiling

To use Tracy, first do git submodule update --init here.

Pass CFLAGS=-DTRACY_ENABLE to make when compiling Folk (you might need to clean first if you already built Folk).

Ideally, run Folk as root with sudo ./folk or make sudo-remote.

Build the profiler client on your laptop/other PC:

$ cmake -B vendor/tracy/profiler/build -S vendor/tracy/profiler -DCMAKE_BUILD_TYPE=Release
$ make -C vendor/tracy/profiler/build

Run the profiler client on your laptop/other PC and connect to a running Folk:

$ make run-tracy

Potentially useful

Potentially useful for graphs: graphviz

Potentially useful: gdb, streamer, cec-utils, file, strace

Potentially useful: add folk-WHATEVER shortcut to your laptop ~/.ssh/config:

Host folk-WHATEVER
     HostName folk-WHATEVER.local
     User folk

Potentially useful: journalctl -f -u folk to see log of folk service

For audio: https://askubuntu.com/questions/1349221/which-packages-should-be-installed-to-have-sound-output-working-on-minimal-ubunt

Troubleshooting

HDMI No signal on Pi 4

Edit /boot/cmdline.txt https://github.com/raspberrypi/firmware/issues/1647#issuecomment-971500256 (HDMI-A-1 or HDMI-A-2 depending on w