openFTTHDocs/Design
Rulebooks
The YAML file that holds every number a solver or validator may use.
A rulebook is a YAML file holding every number a solver or validator may use: optical budgets, split ratios, cable sizes, distances, losses, capacities and prices. The crew can read it, explain it and change single values on your request; it can never bypass it. A copy of the rulebook used is saved in every project as rulebook.yaml.
Presets
| Preset | What it is |
|---|---|
generic-gpon | Neutral: centralised 1:32 split GPON, class B+, underground in footpaths. |
generic-xgspon | The XGS-PON counterpart. |
belgium | Flanders draft. |
norway | Draft, cascaded split. |
The presets live in rulebooks/.
Where the numbers come from
Every value in a preset carries a comment: # source: ... for a public specification or datasheet, # assumed otherwise. A design partner reviews the assumed values before a preset is called anything but "draft". An excerpt from generic-gpon.yaml:
pon:
class: B+ # source: ITU-T G.984.2 amendment 1, class B+
budget_db: 28.0 # source: G.984.2 B+ max ODN loss
min_loss_db: 13.0 # source: G.984.2 B+ min ODN loss
max_differential_db: 15.0 # source: G.984.2 max differential optical path loss
split_ratio: 32 # assumed: most common residential design
cascade: null # centralised split in the FDH
distances:
max_drop_m: 150 # assumed: typical limit for a drop without a mid-span closure
max_dist_m: 2000 # assumed
max_reach_km: 20 # source: G.984 logical reach 20 km
max_pull_m: 250 # assumedSections
| Section | What it sets |
|---|---|
pon | technology (gpon, xgspon or gpon+xgspon), class and budget, split ratio, optional cascade, architecture, worst-case wavelength |
fibers | distribution and feeder ladders, drop fibres, spare %, take rate |
homes | count dwelling units, apartment estimation when there is no unit data |
distances | max drop, max FDH→FAT, logical reach, pulling distance |
loss_db, connectors_per_path | connector, splice and splitter losses, fibre attenuation per wavelength, design margin |
fdh, fat, chambers, closures, slack, ducts | capacities, fill limits, placements, sizes |
routing | OSM highway classes no cable may follow |
surfaces, highway_to_surface | trench + reinstatement cost per metre by surface, and which surface each highway class trenches in |
aerial, facade | cable on existing poles or along building fronts (facade is off by default; it needs the owners' consent) |
inside | blocks of flats: riser, floor boxes, flat cabling |
phasing | number of build phases and their order; one BOQ per phase |
crossings | the price and longest length of a bore under a motorway, railway, water or unmapped obstacle |
pops | max_units, the units one POP serves |
units, labour | unit prices |
Changing prices and limits
Ask the crew to change a single value, for example a unit price or distances.max_drop_m; the crew changes single values on your request and can never bypass the rulebook. If you edit a rulebook file yourself, validate it:
uv run openftth-engine rules validate rulebooks/belgium.yamlThe schema is rulebooks/schema.json, generated from the engine's model; do not edit it by hand. The full reference is docs/RULEBOOK.md.