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