feat: add readme and download script

.gitignore

@@ -12,3 +12,6 @@ wheels/
 # Models
 **/*.pt
 *.pt
+
+# Training data
+physionet.org/

README.md

@@ -0,0 +1,60 @@
+# sleep-detection
+
+A small ML pipeline that turns wrist accelerometer + heart rate data into per-epoch sleep stage predictions (hypnogram building blocks).
+
+Built to support [InfiniTime PR #2304](https://github.com/InfiniTimeOrg/InfiniTime/pull/2304), which adds sleep tracking to InfiniTime (PineTime firmware) but stops at raw data logging.
+This repo explores whether a small offline-trained classifier can turn that raw data into sleep stages and eventually an on-device hypnogram.
+
+## Repo layout
+
+- `src/sleep_detection/` — data loading, epoching/features, model, training loop
+- `scripts/` — supporting/experimentation scripts
+- `plots/` — output plots
+
+## Datasets
+
+Not included in this repo — download separately:
+
+- [PhysioNet: Motion and heart rate from a wrist-worn wearable and labeled sleep from polysomnography](https://physionet.org/content/sleep-accel/1.0.0/) (Walch et al., 2019) — primary dataset used so far.
+- [PhysioNet: A Multi-Night Instantaneous Heart Rate and Accelerometry Dataset with EEG Sleep Stage Labels](https://physionet.org/content/bidsleep-dataset/1.0.0/) — larger, newer, same sensor modalities.
+- [PhysioNet: MMASH](https://physionet.org/content/mmash/1.0.0/) — 24h continuous HR + accelerometer + sleep quality, healthy adults.
+
+## Getting started
+
+This is just a regular python project. I recommend you work in an editable virtual environment during development.
+
+```sh
+cd sleep-detection
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install -e .
+```
+
+The [uv](https://github.com/astral-sh/uv) project manager should also work just fine if you prefer to use that.
+
+### Datasets
+
+Not included in this repo, but a convenience download script exists. Note that this will take a while because the
+physionet servers are deliberately quite slow.
+
+```sh
+./download.sh
+```
+
+## Usage
+
+As an example training a model on the `sleep-accel` dataset subject `1066528`:
+
+```sh
+sleep-detection \
+   -a physionet.org/files/sleep-accel/1.0.0/motion/1066528_acceleration.txt \
+   -H physionet.org/files/sleep-accel/1.0.0/heart_rate/1066528_heartrate.txt \
+   -l physionet.org/files/sleep-accel/1.0.0/labels/1066528_labeled_sleep.txt \
+   --output model.pt
+```
+
+## Help Wanted
+
+I am not sure if the way I am feeding / dividing the training data up is done appropriately and if the model is too
+simple for this kind of dataset. I would love some help from someone who have experience and proper insight into how to
+train models using pytorch. Feel free to message me, submit an issue, fork the project etc.

download.sh

@@ -0,0 +1,17 @@
+#!/bin/env bash
+# Copyright (C) 2026 Asger Gitz-Johansen
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+wget -r -N -c -np https://physionet.org/files/sleep-accel/1.0.0/
+wget -r -N -c -np https://physionet.org/files/bidsleep-dataset/1.0.0/