Handbook

How it fits together

One iPad runs everything. It is the server, the facilitator's control panel, and the source of the board the room watches. Students' phones are ordinary browsers — nothing to install, nobody to sign in.

All of it travels over your local Wi-Fi, and Halqa works perfectly on a network with no internet at all — worth knowing before you fight a school's firewall over it. The single exception is installing an activity from a link, which you have to ask for and which only ever fetches from halqa.education.

An activity is the unit you run: a single file holding either a set of challenges, a lecture built from your own slides, or both at once — questions sitting between the pages of a deck. It is the same mechanism either way, which is why a lecture needs no separate mode.

Your first session

1. Start the server on the iPad. A join code appears.
2. Teams join — one phone each, scanning the code or typing the address.
3. Pick an activity from the catalog and start it.
4. Reveal each round and let the room argue about the answer.

The bundled activity Run a Session teaches the app by being one. Running it with colleagues before you use Halqa with students is the fastest way to learn it, and takes about ten minutes.

The server and the PIN

Starting the server turns the iPad into a small web server on your local network. Stopping it ends the session: teams disconnect, scores are gone, and nothing is written anywhere — unless you have deliberately switched on the saved log described under privacy and data.

The facilitator PIN is six digits, generated once per install. It protects the facilitator page and the assistant connection. You can regenerate it — but only while the server is stopped, since restarting mid-lesson would clear the room.

Getting teams in

One phone per team, not per student. A team is a name someone types and a seat number — there are no accounts and no passwords.

• Lock joining once everyone is in, so a late scan cannot add a stray team mid-session.
• Reset room clears every seat. Use it if teams joined twice or with names you would rather not project.
• A phone that locks, sleeps or reloads picks up where it was. Only restarting the server ends a session.

Rounds and your controls

A round moves through phases, and what you can do depends on where it is.

Study only happens on rounds whose author asked for it — it exists so a room can read a diagram before anyone races. You never have to wait it out: Start answering ends it the moment the class is clearly ready.

Reveal now ends the round early. A round also reveals itself when the timer runs out, or as soon as every connected team has answered — so a quick room is never left waiting.

Skip abandons a round with no reveal and no score. Use it for a question that turns out to be broken or badly worded.

Back never re-opens anything. It puts an earlier round back on the projector for you to talk over, and the class does not move with it — see looking back.

Close returns to the catalog. It sits in the footer rather than among the round controls, deliberately: it is the rarest thing you will press and the most disruptive, and it asks for confirmation.

The board and projector

Two ways to get the board onto a screen:

• Connect the iPad to a display — by cable or AirPlay. The board takes over that screen and your controls stay on the iPad.
• Open the board address on a laptop that is already wired to the projector. Same page, no cables to rearrange.

The board scales itself to whatever screen it lands on, so a 4K projector gets 4K-sized text rather than a small layout stranded in the middle.

Light and dark

The Appearance setting covers the iPad, the board and every phone at once — one decision, because dimming the projector while the phones stay white is not a fix.

• Auto — each device follows its own system setting.
• Light or Dark — the whole room is forced to match, which is what you want in a hall with the blinds down.

Presenting your own slides

Send a PDF to the iPad — AirDrop, Files, or Open in Halqa from anywhere that shares — and it becomes an activity, one page per round. Nothing is rebuilt, nothing is uploaded, and it is playable the moment it lands.

Export from PowerPoint or Keynote to PDF first. Those formats are not read directly, and a PDF is the one thing every deck can already produce.

Presenting is the two controls you already know: Next moves the deck on, Back looks at what is behind. There is no timer on a page and nothing to reveal — you pace it.

Questions between the pages. A deck with challenges in it is the ordinary case rather than a special one: the slides pause, the room answers on their phones, the answer and the reasoning go up, and the deck carries on. Ask an assistant to insert a question after a given page — you never renumber anything by hand.

Drawing on the page

While a page is on the board, your panel is the page. Draw on it with a pencil or a finger and the room watches the line appear as you make it.

• Point — drag without drawing and a dot follows your finger on the projector, with a short trail behind it. Nothing is kept; it means something only while it is moving.
• Erase — takes away a whole stroke at a time rather than rubbing out pixels, so a wrong line goes in one gesture.
• Clear — wipes the page you are on. Only that page.

Annotation belongs to the page it was drawn on. Moving to the next page leaves the board clean; coming back to an earlier one brings its drawing with it. Nothing bleeds from a slide onto the question after it.

