A simple, low-ceremony GPIO library for all your IoT needs
SimpleGPIO
takes a high-level, object-oriented approach to IoT programming, in the same way that high-level programming languages provide features that help abstract what's happening on the metal away from the code.
SimpleGPIO
is a .NET Standard 2.0 library, and therefore should work with all actively supported .NET runtimes.
Simply add the SimpleGPIO
library to your project from NuGet.
Instantiate a new board to be able to access its GPIO header:
var pi = new RaspberryPi();
If you're using a dependency injection container, you can register the board as a singleton to be used elsewhere in the application:
services.AddSingleton<RaspberryPi>();
GPIO pins can be accessed by both their physical location on the board, and/or their Broadcom identifier GPIO#.
var redLED = pi.Pin16;
var sameRedLED = pi.GPIO23;
SimpleGPIO
provides many ways to turn power on or off, depending on your preferences.
The simplest way is to use the built-in helper methods:
redLED.TurnOn();
redLED.TurnOff();
If you prefer assigning values:
redLED.Power = PowerValue.On;
redLED.Power = PowerValue.Off;
At the lowest level, you can directly set the voltage going out of the pin:
redLED.Voltage = Voltage.High; //on
redLED.Voltage = Voltage.Low; //off
All of the above examples assume the default Direct
power mode, where the positive terminal of the LED is connected to the GPIO pin, and the negative terminal is connected to the ground pin.
If, instead, you want to supply constant power by, e.g. the 3v3 pin, and the have the GPIO pin supply (or not supply) resistance, you can use the Differential
power mode, where PowerValue.On == Voltage.Low
and PowerValue.Off == Voltage.High
:
var yellowLED = pi.Pin18;
yellowLED.PowerMode = PowerMode.Differential;
yellowLED.TurnOn();
Pins can be turned on or off for specific lengths of time via the following:
var led = pi.Pin18;
led.TurnOnFor(TimeSpan.FromSeconds(1)); //will turn off after 1 second
led.TurnOn();
led.TurnOffFor(TimeSpan.FromSeconds(0.5)); //will turn back on after 0.5 seconds
There are some helper methods for toggling values. If power is currently on, toggling it will turn it off; if power is off, toggling will turn it on:
redLED.Toggle();
If you want to repeat the toggle at a given frequency, for a set amount of time, pass in the frequency and a TimeSpan
as parameters:
redLED.Toggle(3, TimeSpan.FromSeconds(5));
This will flash the red LED 3 times per second, for 5 seconds.
Alternatively, you can toggle power a set number of times by passing in a number as the second parameter. The following will flash the red LED 3 times over 1.5 seconds:
redLED.Toggle(2, 3);
Pins can have their "strength" set using Pulse Width Modulation (PWM) via the Strength
property on the pin:
var led = pi.Pin18;
led.Strength = 50; //valid range: 0-100
There are also several helper methods to make smooth transitions easier:
led.FadeIn(TimeSpan.FromSeconds(1));
led.FadeOut(TimeSpan.FromSeconds(2));
led.FadeTo(50,TimeSpan.FromSeconds(0.5));
led.Pulse(TimeSpan.FromSeconds(1));
led.Pulse(50, TimeSpan.FromSeconds(1));
Input components such as buttons can be declared the same way as output components, and the Power
and Voltage
can be read from the new variable:
var button = pi.Pin11;
var isPressed = button.Power == PowerValue.On;
The Direct
Power Mode for an input component expects power from e.g. the 3v3 pin, so that electricity flows through to the GPIO pin when the button is depressed.
Three methods are provided on a pin that accept an Action
as a parameter, so that when that pin's state changes, some subsequent steps can be performed:
var button = pi.Pin11;
var redLED = pi.Pin16;
var buzzer = pi.Pin18;
button.OnPowerOn(() => redLED.TurnOn());
button.OnPowerOff(() => redLED.TurnOff());
redLED.OnPowerChange(() => buzzer.Toggle(1, 1));
Whenever the button is pressed down, the LED will turn on. When the button is released, the LED will turn off. Whenever the LED turns on or off, the buzzer will beep for half a second (reminder why: because Toggle will complete a single cycle at 1Hz, which means 0.5s on, then 0.5s off).
If you want to turn off everything that was turned on while your application was running, simply Dispose()
of your RaspberryPi
at the end of your code.
pi.Dispose();
This will turn off and close all open GPIO pins. As with all IDisposable
s, this also works if you wrap the RaspberryPi
you're using in a using(){}
block.
Several components have been implemented to help make development easier.
The RGB LED contains a separate pin for red, green, and blue, which can be combined to show different colors.
var redPin = pi.Pin11;
var greenPin = pi.Pin16;
var bluePin = pi.Pin18;
var rgbLED = new RGBLED(redPin, greenPin, bluePin);
Colors can then be set using the SetColor()
method:
rgbLED.SetColor(Color.Red);
rgbLED.SetColor(Color.Yellow);
rgbLED.SetColor(Color.Purple);
Several helpers also exist:
rgbLED.FadeTo(Color.White, TimeSpan.FromSeconds(1));
rgbLED.Pulse(Color.Green, TimeSpan.FromSeconds(0.5));
rgbLED.TurnOff(); // same as rgbLED.SetColor(Color.Black);
See the example for more details.
Rotary encoders have actions that can be performed when the dial is turned.
var dial = new RotaryEncoder(clockPin, dataPin);
dial.OnIncrease(() => Console.WriteLine("up"));
dial.OnDecrease(() => Console.WriteLine("down"));
Built-in button functionality is not yet supported.
See the example for more details.
Seven-segment displays are currently supported for direct connections to GPIO pins (support for shift register input coming soon) and can be passed a character (all ASCII letters, numbers, and several other symbols)
var segments = new PinSet
{
Center = centerPin,
UpperLeft = upperLeftPin,
Top = topPin,
UpperRight = upperRightPin,
LowerLeft = lowerLeftPin,
Bottom = bottomPin,
LowerRight = lowerRightPin,
Decimal = decimalPin //optional
};
var display = new SevenSegmentDisplay(segments);
display.Show('A');
display.Show('B');
display.Show('C');
display.Show('1');
display.Show('2');
display.Show('3');
Custom characters can also be displayed passing a PowerSet
to SetPowerValues()
:
var custom = new PowerSet
{
Center = PowerValue.On,
UpperLeft = PowerValue.Off,
Top = PowerValue.On,
UpperRight = PowerValue.Off,
LowerLeft = PowerValue.On,
Bottom = PowerValue.Off,
LowerRight = PowerValue.On,
Decimal = PowerValue.Off //optional
};
display.SetPowerValues(custom);
See the example for more details.
The dot matrix display required 16 inputs, one for each row and one for each column. Like the seven segment display, these are initialized via a PinSet
, with pins numbered counter-clockwise starting from the bottom left:
var set = new DotMatrix.PinSet
{
//rows
Pin1 = pi.GPIO5, Pin2 = pi.GPIO7, Pin3 = pi.GPIO12, Pin4 = pi.GPIO13, Pin5 = pi.GPIO8, Pin6 = pi.GPIO15, Pin7 = pi.GPIO6, Pin8 = pi.GPIO3,
//columns
Pin9 = pi.GPIO1, Pin10 = pi.GPIO14, Pin11 = pi.GPIO16, Pin12 = pi.GPIO4, Pin13 = pi.GPIO11, Pin14 = pi.GPIO2, Pin15 = pi.GPIO17, Pin16 = pi.GPIO18
};
var matrix = new DotMatrix(set);
You can then set rows or columns individually or all together:
matrix.SetAllRows(PowerValue.On);
matrix.SetAllColumns(PowerValue.Off);
matrix.SetRows(new DotMatrix.PowerSet { ... });
matrix.SetColumns(new DotMatrix.PowerSet { ... });
See the example for more details.
The wiring required to safely run a motor is rather complicated. The code, however, can be quite eloquent. The Motor
component assumes an L293D-compatible driver.
var enabledPin = pi.Pin11;
var clockwisePin = pi.Pin13; //name assumes connected to L293D pin 1A
var counterclockwisePin = pi.Pin15; // name assumes connected to L293D pin 2A
var motor = new Motor(enabledPin, clockwisePin, counterclockwisePin);
motor.Direction = Rotation.Clockwise;
motor.Start();
motor.Stop();
motor.Direction = Rotation.Counterclockwise;
motor.Start();
motor.Coast();
motor.TurnClockwise();
motor.TurnCounterclockwise();
motor.TurnClockwiseFor(TimeSpan.FromSeconds(1));
motor.TurnCounterclockwiseFor(TimeSpan.FromSeconds(2), true); //optional parameter to coast instead of stop
If you never need to coast (only stop) and your enabled
pin is always on (e.g. 3.3 or 5V), you can pass null
as the first constructor parameter.
If using all 4 inputs on a single driver, declare another Motor
to handle inputs 3 and 4.
To drive a single-direction motor (by only having input 1 connected), simply pass null
as the counterclockwisePin
to the Motor
constructor. Counterclockwise methods are not expected to function under this condition.
See the example for more details.
A shift register allows you to control more outputs than you have inputs. The ShiftRegister
component abstracts the implementation details of the 595-style integrated circuit away, so you can simply send the data you want as a byte
!
var enabledPin = pi.Pin11;
var dataPin = pi.Pin13;
var shiftPin = pi.Pin15;
var outputPin = pi.Pin16; //aka "latch"
var clearPin = pi.Pin18;
var register = new ShiftRegister(enabledPin, dataPin, shiftPin, outputPin, clearPin);
register.SetValue(255); //sets all 8 bits to On
register.SetValue(0b11111111); //does the same
//these two are also identical to each other
register.SetValue(0b10101010);
var values = new PowerSet
{
A = PowerValue.On,
B = PowerValue.Off,
C = PowerValue.On,
D = PowerValue.Off,
E = PowerValue.On,
F = PowerValue.Off,
G = PowerValue.On,
H = PowerValue.Off
};
register.SetPowerValues(values);
//you can also accomplish this more manually
dataPin.TurnOn();
shiftPin.Spike();
dataPin.TurnOff();
shiftPin.Spike();
outputPin.Spike();
Similar to the Motor
component, the enabled
and clear
parameters are optional; if you choose to have the register always on/enabled by connecting it to the 3.3 or 5V rail, set the first param to null
. If you never need to clear, and that pin is also connected to 3.3 or 5V, just leave the last param out.
See the example for more details.
First, thank you for your enthusiasm! I'd love feedback on how you felt using this. If you had an awesome experience, let me know on Twitter. If you had any problems, feel free to file an issue.
If you're looking to contribute code, but don't have any ideas of your own, there are some specific things I'd love help with over in the Issues tab!