Aniker GPS Library Usage Guide

This document provides detailed information on how to use the Aniker GPS library for parsing NMEA sentences.

Installation

Add the following to your Cargo.toml:

[dependencies]
aniker-gps = "0.1.0"

Basic Usage

Parsing a GGA Sentence

The most common use case is parsing a GGA sentence to extract position data:

use aniker_gps::{Position, parse_gga, GpsError};

fn main() {
    // Example NMEA GGA sentence
    let mut gga_example = "$GPGGA,210230,3855.4487,N,09446.0071,W,1,07,1.1,370.5,M,-29.5,M,,*7A".to_string();

    // Parse the GGA sentence and handle the result
    match parse_gga(&mut gga_example) {
        Ok(position) => {
            println!("Latitude: {}", position.lat);
            println!("Longitude: {}", position.long);
            println!("Altitude: {}", position.alt);
        }
        Err(e) => {
            println!("Error parsing GGA sentence:");
            match e {
                GpsError::InvalidMessageType => println!("  Invalid message type, expected GGA"),
                GpsError::InvalidLength => println!("  Invalid GGA sentence length"),
                GpsError::ParseError(msg) => println!("  Parse error: {}", msg),
                GpsError::Other(msg) => println!("  Other error: {}", msg),
            }
        }
    }
}

Working with Position Data

The Position struct contains the following fields:

lat: Latitude in decimal degrees (positive for North, negative for South)
long: Longitude in decimal degrees (positive for East, negative for West)
alt: Altitude in meters

You can access these fields directly:

let position = parse_gga(&mut gga_example).unwrap();
let latitude = position.lat;
let longitude = position.long;
let altitude = position.alt;

Error Handling

The parse_gga function returns a Result<Position, GpsError>, which means it can either return a valid Position or a GpsError. The GpsError enum provides detailed error information:

GpsError::InvalidMessageType: Returned when the message type is not GGA
GpsError::InvalidLength: Returned when the GGA sentence has an incorrect number of fields
GpsError::ParseError(msg): Returned when parsing a specific field fails, with a description of the error
GpsError::Other(msg): Returned for other errors that don't fit into the above categories

Example of error handling:

match parse_gga(&mut gga_example) {
    Ok(position) => {
        // Use the position data
    }
    Err(e) => {
        // Handle the error
        match e {
            GpsError::InvalidMessageType => println!("Invalid message type, expected GGA"),
            GpsError::InvalidLength => println!("Invalid GGA sentence length"),
            GpsError::ParseError(msg) => println!("Parse error: {}", msg),
            GpsError::Other(msg) => println!("Other error: {}", msg),
        }
    }
}

Advanced Usage

Parsing Multiple Sentences

When working with multiple NMEA sentences, you can process them in a loop:

let sentences = vec![
    "$GPGGA,210230,3855.4487,N,09446.0071,W,1,07,1.1,370.5,M,-29.5,M,,*7A",
    "$GPGGA,210231,3855.4488,N,09446.0072,W,1,07,1.1,371.5,M,-29.5,M,,*7B",
];

for sentence in sentences {
    let mut sentence = sentence.to_string();
    match parse_gga(&mut sentence) {
        Ok(position) => {
            // Process the position
            println!("Latitude: {}, Longitude: {}", position.lat, position.long);
        }
        Err(e) => {
            // Handle the error
            match e {
                GpsError::InvalidMessageType => println!("Invalid message type, expected GGA"),
                GpsError::InvalidLength => println!("Invalid GGA sentence length"),
                GpsError::ParseError(msg) => println!("Parse error: {}", msg),
                GpsError::Other(msg) => println!("Other error: {}", msg),
            }
        }
    }
}

Examples

Check out the examples directory for more detailed examples of how to use the library:

basic_usage.rs: Simple example of parsing a GGA sentence
multiple_sentences.rs: Example of parsing multiple sentences

Running the Examples

To run the examples, use the following command:

cargo run --example basic_usage

Running the Tests

To run the tests, use the following command:

cargo test

4.3 KiB Raw Blame History