README.md

   1 marnav
   2 ======
   3
   4 Copyright (c) 2021 Mario Konrad (mario.konrad@gmx.net)
   5
   6 ---
   7
   8 Abstract
   9 --------
  10
  11 This is a C++ library for **MAR**itime **NAV**igation purposes.
  12
  13 It supports (partially):
  14 - NMEA-0183
  15 - AIS
  16 - SeaTalk (Raymarine device communication)
  17 - Reading data from serial ports (NMEA, SeaTalk)
  18 - Basic geodesic functions, suitable for martime navigation.
  19
  20 See chapter _Features_ for a complete and detailed list.
  21
  22 ---
  23
  24 Goals
  25 -----
  26
  27 There are already implementaions for reading and writing NMEA-0183 or AIS.
  28 The goal of this library is
  29 - to have an implementation in modern C++
  30 - easy to use API (std lib like, integrating well)
  31 - unit tested (high test coverage)
  32 - trivial integration into projects (liberal license, as few dependencies as
  33   possible)
  34 - (more or less) well documented
  35 - (more or less) complete, as far as information is freely available
  36 - having fun
  37
  38 ---
  39
  40 Features
  41 --------
  42
  43 ### NMEA-0183
  44
  45 Supported sentences for NMEA-0183 (read and write):
  46 - AAM: Waypoint Arrival Alarm
  47 - ALM: GPS Almanac Data
  48 - APA: Autopilot Sentence "A"
  49 - APB: Autopilot Sentence "B"
  50 - BEC: Bearing and Distance to Waypoint
  51 - BOD: Bearing - Waypoint to Waypoint
  52 - BWC: Bearing & Distance to Waypoint - Geat Circle
  53 - BWR: Bearing and Distance to Waypoint - Rhumb Line
  54 - BWW: Bearing - Waypoint to Waypoint
  55 - DBT: Depth Below Transducer
  56 - DPT: Depth of Water
  57 - DSC: Digital Selective Calling Information (**experimental**)
  58 - DSE: Extended DSC (**experimental**)
  59 - DTM: Datum Reference
  60 - FSI: Frequency Set Information
  61 - GBS: GPS Satellite Fault Detection
  62 - GGA: Global Positioning System Fix Data
  63 - GLC: Geographic Position, Loran-C
  64 - GLL: Geographic Position - Latitude/Longitude
  65 - GNS: Fix data
  66 - GRS: GPS Range Residuals
  67 - GSA: Geographic Position - Latitude/Longitude
  68 - GST: GPS Pseudorange Noise Statistics
  69 - GSV: Satellites in view
  70 - GTD: Geographic Location in Time Differences
  71 - HDG: Heading - Deviation & Variation
  72 - HDT: Heading - True
  73 - HFB: Trawl Headrope to Footrope and Bottom
  74 - HSC: Heading Steering Command
  75 - ITS: Trawl Door Spread 2 Distance
  76 - LCD: Loran-C Signal Data
  77 - MOB: Man over Board
  78 - MSK: Control for a Beacon Receiver
  79 - MSS: Beacon Receiver Status
  80 - MTW: Mean Temperature of Water
  81 - MWD: Wind Direction and Speed
  82 - MWV: Wind Speed and Angle
  83 - OSD: Own Ship Data
  84 - RMA: Recommended Minimum Navigation Information
  85 - RMB: Recommended Minimum Navigation Information
  86 - RMC: Recommended Minimum Navigation Information
  87 - ROT: Rate Of Turn
  88 - RPM: Revolutions
  89 - RSA: Rudder Sensor Angle
  90 - RSD: RADAR System Data (**experimental**)
  91 - RTE: Routes
  92 - SFI: Scanning Frequency Information
  93 - STN: Multiple Data ID
  94 - TDS: Trawl Door Spread Distance
  95 - TFI: Trawl Filling Indicator
  96 - TLL: Target Latitude and Longitude
  97 - TPC: Trawl Position Cartesian Coordinates
  98 - TPR: Trawl Position Relative Vessel
  99 - TPT: Trawl Position True
 100 - TTM: Tracked Target Message
 101 - VBW: Dual Ground/Water Speed
 102 - VDM: AIS VHF Data-Link Message
 103 - VDO: AIS VHF Data-Link Own-Vessel Report
 104 - VDR: Set and Drift
 105 - VHW: Water speed and heading
 106 - VLW: Distance Traveled through Water
 107 - VTG: Track made good and Ground speed
 108 - VWR: Relative Wind Speed and Angle.
 109 - VPW: Speed - Measured Parallel to Wind
 110 - WCV: Waypoint Closure Velocity
 111 - WNC: Distance - Waypoint to Waypoint
 112 - WPL: Waypoint Location
 113 - XDR: Transducer Measurement
 114 - XTE: Cross-Track Error, Measured
 115 - XTR: Cross Track Error - Dead Reckoning
 116 - ZDA: Time & Date - UTC, day, month, year and local time zone
 117 - ZDL: Time and Distance to Variable Point
 118 - ZFO: UTC & Time from origin Waypoint
 119 - ZTG: UTC & Time to Destination Waypoint
 120
 121 Obsolete (according to the standard) but implemented:
 122 - DBK: Depth Below Keel
 123 - HDM: Heading - Magnetic (obsolete as of 2009)
 124 - R00: Waypoints in active route
 125
 126 Vendor Extensions:
 127 - PGRME: Garmin Estimated Error
 128 - PGRMM: Garmin Map Datum
 129 - PGRMZ: Garmin Altitude Information
 130 - STALK: SeaTalk Raw Format
 131
 132 Miscellaneous:
 133 - Tag Block Support (generic for all sentences)
 134
 135
 136 ### AIS
 137
 138 Supported messages for AIS (decode and encode):
 139 - Type 01: Position Report Class A
 140 - Type 02: Position Report Class A (Assigned Schedule)
 141 - Type 03: Position Report Class A (Response to Interrogation)
 142 - Type 04: Base Station Report
 143 - Type 05: Static and Voyage Related Data
 144 - Type 06: Binary Addressed Message
 145 - Type 07: Binary Acknowledge
 146 - Type 08: Binary Broadcast Message
 147 - Type 09: Standard SAR Aircraft Position Report
 148 - Type 10: UTC/Date Inquiry
 149 - Type 11: UTC/Date Response
 150 - Type 12: Addressed Safety-Related Message
 151 - Type 13: Safety-Related Acknowledgement
 152 - Type 14: Safety-Related Broadcast Message
 153 - Type 17: DGNSS Broadcast Binary Message
 154 - Type 18: Standard Class B CS Position Report
 155 - Type 19: Extended Class B CS Position Report
 156 - Type 20: Data Link Management
 157 - Type 21: Aid-to-Navigation Report
 158 - Type 22: Channel Management
 159 - Type 23: Group Assignment Command
 160 - Type 24: Static Data Report (part A and B, norma and auxiliary vessel)
 161
 162 Supported payload of binary message 08:
 163 - 001/11: Meteorological and Hydrological Data (IMO236)
 164 - 200/10: Inland ship static and voyage related data (Inland AIS)
 165
 166 ### SeaTalk
 167
 168 Suported messages for SeaTalk (decode and encode):
 169 - Type 00: depth below transducer
 170 - Type 01: equipment id
 171 - Type 05: Engine RPM and PITCH
 172 - Type 10: apparent wind angle
 173 - Type 11: apparent wind speed
 174 - Type 20: speed through water
 175 - Type 21: trip mileage
 176 - Type 22: total mileage
 177 - Type 23: water temperature 1
 178 - Type 24: Display unit for Mileage and Speed
 179 - Type 25: total and trip log
 180 - Type 26: Speed through Water
 181 - Type 27: water temperature 2
 182 - Type 30: Set Lamp Intensity
 183 - Type 36: Cancel MOB condition
 184 - Type 38: Codelock data (**experimental**)
 185 - Type 50: LAT Postion
 186 - Type 51: LON Postion
 187 - Type 52: Speed over Ground
 188 - Type 53: Magnetic Course in Degrees
 189 - Type 54: GMT Time
 190 - Type 56: Date
 191 - Type 58: LAT/LON
 192 - Type 59: Set Count Down Timer (sent by ST60)
 193 - Type 65: Select Fathom display unit for depth display (see message 00)
 194 - Type 66: Wind Alarm
 195 - Type 6C: Second equipment-ID
 196 - Type 86: Keystroke
 197 - Type 87: Response Level
 198 - Type 89: Compass heading (sent by ST40 compass instrument)
 199
 200
 201 ### IO
 202
 203 - Reading data from serial ports (NMEA, SeaTalk)
 204
 205
 206 ### Geodesic Functions
 207
 208 Basic geodesic functions, suitable for martime navigation.
 209
 210 - Calculation of CPA (closest point of approach)
 211   and TCPA (time to closest point of approach)
 212 - Distance of two points on a sphere
 213 - Distance of two points on an ellipsoid using formula of Vincenty
 214 - Distance of two points on an ellipsoid using formula of Lambert
 215
 216
 217 ---
 218
 219 Examples
 220 --------
 221
 222 More examples [here](examples/README.md).
 223
 224 ### Parse NMEA Sentence
 225
 226 ~~~~~~~~~~~~~{.cpp}
 227 using namespace marnav;
 228
 229 auto sentence = nmea::make_sentence(
 230         "$GPRMC,201034,A,4702.4040,N,00818.3281,E,0.0,328.4,260807,0.6,E,A*17");
 231 std::cout << sentence->tag() << "\n";
 232 auto rmc = nmea::sentence_cast<nmea::rmc>(sentence);
 233 std::cout << "latitude : " << nmea::to_string(rmc->get_latitude()) << "\n";
 234 std::cout << "longitude: " << nmea::to_string(rmc->get_longitude()) << "\n";
 235 ~~~~~~~~~~~~~
 236
 237 Create a specific sentence directly:
 238
 239 ~~~~~~~~~~~~~{.cpp}
 240 using namespace marnav;
 241
 242 auto rmc = nmea::create_sentence<nmea::rmc>(
 243         "$GPRMC,201034,A,4702.4040,N,00818.3281,E,0.0,328.4,260807,0.6,E,A*17");
 244 std::cout << "latitude : " << nmea::to_string(rmc.get_latitude()) << "\n";
 245 std::cout << "longitude: " << nmea::to_string(rmc.get_longitude()) << "\n";
 246 ~~~~~~~~~~~~~
 247
 248 ### Write NMEA Sentence
 249
 250 ~~~~~~~~~~~~~{.cpp}
 251 nmea::mtw mtw;
 252 mtw.set_temperature(units::celsius{22.5});
 253 std::string data = nmea::to_string(mtw);
 254 ~~~~~~~~~~~~~
 255
 256 ### Parse AIS Message from NMEA data
 257
 258 ~~~~~~~~~~~~~{.cpp}
 259 using namespace marnav;
 260
 261 // received sentences
 262 const std::vector<std::string> received_strings
 263         = {"!AIVDM,2,1,3,B,55P5TL01VIaAL@7WKO@mBplU@<PDhh000000001S;AJ::4A80?4i@E53,0*3E",
 264                 "!AIVDM,2,2,3,B,1@0000000000000,2*55"};
 265
 266 // parse NMEA sentences
 267 std::vector<std::unique_ptr<nmea::sentence>> sentences;
 268 for (auto const & txt : received_strings) {
 269         auto sentence = nmea::make_sentence(txt);
 270         if (sentence->id() == nmea::sentence_id::VDM) {
 271                 sentences.push_back(std::move(sentence));
 272         }
 273 }
 274
 275 // parse and and process AIS messags
 276 auto payload = nmea::collect_payload(sentences.begin(), sentences.end());
 277 auto message = ais::make_message(payload);
 278 if (message->type() == ais::message_id::static_and_voyage_related_data) {
 279         auto report = ais::message_cast<ais::message_05>(message);
 280         std::cout << "shipname: " << report->get_shipname() << "\n";
 281         std::cout << "callsign: " << report->get_callsign() << "\n";
 282 }
 283 ~~~~~~~~~~~~~
 284
 285 ### Create NMEA sentences from AIS data
 286
 287 ~~~~~~~~~~~~~{.cpp}
 288 using namespace marnav;
 289
 290 // prepare AIS data
 291 ais::message_01 pos_report;
 292 pos_report.set_sog(units::knots{8.2});
 293 // ... most data not shown here
 294
 295 // create payload
 296 auto payload = ais::encode_message(pos_report);
 297
 298 // create NMEA sentences
 299 for (uint32_t fragment = 0; fragment < payload.size(); ++fragment) {
 300         nmea::vdm vdm;
 301         vdm.set_n_fragments(payload.size());
 302         vdm.set_fragment(fragment + 1);
 303         vdm.set_radio_channel(nmea::ais_channel::B);
 304         vdm.set_payload(payload[fragment]);
 305
 306         // collect, send or do something with the sentence...
 307         std::string s = nmea::to_string(vdm);
 308         std::cout << s << "\n";
 309 }
 310 ~~~~~~~~~~~~~
 311
 312 or simply use `nmea::make_vdms`:
 313
 314 ~~~~~~~~~~~~~{.cpp}
 315 using namespace marnav;
 316
 317 // prepare AIS data
 318 ais::message_01 pos_report;
 319 pos_report.set_sog(units::knots{8.2});
 320 // ... most data not shown here
 321
 322 // create payload
 323 auto payload = ais::encode_message(pos_report);
 324
 325 // create NMEA sentences
 326 auto sentences = nmea::make_vdms(payload);
 327
 328 // process sentences, somehow...
 329 for (auto const & sentence : sentences) {
 330         std::cout << nmea::to_string(*sentence) << "\n";
 331 }
 332 ~~~~~~~~~~~~~
 333
 334 ---
 335
 336 Requirements
 337 ------------
 338
 339 This chapter describes the requirements in order to build the library.
 340 Tools and their versions are listed below, newer/older/other tools
 341 (i.e. compilers, etc.) may work, but not tested.
 342
 343 Compiler:
 344 - GCC 4.9
 345 - GCC 5
 346 - GCC 6
 347 - GCC 7
 348 - GCC 8
 349 - GCC 9
 350 - GCC 10
 351 - Clang 4
 352 - Clang 5
 353 - Clang 6
 354 - Clang 7
 355 - Clang 8
 356 - Clang 9
 357 - Clang 10
 358 - Clang 11
 359 - Clang 12
 360
 361 Tools needed to build the library:
 362 - cmake 3.11 or newer
 363
 364 Tools needed to develop the library:
 365 - git
 366 - clang-format 3.9
 367
 368 Tools needed to build the documentation:
 369 - doxygen
 370 - graphviz
 371 - LaTeX (there are formulas!)
 372
 373 Optional used for development:
 374 - lcov / genhtml, c++filt
 375 - cppcheck
 376 - clang-tools (analyzer)
 377 - ctags, cscope
 378 - perf
 379
 380 Optional (no core dependency):
 381 - Boost.ASIO (used only for some examples)
 382 - Qt 5 (used only for some examples)
 383
 384 Opeating system:
 385 - Linux
 386
 387 There are no other dependencies despite the standard library (C++11)
 388 to build this library.
 389
 390 ---
 391
 392 Build
 393 -----
 394
 395 The following build types `-DCMAKE_BUILD_TYPE=x` are possible:
 396 - Debug
 397 - Release
 398 - Coverage
 399
 400 Build options:
 401 - `ENABLE_STATIC` : enables static build, if `OFF`, a shared library is being built.
 402   Default: `ON`
 403 - `ENABLE_PROFILING` : enables profiling for `gprof`
 404 - `ENABLE_BENCHMARK` : enables benchmarking (disables some optimization)
 405 - `ENABLE_SANITIZER` : enables address and undefined sanitizers
 406
 407 Features:
 408 - `ENABLE_IO` : enables IO support. Default: `ON`
 409
 410 Components:
 411 - `ENABLE_EXAMPLES`: enables examples. Default: `ON`
 412 - `ENABLE_TESTS`: enables unit tests, integration tests and benchmarks. Default: `ON`
 413 - `ENABLE_TOOLS`: enables tools. Default: `ON`
 414
 415
 416 ### Library
 417
 418         mkdir build
 419         cd build
 420         cmake -DCMAKE_BUILD_TYPE=Release ..
 421         make
 422
 423
 424 ### Documentation
 425
 426         mkdir build
 427         cd build
 428         cmake ..
 429         make doc
 430
 431
 432 ### Package
 433
 434         make package
 435
 436 or individual package types:
 437
 438         cpack -G TGZ
 439         cpack -G DEB
 440
 441
 442 ### Developpers Choice
 443
 444         mkdir build
 445         cd build
 446         cmake -DCMAKE_BUILD_TYPE=Coverage ..
 447         make -j 8
 448         make coverage doc cppcheck
 449
 450
 451 ### Static Analysis with Clang
 452
 453 There is a script ```bin/static-analysis-clang``` for doing this, there is not yet
 454 an integration of clang-tidy in the cmake build.
 455
 456
 457 ### Perform Benchmarks
 458
 459 Build in `Release` mode, perform individual benchmarks:
 460
 461         mkdir build
 462         cd build
 463         cmake -DCMAKE_BUILD_TYPE=Release ..
 464         make -j 8
 465         test/benchmark_nmea_split
 466
 467 Using `perf` to do performance analysis:
 468
 469         mkdir build
 470         cd build
 471         cmake -DCMAKE_BUILD_TYPE=Release -DENABLE_BENCHMARK=ON ..
 472         make -j 8
 473         perf record -g test/benchmark_nmea_split
 474         perf report -g 'graph,0.5,caller'
 475
 476
 477 ### Formatting Test
 478
 479 There is a helper script ```bin/check-format``` which uses ```clang-format``` to
 480 check the formatting of all files in the directories containing code (```src```,
 481 ```test``` and ```examples```). This script can be used manually:
 482
 483         bin/check-format
 484
 485 or used as git pre-commit hook:
 486
 487         cd .git/hooks
 488         ln -s ../../bin/check-format pre-commit
 489
 490 which prevents a commit if there are files not complying with the formatting
 491 rules. Be aware of using the script as pre-commit hook, the checking can take
 492 several seconds.
 493
 494
 495 ---
 496
 497 Authors
 498 -------
 499
 500 Mario Konrad (mario.konrad@gmx.net) with help from others.
 501
 502 Search the repository for a complete list:
 503
 504         git log --format=%an | sort -u
 505
 506 ---
 507
 508 Links
 509 -----
 510
 511 A (non-complete) collection of resources from where information was gathered.
 512
 513 - [NMEA Revealed](http://www.catb.org/gpsd/NMEA.html) (by Eric S. Raymond)
 514 - [NMEA FAQ](http://www.kh-gps.de/nmea.faq)
 515 - [it-digin's blog](http://www.it-digin.com/blog/?cat=4)
 516 - [AIVDM/AIVDO Protocol decoding](http://www.catb.org/gpsd/AIVDM.html) (by Eric S. Raymond)
 517 - [DSC Position Request](http://www.thehulltruth.com/marine-electronics-forum/43945-dsc-position-request.html)
 518 - [NMEA-0183 Sentences DSC,DSE](http://www.cruisersforum.com/forums/f13/nmea-0183-sentences-dsc-dse-124887.html)
 519 - [SerialMon - NMEA 0183 Protocol](http://www.serialmon.com/protocols/nmea0183.html)
 520 - [SeaTalk Reference](http://thomasknauf.de/seatalk.htm) (by Thomas Knauf)
 521 - [Navigation Center - AIS Standard Class B Equipment Position Report](http://www.navcen.uscg.gov/?pageName=AISMessagesB)
 522 - [GPS Forums](http://www.gps-forums.net)
 523 - [NMEA Datensaetze](http://www.nmea.de/nmea0183datensaetze.html)
 524 - [AIS VDM & VDO Message Decoder](http://www.maritec.co.za/tools/aisvdmvdodecoding/)
 525
 526 ---
 527
 528 LICENSE
 529 -------
 530
 531 > NOTE:
 532 > The official NMEA 0183 Standard document is not available for free. It was not
 533 > consulted at any point during the development of this library. All information
 534 > was found from free sources on the internet. This library (especially the NMEA
 535 > part) is not derivative work of this standard.
 536
 537
 538 See also [LICENSE](LICENSE)
 539
 540 (BSD)
 541
 542 ```
 543 Copyright (c) 2021, Mario Konrad
 544 All rights reserved.
 545
 546 Redistribution and use in source and binary forms, with or without
 547 modification, are permitted provided that the following conditions are met:
 548 1. Redistributions of source code must retain the above copyright
 549    notice, this list of conditions and the following disclaimer.
 550 2. Redistributions in binary form must reproduce the above copyright
 551    notice, this list of conditions and the following disclaimer in the
 552    documentation and/or other materials provided with the distribution.
 553 3. All advertising materials mentioning features or use of this software
 554    must display the following acknowledgement:
 555    This product includes software developed by Mario Konrad.
 556 4. Neither the name of the software nor the names of its contributors
 557    may be used to endorse or promote products derived from this software
 558    without specific prior written permission.
 559
 560 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 561 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 562 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 563 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
 564 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 565 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 566 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 567 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 568 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 569 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 570 ```
 571
 572