working

README.md

@@ -0,0 +1,115 @@
+# 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