README.md

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