Adding documentation (#31)

Author: Ellerbach

README.md

@@ -10,6 +10,7 @@
 
 This repository contains bindings which can be sensors, small screen and anything else that you can connect to your nanoFramework chip!
 
+Most of the bindings have been migrated from [.NET IoT repository](https://github.com/dotnet/iot/tree/main/src/devices). Not all the bindings make sense to migrate to .NET nanoFramework, so the effort of migration has been placed into devices that can work with .NET nanoFramework. Please note as well that some devices have been migrated without been tested, so they main contain problems.
 
 ## Folder Structure
 
@@ -25,6 +26,32 @@ Other folders in [/src](/src) contain nanoFramework projects that you can refere
 
 **Important:** If you plan to clean up the code in [/src/devices_generated/](/src/devices_generated/), please copy your work to the [/src/devices/](/src/devices/) folder as the content of [/src/devices_generated/](/src/devices_generated/) will be overwritten by the generator tool.
 
+Please check the [detail list of tips and tricks](./tips-tricks.md) to facilitate the migration. The generator takes care of some heavy lifting but there is always some manual adjustments needed.
+
+We are using the following structure for the bindings:
+
+```text
+/devices
+  /Binding1
+    /samples
+      Binding1.Samples.nfproj
+      AssicateFile.cs
+      Program.cs
+    /test
+      BindingA.Test.nfproj
+      AssociatedTestFile.cs
+    Binding1.nfproj
+    Binding1.nuspec
+    version.json
+    OtherFiles.cs
+    OtherFiles.anythingelse
+    Readme.md
+```
+
+## Using the Code Converter
+
+The Code Converter allows to facilitate migration of .NET Core/.NET 5.0 code into .NET nanoFramework. More information and how to [customize and run it here](./src/nanoFramework.IoT.Device.CodeConverter/README.md).
+
 ## 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).

src/nanoFramework.IoT.Device.CodeConverter/Program.cs

@@ -116,6 +116,7 @@ static void Main(string[] args)
                         { "Console.WriteLine(", "Debug.WriteLine(" },
                         { "using System.Diagnostics.CodeAnalysis;", "" },
                         { "\\[MemberNotNull.*\\]", "" },
+                        { "Environment.TickCount", "DateTime.UtcNow.Ticks" },
                     };
 
                     // All generics go to the main project of the binding to avoid conflicts between the projects.

src/nanoFramework.IoT.Device.CodeConverter/README.md

@@ -0,0 +1,36 @@
+# Using nanoFramework Code Converter
+
+This converter is mainly design to help the migration from .NET IoT repository. That said, it can be used for any code transformation from .NET Core/.NET 5.0 to .NET nanoFramework.
+
+The tools create a solution, transform the `csproj` file to a `nfproj` file, find and add automatically some of the nugets, including mscorlib, add reference to shared projects. It does as well generated static class file from a generic `List<Something>` to `ListSomething` so it can be used in nanoFramework as generics are not (yet) supported.
+
+## Running the Code Converter
+
+You can adjust the different paths into the `appsettings.json` file:
+
+```json
+{
+  "SourceDirectory": "e:\\GitHub\\DotNet-iot\\src\\devices",
+  "FilePathFilters": "src\\devices\\",
+  "GenericsTemplatesFolderName": "GenericsTemplates",
+  "TargetProjectTemplateName": "BindingTemplateProject",
+  "TargetUnitTestProjectTemplateName": "UnitTestTemplateProject",
+  "OutputDirectoryPath": "..\\..\\..\\..\\devices_generated"
+}
+```
+
+- The `SourceDirectory` is where you have the project you want to transform and the `FilePathFilters` where you want the generation.
+- `GenericsTemplatesFolderName` contains the generic templates you want to be analyzed and transformed.
+- `TargetProjectTemplateName` contains the target project templates, for libraries and executable.
+- `TargetUnitTestProjectTemplateName` contains the target project for tests.
+- `OutputDirectoryPath` contains the output directory where you want the projects to be generated.
+
+Then run the tool either from the solution either from the command line. Be aware that paths are relative to where the execution is happening.
+
+## Customizing the generator
+
+You can include different shared projects, those are declared into [`SharedProjectImports.cs`](./SharedProjectImports.cs). 
+
+## Customizing the nuget packages
+
+You can include different nuget packages, those are declared into [`NfNugetPackages.cs`](./NfNugetPackages.cs). 

src/nanoFramework.IoT.Device.CodeConverter/SharedProjectImports.cs

@@ -10,21 +10,33 @@ public static SharedProjectImport[] GetnfSharedProjectImports()
                             new SharedProjectImport {
                                 Namespace="System.Diagnostics",
                                 CodeMatchString="Stopwatch",
-                                NewProjectImport = @"<Import Project=""..\..\Stopwatch\Stopwatch.projitems"" Label=""Shared"" />"
+                                NewProjectImport = @"<Import Project=""..\..\src\Stopwatch\Stopwatch.projitems"" Label=""Shared"" />"
                             },
                             new SharedProjectImport {
                                 Namespace="System.Buffers.Binary",
                                 CodeMatchString="BinaryPrimitives",
-                                NewProjectImport = @"<Import Project=""..\..\BinaryPrimitives\BinaryPrimitives.projitems"" Label=""Shared"" />"
+                                NewProjectImport = @"<Import Project=""..\..src\BinaryPrimitives\BinaryPrimitives.projitems"" Label=""Shared"" />"
                             },
                             new SharedProjectImport {
                                 Namespace="System.Device.Model",
-                                NewProjectImport = @"<Import Project=""..\..\System.Device.Model\System.Device.Model.projitems"" Label=""Shared"" />"
+                                NewProjectImport = @"<Import Project=""..\..\src\System.Device.Model\System.Device.Model.projitems"" Label=""Shared"" />"
                             },
                             new SharedProjectImport {
                                 Namespace="System.Numerics",
-                                NewProjectImport = @"<Import Project=""..\..\System.Numerics\System.Numerics.projitems"" Label=""Shared"" />"
+                                NewProjectImport = @"<Import Project=""..\..\src\System.Numerics\System.Numerics.projitems"" Label=""Shared"" />"
                             },
+                            new SharedProjectImport {
+                                Namespace="System.Runtime.CompilerService",
+                                NewProjectImport = @"<Import Project=""..\..\src\System.Runtime.CompilerService\System.Runtime.CompilerService.projitems"" Label=""Shared"" />"
+                            },
+                            new SharedProjectImport {
+                                Namespace="System.Drawing",
+                                NewProjectImport = @"<Import Project=""..\..\src\System.Drawing\System.Drawing.projitems"" Label=""Shared"" />"
+                            },
+                            new SharedProjectImport {
+                                Namespace="Iot.Device.Common",
+                                NewProjectImport = @"<Import Project=""..\..\src\Iot.Device.Common\Iot.Device.Common.projitems"" Label=""Shared"" />"
+                            }                            
             };
         }
     }

