# lc29h

CLI tool and MCP server for Quectel LC29H dual-band (L1+L5) GNSS modules on Linux.

A native Linux replacement for the Windows-only QGNSS tool. Provides position monitoring, satellite tracking, constellation configuration, NTRIP-based RTK corrections for centimeter-level accuracy, base station survey-in, and dead reckoning control -- all from the terminal or through an MCP server for LLM integration.

Supports all five LC29H module variants: AA, BA, CA, DA, and BS.

**Documentation:** <https://lc29h.warehack.ing/>

## Installation

Requires Python 3.11 or later.

```bash
# Recommended
uv tool install lc29h

# Alternative
pipx install lc29h
```

## Serial Port

The module communicates over UART. Specify the port with `--port` or the `LC29H_PORT` environment variable:

```bash
lc29h --port /dev/ttyS0 info       # Pi 4B (built-in UART)
lc29h --port /dev/ttyAMA0 info     # Pi 5
lc29h --port /dev/ttyUSB0 info     # USB-to-serial adapter
```

Default: `/dev/ttyS0`. Baud rate defaults to 115200, configurable via `--baud` or `LC29H_BAUD`.

## CLI Reference

### Module Information

```bash
lc29h info
```

```
Model:    LC29HDANR11A07S
Firmware: LC29HDANR11A07S_RSA
Built:    2024/07/16 17:50:56
Chip:     AG3335A
Chip FW:  AXN_5.3.0_p2
```

### Position Monitoring

```bash
lc29h monitor                          # Live table (default)
lc29h monitor --format csv             # CSV output for logging
lc29h monitor --format nmea            # Raw NMEA sentences
lc29h monitor --count 10               # Stop after 10 fixes
```

### Satellite Status

```bash
lc29h satellites
```

Displays dual-band (L1/L5) signal-to-noise ratios per satellite, grouped by physical PRN:

```
  PRN    Const  Elev  Azim    L1    L5  Used
--------------------------------------------
    2      GPS    51   283    34    30     *
    5      GPS    14   180    22   ---
    7      GPS    63    47    38    34     *
   10      GPS    27   130    30    28     *
   24      GPS    41   314    33    32     *
    3  GALILEO    32    73    31    28     *
    8  GALILEO    19   210    27    25
   26  GALILEO    68   155    36    33     *

8 satellites tracked (14 signal observations)
```

### Configuration

```bash
# Enable/disable constellations
lc29h config constellation --gps --galileo --no-glonass --no-beidou

# Set position fix rate (100-10000 ms)
lc29h config fix-rate 200                # 5 Hz updates

# Change serial baud rate
lc29h config baud 230400

# Save current settings to flash (persist across reboots)
lc29h config save

# Restore factory defaults
lc29h config restore
```

### Module Restart

```bash
lc29h restart hot                       # Keep all data (~1s TTFF)
lc29h restart warm                      # Clear ephemeris (~30s TTFF)
lc29h restart cold                      # Full reacquisition (~60s TTFF)
```

### NTRIP (RTK Corrections)

For centimeter-level positioning on DA and BA variants:

```bash
# List available mount points
lc29h ntrip sources --host rtk2go.com

# Stream RTK corrections (auto-detects NTRIP 1.0/2.0, exponential backoff)
lc29h ntrip start --host rtk2go.com --mount NEAR_ME \
    --user user@example.com --password none
```

### Base Station Survey-In (BS Variant)

```bash
# Start survey-in (average position for 1 hour, target 0.5m accuracy)
lc29h survey-in start-survey --duration 3600 --accuracy 0.5

# Check progress (shows WGS84 position converted from ECEF)
lc29h survey-in status

# Stop survey-in
lc29h survey-in stop
```

### JSON Output

All commands support `--json` for machine-readable output:

```bash
lc29h --json info
lc29h --json monitor --count 1
```

## MCP Server

The package includes `lc29h-mcp`, a FastMCP server that exposes GNSS functionality as tools for LLM integration. The server maintains a persistent serial connection with background NMEA parsing, so position and satellite data are always current.

### Setup

```bash
# Add to Claude Code
claude mcp add lc29h -- uvx lc29h-mcp

# Or run directly
lc29h-mcp
```

Configure via environment variables: `LC29H_PORT`, `LC29H_BAUD`.

### Tools (20)

**Position and Status**
- `get_position` -- Current lat/lon/alt, fix type, satellites, HDOP, speed, course
- `get_satellites` -- All tracked satellites with PRN, elevation, azimuth, SNR, constellation
- `get_module_info` -- Firmware version, model, chip identification

**Configuration**
- `configure_constellations` -- Enable/disable GPS, GLONASS, Galileo, BeiDou, QZSS
- `set_fix_rate` -- Position update rate (100ms to 10s)
- `save_config` -- Persist settings to flash
- `restart_module` -- Hot/warm/cold restart

**NTRIP (RTK Corrections)**
- `ntrip_connect` -- Connect to caster, or list mount points if no mountpoint given
- `ntrip_status` -- Check connection state
- `ntrip_disconnect` -- Stop correction stream

**Base Station (BS Variant)**
- `survey_in_start` -- Begin position averaging with duration/accuracy targets
- `survey_in_status` -- Progress, accuracy, WGS84 position from ECEF

**Dead Reckoning (BA/CA Variants)**
- `dead_reckoning_config` -- Get/set DR mode (GNSS only, DR only, auto)

**EASY / AGNSS (AA Variant)**
- `easy_status` -- Query ephemeris prediction status
- `easy_enable` -- Enable/disable orbit prediction for faster TTFF

**Power and Performance**
- `odometer` -- Enable/disable/reset distance accumulation
- `elevation_mask` -- Get/set satellite elevation cutoff angle
- `speed_clamping` -- Zero-speed reporting when stationary
- `gnss_suspend_resume` -- Idle the GNSS engine to save power
- `periodic_mode` -- Duty-cycled tracking (run/sleep windows)

### Resources

- `gnss://position` -- Live position summary
- `gnss://satellites` -- Current constellation view
- `gnss://status` -- Module and NTRIP connection state

## Supported Variants

| Variant | Features |
|---------|----------|
| LC29H(AA) | SBAS augmentation, EASY self-generated ephemeris |
| LC29H(BA) | Dead Reckoning + RTK |
| LC29H(CA) | Dead Reckoning (inertial navigation, no RTK) |
| LC29H(DA) | RTK with fast convergence |
| LC29H(BS) | Base Station (RTCM3 output, survey-in) |

## License

MIT
