Misc docs updates (#30)

* WIP LED example

* add led doc and remoting doc

* misc feedback

* change resistor ohms

* ohms range

Author: TylerLeonhardt

Diff for: Examples/Microsoft.PowerShell.IoT.LED/Microsoft.PowerShell.IoT.LED.psd1

@@ -0,0 +1,29 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+@{
+    GUID="0432ee36-7e87-4a21-814f-8feb17974641"
+    Author="Microsoft Corporation"
+    CompanyName="Microsoft Corporation"
+    Copyright="© Microsoft Corporation. All rights reserved."
+    Description='PowerShell module for working with a single-color LED.'
+    ModuleVersion="0.1.0"
+    FunctionsToExport = @('Set-Led')
+    CmdletsToExport = '*'
+    AliasesToExport = @()
+    NestedModules=@('Microsoft.PowerShell.IoT','Microsoft.PowerShell.IoT.LED.psm1')
+    HelpInfoURI = 'https://github.com/PowerShell/PowerShell-IoT'
+    # Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.
+    PrivateData = @{
+        PSData = @{
+            # Tags applied to this module. These help with module discovery in online galleries.
+            Tags = 'IoT','RaspberryPi','Raspbian','LED'
+
+            # A URL to the license for this module.
+            LicenseUri = 'https://github.com/PowerShell/PowerShell-IoT/blob/master/LICENSE.txt'
+
+            # A URL to the main website for this project.
+            ProjectUri = 'https://github.com/PowerShell/PowerShell-IoT'
+        }
+    }
+}

Diff for: Examples/Microsoft.PowerShell.IoT.LED/Microsoft.PowerShell.IoT.LED.psm1

@@ -0,0 +1,24 @@
+function Set-Led
+{
+    [CmdletBinding()]
+    param
+    (
+        [Parameter(Mandatory=$true, Position=0, ValueFromPipelineByPropertyName="Pin")]
+        [ValidateNotNullOrEmpty()]
+        [string] $Pin,
+
+        [Parameter(Mandatory=$true, Position=1, ValueFromPipelineByPropertyName="State")]
+        [ValidateSet('On','Off',ignorecase=$true)]
+        [string] $State
+    )
+    if ($State -eq 'On')
+    {
+        $value = "High"
+    }
+    else
+    {
+        $value = "Low"
+    }
+
+    Set-GpioPin -Id $Pin -Value $value
+}

Diff for: Examples/Microsoft.PowerShell.IoT.LED/README.md

@@ -0,0 +1,52 @@
+# Example module Microsoft.PowerShell.IoT.LED
+
+This simple PowerShell module is for turning on/off a single color LED.
+
+![An LED is on](https://i.imgur.com/nJPJ9Vk.jpg)
+
+This showcases GPIO functionality of [the Microsoft.PowerShell.IoT module](../../README.md).
+
+## Hardware setup
+
+Hardware pieces:
+
+* [Breadboard](https://en.wikipedia.org/wiki/Breadboard) (Optional)
+* Male to female [jumper wires](https://en.wikipedia.org/wiki/Jump_wire)
+* 1 270-330Ω resistor
+* A [single-color LED](http://upload.wikimedia.org/wikipedia/commons/e/e8/LEDs.jpg)
+
+## Wiring diagram
+
+![wiring](https://i.imgur.com/lCaxMWZ.png)
+
+## Software setup
+
+### Install PowerShell Core on Raspberry Pi
+
+Installation instructions can be found [here](https://github.com/PowerShell/PowerShell/tree/master/docs/installation/linux.md#raspbian).
+
+### Start Powershell and install modules
+
+```powershell
+sudo pwsh
+
+Install-Module -Name Microsoft.PowerShell.IoT
+
+git clone https://github.com/PowerShell/PowerShell-IoT.git
+
+Import-Module ./PowerShell-IoT/Examples/Microsoft.PowerShell.IoT.LED
+```
+
+### Usage
+
+```powershell
+# Turn LED on
+Set-Led -Pin 1 -State On
+# or
+Set-Led 1 On
+# or
+[PSCustomObject]@{Pin=1; State="On"} | Set-Led
+
+# Turn LED off
+Set-Led 1 Off
+```

Diff for: Examples/Microsoft.PowerShell.IoT.Plant/README.md

@@ -49,11 +49,11 @@ Import-Module ./PowerShell-IoT/Examples/Microsoft.PowerShell.IoT.Plant
 PS /home/pi> # working with light
 PS /home/pi> Set-Light On
 PS /home/pi> Set-Light Off
-PS /home/pi> 
+PS /home/pi>
 PS /home/pi> # working with water
 PS /home/pi> Start-Water
 PS /home/pi> Stop-Water
-PS /home/pi> 
+PS /home/pi>
 PS /home/pi> # reading soil moisture level
 PS /home/pi> Read-SoilIsDry
 ```
@@ -64,4 +64,4 @@ See `full-plant-demo.ps1`.
 
 This script runs 2 PS jobs - one controls light, the other - water.
 
-For demo purposes script runs for 2 minutes. Adjust timeouts in the script for your scenario.
+For demo purposes script runs for 2 minutes. Adjust timeouts in the script for your scenario.

Diff for: Examples/README.md

@@ -0,0 +1,12 @@
+# Examples
+
+Example modules that leverage PowerShell IoT in a specific way.
+
+## Table of Contents
+
+| Example | Difficulty | Type |
+|---------|------------|------|
+| [Microsoft.PowerShell.IoT.LED](/Examples/Microsoft.PowerShell.IoT.LED) | Easy | GPIO |
+| [Microsoft.PowerShell.IoT.BME280](/Examples/Microsoft.PowerShell.IoT.BME280) | Medium | I2C |
+| [Microsoft.PowerShell.IoT.SSD1306](/Examples/Microsoft.PowerShell.IoT.SSD1306) | Medium | I2C |
+| [Microsoft.PowerShell.Plant](/Examples/Microsoft.PowerShell.IoT.Plant) | Hard | GPIO |

Diff for: README.md

@@ -154,11 +154,16 @@ Get-GpioPin 2 # gets the data from GPIO pin 2
 
 #### Testing
 
-You can run tests,
-but they don't do anything right now:
+You can run tests, but they require a particular setup. Here is how you run them:
 
 ```powershell
 ./build.ps1 -Test
 ```
 
-We will investigate standing up a test rig of supported devices and OS's so that we can test against actual hardware.
+The setup required:
+
+* For I2C: An [Adafruit BME280 I2C or SPI Temperature Humidity Pressure Sensor](https://www.adafruit.com/product/2652)
+* For GPIO: Bend pins 26 and 22 to touch each other or connect them in some way
+* For SPI:  An [Adafruit LIS3DH Triple-Axis Accelerometer](https://www.adafruit.com/product/2809)
+
+We currently have a build agent that will deploy PR code onto a test Raspberry Pi and run the tests found in the `test` directory.

Diff for: docs/README.md

@@ -5,4 +5,5 @@ This folder contains documentation on how to get started with PowerShell IoT and
 ## Table of contents
 
 * [Raspberry Pi 3 Pin layout](/docs/rpi3_pin_layout.md)
-* [API reference](/docs/api_reference.md)
+* [Remoting via SSH](/docs/remoting.md)
+* [API reference](/docs/api_reference.md)

Diff for: docs/remoting.md

@@ -0,0 +1,62 @@
+# SSH Remoting Docs
+
+> NOTE: These docs were created while using a Raspberry Pi 3 with Raspbian Stretch.
+
+## Prereqs
+
+First you need to get the IP address of the device. You can do this by running this on the device:
+
+```bash
+PS > hostname -I
+
+123.123.123.123 <ignore this extra stuff>
+```
+
+You also need to have [PowerShell Core](https://github.com/powershell/powershell) installed on your device.
+
+You'll also need some SSH client. macOS and linux have it installed by default, for Windows, check out the [Win32 port of OpenSSH](https://github.com/PowerShell/Win32-OpenSSH/wiki/Install-Win32-OpenSSH).
+
+## Using pure SSH
+
+First ssh into your pi:
+
+```plaintext
+> ssh [email protected]
+
+# At this point you are remoted into to the device and can start PowerShell
+
+> sudo pwsh
+PS > Get-GpioPin 1
+```
+
+## Using PowerShell Remoting (PSRP) over SSH
+
+> NOTE: This will only work if your device doesn't require a password when you run `sudo pwsh`. The Raspberry Pi 3 with default configuration does not prompt.
+
+First you need to install [PowerShell Core](https://github.com/powershell/powershell) on your client machine. Windows PowerShell does not support PowerShell Remoting (PSRP) over SSH so that will not work.
+
+Second you need to set up PSRP over SSH. You can [follow this guide](https://github.com/PowerShell/PowerShell/blob/11631e7412197f3f803ebbef95a3ddb174a387ec/demos/SSHRemoting/README.md).
+
+When you get to the part where it says:
+
+> Add a PowerShell subsystem entry
+
+Put this:
+
+```plaintext
+Subsystem powershell sudo pwsh -sshs -NoLogo -NoProfile
+```
+
+Note the use of `sudo`.
+
+If done correctly, you should be able to run:
+
+```powershell
+PS > Enter-PSSession -Hostname 123.123.123.123 -UserName pi
+
+# At this point you are remoted into to the device already in PowerShell
+
+[123.123.123.123] PS > Get-GpioPin 1
+```
+
+By doing this, you should be able to automate working with your device using PowerShell 🎉