Home

imPress

imPress is a classroom response system built on ESP32 hardware. Each student gets a small module with four answer buttons, A to D. A teacher starts a quiz question or a poll in the browser. The question appears on every student's module, every button press travels back through the classroom, and the teacher's dashboard counts answers live.

Students never touch Wi-Fi. Their modules form a radio mesh using ESP-NOW, which needs no access point and no passwords. In each room, a hub (ESP32-S3) is the root of that mesh, and a gateway (ESP32-C6) is the only device on the school network. A Python backend stores everything and serves the web app that teachers and administrators use.

This wiki explains how it works, how to install and run it, and how to work on its code.

Version. This wiki describes the v2.1 line on the varun/v2.1 branch. Every push that passes CI is released as the next patch, for example varun/v2.1.5 (see Release Notes). What changed since v2.0 is in Release Notes. The source documentation lives in the repository's docs/ folder. Every page here links to the reference it is based on.

---

Start here

If you want to…	Read
understand what imPress is and how the pieces fit	Concepts and Glossary, then System Architecture
install the server	Installation
download a release (bundle, firmware, docs, container)	the Releases page and the Release Notes
set up a classroom (boards, wiring, flashing)	Hardware Guide, Firmware: Build and Flash
run the system as an administrator	Administrator Guide
teach with it	Teacher Guide
bulk-load questions, courses or sections	CSV Imports
watch and look after devices	Device Management
update firmware over the air	Firmware Management and OTA
secure a deployment	Security
fix something that broke	Troubleshooting, Recovery Procedures
integrate with the API	API Reference
understand the radio and wire formats	Protocols and Mesh
understand the database	Database and Migrations
change the code	Development Guide, Testing and CI
look up any setting	Configuration Reference
find a quick answer	FAQ

---

The system in one picture

flowchart LR
    subgraph Room["One classroom"]
        ST1["Student module<br/>ESP32 · buttons A–D"]
        ST2["Student module"]
        ST3["Student module<br/>(far away)"]
        HUB["Hub<br/>ESP32-S3<br/>mesh root"]
        GW["Gateway<br/>ESP32-C6<br/>Wi-Fi"]
        ST1 <-- "ESP-NOW" --> HUB
        ST2 <-- "ESP-NOW" --> HUB
        ST3 <-- "relayed by ST2" --> ST2
        HUB <-- "SPI cable" --> GW
    end
    GW <-- "Wi-Fi: HTTP + WebSocket" --> BE["Backend<br/>FastAPI + SQLite"]
    T["Teacher's browser"] <-- "HTTPS + WSS" --> BE
    A["Administrator's browser"] <-- "HTTPS" --> BE

Loading

1. The teacher clicks Start on a quiz. The backend sends the question over a WebSocket to the room's gateway.
2. The gateway hands it to the hub over SPI. The hub broadcasts it over ESP-NOW, and students relay it to modules further away.
3. A student presses B. The answer travels back over the mesh, the hub keeps exactly one copy, and the gateway posts it to the backend in a batch.
4. The backend checks the answer (known student, active quiz, valid option, not already answered) and stores it. It then pushes the new count to the teacher's dashboard.

The whole path is described step by step in System Architecture.

---

What v2.1 can do

Area	Capabilities
Teaching	Quizzes (planned or impromptu; per-question, total or manual timing); polls (live or planned); live answer counts; per-question results; attendance
Classroom management	Courses and sections, classrooms with timetables and clash warnings, co-faculty, student registry and enrollment, users with three roles
Bulk data	CSV import of quiz questions, courses and sections (with export), students and staff, each previewed before anything is stored
Devices	Live presence per class; health states (online, degraded, error, updating, offline, unknown) with reasons; diagnostics (uptime, reset reason, boot count, memory, hub link); an inventory of every student module each gateway has seen
Firmware	A registry that validates every uploaded image and keeps it immutable; approval before use; staged over-the-air deployments with a canary, batches, retries, timeouts and automatic pause; automatic rollback on the device; operator rollback
Security	Server-side sessions with idle and absolute expiry; role-based access everywhere; per-device keys with reset and revocation; signed firmware images (opt-in); HTTPS/WSS for device traffic (opt-in)
Operations	One-command install, start and smoke test; versioned database migrations with automatic backups; /health with version and schema; CI on every change

---

The three roles

Role	Can do
teacher	Their own classes (and classes where they are co-faculty): quizzes, polls, results, roster, attendance, live devices
admin	Everything a teacher can, for every class, plus users (teachers), courses, classrooms, students, modules, firmware, deployments and the activity log
super_admin	Everything an admin can, plus granting or removing admin rights

The first account, admin, is a super admin created on first start. See Installation.

---

Status and honesty notes

• Automated verification: every feature in v2.1 is verified by automated tests: more than 700 tests (all passing) across backend, firmware host code, firmware structure, repository checks and browser tests. CI also builds the firmware and does a clean install. See Testing and CI.
• Hardware verification: no v2.1 feature has been verified on real boards yet. The bench checklist and its status are in Testing and CI, and the test plan is tracked in #94. Until those issues are closed, the 2.1.0 release is marked Beta.
• Opt-in security: signed firmware and device TLS are off by default, because each needs the site's own key or certificate. Turn them on before production: Security.

---

Repository

• Code: github.com/Kush-Kelaiya22/imPress, integration branch varun/v2.1.
• Issues: GitHub issues.
• License: the repository has no license file yet, so no license has been granted.