FiberWeave

1. Introduction

1.1 What is FiberWeave?

FiberWeave is a QGIS plugin that provides a complete fiber optic network planning and management solution. It integrates directly with QGIS to combine geospatial mapping with ITU-T compliant FTTX/FTTH design, power budget calculations, inside plant management, bill of materials generation, and automated reporting.

FiberWeave stores all network data in a PostgreSQL/PostGIS database using the fttx schema, giving you full spatial query capabilities and multi-user collaboration.

1.2 System Requirements

1.3 Key Concepts

FTTX Network Architecture

FiberWeave models a Passive Optical Network (PON) with the following hierarchy:

Core Database Layers

2. Installation

2.1 Installing the Plugin

Option A: From FiberWeave Repository (Recommended)

1. Open QGIS and navigate to Plugins > Manage and Install Plugins.
2. Click the Settings tab.
3. Under Plugin Repositories, click Add...
4. Enter the name FiberWeave and the URL:
   https://qgis.devitt.co.za/plugins.xml
5. Click OK, then go to the All or Not Installed tab.
6. Search for FiberWeave and click Install Plugin.

Option B: Manual ZIP Installation

1. Download the plugin ZIP from https://qgis.devitt.co.za/plugins/fiberweave.zip
2. In QGIS, go to Plugins > Manage and Install Plugins > Install from ZIP.
3. Browse to the downloaded ZIP file and click Install Plugin.

After installation, the FiberWeave toolbar will appear in the QGIS interface.

2.2 Database Setup

FiberWeave requires a PostgreSQL database with PostGIS enabled. You can set this up using the built-in Database Installer.

1. Click Setup Database on the FiberWeave toolbar (the first button in the Connection group).
2. Enter your PostgreSQL connection details:

   Field	Default	Description
   Host	localhost	Database server address
   Port	5432	PostgreSQL port
   Connect to Database	postgres	Initial connection database
   Username	postgres	PostgreSQL superuser
   Password	(enter yours)	Database password
   New Database Name	fiberweave_network	The database to create

3. Click Test Connection to verify connectivity.
4. Click Install Database to create the database.

The installer will automatically:

• Create the fiberweave_network database
• Enable the PostGIS and PostGIS Topology extensions
• Enable pgRouting (if available)
• Create the fttx schema
• Run all numbered SQL migration files to create tables, indexes, and seed data

3. Getting Started

3.1 The FiberWeave Toolbar

The FiberWeave toolbar is organized into five groups:

3.2 Connecting to a Database

1. Click Connect Database on the toolbar.
2. Enter connection parameters:
   • Host: localhost (or your server address)
   • Port: 5432
   • Database: fiberweave_network
   • User: budget_user (or your configured user)
   • Password: (enter at runtime)
3. Click Test Connection to verify, then click Connect.

3.3 Loading Layers and Styles

After connecting to the database:

1. Click Load Layers to add all 7 core layers to your QGIS project. Each layer is loaded as a PostGIS layer from the fttx schema.
2. Click Apply Styles to apply FiberWeave's categorized symbology. This sets up:
   • Color-coded symbols based on feature type and status
   • Custom attribute forms with dropdown menus (ValueMaps)
   • Auto-calculated fields (e.g., cable length from geometry)
   • Snapping configuration (10-pixel tolerance, vertex + segment, topological editing)

3.4 Generating Sample Data

To explore FiberWeave before working with real data, generate a sample network:

1. Click Reports > Generate Sample Data from the toolbar.
2. Choose the number of ONUs to generate (10 to 500, default 64).
3. Click Generate.

The sample data generator creates a complete GPON network with the following components in 10 automated steps:

1. OLT equipment (central office)
2. PON ports on the OLT
3. Cable routes (conduit and aerial infrastructure)
4. Fiber cables (backbone, distribution, and drop)
5. Fiber strands within cables
6. Primary splitter (1:8 ratio)
7. Secondary splitters (1:32 ratio)
8. Splice points at cable junctions
9. ONU equipment at customer premises
10. Network paths linking each ONU to its OLT

