What changed in each release, and what to do when upgrading. The per-issue changelogs, with the tests for each change, are in the repository: v2.1, v2. The full engineering report: docs/engineering/V2.1_ENGINEERING_REPORT.md.

Version	Branch	In one line
2.1.0	varun/v2.1	CSV imports; a firmware registry with staged OTA and rollback; the gateway's own OTA client; diagnostics and health; a module inventory; migrations; a tested install path; per-device keys, signed firmware and device TLS
2.0	v2	the October 2026 audit fixes (#1–#25), a full test suite, CI and documentation
1.x	main	the original system

Releases are published automatically on the Releases page. Every push to an integration line that passes CI becomes its next patch release, named after the line's owner: varun/v2.1.0, varun/v2.1.2, … varun/v2.1.5. What changed in each one is in CHANGELOG.md, grouped as Added, Changed, Removed, Fixed and Security.

Item	Format	Example
Integration line (branch)	<owner>/vMAJOR.MINOR	varun/v2.1, aamna/v2.4
Release (tag and title)	<owner>/vMAJOR.MINOR.PATCH, plus (Beta) while Beta	varun/v2.1.5
Download files	impress-<owner>-<version>.zip, -firmware.zip, -docs.zip	impress-varun-2.1.5.zip
Container image	<owner>-<version>, <owner>-<MAJOR.MINOR>, <owner>-latest, <owner>-beta	varun-2.1.5, varun-2.1

• The line comes from the branch name. The patch is the number of pushes to the line since its first release (<owner>/vMAJOR.MINOR.0), so the same commit always gets the same number. Gaps are normal: varun/v2.1.1 was never released.
• The software reports the plain version (/health, firmware, OTA: 2.1.5). The owner is part of the release name only.
• Every owner works the same way (varun, kush, aamna, encrypted): a push to aamna/v2.4 that passes CI publishes aamna/v2.4.0, creates the milestone aamna/v2.4, and pushes the images aamna-2.4.0 and aamna-2.4.

Each release page is complete when GitHub Actions publishes it. At the top it has the status badges, a Warning (Beta) or Note (Stable) box, and a table of the release's test issues: No., Issue, Assigned to, Status. Below that come the summary, what changed, downloads, install and set-up, first use, checks, setup problems, upgrade, and checksums. You can edit the page afterwards; only the status section is redrawn, within about a minute of any change to a test issue.

Status	Meaning
Beta	At least one open test issue (label testing) gates the release. For 2.1 these are the hardware bench checks #83–#94. GitHub shows a pre-release.
Stable	No open test issue gates the release. The newest Stable release is GitHub's latest.

Which issues gate a release (Issues > Milestones):

Milestone	Gates
<owner>/vX.Y	every release of that line, and every release built on it: later lines of the same owner and other owners' lines branched from it (the line's first release is a git ancestor, and was published before)
<owner>/vX.Y.Z	that one release

So closing a 2.1 test issue updates the 2.1 releases and everything built on 2.1, in one run. A 2.2-only issue never affects 2.1. Issues inherited from another line show from varun/v2.1 in the table.

Tested end to end on 2026-10-10 with a demo line varun/v2.2 built on varun/v2.1:

1. Closing the twelve 2.1 issues made all 2.1 releases Stable in about 35 s, and varun/v2.2.0 stayed Beta because of its own 2.2 issue.
2. Closing that 2.2 issue made everything Stable, with varun/v2.2.0 as Latest.
3. Reopening the 2.1 issues made every release Beta again.

The demo line was removed afterwards. How it works: docs/guides/releases.md.

---

All files are on each release's page, for example varun/v2.1.0. Later 2.1 releases have the same files with their own version in the name.

File	Contents
impress-varun-2.1.0.zip	the source at the release commit, the prebuilt firmware (release/firmware/) and the release notes
impress-varun-2.1.0-firmware.zip	gateway, hub and student images with their flash layout (flash_args) and checksums
impress-varun-2.1.0-docs.zip	the repository documentation and this wiki, for offline reading
SHA256SUMS.txt	checksums: sha256sum -c SHA256SUMS.txt
ghcr.io/kush-kelaiya22/impress-backend:varun-2.1.0	the backend as a container image (linux/amd64): see Installation → Container

The release page also has the set-up, test and deploy steps.

