Porygon Server
Central GNSS Frame Processing Server Software
This service receives GNSS frames from GNSS base stations, and processes/deduplicates/verifies them. It then provides APIs to access known GNSS frames. Like the rest of the OpenAGPS stack, this is still in development.
Please refer to the Porygon API documentation to dive into the details of Porygon's http-based JSON API.
- Docker with the Compose plugin (
docker compose version)
Set your OpenCellID token. The cell-tower updater needs an API token from opencellid.org. Export it in your shell, or put it in a
.envfile next todocker-compose.yml:export OCID_TOKEN=pk.your_token_here echo "OCID_TOKEN=pk.your_token_here" > .envYou can skip this if you only want to test the GNSS endpoints and not the cell location feature — leave the variable empty and the updater will simply fail silently in the background.
Build and start the stack:
docker compose up --buildMariaDB is initialised from
init.sqlon first start. The Porygon API will be available at http://localhost:8080 (Swagger UI at http://localhost:8080/docs). This will automatically attempt a database refresh.Add a test token so the authenticated endpoints accept requests:
docker compose exec db mariadb -u root -pmypass config \ -e "INSERT INTO tokens (token, user) VALUES ('testtoken', 'local-dev');"Then pass
?token=testtokenin your requests. Tokens are generally only required to test endpoints used by GNSS base stations.
MariaDB data is stored in the named volume db_data. To wipe it and start fresh (e.g. to re-run init.sql):
docker compose down -v
tools/test_locate.py picks a random location on Earth that has cell coverage, gathers nearby towers from the database, and calls /locate/cell. It then reports how far the API's estimate is from the true geographic centre of those towers — so you can see both that the pipeline works and how accurate the result is.
docker compose up -d
docker compose exec porygon python /tools/test_locate.py
docker compose exec porygon python /tools/test_locate.py --simulate-rssi
docker compose exec porygon python /tools/test_locate.py --radius 5 --count 10
Sample output:
Database contains 38,942,117 towers.
Searching for a random area with coverage (radius=15 km)…
Anchor (centroid of 5 towers): 48.856400, 2.352200
LTE MCC=208 MNC=1 LAC=27610 Cell=12345678 (0.4 km from anchor)
LTE MCC=208 MNC=10 LAC=52032 Cell=87654321 (1.1 km from anchor)
GSM MCC=208 MNC=20 LAC=18320 Cell=4321 (2.8 km from anchor)
UMTS MCC=208 MNC=1 LAC=27610 Cell=9876543 (4.3 km from anchor)
LTE MCC=208 MNC=15 LAC=52100 Cell=11223344 (6.7 km from anchor)
POST http://localhost/locate/cell
True centre: 48.856400, 2.352200
API result: 48.858100, 2.349700
Error: 230 m (API reported ±410 m) ✓ within reported accuracy
tools/ofono_locate.py queries ofono over D-Bus for the currently registered serving cell and sends it to the API. Run it on the Ubuntu Touch device (directly or over SSH).
python3 tools/ofono_locate.py \
--api http://DESKTOP_IP:8080
DESKTOP_IP is the LAN address of the machine running docker compose up. The Ubuntu Touch device and the desktop must be on the same network.
- GNSS Base station receiving
- Access API
- Ability to have several (physical) servers and fail over in case of downtime on one
- Ability to read GNSS data from other public sources
This project is funded through NGI Mobifree Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet program. Learn more at the NLnet project page.
