27 December 2015

Gotcha–navigating from SplitView requires back button to be pressed twice in UWP apps

Yesterday, while being in the process of converting my one of my apps to UWP, I was moving a lot of the functionality of the app menu to a SplitView. Microsoft have really gone out on a limb as far as samples are concerned, so I was following the SystemBack sample, which has really little code in it. How hard can it be, right?
All  went rosey, until I discovered that altough the back button showed up nicely on my secondary page, the actual navigation back only happenend after I had pressed the back button twice. Some debugging learned me the global event
SystemNavigationManager.GetForCurrentView().BackRequested
does not even get called the first time. I spent a not so enjoyable hour deconstructing my app, then finally building a bare bones repro – and there it happened too. One of those moment where you seriously start to doubt your own mental health. The code is not very complicated. I have a MainPage.xaml with a button on a SplitView, and when you click that, it navigates to the next page
private void Navigation_Click(object sender, RoutedEventArgs e)
{
  Frame rootFrame = Window.Current.Content as Frame;
  rootFrame.Navigate(typeof(Page2));
}
And on that Page2 a rather piece of standard code
protected override void OnNavigatedTo(NavigationEventArgs e)
{
  base.OnNavigatedTo(e);
  var rootFrame = Window.Current.Content as Frame;
  if (rootFrame != null)
  {
    SystemNavigationManager.GetForCurrentView().AppViewBackButtonVisibility =
      rootFrame.CanGoBack
        ? AppViewBackButtonVisibility.Visible
   : AppViewBackButtonVisibility.Collapsed;
  }
}
And in the app.xaml.cs, also rather standard (and ugly, now that I look at it), nicked from the sample
private void App_BackRequested(object sender, BackRequestedEventArgs e)
{
  Frame rootFrame = Window.Current.Content as Frame;
  if (rootFrame == null)
    return;

  if (rootFrame.CanGoBack && e.Handled == false)
  {
    e.Handled = true;
    rootFrame.GoBack();
  }
}
And yet, this method gets only called on the second back button press. The solution? Read back a little.

“I have a MainPage.xaml with a button on a SplitView, and when you click that, it navigates to the next page”

It's one of those mental leaps you sometimes have to make as a developer. It turns out that the exact method Navigation_Click works flawlessly when the button calling the method is not on a SplitView. Somehow, some way, having a SplitView open messes up the navigation back stack.
The solution, once you know that, is very simple of course:
private void Navigation_Click(object sender, RoutedEventArgs e)
{
  rootSplitView.IsPaneOpen = false;
  Frame rootFrame = Window.Current.Content as Frame;
  rootFrame.Navigate(typeof(Page2));
}
Go back to the click event handler, and add a line that closes the SplitView before initiating the navigation. It’s the little things like this that makes developer life so interesting. ;)

Code used in this post can be found here.

Special thanks to Scott Lovegrove and the other people from the Open Live Writer team for making this post possible – it’s the first one using Open Live Writer that now supports blogger – right after Google shut down the outdated web api endpoint that Live Writer still used. Thank you all folks!

12 December 2015

UWP Map data binding with WpWinNlMaps explained

Intro

Recently I released WpWinlMaps for the Universal Windows Platform, a NuGet package that allows you to data bind map shapes to the awesome new map control for Windows 10. This map control got recently even more awesome with SDK 10586, when multipolygons, aka polygons with holes, aka donuts where added to it. For those who have read this blog before, this binding code should not come as a surprise - I basically did this already in 2012 for the Bing Maps control for Windows, and there are incarnations of this for Windows Phone 8 and the Here Maps control for Windows Phone 8.1. The UWP binding - of course built as a behavior - is an evolution of the Windows Phone 8.1 behavior. It's most important new features are:
  • It's built on top of the new UWP Behaviors NuGet Package
  • MapShapeDrawBehavior can now also draw multi polygons (with holes)
  • The geometry type used to support Geopath only (even if you wanted to draw just a MapIcon). Now you can use a BasicGeoposition for MapIcon, a Geopath for MapPolyline or a 'normal' MapPolygon, and an IList<Geopath> to create the new type of polygons-with-holes that I mentioned earlier.
  • MapShapeDrawBehavior supports the new MapElementClick event for selecting objects on the map (and still supports the old MapTapped event, as well as Tapped, although the last one is still not recommended for use)
  • The EventToCommandMapper is renamed to EventToHandlerMapper; now it can not only call a command, but also directly a method of the view model. This is to align with the way x:Bind introduces calling direct events as well.
  • Speaking of - x:Bind to the MapShapeDrawBehavior's ItemSource is fully supported, although that's 99% thanks to the platform and 1% to my coding.

Getting started

Create a project, add the WpWinNl NuGet package to it. This will pull in the WpWinNlBasic package as well, as well as - of course Microsoft.Xaml.Behaviors.Uwp.Managed, and Rx-Linq because I use that to dynamically react on events.

Then, of course, you will need some MVVM framework, be it something that you make yourself or something that is made by someone else. In my sample I opted for pulling in MVVMLight, this being more or less an industry standard now. I also pulled in WpWinNl full, because I use some more features from it in my sample code. And that automatically pulls in MVVMLight too, so that saves you the trouble of doing that yourself ;)

Concepts

These are basically still the same, but I will repeat them here for your convenience.
Typically, maps are divided into layers. You can think of this as logical units representing one class of real-world objects (or ‘features’ as they tend to be called in the geospatial word). For instance, “houses”, “gas stations”, “roads”. In WpWinNlMaps, a layer translates to one behavior attached to the map.

A MapShapeDrawBehavior contains the following properties
  • ItemsSource – this is where you bind your business objects/view models to.
  • PathPropertyName – the name of the property in a bound object that contains the BasicGeoposition, the Geopath or the IList<Geopath>  describing the object’s location
  • LayerName – the name of the layer. Make sure this is unique within the map
  • ShapeDrawer – the name of the class that actually determines how the shape in PathPropertyName is actually displayed
  • EventToCommandMappers – contains a collection of events of the map that need to be trapped, mapped to a command or a method of the bound object that needs to be called when the map receives this event. Presently, the only events that make sense are "MapClicked", “MapTapped” and “Tapped”.

Sample

As always, a sample says more than a 1000 words. Our view model has a property
MultiPolygons = new ObservableCollection<MultiPathList>();
And a MultiPathList indeed as a
public List<Geopath> Paths { get; set; }
Drawing a set of polygons with holes in it, is as easy as
<maps:MapControl x:Name="MyMap" Grid.Row="0">
  <interactivity:Interaction.Behaviors>
    <mapbinding:MapShapeDrawBehavior LayerName="MultiShapes" 
        ItemsSource="{x:Bind ViewModel.MultiPolygons,
          Converter={StaticResource MapObjectsListConverter}}" 
        PathPropertyName="Paths">
      <mapbinding:MapShapeDrawBehavior.EventToHandlerMappers>
        <mapbinding:EventToHandlerMapper EventName="MapElementClick" 
                                         MethodName="Select"/>
      </mapbinding:MapShapeDrawBehavior.EventToHandlerMappers>
      <mapbinding:MapShapeDrawBehavior.ShapeDrawer>
        <mapbinding:MapMultiPolygonDrawer 
          Color="OrangeRed" StrokeColor="Crimson" 
          Width="2" StrokeDashed="True"/>
      </mapbinding:MapShapeDrawBehavior.ShapeDrawer>
    </mapbinding:MapShapeDrawBehavior>
  </interactivity:Interaction.Behaviors>
</maps:MapControl>
So what we have here is a MapShapeDrawBehavior that binds to ViewModel.MultiPolygon, using a converter. Unfortunately, due to the nature of x:Bind, you will always need to use this converter. If you don't, you will run into this error: "XamlCompiler error WMC1110: Invalid binding path 'ViewModel.MultiPolygons' : Cannot bind type 'System.Collections.ObjectModel.ObservableCollection(WpWinNl.MapBindingDemo.Models.MultiPathList)' to 'System.Collections.Generic.IEnumerable(System.Object)' without a converter". So I give it a converter to make it happy, although the convert method of the MapObjectsListConverter in fact only is this
public override object Convert(object value, Type targetType, 
                               object parameter, CultureInfo culture)
{
  return value;
}
If you have been working as a career developer for 23 you learn it's best just not get wound up about these kinds of things and just happily accept a feasible work-around :)

Event handling

Next up is the EventToHandlerMapper; in its EventName you can put the following event names:
  • MapElementClick
  • MapTapped
  • Tapped
And I recommend you use MapElementClick as that provides the least overhead and is the preferred new event. The other two will work too. Any other events, how valid they might be, are ignored.
The EventToHandlerMapper has two other properties: MethodName and CommandName. The first one is checked first, so if you are a smartypants who defines them both, only MethodName is used. Once again - this is a method or a command on the bound object, not the view model that hosts the ItemSource. The method or command should take a MapSelectionParameters object as a parameter. In the sample code you will see a class GeometryProvider that actually implements both, utilizing standard MVVMLight code:
public class GeometryProvider : ViewModelBase
{
  public string Name { get; set; }

  public ICommand SelectCommand => new RelayCommand<MapSelectionParameters>(Select);

  public void Select(MapSelectionParameters parameters)
  {
    DispatcherHelper.CheckBeginInvokeOnUI(
      () => Messenger.Default.Send(
         new MessageDialogMessage(Name, "Selected object", "Ok", "Cancel")));
  }
}
I use this as a base class for all types that I bind to the MapShapeDrawBehavior to provide an easy base for event handling.

