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