powershell / powershell-iot

Interact with I2C, SPI & GPIO devices using PowerShell Core!

PowerShell-IoT

Note: PowerShell IoT is still in Preview

A PowerShell module for interacting with hardware sensors and devices using common protocols: GPIO, I2C & SPI.

Information

Goals

The main goal of this project is to provide a friendly interface for interacting with hardware sensors and devices using PowerShell.

That said, it was built as close to the metal as possible to keep the library broad enough to cover a range of sensors and devices.

The hope is that this module will be the foundation for other modules that will expose specific cmdlets for interacting with specific sensors and devices.

For example, a cmdlet stack to turn on a light bulb might be:

> Set-Light On # Your user types this / you make this cmdlet
> Set-GpioPin -Id 4 -Value High # You use this to make that^ / we make this cmdlet
> # Our code that makes that^

To see some examples of modules built on top of PowerShell IoT, see the Examples folder.

Supported platforms

Supported devices

• Raspberry Pi 3
• Raspberry Pi 2

Supported operating systems

• Raspbian Stretch

Documentation & Examples

Please see our docs folder here for an API reference, pin layout and other docs. For examples, checkout our examples folder.

Dependencies

This project relies on .NET Core IoT Libraries. It is a .NET library for interacting with Raspberry Pi's IO functionality.

Installation

PowerShell Gallery

You can grab the latest version of PowerShell IoT by running:

Install-Module Microsoft.PowerShell.IoT

Please note that since this module works with Hardware, higher privileges are required (run PowerShell with sudo, or as root user)

Then see the section on running.

If you want to write a module that uses PowerShell IoT, include it in the RequiredModules field of your module manifest.

GitHub releases

You can also manually download the zipped up module from the releases.

Then see the section on running.

AppVeyor

You can download the latest CI build from our AppVeyor build here. Go to the latest build, click on either of the images, then click on the artifacts tab. From there, you can download a zip of the latest CI build.

Then see the section on running.

From Source

Prerequisites

• PowerShell Core 6 or greater
• .NET Core SDK 2.0 or greater
• InvokeBuild
• A supported device like a Raspberry Pi 3 with PowerShell Core 6 on it

Building

NOTE: You can't build on ARM devices at this time so you will need to build on another machine and copy the build to the device.

1. Clone/download the repo
2. run ./build.ps1 -Bootstrap to see if you're missing any tooling
3. run ./build.ps1 to build

At this point, you'll notice an out folder has been generated in the root of your repo. The project is ready to be deployed to your device.

Deploying

We have included a helper script, Move-PSIoTBuild.ps1, that will move the PowerShell IoT build over to your device. This copy uses PSRP over SSH so make sure you're able to connect to your pi this way. The Microsoft.PowerShell.IoT module will be copied to your $env:PSModulePath on your device. Here's an example:

Move-PSIoTBuild.ps1 -Ip 10.123.123.123 # IP address of device

You can also easily copy examples in the Examples folder over using the -WithExample flag. Just give a list of examples you want to copy over and it will move those to you $env:PSModulePath along with Microsoft.PowerShell.IoT:

Move-PSIoTBuild.ps1 -Ip 10.123.123.123 -WithExample Microsoft.PowerShell.IoT.Plant,Microsoft.PowerShell.IoT.SSD1306

Also, with the -Build parameter, it will build/test/package your project before moving it.

NOTE: If you'd rather not use the script, simply copy the out/Microsoft.PowerShell.IoT to your device to get started.

Running

Start PowerShell:

pwsh

If you have the Microsoft.PowerShell.IoT module in your PSModulePath:

Import-Module Microsoft.PowerShell.IoT

Alternatively, just import the .psd1:

Import-Module /path/to/Microsoft.PowerShell.IoT/Microsoft.PowerShell.IoT.psd1

At this point you can now mess with the module:

Get-Command -Module Microsoft.PowerShell.IoT
Get-GpioPin 2 # gets the data from GPIO pin 2

Testing

You can run tests, but they require a particular setup. Here is how you run them:

./build.ps1 -Test

The setup required:

• For I2C: An Adafruit BME280 I2C or SPI Temperature Humidity Pressure Sensor
• 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

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.

powershell-iot's Issues

Support other devices

Allow this to be the issue where folks as for specific devices 😄

I'll start.

One of the Particle boards: https://www.particle.io/

NOTE: this is bounded by .NET Core's ability

Support Windows IoT

The library we are using Unosquare.Raspberry.IO only uses the linux binaries of wiring pi.

We should contribute to that project to get support for Windows IoT so that we can leverage that here.

