Welcome to EPower Maps

EPower Maps is a field data-collection app for electrical infrastructure. Use it on Android and iOS to capture pole GPS, attach accessories, manage cable and transformer catalogs, sync with the server, and export a KMZ map of everything you collected to Google Earth — even when offline.

Live demo

What this guide covers

Before you start

1. Install the app on Android (API 21+) or iOS.
2. Grant Location permission (required) plus Camera (for QR tenant scan), Microphone (voice input for AI ERA), and Biometric (optional).
3. Register your organisation by scanning the tenant QR code (Settings → Manage Tenants → Scan QR) — see step 14.
4. Run an initial sync (Communication tab → Import Data) to pull your catalog from the server — see step 4.
5. You're ready: the app opens to Dashboard (step 1). Switch to the Collect tab to start capturing poles (step 2).

1. Dashboard & Analysis

The Dashboard screen

1. 1Overview card — total Places, collected vs. pending counts, and a thin progress bar. Tap to drill into the Analysis charts.
2. 2Manage Catalog — coloured icon tiles for each catalog (Accessories, Packages, Poles, Styles, Transformers, Line Styles, Transformer Styles, Cable, Distribution Method). Counts pulled from /Dashboard.
3. 3Pull-to-refresh anywhere on the page to fetch fresh counts.
4. 4Dashboard is the first tab and the post-splash landing screen.

Collection Analysis — drill-down

Tap the Overview card on Dashboard to open Collection Analysis: a progress bar, donut chart of the collected-vs-not-collected split, three count tiles, and a tab list of every pole grouped by area.

1. 1Collection Progress bar — green = collected portion, red = not-collected. The percentage chip on the right mirrors the donut centre.
2. 2Donut chart — interactive. Tap a slice to switch the focus between the Collected and Not Collected lists below.
3. 3Three count tiles — Total Poles / Collected (green tick) / Not Collected (red ring). Numbers come straight from /Dashboard.
4. 4Two tabs — "Collected (n)" and "Not Collected (n)". The active tab is underlined in orange. Left screenshot above shows the Collected tab (green pills with collection dates); right shows Not Collected (gray outlined pills, no date).
5. 5Pole list — grouped by area (T01, T14 …). On Collected, each row shows pole code + "Collected on …" date + green "Collected" pill. On Not Collected, only the pole code + "Not Collected" label. Tap a row to open that pole's Place detail.

2. Collect — Capturing a pole

The core workflow used by field technicians to capture a pole's GPS, style, ownership, and accessories.

The Collect screen

1. 1Location card — live latitude / longitude / accuracy. Green LIVE badge while the GPS stream is active; tap the refresh icon to force a re-read.
2. 2Pole Information card — search-pick a pole (here: B1), then pick its style (e.g. បង្គោលកំពស់១២ម៉ែត្រ). Tick "Own" if the pole belongs to E-Power.
3. 3Accessories card — each row shows index chip + name + qty input + red trash icon to remove. Header pill shows the live count.
4. 4Sticky bottom bar — outlined accessory-count button above a Prev / Save (orange pill) / Next row. Save persists locally and posts when online; queues to pending-sync when offline.
5. 5Bottom nav — Dashboard / Collect (active) / Maps / Communication / Settings. Tap Maps to launch Google Earth from the latest data.

3. Maps / KMZ Export

The KMZ generator has been rewritten end-to-end: it composes Google Earth output entirely from current PoleStyle / CableStyle catalog data — no more hard-coded blue/red icons. Pole markers are tinted from a single white outline icon, cables come from real TblCablePlace records, and a LOD-swap keeps icons readable from continent zoom down to street level.

What the KMZ looks like in Google Earth

