Rework 1-Wire implementation (#84)

.github/workflows/update-dependencies.yml

@@ -29,4 +29,4 @@ jobs:
       - name: Update dependencies
         uses: nanoframework/nanodu@v1
         with:
-          solutionsToCheck: 'nanoFramework.Devices.OneWire.sln'
+          solutionsToCheck: 'nanoFramework.Device.OneWire.sln'

.gitignore

@@ -253,3 +253,6 @@ paket-files/
 
 #SoundCloud
 *.sonarqube/
+
+#VSCode
+.vscode/*

README.md

@@ -4,7 +4,7 @@
 
 -----
 
-### Welcome to the .NET **nanoFramework** 1-Wire Class Library repository
+# Welcome to the .NET **nanoFramework** 1-Wire® Class Library repository
 
 ## Build status
 
@@ -13,6 +13,64 @@
 | nanoFramework.Device.OneWire | [![Build Status](https://dev.azure.com/nanoframework/nanoFramework.Device.OneWire/_apis/build/status/nanoframework.nanoFramework.Devices.OneWire?repoName=nanoframework%2FnanoFramework.Device.OneWire&branchName=main)](https://dev.azure.com/nanoframework/nanoFramework.Device.OneWire/_build/latest?definitionId=15&repoName=nanoframework%2FnanoFramework.Device.OneWire&branchName=main) | [![NuGet](https://img.shields.io/nuget/v/nanoFramework.Device.OneWire.svg?label=NuGet&style=flat&logo=nuget)](https://www.nuget.org/packages/nanoFramework.Device.OneWire/) |
 | nanoFramework.Device.OneWire (preview) | [![Build Status](https://dev.azure.com/nanoframework/nanoFramework.Device.OneWire/_apis/build/status/nanoframework.nanoFramework.Devices.OneWire?repoName=nanoframework%2FnanoFramework.Device.OneWire&branchName=develop)](https://dev.azure.com/nanoframework/nanoFramework.Device.OneWire/_build/latest?definitionId=15&repoName=nanoframework%2FnanoFramework.Device.OneWire&branchName=develop) | [![NuGet](https://img.shields.io/nuget/vpre/nanoFramework.Device.OneWire.svg?label=NuGet&style=flat&logo=nuget)](https://www.nuget.org/packages/nanoFramework.Device.OneWire/) |
 
+## 1-Wire® bus
+
+1-Wire® it's a communication protocol, property of Maxim Semiconductor. You can read the technical details about it on [this guide](https://www.maximintegrated.com/en/design/technical-documents/tutorials/1/1796.html).
+
+## .NET nanoFramework implementation
+
+Our low level implementation of the 1-Wire communication uses an UART to achieve precise timing with the less possible burden on the MCU.
+For that reason it requires an UART and shunting together it's RX and TX pins. Depending on the bus length and impedance it may be required connecting an external pull-up resistor to provide the necessary signalling for 1-Wire communication.
+
+**Important**: If you're using an ESP32 device it's mandatory to configure the UART2 pins before creating the `OneWireHost`. To do that, you have to add a reference to [`nanoFramework.Hardware.ESP32`](https://www.nuget.org/packages/nanoFramework.Hardware.Esp32). In the code snnipet below we're assigning GPIOs 16 and 17 to UART2.
+
+```csharp
+//////////////////////////////////////////////////////////////////////
+// Configure pins 16 and 17 to be used in UART2
+Configuration.SetPinFunction(16, DeviceFunction.COM2_RX);
+Configuration.SetPinFunction(17, DeviceFunction.COM2_TX);
+```
+
+For other devices, like STM32 ones, there is no need to configure the GPIO pins. You have to find in the respective device documentation what are the UART pins used for 1-Wire.
+
+## Usage examples
+
+To connect to a 1-Wire bus and perform operations with the connected devices, one has to first instantiate the OneWireHost.
+
+```csharp
+OneWireHost _OneWireHost = new OneWireHost();
+```
+
+To find the first device connected to the 1-Wire bus, and perform a reset on the bus before performing the search, the following call should be made:
+
+```csharp
+_OneWireHost.FindFirstDevice(true, false);
+```
+
+To write a byte with the value 0x44 to the connected device:
+
+```csharp
+_OneWireHost.WriteByte(0x44);
+```
+
+To get a list with the serial number of all the 1-Wire devices connected to the bus:
+
+```csharp
+var deviceList = _OneWireHost.FindAllDevices();
+
+foreach(byte[] device in deviceList)
+{
+    string serial = "";
+
+    foreach (byte b in device)
+    {
+        serial += b.ToString("X2");
+    }
+
+    Console.WriteLine($"{serial}");
+}
+```
+
 ## Feedback and documentation
 
 For documentation, providing feedback, issues and finding out how to contribute please refer to the [Home repo](https://github.com/nanoframework/Home).

nanoFramework.Device.OneWire/OneWireHost.cs

@@ -10,17 +10,52 @@ using System.Runtime.CompilerServices;
 namespace nanoFramework.Device.OneWire
 {
     /// <summary>
-    /// Represents a 1-Wire bus controller. The class provides methods and properties that an application can use to interact with the 1-Wire bus and connected devices.
+    /// Initializes a new instance of the <see cref="OneWireHost"/> class.
+    /// Represents a 1-Wire host. The class provides methods that an application can use to interact with the 1-Wire bus and connected devices.
     /// </summary>
-    public class OneWireController
+    public class OneWireHost : IDisposable
     {
+        // flag to signal that an instance of the class has been created
+        private static bool s_opened = false;
+
         // this is used as the lock object 
-        // a lock is required because multiple threads can access the SerialDevice
-        private object _syncLock = new object();
+        // a lock is required because multiple threads can access the FindAllDevices method
+        private readonly object _syncLock;
 
         // this is the backing field for the serial number on discovery or when performing a read/write operation
         // need to create it here to be used in native
-        private byte[] _serialNumber = new byte[8];
+        private byte[] _serialNumber;
+
+        private bool _disposed;
+
+        // external One Wire functions from link layer owllu.c
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="OneWireHost"/> class.
+        /// </summary>
+        /// <exception cref="InvalidOperationException">If there is already another instance of the <see cref="OneWireHost"/> class.</exception>
+        public OneWireHost()
+        {
+            if (!s_opened)
+            {
+                _disposed = false;
+
+                NativeInit();
+
+                // flag that we have this open and initialized
+                s_opened = true;
+
+                // create lock object
+                _syncLock = new();
+
+                // create array for serial number
+                _serialNumber = new byte[8];
+            }
+            else
+            {
+                throw new InvalidOperationException();
+            }
+        }
 
         /// <summary>
         /// Reset all of the devices on the 1-Wire Net and return the result.
@@ -149,8 +184,61 @@ namespace nanoFramework.Device.OneWire
                     result = FindNextDevice(true, false);
                 }
 
+
+                foreach(byte[] device in serialNumbers)
+                {
+                    string serial = "";
+
+                    foreach (byte b in device)
+                    {
+                        serial += b.ToString("X2");
+                    }
+
+                    Console.WriteLine($"{serial}");
+                }
+
                 return serialNumbers;
             }
         }
+
+        #region Dispose
+
+        /// <inheritdoc/>
+        protected virtual void Dispose(bool disposing)
+        {
+            if (!_disposed)
+            {
+                NativeDispose();
+
+                _disposed = true;
+                s_opened = false;
+            }
+        }
+
+        /// <inheritdoc/>
+        ~OneWireHost()
+        {
+            // Do not change this code. Put cleanup code in 'Dispose(bool disposing)' method
+            Dispose(disposing: false);
+        }
+
+        /// <inheritdoc/>
+        public void Dispose()
+        {
+            Dispose(disposing: true);
+            GC.SuppressFinalize(this);
+        }
+
+        #endregion
+
+        #region Native methods
+
+        [MethodImpl(MethodImplOptions.InternalCall)]
+        private extern void NativeDispose();
+
+        [MethodImpl(MethodImplOptions.InternalCall)]
+        private extern void NativeInit();
+
+        #endregion
     }
 }

nanoFramework.Device.OneWire/Properties/AssemblyInfo.cs

@@ -1,6 +1,4 @@
 using System.Reflection;
-using System.Runtime.CompilerServices;
-using System.Runtime.InteropServices;
 
 // General Information about an assembly is controlled through the following 
 // set of attributes. Change these attribute values to modify the information
@@ -12,5 +10,5 @@ using System.Runtime.InteropServices;
 
 ////////////////////////////////////////////////////////////////
 // update this whenever the native assembly signature changes //
-[assembly: AssemblyNativeVersion("100.0.3.4")]
+[assembly: AssemblyNativeVersion("100.0.4.0")]
 ////////////////////////////////////////////////////////////////

nanoFramework.Device.OneWire/nanoFramework.Device.OneWire.nfproj

@@ -30,7 +30,7 @@
   <PropertyGroup>
     <!-- override default options for MetaDataProcessor -->
     <NF_GenerateStubsDirectory>bin\$(Configuration)\Stubs</NF_GenerateStubsDirectory>
-    <NF_GenerateSkeletonProjectName>nf_device_onewire_native</NF_GenerateSkeletonProjectName>
+    <NF_GenerateSkeletonProjectName>nf_dev_onewire</NF_GenerateSkeletonProjectName>
     <Name>nanoFramework.Device.OneWire</Name>
   </PropertyGroup>
   <ItemGroup>
@@ -40,7 +40,7 @@
   </ItemGroup>
   <Import Project="$(NanoFrameworkProjectSystemPath)NFProjectSystem.props" Condition="Exists('$(NanoFrameworkProjectSystemPath)NFProjectSystem.props')" />
   <ItemGroup>
-    <Compile Include="OneWire.cs" />
+    <Compile Include="OneWireHost.cs" />
     <Compile Include="Properties\AssemblyInfo.cs" />
   </ItemGroup>
   <ItemGroup>