Home - Kush-Kelaiya22/imPress GitHub Wiki
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.1branch. Every push that passes CI is released as the next patch, for examplevarun/v2.1.5(see Release Notes). What changed since v2.0 is in Release Notes. The source documentation lives in the repository'sdocs/folder. Every page here links to the reference it is based on.
| 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 |
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
- The teacher clicks Start on a quiz. The backend sends the question over a WebSocket to the room's gateway.
- The gateway hands it to the hub over SPI. The hub broadcasts it over ESP-NOW, and students relay it to modules further away.
- 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.
- 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.
| 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 |
| 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.
- 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.
-
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.