That repo:
https://github.com/unosquare/raspberryio

Enable Oversampling parameter in BME280 module

Get-BME280Data/Set-BME280Config functions have Oversampling parameter, but it currently does nothing.
This parameter should be tied to binary value used in Set-BME280Config function according to sensor datasheet.
Currently oversampling of data is set to ×2 by constants like this: [Convert]::ToByte("01001001",2).
This should be changed to be based on Oversampling parameter.

Combining Device Address & Start Command ADS 1115

Prerequisites

• Write a descriptive title.
• Make sure you are able to repro it on the latest version
• Search the existing issues.

Steps to reproduce

When using the PS IOT module to communicate with the TI ADS 1115 TI ADS 1115 Documentation on the i2c bus the commands on the module are not activating the module and the conversation is not starting with the chip. I think it is because the chip is expecting a START command after the REGISTER call to initiate the conversation.

$device = Get-i2cDevice -Id 0x48
$device Returns ID 72 & BUSID 1
Get-i2CRegister -Device $device -Register 0x01 2
Returns
Device 72, Register 1, Data 133,131.

I need to change the first data bit from 133 to 132 to start a continuous conversation.

If I use the -passThru command with set the chip is returning the changed values. However a subsequent query show the same 133, 131.
> Set-I2CRegister -device $device -Register 0x01 -data 132, 131 -passthru
returned:
Device Register Data

---

72 1 {132, 131}

But Get-I2CRegister -Device $device -register 0x01 2
returns:
Device Register Data

---

72 1 {133, 131}

Expected behavior

Set-I2CRegister -device $device -Register 0x01 -data 132, 131 -passthru`
and
'Get-I2CRegister -Device $device -register 0x01 2'
should return
Device Register Data
------ -------- ----
72            1 {132, 131}

Actual behavior

Set-I2CRegister -device $device -Register 0x01 -data 132, 131 -passthru`
and
'Get-I2CRegister -Device $device -register 0x01 2'
should return
Device Register Data
------ -------- ----
72            1 {133, 131}

Error details

Get-error no error is returned.

Environment data

PS /home/pi> $PSVersionTable

Name                           Value
----                           -----
PSVersion                      7.2.5
PSEdition                      Core
GitCommitId                    7.2.5
OS                             Linux 5.15.32-v7+ #1538 SMP Thu Mar 31 19:38:48…
Platform                       Unix
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0…}
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1
WSManStackVersion              3.0

Version

7.2.5

Visuals

na

Support Alternate i2c bus 4

I'm working on a project with two i2c devices, a RTC (Adafruit 4282) 0x68 and a OLED (SSD1306) 0x3C. I can get them both to show up but they are on different busses. The RTC module uses bus 1 and I have configured dtoverlay to create bus 4 (SDA to GPIO 23 and SCL to GPIO 24) to which I have the OLED connected. However, I can't communicate with anything on bus 4 using this powershell module, only Python. (https://github.com/adafruit/Adafruit_Python_Extended_Bus)

impact of 'wiringPI - deprecated' as this library is build on top if it?

Deprecate annoncement

I will make a final release of wiringPi available soon – with the sources, but that’s that. No more public releases. I’ll still be maintaining it for my own uses and clients, but for everyone else, please look at for alternative GPIO library for on-going projects.

-Gordon, August, 2019
Is an alternative GPIO library considered to replace wiringPI ?

Move off of 6.0.0-rc2 version of PowerShell SDK

This should either be a release version of the PowerShell SDK or PowerShell Standard:

https://github.com/PowerShell/PowerShell-IoT/blob/master/src/Microsoft.PowerShell.IoT/Microsoft.PowerShell.IoT.csproj#L8

Support Raspberry Pi 4

The title says it all. The Raspberry Pi 4 has been out for about a year and is by far the most-prevalent RPi hardware being deployed at this point. It'd be great if it was supported.

Support Raspberry Pi OS / Raspbian Buster

The title says it all :) These newer versions of Raspberry Pi OS (formerly known as Raspbian) have been out for over a year at this point; they should be supported.

GpioPin changes

