> For the complete documentation index, see [llms.txt](https://codifi-fdm.gitbook.io/codifi-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codifi-fdm.gitbook.io/codifi-docs/mobile-app/mapping-locations/gps-and-live-data/gps-technical-reference.md).
# GPS Technical Reference
This page covers how Codifi works with GPS hardware — connecting external receivers, understanding signal quality, and knowing what the accuracy indicators mean. Useful for anyone setting up equipment, troubleshooting signal issues, or wanting to understand the data behind the numbers.
## Device GPS vs External GPS
**Your iPad/iPhone has built-in GPS.** It works fine for general navigation but typically provides accuracy of 5–10 meters (15–30 feet). Good enough for some work, but not for precise surveying.
**External GPS receivers** connect via Bluetooth and provide significantly better accuracy:
| Receiver Type | Typical Accuracy | Examples |
| -------------------------- | ----------------------- | -------------------------------- |
| Consumer MFi Bluetooth GPS | 2–5 meters (6–15 feet) | MFi-certified handheld receivers |
| Professional GNSS receiver | Sub-meter to centimeter | Trimble R series, Juniper Geode |
**How to tell which GPS you're using:** Look at the GPS Source label in the Live Data Bar. "iPad GPS" or "iPhone GPS" means built-in. Anything else (e.g. "Trimble R2", a Juniper Geode device name, or a paired Bluetooth receiver's name) means external.
If your Project requires high accuracy (survey-grade data, for instance), your organization will typically provide an external receiver. If you're doing general field inspections or assessments, the built-in GPS may be sufficient.
***
## Connecting an External GPS Device
Codifi supports three types of external GPS connections. Which one you use depends on your receiver.
### Trimble Devices (via Trimble Mobile Manager)
Trimble receivers connect through the **Trimble Mobile Manager (TMM)** app, which acts as a bridge between the receiver and Codifi.
**First-time setup:**
1. Install the **Trimble Mobile Manager** app from the App Store (if not already installed)
2. Open TMM and pair your Trimble receiver following Trimble's instructions
3. In Codifi, open the **External Devices** panel (tap the GPS source label in the Live Data Bar)
4. Tap the **+ button**
5. Select **"Trimble Device"**
6. Codifi opens the TMM app — confirm the connection there
7. When connected, your Trimble device appears in Codifi's device list
**After first-time setup**, Codifi detects the Trimble connection automatically when TMM is running and the receiver is on.
{% hint style="info" %}
The Trimble Mobile Manager app must be installed and running for the connection to work. If Codifi can't find your Trimble device, make sure TMM is open and showing a connection to the receiver.
{% endhint %}
### MFi Devices (Made-For-iPhone)
MFi GPS receivers are certified by Apple and connect through the standard iOS Bluetooth pairing system. Many popular field GPS receivers use this connection type.
**MFi devices** are GPS receivers certified by Apple to communicate over Bluetooth via the Made-for-iPhone protocol. Specific receiver compatibility varies — check with your hardware vendor or your Project's solution engineer if you're unsure whether a specific device is supported.
**Setup:**
1. In Codifi, open the **External Devices** panel
2. Tap the **+ button**
3. Select **"MFi Device"**
4. Your device's **Bluetooth Settings** opens automatically
5. Find your GPS receiver in the list and tap to pair it
6. Return to Codifi — the device appears in your device list automatically
**After pairing**, MFi devices connect to Codifi automatically whenever they're powered on and within range. You typically only need to do the pairing step once.
### Bluetooth LE (BLE) Devices
Some newer GPS receivers use Bluetooth Low Energy. These connect directly through Codifi rather than through iOS Settings.
**Setup:**
1. Make sure your GPS receiver is powered on and in pairing mode
2. In Codifi, open the **External Devices** panel
3. Tap the **+ button**
4. Select **"BLE Device"**
5. A scanning screen appears — tap **"Scan"**
6. Nearby devices appear in a list, sorted by signal strength:
* **GPS Devices** are shown at the top (the app recognizes common GPS receiver brands)
* **Other Devices** are hidden by default — tap "Show Other Devices" if yours doesn't appear in the GPS list
7. Each device shows a **signal strength indicator** — look for "Good" or "Excellent" signal
8. Tap **"Connect"** next to your device
9. If iOS asks you to confirm pairing, tap **Pair**
10. The device appears in your Codifi device list
***
## Managing Your GPS Devices
Tap the GPS source label to open the **External Devices** panel:
* View all connected devices
* See which is set as your **Favorite GPS** (marked with star and highlighted)
* Add new devices via the **+ button**
* Manage existing devices (disconnect, reconnect, set as favorite)
{% hint style="info" %}
**Tip:** Set your preferred external GPS as the **Favorite**. Codifi will automatically use it when available. If the external device disconnects or is turned off, Codifi automatically falls back to the built-in iPad/iPhone GPS so you can keep working.
{% endhint %}
***
## Understanding GPS Quality
When using an external receiver, you may see a **GPS quality label** that tells you what type of correction your receiver is providing. Higher-quality fixes mean more accurate locations.
| Quality Label | What It Means | Typical Accuracy |
| -------------- | ----------------------------------------------------------- | ------------------------------ |
| **RTK Fixed** | Best possible fix — real-time corrections fully resolved | 1–3 centimeters |
| **RTK Float** | Corrections in progress but not fully locked in yet | 5–50 centimeters |
| **DGPS** | Differential corrections from ground stations or satellites | 1–3 meters |
| **Autonomous** | Standard GPS, no corrections | 3–10 meters |
| **No Fix** | Receiver can't determine a position | N/A — wait or move to open sky |
{% hint style="info" %}
**What is RTK?** Real-Time Kinematic (RTK) is a correction technology used by professional GNSS receivers. It compares satellite signals with data from a known reference point (a base station or network) to dramatically improve accuracy. If your receiver supports RTK and your organization provides corrections, you may see centimeter-level accuracy in the field.
{% endhint %}
Not all receivers display all quality types. Consumer-grade receivers typically show "Autonomous" or "DGPS." Professional receivers (Trimble, Juniper, and other GNSS receivers) can show the full range including RTK labels. The built-in iPad/iPhone GPS displays as **"iOS"** and does not show a standard quality label.
***
## Accuracy Indication
Codifi uses a color-coded system throughout the app to indicate GPS accuracy:
### In the Live Data Bar
| Color | What It Means |
| --------------- | -------------------------------------------------- |
| **Dark/Normal** | Good signal — data is fresh |
| **Orange** | Signal getting stale (3–10 seconds) — wait |
| **Red** | Signal is very stale (> 10 seconds) — check device |
### In Draw Mode (Accuracy Dot)
| Dot Color | Accuracy Range | Meaning |
| ---------- | -------------- | ------------------------------------------------- |
| **Green** | ≤ 2m | Excellent — high confidence |
| **Yellow** | 2–5m | Good — fine for most work |
| **Orange** | 5–10m | Fair — consider waiting for improvement |
| **Red** | > 10m | Poor — wait for better signal or move to open sky |
| **Gray** | N/A | Manual placement (no GPS) |
### On the Commit/Add Button
The commit button in Draw Mode displays the current accuracy value (e.g., "Commit (±2.5m)") and changes color:
* **Bright green** — accuracy is within acceptable range
* **Muted/dimmed** — accuracy is borderline
* **Disabled** — accuracy does not meet the Project's required threshold (if configured)
***
## What Happens When an External GPS Disconnects
If your external GPS device loses connection (battery dies, moves out of range, etc.):
1. The signal indicator turns **orange**, then **red**
2. After about 10 seconds without data, Codifi automatically switches to the **built-in iPad/iPhone GPS** so you can keep working
3. Your device stays in the Saved Devices list — when it comes back in range or is powered back on, you can reconnect it
This automatic fallback means you won't lose the ability to capture locations, though accuracy may decrease until you reconnect your external receiver.
***
## NMEA Data & Sentence Processing
External GPS receivers communicate via the **NMEA protocol**, sending standardized sentence types (GGA, RMC, GSA, etc.) over Bluetooth. Codifi parses these sentences to extract:
* **Position** (latitude, longitude) from GGA and RMC sentences
* **Altitude** from GGA sentences
* **Accuracy / HDOP** from GSA sentences
* **Course over ground** from RMC sentences
* **Satellite count** from GGA sentences
Each sentence type has its own **freshness threshold** — coordinates are considered stale after 2.5 seconds, while error estimates tolerate up to 5 seconds. This prevents mixing fresh position data with outdated accuracy values.
***
## Buffering & Adaptive Polling
Codifi adapts how frequently it reads GPS data depending on what you're doing:
| Activity | Polling Rate | Why |
| ------------------------- | ---------------- | ---------------------------------------- |
| **Draw Mode / LiveTrack** | Every 1 second | Active capture needs frequent updates |
| **Browsing (zoomed in)** | Every 5 seconds | Moderate updates for map tracking |
| **Browsing (zoomed out)** | Every 10 seconds | Less frequent to save battery |
| **App backgrounded** | Paused | GPS watcher suspends to conserve battery |
### GPS Puck Animation
The GPS location puck animates smoothly between position fixes (\~400ms for position, \~550ms for heading) instead of jumping between points. Compass heading is integrated into the puck's orientation, showing your device's facing direction (or course over ground for external GPS units).
***
## Location Policy Enforcement
Project administrators can configure GPS requirements per archetype:
GPS-Only Mode
When enabled, the Manual toggle is disabled in Draw Mode. Field workers must use GPS capture — manual placement is not allowed. A message shows: "GPS required · Switch to GPS."
Accuracy Thresholds
Administrators can set minimum accuracy requirements. If GPS accuracy doesn't meet the threshold, the Add/Commit button is disabled with a message: "Waiting for Xm accuracy." The button re-enables when GPS accuracy improves.
If accuracy exceeds a warning threshold (but isn't blocked), the button turns orange and tapping it shows a confirmation dialog — proceed anyway or wait for better accuracy.
***
## Tips for Better GPS Accuracy
* **Give your GPS a moment to settle.** When you first connect a device or step outside, accuracy improves over the first 30–60 seconds as the receiver locks onto more satellites.
* **Stay in open sky.** Buildings, dense tree canopy, and steep terrain block satellite signals. Move to a clearing if accuracy is poor.
* **Hold the device steady** when capturing a point — moving around during capture can reduce accuracy.
* **Check your source before capturing.** A quick glance at the Live Data Bar confirms you're using the right GPS device and that accuracy looks reasonable.
* **For RTK users:** Make sure your corrections source (NTRIP, base station) is connected and active. RTK Float will eventually resolve to RTK Fixed once the receiver locks in — this can take a minute or two.
***
## Typed Coordinate Entry
Codifi's typed coordinate sheet accepts **WGS84**, **NAD83**, and **NAD27** and converts them internally so every target lands in the WGS84 coordinate space the map uses. How accurate that conversion is depends on the source datum.
| Source datum | Method | Expected error (CONUS) |
| ------------ | -------------------------------------- | ---------------------- |
| WGS84 | Identity (no conversion) | 0 m |
| NAD83 | Identity (treated as WGS84) | < 1 m |
| NAD27 | 3-parameter Helmert shift through ECEF | \~5 m RMS |
Why NAD83 is treated as identical to WGS84
Within the contiguous US (CONUS), NAD83 (2011) and WGS84 (G2139 realization) agree to less than 1 meter. The mean offset is around 0.5 m, with regional variation up to \~1.2 m in parts of the western states. That's well below the 3–5 m accuracy of consumer GPS and well below what a user can visually distinguish on-screen, so Codifi treats them as equivalent.
Survey-grade workflows that require the full HARN/ITRF realignment (sub-meter) would need a 14-parameter Bursa-Wolf transform with epoch-dependent velocity corrections — that's out of scope for the built-in converter. If you need that precision, Project your coordinates outside Codifi before entry.
How NAD27 → WGS84 conversion works
NAD27 uses the Clarke 1866 ellipsoid, not WGS84's, so the converter does a three-step shift through Earth-Centered, Earth-Fixed (ECEF) space:
1. **Geodetic → ECEF on Clarke 1866.** Convert the input lat/lng (with h=0) to Cartesian XYZ centered at Earth's mass center. Clarke 1866 parameters: a = 6,378,206.4 m, f = 1/294.9787.
2. **Apply a 3-parameter translation (NIMA CONUS):**
* ΔX = −8 m
* ΔY = +160 m
* ΔZ = +176 m
Source: *NIMA TR 8350.2*, "World Geodetic System 1984." These are translations only — no rotations or scale.
3. **ECEF → geodetic on WGS84** (a = 6,378,137 m, f = 1/298.257223563) using Bowring's closed-form solution. Non-iterative and sub-meter accurate at sea-level altitudes.
**Accuracy:** The 3-parameter CONUS values give roughly **5 m RMS** positional uncertainty across the contiguous US. Published 1-sigma errors per component are ±5 m in X, ±5 m in Y, ±6 m in Z. Regional variation is real — these are continent-wide averages, and specific areas can be several meters off from the mean.
**What this misses:** NADCON grid shifts interpolate from a dense network of surveyed tie points and reach \~0.15 m typical error in CONUS. The grid files are 50+ MB and require a specialized library, so Codifi uses the 3-parameter fallback instead. For "drop a reference pin from a BLM plat or USGS quad," 5 m is fine. For survey-grade NAD27 work, convert outside Codifi and enter in WGS84.
Outside CONUS (Alaska, Hawaii, territories)
The NAD27 conversion parameters are tuned for the contiguous 48 states. Expect higher positional error on this path in Alaska, Hawaii, and US territories — region-specific parameter sets exist (e.g. "NAD-27 Alaska") but are not yet part of Codifi's converter. If this is common in your workflow, let us know and we'll prioritize adding them.