4. Planning Workflow — Step by Step

4.1 Overview: The 8-Step Planning Process

FiberWeave provides a structured workflow for planning a fiber optic network from scratch. Following these steps ensures your design is complete, compliant, and validated.

4.2 Step 1 — Project Setup

1. Install and connect to the FiberWeave database (see Chapter 2).
2. Click Load Layers to load the 7 core layers.
3. Click Apply Styles to set up symbology, forms, and snapping.
4. Save your QGIS project (Ctrl+S).

4.3 Step 2 — Define Coverage Area

Before placing equipment, identify your target area:

• Load a base map (OpenStreetMap, satellite imagery, or cadastral data).
• Use QGIS's built-in tools to import building footprints or address points for your service area.
• Alternatively, use Reports > Import Data to import existing building, cable, or equipment data from CSV, Shapefile, Excel, GeoJSON, KML, or other formats.

4.4 Step 3 — Network Design (Planning Wizard)

The Planning Wizard automates the initial network design calculations:

1. Click Planning Wizard on the Design toolbar group.
2. Page 1 — Project Info: Enter the project name and description.
3. Page 2 — Coverage Area: Specify the total number of customers (premises) to serve.
4. Page 3 — Network Design: Select the splitter ratio (e.g., 1:32 or 1:64). The wizard automatically calculates:
   • Number of OLTs required
   • Number of PON ports needed
   • Optimal splitter cascade configuration
5. Page 4 — Review: Review the design summary and confirm.

4.5 Step 4 — Add OLT Equipment & PON Ports

Place your central office equipment on the map:

1. Select the OLT Equipment layer and toggle editing (Ctrl+E).
2. Use the Add Point Feature tool to place the OLT at the central office location.
3. Fill in the attribute form: name, vendor, model, capacity, and status. The form provides dropdown menus for standardized values.
4. Click Add PON Port on the toolbar to add ports to the OLT:
   • Select the OLT from the dropdown list
   • Enter the port number and label (or use auto-generate)
   • Select the budget class: A, B, B+, C, C+, or C++
   • Set maximum reach (km) and maximum ONUs

PON Budget Classes

4.6 Step 5 — Design Cable Routes & Fiber Cables

Create the physical infrastructure paths and fiber cable runs:

Cable Routes (Infrastructure)

1. Select the Cable Routes layer and toggle editing.
2. Use the Add Line Feature tool to draw conduit, aerial, or underground routes.
3. In the attribute form, set the infrastructure type:
   • underground_conduit — Buried conduit
   • aerial — Pole-to-pole overhead
   • direct_buried — Direct-buried cable
   • micro_trench — Micro-trenching

Fiber Cables

1. Select the Fiber Cables layer and toggle editing.
2. Draw cables along the routes you created. Snapping ensures cables align with route geometry.
3. Set the cable type in the form:
   • backbone — High-count trunk cables from OLT to distribution points
   • distribution — Mid-count cables from splitters to drop areas
   • drop — Low-count cables from access points to individual premises
   • indoor — Inside building cables
4. Specify the fiber count, cable model, and status. The cable length is automatically calculated from the drawn geometry.

4.7 Step 6 — Place Splitters & Splice Points

1. Select the ODN Nodes layer and toggle editing.
2. Place splitter nodes at distribution points. Set the node type to splitter and choose the split ratio:
   • 1:2, 1:4, 1:8, 1:16, 1:32, or 1:64
3. The insertion loss is auto-calculated from the split ratio using standard values:

   Split Ratio	Insertion Loss (dB)
   1:2	3.5
   1:4	7.0
   1:8	10.5
   1:16	13.5
   1:32	17.0
   1:64	21.0

4. Place splice points (splice_closure) where cables are joined.
5. Place access points (access_point) where drop cables branch off.

