Last modified: 2021-09-10 20:44


About uxfs

uxfs is a brigde to implement user interfaces (to what is called a "controller") as a virtual filesystem.

I created uxfs to have access to hardware on the Raspberry Pi. Additional hardware comes usually with python modules to access them, but python is not my preferred language (as you will see when you look at With the combination of uxfs and I'm able to access to access the Pi's Sense HAT directly from within a shell script, e.g.

echo 100 50 200 >/path/to/d/dot-21

Of course, this could have also been done by writing an appropriate python script.

So, what is uxfs not? Neither uxfs nor its controller create any magic that isn't already available. They just create a virtual filesystem as interface to it. (It is said, that in UNIX everything is a file.)

So what does "... is a bridge ..." mean?

  1. uxfs interfaces with libfuse to expose a virtual filesystem to user processes.

  2. Read-write operations are send to uxfs's controller and are processed there.

  3. uxfs itself does not implement any of the controller's application logic. It is just a relay and the controller has full control about what is going on (and must implement it).


uxfs is only a translator for filesystem operations. It communicates with its controller via a simple line protocol. I have added two examples. They actually do the same but the way how they are started is different to demonstrate uxfs' two innvocation methods.

Use the scripts and uxfs's manpage to understand the protocol.


You need libfuse-dev to compile uxfs:

sudo apt-get install libfuse-dev fuse

Of course you need a C compiler and linker too, but I think that's obvious, right?

Download and untar the latest tar archive, then run

CFLAGS="-D_FILE_OFFSET_BITS=64 -I/usr/include/fuse"
gcc -O2 -Wall -DVERSION=\"$(VERSION)\" $CFLAGS -c -o uxfs.o uxfs.c
gcc -o uxfs uxfs.o -lfuse -pthread

or you run make uxfs if you have that installed too. There is no make target to install uxfs.

$ sudo cp uxfs /usr/local/bin
$ sudo sp uxfs.1 /usr/local/man/man1

should do that.


If you have a Raspberry Pi Sense HAT or python's Sense HAT Emulator module (from sense_emu import SenseHat) installed you can try

mkdir -p x  &&  ./uxfs ./x -- ./

and then

echo 100 50 200 >x/d/dot-21
echo "Hello World!" >x/print/text

in another shell. You might run also run ./random.awk x. Use

echo >x/shutdown

to terminate the controller (and the virtual filessystem).

ux-test-stdio and ux-test-main are also examples but more boring because they don't interact with any hardware. Start them with

mkdir -p x  &&  ./uxfs ./x -- ./ux-test-stdio


mkdir -p x  &&  ./ux-test-main

ux-test-main and ux-test-stdio do the same thing and the only difference is their invocation and how they talk to uxfs. Interact with the files and watch ux-stdio-test's output to get an idea of uxfs's protocol. Look into the script code for more information and read the manpage. To test something more advanced run

mkdir x/test
echo 3 >x/test/a
echo 4 >x/test/b
cat x/test/c

Again, use

echo >x/shutdown

to terminate the program.

uxfs and the controller don't have to run on the same host. Setups like

./uxfs ./x -- ssh -l pi pi-400 "/path/to/uxfs/"

are possible too.