rn-gnss

Note: This package was generated with AI assistance and may require human review before production use.

React Native module for accessing GNSS (GPS) data on Android and iOS using Nitro.

Features

• Location updates - Get precise location from GPS
• Satellite status - View satellite information (constellation, CN0, azimuth, elevation)
• Raw GNSS measurements - Access pseudorange, carrier phase, and other raw data (Android only)
• Navigation messages - Receive decoded navigation messages (Android only)

Installation

npm install rn-gnss
cd ios && pod install

Permissions

Android

Add to your AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

<uses-feature android:name="android.hardware.location.gnss" android:required="false" />

Request permission at runtime:

import { Platform } from 'react-native'

if (Platform.OS === 'android') {
  const granted = await PermissionsAndroid.request(
    PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION
  )
}

iOS

Add to your Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>App needs location for GNSS data</string>
<key>NSLocationAlwaysAndWhenInUsageDescription</key>
<string>App needs background location for GNSS tracking</string>

Usage

import { GnssManager, enrichSatelliteStatusWithPositions } from 'rn-gnss'

// Create GNSS manager instance
const gnss = new GnssManager()

// Check capabilities
console.log('Capabilities:', gnss.capabilities)

// Start GNSS
gnss.start()

// Get location
const location = gnss.getLatestLocation()
if (location) {
  console.log('Latitude:', location.latitude)
  console.log('Longitude:', location.longitude)
  console.log('Accuracy:', location.accuracy, 'meters')
}

// Get satellite status
const satellites = gnss.getLatestSatelliteStatus()

// Enrich with positions (auto fetch TLE + calculate)
await enrichSatelliteStatusWithPositions(satellites)

// Ready to use - each satellite has latitude, longitude, altitude
satellites.forEach((sat) => {
  console.log(`SV ${sat.svid}:`)
  console.log(`  CN0: ${sat.cn0DbHz.toFixed(1)} dB-Hz`)
  console.log(
    `  Position: ${sat.latitude?.toFixed(2)}°, ${sat.longitude?.toFixed(2)}°`
  )
})

// Stop GNSS when done
gnss.stop()

Satellite Position Tracking

Get the real-time geodetic position (latitude, longitude, altitude) of any GPS satellite using TLE (Two-Line Element) data.

Step 1: Fetch TLE Data

Fetch satellite TLE from CelesTrak or N2YO:

import { getTle, ConstellationType } from 'rn-gnss'

// Get TLE for GPS satellite PRN 1
const tle = await getTle(ConstellationType.GPS, 1)

if (tle) {
  console.log('Satellite:', tle.name)
  console.log('Line 1:', tle.line1)
  console.log('Line 2:', tle.line2)
}

Step 2: Calculate Position

Use the TLE to calculate the satellite's current position:

import { getSatellitePosition } from 'rn-gnss'

// TLE for ISS (example)
const tleLine1 =
  '1 25544U 98067A   26093.10136821  .00012012  00000-0  22784-3 0  9993'
const tleLine2 =
  '2 25544  51.6327 311.6710 0006236 265.7481  94.2795 15.48735493560113'

// Get current position
const position = getSatellitePosition(tleLine1, tleLine2, Date.now())

if (position) {
  console.log('Latitude:', position.latitude.toFixed(4), '°')
  console.log('Longitude:', position.longitude.toFixed(4), '°')
  console.log('Altitude:', position.altitude.toFixed(0), 'm')
}

Full Example: Track GPS Satellites

import {
  getTle,
  getSatellitePosition,
  ConstellationType,
  svidToIdentifier,
} from 'rn-gnss'

async function trackGpsSatellites() {
  const constellationType = ConstellationType.GPS
  const maxSatellites = 32

  for (let svid = 1; svid <= maxSatellites; svid++) {
    // Fetch TLE
    const tle = await getTle(constellationType, svid)
    if (!tle) continue

    // Calculate position
    const position = getSatellitePosition(tle.line1, tle.line2, Date.now())
    if (!position) continue

    // Display satellite info
    console.log(`${svidToIdentifier(constellationType, svid)}:`)
    console.log(
      `  Position: ${position.latitude.toFixed(2)}°, ${position.longitude.toFixed(2)}°`
    )
    console.log(`  Altitude: ${position.altitude.toFixed(0)} km`)
  }
}

trackGpsSatellites()

Available Functions

| Function | Description | | ----------------------------------------------------- | ------------------------------------ | | getTle(constellationType, svid) | Fetch TLE from network | | getSatellitePosition(tleLine1, tleLine2, timestamp) | Calculate geodetic position | | propagate(tleLine1, tleLine2, timestamp) | Get ECI coordinates | | svidToIdentifier(constellationType, svid) | Format satellite ID (e.g., "PRN 01") | | getConstellationName(constellationType) | Get constellation name (e.g., "GPS") | | getCelestrakGroup(constellationType) | Get CelesTrak group name |

Constellation Types

| Type | Value | Satellites | | --------- | ----- | ---------- | | GPS | 1 | 32 | | GLONASS | 2 | 24 | | QZSS | 3 | 10 | | BEIDOU | 4 | 60 | | GALILEO | 5 | 36 | | IRNSS | 6 | 7 | | SBAS | 7 | ~20 |

API

GnssManager

| Property | Type | Description | | -------------- | ------------------ | --------------------------------- | | isStarted | boolean | Whether GNSS is actively tracking | | capabilities | GnssCapabilities | Bitmask of supported features |

| Method | Returns | Description | | ---------------------------- | ------------------------------- | ------------------------------- | | start() | void | Start GNSS tracking | | stop() | void | Stop GNSS tracking | | getLatestLocation() | GnssLocation \| null | Last known location | | getLatestSatelliteStatus() | GnssSatellite[] | Current satellite status | | getLatestMeasurements() | GnssMeasurementsEvent \| null | Raw measurements (Android only) |

Types

interface GnssLocation {
  latitude: number
  longitude: number
  altitude: number
  speed: number
  bearing: number
  accuracy: number
  timestamp: number
}

interface GnssSatellite {
  svid: number
  constellationType: ConstellationType
  cn0DbHz: number
  elevationDegrees: number
  azimuthDegrees: number
  usedInFix: boolean
  hasAlmanacData: boolean
  hasEphemerisData: boolean
}

interface GnssMeasurement {
  timeNanos: number
  svid: number
  constellationType: ConstellationType
  cn0DbHz: number
  pseudorangeRateMps: number
  carrierFrequencyHz: number
  carrierPhase: number
  multipathIndicator: MultipathIndicator
  state: MeasurementState
}

const ConstellationType = {
  GPS: 1,
  GLONASS: 2,
  QZSS: 3,
  BEIDOU: 4,
  GALILEO: 5,
  IRNSS: 6,
  SBAS: 7,
  UNKNOWN: 0,
}

Platform Differences

| Feature | Android | iOS | | ------------------- | ------- | ---------------- | | Location | ✅ Full | ✅ Full | | Satellite status | ✅ Full | ⚠️ Limited | | Raw measurements | ✅ Full | ❌ Not available | | Navigation messages | ✅ Full | ❌ Not available |

iOS Core Location does not expose raw GNSS measurements or navigation messages to third-party apps.

License

MIT