4.8 Step 7 — Connect ONUs (Customers)

1. Select the ONU Equipment layer and toggle editing.
2. Place ONUs at each customer premises location.
3. Fill in the attribute form: serial number, model, customer name, service status (active, planned, provisioned, suspended).
4. Associate each ONU with its serving PON port and splitter by setting the appropriate foreign key fields.

4.9 Step 8 — Validate & Verify

Once your network design is complete, validate it:

1. Run Validate Network from the Processing Toolbox (see Chapter 10) to check for:
   • Missing OLTs or PON ports
   • Orphaned ONUs (not connected to any splitter)
   • Cable topology issues
   • Power budget compliance
   • Duplicate serial numbers
2. Run Power Budget Batch to calculate power budgets for all active ONUs and check ITU-T G.984.2 compliance.
3. Open the Network Dashboard (Tools > Analysis > Network Dashboard) to review overall network statistics and health.
4. Fix any issues identified and re-validate until all checks pass.

5. Inside Plant Management

FiberWeave includes a full inside plant management system for tracking physical infrastructure within buildings. Access it via Design > Inside Plant on the toolbar.

5.1 Building Management

The Inside Plant Manager uses a hierarchical structure:

The Buildings tab allows you to:

• Add new buildings with name, address, type (central office, cabinet, customer premises, data center, POP), and geographic coordinates
• Edit existing building details
• Delete buildings (cascades to rooms, racks, and equipment)
• View building summary in the Overview tab

5.2 Room & Rack Management

Within each building, manage rooms and their rack contents:

• Rooms: Add rooms with name, floor, room number, and purpose (server room, telecom room, MDF, IDF, general)
• Racks: Add racks within rooms with name, height (rack units), width, depth, weight capacity, and current power draw

5.3 Equipment & Port Tracking

The equipment and port tracking integrates with the OLT and ONU layers in the database, allowing you to correlate geospatial network elements with their physical rack positions.

6. Engineering Calculators

Access all calculators from Tools > Calculators on the toolbar.

6.1 Power Budget Calculator

The Power Budget Calculator verifies that the optical signal can travel from the OLT to the ONU with sufficient margin, per ITU-T G.984.2.

Input Parameters

Calculations Performed

• Total fiber loss: length × attenuation
• Splitter loss: looked up from standard values for the selected ratio
• Connector loss: count × 0.5 dB
• Splice loss: count × 0.1 dB
• Total path loss: sum of all losses
• Downstream margin: OLT TX Power − ONU Sensitivity − Total Loss
• Upstream margin: ONU TX Power − OLT Sensitivity − Total Loss

6.2 Cable Tension Calculator

Calculates the maximum pulling tension during cable installation to prevent damage.

Input Parameters

Calculations

• Straight tension: cable weight × pull length × friction × gravity
• Bend tension: uses the Capstan equation (exponential friction at each bend)
• Elevation tension: cable weight × elevation change × gravity
• Total tension: sum of all components
• Safety factor: 4.0 × total (must be below max rated tension)

6.3 Aerial Slack & Sag Calculator

Calculates cable sag and required slack for aerial (pole-to-pole) installations.

Input Parameters

Calculations

• Catenary sag: calculated from span, weight, and tension using the catenary equation
• Cable length: actual cable length accounting for sag
• Slack percentage: excess cable needed beyond straight-line distance
• Thermal expansion: length change across the temperature range
• Recommended slack: total slack including thermal compensation

7. Analysis & Visualization Tools

Access these tools from Tools > Analysis on the toolbar.

7.1 Network Dashboard

The Network Dashboard provides a real-time overview of your fiber network by querying the database:

• 4 summary cards: Total ONUs, Active ONUs, Total Cable (km), Total Splitters
• Detailed HTML report: Equipment counts by type, cable lengths by category, splitter distribution by ratio, ONU status breakdown
• Health status: Overall network health indicator based on active equipment ratios

Click Refresh to update statistics after making changes to your network.

