Adding .NET support

documentation/asciidoc/accessories/build-hat.adoc

@@ -1,12 +1,28 @@
+// Intro
+
 include::build-hat/introduction.adoc[]
 
 include::build-hat/preparing-build-hat.adoc[]
 
-include::build-hat/installing-software.adoc[]
+// Python
+
+include::build-hat/py-installing-software.adoc[]
+
+include::build-hat/py-motors.adoc[]
+
+include::build-hat/py-sensors.adoc[]
+
+// .NET
+
+include::build-hat/net-installing-software.adoc[]
+
+include::build-hat/net-brick.adoc[]
+
+include::build-hat/net-motors.adoc[]
 
-include::build-hat/motors.adoc[]
+include::build-hat/net-sensors.adoc[]
 
-include::build-hat/sensors.adoc[]
+// Close out
 
 include::build-hat/links-to-other.adoc[]
 

documentation/asciidoc/accessories/build-hat/compat.adoc

@@ -21,7 +21,7 @@ SPIKE Prime Expansion Set | 45678, 45680 | Motor | Active | 31
 
 | Distance Sensor | White/Black	| 6302968 | Yes | Yes | | https://www.bricklink.com/v2/catalog/catalogitem.page?P=37316c01&idColor=11#T=C&C=11[Link] | SPIKE Prime Set, Mindstorms Robot Inventor | 45678, 51515  |DistanceSensor | Active | 3E
 
-| System medium motor | White/Grey | 45303,6138854,6290182,6127110 | Yes | Yes | | | Wedo 2.0, LEGO Ideas Piano, App controlled Batmobile | 76112 | | Passive | 1
+| System medium motor | White/Grey | 45303, 6138854, 6290182, 6127110 | Yes | Yes | | | Wedo 2.0, LEGO Ideas Piano, App controlled Batmobile | 76112 | | Passive | 1
 
 | Force Sensor | White/Black | 6254354 | Yes | Yes | 45606 | https://www.bricklink.com/v2/catalog/catalogitem.page?P=37312c01&idColor=11#T=C&C=11[Link] | SPIKE Prime Set | 45678 | ForceSensor | Active | 3F
 

documentation/asciidoc/accessories/build-hat/links-to-other.adoc

@@ -5,7 +5,7 @@ You can download documentation on the,
 * https://datasheets.raspberrypi.com/build-hat/build-hat-serial-protocol.pdf[Raspberry Pi Build HAT Serial Protocol]
 * https://datasheets.raspberrypi.com/build-hat/build-hat-python-library.pdf[Raspberry Pi Build HAT Python Library]
 
-and full details of the Python Library documentation can also be found https://buildhat.readthedocs.io/[on ReadTheDocs].
+and full details of the Python Library documentation can also be found https://buildhat.readthedocs.io/[on ReadTheDocs]. You can find more information on the .NET library in the https://github.com/dotnet/iot/tree/main/src/devices/BuildHat[.NET IoT] Github repository.
 
 You can also follow along with projects from the Raspberry Pi Foundation,
 

documentation/asciidoc/accessories/build-hat/net-brick.adoc

