Documentation changes (second half): Use only a single README.md per device #1610

krwq · 2021-07-21T14:40:33Z

@Ellerbach is doing first part

The idea is that samples/README.md should not exist and only one README.md file per device should be used.

This will make it easier to make READMEs visible in the documentation.

Microsoft Reviewers: Open in CodeFlow

…device

krwq · 2021-07-22T11:55:11Z

src/devices/Max44009/README.md

+
+![Sample Result](RunningResult.jpg)
+
+## Hardware Required


this should go first in the usage section

same for circuit

krwq · 2021-07-22T12:00:01Z

src/devices/Mlx90614/README.md

+* Male/Female Jumper Wires
+
+### Circuit
+![](MLX90614_circuit_bb.jpg)


Suggested change

![](MLX90614_circuit_bb.jpg)

![Schematics](MLX90614_circuit_bb.jpg)

krwq · 2021-07-22T12:01:01Z

src/devices/Mpr121/README.md

+
+
+This sample demonstrates how to read channel statuses using auto-refresh configuration.
+


Suggested change

This sample demonstrates how to read channel statuses using auto-refresh configuration.

krwq · 2021-07-22T12:01:51Z

src/devices/Nrf24l01/README.md

@@ -47,10 +104,11 @@ private static void Receiver_ReceivedData(object sender, DataReceivedEventArgs e
    }
    Console.WriteLine();

-    Console.WriteLine($"Message: {msg}");
+    Console.WriteLine($"Massage: {msg}");


Suggested change

Console.WriteLine($"Massage: {msg}");

Console.WriteLine($"Message: {msg}");

krwq · 2021-07-22T12:04:08Z

src/devices/Pcd8544/README.md

@@ -124,7 +128,7 @@ var bitmap3 = BitmapToByteArray(bitmapLarge);

 Note: you may want to reverse the colors first depending on what you want.

-## Advance functions
+### Advance functions


Suggested change

### Advance functions

### Advanced functions

krwq · 2021-07-22T12:05:25Z

src/devices/Rtc/README.md

+
+## Board
+
+![](Circuit_DS1307_bb.png)


Suggested change

![](Circuit_DS1307_bb.png)

![Schematics](Circuit_DS1307_bb.png)

krwq · 2021-07-22T12:05:45Z

src/devices/Seesaw/README.md

+
+This sample duplicates the functionality of the rpi-more-blinking-lights sample but instead of using the raspberry pi Gpio it uses the Seesaw breakout board for all inputs
+
+![](SeesawSampleBlinkingLights_bb.png)


Suggested change

![](SeesawSampleBlinkingLights_bb.png)

![Schematics](SeesawSampleBlinkingLights_bb.png)

Ellerbach

few comments on few files. I left you Markdown tips as well to help correcting some of the docs.

Ellerbach · 2021-07-22T12:37:58Z

src/devices/Lps25h/README.md


 - https://www.st.com/resource/en/datasheet/lps25h.pdf
+


while you are at adjusting those elements, make it with the proper pattern so something like:

