Push Version 0.1.0 to main

.gitattributes

@@ -0,0 +1,4 @@
+# Line ends that must not depend on the checkout's core.autocrlf: cmd.exe
+# misreads batch files with bare LF, bash rejects scripts with CRLF.
+*.cmd text eol=crlf
+*.sh  text eol=lf

.github/workflows/build.yml

@@ -0,0 +1,141 @@
+# EspDrop - builds: the ESP32-C5 firmware with ESP-IDF, then the app compiled
+# with Nuitka (Python -> C) for Windows and Linux with that firmware inside,
+# and the tests. A tag v* also drafts a GitHub release with the files.
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (C) 2026  EspDrop contributors
+
+name: build
+
+on:
+  push:
+    branches: [main, test]
+    tags: ["v*"]
+    paths: ["host/**", "firmware/**", "tools/**", ".github/workflows/build.yml"]
+  pull_request:
+    paths: ["host/**", "firmware/**", "tools/**", ".github/workflows/build.yml"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: build-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  firmware:
+    name: firmware (ESP32-C5)
+    runs-on: ubuntu-latest
+    container: espressif/idf:v6.0.3
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build the bridge
+        shell: bash
+        run: |
+          . "$IDF_PATH/export.sh"
+          cd firmware/spikes
+          idf.py -B build_c5_bridge -DSDKCONFIG=build_c5_bridge/sdkconfig -DIDF_TARGET=esp32c5 \
+            -DSDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.bridge.defaults" build
+      - name: One image of the whole flash
+        shell: bash
+        run: |
+          . "$IDF_PATH/export.sh"
+          python tools/firmware_image.py firmware/spikes/build_c5_bridge -o espdrop-esp32c5.bin
+      - uses: actions/upload-artifact@v4
+        with:
+          name: firmware
+          path: espdrop-esp32c5.bin
+          if-no-files-found: error
+
+  test:
+    name: tests
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Libraries (libarchive; what Qt needs offscreen)
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libarchive13t64 libegl1 libgl1 libxkbcommon0 libfontconfig1 libdbus-1-3
+      - name: The venv with the patched OpenDrop
+        run: python tools/opendrop_install.py --venv "$RUNNER_TEMP/venv"
+      - name: Host tests
+        env:
+          QT_QPA_PLATFORM: offscreen
+        run: '"$RUNNER_TEMP/venv/bin/python" -m unittest discover -s host/tests'
+      - name: Firmware host tests (protocol logic, no ESP)
+        run: make -C firmware/spikes/components/awdl/test/host run
+
+  app:
+    name: app (${{ matrix.name }})
+    needs: firmware
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: Windows
+            os: windows-latest
+          - name: Linux
+            os: ubuntu-22.04          # the oldest glibc we build on: runs on newer ones
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: actions/download-artifact@v4
+        with:
+          name: firmware
+          path: build/firmware
+      - name: Libraries (Linux)
+        if: runner.os == 'Linux'
+        # libarchive and Qt's X11 plugin's xcb libraries go into the program
+        # (users need not install them); xvfb for the start test under X11.
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libarchive13 libegl1 libgl1 libxkbcommon0 libfontconfig1 libdbus-1-3 \
+            libxcb-cursor0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-render-util0 \
+            libxcb-shape0 libxcb-xkb1 libxkbcommon-x11-0 libxcb-util1 xvfb
+      - name: The venv with the patched OpenDrop, and Nuitka
+        shell: bash
+        run: |
+          python tools/opendrop_install.py --venv "$RUNNER_TEMP/venv"
+          if [ "$RUNNER_OS" = Windows ]; then PY="$RUNNER_TEMP/venv/Scripts/python.exe"; else PY="$RUNNER_TEMP/venv/bin/python"; fi
+          "$PY" -m pip install -q nuitka zstandard   # zstandard: the single file's packing
+          if [ "$RUNNER_OS" = Linux ]; then "$PY" -m pip install -q patchelf; fi
+          echo "PY=$PY" >> "$GITHUB_ENV"
+      - name: Compile (Nuitka) and check the program
+        shell: bash
+        run: |
+          if [ "$RUNNER_OS" = Linux ]; then export PATH="$RUNNER_TEMP/venv/bin:$PATH"; fi
+          "$PY" tools/build_app.py --firmware build/firmware/espdrop-esp32c5.bin --smoke --smoke-install
+      - uses: actions/upload-artifact@v4
+        with:
+          name: EspDrop-${{ matrix.name }}
+          path: |
+            build/EspDrop-*
+            build/THIRD_PARTY-*.txt
+          if-no-files-found: error
+
+  release:
+    name: draft release
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: [firmware, test, app]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4             # the release text (first: it cleans the folder)
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: softprops/action-gh-release@v2
+        with:
+          draft: true                         # published by hand, after a look
+          name: EspDrop ${{ github.ref_name }}
+          body_path: docs/RELEASE.md
+          files: dist/*

.gitignore

@@ -0,0 +1,44 @@
+# --- Build output -----------------------------------------------------------
+build/
+**/build/
+firmware/**/sdkconfig
+firmware/**/sdkconfig.old
+firmware/**/managed_components/
+firmware/**/dependencies.lock
+*.o
+*.a
+*.elf
+*.bin
+*.map
+
+# --- Python -----------------------------------------------------------------
+__pycache__/
+*.pyc
+.venv/
+venv/
+.pytest_cache/
+
+# --- Editors ----------------------------------------------------------------
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# --- Privacy: never commit captures or logs ---------------------------------
+# Wi-Fi/BLE captures and serial logs contain MAC addresses and device names
+# ("Anna's iPhone") of everyone nearby. Keep them local.
+*.pcap
+*.pcapng
+*.cap
+captures/
+logs/
+*.log
+
+# Native host test binary
+test_awdl_frame
+test_awdl_cobs
+test_awdl_power
+
+# Separate build dirs for the bridge-mode / per-chip firmware
+build_bridge/
+firmware/**/build_*/

README.md

@@ -1,2 +1,85 @@
 # EspDrop
-A AirDrop implementation for Windows and Linux using an ESP32 as a cheap Wifi Adapter
+
+**AirDrop for Windows and Linux**, with an ESP32-C5 board on USB as the
+radio. Send files from your PC to an iPhone, iPad or Mac, and receive from
+them, the same way Apple devices do it among themselves: no app on the iPhone,
+no cloud, no cable to the phone.
+
+A PC's own Wi-Fi card cannot speak AWDL, the Wi-Fi link AirDrop runs on, and
+Bluetooth alone is not enough either. EspDrop moves that part onto a small,
+cheap ESP32-C5 board: its firmware runs AWDL and the Bluetooth signal that
+wakes Apple devices, plus a small IPv6 stack; the desktop app does AirDrop
+itself on top (based on OpenDrop) and talks to the board over its USB port.
+
+## What you need
+
+- An **ESP32-C5** board with USB, e.g. the Waveshare ESP32-C5-Zero (the one
+  EspDrop is tested with). The app puts the firmware on it, over the same USB
+  cable, no buttons or tools needed.
+- A PC with **Windows 10 or 11** (64 bit) or **Linux** on a 64-bit PC (glibc
+  2.35 or newer: Ubuntu 22.04+, Debian 12+, Fedora 36+, Linux Mint 21+, Arch,
+  …). No administrator rights, driver or firewall rule.
+- On the iPhone/iPad: AirDrop set to **Everyone**, unlocked.
+
+## Install
+
+1. Download the program for your system from
+   [Releases](https://github.com/AntiWireless/EspDrop/releases):
+   `EspDrop-…-windows-x64.exe` or `EspDrop-…-linux-x86_64`.
+2. Start it (Linux: `chmod +x` it first). It installs itself – Windows into
+   `%LOCALAPPDATA%\Programs\EspDrop` with a Start menu entry and an entry under
+   *Installed apps*, Linux into `~/.local/bin` with an entry in the
+   applications menu – and removes the download from the Downloads folder.
+   Windows asks once because the program is not signed: *More info* → *Run
+   anyway*.
+3. Plug in the ESP32-C5. Under *General → ESP firmware* the app offers to
+   install its firmware; that takes about a minute.
+
+Starting a newer download later updates the installed program. *Uninstall*
+in the app's *…* menu (or under *Installed apps* on Windows) removes it
+again; received files stay.
+
+On Linux the user needs access to the board's serial port: `sudo usermod
+-aG dialout $USER` (Arch: `uucp`), then log out and in again.
+
+## Use
+
+- **Receive:** set *Receiving from* to *10 minutes* or *Everyone*; on the
+  iPhone, share something and pick your PC. Every transfer asks first; files
+  land in Downloads (optionally also on the clipboard).
+- **Send:** *Search*, then drop files on a device or click it – or right-click
+  files: *Send with EspDrop* in Explorer, *Open with → AirDrop (EspDrop)* in a
+  Linux file manager.
+- The app starts with your login and waits quietly in the notification area;
+  the ESP's radio sleeps while nothing needs it and wakes when an Apple device
+  nearby wants to share.
+- English or German (*General → Language*), light or dark.
+
+Folders cannot be sent yet, only files; Apple's *Contacts Only* mode is not
+supported (it needs an Apple ID).
+
+## Build it yourself
+
+| part | where | how |
+|---|---|---|
+| firmware (ESP-IDF 6) | [`firmware/`](firmware/README.md) | `idf.py` builds, `tools/firmware_image.py` makes the image |
+| desktop app (Python, PySide6, patched OpenDrop) | [`host/`](host/README.md) | `tools/opendrop_install.py`, then `tools/espdrop.py gui` |
+| the single-file programs | [`tools/build_app.py`](tools/build_app.py) | Nuitka (Python → C) |
+
+GitHub Actions ([`.github/workflows/build.yml`](.github/workflows/build.yml))
+builds the firmware, both programs and runs the tests on every push; a tag
+`v*` drafts a release. The project's notes, experiments and test plans (in
+German) are in [`docs/`](docs/).
+
+## Credits and license
+
+EspDrop builds on the reverse engineering of AWDL and AirDrop by the
+[Open Wireless Link](https://owlink.org) project of TU Darmstadt's Secure
+Mobile Networking Lab: [OWL](https://github.com/seemoo-lab/owl) (AWDL) and
+[OpenDrop](https://github.com/seemoo-lab/opendrop) (AirDrop), and on the
+patches in [jedbillyb/airdrop-mt7921](https://github.com/jedbillyb/airdrop-mt7921)
+that make OpenDrop work with current iOS.
+
+GPL-3.0-or-later, see [LICENSE](LICENSE). EspDrop is an interoperability
+project and is not affiliated with or endorsed by Apple. AirDrop, iPhone,
+iPad and Mac are trademarks of Apple Inc.