tips-trick.md

@@ -0,0 +1,70 @@
+# Tips and tricks for .NET IoT to .NET nanoFramework migration
+
+You'll find a list of tips and tricks to help in the migration. There is no specific order in this list.
+
+## What's already done for you
+
+The project conversion, transformation os `Span<byte>` to `SpanByte` and other associated elements are done automatically.
+
+## Enums
+
+- Issue: .NET nanoFramework supports a limited version of enum, so `GetValues`, `IsDefined` are not available. 
+- Resolution: just remove the `IsDefined`, this is used for check only. If you need the nice names with the `GetValues` use either a switch or string or anything like this depending on the scenario.
+
+## Multidimensional Arrays [,]
+
+- Issue: multidimensional `Arrays [,]` are not supported in .NET nanoFramework
+- Resolution:
+  - Replace them with `Array [][]`
+  - Initialization is different, example:
+  ```csharp
+  // byte[,] array = new byte[42,15];
+  byte[][] array = new byte[42][];
+  for(int i = 0, i < 15; i++)
+  {
+    array[i] = new byte[15];
+  }
+  ```
+  - If you have something lile `public int this[int x, int y]`, you'll need to create a class, example:
+  ```csharp
+  class Point
+  {
+      public Point(int X, int y)
+      {
+          X = x;
+          Y = y;
+      }
+      public int X { get; set; }
+      public int Y { get; set; }
+  }
+  public int this[Point pt]
+  // and get access to pt.X and pt.Y
+  // ...
+  // Access is then like:
+  Somthing[new Point(12,34)];
+  ```
+## Queue<Something>
+
+- Issue: There is no generic (yet) and no Queue in nanoFramework. Most of the time, the usage of those elements are simple.
+- Resolution: Replace the Queue by a `ArrayList` and use `Add` and `Remove` with a cast to read the data.
+
+## Console
+
+- Issue: `Console` is not available in .NET nanoFramework. It does only appear on the sample side.
+- Resolution: can be replaced by `Debug`. And the `Console.Read` and other elements like this from the samples can be replaced by hard coded data or constants. 
+
+## Unsafe
+
+You may have to compile some of the projects in unsafe mode. This is needed if you are using unsafe blocks or unsafe instructions into your project.
+
+Add `<AllowUnsafeBlocks>true</AllowUnsafeBlocks>` in the nfproj in the property group `PropertyGroup` right after then language version.
+
+## Adjust the documentation
+
+When converting, you may move some code, change some properties or functions a bit, that may need adjustment in README and other documentation, don't forget to adjust those! This does include as well replacing schema from Raspberry Pi to our lovely MCU. Any ESP32 or any STM32 or any supported MCU will be enough.
+
+## Nuget restore and updates
+
+It is recommended to update the nugets with a `dotnet restore` before opening the solution.
+
+You may be stuck sometimes because some references may be corrupted and you won't be able to update or add a new nuget. In this case, you can try to downgrade by one version all the nugets and then update them again, this will pull potential missing references.