Shape drawers

These are classes that for actually converting the geometry into an actual shape, that is, a MapIcon, a MapPolyline, or a MapPolygon. Out of the box, there are four drawers with the following properties:
  • MapIconDrawer
  • MapPolylineDrawer
    • Color - line color
    • StrokeDashed - dashed or solid line
    • Width - line width
  • MapPolygonDrawer
    • Color - shape fill color
    • StrokeDashed - dashed or solid shape outline
    • StrokeColor - shape outline color
    • Width - shape outline width
  • MapPolylineDrawer
    • Same as MapPolygonDrawer
In addition, all drawers support a Z-index property.

Thematic maps - making your own shape drawers

I wish to stress that is does not end with the four default drawers. If you want map elements to change color or other properties based upon values in object that you bind to - there is nothing that keeps you from doing that. You can do this by making by sub classing an existing drawer (or make a completely new one). Suppose you have this business object:
public class CustomObject
{
  public string Name { get; set; }
  public BasicGeoposition Point { get; set; }

  public int SomeValue { get; set; }
}
And you want to have the color of the line to change based on the SomeValue property, you can achieve this by writing something like this:
public class MyLineDrawer : MapPolylineDrawer
{
  public override MapElement CreateShape(object viewModel, Geopath path)
  {
    var shape = (MapPolyline)base.CreateShape(viewModel, path);
    var myObject = (CustomObject)viewModel;
    switch (myObject.SomeValue)
    {
      case 0:
        {
          shape.StrokeColor = Colors.Black;
          break;
        }
      case 1:
        {
          shape.StrokeColor = Colors.Red;
          break;
        }

      //etc
    }
    return shape;
  }
}

Drawer class hierarchy

The class drawers are built according to the following class hierarchy
I'd recommend overriding only the concrete classes when creating custom drawers. Be aware there are three virtual methods in MapShapeDrawer that you can override:
public abstract class MapShapeDrawer
{
  public virtual MapElement CreateShape(object viewModel, BasicGeoposition postion)
  {
    return null;
  }

  public virtual MapElement CreateShape(object viewModel, Geopath path)
  {
    return null;
  }

  public virtual MapElement CreateShape(object viewModel, IList<Geopath> paths)
  {
    return null;
  }

  public int ZIndex { get; set; }
}
Make sure you override the right method for the right goal:
  • CreateShape(object viewModel, BasicGeoposition postion) when you are dealing with icons
  • CreateShape(object viewModel, Geopath path) when you are dealing with lines or polygons
  • CreateShape(object viewModel, IList<Geopath> paths) when are are dealing with multipolygons

Limitations

Be aware this binding method respond to changes in the list of bound objects - that is, if you add or remove an object to or from the bound list, it will be drawn of the map or removed from it. If you change properties within the individual objects after binding and drawing, for instance the color, those will not reflect on the map - you will have to replace the object in the list.

Sample solutions

This article comes not with one but two samples - it's amazing Mike! ;). The first one is actually in the code on GitHub and you can find it here. The drawback of that sample it that it actually requires you to compile the whole library as it uses the sources directly - it was my own test code. So for your convenience I made more or less the same solution, but then using the NuGet packages. You can find that here - it's an old skool downloadable ZIP file as I don't want to confuse people on GitHub. Both solutions work the same and show the same data as in an earlier post where I described the multipolygon feature first.

imageA little word of guidance – after your start either demo app, first go to the ellipses on the right, tap those and hit “show area”. That will bring you to the right location to show all the features that this app can draw.

Conclusion

I hope that this little library is as useful as its earlier incarnations proved to be. I have actually utilized the wp8.1 version in one of my own apps, I know there is a good chance of more apps are using it, and also that some Microsofties are actually recommending it ;). I hope it's useful for you. Let me know what you think about this. In the mean time, happy mapping!

09 December 2015

Release of WpWinNl 3.0.2 alpha with UWP support - and map data binding

I just released my open source library WpWinNl to 3.0.2-alpha (that is, pre-release) to NuGet. WpWinNl now supports Windows Phone 8, Windows Phone 8.1, Windows 8.1 and the new Universal Windows Platform. All the basic libraries are updated to the latest version.
The library builds three NuGet packages, which can be found on NuGet as of now:
  1. WpWinNlBasic, which contains everything except the stuff that hangs on MVVMLight
  2. WpWinNl, builds on top of WpWinNlBasic and MVVMLight (and has dependencies on both)
  3. WpWinNlMaps, that builds on top of WpWinNlBasic. This is code that allows you to bind data to maps utilizing a special behavior
For Windows Phone 8, Windows Phone 8.1 and Windows 8.1 basically nothing changes. With respect to UWP, the following changes have been made:
  1. The behaviors are built on top of the new UWP Behaviors NuGet Package
  2. WpWinNlMaps has a slightly expanded API to support the new features by the new maps control, as well align more with the x:Bind scenario
There is a sample application for WpWinNlMaps in GitHub that I will explain more in detail in a follow-up post. Make sure that if you have a look at the code, take the UWP branch.
A few words of warning:
  • Apart from WpWinNlMaps, this has not yet been extensively tested, hence the pre-release designation.
  • No attempt has been made to share code between UWP and the earlier incarnations of these packages. Effectively I have ceased working on wp8/wp81/win81 code, as of now only the UWP code will move forward and at one point in time these packages will stop supporting them at all.
  • Parts of this library, especially the behaviors, may be removed entirely and end up in the Microsoft Behaviors NuGet package.
However, for the time being, I think especially the map binding is pretty important, so is was time to release it. Any feedback is welcome.

06 December 2015

Fixing "Payload file rd.xml does not exist" when creating a Windows 10 UWP NuGet Package

Just as I thought I finally was done adding Universal Windows Platform support for WpWinNl, I ran into a weird error. I had updated the nuspec file after some guidance from my fellow MVP Dave Smits, created the NuGet package itself, but when I wanted to use it, I ran into an error that looked like this:
Payload file 'C:\Users\joost_000\.nuget\packages\WpWinNlBasic\3.0.0-alpha\lib\uap10.0\WpWinNl.External\Properties\WpWinNl.External.rd.xml' does not exist.
Another fellow MVP, Scott Lovegrove, gave me the first pointer in this article. Apparently, even if you don't have any special directive in the rd.xml file, it still needs to be there. Scott explains how you need to put this file in a subfolder of where the actual assemblies of your package reside. This works, but it takes (as I have found out) quite some hassle making a script that gets the right directory structures. Typos and mistakes are easily made. Or it may be just that I am a bit thick. Anyway, another well-known community hero developer (who I think should really be made MVP at the first possible occasion), Pedro Lamas, actually gave me a way easier way to fix this:
just change the "Build Action"  of the missing rd.xml a Build Action to "embedded resource"
image
Ironically, Pedro gave me this pointer when he made a pull request to the newly open sourced Behaviors library for Windows 10 UWP apps that I help to manage. Here rd.xml files were pulled into the package by file - kind of like I was doing it first, in stead of using the embedded resource way. Which goes to show that this knowledge isn't very common and apparently not even clear to developers within Microsoft - and this is why I decided to write this little post to make the solution to this problem easier to find.
In his pull request Pedro points to this article on the .NET blog from May 2014 where there is actually something written about including the rd.xml file as a resource, but it 's like an aside, with no actual indication the file actually has to be there in a NuGet package, whether you are actually using it or not.
As to the actual functions of the RD.xml file, that's in the .NET blog article. Be sure to read that when you are planning to use reflection. I hope Pedro will indeed find some time to write some more clarification on this, as he seems to be planning to do.
Update - Pedro tweeted in a response to this article that you apparently can also delete the whole rd.xml file from your project, and then it will work as well. So that makes three possible ways to solve the error.

03 December 2015

Drawing polygons with holes (donuts) on Windows 10 UWP apps

