# ntrip

**Repository Path**: unignss/ntrip

## Basic Information

- **Project Name**: ntrip
- **Description**: golang, ntrip
- **Primary Language**: Go
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-08
- **Last Updated**: 2026-02-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NTRIP Library

A comprehensive implementation of the NTRIP (Networked Transport of RTCM via Internet Protocol) protocol, with a focus on NTRIP Caster functionality.

## Table of Contents

- [Project Overview](#project-overview)
- [Project Structure](#project-structure)
- [Core Features](#core-features)
- [Quick Start](#quick-start)
- [API Documentation](#api-documentation)
- [Usage Examples](#usage-examples)
- [Best Practices](#best-practices)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)

## Project Overview

This library provides a complete implementation of the NTRIP protocol, which is widely used in GNSS (Global Navigation Satellite System) applications for real-time data transfer. The core functionality is centered around the NTRIP Caster, which acts as a central hub for distributing RTCM (Radio Technical Commission for Maritime Services) correction data between reference stations and rovers.

### Key Components

- **NTRIP Caster**: Core server implementation for handling NTRIP connections and data transfer
- **NMEA Parser**: Processing GPS data in NMEA format
- **Utilities**: Helper functions for NTRIP protocol processing
- **Logging**: Standard logging interface for the library

## Project Structure

```
ntrip/
├── internal/        # Internal implementation details
├── log/             # Logging functionality
├── nmea/            # NMEA protocol processing
├── ntripcaster/     # NTRIP Caster implementation (core)
├── skill/           # AI skill for automated programming
├── utils/           # NTRIP protocol utilities
├── go.mod           # Go module definition
├── go.sum           # Go module dependencies
└── README.md        # This documentation
```

### Module Details

- **log/**: Provides logging interfaces and a null logger implementation
- **nmea/**: Handles NMEA message parsing, creation, and manipulation
- **ntripcaster/**: Core NTRIP Caster implementation with event-driven architecture
- **utils/**: Utility functions for processing NTRIP request headers
- **internal/**: Internal helper functions not exposed publicly
- **skill/**: AI skill for automated programming with the library

## Core Features

### NTRIP Caster

- **Connection Management**: Handles multiple concurrent NTRIP connections
- **Event-Driven Architecture**: Uses callbacks for connection and data events
- **Mountpoint Support**: Manages different mountpoints for data streams
- **Client Tracking**: Monitors online and alive clients
- **Graceful Shutdown**: Properly cleans up resources on shutdown

### NMEA Processing

- **Message Parsing**: Parses NMEA format GPS data
- **Message Creation**: Creates valid NMEA messages
- **Coordinate Manipulation**: Gets and sets latitude/longitude coordinates
- **Coordinate Offset**: Supports offsetting coordinates by specified meters
- **Validation**: Checks if NMEA messages are valid

### Utilities

- **Request Processing**: Parses and encodes NTRIP request headers
- **Authentication**: Supports basic authentication for NTRIP requests

## Quick Start

### Prerequisites

- Go 1.20 or later
- Git

### Installation

```bash
go get gitee.com/unignss/ntrip
```

### Basic Usage

#### Creating a Simple NTRIP Caster

```go
import (
    "gitee.com/unignss/ntrip/ntripcaster"
    "gitee.com/unignss/ntrip/log"
)

func main() {
    // Create default server options
    opts := ntripcaster.DefaultServerOptions()
    opts.Addr = ":2101" // Set port to 2101
    
    // Create NTRIP Caster with options
    caster := ntripcaster.NewNtripCaster(opts)
    
    // Set null logger (or use your custom logger)
    caster.SetLogger(log.NullLogger)
    
    // Start the server
    err := caster.Start()
    if err != nil {
        panic(err)
    }
    
    // Server is running
    println("NTRIP Caster started on", caster.ListenAddr())
    
    // Wait for shutdown (you can implement signal handling here)
    caster.WaitShutdown()
}
```

## API Documentation

### NTRIP Caster

#### NtripCaster

- **NewNtripCaster(options *ServerOptions) *NtripCaster**: Creates a new NTRIP Caster instance
- **Start() error**: Starts the NTRIP Caster server
- **Close()**: Closes the NTRIP Caster server
- **ListenAddr() string**: Returns the address the server is listening on
- **GetOnline() int**: Returns the number of online clients
- **GetClientAliveN() int**: Returns the number of alive clients
- **StatusString() string**: Returns the server status as a string
- **SetLogger(logger Logger)**: Sets the logger for the server
- **Actived() bool**: Returns whether the server is active
- **WaitShutdown()**: Waits for the server to shutdown

#### Event Handlers

- **OnNtripAccept(c *Client, req *utils.NtripRequestHead, data []byte)**: Called when a new NTRIP connection is accepted
- **OnNtripDataRecv(c *Client, data []byte)**: Called when NTRIP data is received from a client
- **OnNtripDataSend(c *Client, data []byte)**: Called when NTRIP data is sent to a client
- **OnNtripClose(c *Client)**: Called when an NTRIP connection is closed

#### ServerOptions

- **DefaultServerOptions() *ServerOptions**: Creates default server options
- **Addr string**: Server address to listen on (e.g., ":2101")
- **ReadTimeout time.Duration**: Read timeout for client connections
- **WriteTimeout time.Duration**: Write timeout for client connections

### NMEA

#### NMEA

- **NewNMEA() *NMEA**: Creates a new NMEA instance
- **CheckNMEAIsOK() bool**: Checks if NMEA message is valid
- **GetLat() float64**: Gets latitude in degrees
- **GetLng() float64**: Gets longitude in degrees
- **SetLat(lat float64)**: Sets latitude in degrees
- **SetLng(lng float64)**: Sets longitude in degrees
- **Encode() string**: Encodes NMEA data to string
- **ParseText(text string) bool**: Parses NMEA string to NMEA structure
- **OffsetLat(metre float64)**: Offsets latitude by specified meters
- **OffsetLng(metre float64)**: Offsets longitude by specified meters
- **OffsetLatLng(lat_offset float64, lng_offset float64)**: Offsets both latitude and longitude by specified meters

### Utilities

#### NtripRequestHead

- **NewNtripRequestHead() *NtripRequestHead**: Creates a new NTRIP request head instance
- **ParseText(text string) bool**: Parses NTRIP request text to structure
- **Encode() string**: Encodes NTRIP request to string
- **SetUserPass(user string, pass string)**: Sets username and password for authentication

### Logging

#### Logger

- **Debug(v ...interface{})**: Logs debug message
- **Info(v ...interface{})**: Logs info message
- **Warn(v ...interface{})**: Logs warning message
- **Error(v ...interface{})**: Logs error message
- **Infof(format string, v ...interface{})**: Logs formatted info message

#### NullLogger

A null logger implementation that discards all log messages, useful as a default logger when detailed logging is not needed.

## Usage Examples

### NTRIP Caster with Event Handlers

```go
import (
    "fmt"
    "gitee.com/unignss/ntrip/ntripcaster"
    "gitee.com/unignss/ntrip/utils"
    "gitee.com/unignss/ntrip/log"
)

func main() {
    // Create server options
    opts := ntripcaster.DefaultServerOptions()
    opts.Addr = ":2101"
    
    // Create NTRIP Caster
    caster := ntripcaster.NewNtripCaster(opts)
    caster.SetLogger(log.NullLogger)
    
    // Set up event handlers
    caster.OnNtripAccept = func(c *ntripcaster.Client, req *utils.NtripRequestHead, data []byte) {
        fmt.Printf("Client connected: %s, Mountpoint: %s\n", c.RemoteAddr(), req.Mp)
        // Send ICY 200 OK response for NTRIP clients
        c.PostBuf([]byte("ICY 200 OK\r\n\r\n"))
    }
    
    caster.OnNtripDataRecv = func(c *ntripcaster.Client, data []byte) {
        fmt.Printf("Received data from client: %d bytes\n", len(data))
        // Process received data (e.g., RTCM messages)
    }
    
    caster.OnNtripClose = func(c *ntripcaster.Client) {
        fmt.Printf("Client disconnected: %s\n", c.RemoteAddr())
        // Clean up resources if needed
    }
    
    // Start server
    err := caster.Start()
    if err != nil {
        panic(err)
    }
    
    fmt.Println("NTRIP Caster started with event handlers")
    caster.WaitShutdown()
}
```

### Processing NMEA Messages

```go
import (
    "fmt"
    "gitee.com/unignss/ntrip/nmea"
)

func main() {
    // Create a new NMEA instance
    nmeaMsg := nmea.NewNMEA()
    
    // Set coordinates
    nmeaMsg.SetLat(30.5)
    nmeaMsg.SetLng(114.3)
    
    // Get coordinates
    lat := nmeaMsg.GetLat()
    lng := nmeaMsg.GetLng()
    fmt.Printf("Initial coordinates: Lat=%f, Lng=%f\n", lat, lng)
    
    // Offset coordinates (meters)
    nmeaMsg.OffsetLatLng(100, 200) // Move 100m north, 200m east
    
    // Get updated coordinates
    newLat := nmeaMsg.GetLat()
    newLng := nmeaMsg.GetLng()
    fmt.Printf("Updated coordinates: Lat=%f, Lng=%f\n", newLat, newLng)
    
    // Encode NMEA message
    encoded := nmeaMsg.Encode()
    fmt.Printf("Encoded NMEA: %s\n", encoded)
    
    // Check if NMEA is valid
    isValid := nmeaMsg.CheckNMEAIsOK()
    fmt.Printf("NMEA valid: %t\n", isValid)
}
```

### NTRIP Request Processing

```go
import (
    "fmt"
    "gitee.com/unignss/ntrip/utils"
)

func main() {
    // Create a new NTRIP request head
    req := utils.NewNtripRequestHead()
    
    // Set up a GET request for a mountpoint
    req.Method = "GET"
    req.Mp = "MOUNT1"
    
    // Add some headers
    req.Head = make(map[string]string)
    req.Head["User-Agent"] = "NTRIP Client"
    
    // Encode request to string
    encoded := req.Encode()
    fmt.Printf("Encoded request:\n%s\n", encoded)
    
    // Parse a request string
    testReq := "GET /MOUNT1 HTTP/1.0\r\nUser-Agent: NTRIP Client\r\n\r\n"
    parsedReq := utils.NewNtripRequestHead()
    success := parsedReq.ParseText(testReq)
    if success {
        fmt.Printf("Parsed request: Method=%s, Mountpoint=%s\n", parsedReq.Method, parsedReq.Mp)
    }
}
```

## Best Practices

1. **Logging**: Always use `log.NullLogger` as the default logger if you don't need detailed logging
2. **Error Handling**: Implement proper error handling for all NTRIP Caster operations
3. **Timeouts**: Set appropriate timeouts for client connections to prevent resource leaks
4. **Event Handlers**: Use event handlers to properly process NTRIP data and manage client connections
5. **Validation**: Always validate NMEA messages before processing them
6. **Graceful Shutdown**: Implement graceful shutdown for the NTRIP Caster to properly clean up resources
7. **Monitoring**: Monitor the number of online clients to detect potential issues
8. **Authentication**: Use proper authentication for sensitive NTRIP services

## Troubleshooting

### Common Issues

#### NTRIP Caster fails to start

- **Possible causes**: Port already in use, invalid address format, permission denied
- **Solutions**: Use a different port, check address format, run with appropriate permissions

#### Clients cannot connect

- **Possible causes**: Firewall blocking port, incorrect server address, network issues
- **Solutions**: Configure firewall, verify server address, check network connectivity

#### Data not being transmitted correctly

- **Possible causes**: Invalid NTRIP messages, network timeouts, incorrect event handlers
- **Solutions**: Validate NTRIP messages, adjust timeouts, check event handler implementation

## Contributing

### Development Setup

1. Fork the repository
2. Clone your fork
3. Create a feature branch
4. Make your changes
5. Run tests
6. Submit a pull request

### Code Style

- Follow Go's standard code style
- Use `go fmt` to format your code
- Write clear, concise comments
- Test your changes

### Testing

```bash
go test ./...
```

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

## Acknowledgments

- This project implements the NTRIP protocol as defined by the RTCM (Radio Technical Commission for Maritime Services)
- Thanks to all contributors who have helped improve this library

## Contact

For questions or issues, please open an issue on the [GitHub repository](https://gitee.com/unignss/ntrip/issues).

---

*Version 1.0.0*