The ONU GPS map

The ONU GPS map turns the ONU inventory of one OLT into a geographic picture: the OLT at its real location, the splitter cabinets between it and the street, and every subscriber ONU where it actually sits. It lives in the ONUs tab of an OLT’s detail page, behind the Table | Map toggle at the top left.

Where network maps are a logical topology of your core and aggregation, this is the access layer on real geography. It answers a different set of questions: which streets does PON port g0/3 actually feed, is this cluster of Rx-power complaints all hanging off one splitter, and where does the technician need to drive.

It is worth being clear about what the map is: a layer you author on top of what NetSense already discovers. The OLT → PON port → ONU relationship comes from the device itself and you cannot change it here. Coordinates, splitters and the ONU↔splitter associations are your annotations — NetSense never invents them, and it validates them against the discovered topology so the drawing can’t lie about which port an ONU is on.

Before you start

Two things gate the map:

• The fiber map must be enabled for your tenant. If it isn’t, the Map toggle is inactive and the view reads “The fiber map is not enabled for this tenant.”
• A Google Maps API key must be configured. Tenants can supply their own key (recommended — the map traffic then bills and rate-limits against your own Google project); otherwise the platform default applies. With the map enabled but no key available you get “No Google Maps API key is configured for this tenant.” If you supply your own key, restrict it by HTTP referrer to your NetSense URL: the Google Maps JS API key is exposed to the browser by design, and referrer restriction is what keeps it yours.

Permissions decide what you can do once you’re in:

Action	Permission
View the map	olt:port:view
Give an ONU coordinates, or unmap it	onu:edit
Set or move the OLT’s location	olt:edit
Create, edit, delete splitters; assign ONUs to them	olt:splitter:edit

Read-only users get the full map, popups, search and CSV export — they just don’t get Edit topology.

Edit mode

Nothing on the map is editable until you click Edit topology (top right). That turns on marker dragging, the right-click menu’s editing items, and the on-map Add element button; Exit edit mode turns it all off again. Two habits worth forming:

• Nothing writes on a bare map click. Every placement — ONU, splitter, OLT — hands off to a dialog you confirm. Escape cancels an armed placement.
• Dragging a marker saves it, about half a second after you let go. Grab the same marker again before then and the save is cancelled, so a mis-drop is fixable by simply dragging it where you meant.

Step 1: pin the OLT

Start here. The OLT is the root of the drawing and the anchor everything else is read against.

In edit mode, an OLT with no coordinates yet shows a Set OLT location button in the toolbar: click it, then click the OLT’s real position on the map, and confirm the coordinates in the dialog. The same action is on the map’s right-click menu as Place OLT here.

Both of those disappear once the OLT has a location — that is deliberate, not a missing button. To correct an already-placed OLT, either drag its marker in edit mode, or right-click the OLT marker and choose Change GPS coordinates to type an exact pair.

Step 2: give ONUs coordinates

An ONU appears on the map as soon as it has a latitude and longitude. There are three ways in, and they write to the same field.

From the ONU table (the everyday path, and it works without opening the map at all): the GPS column carries a pin icon per row — grey when the ONU has no coordinates, dark when it does. Click it and a small OpenStreetMap panel opens with Latitude and Longitude fields.

The fields are read-only until you click the pencil button. Click the pencil first, then edit.

In edit mode you can then type the values, paste lat, lng into either field to fill both, click the mini-map, or drag its marker. ✓ saves, ✗ discards.

From the map, right-click where the ONU belongs and choose Map ONU here, then pick the ONU from the list. Or work the other way round: the Unmapped ONUs (n) button on the map lists everything on this OLT still without coordinates, so you can walk the backlog down to zero.

To correct an existing pin, drag its marker in edit mode, or right-click it → Change GPS coordinates. Right-click → Unmap clears the coordinates and returns the ONU to the Unmapped list.

Coordinate formats that work

Coordinates are decimal degrees with a dot as the decimal separator — 28.71694, 77.17449. That is the only accepted form; a comma decimal separator (28,71694) is rejected, and so are degrees/minutes/seconds.

• Latitude must be between −90 and 90, longitude between −180 and 180. A value outside that range is what triggers “Enter a latitude between -90 and 90 and a longitude between -180 and 180.”
• Pasting a pair works, and is the fastest way in: copy 28.71694, 77.17449 out of Google Maps and paste it into either field — both get filled. In the map’s dialogs a space also separates the pair; in the table’s GPS panel use a comma.
• Fill both fields or neither. Saving with only one filled returns “Field is required” on the empty one.
• Note that latitude comes first in every NetSense field and in anything you paste, which is the opposite order from some GIS exports. Swapped values are usually valid numbers, so nothing errors — the ONU just lands in the wrong hemisphere.

