Merge pull request #62 from WildernessLabs/develop

RC2

.github/workflows/ci-develop-push.yml

@@ -1,4 +1,4 @@
-name: CI Develop Push Build
+name: Develop Build
 
 on:
   workflow_dispatch:

README.md

@@ -1,9 +1,12 @@
+<img src="Design/banner.jpg" style="margin-bottom:10px" />
+
 # Meadow.Contracts
 
-This repository contains the interfaces used by Core Meadow implementations.  It requires Meadow.Units and Meadow.Logging.
+[![Develop Branch](https://github.com/WildernessLabs/Meadow.Contracts/actions/workflows/ci-develop-push.yml/badge.svg)](https://github.com/WildernessLabs/Meadow.Contracts/actions/workflows/ci-develop-push.yml)
 
-Please clone Meadow.Units and Meadow.Logging as siblings to resolve solution dependency.
 
-## Repo Status
+This repository contains the interfaces used by Core Meadow implementations.
 
-[![Develop Branch](https://github.com/WildernessLabs/Meadow.Contracts/actions/workflows/ci-develop-push.yml/badge.svg)](https://github.com/WildernessLabs/Meadow.Contracts/actions/workflows/ci-develop-push.yml)
+It has a dependency of the following of two other repos you will need to clone/download to successfully build this solution:
+* [Meadow.Units](https://github.com/WildernessLabs/Meadow.Units)
+* [Meadow.Logging](https://github.com/WildernessLabs/Meadow.Logging)

Source/Meadow.Contracts/Gateways/WiFi/NetworkCapabilities.cs

@@ -1,13 +1,15 @@
 namespace Meadow
 {
+
     public class NetworkCapabilities
     {
         public bool HasWiFi { get; protected set; }
         public bool HasEthernet { get; protected set; }
 
         public NetworkCapabilities(
             bool hasWifi,
-            bool hasEthernet) {
+            bool hasEthernet)
+        {
             this.HasWiFi = hasWifi;
             this.HasEthernet = hasEthernet;
         }

Source/Meadow.Contracts/Hardware/AnalogCapabilities.cs

@@ -1,8 +1,19 @@
 using System;
+
 namespace Meadow
 {
+    /// <summary>
+    /// Provides a description of the Analog I/O capabilities of a platform
+    /// </summary>
     public class AnalogCapabilities
     {
+        protected int? _maxRawAdcVoltageValue;
+
+        /// <summary>
+        /// Creates an AnalogCapabilities instance
+        /// </summary>
+        /// <param name="hasAdc"></param>
+        /// <param name="adcResolution"></param>
         public AnalogCapabilities(
             bool hasAdc,
             int? adcResolution
@@ -12,18 +23,32 @@ public AnalogCapabilities(
             this.AdcResolution = adcResolution;
         }
 
+        /// <summary>
+        /// Returns true if the platofm has an analog-to-digital converter
+        /// </summary>
         public bool HasAdc { get; protected set; }
+        /// <summary>
+        /// Returns the bit-resolution of the ADC
+        /// </summary>
         public int? AdcResolution { get; protected set; }
-        public int? MaxRawAdcVoltageValue {
-            get {
-                if (_maxRawAdcVoltageValue != null) {
+        /// <summary>
+        /// Returns the maximum voltage the ADC supports
+        /// </summary>
+        public int? MaxRawAdcVoltageValue
+        {
+            get
+            {
+                if (_maxRawAdcVoltageValue != null)
+                {
                     return _maxRawAdcVoltageValue;
-                } else {
+                }
+                else
+                {
                     _maxRawAdcVoltageValue = (int?)Math.Pow(2, (double)(AdcResolution ?? 1));
                     return _maxRawAdcVoltageValue;
                 }
             }
-        } protected int? _maxRawAdcVoltageValue;
+        }
     }
 }
 

Source/Meadow.Contracts/Hardware/DeviceCapabilities.cs

@@ -1,17 +1,38 @@
 namespace Meadow
 {
+    /// <summary>
+    /// A set of capabilities of the current Device
+    /// </summary>
     public class DeviceCapabilities
     {
+        /// <summary>
+        /// Network capabilities of the current Device
+        /// </summary>
         public NetworkCapabilities Network { get; protected set; }
+        /// <summary>
+        /// Analog I/O capabilities of the current Device
+        /// </summary>
         public AnalogCapabilities Analog { get; protected set; }
+        /// <summary>
+        /// Storage capabilities of the current Device
+        /// </summary>
+        public StorageCapabilities Storage { get; protected set; }
 
+        /// <summary>
+        /// Creates an instance of a DeviceCapabilities class
+        /// </summary>
+        /// <param name="analog"></param>
+        /// <param name="network"></param>
+        /// <param name="storage"></param>
         public DeviceCapabilities(
             AnalogCapabilities analog,
-            NetworkCapabilities network
+            NetworkCapabilities network,
+            StorageCapabilities storage
             )
         {
             this.Network = network;
             this.Analog = analog;
+            this.Storage = storage;
         }
     }
 }

Source/Meadow.Contracts/Hardware/DigitalPortResult.cs

@@ -11,6 +11,11 @@ public struct DigitalPortResult : IChangeResult<DigitalState>
         public DigitalState New { get; set; }
         public DigitalState? Old { get; set; }
 
+        /// <summary>
+        /// Creates an instance of a DigitialPortResult
+        /// </summary>
+        /// <param name="newState"></param>
+        /// <param name="oldState"></param>
         public DigitalPortResult(DigitalState newState, DigitalState? oldState)
         {
             New = newState;
@@ -20,7 +25,8 @@ public DigitalPortResult(DigitalState newState, DigitalState? oldState)
         /// The duration of time in between the time the event or notification
         /// ocurred, and the the time it occurred before.
         /// </summary>
-        public TimeSpan? Delta {
+        public TimeSpan? Delta
+        {
             get => New.Time - Old?.Time;
         }
     }

Source/Meadow.Contracts/Hardware/DigitalState.cs

@@ -16,6 +16,11 @@ public struct DigitalState
         /// </summary>
         public DateTime Time { get; set; }
 
+        /// <summary>
+        /// Creates an instance of a DigitalState
+        /// </summary>
+        /// <param name="state"></param>
+        /// <param name="time"></param>
         public DigitalState(bool state, DateTime time)
         {
             State = state;

Source/Meadow.Contracts/Hardware/IPowerController.cs

@@ -43,5 +43,7 @@ public void Sleep(DateTime wakeTime)
 
             Sleep(wakeTime - DateTime.UtcNow);
         }
+
+        void RegisterForSleep(ISleepAwarePeripheral peripheral);
     }
 }

Source/Meadow.Contracts/Hardware/Networking/INetworkAdapter.cs

@@ -9,12 +9,20 @@ namespace Meadow.Hardware
     /// <param name="sender"></param>
     /// <param name="args"></param>
     public delegate void NetworkConnectionHandler(INetworkAdapter sender, NetworkConnectionEventArgs args);
+
     /// <summary>
     /// Delegate containing information about a network disconnection event
     /// </summary>
     /// <param name="sender"></param>
     public delegate void NetworkDisconnectionHandler(INetworkAdapter sender);
 
+    /// <summary>
+    /// Delegate containing information about a network error event.
+    /// </summary>
+    /// <param name="sender">Object sending this error</param>
+    /// <param name="args">Error codes and information about the error.</param>
+    public delegate void NetworkErrorHandler(INetworkAdapter sender, NetworkErrorEventArgs args);
+
     /// <summary>
     /// Base interface for a network adapter
     /// </summary>
@@ -24,11 +32,17 @@ public interface INetworkAdapter
         /// Event raised when a network is connected
         /// </summary>
         event NetworkConnectionHandler NetworkConnected;
+
         /// <summary>
         /// Event raised when a network is disconnected
         /// </summary>
         event NetworkDisconnectionHandler NetworkDisconnected;
 
+        /// <summary>
+        /// Event raised on an unexpected network error.
+        /// </summary>
+        event NetworkErrorHandler NetworkError;
+
         /// <summary>
         /// Indicate if the network adapter is connected to an access point.
         /// </summary>

Source/Meadow.Contracts/Hardware/Networking/INetworkAdapterCollection.cs

@@ -7,9 +7,14 @@ public interface INetworkAdapterCollection : IEnumerable<INetworkAdapter>
     {
         INetworkAdapter this[int index] { get; }
 
-        public T Primary<T>() where T : INetworkAdapter
+        /// <summary>
+        /// Retrieves the first registered INetworkAdapter matching the requested type
+        /// </summary>
+        /// <typeparam name="T"></typeparam>
+        /// <returns></returns>
+        public T? Primary<T>() where T : INetworkAdapter
         {
-            return this.OfType<T>().First();
+            return this.OfType<T>().FirstOrDefault();
         }
     }
 }

Source/Meadow.Contracts/Hardware/Networking/INetworkAdapterController.cs

@@ -1,10 +1,22 @@
 namespace Meadow.Hardware
 {
+    /// <summary>
+    /// A contract for Meadow devices that support network interfaces
+    /// </summary>
     public interface INetworkAdapterController
     {
+        /// <summary>
+        /// The event raised when a network adapter has connected to a network
+        /// </summary>
         event NetworkConnectionHandler NetworkConnected;
+        /// <summary>
+        /// The event raised when a network adapter has disconnected from a network
+        /// </summary>
         event NetworkDisconnectionHandler NetworkDisconnected;
 
+        /// <summary>
+        /// A collection of network adapters
+        /// </summary>
         INetworkAdapterCollection NetworkAdapters { get; }
     }
 }

Source/Meadow.Contracts/Hardware/Networking/IWiFiNetworkAdapter.cs

@@ -49,8 +49,7 @@ public interface IWiFiNetworkAdapter : IWirelessNetworkAdapter
         /// <param name="token">Cancellation token for the connection attempt</param>
         /// <param name="reconnection">Should the adapter reconnect automatically?</param>
         /// <exception cref="ArgumentNullException">Thrown if the ssid is null or empty or the password is null.</exception>
-        /// <returns>true if the connection was successfully made.</returns>
-        Task<ConnectionResult> Connect(string ssid, string password, TimeSpan timeout, CancellationToken token, ReconnectionType reconnection = ReconnectionType.Automatic);
+        Task Connect(string ssid, string password, TimeSpan timeout, CancellationToken token, ReconnectionType reconnection = ReconnectionType.Automatic);
 
         /// <summary>
         /// Start a WiFi network.
@@ -59,11 +58,10 @@ public interface IWiFiNetworkAdapter : IWirelessNetworkAdapter
         /// <param name="password">Password for the network.</param>
         /// <param name="reconnection">Should the adapter reconnect automatically?</param>
         /// <exception cref="ArgumentNullException">Thrown if the ssid is null or empty or the password is null.</exception>
-        /// <returns>true if the connection was successfully made.</returns>
-        async Task<ConnectionResult> Connect(string ssid, string password, ReconnectionType reconnection = ReconnectionType.Automatic)
+        async Task Connect(string ssid, string password, ReconnectionType reconnection = ReconnectionType.Automatic)
         {
             var src = new CancellationTokenSource();
-            return await Connect(ssid, password, TimeSpan.Zero, src.Token, reconnection);
+            await Connect(ssid, password, TimeSpan.Zero, src.Token, reconnection);
         }
 
         /// <summary>
@@ -74,11 +72,10 @@ async Task<ConnectionResult> Connect(string ssid, string password, ReconnectionT
         /// <param name="token">Cancellation token for the connection attempt</param>
         /// <param name="reconnection">Should the adapter reconnect automatically?</param>
         /// <exception cref="ArgumentNullException">Thrown if the ssid is null or empty or the password is null.</exception>
-        /// <returns>true if the connection was successfully made.</returns>
-        async Task<ConnectionResult> Connect(string ssid, string password, CancellationToken token, ReconnectionType reconnection = ReconnectionType.Automatic)
+        async Task Connect(string ssid, string password, CancellationToken token, ReconnectionType reconnection = ReconnectionType.Automatic)
         {
             var src = new CancellationTokenSource();
-            return await Connect(ssid, password, TimeSpan.Zero, token, reconnection);
+            await Connect(ssid, password, TimeSpan.Zero, token, reconnection);
         }
 
         /// <summary>
@@ -89,11 +86,10 @@ async Task<ConnectionResult> Connect(string ssid, string password, CancellationT
         /// <param name="timeout">Timeout period for the connection attempt</param>
         /// <param name="reconnection">Should the adapter reconnect automatically?</param>
         /// <exception cref="ArgumentNullException">Thrown if the ssid is null or empty or the password is null.</exception>
-        /// <returns>true if the connection was successfully made.</returns>
-        async Task<ConnectionResult> Connect(string ssid, string password, TimeSpan timeout, ReconnectionType reconnection = ReconnectionType.Automatic)
+        async Task Connect(string ssid, string password, TimeSpan timeout, ReconnectionType reconnection = ReconnectionType.Automatic)
         {
             var src = new CancellationTokenSource();
-            return await Connect(ssid, password, timeout, src.Token, reconnection);
+            await Connect(ssid, password, timeout, src.Token, reconnection);
         }
 
         /// <summary>
@@ -103,11 +99,9 @@ async Task<ConnectionResult> Connect(string ssid, string password, TimeSpan time
         /// <param name="password">Password for the network.</param>
         /// <param name="timeout">Timeout period for the connection attempt</param>
         /// <param name="token">Cancellation token for the connection attempt</param>
-        /// <returns>true if the connection was successfully made.</returns>
-        async Task<ConnectionResult> Connect(string ssid, string password, TimeSpan timeout, CancellationToken token)
+        async Task Connect(string ssid, string password, TimeSpan timeout, CancellationToken token)
         {
-            var src = new CancellationTokenSource();
-            return await Connect(ssid, password, TimeSpan.Zero, token, ReconnectionType.Automatic);
+            await Connect(ssid, password, timeout, token, ReconnectionType.Automatic);
         }
 
         /// <summary>
@@ -116,10 +110,9 @@ async Task<ConnectionResult> Connect(string ssid, string password, TimeSpan time
         /// <param name="ssid">Name of the network to connect to.</param>
         /// <param name="password">Password for the network.</param>
         /// <param name="timeout">Timeout period for the connection attempt</param>
-        /// <returns>true if the connection was successfully made.</returns>
-        async Task<ConnectionResult> Connect(string ssid, string password, TimeSpan timeout)
+        async Task Connect(string ssid, string password, TimeSpan timeout)
         {
-            return await Connect(ssid, password, timeout, CancellationToken.None);
+            await Connect(ssid, password, timeout, CancellationToken.None);
         }
 
         /// <summary>
@@ -128,9 +121,9 @@ async Task<ConnectionResult> Connect(string ssid, string password, TimeSpan time
         /// <param name="ssid">Name of the network to connect to.</param>
         /// <param name="password">Password for the network.</param>
         /// <returns>true if the connection was successfully made.</returns>
-        async Task<ConnectionResult> Connect(string ssid, string password)
+        async Task Connect(string ssid, string password)
         {
-            return await Connect(ssid, password, TimeSpan.FromSeconds(90), CancellationToken.None);
+            await Connect(ssid, password, TimeSpan.FromSeconds(90), CancellationToken.None);
         }
 
         /// <summary>
@@ -141,7 +134,18 @@ async Task<ConnectionResult> Connect(string ssid, string password)
         /// the disconnection from the current access point.
         /// </remarks>
         /// <param name="turnOffWiFiInterface">Should the WiFi interface be turned off?</param>
-        Task<ConnectionResult> Disconnect(bool turnOffWiFiInterface);
+        Task Disconnect(bool turnOffWiFiInterface);
+
+        /// <summary>
+        /// Connect to the default access point.
+        /// </summary>
+        /// <remarks>The access point credentials should be stored in the coprocessor memory.</remarks>
+        void ConnectToDefaultAccessPoint();
+
+        /// <summary>
+        /// Removed any stored access point information from the coprocessor memory.
+        /// </summary>
+        Task ClearStoredAccessPointInformation();
 
         /// <summary>
         /// Get the list of access points.

Source/Meadow.Contracts/Hardware/Networking/NetworkErrorEventArgs.cs

@@ -0,0 +1,29 @@
+using System;
+
+namespace Meadow.Hardware
+{
+    /// <summary>
+    /// Data relating to a WiFi error event.
+    /// </summary>
+    public class NetworkErrorEventArgs : EventArgs
+    {
+        /// <summary>
+        /// Date and time the event was generated.
+        /// </summary>
+        public DateTime When { get; private set; }
+
+        /// <summary>
+        /// Error code.
+        /// </summary>
+        public uint ErrorCode { get; private set; }
+
+        /// <summary>
+        /// Construct a NetworkErrorEventArgs object.
+        /// </summary>
+        public NetworkErrorEventArgs(uint code)
+        {
+            When = DateTime.Now;
+            ErrorCode = code;
+        }
+    }
+}