145 lines
4.3 KiB
Markdown
145 lines
4.3 KiB
Markdown
# 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`:
|
|
|
|
```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:
|
|
|
|
```rust
|
|
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:
|
|
|
|
```rust
|
|
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:
|
|
|
|
```rust
|
|
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:
|
|
|
|
```rust
|
|
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:
|
|
|
|
```bash
|
|
cargo run --example basic_usage
|
|
```
|
|
|
|
## Running the Tests
|
|
|
|
To run the tests, use the following command:
|
|
|
|
```bash
|
|
cargo test
|
|
``` |