Any node’s coordinates can be copied back out: right-click it → Copy GPS coordinates.

Step 3: add splitters

Splitters are what make the map a fiber map rather than a scatter of pins. Each one attaches to exactly one parent: an OLT PON port, or another splitter.

In edit mode, right-click the splitter’s location and choose Add splitter here (or use Add element → Splitter, then click the position).

The New splitter dialog asks for:

• Label — required, unique within this OLT, up to 50 characters. Something a technician recognises: SPL-A1, a cabinet or pole ID.
• Parent (feeds this splitter) — a PON port or an existing splitter. PON ports that already carry a primary splitter are listed (in use) and disabled; existing splitters are listed as ↳ label | port so you can see which PON port each one hangs off.
• Latitude / Longitude — prefilled from the point you clicked, editable before you commit. If you clicked roughly and know the exact pair, replace it here.
• Split ratio — 1:2, 1:4, 1:8 (the default), 1:16, 1:32 or 1:64.

Click Create and the feeder line is drawn from the parent to the new splitter.

Tiers are derived, not chosen

You never pick a tier. It follows from what you attached the splitter to:

Attached to	Tier
An OLT PON port	Primary
A primary splitter	Secondary
A secondary splitter	Tertiary
A tertiary splitter	Quaternary

Four levels is the hard maximum, and it’s enforced on the whole subtree — moving a splitter that already has children under a deeper parent is rejected if any descendant would land past quaternary. One primary per PON port, so a 16-port OLT supports at most 16 primaries.

To restructure, right-click a splitter → Edit splitter and change its Parent. One constraint applies: if the splitter’s subtree already has ONUs assigned, it can only move to a parent on the same PON port — the dialog says so inline, and blocks Save if you pick a parent on a different port. Unassign the ONUs first if you really need to move it across ports.

Delete splitter removes that splitter and every sub-splitter beneath it, and unassigns all of their ONUs. The confirmation says exactly that; the ONUs themselves and their coordinates are untouched.

Step 4: associate ONUs with splitters

Coordinates put an ONU on the map. Associating it with a splitter is what draws the drop cable and makes the tree walkable.

The important rule, and the one that generates the most “why won’t it let me” moments:

An ONU can only be assigned to a splitter whose effective PON port — the port at the root of its chain — matches the port the ONU is actually registered on. NetSense reads that from the device, so this is not negotiable.

Two ways to do it, and the second is much faster in bulk:

One ONU at a time — right-click the ONU → Assign to splitter. The dialog lists only splitters on that ONU’s port and says so: “Only splitters on g0/5 can take this ONU.” Search by label if the list is long.

Many ONUs at once — right-click a splitter → Edit splitter and work the Associated ONUs section at the bottom. It shows used/total against the split ratio, a search box (ID, SN, MAC or description), and every ONU on that PON port with a one-click Assign button. An ONU already on another splitter shows on <label> with a Move here button instead, so re-patching is a single click. This is a rapid one-click-per-ONU list rather than a multi-select — for thousands of ONUs, see Loading a whole ODN from a file below.

Each row carries the ONU’s PON port, ID and measured fiber distance (g0/1 · ID 43 · 2780m). The distance is the practical tiebreaker when you know roughly where a splitter sits but not which subscribers hang off it: ONUs at a similar distance are usually on the same leg, and an ONU hundreds of metres out of family with the rest is worth a second look before you assign it. The footer confirms the port filter is active — “Showing ONUs on PON port g0/1 only.”

Capacity is real: a 1:8 splitter has eight output legs, and child splitters consume legs too. Once they’re gone you get “No free output legs — unassign one first.” An ONU belongs to at most one splitter, so assigning it somewhere else moves it rather than duplicating it.

Unassign is on the ONU’s right-click menu (Unassign from <label>) and on each assigned row in the splitter dialog. It removes the drop line and leaves the ONU on the map, unattached.

Associations can drop by themselves

If a device re-discovery moves an ONU to a different PON port — a re-patch in the field, a port renumbering after a firmware upgrade — its old association is now physically impossible, and NetSense removes it automatically during housekeeping. The ONU stays on the map with its coordinates; only the drop line goes. If a splitter unexpectedly looks emptier than you left it, that is the first thing to check: the ONUs moved ports.

Reading the map

The map reveals itself progressively with zoom. Zoomed out you see the OLT and the primary splitters, each carrying a donut with the ONU count of everything beneath it, colour-split by status. Zoom in and secondary, tertiary and quaternary tiers appear in turn, and finally individual ONU markers. This is what keeps a 600-ONU OLT readable instead of a solid blob of pins — and it’s why search results and specific markers may only resolve once you’re zoomed in far enough for that tier to be revealed.