7.2 OTDR Analyzer

The OTDR (Optical Time Domain Reflectometer) Analyzer lets you manage test results:

• Load .sor files: Import standard OTDR trace files for analysis
• Event table: View all events (connectors, splices, reflections) with distance, loss, reflectance, and type
• Trace summary: Total fiber length, total loss, average loss per km, number of events
• Manual test entry: Record test results directly with cable, test type (OTDR / Power Meter / VFL), wavelength, loss, return loss, technician name, and pass/fail result
• Load from database: Retrieve previously stored test results

7.3 Splice Diagram Viewer

View splice closure fiber assignments from the database:

1. Select a splice closure from the dropdown (populated from the ODN Nodes layer).
2. View the text-based splice diagram showing input and output fiber connections.
3. Review loss statistics per splice.

7.4 Butterfly Closure Viewer

View a graphical representation of butterfly-type splice closures:

• Input cables shown on the left, output cables on the right
• Fiber-to-fiber assignment table
• Export the diagram to PNG or SVG format for documentation

7.5 Fiber Color Reference

Quick reference for fiber identification with three standards:

Each tab displays a visual color swatch alongside the fiber/tube number and color name.

8. Documentation & Reporting

Access via Documentation > Reports on the toolbar.

8.1 BOM Generator

The Bill of Materials Generator produces itemized cost reports for your fiber network.

Configuration Options

Output Tabs

• Summary: Total equipment cost, labor cost, subtotal, markup, discount, contingency, and grand total
• Detailed BOM: Full table with 10 columns (Item, Category, Type, Qty, Unit, Unit Price, Total, Labor, Status, Notes) — searchable
• By Category: Materials grouped by category (OLTs, PON Cards, ONUs, Fiber Cable, Splitters, Poles, Labor)
• Cost Analysis: Breakdown of cost drivers and budget allocation

Export Formats

• Excel (.xlsx): Full workbook with formatting (requires openpyxl)
• CSV: Comma-separated values for import into other systems
• PDF: Print-ready document via the system print dialog
• Print: Send directly to a printer

8.2 Documentation Generator

Generate professional network documents by querying the live database. Four document types are available:

Each document is generated as an HTML report that can be saved or printed to PDF.

8.3 Label Generator

Generate standardized labels for field identification. Access via Reports > Label Generator.

Label Types (4 Tabs)

Features:

• Batch generation: Create labels for all items of a type at once
• Export to CSV: For import into label printing software
• Print: Direct printing of label sheets

9. Data Import

Access via Reports > Import Data on the toolbar.

9.1 Supported Formats

9.2 Import Wizard

The Data Import Manager uses a 4-step wizard:

1. Select Source: Choose the file format and browse to the data file. For database sources, enter connection parameters.
2. Map Fields: Map source columns to FiberWeave database fields. The wizard auto-maps fields with matching names. You can manually adjust any mapping.
3. Validate: Preview the data and check for issues (missing required fields, invalid geometry, CRS mismatches). The wizard reports errors before importing.
4. Import: Execute the import with configurable batch size and rollback-on-error option.

9.3 Field Mapping & Validation

Target Tables

Import Options

• Skip existing: Skip records that already exist in the database (matched by primary key)
• Update existing: Update matching records with new values
• Geometry validation: Check and fix invalid geometries before import
• CRS transform: Automatically reproject data from source CRS to the database CRS
• Batch size: Number of records per database transaction
• Rollback on error: Abort entire import if any record fails

10. Processing Toolbox Algorithms

FiberWeave registers three algorithms in the QGIS Processing Toolbox under the FiberWeave provider. Access them via Automation > Processing Toolbox on the toolbar, or from the QGIS menu Processing > Toolbox.

10.1 Validate Network

Performs a comprehensive 9-point validation of your network design:

The output is a detailed text report listing each check with PASS/FAIL status and specific issues found.

10.2 Power Budget Batch

