diff --git a/README.md b/README.md
new file mode 100644
index 0000000..32cb245
--- /dev/null
+++ b/README.md
@@ -0,0 +1,106 @@
+# pozytywny sejf™
+
+## What is this?
+
+Pozytywny Sejf™ is an entertainment device - essentially an inside-out escape
+room.
+
+A 80x80x80cm box where each of four sides have ~8-10 different tasks to solve.
+Every side contains:
+
+* 6 "slots" for replaceable hardware modules
+* an ~12" 1280x1024 LCD screen in the middle
+* a "status indicator" slot above the screen - 10 RGB LEDs indicating tasks progress
+* a drawer with a PIN entry keyboard
+* (optional, present on one of the sides) extra drawer for final game reward
+
+Main point of this project is to design a framework for these types of
+entertainment devices, and some reference game task modules.
+
+## Hardware
+
+### Furniture
+
+80x80x80cm wooden box holding all the modules.
+
+#### Wiring
+
+All module slots should have CAT5e RJ45-terminated input/output cables available.
+Whenever a slot does not use a sejfduino module in a specific game - an RJ45 coupler
+should be used.
+
+"Status indicator" is not generally meant to be replaceable. Some extra hardware
+features like game finish siren/lamp or extra game finish drawer will be
+controlled via its sejfduino board.
+
+Certain slots may have extra 12v high power Tamiya connector exposed.
+
+Certain slots may have extra USB female port available for custom functionality
+(eg. extra audio interface for microphone/speaker)
+
+All wiring runs going to module slots shall have enough slack for simple
+maintenance (module removal *before* disconnecting of its cabling)
+
+Main 5v/12v power will be provided by a central ATX power supply.
+
+Raspberry Pi boards should be connected to a 5-port ethernet switch, with static
+IPv4 networking set up (with "master" board exposing a management/debugging
+DHCP server)
+
+The only cable coming out of the Furniture shall be a 230v power lead.
+
+Only cabling shared between "sides" shall be ethernet data and 12v power.
+UBus/RS485 *must not* be shared between multiple sides - each "side" has its own
+separate bus managed by its Raspberry Pi board.
+
+### sejfduino
+
+A custom Arduino-style board with several special features:
+
+* ATMega328PB running at 16MHz - compatiblity with a lot of arduino boards
+* 8P8C/RJ45 input/output connectors for 12v power and RS485 half-duplex
+  communication bus. If a module is removed, it can be easily replaced with
+  a dumb RJ45 coupler, keeping all the wiring inside.
+* Arduino Pro Mini-style serial programming header
+* Screw terminals for easy and (fairly) secure connection of extra peripherals
+
+Design files for this board are present in `hardware/sejfduino/` directory.
+
+Sejfduino-based modules are running arduino-based code, including an "UBus"
+library that implements some basic cross-device communication on a half-duplex
+RS485 bus. See `software/arduino/ubus/` and `protocol.md` for reference on that.
+
+### Raspi
+
+Raspberry Pi 3 connected to an LCD screen is present on each of 4 sides of the
+"Furniture".
+
+Raspberry Pi boards are running Python Kivy based software that takes a role of
+a ~master~ leader on the "UBus" bus.
+
+Game "scenario" is configured there, and sejfduino modules are mostly meant to
+be a custom human interface devices for specific game tasks.
+
+Code running on the raspberry pi is present in `software/raspi/` directory.
+
+#### raspbian bootstrap (WIP)
+
+```sh
+apt install -y --no-install-recommends python3-pip python3-virtualenv
+apt install -y --no-install-recommends libsdl2-2.0-0 libsdl2-image-2.0-0 libgl1 libmtdev1
+python3 -m virtualenv /opt/kivy
+/opt/kivy/bin/pip3 install "kivy[base]" kivy_examples
+
+apt-get install --no-install-recommends xserver-xorg-video-all xserver-xorg-input-all xserver-xorg-core xinit x11-xserver-utils unclutter xterm
+```
+
+## Sample task modules
+
+* 16x2 LCD + a potentiometer used as a digit input device - "safebox combination
+  lock dial" entry module
+* Snake - displayed on screen, with hardware joystick exposed as plain GPIO inputs
+* NFC card reader - connected over I2C (card found earlier in the game)
+* "Key" module - plain GPIO input - key found earlier in the game
+* Barcode scanner - USB port exposed externally, with a separate USB scanner
+  (found earlier in the game)
+* Electronic drawer with pincode entry