@@ -0,0 +1,114 @@
+=== Using the Build HAT from .NET
+
+The Raspberry Pi Built HAT is refered to "Brick" in LEGO® parlance and you can talk directly to it from .NET using the https://datasheets.raspberrypi.com/build-hat/build-hat-serial-protocol.pdf[Build HAT Serial Protocol].
+
+You can create a `brick` object as below,
+
+[csharp]
+----
+Brick brick = new("/dev/serial0");
+----
+
+but you need to remember to dispose of the `brick` at the end of your code.
+
+[csharp]
+----
+brick.Dispose();
+----
+
+WARNING: If you do not call `brick.Dispose()` you program will not terminate.
+
+If you want to avoid calling `brick.Dispose` at the end, then create your brick with the `using` statement:
+
+[csharp]
+----
+using Brick brick = new("/dev/serial0");
+----
+
+In this case, when reaching the end of the program, your brick will be automatically disposed.
+
+==== Displaying the information
+
+You can gather the various software versions, the signature, and the input voltage:
+
+[csharp]
+----
+var info = brick.BuildHatInformation;
+Console.WriteLine($"version: {info.Version}, firmware date: {info.FirmwareDate}, signature:");
+Console.WriteLine($"{BitConverter.ToString(info.Signature)}");
+Console.WriteLine($"Vin = {brick.InputVoltage.Volts} V");
+----
+
+NOTE: the input voltage is read only once at boot time and is not read again afterwards.
+
+==== Getting sensors and motors details
+
+The functions `GetSensorType`, `GetSensor` will allow you to retrieve any information on connected sensor.
+
+[csharp]
+----
+SensorType sensor = brick.GetSensorType((SensorPort)i);
+Console.Write($"Port: {i} {(Brick.IsMotor(sensor) ? "Sensor" : "Motor")} type: {sensor} Connected: ");
+----
+
+In this example, you can as well use the `IsMotor` static function to check if the connected element is a sensor or a motor.
+
+[csharp]
+----
+if (Brick.IsActiveSensor(sensor))
+{
+    ActiveSensor activeSensor = brick.GetActiveSensor((SensorPort)i);
+}
+else
+{
+    var passive = (Sensor)brick.GetSensor((SensorPort)i);
+    Console.WriteLine(passive.IsConnected);
+}
+----
+
+`ActiveSensor` have a collection of advanced properties and functions allowing to understand every element of the sensor. It is also possible to call the primitive functions from the brick from them. This will allow you to select specific modes and do advance scenarios. While this is possible, motor and sensor classes have been created to make your life easier.
+
+==== Events
+
+Most sensors implements events on their special properties. You can simply subscribe to `PropertyChanged` and `PropertyUpdated`. The changed one will be fired when the value is changing while the updated one when there is a success update to the property. Depending on the modes used, some properties may be updated in the background all the time while some others occasionally.
+
+You may be interested only when a color is changing or the position of the motor is changing, using it as a tachometer. In this case, the `PropertyChanged` is what you need!
+
+[csharp]
+----
+Console.WriteLine("Move motor on Port A to more than position 100 to stop this test.");
+brick.WaitForSensorToConnect(SensorPort.PortA);
+var active = (ActiveMotor)brick.GetMotor(SensorPort.PortA);
+bool continueToRun = true;
+active.PropertyChanged += MotorPropertyEvent;
+while (continueToRun)
+{
+    Thread.Sleep(50);
+}
+
+active.PropertyChanged -= MotorPropertyEvent;
+Console.WriteLine($"Current position: {active.Position}, eventing stopped.");
+
+void MotorPropertyEvent(object? sender, PropertyChangedEventArgs e)
+{
+    Console.WriteLine($"Property changed: {e.PropertyName}");
+    if (e.PropertyName == nameof(ActiveMotor.Position))
+    {
+        if (((ActiveMotor)brick.GetMotor(SensorPort.PortA)).Position > 100)
+        {
+            continueToRun = false;
+        }
+    }
+}
+----
+
+==== Waiting for initialization
+
+The brick can take long before it initializes. A wait for sensor to be connected has been implemented,
+
+[csharp]
+----
+brick.WaitForSensorToConnect(SensorPort.PortB);
+----
+
+It does as well take a `CancellationToken` if you want to implement advance features like warning the user after some time and retrying.

documentation/asciidoc/accessories/build-hat/net-installing-software.adoc

@@ -0,0 +1,22 @@
+== Using the Build HAT from .NET 
+
+=== Installing the .NET Framework
+
+The .NET framework from Microsoft is not available via `apt` on Raspberry Pi. However, you can follow the https://docs.microsoft.com/en-us/dotnet/iot/deployment[official instructions] from Microsoft to install the .NET framework. Alternatively, there is a simplified https://www.petecodes.co.uk/install-and-use-microsoft-dot-net-5-with-the-raspberry-pi/[third party route] to get the .NET toolchain on to your Raspberry Pi. 
+
+WARNING: The installation script is run as `root`. You should read it first and make sure you understand what it is doing. If you are at all unsure you should follow the https://docs.microsoft.com/en-us/dotnet/iot/deployment[official instructions] manually.
+
+[.bash]
+----
+$ wget -O - https://raw.githubusercontent.com/pjgpetecodes/dotnet5pi/master/install.sh | sudo bash
+----
+
+After installing the .NET framework you also need to install the nuget packages:
+
+[.bash]
+----
+$ dotnet add package System.Device.Gpio --source https://pkgs.dev.azure.com/dotnet/IoT/_packaging/nightly_iot_builds/nuget/v3/index.json
+$ dotnet add package Iot.Device.Bindings --source https://pkgs.dev.azure.com/dotnet/IoT/_packaging/nightly_iot_builds/nuget/v3/index.json
+----
+
+You can now create a project and edit it.

documentation/asciidoc/accessories/build-hat/net-motors.adoc

