Create a standard IoT Device Binding template

[shaggygi]

Core Objective

To establish a rich set of quality .NET bindings making it straightforward to use .NET and IoT devices, there needs to be a rich offering of supporting tooling. And while it will be very difficult to manage bindings (code, docs, etc.) across the range of producers, we can lower the "how to get started bar" that will hopefully make bindings more consistent as the ecosystem grows. This objective is part of that initiative where it attempts to explain the goal along with various action items.

Current Binding Structure

Below shows the current device binding structure based on the Device Binding README.

NOTE: [IotDeviceBinding] represents the actual name of binding. For example, Mcp3008, Mcp23xxx, etc.

iot/
  src/
    devices/
      [IotDeviceBinding]/
        [IotDeviceBinding].csproj
        [IotDeviceBinding].cs
        README.md
        samples/
          [IotDeviceBinding].Sample.csproj
          [IotDeviceBinding].Sample.cs
          README.md
        tests/   <--  Tests are optional, but if present they should be layed out like this.
          [IotDeviceBinding].Tests.csproj
          [IotDeviceBinding].Tests.cs

Future Work

One approach to create a consistent structure with ease is to offer an IoT Device Binding template based on the .NET Templates.

There is a PR #114 that provides a template as an exercise. If this PR is accepted, there are a few action items that need to be completed. I'm sure I am not thinking of everything so please chime in to help this effort.

• Setup a NuGet package for the template.

  Currently, the user is required to download the project to local machine and point to a folder when executing the dotnet new command. It would be more efficient if there is an official package.

• Verify and improve the template.json file.

  This currently includes the basics. What else is missing?

• (PR Added device binding template readme #136) Update overall binding markdown explaining the template and how to get started.

• (PR Added device binding template readme #136) Deprecate the main binding README markdown.

  This is now included within the template structure and is no longer needed. It is a better approach as it will be automatically provided instead of forcing the user to make a copy of the markdown into their project.

• Review and finalize the main binding README markdown.

  The binding markdown should be brief and specific about the binding's device(s). This markdown should only include a description, related datasheets, compatible components, notes on the API basics & gotchas, and references. See Mcp23xxx README as a good starting example. NOTE: This markdown should not include anything related to respective sample work as there is another README below that should house that information.

  This markdown is located as shown below:

  iot/
  src/
    devices/
      IotDeviceBinding/
        IotDeviceBinding.csproj
        IotDeviceBinding.cs
        [README.md]  // This represents the main Binding Markdown file.

• Review, determine and finalize the structure for binding samples markdown.

  There should be a description to help users decide if the sample provides what they are looking for.

  While it is not prohibited, this markdown should not include the basics like creating interface connections (e.g. new I2cConnectionSettings(), etc. ). This will minimize redundant steps throughout the binding samples. There will eventually be a System.Device.* API Overview doc provided that explains all the introductory stuff.

  Fritzing diagrams should be added here and show connections as clearly as possible. This helps limit the content on pin-to-pin writing. Users will most likely be referencing datasheets/pinouts, so they can find info there (usually on page 1 in PDFs).

  This markdown is located as shown below:

iot/
  src/
    devices/
      IotDeviceBinding/
        samples/
          IotDeviceBinding.Sample.csproj
          IotDeviceBinding.Sample.cs
          [README.md]   // This represents the Binding Samples Markdown file

• Review, determine and finalize content that should be in code files ([IotDeviceBinding].cs, [IotDevinceBinding].Sample.cs, [IotDeviceBinding]Tests.cs, etc.).

  This should include common code a user would need to start adding code to interact with device. Below are a few examples:

  • using statements
  • Helper methods to get device binding objects and interfaces. For example,

  Mcp23xxx mcp23xxx = GetMcp23xxxWithSpi();

  • If guidance is recommended, we could add plumbing code for adding CLI.

• Investigate if possible to use the template within Visual Studio.

  • Would be nice to right-click a folder in Solution Explorer > Add New IoT Device Binding 😄
  • This item could be removed and added to new issue as it is not required to complete this initial proposal.
  • A separate VSIX might be needed.
  • Looks like MS is working on a solution here: Announcement: adding Template Engine templates to VS2017 templating#1209 (comment)

[joperezr]

Do we really need to ship this binding as a NuGet Package? Is there a NuGet convention for project templates? IMHO I would consider this issue done, given that the main consumers of the template will be people contributing to our repo, so installing it from the local path seems like a good enough solution to me. What do you think @shaggygi ?

[shaggygi]

No, a package isn't really needed and users can install as is. Markdown should explain enough to get them going. I'll go ahead and close.

[joperezr]

BTW, this was used a lot during the hackathon and everyone that did pointed out how useful it was to get started with it, so just extending the kudos to you who actually did all the work.

[shaggygi]

Thx. You pointed out a few goodies to make it better, as well 👍