Calculates power budgets for all active ONUs in the network in a single operation:

• Traces the optical path from each ONU back to its OLT
• Sums fiber loss, splitter loss, connector loss, and splice loss
• Calculates downstream and upstream margins
• Stores results in the itu_power_budget table
• Reports compliance status (PASS/FAIL) per ITU-T G.984.2

10.3 Export Network Report

Generates a comprehensive text report covering:

• Network Summary: Total OLTs, PON ports, ONUs, cables, splitters
• OLT Details: Per-OLT equipment specifications and port utilization
• Power Budget Analysis: Summary statistics (min/max/average margin), compliance rate
• Non-Compliant Paths: Detailed listing of any ONU paths that fail the 3 dB margin requirement

The report is saved as a text file at a location you specify.

11. Layer Styles & Form Configuration

11.1 Automatic Styling

When you click Apply Styles, FiberWeave applies categorized symbology to all layers:

11.2 Attribute Forms

FiberWeave configures QGIS attribute forms for each layer with:

• ValueMap dropdowns: Standardized values for fields like cable type, node type, status, split ratio, and infrastructure type. This prevents typos and ensures data consistency.
• Field aliases: Human-readable names for database columns (e.g., cable_type appears as "Cable Type").
• Default values: Common defaults like planned for status fields and today's date for date fields.
• Auto-calculated fields:
  • Cable length: Calculated from the drawn geometry ($length)
  • Insertion loss: Calculated from the selected split ratio
• Date pickers: Calendar widgets for date fields.
• Range spinboxes: Numeric spinners for values like fiber count and attenuation.

11.3 Snapping & Topology

Apply Styles also configures snapping automatically:

• Snapping tolerance: 10 pixels
• Snap to: Vertex and segment
• Topological editing: Enabled (moving a shared vertex moves it in all connected layers)
• Applies to all layers: All 7 core FiberWeave layers are configured simultaneously

12. Time-Saving Features Summary

FiberWeave is designed to automate repetitive tasks and reduce manual data entry. Here is a summary of the key time-saving features:

13. Troubleshooting & FAQ

Connection Issues

Layer Issues

Calculator Issues

Frequently Asked Questions

Q: Can multiple users work on the same network simultaneously?

A: Yes. FiberWeave uses PostgreSQL, which supports concurrent connections. Multiple QGIS users can connect to the same database. Use PostgreSQL's built-in locking to prevent edit conflicts.

Q: What coordinate reference system should I use?

A: PostGIS stores geometry in the CRS defined when you create the tables. For accurate cable length calculations, use a projected CRS appropriate for your region (e.g., UTM zone). The data import wizard can reproject data from any source CRS.

Q: Can I import data from an existing GIS or CAD system?

A: Yes. The Data Import Manager supports CSV, Excel, Shapefile, GeoJSON, KML/KMZ, AutoCAD DXF, QGIS layers, PostGIS, and Oracle Spatial. The wizard handles field mapping and CRS transformation.

Q: What does "AI Optimize" do?

A: AI-powered route optimization is planned for Phase 2 and is not yet available in the current release. This feature will provide automated route optimization using network analysis algorithms.

Q: How do I back up my network data?

A: Use standard PostgreSQL backup tools: pg_dump fiberweave_network > backup.sql for a full database backup. Schedule regular backups for production networks.

Q: Can I use FiberWeave without PostGIS?

A: No. FiberWeave requires PostgreSQL with the PostGIS extension for spatial data storage and queries. PostGIS Topology is also required. pgRouting is optional.

Appendix: ITU-T Standards Reference

ITU-T G.984.2 — GPON Physical Media Dependent Layer

FiberWeave's power budget calculations comply with ITU-T G.984.2, which defines the optical interface specifications for Gigabit-capable Passive Optical Networks (GPON).

Key Parameters Used in FiberWeave

Splitter Loss Reference

FTTx Code Reference (Layer Attribute Values)

Cable Types

Node Types

Status Codes