The words this wiki uses, what they mean in imPress, and where each one lives in the code. Read this first if a term elsewhere is unclear.
| Term |
Also called |
What it is |
| Student module |
module, student device, node |
An ESP32 board held by one student. Four answer buttons (A–D), a CONFIRM button, an optional OLED screen and an optional LED. Runs firmware/student. Joins the classroom mesh, shows questions, sends answers and votes, and relays messages for modules further from the hub. Never uses Wi-Fi. |
| Hub |
S3, mesh root, class module |
An ESP32-S3 board, one per room. The root of the ESP-NOW mesh (its mesh sender_id is always 0). Keeps a routing table of up to 300 students, drops duplicate relay copies, and exchanges data with the gateway over SPI. Updates its own firmware by briefly joining Wi-Fi (the "OTA hop"). Runs firmware/class_s3. |
| Gateway |
C6, classroom node |
An ESP32-C6 board, one per room, wired to the hub. The only classroom device on the school network. Posts student messages to the backend in batches, keeps a WebSocket open for commands, sends heartbeats and diagnostics, and updates its own firmware directly. Runs firmware/class_c6. |
| Backend |
server |
The Python application (FastAPI, SQLite) in backend/. Stores all data, serves the web app at /, the REST API at /api/* and WebSockets at /ws/class/{id}. |
| Web app |
SPA, dashboard |
The browser application served by the backend (backend/app/static, templates). Teachers and admins use it. A separate React development UI (frontend/) is optional and incomplete. |
| Term |
Meaning |
| User |
Someone who logs into the web app: a teacher, admin or super_admin. Stored in users. |
| Student |
A learner. Not a user: students never log in. Identified by an enrollment number. Stored in students. |
| Enrollment number |
Exactly 10 letters or digits (stored upper-case), e.g. ABCDE12345. It is the student's identity everywhere: on the module, in every answer, and in the backend (students.roll_number). Also called the roll number. |
| Course |
A catalog entry such as CS101 Introduction to Computing. Stored in courses. |
| Section |
One taught instance of a course (CS101, section A). In the database it is a class session linked to a course. |
| Class |
A class session: what teachers run quizzes in. It has a numeric id, a join code (code, e.g. PHY101), an optional physical classroom code (classroom_code, e.g. RM-201), a primary teacher, optional co-faculty, a roster and a timetable. Stored in class_sessions. The web app calls them Classrooms. |
| Classroom code |
The label of the physical room (RM-201). A gateway that registers with this code is linked to the class automatically. |
| Primary teacher / co-faculty |
Every class has one primary teacher. Co-faculty have the same rights in that class, except deleting it. A teacher who joins a class with its join code becomes co-faculty and never replaces the primary teacher. |
| Active class |
A class whose is_active is true. Gateways only auto-link to active classes, and live teaching happens in active classes. New classes start inactive. |
| Enrollment |
A student's membership in a class (student_enrollments). One per student and class. |
| Term |
Meaning |
| Quiz |
A set of 1 or more questions, each with 2–4 options and a correct option. States: draft, active, completed. Planned quizzes start when the teacher clicks Start; impromptu quizzes start immediately. Timing: per-question, total, or manual (the teacher advances). |
| Poll |
A single question with 2–4 options and no correct answer. States: draft, active, closed. Live polls start immediately; planned ones on demand. |
| Answer / vote |
One student's choice for a quiz question / poll. The database keeps one per student per question (and one per student per poll), enforced by unique indexes. |
| Live count |
The running total of answers or votes pushed to the teacher's dashboard over the WebSocket after each stored answer. |
| Attendance |
A check-in record per class and enrollment. |
| Term |
Meaning |
| Registration |
A gateway or hub announcing itself (POST /api/device/register). Creates or updates its row in esp_devices, marks it online, links a gateway to a class, and (since #66) issues it a device key. |
| Heartbeat |
A periodic "I'm alive" message. The gateway sends one every 15 s with telemetry and diagnostics. Students send one every 30 s over the mesh; the hub sends one every 5 s to the gateway. |
| Presence |
Whether a device is online. A device is offline after 30 s without contact; a student module is shown as seen (not connected) after 90 s. |
| Health state |
A gateway's condition, computed from its latest diagnostics: ONLINE, DEGRADED, ERROR, UPDATING, OFFLINE, UNKNOWN, with reasons. See Device Management. |
| Diagnostics |
Values the gateway reports with its heartbeat: uptime, last reset reason, boot count, lowest free memory, Wi-Fi signal, and whether its hub link is up. |
| Student module inventory |
The list of every student module a gateway has seen: device ID, enrollment, class, gateway, connected or seen, last seen, battery. One row per module, no history (student_modules). |
|
Device ID (student module) |
A 32-bit number from the module's MAC address, shown in hex (1A2B3C4D). Used for routing and the inventory. Never used as a student identity. |
| Term |
Meaning |
| Firmware image |
The compiled application file (build/impress_<project>.bin) for one board type. |
| Firmware registry |
The backend's list of uploaded images (firmware_artifacts). Each image is validated, stored under its SHA-256, and immutable: one version means one set of bytes. |
| Approved / deprecated |
An image must be approved before it can be deployed. Deprecated images aren't deployed again, but devices already using them are unaffected. |
| OTA |
Over-the-air update: a device downloads and installs a new image by itself. Hubs and gateways support it; student modules don't (they are updated over a USB cable). |
| Deployment |
One rollout of one image to a set of devices. It has a strategy (canary size, batch size, concurrency, failure tolerance, attempts, timeout) and a state (running, paused, completed, cancelled). |
| Canary |
The first stage of a deployment: a few devices update first, and the rest only follow if they succeed. |
| Target |
One device in a deployment, with its own state machine: waiting → queued → precheck → downloading → verifying → installing → rebooting → health_check → success (or failed, rolled_back, timed_out, unreachable, cancelled). |
| Rollback (device) |
When a new image can't prove it works after rebooting, the bootloader boots the previous image, which reports rolled_back. |
| Rollback (operator) |
Deploying an older approved image on purpose, with an explicit "allow downgrade" confirmation. |
| OTA slot |
Each board has two app partitions (ota_0, ota_1). An update is written to the one not running, so a failed update never damages the running image. |
| Signed image |
An image carrying an RSA-3072 signature from the site's private key. Devices built with the signed profile refuse unsigned images. Opt-in. See Security. |
| Term |
Meaning |
| Session token |
An opaque impress_… string returned at login and sent as Authorization: Bearer …. The server stores only its SHA-256. Sessions expire after 60 minutes idle or 6 hours in total (by default). |
| Shared (provisioning) key |
IMPRESS_DEVICE_API_KEY: the site-wide key every device starts with and uses to register. |
| Device key |
A per-device key issued at registration. Once used, it is the only key that can act for that device. Admins can reset it. |
| Site signing key |
The RSA key pair used to sign firmware: private half offline, public half given to the backend (IMPRESS_FIRMWARE_SIGNING_KEY) and compiled into signed firmware. |
| Term |
Meaning |
| ESP-NOW |
Espressif's connectionless radio protocol: short broadcast frames (≤ 250 bytes) with no access point. |
| Mesh |
Every student module re-broadcasts each message once, with a TTL of 5 hops, so modules out of the hub's range are still reached. |
| De-duplication |
Identifying copies of the same message by a hash of its origin and content, so each message is handled once. Done on modules, the hub and the backend. |
| TTL / hops |
How many more times a message may be relayed / how many times it has been. |
| Mesh channel |
The 2.4 GHz channel every module and the hub use (default 1). |
| SPI slot |
One 4096-byte exchange between hub and gateway, carrying many messages at once, with a length and CRC. |
| Ready lines |
Two extra wires between hub and gateway, each saying "I have something to send". |
| Frame |
One protocol message: start byte, type, length, payload, CRC-16. See Protocols and Mesh. |
| Term |
Meaning |
| Migration |
A numbered, recorded change to the database structure applied at startup (schema_migrations). See Database and Migrations. |
run_tests.py |
The single test runner for every suite. See Testing and CI. |
| IST |
Indian Standard Time. All stored timestamps are naive IST. |
| NVS |
Non-volatile storage on an ESP32: a small key–value store in flash that survives reboots and firmware updates. Holds Wi-Fi details, the backend address, keys and identities. |
| Kconfig / menuconfig |
ESP-IDF's build-time configuration system (idf.py menuconfig). Firmware defaults come from here; values in NVS override them after the first boot. |