A blank page

When the deck has nothing for what you are about to explain, add a blank page: an empty page appears after the one you are on and the room moves onto it. Draw on it as you would any other page.

It lasts as long as the session and no longer — the PDF you imported is never modified, and a blank page nobody drew on quietly leaves no trace. It goes into the handout with everything else.

Looking back

Back means the same thing everywhere in Halqa: put an earlier round on the projector so you can talk over it. The lesson does not move. Phones stay on the round they are on, nothing re-opens, nobody is asked to answer again, and no score changes.

Next walks forward again through what you have already covered. At the far edge it asks before returning the room to the current round, so the tap that steps through history is never the tap that ends the walk.

A question you have already revealed comes back as its summary — the answer and the explanation as the room saw them — not as a question re-opened. You can draw on a page while looking back at it, and the drawing is still there when the lesson reaches that page again.

What students take home

A link on the student's own phone opens the lesson so far as a single page: every slide as it was shown with what you drew on it, and every question with its options, the answer and the explanation. Their browser's print sheet turns it into a PDF, which is the version that survives in Files.

• One document for the whole room, not one per team. It names nobody, carries no scores and records nobody's answers — it is the material, not a report on anyone.
• Available throughout, not only at the end. A class that overruns and never reaches the last slide still gets everything it saw.
• Only what has been covered. The rest of the deck is withheld, since handing it over would hand out the answers to questions nobody has been asked yet.
• It works after you close the lesson, so a student still holding the link does not lose it mid-bus-ride. It goes when you start the next activity or clear the room.
• Self-contained. The pictures are inside the file. It has to be, because the iPad's address stops existing the moment you leave the building.

The five round types

A slide asks for nothing, which is what makes a deck and a quiz the same kind of thing here. It has no timer, nothing to reveal and no score; a phone can ask to see the page if the back row cannot read the projector, and otherwise the phones stay quiet.

Discuss rounds never score. Every answer is accepted, everything scores zero, and all of them go on the board together. That is the point: some questions are for the conversation, not the leaderboard.

How scoring works

• Choice and Find it — correct answers score, and faster correct answers score more.
• Put in order — all or nothing. Exactly the right sequence, and the right items binned.
• Discuss — always zero.
• Slide — nothing is asked, so nothing scores.

Option order is shuffled every time a round is played. Nobody can learn that the answer is always the third one, and running the same activity with a second class is fair. An author can pin the order for a round where it genuinely matters — a numeric sequence, or a "none of the above" that has to come last.

Managing your catalog

As the catalog grows, search it or filter by tag. Selecting several tags narrows rather than widens.

Activities carry tags from whoever wrote them, and you can add your own. Your tags stay on your iPad — sharing an activity does not pass your filing system to anyone else.

Bundled activities can be hidden rather than deleted, and restored later. Imported ones can be deleted outright.

Sharing activities

An activity is a single file. Send it by AirDrop, email or any file sharing — the recipient opens it and it appears in their catalog. No update, no rebuild, no store.

Use Share… on any activity to export it, including the bundled ones, which is a reasonable starting point for one of your own.

A lecture is shared the same way, and carries its pages with it — the recipient needs neither your PDF nor the app that made it.

Authoring mode

Authoring mode enables the design tools: Pack Studio in a browser, and the connection an AI assistant uses to build activities directly onto the iPad.

It is off by default, and only changeable while the server is stopped. With it off, those endpoints are not merely refused — they do not exist, so a classroom iPad exposes nothing that can write to it.

Working with an assistant

1. Turn on Authoring mode and start the server.
2. On the iPad's panel, tap How to make a Halqa pack and copy the connection address from there. It is behind that button rather than on the panel itself because it carries your facilitator PIN, and the panel is what the projector mirrors.
3. Paste it into your assistant. Any assistant that speaks the Model Context Protocol will do — this is not tied to one product.
4. Describe the activity you want in plain language.
5. It drafts the activity, checks it, and installs it. Nothing to copy, zip or transfer.

What to say matters more than how you say it. The topic, and what teams have to decide — an activity needs a disagreement, not a recall exercise. Then length, roughly how many teams, and any round types you want.

The checks are structural. They confirm an activity is well-formed — round types, required fields, missing images. Nothing can tell you a question is wrong, ambiguous or dull. Run a new activity once yourself before you play it with a class.

