FAQ

Short answers, with links to the full explanation.

General

What is imPress? A classroom response system. Students answer quizzes and polls on small ESP32 modules with four buttons, and teachers see the answers live in a browser. See Home.

Do students need phones, Wi-Fi or accounts? No. A student module is all they need. Modules talk to each other and to the room's hub over ESP-NOW radio, with no Wi-Fi and no passwords. Students never sign in; their identity is the enrollment number stored on their module.

How many students per room? Up to 300 (the hub's and gateway's tables). Radio airtime in a burst is the practical limit; it is comfortable at 30 modules. A full-room burst test is on the hardware checklist.

What hardware do I need per room? One ESP32-C6 gateway, one ESP32-S3 hub (32 MB octal flash for the shipped image), and one classic-ESP32 module per student. See Hardware Guide.

Has it been tested on real hardware? Every v2.1 feature is verified by automated tests and firmware builds. None has been verified on boards yet; the checklist is in Testing and CI.

Installing and running

How do I install it?

git clone … && cd imPress && scripts/install.sh
scripts/start.sh

See Installation.

Can I run several backend workers? No. WebSocket rooms live in one process's memory, so run one uvicorn worker.

Can I use PostgreSQL? Not as shipped. The models are standard SQLAlchemy, but the migration runner is SQLite-specific.

Where is the first admin password? It is whatever you set in IMPRESS_INITIAL_ADMIN_PASSWORD, or a random one printed once in the server log at the first start.

The server won't start: "Refusing to start with default secrets". Run scripts/install.sh (it generates secrets), or set IMPRESS_JWT_SECRET and IMPRESS_DEVICE_API_KEY. See Troubleshooting.

How do I check an installation works? Run scripts/smoke_test.py --password …. It exercises 12 steps end to end.

Teaching

Why is a quiz limited to four options? The modules have four answer buttons.

My question text is cut off on the modules. They show about 139 bytes of the question and 14 bytes per option. The web app warns you when you exceed that.

Do timed quizzes move on by themselves? Yes (#73, fixed). With a per-question timer the next question goes out when the time is up. With a total limit the quiz ends on time. Next → and ⏹ Stop still work in every mode. See Teacher Guide → Running a quiz.

Can a student answer twice? No. Only one answer per student per question is stored, even if their press arrives several times through the mesh or the gateway re-sends a batch.

A student's answers don't count. Their module's enrollment number must exist in Students, and the quiz must be active. See Teacher Guide.

Can I import questions from Excel? Yes. Save the sheet as CSV UTF-8 and use Import questions from CSV on the Create Quiz page. See CSV Imports.

Devices

How does a gateway know which room it's in? Set the class's Room Label (classroom_code, e.g. RM-201) and have the gateway register with it. Without a code, a gateway links itself to the first active class that has no gateway. See Device Management.

What do the health states mean? ONLINE, DEGRADED (hub link down, weak Wi-Fi, low memory), ERROR (a failed update, or a recent crash, watchdog reset or brown-out), UPDATING, OFFLINE (silent for over 30 s) and UNKNOWN. See Device Management.

A module shows NO ID. It needs its student's enrollment number. Set it with the buttons or over USB serial. See Hardware Guide.

How do I give a module to a different student? Hold CONFIRM + C for 2 s at boot to clear it, then set the new enrollment number.

Does imPress track where students are? No. The inventory records which gateway last heard a module, not a location history.

Firmware

Can I update student modules over the air? No, only hubs and gateways. Student modules are updated over USB.

Do I need a USB cable for updates? Once, for the first v2.1 install on every gateway and hub. After that they update over the air. Student modules always need USB.

What if an update breaks a device? The device boots its previous image by itself and reports rolled_back. The deployment pauses so no other device gets the image. See Recovery Procedures.

Can I go back to an older version? Yes. Deploy the older approved image with Allow downgrade. See Firmware Management and OTA.

Why was my firmware upload refused? The message says why: wrong chip, not an imPress project, a version that isn't X.Y.Z, a corrupted file, too large, or not signed with the site key. Check it with scripts/verify_firmware.py.

Why can't I replace an image with the same version? A version means one set of bytes. Bump version.txt and rebuild.

Security

Is device traffic encrypted? Only if you turn it on: Backend over TLS in the firmware, plus HTTPS on the server. See Security.

Are firmware images signed? Only if you turn it on: scripts/firmware_key.sh, scripts/build_signed.sh and IMPRESS_FIRMWARE_SIGNING_KEY. See Security.

What if a device is stolen? Disable it on the Modules page: every request for it is then refused. If its flash might be read, rotate the shared key. See Recovery Procedures.

What does "Reset key" do? It invalidates the device's own key immediately. The device then registers again with the shared key and gets a new one. Use it after reflashing a device, or if a key may have leaked.

Can someone fake answers over the radio? In principle, yes: the mesh isn't encrypted, so a rogue module could claim a student's enrollment number. Answers still only count for registered students, once each. See Security.

Development

How do I run the tests? python run_tests.py. See Testing and CI.

Which branch do I work on? Branch from varun/v2.1, and open a pull request into it. Never commit to main, v2 or v3. See Development Guide.

Can I develop without hardware? Yes. Use the backend, the browser tests and the simulated gateway (backend/tests/gateway_sim.py), plus curl for device calls. See Development Guide.