imageNovember 30th was the day a long standing wish of me came true - Windows 10 Universal Windows Platform gets on par with some professional geographical information systems. As of SDK version 10586, you can draw polygons with holes in them on the map (we GIS people call those 'donuts' - remember this term if you want to sound like a smartass educated in the GIS area) as well as multipolygons (single map objects consisting out of multiple disjoint shapes. What I mean by this, can be seen on the right. On this map are actually only two shapes. The 'smiley' on the bottom is one shape, and rest is actually also one shape.
To achieve this, the maps team have extended the MapPolygon. This type, that is used to draw polygons, already had a property Path of type GeoPath. Now it has a property Paths - plural. This property is of type IList<GeoPath>. The smiley exists of four of these GeoPaths. The first one is the outer shape, the second, third and forth one fall on top of a shape that is earlier in the list, and thus creates a hole. You can get some pretty interesting side effects as you look a the top shape - if you draw a second or later path outside of the first shape, you just get a second shape. But for the map, this is one object and if you click on it you will get the same text. Even more interesting is drawing a second shape partly on top of an earlier shape - the overlapping part becomes a hole, the rest just a filled shape.
Other possibilities are drawing a shape, on top of that a smaller shape (creating a hole), inside the hole an even smaller shape (that will be a normal shape again), on top of that an yet even smaller shape - that will create a hole... etc... and so you can create rings. The odd shapes are shapes (when you start counting with 1!), the even shapes holes.
I have extended the solution that I used in my 7-part map series to make clear how this happens. I have added a class MultiPathList that is basically a very long and boring list of coordinates. It looks like this:
new BasicGeoposition{Latitude = 52.1782977506518, Longitude = 5.40948953479528},


using System.Collections.Generic;
using Windows.Devices.Geolocation;

namespace Manipulation_Drawing
{
    public class MultiPathList : IMapObject
    {
      public MultiPathList()
      {
          Paths = new List<Geopath>();
      }
      
      public string Name { get; set; }

      public List<Geopath> Paths { get; set; }


      public static List<MultiPathList> GetMultiPolygons()
      {
        var paths = new List<MultiPathList>
        {
          new MultiPathList
          {
            Name = "MultiArea 1",
            Paths = new List<Geopath>
            {
               new Geopath( new[]
               {
                 new BasicGeoposition{Latitude = 52.1840454731137, Longitude = 5.40299842134118},
                 new BasicGeoposition{Latitude = 52.182151498273, Longitude = 5.40619041770697},
                 new BasicGeoposition{Latitude = 52.1841113548726, Longitude = 5.40994542650878},
                 new BasicGeoposition{Latitude = 52.1861041523516, Longitude = 5.40627088397741}
               }),
               new Geopath( new[]
               {
                 new BasicGeoposition{Latitude = 52.184210177511, Longitude = 5.40817516855896},
                 new BasicGeoposition{Latitude = 52.185066556558, Longitude = 5.40637808851898},
                 new BasicGeoposition{Latitude = 52.1842925716192, Longitude = 5.4054393991828},
                 new BasicGeoposition{Latitude = 52.1834195964038, Longitude = 5.40739741176367}
               }),
             }
             //etc
          },
          new MultiPathList
          {
            Name = "Smiley (MultiArea 2)",
            Paths = new List<Geopath>
            {
               new Geopath( new[]
               {
                 new BasicGeoposition{Latitude = 52.1787753514946, Longitude = 5.40471511892974},
                 new BasicGeoposition{Latitude = 52.1801093313843, Longitude = 5.40570753626525},
                 new BasicGeoposition{Latitude = 52.1801258437335, Longitude = 5.40860432200134},
                 new BasicGeoposition{Latitude = 52.1789400558919, Longitude = 5.4108305554837},
                 new BasicGeoposition{Latitude = 52.1772930957377, Longitude = 5.40975767187774},
                 new BasicGeoposition{Latitude = 52.1764037758112, Longitude = 5.40750461630523},
                 new BasicGeoposition{Latitude = 52.1769636869431, Longitude = 5.40490287356079},
               }),
              //etc
             }
          }
        };
        return paths;
    }
  }
}
it just creates two lists of GeoPaths (I have omitted most of them - there are 9 of these paths in grand total). And then in MainPage.xaml.cs you will find this simple method that actually draws the shapes:
private void DrawMultiShapes(object sender, RoutedEventArgs e)
{
  if (!DeleteShapesFromLevel(4))
  {
    var strokeColor = Colors.Crimson;
    var fillColor = Colors.OrangeRed;
    fillColor.A = 150;

    foreach (var dataObject in MultiPathList.GetMultiPolygons())
    {
      var shape = new MapPolygon
      {
        StrokeThickness = 1,
        StrokeColor = strokeColor,
        FillColor = fillColor,
        StrokeDashed = false,
        ZIndex = 4
      };
      foreach (var path in dataObject.Paths)
      {
        shape.Paths.Add(path);
      }
      shape.AddData(dataObject);

      MyMap.MapElements.Add(shape);
    }
  }
}
image[9]In stead of setting the MapPolygon's shape, we add a number of GeoPaths to the Paths property, and that is all. You can view the shapes for yourself by downloading the sample solution from GIT (take branch "multipolygon" )
That is all there is to it. This is a very important for when you are are drawing things like zoning permits, buildings with an inner garden, parking areas in cities (where the fee increases when you come closer to the center), so they are basically rings in rings in rings - etc. - anything were less-than-trivial mapping is concerned. And it's very easy to use now.
And of course, all this goodness can be used on Windows 10 mobile as well. Enjoy mapping!

14 November 2015

Fix - Dell Venue 8 Pro Windows 10 Fall update gets stuck at 40%

My Dell Venue 8 Pro that I primarily use as an e-reader was the last of the flock to get the update... so after gone trough the plight of getting about 8GB of data free to be able to actually start the Fall update... it got stuck at 40%. Twice, actually. It was installing a whole night but never passed 40%.

The root cause appeared to be an SD card. The fix is pretty easy.

  1. Hold the power button till your DV8P powers down
  2. Once it has shut down, pop out the SD card
  3. Power it up again.
  4. It will now restore your previous version of Windows, that is, the Windows 10 RTM 10240. Wait for that complete (should be a few minutes)
  5. Follow this procedure as described by Rod Trent on the SuperSite for Windows
  6. The update will now complete (fingers crossed)
  7. Once it's done, login and pop in your SD card again.

At the original writing of this article I was thinking "I have read this somewhere before, but where"? Neither Google or Bing yielded any results. The odd thing is my Surface Pro 1 upgraded flawlessly, although it does have SD card too.

Maybe I did not search thoroughly enough, because a day later the writer of this blog (in Dutch) pointed out he posted the same thing before I did. The post recounts a twitter conversation between Gabe Aul and Mary Jo Foley about popping the SD card on upgrade. I probably have seen the  conversation in my timeline and subconsciously registered it. I admit prior art ;) but I will leave this post up because I think it makes the solution easier to find.

Re-enabling the Hanselman trick to easily switch between Hyper-V and VirtualBox after Windows 10 Fall update

Since my first forays into Xamarin I have been making great use of this awesome trick by Scott Hanselman to quickly change from a configuration with Hyper-V (for Windows Phone and Windows 10 Mobile development) and Virtual Box (for using emulators based upon VirtualBox. I created this dual-boot option in Windows 8.1, and it survived the upgrade to Windows 10 RTM 10240 in July.

After updating to the Windows 10 Fall update (aka 1511, aka 10586.3) I found out I had two boot option in my boot screen - "Windows 10" and "Windows 10", both with Hyper-V enabled.

Bummer.

Fortunately, this is easy to fix.

  1. Open an admin command prompt
  2. Enter bcdedit.
    You will get a list of three entries, the first one "Windows Boot Manager" (ignore that) and two called "Windows Boot Loader"
  3. Check that both have an entry "hypervisorlaunchtype" set to "Auto"
  4. Both boot loaders description "Windows10" and will have an identifier. One will be a {current}, the other a GUID like identifier, like {3bca20f3-367f-11e5-9da7-f5ee60b7b905}. That is the one you can change.
  5. Enter bcdedit /set {your-guid-here} description "No Hyper-V"
  6. Enter  bcdedit /set {your-guid-here} hypervisorlaunchtype off

If your reboot now, you will once again have two options, one with description Hyper-V, the other still called Windows 10

Caveat emptor: playing around with the boot editor can seriously mess up your system. Be sure of what you are doing. Even I usually stay away from this as much as possible. Worked on my machine - I cannot accept any responsibility for it not working on yours :)

21 October 2015

Windows 10 maps part 7 - using external maps with TMS/WMS

Intro
In this final episode of the planned series, posted on "Back to the Future" day, I will show you how to use external map sources and how to use them with the Windows 10 maps control. Specifically I will show you how to use Tile Map Services (TMS) - way of distributing digital maps designed by the Open Source Geospatial Foundation and popularized by Google Maps - and Web Map Services (WMS), and older, more complex protocol designed by the Open Geospatial Consortium in 1999.
I am using TMS in a loosely defined way here - I am defining it as a REST-based system that retrieves pre-rendered tiles of maps using fixed zoom levels based on zoom level and location (try to say that without stuttering). A TMS basically is a take-it-or-leave-it approach - you get a map rendered as the maker saw fit, whereas WMS offers you the possibility to select layers and determine the order in which those layers are retrieved - and sometimes they even support custom styling. In addition, it allows for arbitrary image sizes, whereas TMS typically services 256x256 images. TMS typically comes from a file system containing a very large number of small files, whereas a WMS is typically served from a spatial database. Consequently, WMS, while being more versatile, usually is a lot slower.


So what is this all about?
The are a very large number of servers out there that offer you maps that you can use - OpenStreetmaps, Google, NOAA, but also our own Dutch Rijkswaterstaat - a government agency that maintains the Dutch main road and water transport infrastructure. You can search for public endpoints of those servers, and when you implement a little code to translate the requests of you Windows 10 map control into the right URLs, maps will show up.
The sample code will show you how to use the following data:

  • Google Maps
  • OpenStreetMaps (a non-profit organization that has insanely detailed maps) - I use it often when I go on hiking holidays in Germany or the like, as even the most obscure hiking trails are displayed in more detail than any tourist map you can buy.
  • Dutch Rijkswaterstaat maps
  • NOAA weather and cloud maps

Be sure to read up on the terms of services of the map providers. Not every one of those providers have unlimited bandwidth or CPU power to serve up the needs of your app, or they may require you to pay for that. OpenStreetMaps is a non-profit organization that does not like you to let their servers burn. Some, like Google, require you to use their API in stead of directly accessing the URLs where their data reside. The sample code used in this project violates this TOS of Google, and is intended as an educational sample only. I strongly advise you not to use this in production environments - and to be honest, the HERE maps data is so good in most of the cases there is little need for doing that.