@@ -0,0 +1,128 @@
+=== Using Motors from .NET
+
+There are two types of motors, the *passive* ones and the *active* ones. Active motors will provide detailed position, absolute position and speed while passive motors can only be controlled with speed.
+
+A common set of functions to control the speed of the motors are available. There are 2 important ones: `SetPowerLimit` and `SetBias`:
+
+[csharp]
+----
+train.SetPowerLimit(1.0);
+train.SetBias(0.2);
+----
+
+The accepted values are only from 0.0 to 1.0. The power limit is a convenient ay to reduce in proportion the maximum power.
+
+The bias value sets for the current port which is added to positive motor drive values and subtracted from negative motor drive values. This can be used to compensate for the fact that most DC motors require a certain amount of drive before they will turn at all.
+
+The default values when a motor is created is 0.7 for the power limit and 0.3 for the bias.
+
+==== Passive Motors
+
+.Train motor, https://www.bricklink.com/v2/catalog/catalogitem.page?S=88011-1&name=Train%20Motor&category=%5BPower%20Functions%5D%5BPowered%20Up%5D#T=S&O={%22iconly%22:0}[Image from Bricklink]
+image::images/train-motor.png[Train motor,width="60%"]
+
+The typical passive motor is a train and older Powered Up motors. The `Speed` property can be set and read. It is the target and the measured speed at the same time as those sensors do not have a way to measure them. The value is from -100 to +100.
+
+Functions to control `Start`, `Stop` and `SetSpeed` are also available. Here is a example of how to use it:
+
+[csharp]
+----
+Console.WriteLine("This will run the motor for 20 secondes incrementing the PWM");
+train.SetPowerLimit(1.0);
+train.Start();
+for (int i = 0; i < 100; i++)
+{
+    train.SetSpeed(i);
+    Thread.Sleep(250);
+}
+
+Console.WriteLine("Stop the train for 2 seconds");
+train.Stop();
+Thread.Sleep(2000);
+Console.WriteLine("Full speed backward for 2 seconds");
+train.Start(-100);
+Thread.Sleep(2000);
+Console.WriteLine("Full speed forward for 2 seconds");
+train.Start(100);
+Thread.Sleep(2000);
+Console.WriteLine("Stop the train");
+train.Stop();
+----
+
+NOTE: Once the train is started, you can adjust the speed and the motor will adjust accordingly.
+
+==== Active Motors
+
+.Active motor, https://www.bricklink.com/v2/catalog/catalogitem.page?S=88014-1&name=Technic%20XL%20Motor&category=%5BPower%20Functions%5D%5BPowered%20Up%5D#T=S&O={%22iconly%22:0}[Image from Bricklink]
+image::images/active-motor.png[Active motor,width="60%"]
+
+Active motors have `Speed`, `AbsolutePosition`, `Position` and `TargetSpeed` as special properties. They are read continuously even when the motor is stopped.
+
+The code snippet shows how to get the motors, start them and read the properties:
+
+[csharp]
+----
+brick.WaitForSensorToConnect(SensorPort.PortA);
+brick.WaitForSensorToConnect(SensorPort.PortD);
+var active = (ActiveMotor)brick.GetMotor(SensorPort.PortA);
+var active2 = (ActiveMotor)brick.GetMotor(SensorPort.PortD);
+active.Start(50);
+active2.Start(50);
+// Make sure you have an active motor plug in the port A and D
+while (!Console.KeyAvailable)
+{
+    Console.CursorTop = 1;
+    Console.CursorLeft = 0;
+    Console.WriteLine($"Absolute: {active.AbsolutePosition}     ");
+    Console.WriteLine($"Position: {active.Position}     ");
+    Console.WriteLine($"Speed: {active.Speed}     ");
+    Console.WriteLine();
+    Console.WriteLine($"Absolute: {active2.AbsolutePosition}     ");
+    Console.WriteLine($"Position: {active2.Position}     ");
+    Console.WriteLine($"Speed: {active2.Speed}     ");
+}
+
+active.Stop();
+active2.Stop();
+----
+
+NOTE: You should not forget to start and stop your motors when needed.
+
+Advance features are available for active motors. You can request to move for seconds, to a specific position, a specific absolute position. Here are couple of examples:
+
+[csharp]
+----
+// From the previous example, this will turn the motors back to their initial position:
+active.TargetSpeed = 100;
+active2.TargetSpeed = 100;
+// First this motor and will block the thread
+active.MoveToPosition(0, true);
+// Then this one and will also block the thread
+active2.MoveToPosition(0, true);
+----
+
+Each function allow you to block or not the thread for the time the operation will be performed. Note that for absolute and relative position moves, there is a tolerance of few degrees.
+
+[csharp]
+----
+brick.WaitForSensorToConnect(SensorPort.PortA);
+var active = (ActiveMotor)brick.GetMotor(SensorPort.PortA);
+active.TargetSpeed = 70;
+Console.WriteLine("Moving motor to position 0");
+active.MoveToPosition(0, true);
+Console.WriteLine("Moving motor to position 3600 (10 turns)");
+active.MoveToPosition(3600, true);
+Console.WriteLine("Moving motor to position -3600 (so 20 turns the other way");
+active.MoveToPosition(-3600, true);
+Console.WriteLine("Moving motor to absolute position 0, should rotate by 90°");
+active.MoveToAbsolutePosition(0, PositionWay.Shortest, true);
+Console.WriteLine("Moving motor to position 90");
+active.MoveToAbsolutePosition(90, PositionWay.Shortest, true);
+Console.WriteLine("Moving motor to position 179");
+active.MoveToAbsolutePosition(179, PositionWay.Shortest, true);
+Console.WriteLine("Moving motor to position -180");
+active.MoveToAbsolutePosition(-180, PositionWay.Shortest, true);
+active.Float();
+----
+
+You can place the motor in a float position, meaning, there are no more constrains on it. This is a mode that you can use when using the motor as a tachometer, moving it and reading the position. If you still have constrains on the motors, you may not be able to move it.