Merge pull request #65 from dotMorten/docfx

Docfx

.gitignore

@@ -111,3 +111,4 @@ Tools/Nuget/*.nupkg
 src/NmeaParser.sln.ide/
 project.lock.json
 src/.vs/
+artifacts

build/DownloadDocFX.ps1

@@ -0,0 +1,18 @@
+[cmdletbinding()]
+param([string]$Version="2.48.1",[string]$Folder)
+Add-Type -AssemblyName System.IO.Compression.FileSystem
+[Net.ServicePointManager]::SecurityProtocol =[Net.SecurityProtocolType]::Tls12
+
+function DownloadDocFX([string]$version, [string]$folder)
+{
+   Write-Output "Using folder $folder"
+   $path = "$folder\v$version"
+   if (!(Test-Path $path)) 
+   {
+      New-Item -ItemType Directory -Force -Path $path
+      Write-Output "Downloading DocFX v$version..."
+      Invoke-WebRequest -Uri "https://github.com/dotnet/docfx/releases/download/v$version/docfx.zip" -OutFile "$folder\docfx_v$version.zip"
+      [System.IO.Compression.ZipFile]::ExtractToDirectory("$folder\docfx_v$version.zip",$path )
+   }
+}
+DownloadDocFX -version $Version -folder $Folder

build/GenerateDoc.cmd

@@ -0,0 +1,20 @@
+@ECHO OFF
+
+SET DocFXVersion=2.48.1
+SET DocFxFolder=..\artifacts\toolset
+
+REM Download DocFx
+powershell -ExecutionPolicy ByPass -command "./DownloadDocFX.ps1" -Version %DocFXVersion% -Folder %DocFxFolder%
+
+REM Build metadata for all platforms (uses configuration in docfx.json in this folder)
+%DocFxFolder%\v%DocFXVersion%\docfx.exe ..\docs\docfx.json metadata
+
+REM Merge output (not implemented)
+REM %DocFxFolder%\v%DocFXVersion%\docfx.exe merge
+
+REM Generate OMD
+dotnet tool install --global dotMorten.OmdGenerator
+generateomd /source=../src/NmeaParser /output=../artifacts/docs/api/omd.html
+
+REM Build the output site (HTML) from the generated metadata and input files (uses configuration in docfx.json in this folder)
+%DocFxFolder%\v%DocFXVersion%\docfx.exe ..\docs\docfx.json build

docs/.gitignore

@@ -0,0 +1,9 @@
+###############
+#    folder   #
+###############
+/**/DROP/
+/**/TEMP/
+/**/packages/
+/**/bin/
+/**/obj/
+_site

docs/Features.md

@@ -0,0 +1,15 @@
+# Features
+
+- Most common NMEA messages fully supported
+  - GNSS: BOD, GGA, GLL, GNS, GSA, GST, GSV, RMB, RMA, RMB, RMC, RTE, VTG, ZDA
+  - Garmin Proprietary: PGRME, PGRMZ
+  - Trimble Laser Range Finder: PTNLA, PTNLB
+  - TruePulse Laser Range Finder: PLTIT
+- Automatic merging of multi-sentence messages for simplified usage.
+- Extensible with custom NMEA messages [see here](concepts/CustomMessages.html)
+- Multiple input devices out of the box
+  - System.IO.Stream (all platforms)
+  - Emulation from NMEA log file (all platforms)
+  - Serial Device: .NET Framework, .NET Core (Windows, Linux, Mac) and Windows Universal.
+  - Bluetooth: Windows Universal and Android. .NET Core/.NET Framework is supported using the bluetooth device via the SerialPortDevice.
+

docs/api/android/index.md

@@ -0,0 +1,3 @@
+# NMEAParser API Reference
+
+Select an API from the menu on the left.

docs/api/index.md

@@ -0,0 +1,24 @@
+# Library reference
+
+**Select your platform:**
+
+- [.NET Standard API Reference](netstd/index.html)
+
+- [.NET Framework API Reference](netfx/index.html)
+
+- [.NET Core API Reference](netcore/index.html)
+
+- [UWP API Reference](uwp/index.html)
+
+- [Android API Reference](android/index.html)
+
+- [iOS API Reference](ios/index.html)
+
+### Object model diagram:
+
+[Click here](omd.html) to see the full object model diagram
+
+### Platform specific devices:
+
+Note: The library reference is identical on each platform, except some platforms have platform-specific additional NMEA devices to simplify usage on those platforms. While they may be named the same, they might be have slightly different or take different platform-specific arguments.
+See the menu in the "[Getting Started](../concepts/index.html)" section for more info on these.

