Atalaia
The open force-on-force platform. Project page: Português · English
Manuals for the people who use it (players, game masters, marshals, box operators): English · Português · all manuals
Atalaia is an open, local-first platform for airsoft, paintball and milsim game props. Build a domination box from a €20 microcontroller, turn an old Android phone into a hacking terminal, run a 20-box weekend milsim on a LoRa mesh, and write your own game modes as small scripts. No cloud required, no vendor lock-in.
Atalaia is Portuguese for "watchtower" (why that name?).
Status: pre-alpha. Nothing here is ready for the field yet. The software has gone ahead of the hardware:
- Phase 0 (foundations) is complete.
- Phases 1 and 2 are done in software; real Heltec V4.3 boards already play whole games with the field controller on the bench. The Field Box's game-timer bar, its setup re-send with a box acknowledgement, the Change field menu entry and a bigger firmware partition table (4 MB slots; a box on the old table needs one USB flash) are built in software and host tests only, not yet seen on a real board. Found on the bench on 29 October and fixed: a change of the field's channel no longer strands the free boxes (a new radio message, MOVE), a start reaches the boxes in about a second (the state is repeated as TIME), the projected score follows a capture, a box's
game.end ends the game (so a Bomb / Rush explosion does) and the Field Box's internal memory fits Wi-Fi and its new iBeacon (never at the same time); the radio fixes still need their two-board check, and nobody has yet checked that a phone hears a real box's beacon. The box no longer fetches the field's logo: it shows the Atalaia tower, replaceable at build time. The first Field Box bench build (loose wires, no enclosure) plays Domination with the bench controller, its big screen showing a hold bar, the held time and each team's points, as the small screen does; the same screens for Master and Satellites (MESTRE / SATÉLITE), Progressive Domination and VIP Payload, the big screen's boot splash (the tower and the version), a fix so that a flaky I2C bus no longer reboots a box (a restart now reports its real reason, a crash included), a check that refuses a screen text that does not fit (a failed one shows ?, not a blank) and the singular for a count of one are in reference images and host tests, not yet seen on a board. The gates wait for built boxes and field tests.
- Phase 3 (Android and players) is done in software, the iOS app included (it has passed its checklist on an iPhone); the app now follows a game from the scoreboard's QR code, shows a field plan and game history, relinks to a lost I/O pod by itself (whose settings the GM console can now push over the radio), and logs in with Google, Microsoft, Apple or a passkey (Android, and on iOS in Swift: compiled on CI, passkeys opt-in at build time) and draws the field's grid, but none of that has been tried on a real phone or pod (the iPhone's site login not at all), and none has been in a field. Indoor beacons (the GM's, and now the Field Boxes') work from Android in software only; the iPhone plugin over CoreLocation is built and compiled on CI, not yet tried on an iPhone. A standby controller takes the beacon choices and the boxes' places from its join, and a console open on it moves the boxes' markers at once.
- Phase 4's site server now has staff pages, field settings and branding pushed to the controllers, login with Google, Microsoft or Apple and passkeys, association membership checks (APDs in Portugal), hosted-mode quotas and custom domains, data retention per field, the published privacy notice (with re-consent) and a database role per hosted field, and a read-only live demo (alternating an open field and a three-storey building); social accounts choose a username, any account can rename itself, two accounts of one person can be merged, a social sign-up records the privacy-notice version the person saw and the daily purge deletes anonymised accounts nothing refers to. The security and privacy review of 30 October added a second factor for changing how an account logs in, request limits, an audit log that forgets addresses after 180 days, inactive accounts anonymised after 24 months, erasures that reach other fields and survive a restore, game history kept 90 days (team results without player ids 365), accounts on the contract with a minimum age of 16, the sharing terms a field accepts before it shares chrono readings, and one social-login callback for a whole hosted hub. It has been tested on a computer; Google and Microsoft login have also been tried against the real providers on the test server (tests.atalaia-project.link), Apple not yet, and the username step and the merge are still to be tried there.
What it looks like
The eight captures below show the real Field Box firmware (ESP32, LVGL 9.2, 320×240 TFT) running in the Wokwi emulator. The box UI is in English. Not yet tested on physical hardware.
A mode's screens change as its game goes on. The animation below is drawn by the firmware's own screen code, the big screen and the small OLED: in Domination a zone nobody holds, red claiming it by holding its button, its points counting up, blue taking it over, and the final score. The modes page has one for thirteen modes, in Portuguese, English, German and Traditional Chinese (python3 tools/gen_mode_gifs.py makes them).
The Android app (phase 3, in Portuguese here) draws the same mode screens from the same YAML files. These are its test images, not photos of a phone: nothing has run on a real phone yet.
Why Atalaia
Electronic game props add a lot to a game, but commercial systems keep the rules locked inside closed firmware. Every new game mode waits on the vendor, there is no public API, and you cannot add your own hardware.
Atalaia takes a different approach:
- Local-first. Every game runs fully offline, from a single house to a multi-kilometre forest. The internet is optional.
- Any hardware. ESP32 boards, Raspberry Pi, Arduino-class boards and new or repurposed Android phones all work in the same game.
- Game modes are scripts. Modes are short Lua scripts with a settings file. Change or share a mode without reflashing anything.
- Open protocol and API. Props talk over the documented Skirmesh-RF protocol, and the field controller exposes MQTT, REST and WebSocket APIs for scoreboards, overlays and your own tools.
- Built for players and fields. A player app with roles (player, squad leader, VIP, marshal, GM), squads, custom scenarios, and a chrono registry with spot checks to catch power changes after check-in.
- Copyleft. Anyone can use Atalaia, including fields that charge entry fees and makers who sell boxes. Anyone who distributes or hosts a modified version must share their changes.
How it fits together
Site server (optional)
accounts · history · player app · chrono
│ internet
GM & player apps ── Field controller ── Scoreboards, ATAK, webhooks
(Wi-Fi) Raspberry Pi / Android (MQTT, REST)
│
Skirmesh-RF (LoRa mesh)
┌──────────┬──────┴──────┬──────────────┐
Field Box Satellite Android prop Thin node
(ESP32) (ESP32) (+ ESP32 pod) (Arduino)
Every full node runs the same C11 core and the same Lua game modes; only the platform shell and hardware drivers differ. The complete design is in the design specification, and how the parts talk to each other is shown in diagrams.
How the radio works
The props talk over LoRa, a long-range, low-power radio, in Atalaia's own protocol, Skirmesh-RF. None of it has been on a real field yet: range and timing will be measured in the phase 2 field test.
What LoRa can do. LoRa trades speed for reach: it gets short messages across a field on very little battery, and its signal gets through walls and trees better than Wi-Fi does, although concrete, metal and hills still block it. A box that cannot reach the controller is heard through the other boxes, and European rules limit how much of the time each device may transmit.
Which channel, and why 869.525 MHz. All of a game's traffic shares one channel. The default, 869.525 MHz, is the centre of 869.4–869.65 MHz, the only part of the European 868 MHz band where a device may transmit up to 10% of the time at up to 500 mW (ERP). Elsewhere in 868–870 MHz the rules allow 1% of the time (0.1% on 868.7–869.2 MHz) at 25 mW: about a tenth of the airtime, and much less range. 868.1, 868.3 and 868.5 MHz are LoRaWAN's default channels and often busy. The default is shared too: LoRaWAN gateways send some replies on 869.525 MHz, and Meshtastic's European default is the same frequency; nobody's packets are mistaken for anyone else's, but everyone nearby shares the airtime. So the GM chooses the field's channel in the GM console: keep 869.525 MHz, let the controller's USB modem listen to every legal channel for about a minute and suggest the quietest, draw one at random, or pick one by hand. The boxes and the modem then follow that channel's own power and duty-cycle limits, and a channel must fit inside one sub-band as a whole. Sources and details: RFC 0001 Amendment 3 (ERC Recommendation 70-03 Annex 1, ETSI EN 300 220-2, LoRaWAN Regional Parameters) and controller/README.md.
Radio regions: Europe and Taiwan. A field is in one radio region, chosen once in the GM console ([radio] region). In Taiwan (AS923, 920–925 MHz) the NCC's rules (LP0002 5.8.1) give a single channel that does not hop full power only if it is at least 500 kHz wide, so there the boxes use LoRa SF9 at 500 kHz (about the range of SF7 at 125 kHz), at most 0.5 W at the antenna, and 921.5 MHz by default. Every box, USB radio modem and I/O pod is built for one region (docker_fw.py build --region=as923-tw) and refuses the other regions' channels and joins. The Taiwanese region is in software and host tests only: not tested on air, and not certified (a product sold in Taiwan needs NCC type approval and an antenna made for 920 MHz). Details: RFC 0001 Amendment 12, decisions RF-AS923-1 to -14.
One protocol on every device. Skirmesh-RF is built in layers, from the radio up to the controller's API. A Field Box runs everything up to the game modes; a Raspberry Pi controller leaves the radio work to a USB radio modem; in phase 3 an Android phone does the same with an I/O pod, whose firmware is the USB modem's radio code. Phones on the field's Wi-Fi need no LoRa radio at all. The wire format is RFC 0001.
The diagrams are built in English and Portuguese, for wide and narrow screens, from site/src/diagrams/ by tools/build_site.py; the project page's radio page shows them in your language (Português · English).
Repository layout
| Folder | What lives there | Licence |
|---|
core/ | Shared C11 core: event bus, state store, Lua sandbox, protocol codec | GPL-3.0-or-later |
protocol/ | Skirmesh-RF message and event schemas; usb-modem.md (modem framing); join.md (join payload) | GPL-3.0-or-later |
modes/ | Built-in game modes (Lua + manifest) | GPL-3.0-or-later |
firmware/ | ESP32 firmware (ESP-IDF) and Arduino thin-node firmware | GPL-3.0-or-later |
app/ | Flutter app: props and the phone controller (Android), player, marshal and GM roles (Android; iOS too: its checklist passed on an iPhone on 2026-10-26: guide) | GPL-3.0-or-later + app-store permission |
controller/ | Field controller (atalaia_controller) and GM console (controller/console/, served at /console/) | AGPL-3.0-or-later |
See LICENSING.md for the details.
Roadmap
| Phase | Focus | Status | Done when |
|---|
| 0 · Foundations | Shared core, Lua sandbox, Skirmesh-RF codec, browser simulator | Done | The simulator runs Domination and Bomb from Lua scripts |
| 1 · Single box · status | Field Box firmware and build manual | Software done; a real board plays whole games on the bench, and the first Field Box bench build shows a hold bar, held time and team points on its big screen; game-timer bar, setup re-send, Change field and the 4 MB partition table (one USB flash for boxes on the old one) in software only; the Field Box advertises as an iBeacon in a game and shows only the Atalaia tower (no field logo), its memory budget measured on the bench; no phone has yet heard a real box's beacon; the big screen's boot splash, the other modes' screens and the I2C fault handling (a flaky bus no longer reboots a box; a restart says why) in host tests only; radio replay window and PIN-gated serial commands in software only | One box runs a 2-hour club game with no restarts |
| 2 · Field network · status | Skirmesh-RF over LoRa, field controller, GM console, mode pack, the box's Wi-Fi setup | Software done; scenarios in German and Traditional Chinese; two bench boards play with the controller; boxes listen before they talk (simulator: 89 % of updates heard at 20 boxes, from 65 %); controller TX pacing built, off until the field test; a new mode, Sabotage (Bomb in rounds with a score), in the simulator and the box's presets; bench findings fixed (channel change keeps the free boxes, start reaches the boxes in about a second, projected score follows a capture, a box's game end ends the game, a Bomb explosion ends it), the two-board radio check still to do; a Find boxes sweep is capped per hour on channels with little air time; recorded commands refused by a replay window per sender, controllers hardened (HTTPS-only tokens, MQTT TLS, fail-closed revocation), a second epoch-store loss cannot draw lower and a former leader keeps no old node id (Amendment 25), a controller's lost epoch draw can no longer run out of range, Master and Satellites test-played on four bench boxes, a tried on the bench (not on a Pi or in a field), none of the rest on real boards yet |
What each phase has done, what is next and what it waits for is on the roadmap page, as short lists, and in each phase's STATUS.md.
Getting started
Run the simulator (no hardware needed). Build the core and run its tests and every mode's tests:
sh tools/check.sh
You need a C11 compiler, CMake 3.16 or newer, Python 3.10 or newer and PyYAML. No compiler? Use the dev container. To play a mode in your browser, holding team buttons and watching the props' screens and the event log, see the simulator. To write a mode, start with modes/README.md.
Get the firmware. Ready-made images (Field Box and Satellite, the controller's USB modem, the I/O pod) are on the Releases page, signed by the project's release keys: pre-alpha and not field-tested (firmware guide). The controller's radio modem has its own setup guide. Or build the Field Box firmware yourself (cross-compiles in Docker, no toolchain needed locally; works from cmd, PowerShell or bash):
python tools/docker_fw.py build # the firmware, in firmware/esp32/build/
python tools/docker_fw.py test # its host tests and screen reference images
python tools/docker_fw.py wokwi # the variant for the Wokwi emulator
Run the field controller and its GM console on a laptop, without a radio, in the dev container (see controller/README.md): the console is at http://localhost:8080/console/ and the scoreboard at /scoreboard. The console's browser tests run with python tools/docker_console.py.
Run the site server's tests (its skeleton, accounts, personal data rights, the controller sync, the chrono registry, scheduling with the public field pages and feeds, registration with the game-day roster, and the registration import with platform adapters exist so far, the sync tested end to end against the real controller) against a throwaway PostgreSQL 16 in Docker: python3 tools/docker_server.py test, python3 tools/docker_server.py migrations, python3 tools/docker_server.py deploy (the deployment behind Caddy) and python3 tools/docker_server.py browser (the staff pages in headless Chromium); up and down start and stop a local trial. See server/README.md.
To play a game on an emulated Field Box in VS Code before any hardware exists, see firmware/esp32/docs/WOKWI.md. See firmware/esp32/README.md for the full build guide, Kconfig options, pin table, and bring-up checklist.
Contributing
Atalaia is built by players, field owners and makers. You can help by:
- asking questions and sharing ideas in Discussions,
- reviewing the design specification and opening issues,
- proposing game modes with the Game mode idea issue template,
- writing code for any phase-0 task,
- sharing how your field plays, so the defaults fit real games.
Please read CONTRIBUTING.md first. Every commit needs a Signed-off-by line (git commit -s), and we follow a strict clean-room policy: no code, firmware, manuals, sounds or images from any commercial product.
Safety
Atalaia props are game equipment. Make them look like game props: bright colours, clear "GAME PROP" labels, and nothing resembling a real explosive device. Transport them in labelled cases, never leave them unattended outside the field, and treat lithium batteries with care. The design specification covers field safety and radio regulations in more detail.
Name
An atalaia (say "ah-tah-LYE-ah") is a watchtower: a lookout post on a hill or a stretch of coast whose crew watched for trouble and passed the warning along. The word came into Portuguese from the Arabic aṭ-ṭalāʾiʿ, "the scouts" or "the vanguard", and estar de atalaia still means "to be on the lookout". Atalaias are scattered across Portugal's coast and countryside, and several towns carry the name.
It turned out to be an accurate name for this project:
- A field controller is a watchtower. It sits somewhere high, sees every prop on the field, and tells the GM the moment something changes.
- Watchtowers were local-first. No tower ever waited for a cloud service. They worked with what was in sight.
- They also ran the original low-bandwidth mesh. Smoke by day, fire by night, relayed from tower to tower: tiny messages, long range, very little airtime, a limited number of hops, and nobody streaming video. Skirmesh-RF follows the same rules with LoRa and fewer burnt eyebrows.
- The Arabic root means "the scouts". That's a reasonable description of anyone who has ever played milsim.
- It's a real word, not a product name. Portuguese speakers can say it without trying, and everyone else gets to learn one new word.
Forks are welcome under the licence, but please give your fork its own name so players can tell it apart from the original project. Every watchtower needs its own hill.
Licence
Atalaia is free software. The core, firmware, app and modes are licensed under the GNU GPL v3 or later; the field controller and site server under the GNU AGPL v3 or later; hardware designs under CERN-OHL-S-2.0; documentation under CC BY-SA 4.0. See LICENSING.md.
