Sunday, January 8, 2017

Introducing EasyLayout.Droid For Simpler Xamarin Android Layouts

If you've done much Xamarin iOS work you're probably run into Frank Krueger's awesome framework, EasyLayout, that makes manually coded auto layout's considerably easier to read and maintain.

If you've ever wanted the same type of functionality for Xamarin Android either for consistency or ease of cross platform code sharing, now you can with EasyLayout.Droid.

What Is EasyLayout?

The original EasyLayout takes Xamarin iOS code like this:

    _passwordField, NSLayoutAttribute.Top, NSLayoutRelation.Equal,
    _usernameTextField, NSLayoutAttribute.Bottom, 1f, 20f));
    _passwordField, NSLayoutAttribute.CenterX, NSLayoutRelation.Equal,
    View, NSLayoutAttribute.CenterX, 1f, 0f));

And turns it into this:

View.ConstrainLayout(() =>
    _passwordField.Frame.Top == _usernameTextField.Frame.Bottom + 20 &&
    _passwordField.Frame.GetCenterX() == View.Frame.GetCenterX()

If you're on a team, or storyboards just aren't your thing it's a lifesaver!

What's Wrong with Android .axml?

Android's axml files are ok, but on large projects they take a long time to generate, and they make it hard to share layout information cross platform.  But if you try to code Android by hand, you quickly discover the same type of verbosity that Xamarin iOS had.  Enter EasyLayout.Droid.

Example 1 - Parent Align

If you want to align an image to the edges of the frame you used to do this:

var layoutParams = new RelativeLayout.LayoutParams(
_image.LayoutParams = layoutParams;

Now you can do this:

relativeLayout.ConstrainLayout(() =>
    _image.Top == relativeLayout.Top
    && _image.Right == relativeLayout.Right
    && _image.Left == relativeLayout.Left
    && _image.Bottom == relativeLayout.Bottom

There's no need to set LayoutParams at all.  If they don't exist EasyLayout.Droid will add them, if they do EasyLayout.Droid will append to them.  And if you don't add them it will take care of choosing LayoutParams.MatchParent or WrapContent.

Example 2 - Relative Alignment and Constants

If you wanted to align an image 20 dp under another image and center align it to the parent you used to do this:

var layoutParams = new RelativeLayout.LayoutParams(
layoutParams.AddRule(LayoutRules.AlignBottom, image1.Id);
layoutParams.TopMargin = DpToPx(20);
_image2.LayoutParams = layoutParams;

There's a couple of gotchas.  

  1. If you set the TopMargin to 20, then Android assumes you mean pixels not device independent pixels.  To fix that you need to remember to call a function like DpToPx().  
  2. Your relative view (image1) needs to have an Id.  If you forget to set it there's no error, it just does strange layout things.

EasyLayout.Droid replaces the code above with:

relativeLayout.ConstrainLayout(() =>
    _image2.Top == _image1.Bottom + 20
    && _image2.GetCenterX() == relativeLayout.GetCenterX()

That's less code, and it's easier to read, plus there's some other small benefits: 

  1. If you forget to add an Id to _image1, EasyLayout.Droid will throw a helpful runtime error.  
  2. EasyLayout.Droid always assumes every number is in Dp, so it automatically converts all literals for you.

Incidentally, GetCenterX() is one of a couple of new extension methods along with GetCenterY() and GetCenter().

Example 3 - Constants

Constants weren't difficult to work with previously, but for completeness they used to work like this:

var layoutParams = new RelativeLayout.LayoutParams(
_image2.LayoutParams = layoutParams;

With EasyLayout.Droid you can do this:

relativeLayout.ConstrainLayout(() =>
    _image.Width == 50
    && _image.Height == ViewModel.SomeHeight.ToConst()

As mentioned previously 50 will be assumed to be in dp and will be auto-converted to pixels.  Also arbitrary properties such as SomeHeight will need the .ToConst() extension method applied in order to tell EasyLayout.Droid that they should be treated as constants.


Android relative layouts are far from a replacement for iOS's auto layout.  To that end you cannot do the following operations that EasyLayout could:

  • Constraining Heights or Widths to be equal to the Heights or Widths of other elements
  • Using >= or <= signs to indicate GreaterThanOrEqual or LessThanOrEqual type constraints
  • Multiplication of elements (e.g. _image2.Width == _image1.Width * .25f)


If you want to add this to your project you can either install via NuGet (safer):

Install-Package EasyLayout.Droid

or if you think it's perfect as-is (you don't want updates) you can copy EasyLayoutDroid.cs into your source.  Next using EasyLayout.Droid and you're good to go.


Hope this helps make someone's Xamarin Android day a little better.  The code is MIT licensed.  If you have any questions please contact me on twitter.

Benefits Of Git Rebase

In the first article in this series (Git: Rebase vs Merge) I covered the tactics of rebasing.  I discussed what merge commits are, and how to avoid them with rebasing.  In this post I'll cover the benefits of rebasing, including how its use speeds up finding hard to track down bugs via git blame and git bisect.

Is Rebase Really Worth It?

I worked on one large project that discouraged rebasing a while ago.  In short, this was the result:

The repository was insanely complicated to look at with gitk (or SourceTree in this case).  Trying to understand what was going on across the program was virtually impossible.
The recalcitrant developer (hey, someone forced me to learn these stupid SAT words, might as well inflict them on others), at this point, might simply respond: "So what?  As long as my stuff works."  And perhaps it's true, just like the old joke:
Patient: Doctor, it hurts whenever I do this.
Doctor: Don't do that.

Merge Commits: Ugly, Painful, or Both?

But even if someone never looked at the repo with gitk, or a fancy git GUI, in the project above roughly 50% of all commits were merge commits!
That meant 50% of the history of the project was useless noise distributed like a shotgun blast into the true history.  Furthermore, some of those merge commits hid sneaky little bugs introduced when merge conflicts were poorly resolved.  
Granted, 50 percent may be high for most projects.  The actual number depends on how many developers, how often they commit, and how often they merge.  For example if developers pull from develop daily, a given project will get one merge commit per developer per day.  If developers commit 3 times per day (seems kind of average from my observations), then 25% of commits will be merge commits.
The recalcitrant developer (stupid SAT) might again at this point respond: "25% of commits are merges, so what?  Just don't look at the commit history!  And if forced to, just ignore the merge commits!"
However, there are two specific cases where a messy history may yet affect a fast and loose, merge happy team.

Don't Blame Git!

Have you ever looked at a file and wondered who wrote a particular line of crap?  In my case 99% of the time that person is me.  But never mind that.  The tool for this job is clearly git blame.
The command git blame (or git annotate for the more more politically correct) will annotate every line of a particular file with its last commit.  Apart from finding who wrote something, it's also an essential tool for discovering why something was done the way it was when spelunking through larger, or especially older, codebases.
However, merge commits obfuscate git blame.  If an associated commit message is simply "merged develop into feature.awesome" and the developer is no longer around to ask, then we have to go through additional effort to track down history.

For instance, in the example above line 3 "c" was actually created by commit C (b49c7b1), but git blame incorrectly shows the merge commit (d9400d4) as the author.

Git Bisect For The Win!

The second scenario in which merge commits complicate history is in tracking a bug that someone introduced, typically, within the last few days.  One could manually checkout every commit between the good commit and the bad commit, or simply use git bisect.  
Git bisect is wonderful for automating the process of finding a commit.  It allows you to specify the last known good commit, and the last known bad commit, and then it performs a binary search of all the commits in between to discover the bad commit as quickly as possible.
Regardless of whether you search manually, or use git bisect, life gets hard as soon as you try to juggle many branches with lots of merge commits.  The automated approach makes navigating many merged branches easier, but either way if you have a fully merge-based project, you are now required to take an additional 25-50% steps.   If each step takes time to build or deploy, these extra steps can quickly add up (trust me, I've had to do this a lot).
For instance consider the following project with three feature branches, seven real commits, and five merge commits.
Now pretend that you've come in on Monday morning to discover that after committing D on Friday, some developers over the weekend committed E and F, and suddenly there's a hard to track down bug.  Git bisect will solve it for you like this: 
Lee@lee-xps MINGW64 /c/Temp/deletemegit (feature.awesomeness)
$ git bisect start
Lee@lee-xps MINGW64 /c/Temp/deletemegit (feature.awesomeness|BISECTING)
$ git bisect good 880e84a
Lee@lee-xps MINGW64 /c/Temp/deletemegit (feature.awesomeness|BISECTING)
$ git bisect bad be49c0d
Bisecting: 5 revisions left to test after this (roughly 3 steps)
[d9400d4c62807046f8ea235170e681b3e8952200] Merge branch 'develop' into feature.awesomeness
Lee@lee-xps MINGW64 /c/Temp/deletemegit ((d9400d4...)|BISECTING)
$ git bisect good
Bisecting: 2 revisions left to test after this (roughly 2 steps)
[96cf2877d16183cccce1f822d72626d331b582ef] Merge branch 'develop' into feature.awesomeness
Lee@lee-xps MINGW64 /c/Temp/deletemegit ((96cf287...)|BISECTING)
$ git bisect bad
Bisecting: 0 revisions left to test after this (roughly 1 step)
[190dadb1046822fc169193e86484a19e3543b783] Merge branch 'feature.2' into develop
Lee@lee-xps MINGW64 /c/Temp/deletemegit ((190dadb...)|BISECTING)
$ git bisect bad
Bisecting: 0 revisions left to test after this (roughly 0 steps)
[ef4a5532ace6075aead0850f088322f98e7afbf1] E
Lee@lee-xps MINGW64 /c/Temp/deletemegit ((ef4a553...)|BISECTING)
$ git bisect bad
ef4a5532ace6075aead0850f088322f98e7afbf1 is the first bad commit
commit ef4a5532ace6075aead0850f088322f98e7afbf1
Author: Lee Richardson
Date:   Mon Sep 5 21:56:07 2016 -0400
:000000 100644 0000000000000000000000000000000000000000 d8263ee9860594d2806b0dfd1bfd17528b0ba2a4 A      2.txt
Lee@lee-xps MINGW64 /c/Temp/deletemegit ((ef4a553...)|BISECTING)
$ git bisect reset
Previous HEAD position was ef4a553... E
Switched to branch 'feature.awesomeness'
Your branch is based on 'origin/feature.awesomeness', but the upstream is gone.
  (use "git branch --unset-upstream" to fixup)
Lee@lee-xps MINGW64 /c/Temp/deletemegit (feature.awesomeness)

Beautiful!  Commit E was the culprit.  The only problem: three of the four steps wouldn't have been needed if the team had been rebasing.


If your project is still small, and you haven't had to use git blame or git bisect yet, you may not find these arguments compelling.  However, if this is the case I suspect you may also  not find much value in unit testing either.  Unit testing and rebasing both require extra up-front work in order to build quality into your work and set your future self up for success.
More worried about immediate deadlines than your future self?  Consider the developer who will replace you when you leave.  Not worried about her?  Consider your customer at some future point in time when they're attempting to spelunk through your code.  Unless this is a throwaway project, the chances are good that a little extra effort learning a new technique today could save yourself, other developers, and possible a future employer considerable time and energy.  Not a bad investment.

Tuesday, September 13, 2016

Git: Rebase VS Merge

Distributed version control (git): Check.
Feature branches: Check.
Rebasing: Ugh, serioiusly.

On multiple projects I've attempted to introduce the concept of rebasing commits.  It rarely goes well (at first).  The initial reaction tends to be reluctance and confusion.  Reluctance, because it adds complexity and appears to give nothing back.  Confusion, because doing it wrong, and intertwangling feature branches in particular, turns out to be way too easy.
This is the first post in a series that covers how and why to make a clean commit history.  In this post I'll cover the history of merging, the difference between merging and rebasing, and the golden rule of rebasing.

In subsequent posts I'll cover the benefits of rebasing, cover common pitfalls, and provide several concrete workflow tips you can implement today to leave your project with a simple, clean, and linear source history with the ability to easily track down newly introduced issues.

The Good Old Days

Remember Source Safe and CVS?  Those were the good old days.  You'd simply check out files you were working on, and no one else could touch them.  No merge conflicts, ever.  It just worked, right?
That was great - right up until someone went on vaction and left a ton of files checked out, leaving the entire team unable to work.  Oh yea, not so great.
But remember subversion?  Those were the good old days.   Optimistic concurrency to the rescue.  Multiple people could work on the same file and 90% of the time it just worked.  And branching was super easy.
Subversion was great.  Right up until you had to merge branches.  Then it was time switch projects, and ASAP.  Merging was always a complete disaster.  Maybe subversion wasn't so great after all.
Git has revolutionized source control, first and foremost by making branching and merging easy.  Distributed version control systems (DVCS) like git allow us to work on features independently, and defer integrating with the rest of the team until the time is right.  Since we can commit locally, we can use small, frequent commits, thus allowing us to break complex features into smallier pieces and allowing our commit history to tell a story.
However, with git, while merging may be much easier than it once was - we still have to choose between two approaches.

To Merge or Not, That is the Question

The easiest option, and what most do by default is git merge.  Say you've started feature.awesomeness and committed "B" and "D" to it.  Except meanwhile back on develop someone committed "C".  
No big deal, you merge develop into feature.awesomeness with git merge develop and give it a nice descriptive commit message like "Merge branch 'develop' into feature.awesomeness".
That last commit, a merge commit, is a necessary side-effect, and a teltale sign, of merging.  You'll end up with one of these sketchy looking commits each time you want to integrate with (pull from) another branch.
When the feature is done you can merge it back to develop with git checkout develop and git merge feature.awesomeness. And thanks to the magic of fast-forward you won't have a second commit in develop.
While there the extra merge commit may be aesthetically unpleasing, and the lines branching and merging in the diagram a little noisy; this merge approach is easy, it's clear what happened, the commits maintain their chronology (A, B, C, D).

Marty McFly: "Yeah, well, history is gonna change"

The alternative is rebasing.  With this technique, you replay all of your local commits on top of another branch (usually develop or master).  This essentially deletes your original commits and does them again in the same order.  The other branch becomes the new "base".  So In the scenario above you'd do git rebase develop and end up with:
Pretty.  Clean.  You can pull from develop as many times as you want, and you'll never get extra commits.
If you're done, you switch back to develop and with a quick git merge and a free fast-forward you get:
Notice that the commits are no longer chronological (A, C, B, D rather than A, B, C, D) and that B and D both have the same commit time, 21:07.  Duplicate checkin times are the teltale sign of rebasing.    
Sounds just as easy as merging, looks clean, but rebasing can be dangerous.

Golden Rule of Rebasing

Since rebasing changes history, the most important rule is never to rebase after you're pushed to a remote branch.  Or, more subtly, never rebase if someone might be using using your remote branch (e.g. pure backups are ok).  The reasoning: if you've changed history, you can only push again with a git push -force, and forcing the push will overwrite remote history, making a mess for anyone needing to reconcile your old commits with your new ones.
An important corollary to the golden rule of rebasing is that if you push your local feature branch to origin but don't merge it to origin/develop, you are (usually) giving up the opportunity to rebase ever again on that branch.  In other words, if you want the benefits of rebasing (generally) refrain from pushing until you're ready to merge it back.
For example imagine you have a local unpushed branch like this:
Now you'd like to share your commit B with the world.  However, you aren't quite ready to merge it back to develop yet, and so you push without merging:
This may look fine, but you've just lost your ability to rebase.  This can be verified by examining the case where someone subsequently makes a change back on develop (C) while you have unpushed local changes (D):
Now if you rebase, you'll rewrite B, and that will result in a two commits called B, one locally and one on the server in origin/feature.awesomeness:
In this case git push -force can sometimes help, but it can also open a whole other can of worms.  The best option is to maintain the ability to rebase isby not pushing until it's absolutely necessary.


Hopefully you've learned a little about the history of merging, what merge commits are, how rebasing can elimiate merge commits, and a little of how to avoid rebasing trouble.  
But what if you're working on a large feature and you want to share it with another branch, but not merge back yet?  Are the benefits of rebasing really worth it?  This post has been more about tactics.  I'll cover strategy in subsequent posts.

Monday, June 6, 2016

4 Xamarin Misconceptions Debunked (aka What Even Is Xamarin)

This article explains what Xamarin is, the basics of how it works, and dispels four common misconceptions.
When Mary Jo Foley and Paul Thurott attempted and failed to describe Xamarin on Windows Weekly a couple of months ago, I grumbled about pundits not performing due research and moved on.  But when even Scott Hanselman (who I worshipgreatly admire) mischaracterized it on his most recent podcast, I realized there is sufficient confusion within our industry that additional clarification is needed.
Thus this post that attempts to dispel 4 common Xamarin Misconceptions and hopefully shed some light on what even is Xamarin.

Misconception #1: Xamarin UI's Require XAML

This was stated by a guest during Hanselman's recent podcast. The misconception is quite understandable given the popularity of Xamarin Forms and it's XAML-based UI abstraction layer.  However, a traditional (non-Forms) Xamarin solution involves no XAML whatsoever. With traditional Xamarin you write your UI multiple times -- once for every platform. On Android you write your UI in traditional .axml XML files. For iOS you write your UI using StoryBoards, .xib files, or manually in code by manipulating UIView's (ideally with EasyLayout) in a class that derives from UIViewController.
If traditional Xamarin sounds like a lot of work, keep in mind that writing fully native apps typically requires building two completely separate apps in two completely different languages with no code sharing ever. Which leads us to the next misconception:

Misconception #2: Sharing Code is Hard with Xamarin

My company was brought in recently to help a customer that had implemented a traditional Xamarin solution without any code sharing. They made the mistake of fully implementing an Android app first, and then once complete implementing a Xamarin iOS app by copy-pasting much of the same C# into the iOS app.
Sharing code isn't difficult with Xamarin, but the trap they fell into was not designing for it up-front. If they had spent a little more time architecting, or (better) written their Android and an iOS apps simultaneously, they would have likely ended up with Xamarin's recommended architecture:

All of their common logic would have been in a Shared Project implemented as either a Portable Class Library (PCL) that targeted iOS and Android (and Silverlight/Windows Phone), or as a Shared Project.
With either of these code sharing approaches there exists the problem of mixing shared code with platform specific code. The PCL approach solves the problem by having shared code call into interfaces or abstract classes defined in the PCL, and some form of dependency injection swaps in platform-specific concrete implementations at runtime.

On the other hand the Shared Project approach solves the problem with #ifdef compiler directives. It does this because shared projects don't produce a separate DLL. Instead, they essentially inject Symbolic Links from the Shared Project's C# files into each of the platform specific projects. That means any line of code written in a shared project is also written in the iOS and android projects.

There are plenty of people with strong opinions on which approach is better (e.g. Miguel De Icaza, co-founder of Xamarin, is pro Shared Project) but at the end of the day neither code sharing approach is hard, as long as you plan for it up-front.

Misconception #3: Xamarin Isn't Native

The topic of which cross platform mobile solutions are truly native seems to generate confusion. In his recent podcast Scott Hanselman implied that Xamarin produces the same non-native UI as Ionic. He is correct that Xamarin's HTML-based cross platform competitors such as Cordova PhoneGap, Ionic, and React Native are not and will never be fully native because they run in an embedded browser. Because of that their performance and user experience will never equal that of native apps written in Objective C, Swift, or Java.
However, Xamarin is different from the HTML based cross platform apps in that it is always 100% native. If you've read this far then you'll understand that a traditional Xamarin solution that uses StoryBoards and .axml will necessarily be fully native. However, Xamarin Forms is fully native too.
Xamarin Forms allows you to define user interface once, in XAML, and then Xamarin renders that XAML into fully native controls. For instance if you write an  then Xamarin Forms renders it as a UITextField in iOS and a EditText in Android.

The skeptical reader will undoubtedly think this sounds too good to be true, that one couldn't possibly make a decent native experience with this. While it's true that the Xamarin Forms abstraction falls short quickly for more sophisticated UI's, the framework accounts for this with Custom Renderers.
Custom Renderers allow the creation of new XAML elements or customization of existing Xamarin Forms elements in the platform specific projects. This solution ends up providing a fantastic level of flexibility. Unless you want a pixel perfect, or highly customized platform specific solution where you'd have more code in custom renderers than in XAML, Xamarin Forms is a great option -- but either way you'll end up with a fully native user experience.

Misconception #4: Xamarin Is Slow

People often seem surprised that a Xamarin based solution could perform as well as an app written in a native language. Perhaps this is because of a misconception that .Net apps on Windows typically run slower than C or C++ based ones that manage their own memory and don't require the Common Language Runtime (the Windows virtual machine that manages memory, does garbage collection, handles threads and performs just-in-time compilation).
While Xamarin apps still require a version of the CLR (aka the Mono Runtime), just like on Windows that doesn't mean slower.  The CLR may mean larger binaries (particularly for iOS apps that require Ahead-Of-Time rather than Just-In-Time compilation), but surprisingly Xamarin can actually run faster than native language based apps!
Last year Harry Cheung, one of the original Google engineers, measured the performance of a wide range of mobile platforms and came up with these amazing results:
If you get the chance you should read the updated article as well as his original one.


Hopefully this article has helped to clarify some of what Xamarin is and how Xamarin works.  Please post in the comments if there are any additional areas that could use clarification.

Thursday, April 21, 2016

How to Fade an LED with PWM in Windows IoT

Motors, dimmable LED's, speakers, multi-color LED's and a variety of other components have a requirement that's easy for an Arduino, but that turns out to be a little tricky in Windows IoT.  This is the second article in a series exploring Windows IoT on a Raspberry Pi.  In this post we'll describe PWM, discuss how to perform simple binary GPIO manipulation, and then dig into configuring a device to fade an LED using Pulse Width Modulation (PWM).

Pulse Width What?

Microcontrollers such as Arduino and System on Chip (SoC) devices such as Raspberry Pi can technically only output one of exactly two voltages on their General Purpose I/O (GPIO) pins: either 0 or 3.3 volts.  The problem is that many components such as speakers or multi-color LED's require not two, but a whole range of voltages.
Microcontrollers or SoC devices typically fulfill the requirement by switching a pin on and off so fast as to give the appearance to most components as being between the min and max.  For instance to get ~3.0 volts you keep the duty cycle, or the proportion of time the pin is at High at 90%.  This process is known as Pulse Width Modulation or PWM.  
The following diagram from Wikipedia is a beautiful illustration of how to accomplish a sine wave using PWM.  Hooking this output up to a speaker would produce a decent sounding continuous tone.
The problem is that PWM can be tricky for devices with non-realtime operating systems, because an OS can't just pause it's pin switching process to do a garbage collection or preemptively give some other process CPU time. Consequently, until recently Microsoft required you to get an external board if you wanted to output variable voltages in its fledgling Windows 10 IoT operating system.
However, as of version 10.0.10586.0 there is a way. That way is called Lightning Providers, but getting it working is a little tricky, and the documentation is scattered and doesn't work out of the box.

Binary GPIO

Before we get into how to do PWM, this series has yet to touch on regular binary GPIO manipulation.  Fortunately it's fairly simple and well documented.  Assuming you've got a hello world Windows IoT app, you can turn a pin high and then low like this:
gpioController = await GpioController.GetDefaultAsync();
if (gpioController == null)
    StatusMessage.Text = "There is no GPIO controller on this device.";
_pin = gpioController.OpenPin(22);
await Task.Delay(500);

Seems simple enough, it flashes an pin (and perhaps an attached LED) High for a half a second.  But there are a couple of things to note.  
First GpioController is in Windows.Devices.Gpio, and it's only available when you reference Windows IoT Extensions for the UWP.

Second, GpioController.GetDefaultAsync() may return null if we're running this Universal Windows Platform project on a regular PC, or a phone, or an XBox.  That's something to guard against.
Third, the pin 22 was (arbitrarily) picked from one of the Pi's available GPIO pins using the following diagram:

In other words, the above code will flash the 8th pin down on the left-hand side (aka the 15th pin).  
Quick word of warning: if you test this out with an LED, make sure you get the polarity right, since LED's are not omnidirectional.


There are five steps to get PWM working.

1. Latest Bits

First, ensure you have the latest version of Windows IoT.  Technically you only need the current public release of Windows IoT, aka Build 10586, December 2015.  However, I tested this on the Pi 3, and since it's supposed to be 60% faster, your Pi 2 results may vary.  For this reason I'm recommending you install the Insider Preview of Windows IoT, which I showed how to set up in the last post.

2. Lightning Driver

Second, you need to install the Lightning Direct Memory Mapped driver.  Lightning is a new driver that provides a variety of additional capabilities including device and remote board PWM support.  It's still in beta, and consequently there's a warning when you select it: "This option will reduce Windows security in exchange for performance using an in development driver". 
To do change drivers:
  1. Navigate to the configuration url for your device (e.g. http://LeesRasPi3:8080/).  
  2. Select Devices
  3. Under Default Controller Driver, select "Direct Memory Mapped Driver"

  4. Reboot your device when prompted

 Lightning SDK

Third, you'll need to reference the Lightning SDK.  According to the documentation, you just reference via NuGet.  Unfortunately, this doesn't work as of v1.0.3-alpha.  I had to download the Microsoft.IoT.Lightning.Providers C++ source, add the Microsoft.Iot.Lightning.Providers.vcxproj project to my solution, and then make a project reference.  
Incidentally, I contacted some folks at Microsoft, and they said a new nuget will be published shortly with binaries that will fix this issue.

4. Permissions

Next, Lightning providers require additional manifest permissions.  To grant them you'll need to edit the Package.appxmanifest file of your UWP app and add the following bits inside capabilities at the end of the document:
<iot:Capability Name="lowLevelDevices" />
<DeviceCapability Name="109b86ad-f53d-4b76-aa5f-821e2ddf2141"/>
And then add the iot namespace to the Package element at the top of the document and iot to IgnorableNamespaces: 
  IgnorableNamespaces="uap mp iot">

5. PWM Code

Finally, we're ready for some code.  One nice thing is that we can keep all of our existing binary GPIO code, plus allow the device to use either driver by simply adding the following line:
if (LightningProvider.IsLightningEnabled)
    LowLevelDevicesController.DefaultProvider = LightningProvider.GetAggregateProvider();
But, to get full on-device PWM functionality we'll need something like this:
if (LightningProvider.IsLightningEnabled) {
  LowLevelDevicesController.DefaultProvider = LightningProvider.GetAggregateProvider();
  var pwmControllers = await PwmController.GetControllersAsync(LightningPwmProvider.GetPwmProvider());
  var pwmController = pwmControllers[1]; // use the on-device controller
  pwmController.SetDesiredFrequency(50); // try to match 50Hz
  _pin = pwmController.OpenPin(22);
The first couple of lines set up the lightning driver and PWM provider using the on-device controller (as opposed to a dedicated PWM board, which you could attach to get better performance).   It then requests a leisurely 50Hz frequency speed.
Finally it opens pin 22 and sets the duty cycle to 25%.  
And that's it!  With a scrollbar and a few extra lines of code you'll be able to get something like this: 

Source Code

The complete code for this project is available on the WindowsIotPwmExample github project.


In this article we've covered what Pulse Width Modulation is, how to use Windows IoT to write binary-states to GPIO pins, and finally how to generate variable voltages using PWM.  Keep an eye out for the next article in the series on how to turn a Raspberry Pi into an information radiator.