Improving README and documentation (#166)

Author: Ellerbach

devices/AD5328/README.md

@@ -1,15 +1,34 @@
 # AD5328 - Digital to Analog Convertor
+
 AD5328 is an Digital-to-Analog converter (DAC) with 12 bits of resolution.
 
+## Documentation
+
+Product information and documentation can he found [here](https://www.analog.com/en/products/ad5328.html)
+
 ## Usage
 
+**Important**: make sure you properly setup the SPI pins especially for ESP32 before creating the `SpiDevice`, make sure you install the `nanoFramework.Hardware.ESP32 nuget`:
+
+```csharp
+//////////////////////////////////////////////////////////////////////
+// when connecting to an ESP32 device, need to configure the SPI GPIOs
+// used for the bus
+Configuration.SetPinFunction(21, DeviceFunction.SPI1_MOSI);
+Configuration.SetPinFunction(22, DeviceFunction.SPI1_MISO);
+Configuration.SetPinFunction(23, DeviceFunction.SPI1_CLOCK);
+// Make sure as well you are using the right chip select
+```
+
+For other devices like STM32, please make sure you're using the preset pins for the SPI bus you want to use. The chip select can as well be pre setup.
+
 ```csharp
 using System.Device.Spi;
 using System.Threading;
 using Iot.Device.DAC;
 using UnitsNet;
 
-var spisettings = new SpiConnectionSettings(0, 1)
+var spisettings = new SpiConnectionSettings(1, 42)
 {
     Mode = SpiMode.Mode2
 };
@@ -19,8 +38,3 @@ var dac = new AD5328(spidev, ElectricPotential.FromVolts(2.5), ElectricPotential
 Thread.Sleep(1000);
 dac.SetVoltage(0, ElectricPotential.FromVolts(1));
 ```
-
-## References
-
-https://www.analog.com/en/products/ad5328.html
-

devices/AD5328/samples/Program.cs

@@ -6,7 +6,14 @@
 using Iot.Device.DAC;
 using UnitsNet;
 
-var spisettings = new SpiConnectionSettings(0, 1)
+//////////////////////////////////////////////////////////////////////
+// when connecting to an ESP32 device, need to configure the SPI GPIOs
+// used for the bus
+//Configuration.SetPinFunction(21, DeviceFunction.SPI1_MOSI);
+//Configuration.SetPinFunction(22, DeviceFunction.SPI1_MISO);
+//Configuration.SetPinFunction(22, DeviceFunction.SPI1_CLOCK);
+// Make sure as well you are using the right chip select
+var spisettings = new SpiConnectionSettings(1, 42)
 {
     Mode = SpiMode.Mode2
 };

devices/Ads1115/ADS1115_circuit.fzz

@@ -1,11 +1,30 @@
 # ADS1115 - Analog to Digital Converter
+
 ADS1115 is an Analog-to-Digital converter (ADC) with 16 bits of resolution.
 
+## Documentation
+
+Prodcut datasheet can be found [here](https://cdn-shop.adafruit.com/datasheets/ads1115.pdf)
+
 ## Sensor Image
-![](sensor.jpg)
+
+![ADS1115](sensor.jpg)
 
 ## Usage
-```C#
+
+**Important**: make sure you properly setup the I2C pins especially for ESP32 before creating the `I2cDevice`, make sure you install the `nanoFramework.Hardware.ESP32 nuget`:
+
+```csharp
+//////////////////////////////////////////////////////////////////////
+// when connecting to an ESP32 device, need to configure the I2C GPIOs
+// used for the bus
+Configuration.SetPinFunction(21, DeviceFunction.I2C1_DATA);
+Configuration.SetPinFunction(22, DeviceFunction.I2C1_CLOCK);
+```
+
+For other devices like STM32, please make sure you're using the preset pins for the I2C bus you want to use.
+
+```csharp
 // set I2C bus ID: 1
 // ADS1115 Addr Pin connect to GND
 I2cConnectionSettings settings = new I2cConnectionSettings(1, (int)I2cAddress.GND);
@@ -23,11 +42,71 @@ using (Ads1115 adc = new Ads1115(device, InputMultiplexer.AIN0, MeasuringRange.F
 }
 ```
 
-See the samples project for more examples and usage for different applications. 
+See the [samples project](https://github.com/dotnet/iot/tree/main/src/devices/Ads1115/samples) for more examples and usage for different applications.
+
+If you want to use the interrupt pin, the pulses generated by the ADS1115 might be to short to be properly recognized in the software, i.e. on a MCU. The schematic below shows a way of increasing the pulse length so that it is properly recognized (from about 10us to 150us). This uses discrete electronics, but an implementation with an NE555 or equivalent would likely work as well (Just note that you need a type that works at 3.3V).
+
+![Pulse_lengthener_schema](Pulse_lengthener_schema.png)
+
+## Example
+
+### Hardware Required
+
+* ADS1115
+* Rotary Potentiometer
+* Male/Female Jumper Wires
+
+### Circuit
+
+![circuit](ADS1115_circuit_bb.png)
+
+ADS1115
+
+* ADDR - GND
+* SCL - SCL
+* SDA - SDA
+* VCC - 5V
+* GND - GND
+* A0 - Rotary Potentiometer Pin 2
 
-If you want to use the interrupt pin, the pulses generated by the ADS1115 might be to short to be properly recognized in the software, i.e. on a Raspberry Pi. The schematic below shows a way of increasing the pulse length so that it is properly recognized (from about 10us to 150us). This uses discrete electronics, but an implementation with an NE555 or equivalent would likely work as well (Just note that you need a type that works at 3.3V). 
+Rotary Potentiometer
+
+* Pin 1 - 5V
+* Pin 2 - ADS1115 Pin A0
+* Pin 3 - GND
+
+### Code
+
+```csharp
+// set I2C bus ID: 1
+// ADS1115 Addr Pin connect to GND
+I2cConnectionSettings settings = new I2cConnectionSettings(1, (int)I2cAddress.GND);
+I2cDevice device = I2cDevice.Create(settings);
+
+// pass in I2cDevice
+// measure the voltage AIN0
+// set the maximum range to 6.144V
+using (Ads1115 adc = new Ads1115(device, InputMultiplexer.AIN0, MeasuringRange.FS6144))
+{
+    // loop
+    while (true)
+    {
+        // read raw data form the sensor
+        short raw = adc.ReadRaw();
+        // raw data convert to voltage
+        double voltage = adc.RawToVoltage(raw);
+
+        Debug.WriteLine($"ADS1115 Raw Data: {raw}");
+        Debug.WriteLine($"Voltage: {voltage}");
+        Debug.WriteLine();
+
+        // wait for 2s
+        Thread.Sleep(2000);
+    }
+}
+```
 
-![](Pulse_lengthener_schema.png)
+### Results
 
-## References
-https://cdn-shop.adafruit.com/datasheets/ads1115.pdf
+![run results](RunningResult.jpg)
+![interupt result](InterruptResult.png)

devices/Ads1115/ADS1115_circuit_bb.png

@@ -9,6 +9,12 @@
 using Iot.Device.Ads1115;
 using UnitsNet;
 
+//////////////////////////////////////////////////////////////////////
+// when connecting to an ESP32 device, need to configure the I2C GPIOs
+// used for the bus
+//Configuration.SetPinFunction(21, DeviceFunction.I2C1_DATA);
+//Configuration.SetPinFunction(22, DeviceFunction.I2C1_CLOCK);
+
 // set I2C bus ID: 1
 // ADS1115 Addr Pin connect to GND
 I2cConnectionSettings settings = new(1, (int)I2cAddress.GND);
@@ -65,7 +71,7 @@
 }
 
 // Provide a callback that triggers each time the ADC has a new value available. The DataRate parameter will define the sample rate.
-// We are using pin 23 as interrupt input from the ADC, but note that the trigger signal from the ADC may be to short to be properly recognized by the Raspberry Pi and
+// We are using pin 23 as interrupt input from the ADC, but note that the trigger signal from the ADC may be to short to be properly recognized by the MCU and
 // some extra electronics is required to make this reliably work (see readme).
 using (var controller = new GpioController(PinNumberingScheme.Logical))
 {

devices/Ads1115/samples/InterruptResult.png devices/Ads1115/InterruptResult.png

@@ -1,12 +1,35 @@
 # ADXL345 - Accelerometer
+
 ADXL345 is a small, thin, low power, 3-axis accelerometer with high resolution (13-bit) measurement at up to ±16g.
 
+## Documentation
+
+In [Chinese](http://wenku.baidu.com/view/87a1cf5c312b3169a451a47e.html)
+
+In [English](https://www.analog.com/media/en/technical-documentation/data-sheets/ADXL345.pdf)
+
 ## Sensor Image
-![](sensor.jpg)
+
+![sensor](sensor.jpg)
 
 ## Usage
-```C#
-SpiConnectionSettings settings = new SpiConnectionSettings(0, 0)
+
+**Important**: make sure you properly setup the SPI pins especially for ESP32 before creating the `SpiDevice`, make sure you install the `nanoFramework.Hardware.ESP32 nuget`:
+
+```csharp
+//////////////////////////////////////////////////////////////////////
+// when connecting to an ESP32 device, need to configure the SPI GPIOs
+// used for the bus
+Configuration.SetPinFunction(21, DeviceFunction.SPI1_MOSI);
+Configuration.SetPinFunction(22, DeviceFunction.SPI1_MISO);
+Configuration.SetPinFunction(23, DeviceFunction.SPI1_CLOCK);
+// Make sure as well you are using the right chip select
+```
+
+For other devices like STM32, please make sure you're using the preset pins for the SPI bus you want to use. The chip select can as well be pre setup.
+
+```csharp
+SpiConnectionSettings settings = new SpiConnectionSettings(1, 42)
 {
     ClockFrequency = Adxl345.SpiClockFrequency,
     Mode = Adxl345.SpiMode
@@ -24,7 +47,54 @@ using (Adxl345 sensor = new Adxl345(device, GravityRange.Range04))
 }
 ```
 
-## References
-In Chinese : http://wenku.baidu.com/view/87a1cf5c312b3169a451a47e.html
+## Example
+
+### Hardware Required
+
+* ADXL345
+* Male/Female Jumper Wires
+
+## Circuit
+
+![cicuit](ADXL345_circuit_bb.png)
+
+* VCC - 3.3 V
+* GND -  GND
+* CS - CS
+* SDO - SPI1 MISO
+* SDA - SPI1 MOSI
+* SCL - SPI1 SCLK
+
+### Code
+
+```csharp
+SpiConnectionSettings settings = new SpiConnectionSettings(1, 42)
+{
+    ClockFrequency = Adxl345.SpiClockFrequency,
+    Mode = Adxl345.SpiMode
+};
+var device = SpiDevice.Create(settings);
+
+// Set gravity measurement range ±4G
+using (Adxl345 sensor = new Adxl345(device, GravityRange.Range04))
+{
+    // loop
+    while (true)
+    {
+        // read data
+        Vector3 data = sensor.Acceleration;
+
+        Debug.WriteLine($"X: {data.X.ToString("0.00")} g");
+        Debug.WriteLine($"Y: {data.Y.ToString("0.00")} g");
+        Debug.WriteLine($"Z: {data.Z.ToString("0.00")} g");
+        Debug.WriteLine();
+
+        // wait for 500ms
+        Thread.Sleep(500);
+    }
+}
+```
+
+### Result
 
-In English : https://www.analog.com/media/en/technical-documentation/data-sheets/ADXL345.pdf
+![running result](RunningResult.jpg)

devices/Ads1115/README.md

@@ -8,7 +8,14 @@
 using Iot.Device.Adxl345;
 using System.Diagnostics;
 
-SpiConnectionSettings settings = new(0, 0)
+//////////////////////////////////////////////////////////////////////
+// when connecting to an ESP32 device, need to configure the SPI GPIOs
+// used for the bus
+//Configuration.SetPinFunction(21, DeviceFunction.SPI1_MOSI);
+//Configuration.SetPinFunction(22, DeviceFunction.SPI1_MISO);
+//Configuration.SetPinFunction(22, DeviceFunction.SPI1_CLOCK);
+// Make sure as well you are using the right chip select
+SpiConnectionSettings settings = new(1, 42)
 {
     ClockFrequency = Adxl345.SpiClockFrequency,
     Mode = Adxl345.SpiMode