Activities that contain code

Most activities are pure data: questions, pictures, answer keys. One can also carry a small program defining its own rules — that is how self-paced races and per-team content work.

Installing such an activity means running someone's code, so Halqa holds it back: it arrives on the iPad but cannot be played until you review and allow it. The review screen shows what the activity declares — where it came from, how many rounds, what files it brings, and that it contains a program.

Themes

A facilitator can restyle the room — colours, corner rounding, font, and a background image per surface. Themes apply to the phones, board and facilitator page. The iPad's own control panel deliberately stays looking like iPadOS: it is your instrument, not part of the show.

Background images are blended with the palette, so a picture takes the theme's hue and contributes only its light and shade. Any image fits without colour-matching, and it doubles as a wash that keeps text readable. The trade is that a photograph reads as texture rather than keeping its own colours.

Troubleshooting

Students cannot open the join page

Almost always the network. Phones must be on the same Wi-Fi as the iPad, and guest networks usually block devices from talking to each other, which blocks this too. Scanning the code avoids typos.

The line under the join address says which kind of network the iPad is offering — the Wi-Fi it is on, or its own hotspot. It cannot name the network, only its kind, which is enough to catch the common mismatch of a room on the school Wi-Fi and an iPad quietly serving something else.

Nothing useful on the projector

The display is set to extend. Switch it to mirror. Failing that, open the board address on a laptop already connected to the projector.

A team shows as disconnected but they are fine

A phone coming and going is noticed within roughly half a minute, not instantly, so a brief grey dot during a lull is normal. If it stays grey, the phone really has lost the network.

A phone locked or reloaded

Nothing is lost — it remembers which team it is and asks the iPad for the current state. Only restarting the server ends a session.

The answers are in a different order than last time

Deliberate. See scoring.

I went back a page and the phones did not follow

That is what Back is for. It moves the projector, not the class — see looking back. Nothing re-opens and no score changes, and Next asks before it puts the room back on the current round.

Something I drew has gone

Drawing belongs to the page it was drawn on, so the board clears when you move on and the drawing returns when you step back. All of it is in the handout for as long as the session lasts.

My PowerPoint will not import

Export it to PDF first. Halqa reads PDF only — it is the one format every deck can already produce, and reading the others would mean rendering someone else's layout engine on an iPad.

Something went wrong and you want to report it

The ⋯ menu in the sidebar has Export Error Log under Debugging — a record of errors from the session. Attaching it is far more useful than describing what happened.

Privacy and data

Halqa collects nothing. No accounts, no analytics, no third-party services. A team name and seat number exist only while the session runs.

The app makes no outbound connections except one you ask for: pasting a halqa.education link to install an activity fetches that file and sends nothing about you. No session data leaves the iPad by any route.

You can export a session log — teams joining, rounds revealed, rounds skipped — as a CSV. It is a record of the session, not a grade book, and it stays on the iPad unless you share it.

The handout students can save is deliberately not personal: one document for the whole room, carrying the material and the discussion but no team names, no answers attributed to anybody and no scores. It is generated on request and never stored.

The saved log is the one thing Halqa can write to disk, and it is off until you turn it on. It lives behind the ⋯ menu beside Export Error Log, and it exists so that a session that crashed — or an iPad that went to sleep mid-lesson — leaves something to read afterwards, which the in-memory log cannot.

Each line is a timestamp and a short phrase: the activity started, each round opening and being revealed, teams joining by the name they chose, and that a team answered a given round — never what it chose or wrote. No scores, nothing drawn on a slide, no addresses, and nothing from a phone beyond its team name. The privacy page lists every line it can write and shows a real excerpt.

It stays on the iPad, is excluded from backups, is deleted after three weeks, and the same menu deletes it on the spot. If your class uses real names as team names, those names are in it — the same is true of the session CSV, and table numbers avoid both.

Full detail: the privacy policy.

Limits

• One activity at a time. A session has one active activity.
• PDF only for decks. Export from PowerPoint or Keynote first.
• Drawing is the pencil and an eraser — no shapes, no text boxes. Halqa is not trying to be a whiteboard.
• Around a hundred phones has been tested without errors — well past a normal class. Your Wi-Fi will run out of room before Halqa does.
• No per-student results. There are teams, not accounts, and nothing survives the session but the log you choose to export.
• Written answers are never marked automatically unless an activity carries its own scoring code.