README.md

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