Clicking any node opens a popup: a splitter shows its tier, split ratio, OLT, PON port, coordinates, used/total capacity and a status breakdown of its whole subtree; an ONU shows its identity, status, down reason and optical figures.

Lines carry meaning too — feeder lines from the OLT trunk, feeder lines from a parent splitter, and drop lines to ONUs are drawn distinctly and coloured by health.

The Display Options panel (the gear tab on the right edge, or Cmd/Ctrl+B) is where a large map becomes a diagnostic tool rather than a picture.

Sections cover:

• Show / Status / Rx power — filter markers by up, down, warning, unknown; by down reason (power off, optical loss, SNMP check, unknown); or by Rx-power band. Show only down ONUs with optical loss on a map is usually a fiber run, not four unrelated faults.
• Links and Splitter markers — turn individual tiers and link types off to de-clutter.
• Annotations — marker labels: ONU ID, serial/MAC, description. Also always show subtree counts, which keeps the count donuts on at every zoom.
• Mapped ONUs (n) and Splitters (n) — browsable lists that double as a progress meter for how much of the OLT you’ve mapped. Reset restores the defaults.

Preferences persist across OLTs and sessions.

Other controls: Fit all nodes and Center on OLT (top right, with Fullscreen next to them), the Map | Satellite base-layer toggle, and a search box that covers every ONU on the OLT by ID, SN, MAC or description regardless of what the filters are currently drawing.

Export CSV dumps the current view — OLT, ONU ID, serial, MAC, status, down reason, Rx power and band, OLT Rx power, latitude, longitude, a mapped yes/no flag, and description. Unmapped ONUs are included and flagged, which makes the export a practical worklist for field survey.

Loading a whole ODN from a file

Clicking in 4,000 subscriber positions is not a plan. There is no self-service bulk import in the UI yet; for an initial load, send the data to your NetSense contact and it will be imported for you.

Per ONU, three things are needed:

• OLT hostname or IP — which OLT the ONU belongs to
• ONU serial number or MAC — how the row is matched to a device
• Latitude and longitude in decimal degrees

Splitter mapping is optional in the same file — a splitter label per ONU row, plus the splitter list with label, parent (PON port or parent label), coordinates and split ratio. Send it if you have it; if not, load the ONU coordinates now and draw the splitter tree in the UI afterwards. If you hold subscriber addresses rather than coordinates, say so — addresses can be geocoded as part of the import.

Two things to expect in the report back: rows whose serial or MAC matches no ONU on the named OLT are skipped, and a serial that appears more than once in the sheet takes the first coordinates it matched and gets flagged, so double-check those positions.

Troubleshooting

The Map toggle does nothing / “Map unavailable”. Either the fiber map isn’t enabled for the tenant or no Google Maps API key is configured. The empty state distinguishes the two.

I can’t type or paste into the GPS fields in the ONU table. Click the pencil first — the fields are read-only until you do.

My coordinates are rejected. Use decimal degrees with a dot (28.71694), fill both fields, and check latitude is within ±90 and longitude within ±180. A comma decimal separator will not parse.

A pasted pair only filled one field. The paste helper needs exactly two numbers. Strip labels (Lat: 28.7 Long: 77.1 won’t split) and use a comma in the table’s GPS panel.

“No free output legs.” The splitter’s ratio is exhausted — remember child splitters occupy legs too. Unassign something, or raise the split ratio in Edit splitter.

A splitter won’t accept an ONU. The ONU is on a different PON port than the splitter’s root. Check the ONU’s port in the table, then either assign it to a splitter on that port or add one.

A splitter can’t be re-parented. Its subtree has ONUs assigned, and the parent you picked sits on a different PON port. Unassign those ONUs first.

Markers or search hits don’t appear. Zoom in — deeper tiers and individual ONUs are only drawn once the zoom reveals them. Also check Display Options for a filter or tier you’ve switched off, and use Reset if in doubt.

A splitter lost its ONUs on its own. Re-discovery moved those ONUs to a different PON port, and housekeeping removed the now-invalid associations. Re-assign them to a splitter on their new port.

What’s next

The GPS map covers the PON access layer today: OLTs, splitters and ONUs. Coordinates for switches, BNGs and other active elements, real fiber routes rather than straight lines, and passive plant (cable types, enclosures, poles, ducts) belong to the element-management work that follows — on Google Maps or OpenStreetMap. Until then, pair this map with a network map of the same region and you have both the geography of the access layer and the logical topology of everything upstream.