mirror of
https://github.com/geoffsee/gpyes-stream.git
synced 2025-09-08 22:56:47 +00:00
115 lines
3.1 KiB
Markdown
115 lines
3.1 KiB
Markdown
# GNSS Reader
|
|
|
|
A Rust-based GNSS (Global Navigation Satellite System) data parser that reads GPS location data from serial devices and converts NMEA sentences into structured, usable location information.
|
|
|
|
## Features
|
|
|
|
- **NMEA Sentence Parsing**: Supports GPGGA and GPRMC sentence formats
|
|
- **Live GPS Reading**: Real-time data streaming from USB GPS devices
|
|
- **Demo Mode**: Built-in demonstration with sample GPS data
|
|
- **Cross-Platform**: Works on macOS, Linux, and Windows
|
|
- **Structured Output**: Converts raw NMEA data into organized LocationData structures
|
|
- **Comprehensive Testing**: Includes extensive test coverage for various GPS scenarios
|
|
|
|
## Requirements
|
|
|
|
- Rust 2024 edition or later
|
|
- USB GPS device (tested with Stratux GPYes 2.0 u-blox 8)
|
|
- Serial port access permissions
|
|
|
|
## Installation
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
git clone <repository-url>
|
|
cd gpyes-stream
|
|
```
|
|
|
|
2. Build the project:
|
|
```bash
|
|
cargo build --release
|
|
```
|
|
|
|
3. Run the application:
|
|
```bash
|
|
cargo run
|
|
```
|
|
|
|
## Usage
|
|
|
|
The application automatically detects and connects to your GPS device. On startup, it will:
|
|
|
|
1. Attempt to connect to the GPS device via serial port
|
|
2. Parse incoming NMEA sentences (GPGGA and GPRMC formats)
|
|
3. Display structured location data including:
|
|
- Latitude and Longitude coordinates
|
|
- Altitude information
|
|
- GPS fix quality and satellite count
|
|
- Speed and course data
|
|
- UTC timestamp
|
|
|
|
### Demo Mode
|
|
|
|
To run the application with sample data without a physical GPS device:
|
|
|
|
```bash
|
|
cargo run -- --demo
|
|
```
|
|
|
|
## Supported Hardware
|
|
|
|
### Tested Devices
|
|
- **Stratux GPYes 2.0 u-blox 8 USB GPS Unit** (~$20)
|
|
- Amazon: https://www.amazon.com/Stratux-GPYes-2-0-u-blox-unit/dp/B0716BK5NT
|
|
- Device paths on macOS: `/dev/tty.usbmodem2101` or `/dev/cu.usbmodem2101`
|
|
|
|
### Compatibility
|
|
The application should work with any USB GPS device that outputs standard NMEA sentences via serial communication.
|
|
|
|
## NMEA Sentence Support
|
|
|
|
Currently supports the following NMEA sentence types:
|
|
- **GPGGA**: Global Positioning System Fix Data
|
|
- **GPRMC**: Recommended Minimum Course
|
|
- **GNGGA**: GNSS Fix Data (multi-constellation)
|
|
- **GNRMC**: GNSS Recommended Minimum Course
|
|
|
|
## Development
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
cargo test
|
|
```
|
|
|
|
### Building for Release
|
|
|
|
```bash
|
|
cargo build --release
|
|
```
|
|
|
|
The compiled binary will be available in `target/release/gnss-reader`.
|
|
|
|
## Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
|
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
|
|
4. Push to the branch (`git push origin feature/amazing-feature`)
|
|
5. Open a Pull Request
|
|
|
|
## License
|
|
|
|
This project is open source. Please refer to the LICENSE file for details.
|
|
|
|
## Troubleshooting
|
|
|
|
### Device Not Found
|
|
- Ensure your GPS device is properly connected
|
|
- Check device permissions (you may need to add your user to the `dialout` group on Linux)
|
|
- Verify the device path matches your system configuration
|
|
|
|
### No GPS Signal
|
|
- Ensure you have a clear view of the sky
|
|
- Wait for the GPS device to acquire satellite lock (may take several minutes on first use)
|
|
- Check that your GPS device is functioning properly |