Viewing the demos
Start the app, click "Initial location". You will see this.
image
Now select "None" for Map style (the map will turn black), then select "OpenStreetMap" for Tile Map. The map will turn into as displayed below, and already shows some blue dotted hiking trails - even through the very neck of the woods where I live.
image
If you select Google Hybrid you will get the Google Satellite imagery with street labels on top of it. Once again, this is illegal, but it proves my point:
image
And why this might be useful... if you zoom all the way in and put the Google and Here imagery next to each other you will see that Google imagery in some places still has some more detail, although it's very outdated - my neighbor's house extension is not visible yet (it is on Here Maps) and I am now driving the 2nd car after the car that is still in front of my house - putting this back to the early days of 2009 at the very latest.
image
If you zoom out a little again, and select "RWS NWB" you will see the national road grid map from the Dutch Rijkswaterstaat, a simple line map for secondary roads, the major highway depicted as double red lines, with black dots showing the location of hectometer signs - the little signs that show you where you are on the roads, and that can be used to specify your location when your cars breaks down and you need to call for help. Amongst other things :)
image
Set style back to "Roads", and zoom out more or less the USA, the select NOAA Radar. This shows the rain radar of the USA, as observed by the NOAA

image
Looks like my friend Richard Hay is in for some rain over in Jacksonville. Or maybe it is just past him ;). Anyhow, if you select "Visible Img" you will get some real-time (or as near as real time as possible) weather satellite imagery in the visible light.
image
Now this is what I call a cloud service  ;)
Now believe it or not, but all those beautiful maps are created by these simple methods way down in MainPage.Xaml.cs

private void TileComboChanged(object sender, SelectionChangedEventArgs e)
{
  MyMap.TileSources.Clear();
  var tileSource = TileCombo.SelectedItem as ITileSource;
  if (tileSource != null)
  {
    MyMap.TileSources.Add(new MapTileSource(tileSource.TileSource));
  }
}

private void InitTileComboBox()
{
  TileCombo.Items.Add("None");
  TileCombo.Items.Add(new OpenStreetMapSource());
  TileCombo.Items.Add(new GoogleMapSource("y", "Google Hybrid"));
  TileCombo.Items.Add(new WmsTileSource("NOAA Radar",
   "http://nowcoast.noaa.gov/arcgis/services/nowcoast/radar_meteo_imagery_nexrad_time/MapServer/WmsServer?", 
    new[] { "1" }, "1.3.0", "CRS"));
  TileCombo.Items.Add(new WmsTileSource("NOAA Visible Img",
   "http://nowcoast.noaa.gov/arcgis/services/nowcoast/sat_meteo_imagery_goes_time/MapServer/WMSServer?", 
   new[] { "9" }, "1.3.0", "CRS"));
  TileCombo.Items.Add(new WmsTileSource("RWS NWB", 
    "http://geodata.nationaalgeoregister.nl/nwbwegen/ows?service=WMS", 
      new[] { "wegvakken", "hectopunten" }));
  TileCombo.Items.Add(new WmsTileSource("RWS NWB 4326", 
    "http://geodata.nationaalgeoregister.nl/nwbwegen/ows?service=WMS", 
    new[] { "wegvakken", "hectopunten"},"1.3.0", "CRS", 4326));

  TileCombo.SelectedIndex = 0;
}

And, of course, 'the supporting act' of some classes I wrote myself.

 
Tile sources
Welcome to the wonderful world of tile maps. Our friends of the Maps develop team have created a small class hierarchy to serve up tile maps to a Windows app map. Add any child of MapTileSource to your map's TileSource collection and you have created a new map. It's as simple as that. There are three kinds of map tiles sources, as depicted in the diagram below:
image

  • HttpMapTileDataSource is meant to serve up map tiles via an URI to the web and download them on the fly
  • LocalMapTileDataSource is meant to serve up map tiles via an URI to titles that are downloaded to local storage
  • CustomMapTileDataSource is meant to cover all other cases - it does not ask for a remote or a local URI to a map tile, but asks you to return a 256x256 bitmap and it's up to you to determine where it comes from or how it's created.
My samples use HttpMapTileDataSource only, but of course the other classes are very interesting too, specifically LocalMapTileDataSource, as it opens the possibility to download and use tiles from any map to your device and use it from there, thereby creating your own Here-Maps-like offline experience.
HttpMapTileDataSource has a UriRequested event. You will need to attach a listener to it with this signature:
void MapUriRequested(
     HttpMapTileDataSource sender, 
     MapTileUriRequestedEventArgs args);
MapTileUriRequestedEventArgs has a Request property with four parameters:
  • Request
  • X
  • Y
  • Zoomlevel
The last three are input, based upon which the event listener must calculate a Uri, which needs to be put in Request - the output property. How this works in practice can be seen in for instance the OpenStreetMapSource:
private readonly static string[] TilePathPrefixes = { "a", "b", "c" };

protected override void MapUriRequested(HttpMapTileDataSource sender, MapTileUriRequestedEventArgs args)
{
  var deferral = args.Request.GetDeferral();
  // TilePathPrefixes - load balancing + caching
  args.Request.Uri = new Uri(
    $"http://{TilePathPrefixes[args.Y % 3]}.tile.openstreetmap.org/{args.ZoomLevel}/{args.X}/{args.Y}.png");
  deferral.Complete();
}
Where do you get this wisdom? You can be a GIS expert, or just look for these kinds of tricks on the internet, and mostly they can be found on the tile provider's site itself. Sufficient to say OpenStreetMaps has 3 servers, and then the X, Y and Zoomlevel are simply in the path and the filename.
The MapTileDataSource and it's children sport a weird oddity, though. The most logical approach would be to subclass HttpMapTileDataSource, right? This is possible, as they are not sealed. All is well, up until the moment you actually try to use such a child class in real life by adding it to the map TileSources collection and have the map display itself. Then you are greeted by
An exception of type 'System.Runtime.InteropServices.InvalidComObjectException' occurred in Manipulation_Drawing.exe but was not handled in user code
WinRT information: The text associated with this error code could not be found.
And good luck to you. Fortunately, where's a need, there's a workaround. I made a class containing a HttpMapTileDataSource, implementing an interface exposing that HttpMapTileDataSource. Meet BaseHttpTIleSource and it's friends.
image
ITileSource is pretty simple, as I alluded to:
interface ITileSource
{
  MapTileDataSource TileSource { get; }
}
It basically allows you to add YourTileSource.TileSource to the map's TileSource's collection without having aforesaid crash. BaseHttpTileSource is pretty simple, too.
public abstract class BaseHttpTileSource : ITileSource
{
  protected BaseHttpTileSource()
  {
    var t = new HttpMapTileDataSource();
    t.UriRequested += MapUriRequested;
    TileSource = t;
  }

  public MapTileDataSource TileSource { get; private set; }

  protected abstract void MapUriRequested(HttpMapTileDataSource sender, 
    MapTileUriRequestedEventArgs args);
}
It takes away most of the plumbing of using a HttpMapTileDataSource and the only thing you need to do is subclass this and override the MapUriRequested method. As shown for OpenStreetMaps, and there is also such an override for Google:
protected override void MapUriRequested(HttpMapTileDataSource sender, MapTileUriRequestedEventArgs args)
{
  var deferral = args.Request.GetDeferral();
  args.Request.Uri = 
    new Uri($"http://mt{(args.X%2)+(2*(args.Y%2))}.google.com/vt/lyrs={mapPrefix}&z={args.ZoomLevel}&x={args.X}&y={args.Y}");
  deferral.Complete();
}

Once again, this violates Google's TOS, but the trick is very old and I wrote first about it almost exactly five years ago. I still wait for Google's lawyers to turn up on my doorstep, at which point I will gladly discuss the lack of a decent API for Windows apps which enables us to use the data in a legitimate way.

WMS maps
Web Map Services is a prime example of the age-old wisdom stating a camel is a horse designed by a committee - the committee in this case being the Open Geo Consortium. OGC is - or at least was in that time - a group op GIS professionals of academic origin and they have clearly tried to a design a protocol that catered for a wide variety of analytic needs - of course using XML, which was the hot rage in the days it was designed. What they did not do was taking into account banal things like consistency, ease of use, performance, and other things that are valued by mere mortals who just want to have a bloody map in their web page or app. And if you think this is bad, try to read the specifications for vector data (WFS or Web Feature Service), a format so convoluted, bloated, with so much versions, inconsistencies and complexities that it almost requires a PhD to get a basic understanding of how it works - let alone use it. WMS servers used to be slow, bandwidth and processing power gorging monsters. And this in the early 2000s, the year where most web access was served over 56k6 dial up lines, and a top of the line computer had a Pentium 4 processor. No wonder it never gained much use outside of the specialist realm.
But I digress. I wrote a small class that will serve as a WMS client for the limited scenarios that play nice with the Windows map control, which require little knowledge of the actual plumbing for using it. This class is called WmsTileSource, How it's used, you can see in InitTileComboBox, where I initialize four instances of it. To explain how you get to such parameters, I will need to explain a bit first. The next paragraph is me getting on my GIS hobby horse. If you do not care about that, at least read the two bullet points halfway and the first sentence of the paragraph below the Africa picture.


Projections (and coordinate systems)