On the new library, the GPIO is controlled by a GpioController instance (here's the class).
As far as I've understood, there should be only 1 controller "active" (1 instance at the time). For that reason, I've decided that it was a better approach to have the *-GpioPin to receive the controller, similar to what's being done with the I2C device. This avoids the overload of creating a controller per command execution, and allows us to keep context of the pins through the controller.
This also requires that we have a new cmdlet to create a Controller (Get-GpioController ?)

Another thing to keep in mind is that we should have a way do properly dispose the controller, if the user doesn't do so (see here).

Another breaking change is that this library does not use the PullMode like we currently have. Instead, they have a PinMode (here's the source). This is used when opening a pin/setting its mode

_controller.OpenPin(_echo, PinMode.Input);
_controller.OpenPin(_trigger, PinMode.Output);

(source)

As a final note, we now have to pay special attention to opening/closing pins while developing our cmdlets, in order to avoid potential bugs where pins are left open, or are wrongly closed :)

Here's a snippet with an example on how to get a pin info

$controller = Get-GpioController #if no scheme is specified, use the default one

$pin = Get-GpioPin -Controller $controller -Id 5 -PinMode Input

Convert-FromBinary function

Since this module communicates with hardware and hardware uses a lot of binary "communication", it could make it easier (and more readable) to understand the "low-level" code if we had a function that would convert our binary value to an int. For what I've searched, there is no powershell native function to do so.
For example, if I see that a register needs the following value:
0001 1010
I can create as $value = 0x1A, or $value = 26.
The suggestion would be something like :
$value = Convert-FromBinary '0001 1010'
Do you think that this would be useful?

API Reference Link 404ed

Any chance you can update the API reference link in the docs section?

https://github.com/PowerShell/PowerShell-IoT/blob/master/docs/api_reference.md

Allow the registering of change events

It would look something like this:

Register-GpioPinChangeEvent -Type LowToHigh -ScriptBlock {
    Write-Host "do the thing"
}

# and

Register-GpioPinChangeEvent -Type HighToLow -ScriptPath foo.ps1

Under the hood it could use Register-ObjectEvent to allow the script execution to be in the same runspace.

Unosquare docs here:
https://github.com/unosquare/raspberryio#interrupts-and-callbacks

Relying on old version of WiringPi breaks Pi4 compatibility

The module installs fine on Raspberry Pi 4, but it's not actually possible to interact with GPIO. Error message after running Get-GpioPin:

Unable to determine hardware version. I see: Hardware : BCM2711
,

• expecting BCM2708, BCM2709 or BCM2835.
  If this is a genuine Raspberry Pi then please report this
  to [email protected]. If this is not a Raspberry Pi then you
  are on your own as wiringPi is designed to support the
  Raspberry Pi ONLY.

This is caused by an older version of WiringPi that doesn't recognize the updated hardware in the Raspberry Pi 4. The author published a newer version (2.52) that adds support for the Pi 4: http://wiringpi.com/wiringpi-updated-to-2-52-for-the-raspberry-pi-4b/

I installed this version on my Pi and can confirm with gpio -v:

gpio version: 2.52
Copyright (c) 2012-2018 Gordon Henderson
This is free software with ABSOLUTELY NO WARRANTY.
For details type: gpio -warranty

Raspberry Pi Details:
Type: Pi 4B, Revision: 01, Memory: 2048MB, Maker: Sony

• Device tree is enabled.
  *--> Raspberry Pi 4 Model B Rev 1.1
• This Raspberry Pi supports user-level GPIO access.

This does not resolve the issue, the cmdlets still fail. It would be great if this module could support the latest WiringPi version.

[Opinion request] Bluetooth Support

Hey. As the title implies, I would like to get some opinions about supporting bluetooth on this module. As far as I've seen, there are some C# implementations on bluetooth serialport communication.
Disclaimer: I'm not really familiar with bluetooth protocols and whatsoever, so I don't really know the implications or even if it's doable (but at least it seems).

Context: There are some devices that use bluetooth protocol to communicate. In this case I was thinking about the Sphero droids that currently use JavaScript and/or Scratch. In this very same case, it's more complicated because they do not expose an API to communicate with the droids (but that's another question). I've seen a implementation to communicate with them that used a javascript library . Maybe we can use some of the C# bluetooth projects?

Does this make any sense?

Not all code files start with a copyright header

Source code files should start with a header such as the following:

// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.

Need to change NestedModules to RequiredModules in psd1s for examples

This is the correct way to specify a dependency. With NestedModules set to Microsoft.PowerShell.IoT, the cmdlets in Microsoft.PowerShell.IoT get exposed in the global scope which isn't clean.

Detect if I2C is enable and possibly enable it if user agrees

For what I've seen, enable the I2C "manually" seems quite easy, only requiring to edit:

• the /etc/modules file to add i2c-dev
• the /boot/config.txt file and uncomment the dtparam=i2c_arm=on entry.

If this is all that it takes, when the user imports this module, we can check if the i2c is already enabled and display a warning if it's not. Even better would be to prompt the user if he wants to enable it (avoiding the process of running sudo raspi-config and search for that).

