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