See the source imageThis may come as a surprise, but the Earth is not flat, yet every map since the beginning of map making pretends it is. This has various, mostly historical reasons, the most notable being the fact it's much easier to roll up a flat map of the of Earth's pieces you are interested in (or put a lot of them in a book) and take those along for the trip, than to lug around a true representation of the Earth - which most likely would contain a lot of details on stuff you don't need, and too little of the stuff you do. Yes kids, people used to lug atlases around, books with maps. They have the added bonus of never running out of battery.



So a map needs (or needed) to be flat, which makes it necessary to put the outside of what is essentially a sphere on a flat surface. That cannot be done without some dire consequences. Peel an orange and try to make the outside a continuous flat surface - and you will understand what I mean.
This is where projections come into play. These are ways to fit the sphere's outside on a flat surface. There are literally thousands of projections in use, both for the whole planet and for parts of it - so much they are mostly designated by numbers - so called EPSG numbers - not by name. To the left I show only a few ways to project Earth. The most well-known version is the Mercator projection, shown top-left. It is also known as WGS84 or EPSG:4326 (that is the number I meant). There is also a variant of this, hated by professional cartographers everywhere, but it became instantly and overnight the most used projection worldwide as it is used by Google Maps. It is referred to as 'popular Mercator', initially had the tongue-in-cheek designation EPSG:900913 (900913 being 'Google in "leet speak"), later officially adopted as EPSG:3857.
The point of this whole rambling paragraph is two-fold:

  • The Windows 10 Maps control uses the EPSG:3857 projection. This means that only WMS servers that support delivering maps in EPSG:3857 / EPSG:900913 will correctly show data (that is, roads and stuff will appear on exactly the same places as your standard Here Maps data). EPSG:4326 will give 'mostly correct' results, provided you don't zoom out too much. All other projection systems won't work at all. At best they will show stuff in the wrong place, most likely it will appear to be wildly distorted as well.
  • The Popular Mercator projection comes with some severe consequences. One of them is that the further you go from the equator (move closer to the poles), the more stuff gets stretched. A whole generation now has grown up believing Greenland is about the size of Canada (the biggest country in the world bar Russia), and the northern American continent is about the size of Africa. Well, have a look at this map - and have a reality check, too. Cheers!

image
One minor detail: another thing Google made us do was using the WGS84 coordinate system (aka "lat/lon", standing for latitude and longitude) for a projection is was not intended to, because that is so convenient when using it in conjunction with satellite navigation. There are also a lot of ways to designate locations on Earth other than just latitude and longitude, but outside the GIS inner circle hardly anybody knows - and even less people care. There is a lesson to be learned: if you design too academically oriented standards, they will be wiped out or at least bastardized by market parties more interested in practical appliances than scientific correct approaches.


Finding the right parameters for the WmsTileSource
Enough theory (and rambling) - we will now get down to business and actually use the WmsTileSource. First, you will need to know where the WMS server you want to use is actually located. This can be quite a challenge, but some institutions are really helpful. If you enter "noaa wms server" in Bing or Google and search a little around you will quite readily get to this site that shows you a whole range of interesting servers.
image
The important thing to know is that a WMS server can provide you with metadata about what it can and cannot do. These are called "capabilities" and you can get them but getting adding "?service=WMS&request=getcapabilities to the WMS URL. NOAA already has provided those links in their page - how thoughtful of them. You can click those links best using *cough*Google Chrome*cough* as that readily displays XML rather than trying to download it. So I clicked the third link (for "Recent GOES Weather Satellite Imagery", not visible in the image above) and then you get a rather depressingly long and hard to read XML potpourri. But don't despair, I will learn you a few tricks to quickly distill the things you need. We will need to find out:

  1. Does this thing support ESPG:3857, EPSG:900913 or EPSG:4326?
  2. What coordinate system tag is it using?
  3. What layers are available?
  4. What version of WMS is it running?

Find the EPSG
This one is easy. Just search for the number 3857, if you don't find that try 900913, then 4326. If you don't find anything, you're out of luck and the server is unusable. But good old NOAA does not fail us
image
So yes, we can use this server, it supports even the most optimal projection (and 4326 as well, but why use good if you can get perfect).

Find the coordinate tag
Over time the WMS standard has 'evolved'. In ye olden days the coordinate system was designated using the SRS tag, now it's mostly using the CRS tag. I think - but I am not sure - in WMS version 1.1.1 it was SRS, in 1.3.0 it's CRS. Anyway - you can quite easily find this by first searching for CRS, and if you cannot find that, SRS. See the image above - this one is clearly using CRS.


Find available layers

Guess what - you search for the text "Layer". Inside that Layer you will find a Title describing what it is and a Name that you will need to refer to it. NOAA have made this a bit complicated, but the important thing is to hunt for the Layer/Name.
image
So for Visible Imagery you will need a layer with the name "9". Usually a more descriptive name is used, but whatever.


Find the WMS version

Sometimes you can get this out of the URL, but if you cannot - well, you guessed it. Find the word "version" and that will give you give you most likely two possible outcomes: 1.3.0 or 1.1.1


Putting it all together
So know we have:

  • EPSG = 3857
  • Coordinate system tag = "CRS"
  • Layer = "9"
  • WMS version is "1.3.0"
This will allow us to construct a WMS layer like this:
new WmsTileSource("NOAA Visible Img",
"http://nowcoast.noaa.gov/arcgis/services/nowcoast/sat_meteo_imagery_goes_time/MapServer/WMSServer?", 
 new[] { "9" }, "1.3.0", "CRS"));

Notice that the layers are actually constructed as an array, as you can request for multiple layers on top of each other. This only makes sense when the layers are partially transparent, and visible imagery is not - so in this case it doesn't make sense. But if you want to use radar rain images on top of cloud data (see code inside InitTileComboBox) that makes perfect sense. Be aware that layers a drawn in order of appearance, so the last layer in the array will appear on top.
Also notice I did not provide any data for the EPSG. That is because that's the last parameter, and it's default value is 3857.


One more thing
In all cases - be it WMS to TMS - the device you are using goes out to the web to get tiles. That is why a HttpMapTileDataSource has an "AllowCaching" property, that is default set to true. So even if you don't download map tiles to your device, it still caches them - a nice feature for both your users and the map providers.


Conclusion
I have shown you the amazing versatility of the Windows Maps control in nearly all aspects in this series, and hope to have inspired you to look beyond the data that is offered by default with this last post. The world of geo data is a fascinating one, it is a shame so much is locked up behind the complexities of confusing, convoluted and/or outdated protocols.
Enjoy mapping! And let me know if you have found a cool map server to use in your app.

16 October 2015

Borders on Xamarin Forms user interface elements

This is one of those blog posts, born out of utter frustration because looking for this yielded no usable results - while you would expect a lot of people would be wanting to do, as it's quite elementary IMHO. Maybe it's just my inexperience with Xamarin Forms, but for the life of me I could not find how to place borders around panel-like structures like a grid. Sure, there is Frame, but that places a meager 1 pixel hardly visible line around it.

Suppose I had this code

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="XamBorders.MainPage" BackgroundColor="White">
  <ContentView Padding = "20" VerticalOptions="Start" >
    <Label Text="I want a border here!" 
           FontSize="20" TextColor="Black" 
           HorizontalOptions="Center"></Label>
  </ContentView>
</ContentPage>

Result in in the UI below (on the Visual Studio Android Emulator) image

How on Earth do you get something like this?

image

Turns out you need a couple of ContentViews inside each other like a bunch of Matryoshka dolls - one with the border color as background color, and inside that a slightly smaller ContentView with the same background color as the page. Like this:

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="XamBorders.MainPage" 
  BackgroundColor="{StaticResource BackgroundColor}">
  <ContentPage.Resources>
    <ResourceDictionary x:Name="AppDictionary">

      <Color x:Key="BackgroundColor">#FFFFFF</Color>
      <Color x:Key="BorderColor">#E1E1E1</Color>

      <Style x:Key="InternalViewStyle" TargetType="ContentView">
        <Setter Property="BackgroundColor" 
Value="{StaticResource BackgroundColor}"/> <Setter Property="VerticalOptions" Value="Fill"/> <Setter Property="Padding" Value="10,10,10,10"></Setter> </Style> <Style x:Key="BorderStyle" TargetType="ContentView"> <Setter Property="BackgroundColor" Value="{StaticResource BorderColor}"/> <Setter Property="Padding" Value="3,1,1,3"></Setter> </Style> </ResourceDictionary> </ContentPage.Resources> <ContentView Padding="20" VerticalOptions="Start" > <ContentView Style="{StaticResource BorderStyle}" > <ContentView Style="{StaticResource InternalViewStyle}"> <Label Text="I want a border here!" FontSize="20" TextColor="Black" HorizontalOptions="Center"></Label> </ContentView> </ContentView> </ContentView> </ContentPage>

So we have the internal view that has the same background color as the page, as well as a padding of 10 on every side to make the border not too tight around the text. Then the 'border contentview' around that has a padding 0 3,1,1,3 so that it's slightly larger bottom and right as to create some kind of shadow effect. If you don't want that, just make the padding equal. I defined the settings a styles as to make them easily reusable (they are in a app-wide resource dictionary in the app I am now developing).

Why it has to be this way - no idea, but I hope it will save some other Xamarin Forms newbie the frustration I experienced this afternoon. Maybe there are better alternatives - I really welcome comments. But this works

Sample project can be found here.

10 October 2015

