init

1 files changed, 87 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e088361
--- /dev/null
+++ b/README.md
@@ -0,0 +1,87 @@
+# xwing-sensor
+
+Reads temperature and humidity from an SI7021 sensor over I2C and displays the readings on a Waveshare 2.13 inch e-Paper HAT, running on a Raspberry Pi Zero 2 W.
+
+## Hardware
+
+- Raspberry Pi Zero 2 W
+- SI7021 temperature/humidity sensor (I2C, address `0x40`, bus 1)
+- Waveshare 2.13 inch e-Paper HAT (250×122 px, SPI)
+
+Waveshare HAT documentation and wiring guide:
+https://www.waveshare.com/wiki/2.13inch_e-Paper_HAT_Manual#Overview
+
+## System dependencies
+
+Before running `uv sync`, install the required system libraries.
+
+**Pillow build dependencies:**
+
+```bash
+sudo apt-get update && sudo apt-get install -y \
+    build-essential \
+    python3-dev \
+    libjpeg62-turbo-dev \
+    zlib1g-dev \
+    libfreetype-dev \
+    libopenjp2-7-dev
+```
+
+**lg GPIO library:**
+
+The `lgpio` Python package requires the `lg` C library. Follow the install instructions at https://github.com/joan2937/lg, which requires `swig`:
+
+```bash
+sudo apt-get install -y swig
+```
+
+Then build and install `lg` per the instructions in that repository.
+
+## Waveshare EPD library
+
+The `waveshare_epd` library is **not bundled** in this repo. Download it from Waveshare's GitHub:
+
+```bash
+git clone https://github.com/waveshare/e-Paper
+```
+
+The `lib/` directory (`e-Paper/RaspberryPi_JetsonNano/python/lib`) must be on `PYTHONPATH` at runtime. When running as a systemd service this is handled via the `Environment=` line in the unit file (see below). For manual runs:
+
+```bash
+PYTHONPATH=/home/pi/e-Paper/RaspberryPi_JetsonNano/python/lib uv run xwing-sensor
+```
+
+The import in `main.py` uses `epd2in13_V4` — adjust to match your HAT version if needed.
+
+## Setup
+
+```bash
+uv sync
+```
+
+## Running as a systemd service
+
+Copy the unit file to systemd and enable it:
+
+```bash
+sudo cp xwing-sensor.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable xwing-sensor
+sudo systemctl start xwing-sensor
+```
+
+Check status or logs:
+
+```bash
+sudo systemctl status xwing-sensor
+journalctl -u xwing-sensor -f
+```
+
+Before enabling, verify the paths in `xwing-sensor.service` match your environment:
+
+| Field | Default value | What to check |
+|---|---|---|
+| `User` | `pi` | The user that owns the project directory |
+| `WorkingDirectory` | `/home/pi/xwing_sensor` | Absolute path to this repo on the Pi |
+| `PYTHONPATH` | `/home/pi/e-Paper/…/lib` | Where you cloned the Waveshare repo |
+| `ExecStart` | `/home/pi/xwing_sensor/.venv/bin/xwing-sensor` | Created by `uv sync` |