docs: add project README
This commit is contained in:
Lago
@@ -0,0 +1,146 @@
|
|||||||
|
# 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
|
||||||
Reference in New Issue
Block a user