Does this seems feasible/ make sense?

Change of pin layout

With the migration to the dotnet/iot framework, breaking changes will be introduced.
For this case, the dotnet team uses same layout that's used by the python library. This means that from now on, the pin Ids will match those in that library. Another reason is that the wiringpi has been officially deprecated
As a suggestion, here's the website that I use to check the pin ids.

Set-i2cdevice overload to support arrays

I think it would be good to have an overload that would accept an array of registers and an array of values to be set on those registers, 'freeing' the developer to have the necessity to create a loop to iterate each array and set each value

Getting RAW data

When I have something like a photo resistor connected a GPIO pin. How can I get the actual resistance instead of High/Low?

Better Error handling for wrong arch and not using sudo

Right now the error looks like this:

Get-I2CDevice : The type initializer for 'Unosquare.RaspberryIO.Pi' threw an exception.
At line:1 char:1
+ Get-I2CDevice
+ ~~~~~~~~~~~~~
+ CategoryInfo          : NotSpecified: (:) [Get-I2CDevice], TypeInitializationException
+ FullyQualifiedErrorId : System.TypeInitializationException,Microsoft.PowerShell.IoT.GetI2CDevice

It should say "not supported arch" or "not using sudo"

Add API reference

Use PlatyPS

Multiple Links in Examples > README.md are dead

The following README.md files has non-functioning links under "Software setup"

https://github.com/PowerShell/PowerShell-IoT/blob/master/Examples/Microsoft.PowerShell.IoT.ADXL345/README.md
https://github.com/PowerShell/PowerShell-IoT/blob/master/Examples/Microsoft.PowerShell.IoT.BME280/README.md
https://github.com/PowerShell/PowerShell-IoT/tree/master/Examples/Microsoft.PowerShell.IoT.Fan/README.md
https://github.com/PowerShell/PowerShell-IoT/blob/master/Examples/Microsoft.PowerShell.IoT.LED/README.md
https://github.com/PowerShell/PowerShell-IoT/blob/master/Examples/Microsoft.PowerShell.IoT.Plant/README.md
https://github.com/PowerShell/PowerShell-IoT/blob/master/Examples/Microsoft.PowerShell.IoT.Scroll_pHat/README.md

They should be replaced from:
https://github.com/PowerShell/PowerShell/tree/master/docs/installation/linux.md#raspbian

To:
https://github.com/MicrosoftDocs/PowerShell-Docs/blob/d5263484cf6f29148b6e07c7b3e1d9376a5fd635/reference/docs-conceptual/install/install-raspbian.md#raspberry-pi-os

Set-gpiopin not working as expected

I set everything up on the pi and built a small led circuit on a breadboard with gpio #18. I run
set-gpiopin -id 18 -value High and the Led does nothing.

I try the same via python code and works no issues.

Am I missing something here?

SPI implementation

I'm opening this issue so that we can discuss the implementation of the SPI interface. I'm not familiar with this interface, but from my understanding (and from what I'm seeing on the dotnet repo), this seems that the SPI device could be created once and used many times, whereas with current implementation, each time we are sending that through SPI, we are creating a new device and then disposing it.
Would it make sense to have a similar approach to what we have on I2C ? Something like

Get- SPIDevice -BusId 0 -Frequency 2400 ...

Have a 'Type' for GPIO Object that can be input or output

Hi,

Using Get-GpioPin on a pin will force its level to 'low'.

To reproduce (even if the pin is not connected to anything):

Set-GpioPin -Id 0 -Value High

The pin is high.

Get-GpioPin -Id 0

Returns:

Id Value PinInfo
-- ----- -------
 0   Low Unosquare.RaspberryIO.Gpio.GpioPin

And the pin is low :-/

Get-I2CRegister or Set-I2CRegister crash PowerShell if device is unreachable

Hi,

If the device provided to Get or Set-I2CRegister commands is not reachable, PowerShell crash with message:

*** Error in `pwsh': free(): invalid pointer: 0x76d35694 ***
Aborted

To reproduce (do not connect anything on I2C bus):

$Device = Get-I2CDevice -ID 0x54 -FriendlyName 'accelerometer'
Get-I2CRegister -Device $Device -Register 0x00

PowerShell version:

Name                           Value
----                           -----
PSVersion                      6.0.2
PSEdition                      Core
GitCommitId                    v6.0.2
OS                             Linux 4.14.30-v7+ #1102 SMP Mon Mar 26 16:45:49 BST 2018
Platform                       Unix
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0...}
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1
WSManStackVersion              3.0