Skip to content

Commit afb133b

Browse files
elpielelpiel
authoredDec 26, 2024
Merge pull request #141 from AeroRust/docs/document-features
Docs: document features
2 parents 0b2163a + c748443 commit afb133b

40 files changed

+321
-364
lines changed
 

‎Cargo.lock

+16
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Cargo.toml

+85-55
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ serde = { version = "1.0", default-features = false, optional = true }
4444
serde_with = { version = "~3.11", default-features = false, optional = true }
4545

4646
defmt = { version = "0.3", optional = true }
47+
document-features = { version = "0.2", optional = true }
4748

4849
[dev-dependencies]
4950
approx = "0.5"
@@ -53,8 +54,11 @@ quickcheck = { version = "1", default-features = false }
5354
serde_json = "1.0"
5455

5556
[features]
57+
## Default features: `std` & `all-sentences`
5658
default = ["std", "all-sentences"]
59+
## Enable the `std` (standard library) usage
5760
std = ["nom/std", "chrono/std", "arrayvec/std", "serde?/std", "serde_with?/std"]
61+
## Enable derives for (De)Serialization with `serde`
5862
serde = [
5963
"serde/derive",
6064
"serde_with/macros",
@@ -64,127 +68,153 @@ serde = [
6468
"arrayvec/serde"
6569
]
6670

71+
## Enable derives of `defmt@0.3` formatting for embedded platforms
6772
defmt-03 = ["dep:defmt", "heapless/defmt-03"]
6873

74+
## Enable the documentation of features (disabled by default to remove unnecessary to the functionality dependencies)
75+
features-docs = ["dep:document-features"]
76+
77+
#! ## Sentences features
78+
## Enable all sentences
6979
all-sentences = ["GNSS", "waypoint", "maritime", "water", "vendor-specific", "other"]
70-
# GNSS specific sentences related to the possition or speed relative to the ground
71-
GNSS = ["APA", "ALM", "GBS", "GGA", "GLL", "GNS", "GSA", "GST", "GSV", "RMC", "VTG"]
7280

81+
#! ### Categorised features
82+
83+
## GNSS specific sentences related to the position or speed relative to the ground
84+
GNSS = ["APA", "ALM", "GBS", "GGA", "GLL", "GNS", "GSA", "GST", "GSV", "RMC", "VTG"]
85+
## Waypoint
7386
waypoint = ["AAM", "BOD", "BWC", "BWW", "WNC", "ZFO", "ZTG"]
87+
## Maritime
7488
maritime = ["waypoint", "water", "radar"]
89+
## Radar
7590
radar = ["TTM"]
76-
water = ["DBK", "DPT", "MTW", "VHW"]
91+
## Water
92+
water = ["DBK", "DBS", "DPT", "MTW", "VHW"]
93+
## Vendor-specific messages
7794
vendor-specific = ["RMZ"]
95+
## Other
7896
other = ["HDT", "MDA", "MWV", "TXT", "ZDA"]
7997

80-
# AAM - Waypoint Arrival Alarm
81-
# feature: waypoint
98+
#! ### Supported sentences (alphabetically ordered)
99+
100+
## Waypoint Arrival Alarm
101+
## (feature: `waypoint`)
82102
AAM = []
83103

84-
# ALM - GPS Almanac Data
85-
# feature: GNSS
104+
## GPS Almanac Data
105+
## (feature: `GNSS`)
86106
ALM = []
87107

88-
# APA - Autopilot Sentence "A"
89-
# feature: GNSS
108+
## Autopilot Sentence "A"
109+
## (feature: `GNSS`)
90110
APA = []
91111

92-
# BOD - Bearing - Waypoint to Waypoint
93-
# feature: waypoint
112+
## Bearing - Waypoint to Waypoint
113+
## (feature: `waypoint`)
94114
BOD = []
95115

96-
# BWC - Bearing & Distance to Waypoint - Great Circle
97-
# feature: waypoint
116+
## Bearing & Distance to Waypoint - Great Circle
117+
## (feature: `waypoint`)
98118
BWC = []
99119

100-
# BWW - Bearing - Waypoint to Waypoint
101-
# feature: waypoint
120+
## Bearing - Waypoint to Waypoint
121+
## (feature: `waypoint`)
102122
BWW = []
103123

104-
# DBK - Depth Below Keel
105-
# feature: water
124+
## Depth Below Keel
125+
## (feature: `water`)
106126
DBK = []
107127

108-
# DPT - Depth of Water
109-
# feature: water
128+
## Depth Below Surface
129+
## (feature: `water`)
130+
DBS = []
131+
132+
## Depth of Water
133+
## (feature: `water`)
110134
DPT = []
111135

112-
# GBS - GPS Satellite Fault Detection
113-
# feature: GNSS
136+
## GPS Satellite Fault Detection
137+
## (feature: `GNSS`)
114138
GBS = []
115139

116-
# GGA - Global Positioning System Fix Data
117-
# feature: GNSS
140+
## * Global Positioning System Fix Data
141+
## (feature: `GNSS`)
118142
GGA = []
119143

120-
# GLL - Geographic Position - Latitude/Longitude
121-
# feature: GNSS
144+
## * Geographic Position - Latitude/Longitude
145+
## (feature: `GNSS`)
122146
GLL = []
123147

124-
# GNS - Fix data
125-
# feature: GNSS
148+
## * Fix data
149+
## (feature: `GNSS`)
126150
GNS = []
127151

128-
# GSA - GPS DOP and active satellites
129-
# feature: GNSS
152+
## * GPS DOP and active satellites
153+
## (feature: `GNSS`)
130154
GSA = []
131155

132-
# GST - GPS Pseudorange Noise Statistics
133-
# feature: GNSS
156+
## GPS Pseudorange Noise Statistics
157+
## (feature: `GNSS`)
134158
GST = []
135159

136-
# GSV - Satellites in view
137-
# feature: GNSS
160+
## * Satellites in view
161+
## (feature: `GNSS`)
138162
GSV = []
139163

140-
# HDT - Heading - True
164+
## Heading - True
165+
## (feature: `other`)
141166
HDT = []
142167

143-
# MDA - Meterological Composite
168+
## Meterological Composite
169+
## (feature: `other`)
144170
MDA = []
145171

146-
# MTW - Mean Temperature of Water
147-
# feature: water
172+
## Mean Temperature of Water
173+
## (feature: `water`)
148174
MTW = []
149175

150-
# MWV - Wind Speed and Angle
176+
## Wind Speed and Angle
177+
## (feature: `other`)
151178
MWV = []
152179

153-
# RMC - Recommended Minimum Navigation Information
154-
# feature: GNSS
180+
## * Recommended Minimum Navigation Information
181+
## (feature: `GNSS`)
155182
RMC = []
156183

157-
# PGRMZ - Garmin Altitude (Vendor specific)
158-
# feature: vendor-specific
184+
## PGRMZ - Garmin Altitude (Vendor specific)
185+
## (feature: `vendor-specific`)
159186
RMZ = []
160187

161-
# TTM - Tracked target message
188+
## Tracked target message
189+
## (feature: `radar`)
162190
TTM = []
163191

164-
# TXT - Text message
192+
## * Text message
193+
## (feature: `other`)
165194
TXT = []
166195

167-
# VHW - Water speed and heading
168-
# feature: water
196+
## Water speed and heading
197+
## (feature: `water`)
169198
VHW = []
170199

171-
# VTG - Track made good and Ground speed
172-
# feature: GNSS
200+
## * Track made good and Ground speed
201+
## (feature: `GNSS`)
173202
VTG = []
174203

175-
# WNC - Distance - Waypoint to waypoint
176-
# feature: waypoint
204+
## Distance - Waypoint to waypoint
205+
## (feature: `waypoint`)
177206
WNC = []
178207

179-
# ZDA - Time & Date - UTC, day, month, year and local time zone
208+
## Time & Date - UTC, day, month, year and local time zone
209+
## (feature: `other`)
180210
ZDA = []
181211

182-
# ZFO - UTC & Time from origin Waypoint
183-
# feature: waypoint
212+
## UTC & Time from origin Waypoint
213+
## (feature: `waypoint`)
184214
ZFO = []
185215

186-
# ZTG - UTC & Time to Destination Waypoint
187-
# feature: waypoint
216+
## UTC & Time to Destination Waypoint
217+
## (feature: `waypoint`)
188218
ZTG = []
189219

190220
[[test]]

‎README.md

+46-44
Original file line numberDiff line numberDiff line change
@@ -6,48 +6,41 @@
66

77
[Complete documentation can be found on www.docs.rs/nmea][doc]
88

9-
## NMEA 0183 sentence parser for Rust.
10-
11-
Supported sentences:
12-
13-
NMEA Standard Sentences
14-
15-
- AAM
16-
- ALM
17-
- APA
18-
- BOD
19-
- BWC
20-
- BWW
21-
- DBK
22-
- DBS
23-
- DPT
24-
- GBS
25-
- GGA \*
26-
- GLL \*
27-
- GNS \*
28-
- GSA \*
29-
- GST
30-
- GSV \*
31-
- HDT
32-
- MDA
33-
- MTW
34-
- MWV
35-
- RMC \*
36-
- TTM
37-
- VHW
38-
- VTG \*
39-
- WNC
40-
- ZDA
41-
- ZFO
42-
- ZTG
43-
44-
Other Sentences
45-
46-
- TXT \*
47-
48-
Vendor Extensions
49-
50-
- PGRMZ
9+
## NMEA 0183 sentence parser
10+
11+
Supported sentences (alphabetically ordered):
12+
13+
14+
- `AAM` - Waypoint Arrival Alarm (feature: `waypoint`)
15+
- `ALM` - GPS Almanac Data (feature: `GNSS`)
16+
- `APA` - Autopilot Sentence "A" (feature: `GNSS`)
17+
- `BOD` - Bearing - Waypoint to Waypoint (feature: `waypoint`)
18+
- `BWC` - Bearing & Distance to Waypoint - Great Circle (feature: `waypoint`)
19+
- `BWW` - Bearing - Waypoint to Waypoint (feature: `waypoint`)
20+
- `DBK` - Depth Below Keel (feature: `water`)
21+
- `DBS` - Depth Below Surface (feature: `water`)
22+
- `DPT` - Depth of Water (feature: `water`)
23+
- `GBS` - GPS Satellite Fault Detection (feature: `GNSS`)
24+
- `GGA` - * Global Positioning System Fix Data (feature: `GNSS`)
25+
- `GLL` - * Geographic Position - Latitude/Longitude (feature: `GNSS`)
26+
- `GNS` - * Fix data (feature: `GNSS`)
27+
- `GSA` - * GPS DOP and active satellites (feature: `GNSS`)
28+
- `GST` - GPS Pseudorange Noise Statistics (feature: `GNSS`)
29+
- `GSV` - * Satellites in view (feature: `GNSS`)
30+
- `HDT` - Heading - True (feature: `other`)
31+
- `MDA` - Meterological Composite (feature: `other`)
32+
- `MTW` - Mean Temperature of Water (feature: `water`)
33+
- `MWV` - Wind Speed and Angle (feature: `other`)
34+
- `RMC` - * Recommended Minimum Navigation Information (feature: `GNSS`)
35+
- `RMZ` - PGRMZ - Garmin Altitude (feature: `vendor-specific`)
36+
- `TTM` - Tracked target message (feature: `radar`)
37+
- `TXT` - * Text message (feature: `other`)
38+
- `VHW` - Water speed and heading (feature: `water`)
39+
- `VTG` - * Track made good and Ground speed (feature: `GNSS`)
40+
- `WNC` - Distance - Waypoint to waypoint (feature: `waypoint`)
41+
- `ZDA` - Time & Date - UTC, day, month, year and local time zone (feature: `other`)
42+
- `ZFO` - UTC & Time from origin Waypoint (feature: `waypoint`)
43+
- `ZTG` - UTC & Time to Destination Waypoint (feature: `waypoint`)
5144

5245
**\* [`Nmea::parse()`] supported sentences**
5346

@@ -59,10 +52,19 @@ We have an ongoing effort to support as many sentences from `NMEA 0183` as possi
5952
starting with the most well-known.
6053
If you'd like to contribute by writing a parser for a given message, check out the [Supporting additional sentences (AeroRust/nmea#54)](https://github.com/AeroRust/nmea/issues/54) issue and contribute in **3** easy steps:
6154

62-
1. Write a comment - Please write a comment in the issue for the sentence(s) you'd like to implement, you will be mentioned on the task to avoid duplicate implementations.
63-
2. Implement each sentence alongside at least 1 test in its own module under the [`./src/sentences`](./src/sentences) directory using the `nom` crate.
55+
1. Write a comment in the issue for the sentence(s) you'd like to implement, you will be mentioned on the task to avoid duplicate efforts.
56+
2. Implement each sentence in it's own branch alongside:
57+
- At least **2 tests** (**1 passing** and **1 failing**) in its own module under the [`./src/sentences`](./src/sentences) directory using the `nom` crate.
58+
- Re-export the structures and parsing function in [`./src/sentences.rs`](./src/sentences.rs)
59+
- Add a **passing** test to [`tests/all_supported_messages.rs`](./tests/all_supported_messages.rs)
60+
- Add the sentence to the features list in `Cargo.toml` in **alphabetical order** and assign it to proper category (if you are unsure which category to use, open a PR to discuss it)
61+
- Add the sentence to the `README.md` list of [supported sentences above](./README.md#nmea-0183-sentence-parser-for-rust)
62+
- Passing linters checks. Just run `cargo fmt` and fix any issues raised by `cargo clippy`
63+
- Appropriate documentation following the rest of the sentences format. For proper documentation you can take a look at `GSV`, `APA` and `WNC` sentences.
6464
3. Open a PR 🎉
6565

66+
**NB:** We use [https://gpsd.gitlab.io/gpsd/NMEA.html](https://gpsd.gitlab.io/gpsd/NMEA.html) as a reference for most sentences as it's a very well documented project.
67+
6668
## What is NMEA 0183?
6769

6870
> NMEA 0183 is a combined electrical and data specification for communication

0 commit comments

Comments
 (0)