From 3e0aadfed6547b70f098c91c95768862aab13220 Mon Sep 17 00:00:00 2001 From: Morten Nielsen Date: Sat, 1 Feb 2020 17:09:20 -0800 Subject: [PATCH] Add more api ref doc describing how to use devices --- .gitignore | 1 + docs/BuildDoc.cmd | 1 - src/NmeaParser/BluetoothDevice.Android.cs | 14 +++++++++ src/NmeaParser/BluetoothDevice.UWP.cs | 36 ++++++++++++++++++++++ src/NmeaParser/SerialPortDevice.Desktop.cs | 17 ++++++++++ src/NmeaParser/SerialPortDevice.UWP.cs | 35 ++++++++++++++++++++- 6 files changed, 102 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index 72e061e..de4e000 100644 --- a/.gitignore +++ b/.gitignore @@ -113,3 +113,4 @@ project.lock.json src/.vs/ artifacts .tools +docs/memberpage.2.48.1 diff --git a/docs/BuildDoc.cmd b/docs/BuildDoc.cmd index 311da36..c35fb1c 100644 --- a/docs/BuildDoc.cmd +++ b/docs/BuildDoc.cmd @@ -21,7 +21,6 @@ mkdir %~dp0../artifacts/docs/api %~dp0..\.tools\omd\generateomd /source=%~dp0../src/NmeaParser /output=%~dp0../artifacts/docs/api/omd.html /preprocessors=NETSTANDARD1_4;NETSTANDARD %~dp0..\.tools\nuget install memberpage -Version 2.48.1 -OutputDirectory %~dp0 -PAUSE 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 %~dp0\docfx.json ECHO Fixing API Reference Links diff --git a/src/NmeaParser/BluetoothDevice.Android.cs b/src/NmeaParser/BluetoothDevice.Android.cs index bd61a62..53c15eb 100644 --- a/src/NmeaParser/BluetoothDevice.Android.cs +++ b/src/NmeaParser/BluetoothDevice.Android.cs @@ -25,6 +25,20 @@ namespace NmeaParser /// /// A Bluetooth NMEA device /// + /// + /// To use this device, ensure you have the necessary permissions in the AndroidManifest.xml file: + /// + /// ```xml + /// <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> + /// <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /> + /// <uses-permission android:name="android.permission.BLUETOOTH" /> + /// ``` + /// + /// + /// Next see MainActivity.cs in the Android sample as a reference: + /// https://github.com/dotMorten/NmeaParser/blob/master/src/SampleApp.Droid/MainActivity.cs + /// + /// public class BluetoothDevice : NmeaDevice { private static Java.Util.UUID SERIAL_UUID = Java.Util.UUID.FromString("00001101-0000-1000-8000-00805F9B34FB"); diff --git a/src/NmeaParser/BluetoothDevice.UWP.cs b/src/NmeaParser/BluetoothDevice.UWP.cs index 5f5025f..673d605 100644 --- a/src/NmeaParser/BluetoothDevice.UWP.cs +++ b/src/NmeaParser/BluetoothDevice.UWP.cs @@ -31,6 +31,42 @@ namespace NmeaParser /// /// A Bluetooth NMEA device /// + /// + /// To use the NMEA Parser against a bluetooth device in a Universal App, + /// ensure the bluetooth capability is enabled by opening package.appxmanifest in a text editor, + /// and add the following to the <Capabilities> section: + /// + /// <DeviceCapability Name="bluetooth.rfcomm"> + /// <Device Id="any"> + /// <Function Type="name:serialPort" /> + /// </Device> + /// </DeviceCapability> + /// + /// + /// See more here on bluetooth device capabilities in UWP Apps: https://docs.microsoft.com/en-us/uwp/schemas/appxpackage/how-to-specify-device-capabilities-for-bluetooth + /// + /// Make sure your Bluetooth device is paired with your Windows Device. + /// + /// //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 + /// } + /// + /// public class BluetoothDevice : NmeaDevice { private Windows.Devices.Bluetooth.Rfcomm.RfcommDeviceService? m_deviceService; diff --git a/src/NmeaParser/SerialPortDevice.Desktop.cs b/src/NmeaParser/SerialPortDevice.Desktop.cs index bb4e68c..daf8d79 100644 --- a/src/NmeaParser/SerialPortDevice.Desktop.cs +++ b/src/NmeaParser/SerialPortDevice.Desktop.cs @@ -25,6 +25,23 @@ namespace NmeaParser /// /// A Serial Port NMEA device /// + /// + /// Below is an example of connecting to a serial port using .NET Core or .NET Framework. + /// Make sure you choose the correct port name and baud rate. + /// + /// string portname = "COM3"; // Change to match the name of the port your device is connected to + /// int baudrate = 9600; // Change to the baud rate your device communicates at (usually specified in the manual) + /// var port = new System.IO.Ports.SerialPort(portname, baudrate); + /// var device = new NmeaParser.SerialPortDevice(port); + /// device.MessageReceived += OnNmeaMessageReceived; + /// device.OpenAsync(); + /// ... + /// private void OnNmeaMessageReceived(NmeaParser.NmeaDevice sender, NmeaParser.NmeaMessageReceivedEventArgs args) + /// { + /// // called when a message is received + /// } + /// + /// public class SerialPortDevice : NmeaDevice { /// diff --git a/src/NmeaParser/SerialPortDevice.UWP.cs b/src/NmeaParser/SerialPortDevice.UWP.cs index 5c5218f..8cdf2f4 100644 --- a/src/NmeaParser/SerialPortDevice.UWP.cs +++ b/src/NmeaParser/SerialPortDevice.UWP.cs @@ -23,10 +23,43 @@ using Windows.Devices.SerialCommunication; using System.Runtime.InteropServices.WindowsRuntime; namespace NmeaParser -{ +{ /// /// A Serial Port NMEA device /// + /// + /// + /// 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: + /// + /// + /// <DeviceCapability Name="serialcommunication"> + /// <Device Id="any"> + /// <Function Type="name:serialPort" /> + /// </Device> + /// </DeviceCapability> + /// + /// + /// 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 + /// } + /// + /// public class SerialPortDevice : NmeaDevice { private SerialDevice m_port;