Area	What	Issue
CSV	Quiz questions from CSV: preview, warnings, all-or-nothing, duplicates skipped	#31
CSV	Courses and sections from CSV, with export: dry run, create or update mode, all-or-nothing, conflicts explained	#32
Firmware	Validated, immutable firmware registry: facts read from the image; content-addressed storage	#35
Firmware	Firmware page: upload with progress, approve, deprecate, history, devices per version	#36
OTA	Staged deployments: canary, batches, concurrency, failure limits, retries, timeouts, pause, resume, cancel, idempotency, durable across restarts	#38
OTA	The gateway updates itself over the air, with a health check, a 120 s watchdog and rollback	#34
OTA	Rollback: devices report rolled_back; operators can deploy an older image with explicit confirmation	#37
Devices	Health states and diagnostics (uptime, reset reason, boot count, lowest free memory, hub link)	#39
Devices	Student module inventory: every module a gateway has seen, filterable	#40
Hardware	PSRAM optional on the hub; documented hardware requirements; a reduced-flash hub profile	#30
Quizzes	Timed quizzes advance and end on a server timer; late answers are refused; modules show a countdown	#73
Releases	Automated releases with a Beta/Stable status that follows the test issues; a backend container image on GHCR	#96
Packaging	install.sh, start.sh, smoke_test.py; VERSION reported by /health; a clean-install CI job	#42
Tests	a simulated gateway, end-to-end quiz and OTA flows, fault injection, a test strategy, a hardware checklist	#43
Security	Per-device keys with enrolment, reset and revocation	#66 (#69)
Security	Signed firmware, verified on the device and at upload (opt-in)	#66 (#70)
Security	HTTPS/WSS for device traffic (opt-in)	#66 (#71)
Docs	README rebuilt; firmware versioning and recovery; hardware, testing and security documentation; this wiki	#44

Fix	Issue
The hub ↔ gateway SPI link used incompatible wire modes; v3's fixes were ported without its regressions	#29
OTA reported success before rebooting, with a hand-edited version, and the gateway dropped the report, so updates looped	#33
Random bytes were accepted as firmware, and versions could be silently overwritten	#35
Duplicate answers, votes and enrollments were possible under races; deletes left dangling references; the teacher's class delete returned 500	#41
Quizzes accepted 5–6 options, but modules have only four buttons	#49
A slow page could paint over the page you had moved to	#51
The gateway relayed every OTA prompt to its hub	#34
Registration dropped the reported firmware version	#38
A relayed student heartbeat overwrote the gateway's battery and signal readings	#40
The class page's live devices panel never started	#40
A database error on commit was an unhandled 500 (now 503, nothing saved)	#43
A wrong device key now gets 401, so firmware can tell a reset key from a refusal	#66
Timed quizzes advance (per-question) and end (total) on a server timer; Next works in every timing mode; late answers are refused; modules count down	#73
A completed quiz or closed poll could be restarted with its old answers or votes, and a draft could be stopped	#76

• Student modules have no OTA path: they are updated over USB.
• The mesh is not encrypted: a rogue module can claim a student's identity.
• Signed firmware and device TLS are off by default: turn them on before production.
• No v2.1 feature has been verified on hardware yet (the checklist).

The full list: docs/reference/known-issues.md.

1. Back up the database.
2. Update the backend: git pull, scripts/install.sh, restart.
   • Migrations (steps 1–8) run on the first start. They back up the database, repair dangling references, de-duplicate answers, votes and enrollments (keeping the earliest), and add unique indexes and the new columns.
   • Duplicate sections stop startup: if two classes share a course and section, startup stops and names them. Rename one and restart.
3. Flash every gateway and hub once over USB, together. The SPI wire mode changed on both ends (#29), and the gateway's bootloader gained rollback (#34). After this, both update over the air. The old WP/HD wires (S3 GPIO14/9 ↔ C6 GPIO3/4) are no longer used.
4. Device keys: nothing to do at first. Devices enrol by themselves on their next registration. When every device shows own key, set IMPRESS_DEVICE_KEYS_REQUIRED=true.
5. Optional, recommended before production:
   • signed firmware (Security → Signed firmware);
   • device TLS (Security → Device traffic over TLS). Serve TLS first, then deploy TLS firmware.
6. Static RAM after #29 (measured): gateway 41.5 % of DIRAM (was 33.5 %), hub 59.9 % (was 50.4 %).

---

The October 2026 audit. Fixes #1–#25, each on its own branch. Highlights:

Area	Fix
Gateway stability	a dangling SPI slave descriptor (#1); one cJSON batch mutated by two tasks (#4); the WebSocket client destroyed from its own task (#5); empty NVS values now fall back to defaults (#18)
Wire formats	S3 ↔ C6 batch records and framing unified in firmware/protocol (#2); the backend → gateway command contract pinned by a shared fixture (#3)
Mesh	de-duplication of relayed copies on the mesh and in the batch path (#6)
Hub	configuration loaded before the mesh starts (#7); an OTA prompt with nothing to do no longer reboots (#13)
Security	WebSocket teachers authenticated with their session (#8); the vote and answer routes need the device key and a registered device (#9); role escalation closed (#10); default secrets refused, a random first admin password (#11); databases untracked from git and session tokens stored hashed only (#12)
Classes and devices	joining by code adds co-faculty and never replaces the owner (#19); results need class access (#20); co-faculty can run quizzes and polls (#21); a gateway can't take over another class's gateway link (#17)
Errors	class creation (#15) and firmware upload (#16) no longer return 500; correct_option is validated (#22)
Tooling	CI and test infrastructure (#14); run_tests.py preflight, live progress, Ctrl-C and timeouts (#23–#25)

The full list: docs/reference/changelog-v2.md.