docs/api/ios/index.md

@@ -0,0 +1,3 @@
+# NMEAParser API Reference
+
+Select an API from the menu on the left.

docs/api/netcore/index.md

@@ -0,0 +1,3 @@
+# NMEAParser API Reference
+
+Select an API from the menu on the left.

docs/api/netfx/index.md

@@ -0,0 +1,3 @@
+# NMEAParser API Reference
+
+Select an API from the menu on the left.

docs/api/netstd/index.md

@@ -0,0 +1,3 @@
+# NMEAParser API Reference
+
+Select an API from the menu on the left.

docs/api/uwp/index.md

@@ -0,0 +1,3 @@
+# NMEAParser API Reference
+
+Select an API from the menu on the left.

docs/concepts/ArcGISRuntime.md

@@ -0,0 +1,53 @@
+# Creating a location provider for ArcGIS Runtime SDK
+
+Below is an implementation for use with the [ArcGIS Runtime SDK for .NET](http://developers.arcgis.com/net). Use this location provider on the MapView's LocationDisplay to send it location data from your NMEA device to display your current location on a map.
+
+**Usage:**
+```csharp
+NmeaParser.NmeaDevice device = new NmeaParser.NmeaFileDevice("NmeaSampleData.txt");
+mapView.LocationDisplay.LocationProvider = new NmeaLocationProvider(device);
+mapView.LocationDisplay.IsEnabled = true;
+```
+
+**NmeaLocationProvider.cs**
+```csharp
+using System;
+using System.Threading.Tasks;
+using Esri.ArcGISRuntime.Geometry;
+using Esri.ArcGISRuntime.Location;
+
+namespace NmeaParser.ArcGIS
+{
+    public class NmeaLocationProvider : ILocationProvider
+    {
+        public event EventHandler<LocationInfo> LocationChanged;
+        private readonly NmeaParser.NmeaDevice device;
+
+        public NmeaLocationProvider(NmeaParser.NmeaDevice device)
+        {
+            this.device = device;
+            device.MessageReceived += device_MessageReceived;
+        }
+
+        void device_MessageReceived(object sender, NmeaParser.NmeaMessageReceivedEventArgs e)
+        {
+            var message = e.Message;
+            if (message is NmeaParser.Messages.Rmc rmc && rmc.Active)
+            {
+                LocationChanged?.Invoke(this, new LocationInfo()
+                {
+                    Course = rmc.Course,
+                    Speed = rmc.Speed,
+                    Location = new MapPoint(rmc.Longitude, rmc.Latitude, SpatialReferences.Wgs84)
+                });
+            }
+        }
+
+        public Task StartAsync() => device.OpenAsync();
+
+        public Task StopAsync() => device.CloseAsync();
+    }
+}
+
+```
+

docs/concepts/BluetoothAndroid.md

@@ -0,0 +1,3 @@
+# Creating a Bluetooth device in an Android app
+
+TODO...

docs/concepts/BluetoothUWP.md

@@ -0,0 +1,34 @@
+# Creating a Bluetooth device in a Windows Universal App
+
+To use the NMEA Parser against a bluetooth device in a Windows Store or Windows Phone WinRT/Universal App, ensure the bluetooth capability is enabled by opening package.appxmanifest in a text editor, and add the following to the `<Capabilities>` section:
+```xml
+    <DeviceCapability Name="bluetooth.rfcomm">
+      <Device Id="any">
+        <Function Type="name:serialPort" />
+      </Device>
+    </DeviceCapability>
+```
+See more here on bluetooth device capabilities in WinStore: http://msdn.microsoft.com/en-us/library/windows/apps/dn263090.aspx
+
+Make sure your Bluetooth device is paired with your Windows Device.
+
+```csharp
+//Get list of devices
+string serialDeviceType = RfcommDeviceService.GetDeviceSelector(RfcommServiceId.SerialPort);
+var devices = await DeviceInformation.FindAllAsync(serialDeviceType);
+//Select device by name (in this case TruePulse 360B Laser Range Finder)
+var TruePulse360B = devices.Where(t => t.Name.StartsWith("TP360B-")).FirstOrDefault();
+//Get service
+RfcommDeviceService rfcommService = await RfcommDeviceService.FromIdAsync(TruePulse360B.Id);
+if (rfcommService != null)
+{
+	var rangeFinder = new NmeaParser.BluetoothDevice(rfcommService);
+	rangeFinder.MessageReceived += device_NmeaMessageReceived;
+	await rangeFinder.OpenAsync();				
+}
+...
+private void device_NmeaMessageReceived(object sender, NmeaParser.NmeaMessageReceivedEventArgs args)
+{
+   // called when a message is received
+}
+```

docs/concepts/BluetoothiOS.md

@@ -0,0 +1,3 @@
+# Creating a Bluetooth device in an iOS app
+
+TODO...

docs/concepts/CustomMessages.md

@@ -0,0 +1,83 @@
+# Creating custom NMEA messages
+
+Custom NMEA messages can be registered for parsing as well.
+To create a new message, add the NmeaMessageType attribute to the class, and declare the 5-character message type.
+
+*Note: You can use `--` as the first two characters to make it independent of the Talker Type.*
+
+Next ensure you have a constructor that takes the `TypeName` string parameter first, and a second `string[]` parameter that will contain all the message values:
+
+
+Example:
+```cs
+    [NmeaMessageType("PTEST")]
+    public class CustomMessage : NmeaMessage
+    {
+        public CustomMessage(string type, string[] parameters) : base(type, parameters)
+        {
+            Value = parameters[0];
+        }
+        public string Value { get; }
+    }
+```
+
+Next register this with the NMEA Parser using either:
+
+```cs
+NmeaMessage.RegisterAssembly(typeof(CustomMessage).Assembly); //Registers all types in the provided assembly
+NmeaMessage.RegisterMessage(typeof(CustomMessage).GetTypeInfo());  //Registers a single NMEA message
+```
+
+Note that these methods will throw if the NMEA type has already been registers (there's an overload where you can declare the `replace` parameter to `true` to overwrite already registered messages.
+
+Next you should be able to test this method using the Parse method:
+```cs
+var input = "$PTEST,TEST*7C";
+var msg = NmeaMessage.Parse(input);
+```
+
+# Creating a multi-sentence message
+
+A NMEA message cannot exceed 82 characters, so often messages are split into multiple sentences. To create a custom multi message, either implement `IMultiSentenceMessage` or simply subclass `NmeaMultiSentenceMessage`.
+
+
+```cs
+[NmeaMessageType("PTST2")]
+private class CustomMultiMessage : NmeaMultiSentenceMessage, IMultiSentenceMessage
+{   
+    public CustomMultiMessage(string type, string[] parameters) : base(type, parameters)
+    {
+    }
+    public string Id { get; private set; }
+    public List<string> Values { get; } = new List<string>();
+	// Set index in the message where the total count is:
+    protected override int MessageCountIndex => 0;
+	// Set index in the message where the message number is:
+    protected override int MessageNumberIndex => 1;
+    protected override bool ParseSentences(Talker talkerType, string[] message)
+    {
+	    // Ensure this message matches the previous message.
+		// Use any indicator to detect message difference, so you can to error out and avoid
+		// appending the wrong message
+        if (Id == null)
+            Id = message[2]; //First time it's not set
+        else if (Id != message[2])
+            return false;
+        Values.AddRange(message.Skip(3));
+        return true;
+    }
+}
+```
+Note that the message is parsed in the `ParseSentences` method, and not the constructor. Also note that the talkerType is parsed to you, because multi-sentence messages allows a mix of talker types, if you use the `--` prefex in the NMEA type.
+
+Next we can parse the two messages and have the second one be appended to the first one:
+
+```cs
+NmeaMessage.RegisterNmeaMessage(typeof(CustomMultiMessage).GetTypeInfo());
+var input1 = "$PTST2,2,1,123,A,B,C,D*2A";
+var input2 = "$PTST2,2,2,123,E,F,G,H*21";
+var msg1 = NmeaMessage.Parse(input1);
+var msg2 = NmeaMessage.Parse(input2, msg1 as IMultiSentenceMessage);
+```
+
+If msg1 and msg2 aren't the same instance, it means the message couldn't be added to the previous message, and a new message was generated.

docs/concepts/SerialPortNetCore.md

@@ -0,0 +1,14 @@
+# Creating a Serial Port device in a .NET Core app
+
+```csharp
+var port = new System.IO.Ports.SerialPort("COM3", 9600); //change name and baud rage to match your serial port
+var device = new NmeaParser.SerialPortDevice(port);
+device.MessageReceived += device_NmeaMessageReceived;
+device.OpenAsync();
+...
+private void device_NmeaMessageReceived(NmeaParser.NmeaDevice sender, NmeaParser.NmeaMessageReceivedEventArgs args)
+{
+   // called when a message is received
+}								
+```
+

docs/concepts/SerialPortNetFX.md

@@ -0,0 +1,14 @@
+# Creating a Serial Port device in a .NET Framework
+
+```csharp
+var port = new System.IO.Ports.SerialPort("COM3", 9600); //change name and baud rage to match your serial port
+var device = new NmeaParser.SerialPortDevice(port);
+device.MessageReceived += device_NmeaMessageReceived;
+device.OpenAsync();
+...
+private void device_NmeaMessageReceived(NmeaParser.NmeaDevice sender, NmeaParser.NmeaMessageReceivedEventArgs args)
+{
+   // called when a message is received
+}								
+```
+

docs/concepts/SerialPortUWP.md

@@ -0,0 +1,32 @@
+# Creating a Serial Port device in a Windows Universal app
+
+To use the NMEA Parser against a serial device in a Windows 10 Universal app, ensure the serial device capability is enabled by opening package.appxmanifest in a text editor, and add the following to the `<Capabilities>` section:
+```xml
+    <DeviceCapability Name="serialcommunication" > 
+      <Device Id="any"> 
+        <Function Type="name:serialPort"/> 
+      </Device> 
+    </DeviceCapability> 
+```
+
+```csharp
+var selector = SerialDevice.GetDeviceSelector("COM3"); //Get the serial port on port '3'
+var devices = await DeviceInformation.FindAllAsync(selector);
+if(devices.Any()) //if the device is found
+{
+	var deviceInfo = devices.First();
+	var serialDevice = await SerialDevice.FromIdAsync(deviceInfo.Id);
+	//Set up serial device according to device specifications:
+	//This might differ from device to device
+	serialDevice.BaudRate = 4800;
+	serialDevice.DataBits = 8;
+	serialDevice.Parity = SerialParity.None;
+	var device = new NmeaParser.SerialPortDevice(serialDevice);
+	device.MessageReceived += device_NmeaMessageReceived;
+}
+...
+private void device_NmeaMessageReceived(NmeaParser.NmeaDevice sender, NmeaMessageReceivedEventArgs args)
+{
+   // called when a message is received
+}
+```

docs/concepts/index.md

@@ -0,0 +1,30 @@
+# Getting started:
+
+### 1. Install from NuGET:
+
+You can get the library via [NuGet](http://www.nuget.org) if you have the extension installed for Visual Studio or via the PowerShell package manager.  This control is published via NuGet at [SharpGIS.NmeaParser](https://nuget.org/packages/SharpGIS.NmeaParser).
+
+<table border="4px">
+<tr><td>
+            <code>PM&gt; Install-Package SharpGIS.NmeaParser</code>
+</td></tr></table>
+
+### 2. Create a new device:
+
+```cs
+ // Create one of the NMEA devices
+ var device = new NmeaFileDevice("PathToNmeaLogFile.txt", 1000);
+ // Listen to messages from the device: 
+ device.MessageReceived += device_NmeaMessageReceived;
+ // Open the device and start receiving:
+ device.OpenAsync();
+
+ // Create event handler for receiving messages:
+ private void device_NmeaMessageReceived(NmeaDevice sender, NmeaMessageReceivedEventArgs args)
+ {
+    // called when a message is received
+ }
+```
+See the Platform specific device creation section in the menu for more specifics on device creation.
+
+### 3. [Browse the API Reference](api/index.html)

docs/concepts/toc.yml

@@ -0,0 +1,30 @@
+- name: Getting Started
+  href: index.md
+- name: Platform specific device creation
+  items:
+  - name: .NET Framework
+    items:
+    - name: SerialPort
+      href: SerialPortNetFX.md
+  - name: .NET Framework
+    items:
+    - name: SerialPort
+      href: SerialPortNetCore.md
+  - name: UWP
+    items:
+    - name: SerialPort
+      href: SerialPortUWP.md
+    - name: Bluetooth
+      href: BluetoothUWP.md
+  - name: Android
+    items:
+    - name: Bluetooth
+      href: BluetoothAndroid.md
+  - name: iOS
+    items:
+    - name: Bluetooth
+      href: BluetoothiOS.md
+- name: Custom message types
+  href: CustomMessages.md
+- name: Creating a location provider for ArcGIS Runtime SDK
+  href: ArcGISRuntime.md

docs/docfx.json

@@ -0,0 +1,131 @@
+{
+  "metadata": [
+    {
+      "src": [
+        {
+          "files": [ "NmeaParser/NmeaParser.csproj" ],
+          "src" : "../src/"
+        },
+	  ],
+      "dest": "../artifacts/docs/api/netstd",
+      "properties": { "TargetFramework": "netstandard1.4" },
+      "disableGitFeatures": false,
+      "disableDefaultFilter": false
+    },
+	{ "src": [
+        {
+          "files": [ "NmeaParser/NmeaParser.csproj" ],
+          "src" : "../src/"
+        },
+	  ],
+      "dest": "../artifacts/docs/api/netfx",
+      "properties": { "TargetFramework": "net451" },
+      "disableGitFeatures": false,
+      "disableDefaultFilter": false
+    },
+	{ "src": [
+        {
+          "files": [ "NmeaParser/NmeaParser.csproj" ],
+          "src" : "../src/"
+        },
+	  ],
+      "dest": "../artifacts/docs/api/netcore",
+      "properties": { "TargetFramework": "netcoreapp2.1" },
+      "disableGitFeatures": false,
+      "disableDefaultFilter": false
+    },
+	{ "src": [
+        {
+          "files": [ "NmeaParser/NmeaParser.csproj" ],
+          "src" : "../src/"
+        },
+	  ],
+      "dest": "../artifacts/docs/api/android",
+      "properties": { "TargetFramework": "monoandroid70" },
+      "disableGitFeatures": false,
+      "disableDefaultFilter": false
+    },
+	{ "src": [
+        {
+          "files": [ "NmeaParser/NmeaParser.csproj" ],
+          "src" : "../src/"
+        },
+	  ],
+      "dest": "../artifacts/docs/api/ios",
+      "properties": { "TargetFramework": "xamarinios10" },
+      "disableGitFeatures": false,
+      "disableDefaultFilter": false
+    },
+	{ "src": [
+        {
+          "files": [ "NmeaParser/NmeaParser.csproj" ],
+          "src" : "../src/"
+        },
+	  ],
+      "dest": "../artifacts/docs/api/uwp",
+      "properties": { "TargetFramework": "uap10.0.16299" },
+      "disableGitFeatures": false,
+      "disableDefaultFilter": false
+    }
+  ],
+  "build": {
+    "content": [
+	{
+        "files": [
+          "api/**/index.md"
+        ]
+      },
+      {
+        "files": [
+          "api/**.yml",
+          "api/**/toc.yml"         
+        ],
+		"src" : "../artifacts/docs"
+      },
+      {
+        "files": [
+          "concepts/**.md",
+          "concepts/**/toc.yml",
+          "toc.yml",
+          "*.md"
+        ]
+      }
+    ],
+    "resource": [
+      {
+        "files": [
+          "images/**"
+        ]
+      },
+	   {
+        "files": [
+           "api/omd.html"
+        ],
+		"src" : "../artifacts/docs"
+      }
+    ],
+    "overwrite": [
+      {
+        "files": [
+          "apidoc/**.md"
+        ],
+        "exclude": [
+          "obj/**",
+          "_site/**"
+        ]
+      }
+    ],
+    "dest": "../artifacts/docs_site",
+    "globalMetadataFiles": [],
+    "fileMetadataFiles": [],
+    "template": [
+      "default"
+    ],
+    "postProcessors": [],
+    "markdownEngineName": "markdig",
+    "noLangKeyword": false,
+    "keepFileLink": false,
+    "cleanupCacheHistory": false,
+    "disableGitFeatures": false
+  }
+}

docs/index.md

@@ -0,0 +1,21 @@
+# NMEA Parser
+
+Library for reading and parsing NMEA data message streams. It makes it easy to connect and listen for NMEA messages
+coming from various devices in Windows Universal, Windows Desktop/.NET and Windows Universal apps as well
+as Xamarin for iOS and Android.
+
+
+## Sponsoring
+
+If you like this library and use it a lot, consider sponsoring me. Anything helps and encourages me to keep going.
+
+See here for details: https://github.com/sponsors/dotMorten
+
+
+## Getting started:
+
+Read the [Getting Started](concepts/index.html) notes
+
+
+![sampleapp2](https://cloud.githubusercontent.com/assets/1378165/5062460/10cc3064-6d77-11e4-8365-1e9c7c346afc.png)
+![sampleapp3](https://cloud.githubusercontent.com/assets/1378165/5062461/123adfc2-6d77-11e4-8573-1fe95fa0325f.png)

docs/toc.yml

@@ -0,0 +1,10 @@
+- name: Features
+  href: Features.md
+- name: Getting Started
+  href: concepts/index.md
+- name: API Reference
+  href: api/index.md
+- name: Sponsor NMEA Parser
+  href: https://github.com/sponsors/dotMorten
+- name: GitHub
+  href: https://github.com/dotMorten/NmeaParser