Examples: minor cleanup
[marnav.git] / README.md
blob309bdbed755fd5289d16c2e8b2ed409d0c82e22f
1 marnav
2 ======
4 [![Build Status](https://travis-ci.org/mariokonrad/marnav.svg?branch=master)](https://travis-ci.org/mariokonrad/marnav)
6 Copyright (c) 2016 Mario Konrad (mario.konrad@gmx.net)
8 ---
10 Abstract
11 --------
13 This is a C++ library for **MAR**itime **NAV**igation purposes.
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.
22 See chapter _Features_ for a complete and detailed list.
24 ---
26 Goals
27 -----
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
41 ---
43 Features
44 --------
46 ### NMEA-0183
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
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
124 Vendor Extensions:
125 - PGRME: Garmin Estimated Error
128 ### AIS
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)
147 ### SeaTalk
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)
182 ### IO
184 - Reading data from serial ports (NMEA, SeaTalk)
187 ### Geodesic Functions
189 Basic geodesic functions, suitable for martime navigation.
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
200 Examples
201 --------
203 More examples [here](doc/examples.md).
205 ### Parse NMEA Sentence
207 ~~~~~~~~~~~~~{.cpp}
208 using namespace marnav;
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 ~~~~~~~~~~~~~
218 ### Write NMEA Sentence
220 ~~~~~~~~~~~~~{.cpp}
221 nmea::mtw mtw;
222 mtw.set_temperature(22.5);
223 std::string data = nmea::to_string(mtw);
224 ~~~~~~~~~~~~~
226 ### Parse AIS Message from NMEA data
228 ~~~~~~~~~~~~~{.cpp}
229 using namespace marnav;
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"};
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         }
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";
253 ~~~~~~~~~~~~~
255 ### Create NMEA sentences from AIS data
257 ~~~~~~~~~~~~~{.cpp}
258 using namespace marnav;
260 // prepare AIS data
261 ais::message_01 pos_report;
262 pos_report.set_sog(82);
263 // ... most data not shown here
265 // create payload
266 auto payload = ais::encode_message(pos_report);
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]);
276         // collect, send or do something with the sentence...
277         std::string s = nmea::to_string(vdm);
278         std::cout << s << "\n";
280 ~~~~~~~~~~~~~
282 or simply use `nmea::make_vdms`:
284 ~~~~~~~~~~~~~{.cpp}
285 using namespace marnav;
287 // prepare AIS data
288 ais::message_01 pos_report;
289 pos_report.set_sog(82);
290 // ... most data not shown here
292 // create payload
293 auto payload = ais::encode_message(pos_report);
295 // create NMEA sentences
296 auto sentences = nmea::make_vdms(payload);
298 // process sentences, somehow...
299 for (auto const & sentence : sentences) {
300         std::cout << nmea::to_string(*sentence) << "\n";
302 ~~~~~~~~~~~~~
306 Requirements
307 ------------
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.
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
323 Tools needed to build the library:
324 - cmake 3.2
326 Tools needed to develop the library:
327 - git
328 - clang-format 3.7
330 Tools needed to build the documentation:
331 - doxygen
332 - graphviz
333 - LaTeX (there are formulas!)
335 Optional used for development:
336 - lcov / genhtml, c++filt
337 - cppcheck
338 - clang-analyze 3.7
339 - ctags, cscope
340 - perf
342 Optional (no core dependency):
343 - Boost.ASIO (used only for some examples)
344 - Qt 5 (used only for some examples)
346 Opeating system:
347 - Linux
349 There are no other dependencies despite the standard library (C++11)
350 to build this library.
354 Build
355 -----
357 The following build types `-DCMAKE_BUILD_TYPE=x` are possible:
358 - Debug
359 - Release
360 - Coverage
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)
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`
376 ### Library
378         mkdir build
379         cd build
380         cmake -DCMAKE_BUILD_TYPE=Release ..
381         make
384 ### Documentation
386         mkdir build
387         cd build
388         cmake ..
389         make doc
392 ### Package
394         make package
396 or individual package types:
398         cpack -G TGZ
399         cpack -G DEB
402 ### Developpers Choice
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
411 ### Static Analysis with Clang
413 There is a script ```bin/static-analysis-clang``` for doing this, or do it manually:
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
420 After the build, ```scan-build``` will tell you what to do in order to inspect
421 the findings.
424 ### Perform Benchmarks
426 Build in `Release` mode, perform individual benchmarks:
428         mkdir build
429         cd build
430         cmake -DCMAKE_BUILD_TYPE=Release ..
431         make -j 8
432         test/benchmark_nmea_split
434 Using `perf` to do performance analysis:
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'
444 ### Formatting Test
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:
450         bin/check-format
452 or used as git pre-commit hook:
454         cd .git/hooks
455         ln -s ../../bin/check-format pre-commit
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.
464 Authors
465 -------
467 Mario Konrad (mario.konrad@gmx.net) with help from others.
469 Search the repository for a complete list:
471         git log --format=%an | sort -u
475 Links
476 -----
478 A (non-complete) collection of resources from where information was gathered.
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/)
495 LICENSE
496 -------
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.
505 See also [LICENSE](LICENSE)
507 (BSD)
510 Copyright (c) 2016, Mario Konrad
511 All rights reserved.
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.
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.