openFTTH
GitHub Download
FeaturesHow it worksDocsChangelogGitHub

Docs/Start

Your first design

From an area and an OpenStreetMap extract to a validated, priced design and its deliverables.

2 min read

This walkthrough designs a GPON network for an area from an OpenStreetMap extract: POP, FDHs, FATs, feeder, distribution and drop cables and chambers, validated, priced, and with every step kept as a version. The repository ships a small sample, a Gent suburb, in fixtures/gent/.

1. Gather the inputs

  • An area polygon, for example a GeoJSON file such as fixtures/gent/area.geojson.
  • An OpenStreetMap extract (.osm or .pbf) covering it, such as fixtures/gent/gent.osm. With no extract at all, the Surveyor can download one with fetch_osm, the only network call the engine makes, and only when asked.

If you have an address register, streets, existing ducts or other GIS layers instead, use File → Import data… (see Importing data).

2. Open a project

In the open-project form, give the area and the extract and pick a rulebook: generic-gpon (neutral), generic-xgspon, belgium (Flanders draft) or norway (draft, cascaded split). The rulebook holds every number the engine may use (see Rulebooks). Projects you opened before appear under Recent.

3. Design

Choose one of two ways:

  • Design automatically runs every engine tool in stage order with the engine alone: no AI and no cost. Each step appears in the conversation and on the map as a new version.
  • Ask the crew, for example: "Design this area with the Belgian rulebook." The Surveyor imports the data and builds the twin, the Planner places POP, FDHs and FATs and routes, the Checker validates, and the Drafter reports the BOQ. A risky step raises an approval card you answer.

The stage checklist follows the design as it moves from ingest to deliver. While the crew or the automatic design works, manual editing is locked.

4. Read the result

  • Validation. The Checker runs the design-rule checks, including the optical power budget for every home. Errors block; warnings, such as a home set deeper in its plot than the maximum drop, travel to the engineer and show in the BOQ tab as exceptions to accept.
  • BOQ. Quantities and prices from the rulebook's unit prices, labour and surfaces.
  • Trace. Any home's fibre path from OLT port to drop, hop by hop with loss.
  • Explain. Any element's attributes and the decisions recorded for it, with their reasons.
  • Versions and diff. Every tool call is one version; the Diff tab shows what was added, removed or modified.

5. Save the deliverables

Every deliverable saves out of File → Export: the map, the BOQ as CSV and JSON, the validation report, the splice schedule and a GeoPackage you can open in QGIS. See Exports.

The same from the command line

bash
cd engine
uv sync
uv run openftth-engine design --area ../fixtures/gent/area.geojson --osm ../fixtures/gent/gent.osm --rulebook ../rulebooks/belgium.yaml --out ../runs/gent --fresh
uv run openftth-engine versions ../runs/gent

Then look in runs/gent/deliverables/: map.png, boq.csv, validation.json, splice_schedule.csv and design.gpkg.