From 7702de275c859d734414ebef123a9755c0565be2 Mon Sep 17 00:00:00 2001
From: Stefan Bethke <stb@lassitu.de>
Date: Mon, 2 Jun 2025 18:06:06 +0200
Subject: [PATCH] Add more info

---
 README.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/README.md b/README.md
index 870d503..325774c 100644
--- a/README.md
+++ b/README.md
@@ -6,11 +6,64 @@ This is the code to send information to the station display that is hanging in t
 
 The [docs](./docs) directory contains a number of documents about the device, all in German.
 
+## Development Environment
+
+Use [Poetry](https://python-poetry.org) to manage a local environment:
+
+```shell
+poetry install
+```
+
+## Local Development
+
+You can run the server without having a physical display attached. The server will open HTTP port 3000 on localhost, and
+show an emulated display.
+
+## Deployment
+
+The server is deployed as a Docker image and run with Docker Compose. See below for the configuration.
+
+You will need to allow access to the serial port. For example, in `compose.yaml`:
+
+```yaml
+services:
+  buba:
+    image: buba
+    environment:
+      BUBA_SERIAL: /dev/ttyUSB0
+    devices:
+      - /dev/ttyUSB0
+```
+
+## Configuration
+
+Buba is configured completely through environment variables:
+
+| Name          | Default          | Description                                           |
+|---------------|------------------|-------------------------------------------------------|
+| `BUBA_LISTEN` | `127.0.0.1:3000` | IP and port to listen on.                             |
+| `BUBA_SERIAL` | `/dev/ttyUSB0`   | Serial port the display is connected to.              |
+| `DEBUG`       | `false`          | Set to any value except false to enable debug output. |
+
+## Creating Animation Plugins
+
+Buba instantiates objects of type `BubaAnimation` and runs through them in a loop. Each animation must implement the
+`run()` method, which should send data to the display. The animation is run in its own thread, therefor, the animation
+should sleep an appropriate time to let users take in the information. See the existing animations
+in [buba/animations](./buba/animations) for inspiration.
+
+Note: if you need to fetch and update external information regularly, you should start your own thread when initalizing
+your animation.
+
 ## Character Set
 
 The display uses [Code Page 437](https://en.wikipedia.org/wiki/Code_page_437), with a few exceptions. Due to the limited
 resolution of the segments, the display can deviate significantly.
 
+Note that the [Python codecs](https://docs.python.org/3/library/codecs.html) for `CP437` do not map all special characters correctly.
+
+
+
 | Code | CP437        | Geavision Spaltenschrift |
 |------|--------------|--------------------------|
 | 0xb4 | ┤ u2524      | Vehicle end left         |