https://github.com/eduponz/easynmea
A c++ library to get NMEA information from modules which use NMEA 0183 over serial communication.
https://github.com/eduponz/easynmea
cpp gnss gps gps-data gps-library nmea nmea0183 open-source
Last synced: 5 months ago
JSON representation
A c++ library to get NMEA information from modules which use NMEA 0183 over serial communication.
- Host: GitHub
- URL: https://github.com/eduponz/easynmea
- Owner: EduPonz
- License: mit
- Created: 2018-11-16T18:52:16.000Z (about 7 years ago)
- Default Branch: main
- Last Pushed: 2021-10-22T10:00:48.000Z (about 4 years ago)
- Last Synced: 2025-07-28T05:50:27.303Z (6 months ago)
- Topics: cpp, gnss, gps, gps-data, gps-library, nmea, nmea0183, open-source
- Language: C++
- Homepage: https://easynmea.readthedocs.io
- Size: 279 KB
- Stars: 11
- Watchers: 3
- Forks: 4
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# EasyNMEA {#index}
[](https://github.com/EduPonz/easynmea/actions/workflows/automated_testing.yml)
[](https://github.com/EduPonz/easynmea/actions/workflows/publish_docker_image.yml)
[](https://easynmea.readthedocs.io/en/latest/?badge=latest)
[](https://hub.docker.com/repository/docker/eduponz/easynmea)
[](https://codecov.io/gh/EduPonz/easynmea)
[](https://github.com/EduPonz/easynmea/actions/workflows/codeql-analysis.yml)
**EasyNMEA** is a `C++` library to get **NMEA** information from NMEA modules which communicate with **NMEA 0183** over UART.
It can retrieve NMEA data from any NMEA device sending **NMEA 0183** sentences over UART.
* [Features](#features)
* [Getting started](#getting-started)
* [Prerequisites](#prerequisites)
* [Build and install](#build-and-install)
* [Build documentation](#build-documentation)
* [Run examples](#run-examples)
* [Usage](#usage)
* [Authors](#authors)
* [License](#license)
* [To-Do](#to-do)
For more detailed information, please visit the [EasyNMEA documentation](https://easynmea-docs.readthedocs.io/).
## Features
**easynmea** provides the `EasyNmea` class, which uses **NMEA 0183** sentences to extract **NMEA** information from the modules, providing a simple and easy-to-use API.
## Getting started
**easynmea** has been developed and tested in Ubuntu 20.04 Operating System, although it is expected to support Windows 10 and MacOS thanks to [Asio](https://github.com/chriskohlhoff/asio), the cross-platform library used to interact with the serial ports.
### Prerequisites
**easynmea** relies on [Asio](https://github.com/chriskohlhoff/asio) for establishing a serial connection with the NMEA module.
On Ubuntu platforms, this can be installed with:
```bash
sudo apt install libasio-dev
```
### Build and install
To build the library, run:
```bash
cd ~
git clone https://github.com/EduPonz/easynmea.git
mkdir build && cd build
cmake ..
cmake --build .
```
Once built, the library can be installed in a user specified directory with:
```bash
cd ~/easynmea/build
cmake .. -DCMAKE_INSTALL_PREFIX=
cmake --build . --target install
```
To install the library system-wide, just omit the `CMAKE_INSTALL_PREFIX`:
```bash
cd ~/easynmea/build
cmake ..
cmake --build . --target install
```
### Build documentation
It is possible to generate the library's documentation passing CMake option `-DBUILD_DOCUMENTATION=0N` (defaults to `OFF`) on the configuration step:
```bash
cd ~/easynmea/build
cmake .. -DCMAKE_INSTALL_PREFIX= -DBUILD_DOCUMENTATION=ON
cmake --build . --target install
```
### Run examples
It is also possible to build and install the library's examples passing CMake option `-DBUILD_EXAMPLES=ON` (defaults to `OFF`) on the configuration step:
```bash
cd ~/easynmea/build
cmake .. -DCMAKE_INSTALL_PREFIX= -DBUILD_EXAMPLES=ON
cmake --build . --target install
```
Then, they can be run with:
```bash
cd /examples/bin
./gpgga_example
```
An output example from `gpgga_example` would be:
```
Serial port '/dev/ttyACM0' opened. Baudrate: 9600
Please press CTRL-C to stop the example
************** NEW GPGGA SAMPLE **************
Elapsed time ---------> 3468
------------------------------------------
GPGGA Data - GNSS Position Fix
==============================
Message --------------> $GPGGA,072706.000,5703.1740,N,00954.9459,E,1,8,1.28,-21.2,M,42.5,M,,*4E
Timestamp ------------> 72706
Latitude -------------> 57.0529º N
Longitude ------------> 9.91576º E
Fix ------------------>
Number of satellites -> 8
Horizontal precision -> 1.28
Altitude -------------> -21.2
```
The some example's parameters can be configured using command line options.
Run `./gpgga_example --help`
```
------------------------
EasyNMEA - GPGGA Example
------------------------
Usage: ./gpgga_example [OPTIONS]
-h/--help: Print this help and exit
-b/--baudrate [bauds]: The connection baud rate in bauds [Defaults: 9600]
-p/--serial_port [port]: The serial port to use [Defaults: 'dev/ttyACM0']
Example: ./gpgga_example -p /dev/ttyUSB0 -b 9600
```
## Usage
The **NMEA** information can be retrieved in the following manner (see [gpgga_example.cpp](examples/gpgga_example.cpp)):
```c++
using namespace eduponz::easynmea;
// Create an EasyNmea object
EasyNmea easynmea;
// Open the serial port
if (easynmea.open("/dev/ttyACM0", 9600) == ReturnCode::RETURN_CODE_OK)
{
// Create a mask to only wait on data from specific NMEA 0183 sentences
NMEA0183DataKindMask data_kind_mask = NMEA0183DataKind::GPGGA;
// This call will block until some data of any of the kinds specified in the mask is available.
while (easynmea.wait_for_data(data_kind_mask) == ReturnCode::RETURN_CODE_OK)
{
// Take all the available data samples of type GPGGA
GPGGAData gpgga_data;
while (easynmea.take_next(gpgga_data) == ReturnCode::RETURN_CODE_OK)
{
// Do something with the GNSS data
std::cout << "GNSS position: (" << gpgga_data.latitude << "; " << gpgga_data.longitude << ")" << std::endl;
}
}
}
// Close the serial connection
easynmea.close();
```
## Authors
**easynmea** has been developed by **Eduardo Ponz**.
## License
This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.