1. 1The generated KMZ opens in the Google Earth app via openGoogleEarth(). Header keeps a tiny "E-Power Maps" back-link.
2. 2Pole markers tinted from each PoleStyle.line_color — here the orange/yellow colour comes straight from the chosen Style. Pole code labels (P17-6, P08-6 …) render once per pole thanks to the LOD-swap Folder.
3. 3Red lines are real cables — startPoint → ordered Cable details → endPoint. Their colour and width come from CableStyle, not nearest-neighbor inference.
4. 4Transformer placemarks (T06-1, T09-1 …) render at the host pole's coordinates with a different icon, so they're easy to spot in the field.
5. 5Google Earth's native controls (compass, street view, 2D/3D, scale bar) still work — tap a pole to see its full label, or use the search bar to jump to a specific code.

Layer-by-layer KMZ structure

maps.kmz (zip)
├── doc.kml
│   ├── <Style id="poleStyle_<id>">        ← per PoleStyle (tinted ic_pole_outline)
│   ├── <Style id="poleStyleNear_<id>">    ← same icon at ~35 % scale for near zoom
│   ├── <Style id="cableStyle_<id>">       ← per CableStyle (LineColor + LineWidth)
│   ├── <Style id="polePairFolder">        ← ListStyle: checkHideChildren (1 row / pole)
│   ├── <Folder name="Poles">
│   │   └── <Folder> per pole (#polePairFolder)
│   │       ├── <Placemark> far variant — maxLodPixels=300
│   │       └── <Placemark> near variant — minLodPixels=300
│   ├── <Folder name="Cables">
│   │   └── <Placemark> per cable — LineString(start → details[order] → end)
│   └── <Folder name="Transformers">
│       └── <Placemark> per transformer at its place_id's lat/lng
└── icons/
    ├── ic_pole_outline.png    ← single white-fill icon, tinted at render time
    ├── ic_pole_blue.png       ← fallback when no PoleStyle assigned
    ├── ic_pole_red.png        ← fallback for "not collected"
    └── ic_transformer.png

4. Communicate

The biggest architectural change: USB/TCP socket has been replaced with a REST API, and offline + auto-sync are first-class.

The Communication screen

1. 1Tenant chip — green when an organisation is registered and reachable (e.g. អត្តសញ្ញាប័ណ្ណ ស៊ីនហេង · Connected). If empty, prompts you to register one.
2. 2Sync status card — shows "All synced" (no pending) or "n pending changes" with a Sync button. The Auto Sync toggle controls whether the app uploads automatically when connectivity returns.
3. 3Data Sync — two action tiles: Import Data (pull latest catalog from server, also refreshes Distribution Methods) and Full Sync (export then import in one run).
4. 4Sync History — grouped by date (Today / Yesterday / earlier). Each row shows the sync type ("Auto Sync" / "Full Sync" / "Import"), the time, and a green Success / red Failed pill.
5. 5Bottom nav — Communicate tab active (orange pill background). Tap any tab to switch instantly.

5. Accessories

The Accessories screen

1. 1Search box at the top — type to filter accessories by name (e.g. Fuse, MCCB, Auto Recloser).
2. 2Each row shows the accessory icon, name, optional sub-label (image path or code), and a status pill: gray "Not Use" or orange "In Use". The pill comes from the server — an accessory is "In Use" when at least one active Place or Package references it.
3. 3Tap any row to open the detail page (edit name / note, soft-delete). Long-press to enter selection mode for batch actions.
4. 4Orange "+ New Accessory" floating button at bottom-right opens a sheet to create one. Saves go straight to /Accessory when online, or queue offline.

Add / edit an Accessory

Tapping + New Accessory opens the New Accessory form (left). Tapping an existing row opens Edit Accessory (right) pre-filled with current values. Required fields are marked with a red *: Accessory Name, Altitude (m), and Icon Scale / Size. Tap the orange Save button at top-right to commit; it posts to /Accessory when online or queues for later when offline. The layout is identical in Khmer — only the labels translate.

6. Packages

The Packages screen

Each row is a saved bundle (e.g. បង្គោលតង់ស្យូងមធ្យម). Tap a row to view + edit its accessory lines and quantities; tap the orange "+ New Package" floating button to create one. Search by name at the top.

Add / edit a Package

Tapping + New Package opens a quick bottom sheet (left) where you enter just the package name and Save. The package is created empty, then a full Edit Package page (right) lets you add accessories with + Add, edit quantities inline, and remove lines via the red trash icon. The trash icon next to Save (top-right of Edit) hard-deletes the entire package.

7. Poles

The Poles roster screen

The pole master list — every row is a unique pole code (e.g. B1, T05.NL2/40) with its area chip below. The "In Use" pill means at least one active Place / transformer / box / customer-meter references that pole; "Not Use" poles can be edited or removed safely. Search by pole code or area at the top; "+ New Pole" creates one.

8. Styles

The Styles screen

Defines how each pole renders on the KMZ map — name + line color (the pole marker tint) + width + altitude. "In Use" rows are already attached to one or more collected Places; "+ New Style" creates a new style for future collections.

Add / edit a Style + color picker

New Style (left) collects the fields that drive how the pole renders in KMZ: Style Name, Altitude (m), Pole Color / Size (the marker tint + width), Icon Scale / Size, and Label Color / Scale / Opacity. Required fields are starred. Tapping any color swatch opens the Pick Color bottom sheet (right) with 48 preset swatches — the currently selected one has an orange outline + check. The matching field on the form updates as soon as you pick.

9. Transformers

The Transformers screen

Every transformer with its code (e.g. T17-6, P27-10) and optional sub-label (location / owner). "In Use" = currently attached to at least one active pole; "Not Use" rows can be edited or deleted. Tap any row to open its detail page (brand, capacity, phase, position, dates).

14. Companies ➕

The Manage Companies screen

1. 1Current company card — shows the connected organisation. Tap Disconnect to sign out from this tenant; the app then prompts you to register another.
2. 2Scan to register device — opens the camera and reads the tenant QR code. Each scan creates a new App-Id binding so the device can talk to that organisation's server.
3. 3Registered Companies — list of every organisation this device has joined. The currently active one is outlined in orange and shows the Active pill plus an edit (pencil) icon to rename it.
4. 4Tap any non-active row to switch tenants — the app reopens the matching SQLite file (MobileDB_<tenantId>.db) and reloads every catalog. Swipe a row left to delete.

15. Settings ➕

The Settings screen

Settings is one scrollable page. Below: the top (orange hero · Contact · Tenant · Language) and the bottom (Appearance · Theme · Primary Color · Font · Exit App) shown side-by-side.

1. 1Orange hero — app icon, brand name "E-Power Maps", and the version badge (v2.3.1). Tap the version badge seven times to unlock Developer Mode (see chapter 16).
2. 2Contact card — organisation name + two phone rows. Tap the green phone icon to dial directly.
3. 3Tenant / Company card — opens the Manage Companies screen (chapter 14).
4. 4Language card — ខ្មែរ (Khmer) or English. The orange ✓ marks the active language; switching is instant — no app restart needed.
5. 5Appearance — Interface Theme (Light / Dark / System with orange-bordered selection), Primary Color (tap the dot to open a 12-swatch picker), Font Style segmented control (Aa / Aa / Aa = S / M / L), and Font Family (opens a bottom sheet of Khmer-capable fonts).
6. 6Exit App — red outline button at the bottom; confirms before quitting. Copyright footer below.

Primary Color picker · Font picker

Tapping the Primary Color dot on the Appearance card opens a 12-swatch sheet (left). The active color has a checkmark inside an orange ring; every accent in the app — buttons, pills, links — updates immediately on pick. Tapping the Font row opens a font sheet (right) listing every Khmer-capable family bundled with the app (Siemreap is the default, followed by Kantumruy Pro, Noto Sans Khmer, Noto Serif Khmer, Battambang, Hanuman, Suwannaphum, and System Default). The little "សួស្តី Hello" snippet under each name previews how the font renders mixed Khmer + Latin text. Selection is instant — no app restart.

16. Developer Mode ➕

17. Navigation Map

The bottom navigation in context

The bottom nav is visible on every shell page. The Collect screen below shows it in its natural place — five icons across the bottom, with the active tab highlighted in orange.

1. 15 tabs (in order): Dashboard · Collect · Maps · Communicate · Settings — same order as the chapter numbering you're following.
2. 2Active tab = orange pill background + bold label (brand colour). Here Collect is active.
3. 3Nav bar has rounded top corners + top shadow, floating above the body content.
4. 4The Maps tab launches Google Earth directly (it never sets the current tab); the other four are real shell branches with their own back-stack.
5. 5Root-level pages — Tenant management, Developer Mode, AI ERA Chat, Collection Analysis — push above the shell so the bottom nav is hidden while they're open.

10. Line Styles ➕

Catalog vertical added so admins can define cable appearance (color, width, diameter) and electrical attributes (distribution method, shielded, underground). Backend names this entity CableStyle; the mobile UI keeps the user-facing "Line Style" wording, with only the wire contract using the backend name.

The Line Styles screen

Cable / line styles drive the colour and thickness of the cable LineStrings in the KMZ. Each row shows the style name (e.g. ខ្សែ ABC AL 4 x 50mm2) plus the line characteristic underneath. "In Use" means at least one cable references it; you can't hard-delete an in-use style.

Add / edit a Line Style

New Line Style (left) captures everything the KMZ needs to draw a cable: Distribution Method (picked from the Distribution Method lookup, see §13), Line Characteristics (free-text label e.g. ខ្សែ ABC AL 4 x 50mm2), Altitude (m), Cross-section Area (mm²), Line Color / Width (pix) (the swatch opens the same Pick Color sheet shown in §8), and two cable flags — Underground cable and Coated cable. Edit Line Style (right) shows a populated record (red colour, width 1, 50 mm², Coated cable ticked). All starred fields are required; Save posts to /CableStyle.

11. Transformer Styles ➕

Catalog vertical for transformer marker styling (icon, label color, scale, opacity). Mirrors PoleStyle but for transformers. Backend route /TransformerStyle. Currently IsInused is hard-coded false server-side — TblTransformer has no StyleId FK yet.

The Transformer Styles screen

Catalog of transformer brand styles (test, Others, Chang, TranSwitch, ABB, THIBIDI, Erkarat, Thirathai, Thai Pattanakit, Full Light, Precise, Thai Maxwell, …). Each style stores an icon + label colour / scale for KMZ rendering. IsInused is hard-coded false server-side until a TblTransformer.StyleId FK is added.

Add / edit a Transformer Style

Transformer Style mirrors Pole Style but without a line color/width (transformers are placemarks, not lines). Fields: Transformer Style Name, Altitude (m), Icon Scale / Size, and Label Color / Scale / Opacity. New (left) starts blank; Edit (right) shows a populated record (Erkarat, Altitude 5.0, Icon Scale 1.0, black label, 1.0 scale, 100 % opacity). The trash icon in the Edit header is hard-delete — only allowed when no transformer references this style.

12. Cable + Details ➕

A new read-side catalog so the KMZ generator draws cable lines from real, ordered records instead of inferring connectivity via nearest-neighbor. Each cable has a start place, end place, and ordered intermediate stops (details). The mobile keeps no dedicated CRUD UI — admins create these from the desktop / web; mobile only caches them for offline KMZ generation.

3.18 Distribution Method ➕

A small, read-only enum backing the CableStyle distribution picker. Designed to stay offline-usable after the first online fetch — so an admin can still pick "underground / overhead / …" in the field. Persisted via a three-layer cache.

DistributionMethodRepository.getAll({refresh})
  │
  ├─ Layer 1 ─ in-memory _cache (List<DistributionMethodModel>?)
  │            ↳ cheap repeat lookups within a session
  │
  ├─ Layer 2 ─ SQLite tbl_distribution_method  (dbVersion 20)
  │            ↳ survives app restarts → offline launches resolve names
  │
  └─ Layer 3 ─ GET /Lookup/Distributions  (read-only enum)
               ↳ source of truth; refreshed during EMapSyncRepository.importFromServer()