diff --git a/README.md b/README.md
index e69de29..a91a346 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,75 @@
+# Sleepywaves
+
+A RFID powered musick/audiobook player with configurable tracklists and playing modes.
+
+Place a tag onto the reader to start playing. Remove it to stop, or configure a timeout to stop automatically.
+
+
+## Prerequisites / Recommended Setup
+
+- Raspberry Pi (any with audio and SPI. 3A+ works fine)
+- MFRC522 RFID reader module
+- storage medium, e.g. USB stick. Works with SD if nothing else is available.
+- dietpi with the following packages installed:
+  - mpd - audio player
+  - python3
+    - pip3 install poetry
+  - (mympd) - optional web control UI
+  - (samba server) - optional file share server to easily copy new tracks
+- enable SPI in dietpi-config
+
+
+## Installation
+Sleepywaves uses `poetry` to prepare the python environment. Install it with:
+
+- Clone/download the repository
+- Run `poetry install` to create a venv with the required python packages.
+- See `sleepywaves.example.service` for a reference how a systemd unit file could look like
+
+
+## Running
+- Run `poetry shell` or use the python path from the poetry venv directly in the command below.
+- Run `python sleepywaves.py -m <MEDIA DIR>`
+
+Alternatively, start with systemd: `systemctl enable sleepywaves.service` and `systemctl start sleepywaves.service`.
+
+
+## Tag / title configuration
+A new config file is created in the media directory once a new tag is scanned.
+It will be named `changeme_<tag id>.json`.
+Remove the `changeme_` prefix, and configure the file as you wish.
+
+Tracks are added to the `tracks` list in the file, and the start time in a track can be configured by
+adding a `"<name>":<seconds>` pair to `start_times`.
+
+Setting a timeout other than `0` will enable the sleep timer.
+The player will stop after the configured time in seconds, even if the tag is still present on the reader.
+
+These modes are supported:
+
+| Play mode             | Description                                                                                                                                                                    |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| sequence              | Start with the first track (at custom start time if configured), advance through the list one-by-one                                                                           |
+| random                | Select a random track from `tracks` (at custom start time if configured) each time the tag is put on the reader, or after one track finishes playing                           |
+| random_sequence       | Select a random track from `tracks` (at custom start time if configured) when the tag is put on the reader. After the track finishes, advance to the next in the `tracks` list |
+| random_start_sequence | Select a random starting track and time from the list of `start_times`. Advance to the next track in `tracks` after it finishes playing                                        |
+
+Setting `resume_track` to true will save the current playing position if the tag is removed, or the timer is reached.
+Playback will continue at this point when the tag is put on the reader again.
+
+Note: if a custom `start_times` entry is present for a track, all playback will start at this time (i.e. even if the
+track is next-in-line for sequence play mode).
+
+Note: the `random_start_sequence` mode is most useful for using audiobooks with chapters broken into shorter tracks and
+the sleep timer feature. If the book e.g. has tracks of ~4 minutes, but the timeout is set to 8 minutes, it will start
+at one of the configured start tracks and continue playing across the track breaks, but never start at the intermediate
+tracks.
+
+
+### Adding tracks to a title easily
+Adding tracks to the renamed file can be automated with the add_tracks.py tool.
+Run it as `python add_tracks.py -m <media dir> -t <tag id> -p <file name pattern>`
+A pattern of `*Hobbit*.mp3` will find `<media dir>/Hobbit/chapter1.mp3` and similar.
+Using the  `-o` flag will overwrite the track list in the title config file (*USE WITH CAUTION*). If not given, tracks will be appended to the existing tracklist.
+
+