README.md

   1 marnav
   2 ======
   3
   4 Copyright (c) 2016 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++ (C++11 right now, C++14 as soon as compilers
  30   catch up, but not necessarily bleeding edge)
  31 - easy to use API (std lib like, integrating well)
  32 - unit tested (high test coverage)
  33 - trivial integration into projects (liberal license, as few dependencies as
  34   possible)
  35 - (more or less) well documented
  36 - (more or less) complete, as far as information is freely available
  37 - having fun
  38
  39 ---
  40
  41 Features
  42 --------
  43
  44 ### NMEA-0183
  45
  46 Supported sentences for NMEA-0183 (read and write):
  47 - AAM: Waypoint Arrival Alarm
  48 - ALM: GPS Almanac Data
  49 - APA: Autopilot Sentence "A"
  50 - APB: Autopilot Sentence "B"
  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 - MSK: Control for a Beacon Receiver
  78 - MSS: Beacon Receiver Status
  79 - MTW: Mean Temperature of Water
  80 - MWD: Wind Direction and Speed
  81 - MWV: Wind Speed and Angle
  82 - OSD: Own Ship Data
  83 - RMA: Recommended Minimum Navigation Information
  84 - RMB: Recommended Minimum Navigation Information
  85 - RMC: Recommended Minimum Navigation Information
  86 - ROT: Rate Of Turn
  87 - RPM: Revolutions
  88 - RSA: Rudder Sensor Angle
  89 - RSD: RADAR System Data (**experimental**)
  90 - RTE: Routes
  91 - SFI: Scanning Frequency Information
  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
 130 ### AIS
 131
 132 Supported messages for AIS (decode and encode):
 133 - Type 01: Position Report Class A
 134 - Type 02: Position Report Class A (Assigned Schedule)
 135 - Type 03: Position Report Class A (Response to Interrogation)
 136 - Type 04: Base Station Report
 137 - Type 05: Static and Voyage Related Data
 138 - Type 09: Standard SAR Aircraft Position Report
 139 - Type 10: UTC/Date Inquiry
 140 - Type 11: UTC/Date Response
 141 - Type 18: Standard Class B CS Position Report
 142 - Type 19: Extended Class B CS Position Report
 143 - Type 21: Aid-to-Navigation Report
 144 - Type 22: Channel Management
 145 - Type 23: Group Assignment Command
 146 - Type 24: Static Data Report (part A and B, norma and auxiliary vessel)
 147
 148
 149 ### SeaTalk
 150
 151 Suported messages for SeaTalk (decode and encode):
 152 - Type 00: depth below transducer
 153 - Type 01: equipment id
 154 - Type 05: Engine RPM and PITCH
 155 - Type 10: apparent wind angle
 156 - Type 11: apparent wind speed
 157 - Type 20: speed through water
 158 - Type 21: trip mileage
 159 - Type 22: total mileage
 160 - Type 23: water temperature 1
 161 - Type 24: Display unit for Mileage and Speed
 162 - Type 25: total and trip log
 163 - Type 26: Speed through Water
 164 - Type 27: water temperature 2
 165 - Type 30: Set Lamp Intensity
 166 - Type 36: Cancel MOB condition
 167 - Type 38: Codelock data (**experimental**)
 168 - Type 50: LAT Postion
 169 - Type 51: LON Postion
 170 - Type 52: Speed over Ground
 171 - Type 53: Magnetic Course in Degrees
 172 - Type 54: GMT Time
 173 - Type 56: Date
 174 - Type 58: LAT/LON
 175 - Type 59: Set Count Down Timer (sent by ST60)
 176 - Type 65: Select Fathom display unit for depth display (see message 00)
 177 - Type 66: Wind Alarm
 178 - Type 6C: Second equipment-ID
 179 - Type 86: Keystroke
 180 - Type 87: Response Level
 181 - Type 89: Compass heading (sent by ST40 compass instrument)
 182
 183
 184 ### IO
 185
 186 - Reading data from serial ports (NMEA, SeaTalk)
 187
 188
 189 ### Geodesic Functions
 190
 191 Basic geodesic functions, suitable for martime navigation.
 192
 193 - Calculation of CPA (closest point of approach)
 194   and TCPA (time to closest point of approach)
 195 - Distance of two points on a sphere
 196 - Distance of two points on an ellipsoid using formula of Vincenty
 197 - Distance of two points on an ellipsoid using formula of Lambert
 198
 199
 200 ---
 201
 202 Examples
 203 --------
 204
 205 More examples [here](doc/examples.md).
 206
 207 ### Parse NMEA Sentence
 208
 209 ~~~~~~~~~~~~~{.cpp}
 210 using namespace marnav;
 211
 212 auto sentence = nmea::make_sentence(
 213         "$GPRMC,201034,A,4702.4040,N,00818.3281,E,0.0,328.4,260807,0.6,E,A*17");
 214 std::cout << sentence->tag() << "\n";
 215 auto rmc = nmea::sentence_cast<nmea::rmc>(sentence);
 216 std::cout << "latitude : " << nmea::to_string(rmc->get_latitude()) << "\n";
 217 std::cout << "longitude: " << nmea::to_string(rmc->get_longitude()) << "\n";
 218 ~~~~~~~~~~~~~
 219
 220 Create a specific sentence directly:
 221
 222 ~~~~~~~~~~~~~{.cpp}
 223 using namespace marnav;
 224
 225 auto rmc = nmea::create_sentence<nmea::rmc>(
 226         "$GPRMC,201034,A,4702.4040,N,00818.3281,E,0.0,328.4,260807,0.6,E,A*17");
 227 std::cout << "latitude : " << nmea::to_string(rmc.get_latitude()) << "\n";
 228 std::cout << "longitude: " << nmea::to_string(rmc.get_longitude()) << "\n";
 229 ~~~~~~~~~~~~~
 230
 231 ### Write NMEA Sentence
 232
 233 ~~~~~~~~~~~~~{.cpp}
 234 nmea::mtw mtw;
 235 mtw.set_temperature(22.5);
 236 std::string data = nmea::to_string(mtw);
 237 ~~~~~~~~~~~~~
 238
 239 ### Parse AIS Message from NMEA data
 240
 241 ~~~~~~~~~~~~~{.cpp}
 242 using namespace marnav;
 243
 244 // received sentences
 245 const std::vector<std::string> received_strings
 246         = {"!AIVDM,2,1,3,B,55P5TL01VIaAL@7WKO@mBplU@<PDhh000000001S;AJ::4A80?4i@E53,0*3E",
 247                 "!AIVDM,2,2,3,B,1@0000000000000,2*55"};
 248
 249 // parse NMEA sentences
 250 std::vector<std::unique_ptr<nmea::sentence>> sentences;
 251 for (auto const & txt : received_strings) {
 252         auto sentence = nmea::make_sentence(txt);
 253         if (sentence->id() == nmea::sentence_id::VDM) {
 254                 sentences.push_back(std::move(sentence));
 255         }
 256 }
 257
 258 // parse and and process AIS messags
 259 auto payload = nmea::collect_payload(sentences.begin(), sentences.end());
 260 auto message = ais::make_message(payload);
 261 if (message->type() == ais::message_id::static_and_voyage_related_data) {
 262         auto report = ais::message_cast<ais::message_05>(message);
 263         std::cout << "shipname: " << report->get_shipname() << "\n";
 264         std::cout << "callsign: " << report->get_callsign() << "\n";
 265 }
 266 ~~~~~~~~~~~~~
 267
 268 ### Create NMEA sentences from AIS data
 269
 270 ~~~~~~~~~~~~~{.cpp}
 271 using namespace marnav;
 272
 273 // prepare AIS data
 274 ais::message_01 pos_report;
 275 pos_report.set_sog(82);
 276 // ... most data not shown here
 277
 278 // create payload
 279 auto payload = ais::encode_message(pos_report);
 280
 281 // create NMEA sentences
 282 for (uint32_t fragment = 0; fragment < payload.size(); ++fragment) {
 283         nmea::vdm vdm;
 284         vdm.set_n_fragments(payload.size());
 285         vdm.set_fragment(fragment + 1);
 286         vdm.set_radio_channel(nmea::ais_channel::B);
 287         vdm.set_payload(payload[fragment]);
 288
 289         // collect, send or do something with the sentence...
 290         std::string s = nmea::to_string(vdm);
 291         std::cout << s << "\n";
 292 }
 293 ~~~~~~~~~~~~~
 294
 295 or simply use `nmea::make_vdms`:
 296
 297 ~~~~~~~~~~~~~{.cpp}
 298 using namespace marnav;
 299
 300 // prepare AIS data
 301 ais::message_01 pos_report;
 302 pos_report.set_sog(82);
 303 // ... most data not shown here
 304
 305 // create payload
 306 auto payload = ais::encode_message(pos_report);
 307
 308 // create NMEA sentences
 309 auto sentences = nmea::make_vdms(payload);
 310
 311 // process sentences, somehow...
 312 for (auto const & sentence : sentences) {
 313         std::cout << nmea::to_string(*sentence) << "\n";
 314 }
 315 ~~~~~~~~~~~~~
 316
 317 ---
 318
 319 Requirements
 320 ------------
 321
 322 This chapter describes the requirements in order to build the library.
 323 Tools and their versions are listed below, newer/older/other tools
 324 (i.e. compilers, etc.) may work, but not tested.
 325
 326 Compiler:
 327 - GCC 4.9
 328 - GCC 5
 329 - GCC 6
 330 - Clang 3.6
 331 - Clang 3.7
 332 - Clang 3.8
 333 - Clang 3.9
 334
 335 Tools needed to build the library:
 336 - cmake 3.2 or newer
 337
 338 Tools needed to develop the library:
 339 - git
 340 - clang-format 3.9
 341
 342 Tools needed to build the documentation:
 343 - doxygen
 344 - graphviz
 345 - LaTeX (there are formulas!)
 346
 347 Optional used for development:
 348 - lcov / genhtml, c++filt
 349 - cppcheck
 350 - clang-analyze 3.9
 351 - ctags, cscope
 352 - perf
 353
 354 Optional (no core dependency):
 355 - Boost.ASIO (used only for some examples)
 356 - Qt 5 (used only for some examples)
 357
 358 Opeating system:
 359 - Linux
 360
 361 There are no other dependencies despite the standard library (C++11)
 362 to build this library.
 363
 364 ---
 365
 366 Build
 367 -----
 368
 369 The following build types `-DCMAKE_BUILD_TYPE=x` are possible:
 370 - Debug
 371 - Release
 372 - Coverage
 373
 374 Build options:
 375 - `ENABLE_STATIC` : enables static build, if `OFF`, a shared library is being built.
 376   Default: `ON`
 377 - `ENABLE_WARNING_HELL` : enables _much_ more warnings, used for development purposes.
 378   Currently implemented only for GCC.  Default is `OFF`
 379 - `ENABLE_PROFILING` : enables profiling for `gprof`
 380 - `ENABLE_BENCHMARK` : enables benchmarking (disables some optimization)
 381 - `ENABLE_SANITIZER` : enables address and undefined sanitizers
 382
 383 Features:
 384 - `ENABLE_AIS ` : enables AIS support. Default: `ON`
 385 - `ENABLE_SEATALK` : enables SeaTalk support. Default: `ON`
 386 - `ENABLE_IO` : enables IO support. Default: `ON`
 387
 388
 389 ### Library
 390
 391         mkdir build
 392         cd build
 393         cmake -DCMAKE_BUILD_TYPE=Release ..
 394         make
 395
 396
 397 ### Documentation
 398
 399         mkdir build
 400         cd build
 401         cmake ..
 402         make doc
 403
 404
 405 ### Package
 406
 407         make package
 408
 409 or individual package types:
 410
 411         cpack -G TGZ
 412         cpack -G DEB
 413
 414
 415 ### Developpers Choice
 416
 417         mkdir build
 418         cd build
 419         cmake -DCMAKE_BUILD_TYPE=Coverage -DENABLE_WARNING_HELL=YES ..
 420         make -j 8
 421         make coverage doc cppcheck
 422
 423
 424 ### Static Analysis with Clang
 425
 426 There is a script ```bin/static-analysis-clang``` for doing this, or do it manually:
 427
 428         mkdir build
 429         cd build
 430         cmake -DCMAKE_CXX_COMPILER=/usr/share/clang/scan-build-3.9/libexec/c++-analyzer ..
 431         scan-build-3.9 -o doc/analysis --use-analyzer=/usr/bin/clang++-3.9 make
 432
 433 After the build, ```scan-build``` will tell you what to do in order to inspect
 434 the findings.
 435
 436
 437 ### Perform Benchmarks
 438
 439 Build in `Release` mode, perform individual benchmarks:
 440
 441         mkdir build
 442         cd build
 443         cmake -DCMAKE_BUILD_TYPE=Release ..
 444         make -j 8
 445         test/benchmark_nmea_split
 446
 447 Using `perf` to do performance analysis:
 448
 449         mkdir build
 450         cd build
 451         cmake -DCMAKE_BUILD_TYPE=Release -DENABLE_BENCHMARK=ON ..
 452         make -j 8
 453         perf record -g test/benchmark_nmea_split
 454         perf report -g 'graph,0.5,caller'
 455
 456
 457 ### Formatting Test
 458
 459 There is a helper script ```bin/check-format``` which uses ```clang-format``` to
 460 check the formatting of all files in the directories containing code (```src```,
 461 ```test``` and ```examples```). This script can be used manually:
 462
 463         bin/check-format
 464
 465 or used as git pre-commit hook:
 466
 467         cd .git/hooks
 468         ln -s ../../bin/check-format pre-commit
 469
 470 which prevents a commit if there are files not complying with the formatting
 471 rules. Be aware of using the script as pre-commit hook, the checking can take
 472 several seconds.
 473
 474
 475 ---
 476
 477 Authors
 478 -------
 479
 480 Mario Konrad (mario.konrad@gmx.net) with help from others.
 481
 482 Search the repository for a complete list:
 483
 484         git log --format=%an | sort -u
 485
 486 ---
 487
 488 Links
 489 -----
 490
 491 A (non-complete) collection of resources from where information was gathered.
 492
 493 - [NMEA Revealed](http://www.catb.org/gpsd/NMEA.html) (by Eric S. Raymond)
 494 - [NMEA FAQ](http://www.kh-gps.de/nmea.faq)
 495 - [it-digin's blog](http://www.it-digin.com/blog/?cat=4)
 496 - [AIVDM/AIVDO Protocol decoding](http://www.catb.org/gpsd/AIVDM.html) (by Eric S. Raymond)
 497 - [DSC Position Request](http://www.thehulltruth.com/marine-electronics-forum/43945-dsc-position-request.html)
 498 - [NMEA-0183 Sentences DSC,DSE](http://www.cruisersforum.com/forums/f13/nmea-0183-sentences-dsc-dse-124887.html)
 499 - [SerialMon - NMEA 0183 Protocol](http://www.serialmon.com/protocols/nmea0183.html)
 500 - [SeaTalk Reference](http://thomasknauf.de/seatalk.htm) (by Thomas Knauf)
 501 - [Navigation Center - AIS Standard Class B Equipment Position Report](http://www.navcen.uscg.gov/?pageName=AISMessagesB)
 502 - [GPS Forums](http://www.gps-forums.net)
 503 - [NMEA Datensaetze](http://www.nmea.de/nmea0183datensaetze.html)
 504 - [AIS VDM & VDO Message Decoder](http://www.maritec.co.za/tools/aisvdmvdodecoding/)
 505
 506 ---
 507
 508 LICENSE
 509 -------
 510
 511 > NOTE:
 512 > The official NMEA 0183 Standard document is not available for free. It was not
 513 > consulted at any point during the development of this library. All information
 514 > was found from free sources on the internet. This library (especially the NMEA
 515 > part) is not derivative work of this standard.
 516
 517
 518 See also [LICENSE](LICENSE)
 519
 520 (BSD)
 521
 522 ```
 523 Copyright (c) 2016, Mario Konrad
 524 All rights reserved.
 525
 526 Redistribution and use in source and binary forms, with or without
 527 modification, are permitted provided that the following conditions are met:
 528 1. Redistributions of source code must retain the above copyright
 529    notice, this list of conditions and the following disclaimer.
 530 2. Redistributions in binary form must reproduce the above copyright
 531    notice, this list of conditions and the following disclaimer in the
 532    documentation and/or other materials provided with the distribution.
 533 3. All advertising materials mentioning features or use of this software
 534    must display the following acknowledgement:
 535    This product includes software developed by Mario Konrad.
 536 4. Neither the name of the software nor the names of its contributors
 537    may be used to endorse or promote products derived from this software
 538    without specific prior written permission.
 539
 540 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 541 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 542 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 543 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
 544 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 545 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 546 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 547 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 548 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 549 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 550 ```
 551
 552