Skip to content

Latest commit

 

History

History
168 lines (130 loc) · 5.83 KB

README.md

File metadata and controls

168 lines (130 loc) · 5.83 KB
Raw

EasyNMEA {#index}

automated_testing Publish Docker image Documentation Status Docker pulls codecov CodeQL

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.

For more detailed information, please visit the EasyNMEA documentation.

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, the cross-platform library used to interact with the serial ports.

Prerequisites

easynmea relies on Asio for establishing a serial connection with the NMEA module. On Ubuntu platforms, this can be installed with:

sudo apt install libasio-dev

Build and install

To build the library, run:

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:

cd ~/easynmea/build
cmake .. -DCMAKE_INSTALL_PREFIX=<user-specified-dir>
cmake --build . --target install

To install the library system-wide, just omit the CMAKE_INSTALL_PREFIX:

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:

cd ~/easynmea/build
cmake .. -DCMAKE_INSTALL_PREFIX=<user-specified-dir> -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:

cd ~/easynmea/build
cmake .. -DCMAKE_INSTALL_PREFIX=<user-specified-dir> -DBUILD_EXAMPLES=ON
cmake --build . --target install

Then, they can be run with:

cd <user-specified-dir>/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):

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 file for details.