Improving troubleshooting and getting started links and fixing TOC (#214)

Author: Ellerbach

azure-pipelines.yml

@@ -510,7 +510,7 @@ steps:
     $textToAdd = "items:
     - name: Home
       href: ../index.md"
-    $fileContents[1] = $fileContents[1].Replace("items:", $textToAdd)
+    $fileContents[1] = $fileContents[1].Replace("- name: Content", $textToAdd)
     
     # write all lines back to file
     $fileContents | Set-Content $filePath

content/getting-started-guides/index.md

@@ -8,13 +8,16 @@ You only need to build it if you plan to debug the native code, add new targets
 If your goal is to code in C# you just have to flash your MCU with the appropriate firmware image.
 There are available ready to flash firmware images for several targets, please check the [reference targets](../reference-targets/index.md) and several others [community contributed](../community-targets/index.md).
 
+Check out our [special beginner content](./beginner-explained.md)! All what you have ever wanted to know about GPIO, I2C, SPI, DAC, ADC, UART and more!
+
 ## Managed (C#)
 
-- [Getting started guide for C#](getting-started-managed.md)
-- [Getting started trouble shooting guide](trouble-shooting-guide.md)
-- [Getting started with VS Code extension](getting-started-vs-code.md)
-- [Compare .NET **nanoFramework** with .NET IoT](dotnet-iot-core-vs-nanoframework.md)
-- [Virtual Device](virtual-device.md)
+- [Getting started guide for C#](./getting-started-managed.md)
+- [Getting started trouble shooting guide](./trouble-shooting-guide.md)
+- [Getting started trouble shooting device connection guide](./troubleshooting-device-connection.md)
+- [Getting started with VS Code extension](./getting-started-vs-code.md)
+- [Compare .NET **nanoFramework** with .NET IoT](./dotnet-iot-core-vs-nanoframework.md)
+- [Virtual Device](./virtual-device.md)
 
 ## Build instructions
 

content/getting-started-guides/trouble-shooting-guide.md

@@ -49,3 +49,10 @@ Here are solutions to some common problems when getting started.
 - This is due to the nanoff will try to read and backup config partition before the actual flash.
 - If the chip is flashed with something else before (e.g. Arduino), it will cause a read error and stop the process.
 - Add `--masserase` to bypass the backup process and erase the flash.
+
+## nanoff failed to read from ESP32 chip (E4000)
+
+- This is most likely due to the fact that the device needs to be placed manually into boot mode.
+- You will have to handle the `reset` button, press the `boot` button, then release the `reset` button. This places the device into boot mode. It is strongly recommended to close Visual Studio during this process.
+- The serial port can change! So, make sure you are checking the new port number.
+- Once flashed, the device needs to be rebooted manually (press the reset button or disconnect and reconnect the device) to be seen by Visual Studio.

content/getting-started-guides/troubleshooting-device-connection.md

@@ -91,3 +91,11 @@ Regardless of your device, once you connect it, you will see the message `NFPKTV
 Don't worry about the possible scramble characters before, they are the ones from the boot of the device itself. Some devices like ESP32 are quite chatty (see previous section), some devices like STM32 are very quite!
 
 From that point, seeing this message means the device is properly working, so look again at [this troubleshooting guide](./trouble-shooting-guide.md).
+
+### Devices with multiple serial ports
+
+Some devices like the ESP32 S3 may come with multiple serial ports. They usually have one named USB, the other one named UART. In those cases, one port is used to flash the device with nanoff and the other one to be seen by Visual Studio.
+
+If you are not sure which port to use, plug one, try to flash on it, if it doesn't work, use the other one.
+
+In most cases, you **cannot** connect both serial ports to your machine, as this interferes with the flash process and does not allow the device to go into boot mode.

content/getting-started-guides/where-to-buy-devices.md

@@ -2,7 +2,9 @@
 
 This is a list of recommended devices to start with .NET nanoFramework and links where you can find them. While this list is far to be exhaustive, contribution to adjust this list and especially where to buy them will be very appreciated.
 
-> Important: Those lists are just suggestions, the links to buy as well, we are not linked or related to any of those vendors neither any of the resellers.
+> [!Important]
+>
+> Those lists are just suggestions, the links to buy as well, we are not linked or related to any of those vendors neither any of the resellers.
 
 | MCU|Specifications|Manufacturer SKU|Firmware Target|Purchase Option|
 |---|---|---|---|---|
@@ -29,4 +31,6 @@ Integrated devices with additional sensors like accelerometers, screens, leds:
 
 Note that you can find most of those boards as well on Amazon and various local websites. Again, feel free to submit a PR with more links on where we can find your favorite device!
 
-> Important: Those lists are just suggestions, the links to buy as well, we are not linked or related to any of those vendors neither any of the resellers.
+> [!Important]
+>
+> Those lists are just suggestions, the links to buy as well, we are not linked or related to any of those vendors neither any of the resellers.