Windows 10 maps part 6 - scenes and camera

Intro
Picking up the thread where I left it rushing into an IoT series, which I wanted to have ready before the Microsoft devices event that took place on October 6th, I will now write bit about scenes and camera. These are features that are part are designed to work with the new 3D view, that already made an appearance in the previous part of this series.

The problem
Maps in were always 2D previously. You can play with the pitch and show landmarks on it, and that gets a bit of a 3D effect, but the map itself is still flat, and the view on your map is orthogonal (that is, straight from above), like you are holding a paper map. Only the zoom level (i.e. the distance from your eye to the map) and the point directly below you (the map center) determined what you look at. This approach no longer works when you use a 3D map like Windows 10 features. Now, you are basically floating in space next to a sphere (Earth, to be specific) and you can look in any direction you want - directly below the point you are floating next to (or above, whatever) but you can also look sideways, to the 'top' of the sphere, or even from it. You can rotate so South is up. So although the point directly below you and the distance between ('height') are still a factor in what you can see, they are no longer the only factor.

To illustrate what I mean, I can best show a few pictures. First, here we have Earth, and we are floating directly over the Netherlands. Basically, there's not much different from a normal orthogonal map, although this shows a bit of the curve of the Earth

image

Now let's play a little with the controls:

  • First I changed the pitch using the canvas (the controls on the right of the map, the 2nd one from above)
  • Then I rotated about 180 degrees using the top canvas control

You get a totally different view now!

image

Space, the final frontier ;) .

The solution
We need a new helper class, something that helps us create a view given a number of parameters. And luckily, Microsoft have provided not one but actually two: MapCamera and MapScene.

My demo solution actually does very little with both: the save scene button saves the current way you are looking at the map (Earth), and Restore brings you back to it.

private MapScene lastScene;

private void SaveScene(object sender, RoutedEventArgs e)
{
  lastScene = MapScene.CreateFromCamera(MyMap.ActualCamera);
}

private void RestoreScene(object sender, RoutedEventArgs e)
{
  if (lastScene != null)
  {
    MyMap.TrySetSceneAsync(lastScene);
  }
}
MyMap.TrySetSceneAsync is actually async so it could be awaited, but since this is a simple fire-and-forget method I can't be bothered with that.

If we put a breakpoint in SaveScene we can see the MapCamera's values

image

And it's location

image

So apparently I am looking almost due South (Heading 181), from a location that about 1600km above a point that is a bit west and a whole lot more north than the Netherlands (latitude and longitude for the center of our tiny spec by the sea is about 52, 5), pitched upward almost 40°, and rolled a wee bit to the right. My app does not support setting all camera features, but you if you set a breakpoint on SaveScene and change the roll value to 90 before you let it continue, you will get this effect on hitting restore - and you can imagine looking out of a forward-looking window of your spaceship in orbit - that is presumably in some pretty unlikely polar orbit considering the direction it's travelling into

image

The properties of the MapCamera are all excellently explained here in the official documentation and there's also a very good picture illustrating what I mean with 'floating next to a sphere and lookup down on it'

Now Microsoft have recognized the fact that not everyone is a spatial expert and that it may indeed be very hard to create a view in a 3D map that shows all what you want using just the camera, especially when there are blocking features. That's where the MapScene class comes into place. As you may already have noticed, the Map's Camera itself is read only, you can only use the camera to create a Scene from, then put it back to a map.

The intent though is that you create a Scene using one of the static methods the class provides. There is a method to create a camera from a bounding box, optionally specifying a heading an a pitch, a method to create one from a location and a radius, but the best I like is the one that makes sure any number of points in a list will show up. This is a great feature to show all your initial points in your 3D map app - for instance, all flying airplanes in 3D within the target area of your map.

Conclusion
Lots of talk this time, little code. MapCamera and (especially) MapScene make programmatically navigating around a map a lot easier, but it still take some experimenting to check if you get desired results. For me, having grown up in a world of 2D maps and having worked in 2D GIS for 20+ years, it's just as hard as you ;)

30 September 2015

A Microsoft Band client to read temperatures and control a fan on a Raspberry PI2

Part 6 of Reading temperatures & controlling a fan with a RP2, Azure Service Bus and a Microsoft Band

Intro
In the final post of this series I will show how the Microsoft Band client in this project, that is used to actually read temperatures and control the fan, is created and operated. The client has a tile and a two-page UI, looks like this and can be seen in action in this video from the first blog post:

