# Kode Dot FTP Explorer

A wireless FTP file server running on the [Kode Dot](https://docs.kode.diy) (ESP32-S3). Serves the microSD card over Wi-Fi with a real-time AMOLED status display, battery monitoring, and persistent timekeeping.

## Features

- **FTP Server** — Access the SD card from any FTP client (FileZilla, WinSCP, etc.)
- **Wi-Fi from SD** — Reads network credentials from `/Wi-Fi.json` on the SD card
- **AMOLED UI** — 410×502 LVGL 9.5 interface with live status, storage bar, clock
- **Battery** — Real-time charge percentage + charging indicator (BQ27220 + BQ25896)
- **Persistent Clock** — NTP sync → external RTC (MAX31329), survives power cycles
- **Status LED** — NeoPixel: green (idle), blue (connected), purple (transferring), red (error)

## Hardware

| Component | Details |
|-----------|---------|
| MCU | ESP32-S3, 240 MHz, 32 MB flash |
| Display | 410×502 AMOLED (QSPI, CO5300) |
| Storage | microSD via SD_MMC 1-bit |
| Battery | BQ27220 fuel gauge, BQ25896 PMIC |
| RTC | MAX31329 external clock |
| IO Expander | TCA9555 (buttons, SD detect) |
| LED | WS2812B NeoPixel on GPIO 4 |

## Quick Start

### 1. Prepare the SD card

Create a `Wi-Fi.json` file in the root of your microSD card:

```json
[
  { "ssid": "YourNetwork", "pass": "YourPassword" },
  { "ssid": "Fallback Network", "pass": "BackupPass" }
]
```

The device tries each network in order (20s timeout per attempt).

### 2. Build & Flash

```bash
# Build
pio run

# Flash (preserves KodeOS bootloader)
pio run -t upload

# Serial monitor
pio device monitor
```

### 3. Connect via FTP

| Setting | Value |
|---------|-------|
| Host | IP shown on display |
| Port | 21 |
| User | `kode` |
| Pass | `kode` |

> **FileZilla tip**: Go to Site Manager → Transfer Settings → check "Limit number of simultaneous connections" and set to **1**. SimpleFTPServer handles one client at a time.

## UI Layout

```
┌─────────────────────────────────────┐
│         FTP Explorer          96% █ │ Header + battery
│─────────────────────────────────────│
│ 📶 Lago Sommer IoT                  │ Wi-Fi SSID
│ 192.168.178.102                     │ IP address
│                                     │
│ ┌─────────────────────────────────┐ │
│ │  FTP Server                     │ │
│ │  ● Idle                         │ │ FTP panel
│ │  ftp://192.168.178.102          │ │
│ │  User: kode   Pass: kode       │ │
│ └─────────────────────────────────┘ │
│                                     │
│ Storage                             │
│ [██████░░░░]  61 MB / 7.3 GB   1%  │ Storage bar
│                                     │
│          14:32:45                   │ Clock
│       Fri, 03 Apr 2026             │
└─────────────────────────────────────┘
```

## LED Status

| Color | Meaning |
|-------|---------|
| 🟢 Green | Wi-Fi connected, FTP idle |
| 🔵 Blue | FTP client connected |
| 🟣 Purple | File transfer in progress |
| 🔴 Red | Error (no SD, no Wi-Fi) |

## I2C Peripherals

| Device | Address | Function |
|--------|---------|----------|
| TCA9555 | 0x20 | IO expander (buttons, SD detect) |
| BQ27220 | 0x55 | Battery fuel gauge |
| BQ25896 | 0x6B | PMIC / charger |
| MAX31329 | 0xD0 | External RTC |

## Key Pin Assignments

| GPIO | Function |
|------|----------|
| 4 | NeoPixel LED |
| 5, 6, 7 | SD_MMC (CMD, CLK, D0) |
| 47, 48 | I2C (SCL, SDA) |
| 8–10, 14–17 | QSPI display |

## Dependencies

- [LVGL 9](https://github.com/lvgl/lvgl) — UI framework
- [SimpleFTPServer](https://github.com/xreef/SimpleFTPServer) — FTP daemon
- [ArduinoJson 7](https://github.com/bblanchon/ArduinoJson) — Wi-Fi.json parsing
- [GFX Library for Arduino](https://github.com/moononournation/Arduino_GFX) — Display driver
- [Adafruit NeoPixel](https://github.com/adafruit/Adafruit_NeoPixel) — Status LED
- [TCA9555](https://github.com/RobTillaart/TCA9555) — IO expander
- [PMIC_BQ25896](https://github.com/sqmsmu/PMIC_BQ25896) — Charger
- [kode_BQ27220](https://github.com/kodediy/kode_BQ27220) — Fuel gauge
- [kode_MAX31329](https://github.com/kodediy/kode_MAX31329) — External RTC

## Project Structure

```
├── platformio.ini          Build config, libraries, upload command
├── partitions_app.csv      Flash partition layout
├── Wi-Fi.json              Example Wi-Fi credentials
├── boards/
│   └── kode_dot.json       Custom board definition
├── src/
│   ├── main.cpp            Firmware (Wi-Fi, FTP, NTP, battery, SD)
│   ├── ui.h / ui.cpp       LVGL 9 display interface
│   └── lv_conf.h           LVGL configuration
├── lib/kodedot_bsp/        Board support (display driver, pin config)
└── extra_scripts/          Build helpers (auto port, rename, framework libs)
```

## License

MIT