Official LPS25H documentation can be found [here](https://www.st.com/resource/en/datasheet/lps25h.pdf)

I've tried to adjust all those URLs as well

Ellerbach · 2021-07-22T12:38:45Z

src/devices/Lsm9Ds1/README.md

+        return I2cDevice.Create(settings);
+    }
+}
+```


Markdown tip: you need to finish the file with an empty line, so adding an extra enter

See the other Markdown tips left there and there :-) the enum at the beginning of the file is not correct as it should havre an empty line before also reinforce by the fact you have a title.

Ellerbach · 2021-07-22T12:40:48Z

src/devices/Max31856/README.md


 **Max31856** [datasheet](https://datasheets.maximintegrated.com/en/ds/Max31856.pdf)
+
+## Usage
+The Max31856.samples file contains a sample usage of the device. Note that this reads two temperatures. One is a connected thermocouple reading which can be read using the  ```TryGetTemperature``` command and the other is the temperature of the device itself which can be read using the ```GetColdJunctionTemperature``` command. The Cold Junction Temperature is used internally to increase the accuracy of the thermocouple but can also be read if you find a use for it.


Marktdown tips:

all titles except the first level one, must have an empty line and an empty line after.

all code blocks need to be separated with an empty line before and after

al enums need to be grouped without extra enter between them

for code blocks, use only "csharp" and not the c# version, all lowercase

Ellerbach · 2021-07-22T12:41:09Z

src/devices/Max31856/README.md

+```
+
+Create a new ```SpiDevice``` with the settings from above. Then create a new Max31856 device with the ```SpiDevice``` as well as the correct ```ThermocoupleType``` (see note below)
+```csharp


so here you miss an enter before the code block

Ellerbach · 2021-07-22T12:45:26Z

src/devices/Max7219/README.md

+You can use .NET Core to drive MAX7219 based Dot Matrix Modules.
+
+These Modules can be cascaded to get a bigger matrix.
+


Markdown tip: you should not leave extra enters, just what' s needed

Ellerbach · 2021-07-22T12:47:57Z

src/devices/Mbi5027/README.md

@@ -17,6 +17,11 @@ Note: The [MBI5168](http://archive.fairchip.com/pdf/MACROBLOCK/MBI5168.pdf) is a

 The [MBI5027 sample](samples/README.md) demonstrates how to use the shift register. The [generic shift register sample](../ShiftRegister/samples/README.md) is more extensive and is compatible with the MBI5027.

+## Documentation
+
+- Datasheet: http://archive.fairchip.com/pdf/MACROBLOCK/MBI5027.pdf


I won't mark them all but would be perfect if you can adjust those raw URL with the correct pattern.

Markdown tip: In case you really want to show an URL, it should then be contained into < >

Ellerbach · 2021-07-22T12:49:12Z

src/devices/Mcp3xxx/README.md

+
+The sample is based on following resources:
+
+- [Analog Inputs for Raspberry Pi Using the MCP3008](https://learn.adafruit.com/reading-a-analog-in-and-controlling-audio-volume-with-the-raspberry-pi) 


Note: this is a great way to have the enumeration and the links on documentations.

Ellerbach · 2021-07-22T12:50:16Z

src/devices/Mcp3xxx/README.md

+
+The Raspberry Pi has support for SPI. You need to [enable the SPI interface on the Raspberry Pi](https://www.raspberrypi-spy.co.uk/2014/08/enabling-the-spi-interface-on-the-raspberry-pi/) since it is not enabled by default.
+
+You can use the following code to [access the MCP3008 via hardware SPI](Mcp3008.Sample.cs):


wrong URL, should be samples/Mcp3008.Sample.cs

Note: double check the file name, links are case sensitive in theory

Ellerbach · 2021-07-22T12:50:47Z

src/devices/Mcp3xxx/README.md

+
+You can also access the MCP3008 via GPIO pins, implementing SPI manually. This method is referred to as [bit-banging](https://en.wikipedia.org/wiki/Serial_Peripheral_Interface#Example_of_bit-banging_the_master_protocol).
+
+You can use the following code to [access the MCP3008 via GPIO](Mcp3008.Sample.cs):


wrong url as well should be amples/Mcp3008.Sample.cs

Ellerbach · 2021-07-22T12:51:11Z

src/devices/Mcp3xxx/README.md

+
+The chip is 10-bit, which means that it will generate values from 0-1023 (recall that 2^10 is 1024). We can transform the value to a more familiar 0-100 scale by dividing the 10-bit value by 10.24.
+
+


tooooo many enters ;-)

Note: I'll not point them all

src/devices/SoftPwm/README.md

Co-authored-by: Patrick Grawehr <[email protected]>

krwq · 2021-08-02T10:16:21Z

the changes from @Ellerbach LGTM, can't approve since I'm the author of the PR

Ellerbach

Good to merge

Documentation changes (second half): Use only a single README.md per …

9a2217b

…device

krwq requested a review from Ellerbach July 21, 2021 14:40

ghost added the area-device-bindings Device Bindings for audio, sensor, motor, and display hardware that can used with System.Device.Gpio label Jul 21, 2021

Ellerbach mentioned this pull request Jul 21, 2021

Documentation changes (first half): Use only a single README.md per device #1611

Merged

krwq commented Jul 22, 2021

View reviewed changes

Ellerbach reviewed Jul 22, 2021

View reviewed changes

pgrawehr approved these changes Jul 23, 2021

View reviewed changes

src/devices/SoftPwm/README.md Outdated Show resolved Hide resolved

Jimmys20 mentioned this pull request Jul 29, 2021

Added lcd interface to support SPI #1598

Merged

Ellerbach and others added 4 commits July 30, 2021 19:20

First part fix

5950f5f

second cleaning

0b46db2

more adjustments

5b9eb3f

Update src/devices/SoftPwm/README.md

e73955e

Co-authored-by: Patrick Grawehr <[email protected]>

Ellerbach approved these changes Aug 2, 2021

View reviewed changes

Ellerbach merged commit 148fc42 into dotnet:main Aug 2, 2021

github-actions bot locked and limited conversation to collaborators Dec 9, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation changes (second half): Use only a single README.md per device #1610

Documentation changes (second half): Use only a single README.md per device #1610

krwq commented Jul 21, 2021 •

edited by ghost

Loading

krwq Jul 22, 2021

krwq Jul 22, 2021

krwq Jul 22, 2021

krwq Jul 22, 2021

krwq Jul 22, 2021

krwq Jul 22, 2021

krwq Jul 22, 2021

krwq Jul 22, 2021

Ellerbach left a comment

Ellerbach Jul 22, 2021

Ellerbach Jul 22, 2021

Ellerbach Jul 22, 2021

Ellerbach Jul 22, 2021

Ellerbach Jul 22, 2021

Ellerbach Jul 22, 2021

Ellerbach Jul 22, 2021

Ellerbach Jul 22, 2021

Ellerbach Jul 22, 2021

Ellerbach Jul 22, 2021

Ellerbach Jul 22, 2021

krwq commented Aug 2, 2021 •

edited

Loading

Ellerbach left a comment

	![](MLX90614_circuit_bb.jpg)
	![Schematics](MLX90614_circuit_bb.jpg)



		This sample demonstrates how to read channel statuses using auto-refresh configuration.

	Console.WriteLine($"Massage: {msg}");
	Console.WriteLine($"Message: {msg}");

	![](Circuit_DS1307_bb.png)
	![Schematics](Circuit_DS1307_bb.png)


		This sample duplicates the functionality of the rpi-more-blinking-lights sample but instead of using the raspberry pi Gpio it uses the Seesaw breakout board for all inputs

		![](SeesawSampleBlinkingLights_bb.png)

	![](SeesawSampleBlinkingLights_bb.png)
	![Schematics](SeesawSampleBlinkingLights_bb.png)

		You can use .NET Core to drive MAX7219 based Dot Matrix Modules.

		These Modules can be cascaded to get a bigger matrix.


		The sample is based on following resources:

		- [Analog Inputs for Raspberry Pi Using the MCP3008](https://learn.adafruit.com/reading-a-analog-in-and-controlling-audio-volume-with-the-raspberry-pi)


		The Raspberry Pi has support for SPI. You need to [enable the SPI interface on the Raspberry Pi](https://www.raspberrypi-spy.co.uk/2014/08/enabling-the-spi-interface-on-the-raspberry-pi/) since it is not enabled by default.

		You can use the following code to [access the MCP3008 via hardware SPI](Mcp3008.Sample.cs):


		You can also access the MCP3008 via GPIO pins, implementing SPI manually. This method is referred to as [bit-banging](https://en.wikipedia.org/wiki/Serial_Peripheral_Interface#Example_of_bit-banging_the_master_protocol).

		You can use the following code to [access the MCP3008 via GPIO](Mcp3008.Sample.cs):


		The chip is 10-bit, which means that it will generate values from 0-1023 (recall that 2^10 is 1024). We can transform the value to a more familiar 0-100 scale by dividing the 10-bit value by 10.24.

Documentation changes (second half): Use only a single README.md per device #1610

Documentation changes (second half): Use only a single README.md per device #1610

Conversation

krwq commented Jul 21, 2021 • edited by ghost Loading

Microsoft Reviewers: Open in CodeFlow

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Ellerbach left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

krwq commented Aug 2, 2021 • edited Loading

Ellerbach left a comment

Choose a reason for hiding this comment

krwq commented Jul 21, 2021 •

edited by ghost

Loading

krwq commented Aug 2, 2021 •

edited

Loading