FoloToy AI Passport — Timetable Play

An open-source ESP32-C3 demo that turns the FoloToy AI Passport (240×320 ST7789 LCD, no PSRAM) into a personal timetable & GPA assistant — plus a set of hardware test pages (display / button / audio / battery).

Built on ESP-IDF 5.5.x and LVGL 9.5. Everything runs on-device; all data entry is offline on your own computer.

Features

Home

• Two-tile home screen (Timetable / Settings), live clock, animated mascot
• Dark tech theme with a procedural wallpaper, rounded cards and soft glow

Timetable app (the main play)

• Three weekly views + a grades view: Today / Week / Exams / Grades
• Today: course rows with 进行中 (ongoing) / 下一节 (next) markers, tomorrow preview on empty days, vacation countdown before term starts
• Week: 7×5 grid with today's column highlighted
• Exams: upcoming exams with ≤7-day countdown, red/amber emphasis
• Grades: weighted GPA (score/10−5, five-level table), credits, scrollable list with selection, failed courses highlighted
• Live HH:MM clock in the header; 60 s auto-refresh only when content changes

Settings hub

• Sub-menu hosting Display / Button / Audio / Battery test pages plus a Clock page (second-level time, date, teaching week, time source)
• Long-press OK navigates back one level: sub-page → settings → home

Power

• Idle screen-off: 30 s no input → 20% backlight, 60 s → off; any key wakes (the wake keypress is swallowed, so it never triggers navigation)

Time

• No RTC on the board — the device restores the clock from the last sync and, optionally, calibrates it over WiFi + SNTP at boot (Beijing time)

Sync

• USB-Serial-JTAG binary protocol v2 (courses / exams / grades / sync epoch), CRC-protected, with ACK codes and a browser-based web tool

Hardware requirements

• FoloToy AI Passport (ESP32-C3, ST7789 240×320, no PSRAM)
• ESP-IDF 5.5.x toolchain (Windows / Linux / macOS)
• Chrome or Edge for the web tool (Web Serial)

Getting started (build & flash)

get_idf553                      # or source your ESP-IDF 5.5 export script
idf.py set-target esp32c3
idf.py build
idf.py -p <PORT> flash monitor

The boot menu appears after flashing. Data stored in NVS survives re-flashing the app partition.

Using the timetable app

Everything is entered through the browser tool (file import only — nothing leaves your machine):

python -m http.server 8000      # in the repo root
# open http://localhost:8000/tool/index.html in Chrome/Edge

1. Courses: upload the schedule PDF exported by your school system (or import a CSV), review/edit each row in the preview.
2. Exams / Grades: import CSV (columns: date,time,course,room,note and course,score,credit; scores may be numbers or level words like 良好).
3. Calendar: set term start, week count and period times (defaults pre-filled).
4. Connect the device over Web Serial and press 写入课表 — ACK 0x00 means success.

On-device navigation

The Today view shows 假期中 · 距开学 N 天 before the term starts and the teaching week is computed from the term configuration.

WiFi time calibration (optional)

Without an RTC the clock is restored from the last sync. To make the device calibrate itself over WiFi at boot:

1. Create local/wifi.json (see local/wifi.json.example):

   { "ssid": "your-wifi", "password": "your-password" }
   

2. python local/gen_wifi_creds.py — generates a git-ignored header.
3. Rebuild & flash. On boot the device connects, runs SNTP (Aliyun + pool servers), applies Beijing time, then turns WiFi off to save power. Watch for the wifi_time WARN logs.

Your WiFi credentials are never committed to the repository.

Host-side tests

cmake -S tests -B build-tests && cmake --build build-tests && ctest --test-dir build-tests

Covers the timetable model (weeks bitmap, next-class, GPA) and pixel math.

Documentation

• docs/TIMETABLE.md — timetable feature guide
• docs/timetable-format.md — sync protocol spec (v2)
• docs/DEVELOPER.md — BSP developer / agent contract
• docs/AI_HARDWARE_DEVELOPMENT_GUIDE.md — board hardware reference

Repository layout

main/            firmware: menu, timetable app, settings hub, wifi_time
components/bsp/  BSP: display / button / audio / battery / i2c
tool/            browser web tool (PDF/CSV import, preview, Web Serial sync)
tests/           host-side C tests (timetable model, GPA, pixel math)
docs/            guides and protocol spec

Privacy

• The web tool is file-import only: PDFs and CSVs are parsed locally in your browser; nothing is uploaded.
• School-system scraping (login, captcha, grade fetching) is personal tooling kept out of this repository.
• Real grades/schedule data must never be committed.

Credits & license

• Font: Noto Sans SC (SIL Open Font License)
• LCD driver: ESP-IDF esp_lcd ST7789
• Licensed under the MIT License (see LICENSE).