To recap - the function of the Band client is as follows

  • WhenI tap the tile on the Band, the UI is opened and shows the latest data, that is:
    • The temperature as last measure by the Raspberry PI2
    • A button I can use to toggle the fan. The text on the button reflects the current status of the fan (i.e. it shows "Stop fan" when it's running, and "Start fan" when it is not
    • Date and time of the last received data.

The classes involved
As you can see in the demo solution, there are three classes, and one interface, all living in the TemperatureReader.ClientApp's Models namespace - that have something to do with the Band:

  • BandOperator
  • BandUiController
  • BandUiDefinitions
  • IBandOperator

I showed a little bit of it in the previous post that described the Windows 10 UWP app itself, but to recap: the app is put together using dependency injection, so every class gets everything (well, almost everything) it needs passed via the constructor, and only knows what it gets via an interface (not a concrete class). In addition, most communication goes via events.

Start it up
If you look in the MainViewModel's CreateInstance method, you will see the BandOperator first spring into life:

public static MainViewModel CreateNew()
{
  var fanStatusPoster = new FanSwitchQueueClient(QueueMode.Send);
  fanStatusPoster.Start();
  var listener = new TemperatureListener();
  var errorLogger = SimpleIoc.Default.GetInstance<IErrorLogger>();
  var messageDisplayer = SimpleIoc.Default.GetInstance<IMessageDisplayer>();
  var bandOperator = new BandOperator(fanStatusPoster);
  return (new MainViewModel(
    listener, bandOperator, 
    messageDisplayer, errorLogger));
}

I grayed out the stuff that is not so important here, but you see the BandOperator uses the FanSwitchQueueClient (see explanation in this post) to defer sending data on Azure Service bus to, and then it's passed to the MainViewModel. Apparently some other mechanism is used to deliver temperature data from the Azure Service bus, and that code is found in the Start method of MainViewModel:

private async Task Start()
{
  IsBusy = true;
  await Task.Delay(1);
  _listener.OnTemperatureDataReceived += Listener_OnTemperatureDataReceived;
  _listener.OnTemperatureDataReceived += _bandOperator.HandleNewTemperature;
  await _listener.Start();
  await StartBackgroundSession();
  await _bandOperator.Start();
  await _bandOperator.SendVibrate();
  IsBusy = false;
}

You can see the listener - being a ITemperatureListener, see also this post - simply passes the event to the BandOperator, starts it, and makes the Band vibrate. So you see - the actual code that operates the Band is very loosely coupled to the rest of the app. But what you also see - the Band does not listen to the data coming form the Azure Service Bus, nor does it send data. That app does that interaction, and the Band - in turn - interacts with the app.

Some definitions first
What is important to understand is that the UI lives on the Band, an remains there. Changing it, and responding to events, is essentially a process that runs on your phone, not on the Band, and you are interacting with a process that sends data over Bluetooth - but that is mostly abstracted away. Building a Band UI is also vastly different from what you are used to, using XAML. You are basically writing code to build the structure of the UI, then fill it with data using even more code. There is no such things as data binding. All UI elements have to be defined using unique identifiers - no such things as easily recognizable names. It harkens back to ye olden days from even before Visual Basic.

Anyway, there is this separate definition class that contains all the necessary ids:

using System;

namespace TemperatureReader.ClientApp.Models
{
  public static class BandUiDefinitions
  {
    public static readonly Guid TileId = 
      new Guid("567FF10C-E373-4AEC-85B4-EF30EE294174");
    public static readonly Guid Page1Id = 
      new Guid("7E494E17-B498-4610-A6A6-3D0C3AF20226");
    public static readonly Guid Page2Id = 
      new Guid("BB4EB700-A57B-4B8E-983B-72974A98D19E");

    public const short IconId = 1;
    public const short ButtonToggleFanId = 2;
    public const short TextTemperatureId = 3;
    public const short TextTimeId = 4;
    public const short TextDateId = 5;
  }
}

So we have three main UI ids - the tile, and both 'pages', that need to have a GUID. I just generated a few using Visual Studio, what GUID you use does not really matter - they need to be different from each other and refrain from re-using them - even over projects. Then there's five user interface elements.

  • On the first page - the one you see when you tap the tile: the thermometer icon, the button to turn the fan on or off (also used to show the current fan status), and the label that shows the temperature as measured by the Raspberry PI2
  • On the second page two label fields, that show the time and the date of the last received update from the Azure Service Bus as received by the App.

The UI looks like this:

IMG_2288
The tile that you can tap

IMG_2289
The first page, with icon, temperature reading and button. The button now says "Start fan", so apparently the app has already received date from the Raspberry PI2, and it indicated the fan is off. Notice a little part of the second page is already visible on the right, alerting the user there's more to be seen and encouraging him to scroll to the right - a UI pattern in use since the very early days of Windows Phone 7.

IMG_2290

The second page (with date and time of last received data)

The user interface element ids are just just integers, but I make them globally unique - that is, unique in the app. The fact that they are spread over two 'pages' comes from the fact that the Band has a very small display, and you will need to make use of it's multi-page features if you want to show anything but the most trivial data. Fortunately, once you understand how it works, that is not very hard to do.

Building the Band client UI
I have separated the actual operating building and manipulating of the Band UI from the 'business logic' concerning the interaction with events coming from the Azure Service Bus. So we have the BandUiController and the BandOperator. A crude and not completely correct analogy could define the BandUIController as the view, and the BandOperator as a kind-of-viewmodel. I did this because at one point I had a class approaching 300 lines and things got very confusing. So I split it up. I show only a little excerpt of the BanOperator before I start explaining the BandUIController first.

The BandUIController needs access to a IBandClient to be able to work on the Band's UI. You need to retrieve one first. How this works, you can see in the BandOperator's GetNewBandClient method:

var pairedBands = await BandClientManager.Instance.GetBandsAsync();
if (pairedBands != null && pairedBands.Any())
{
  return await BandClientManager.Instance.ConnectAsync(pairedBands.First());
}

And this IBandClient is injected into the BandUIController via the constructor. We have seen this pattern before in this series

public class BandUiController
{
  private readonly IBandClient _bandClient;

  public BandUiController(IBandClient bandClient)
  {
    _bandClient = bandClient;
  }
}

The next important thing to understand is that although both occur from code, defining the Band interface and actually displaying stuff in it are two separate actions. The public interface of the BandUIController actually only has four methods - and one of them is an overload of another:

public async Task<bool> BuildTile();
public async Task RemoveTile();
public async Task SetUiValues(string timeText, string dateText, 
                              string temperature, string buttonText);
public async Task SetUiValues(string temperature, string buttonText);

The first one builds the tile (and the rest of the UI), the second one removes it. The third one sets all the UI elements' value, the second one only that of the elements on the first page - that is used for when you press the button to switch the fan on or off. So let's have a look at BuildTile first.

public async Task<bool> BuildTile()
{
  if (_bandClient != null)
  {
    var cap = await _bandClient.TileManager.GetRemainingTileCapacityAsync();
    if (cap > 0)
    {
      var tile = new BandTile(BandUiDefinitions.TileId)
      {
        Name = "Temperature reader",
        TileIcon = await LoadIcon("ms-appx:///Assets/TileIconLarge.png"),
        SmallIcon = await LoadIcon("ms-appx:///Assets/TileIconSmall.png"),
      };

      foreach (var page in BuildTileUi())
      {
        tile.PageLayouts.Add(page);
      }
      await _bandClient.TileManager.AddTileAsync(tile);
      await _bandClient.TileManager.RemovePagesAsync(BandUiDefinitions.TileId);
      await _bandClient.TileManager.SetPagesAsync(BandUiDefinitions.TileId, 
        BuildIntialTileData());
      return true;
    }
  }
  return false;
}

imageFirst thing you need to do is check remaining tile space capability. There's only room for up to 13 custom tiles, so chances are there's not enough room. If there is no space, this client silently fails. But if there's room, the tile is created with the designated GUID, a big and a small icon. The big icon appears on the tile, the small icon is typically used on notifications, but both can be used otherwise (as we will see later). "Large" is maybe stretching it a little as it's only 46x46 (the small one is 24x24). "LoadIcon" is a little routine that loads the icon and I nicked those from the Band samples. Then the tile UI pages are being built using BuildTileUi, and are added to the tile's PageLayout collection. So far, so good. Then things get a little murky.

  • First we add the tile - with page definitions - to the Band UI. By default, it is added to the very right side of the tile strip - just before the settings gear tile.
  • Then we remove any possible data possibly associated with the pages using RemovePagesAsync. Remember, this is not the structure, just what is being displayed on it. I am not 100% sure this line of code is actually needed, but I just left it while experimenting
  • Then we are adding the default data to display on the tile pages' UI elements using SetPagesAsync

Let's first have a look at BuildTileUi

private IEnumerable<PageLayout> BuildTileUi()
{
  var bandUi = new List<PageLayout>();
  
  var page1Elements = new List<PageElement>
  {
    new Icon {ElementId = BandUiDefinitions.IconId, 
Rect = new PageRect(60,10,24,24)},
new TextBlock {ElementId = BandUiDefinitions.TextTemperatureId, Rect = new PageRect(90, 10, 50, 40)}, new TextButton {ElementId = BandUiDefinitions.ButtonToggleFanId, Rect = new PageRect(10, 50, 220, 40), HorizontalAlignment = HorizontalAlignment.Center} }; var firstPanel = new FilledPanel(page1Elements) {
Rect = new PageRect(0, 0, 240, 150) }; var page2Elements = new List<PageElement> { new TextBlock {ElementId = BandUiDefinitions.TextTimeId, Rect = new PageRect(10, 10, 220, 40)}, new TextBlock {ElementId = BandUiDefinitions.TextDateId, Rect = new PageRect(10, 58, 220, 40)} }; var secondPanel = new FilledPanel(page2Elements) {
Rect = new PageRect(0, 0, 240, 150) }; bandUi.Add(new PageLayout(firstPanel)); bandUi.Add(new PageLayout(secondPanel)); return bandUi; }

Now this may look a bit intimidating, but it's actually not so hard to read.

  • First we create the UI elements of the firstpage - an Icon, a TextBlock, and a TextButton, all with location and size defined by a PageRect, relative to the panel they are going to be in.
  • Then we create the first panel, add the list of the UI elements created in the previous step on it, then define it's size and location by a PageRect as well. I am not exactly sure what the maximum values are for a panel, but 240, 150 works out nice and leaves enough space to the right to make the next page visible
  • Then we create the UI elements of the second panel - two TextBlocks of identical size, the second one right under the first
  • Then we create a second panel with the same size as the first panel
  • Finally, we create a PageLayout  from both panels and add those to the list.

As we could see in the BuildTile method the result of the BuildTileUi method is added the tile's PageLayouts collection:

foreach (var page in BuildTileUi())
{ tile.PageLayouts.Add(page); }

At this point, we have only defined the structure of what is to be displayed on the Band. It still does not display any data.

Showing data on a Band UI
Let's have a look at BuildTile again. It's using this line of code to display data

 await _bandClient.TileManager.SetPagesAsync(BandUiDefinitions.TileId,
BuildIntialTileData());
BuildIntialTileData. that just shows some default strings, in turn calls this method
private List<PageData> BuildTileData(string timeText, string dateText, 
                                     string temperature, string buttonText)
{
  var result = new List<PageData>
  {
    BuildTileDataPage2(timeText, dateText),
    BuildTileDataPage1(temperature, buttonText)
  };
  return result;
}

And then we come to the heart of the matter (as far as displaying data is concerned) - that is, these two little methods:

private PageData BuildTileDataPage1(string temperature, string buttonText)
{
  return 
    new PageData(
      BandUiDefinitions.Page1Id, 0, 
      new IconData(BandUiDefinitions.IconId, 1),
      new TextButtonData(BandUiDefinitions.ButtonToggleFanId, buttonText),
      new TextBlockData(BandUiDefinitions.TextTemperatureId, $": {temperature}"));
}

private PageData BuildTileDataPage2(string timeText, string dateText)
{
  return 
    new PageData(BandUiDefinitions.Page2Id, 1,
      new TextBlockData(BandUiDefinitions.TextTimeId, $"Time: {timeText}"),
      new TextBlockData(BandUiDefinitions.TextDateId, $"Date: {dateText}"));
}

Let's first dissect BuildTileDataPage2 as that is the most simple to understand. This says, basically: for page with Page2Id, which is the 2nd page on this UI (the page numbering  is zero based) set a text on a TextBlock with id BandUiDefinitions.TextTimeId, and set another text for BandUiDefinitions.TextDateId. The third parameter of the PageData constructor is of type params PageElementData[] so you can just go on adding user interface value settings to that constructor without the need of defining a list.

In BuildTileDataPage1 we do something similar - bar that the page index now is 0 in stead of 1, a text on a TextButton needs to be of TextButtonData in stead of TextBlockData. and the first item is an IconData. Notice that it adds an icon with index 1. That is the small icon. Remember this piece of code in BuildTile?

var tile = new BandTile(BandUiDefinitions.TileId)
{
  Name = "Temperature reader",
  TileIcon = await LoadIcon("ms-appx:///Assets/TileIconLarge.png"),
  SmallIcon = await LoadIcon("ms-appx:///Assets/TileIconSmall.png")
};

That was added as second, but of course that's zero based as well. You can also add additional icons to the UI but that's not covered here.

Now there is one important final piece of information that you may not have noticed. In BuildTileData I first add the second pagedata to the list, and then the first. I found it necessary to do it that way, or else the UI appears in reverse order (that is, the page with the date/time is displayed initially, and you have to scroll sideways for the page with the button and the temperature. Sometimes, just sometimes it happens the wrong way around anyway. I have not been able to determine what causes this, but if you add the pagedata in reverse order, it works most times - like in, I saw it go wrong two or three times, and only during heavy development.

The public methods to change the UI values are very simple wrappers around code we have already seen:

public async Task SetUiValues(string timeText, string dateText, 
                              string temperature, string buttonText)
{
  var pageData = BuildTileData(timeText, dateText, temperature, buttonText);
  await _bandClient.TileManager.SetPagesAsync(BandUiDefinitions.TileId, pageData);
}

public async Task SetUiValues(string temperature, string buttonText)
{
  await
    _bandClient.TileManager.SetPagesAsync(BandUiDefinitions.TileId,
       BuildTileDataPage1(temperature, buttonText));
}

The first one refreshes the whole UI, the second only the first page. So that is what is necessary to create a UI and display some data on it. Four UI elements, two pages. Really makes you appreciate XAML, doesn't it? ;)

Handling Band interaction
The BandOperator bascially only has the following functions:

  • When a tile is pressed, show the Band UI with the most recent data received from the Azure Service bus
  • When the toggle button is pressed fire off a command on the Azure Service bus
  • When the fan status change is confirmed by the Raspberry PI2, toggle the text on the button

... and yet, it's almost 250 lines long. A lot of that has to do with problems I encountered when a suspended app was resuming. I have tried to fix that using quite an elaborate method to get and create a Band client (the GetBandClient method) - that and it's helper methods are 60 lines in itself. So I will skip over that, but have a look at it in the demo solution to see how I tried to solve this. I am still not quite satisfied with it, but it seems to work. Most of the times.

Moving to the BandOperator's Start method, you can see how the interaction is set up

public async Task<bool> Start(bool forceFreshClient = false)
{
  var tilePresent = false;
  var bandClient = await GetBandClient(forceFreshClient);
  if (bandClient != null)
  {
    var currentTiles = await bandClient.TileManager.GetTilesAsync();
    var temperatureTile = currentTiles.FirstOrDefault(
      p => p.TileId == BandUiDefinitions.TileId);
    if (temperatureTile == null)
    {
      var buc = new BandUiController(bandClient);
      tilePresent = await buc.BuildTile();
    }
    else
    {
      tilePresent = true;
    }

    if (tilePresent)
    {
      await bandClient.TileManager.StartReadingsAsync();
      bandClient.TileManager.TileOpened += TileManager_TileOpened;
      bandClient.TileManager.TileButtonPressed += TileManager_TileButtonPressed;
    }
  }
  IsRunning = tilePresent;
  return tilePresent;
}

Basically this methods tries to either find an existing tile, and failing that, create a BandUiController to make one. bandClient.TileManager.StartReadingsAsync then activates listening to Band events - and by attaching events to TileOpened and TileButtonPressed the handler methods will be called - if the tile on the Band UI button is pressed, or if a button on the custom UI of the tile is pressed.

private async void TileManager_TileOpened(object sender, 
  BandTileEventArgs<IBandTileOpenedEvent> e)
{
  var bandClient = await GetBandClient();
  if (bandClient != null)
  {
    if (e.TileEvent.TileId == BandUiDefinitions.TileId && _lastTemperatureData != null)
    {
      var buc = new BandUiController(bandClient);
      await buc.SetUiValues(
        _lastTemperatureData.Timestamp.ToLocalTime().ToString("HH:mm:ss"),
        _lastTemperatureData.Timestamp.ToLocalTime().ToString("dd-MM-yyyy"),
         $"{_lastTemperatureData.Temperature}°C",
         GetFanStatusText());
      await bandClient.NotificationManager.VibrateAsync(
         VibrationType.NotificationOneTone);
    }
  }
}

So the funny thing is - this method gets called when a tile is pressed on the Band. Any tile, not necessarily the one just created. So first we have to determine if it was actually our tile that was being pressed, by checking the tile id against the id of our tile. When that is the case, we create a BandUIController and update the UI values with the last received data from the Azure Service bus. And then we send a single vibration, so the Band wearer knows new data was received immediately (without checking the date and time on the 2nd page of our custom UI).

A similar procedure goes for the handling of the fan button press:

private async void TileManager_TileButtonPressed(object sender, 
   BandTileEventArgs<IBandTileButtonPressedEvent> e)
{
  var te = e.TileEvent;
  if (te.TileId == BandUiDefinitions.TileId && 
    te.PageId == BandUiDefinitions.Page1Id && 
    te.ElementId == BandUiDefinitions.ButtonToggleFanId)
  {
    if (!_isProcessing)
    {
      _lastToggleUse = DateTime.UtcNow;
      _isProcessing = true;
      var cmd = new FanSwitchCommand(_lastFanStatus, true);
      Debug.WriteLine($"Sending fan command {cmd.Status}");
      await UpdateFirstPageStatus();
      await _fanStatusPoster.PostData(cmd);
    }
  }
}

First, we need to check if the button was pressed on our custom layout  - in theory, that would have been enough as there is only one button on it, but for good measure you can also check for the page and the element id in that page. What then basically happens is that text of the button is changed to "Processing" and a FanSwitchCommand is sent to the Raspberry PI2.

The changing of the text on the button is done via UpdateFirstPageStatus, that in turn uses GetFanStatusText

private async Task UpdateFirstPageStatus()
{
  var bandClient = await GetBandClient();
  if (bandClient != null)
  {
    var text = GetFanStatusText();
    var buc = new BandUiController(bandClient);
    await buc.SetUiValues($"{_lastTemperatureData.Temperature}°C", text);
  }
}

private string GetFanStatusText()
{
  return _isProcessing ? "Processing" : 
    _lastTemperatureData.FanStatus == FanStatus.On ? "Stop fan" : "Start fan";
}

The logic behind this is as follows:_isProcessing used to prevent the user from pressing the toggle button multiple times in a row. When you press the button, one of the first things that happens is that _isProcessing is set to true, effectively barring you from doing something with the button again. The text on the button changes to "Processing". The BandOperator is now waiting for the Raspberry PI2 to confirm it has actually toggled the fan. But you cannot change the value of one UI element on a Band page - you have to refresh all of them. So I call the BandUiController's SetUiValues overload with both the new button text and the last received temperature.

So how is the loop closed? How does the BandOperator know the Raspberry PI2 has indeed toggled the fan? The answer lies in the HandleNewTemperature method that receives new temperature data from the rest of the app (remember that it was wired up in MainViewModel.Start?)

public async void HandleNewTemperature(object sender, TemperatureData data)
{
  Debug.WriteLine(
    $"New temperature data received {data.Temperature} fanstatus = {data.FanStatus}");
  _lastTemperatureData = data;
  _lastTemperatureData.Timestamp = DateTimeOffset.UtcNow;
  if (_lastFanStatus != _lastTemperatureData.FanStatus && _isProcessing)
  {
    _isProcessing = false;
    _lastFanStatus = _lastTemperatureData.FanStatus;
    await UpdateFirstPageStatus();
  }
  else if (_lastToggleUse.IsSecondsAgo(Settings.FanSwitchQueueTtl) && _isProcessing)
  {
    _isProcessing = false;
    _lastFanStatus = _lastTemperatureData.FanStatus;
    await UpdateFirstPageStatus();
  }
  else if (!_isProcessing)
  {
    _lastFanStatus = _lastTemperatureData.FanStatus;
  }
}

So, the received temperature data does not only contain temperature but also the current status of the fan. But if this method was to accept the fan status right away after we had sent off a command to toggle the fan, the button text would immediately flip back to the old text - because the command had not reached the Raspberry PI2 yet, and it would not have time to react and send a confirmation.

So what we do is - when new temperature data arrives, _isProcessing is true (so the user has recently clicked the toggle button) and the received data indicates a status flip - then the Raspberry PI2 has received the toggle command and has acted upon it. So the button is updated from "Processing" to a value according the new fan status. If there is no status change, but the last toggle button use was longer ago then the message time-to-live of the FanSwitchQueue - we assume the command has never reached the Raspberry PI2, we update the _lastFanStatus to the old status, and update the button accordingly. In any other cases, if the user has not pressed the button recently, we just keep the last fan status. This has not much to do with the Band or the UI itself - it's just dealing with possible delays from message delivery (and possible messages not being received by the other party).

Conclusion
Making a custom Band UI is doable, but you do need to pay a lot of attention to detail to get things right. It's definitely more challenging than creating a UI using Blend, as you basically need to keep seeing the whole UI in your mind - there is no way of visually designing it or even make it visible short of running the app and checking the result on the Band. Debugging is a time and battery consuming activity. Acting upon events and having code interact with remote devices has some particular challenges too. And sometimes things just go wrong - but it is not always clear if those things were caused by me doing things wrong or not understanding the finer details of the Band UI API, the fact that I am using it on Windows 10 mobile (which is still in preview at this moment) or bugs in the various APIs (Band or otherwise) that I use to stitch things together. On the bleeding edge is where you suffer pain - but you have the most fun as well.

And yet, the potential use cases are pretty appealing and  are giving a nice idea of how the (very near) future of device coding with Windows CoreIoT looks like. And it has practical appliances too. Recently I was on a holiday in Neustadt an der Weinstraße (where amongst others this blog post was written so the sample location was not entirely random :) ) I had this contraption running at home - but I had put in in my study at home and had connected it to a powerful spot light in stead of a fan. I had my Lumia 1520 and Band with me - and although being physically in Germany, I was able to turn on a light at home (and get confirmation it was actually on or off) by clicking a button on my Band. Thus hopefully convincing potential burglars the house's resident geek was at his computer and the house was occupied. Not that there's much worth stealing anyway, but it's not fun to get home and find broken windows and stuff. If it had any effect - I don't know, but our house was left alone during our absence.

Well, this marks the end of a rather epic and quite voluminous blog post series.I encourage you one final time to download and check the demo solution - and build kick *ss stuff yourself with CoreIoT and/or the Band. Even Doctor Who is into wearable technology these days, and so should we all be :D