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)
  1. 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 .env file next to docker-compose.yml:

    export OCID_TOKEN=pk.your_token_here
    echo "OCID_TOKEN=pk.your_token_here" > .env
    

    You 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.

  2. Build and start the stack:

    docker compose up --build
    

    MariaDB is initialised from init.sql on 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.

  3. 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=testtoken in 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.

NLnet foundation logo