﻿This is a Microsoft .NET Gadgeteer mainboard project created using the Mainboard template in .NET Gadgeteer Builder Templates.
This template was most recently changed on 2012-04-18.

This template provides a simple way to build software for a custom Microsoft .NET Gadgeteer mainboard
that is compliant with the Microsoft .NET Gadgeteer Mainboard Builder's Guide specifications found at http://gadgeteer.codeplex.com/ 
Using this template auto-generates an installer (MSI) that can easily be distributed to end users, and an 
installation merge module (MSM) that can be used to make kit installers including many modules/mainboards/templates/etc.

We recommend that you read the Mainboard Builder's Guide at http://gadgeteer.codeplex.com/ for full details.

==============================================

SYSTEM REQUIREMENT

To build the installer MSI automatically, this template requires WiX 3.5 to be installed:
http://wix.codeplex.com/releases/view/60102 (Wix35.msi)

==============================================

BUILD NOTES

Building with the Release configuration generates an MSI installer, which includes your code, in the output directory 
of the project (bin/Release/Installer).  This takes a little time, and Visual Studio/C# Express may be unresponsive during the build.  
To avoid this delay, build with the Debug configuration. 

Visual C# Express always builds in Release configuration. In order to turn off the installer build to speed up the build process,
you can go to Menu->Project->[MainboardName] Properties->Build tab and tick the "Define DEBUG constant" box.

If you see the error "The system cannot find the file..." try "Rebuild" rather than "Build"

==============================================

MAINBOARD TEMPLATE DETAILS

This template supports both NETMF 4.1 and NETMF 4.2 - so mainboards can provide a driver for both versions of NETMF.

The template is split into three projects each starting with the name of the mainboard:
 [MainboardName]_41 : the NETMF 4.1 driver for the mainboard
 [MainboardName]_42 : the NETMF 4.2 driver for the mainboard
 [MainboardName] : the installer for the mainboard

For the NETMF projects, the files are similar:
1) [MainboardName]_4x.cs - software implementation of the mainboard's "device driver".
2) Setup\wixparameters4x.wxi - a WiX include file including GUIDs used to install this driver.  You do not need to edit this file.
3) Properties\AssemblyInfo.cs - a cs file including the version number of the mainboard driver, see MAKING CHANGES for when to change this.

In the installer project (with no suffix), the files are:
1) GadgeteerHardware.xml - defines some parameters about your mainboard.
2) ReadMe.txt - this file
3) Image.jpg - placeholder for an image representing the mainboard.
4) common.wxi - WiX (installer) configuration file that specifies parameters for the installer, including the version number. 
5) en-us.wxl - WiX (installer) localization file that specifies text strings that are displayed during installation.
6) msm.wxs - WiX (installer) script that generates an installation "merge module".
7) msi.wxs - WiX (installer) script that generates an installer (msi file) using the merge module.
8) G.ico - G graphic used by the installer.

==============================================

MAINBOARD TEMPLATE USE INSTRUCTIONS

1)  For each of the two NETMF projects (with the suffixes _41 and _42), in the Solution Explorer, right click and choose Properties, then change 
    "ManufacturerShortName" to the short name of your institution with no spaces or punctuation, under Assembly Name and Default Namespace. 
    Also change "GTMainboardName" to a name for your mainboard with no spaces or punctuation, in AssemblyName.
    These names should match what you print on the mainboard PCB.

2)  Do THREE Quick Replaces (Ctrl-H) on the entire solution to customise the template to your mainboard name and manufacturer name.
    You may want to skip the matches in this Readme file. 
    Replace "ManufacturerShortName" with the short name of your institution without any spaces or punctuation.
    Replace "GTMainboardName" with the name of your mainboard without any spaces or punctuation.
    Replace "ManufacturerFullName" with the name of your institution, which may include spaces or punctuation.

3)  Edit the [MainboardName].cs files to implement software for your mainboard.
    If you only want to support one version of NETMF then you only need to edit the relevant CS file, nonetheless, it is recommended
    not to delete the other project in case you wish to add support for the other version of NETMF in future. 
    See steps 5 and 6 for other actions necessary to support only one NETMF version.
    There are comments and examples in the cs files to assist you with this process.

4)  Test your mainboard. Mainboards cannot be run directly, since they are class libraries (dll) not executables (exe).   
    Testing is most easily accomplished by adding a new Gadgeteer project to the same Visual Studio/Visual C# Express solution. 
    You will need to create two test projects if you want to test both NETMF41 and NETMF42 versions.
    With the new Program.cs file open, use the menu item Project->Add Reference, and, in the Projects tab, choose your mainboard.
    Since the designer generates code instantiating the mainboard, we have to disable it for testing.
    Copy the content from Program.Generated.cs to the Program.cs file, and delete the Program.Generated.cs file and the .Gadgeteer file
    of the designer.  Then make the Program.cs file use your new mainboard type [Manufacturer Name].Gadgeteer.[Mainboard Name].
    You will have to manually add modules (add reference and instantiate) to test with modules.  

5)  Edit the GadgeteerHardware.xml file to specify information about your mainboard, as described in that file.
    If you are only supporting one NETMF version, MAKE SURE to delete the <Assembly> element for the other version.

6)  Optionally, change Image.jpg to a good quality top-down image of the mainboard with the socket side facing up,
    cropped tight (no margin), in the same orientation as the width and height specified in GadgeteerHardware.xml (not rotated).   

7)  Edit common.wxi to specify parameters for the installer, as described in that file.  
    If you are only supporting one NETMF version, MAKE SURE to comment out the other NETMFXXSupported tag as described in that file.

8)  Build in Release configuration to build the mainboard installer in the installer project's bin\Release\Installer directory!
    Install this and check that it appears correctly in the Control Panel's Add/Remove Programs window.

9)  Now open a new Gadgeteer App (for the right version(s) of NETMF) and your mainboard should appear in the designer.
    It is recommended to re-run tests using the designer, as well as checking the appearance of the mainboard in the designer.

==============================================

RELEASING THE MAINBOARD SOFTWARE, INDIVIDUALLY OR IN A KIT

The MSI installer generated in the installer project's bin\Release\Installer directory can be distributed to end users.
The MSM merge module in the installer project's bin\Release\Installer directory can be used to build other installers such as "kit" installers 
that incorporate multiple module(s)/mainboard(s).  This will install/remove correctly - e.g. if two kits including a Foo Mainboard 
are both installed, there will be one copy of the Foo mainboard (the most up-to-date version) and if either kit is removed, 
the Foo mainboard will remain installed, because the other kit requires it.

==============================================

MAKING CHANGES

If you make want to release a new version of your mainboard, make sure to change the version number in common.wxi. 
Otherwise, the auto-generated installer will not be able to upgrade the older version correctly (an error message will result).
It is also necessary to change the versions in BOTH Properties\AssemblyInfo.cs files and often a good idea to 
keep these synchronized with your common.wxi version.  

If you have are using the kit template to make an installer, then we you may wish to synchronize the version numbers with the kit.
This process is documented in the Kit readme.txt file; it requires one-off changes to the AssemblyInfo.cs and common.wxi files.

If you want to change the name of your mainboard, be sure to search all the files for instances of the name.

==============================================

UPGRADING FROM AN OLDER TEMPLATE

The only (2.41.500 and before) template was a single project targeting only NETMF 4.1. 
To upgrade an old mainboard to this template (supporting NETMF4.2 as well):

1) Create a new mainboard template with the same name as the old one.  
2) Follow this ReadMe steps above based on your old code, GadgeteerHardware.xml file, and Properties\AssemblyInfo.cs files
   - fix any bugs in the [MainboardName]_42.cs file that might occur due to SDK changes
   - copy over GadgeteerHardware.xml but read "NEW DESIGNER BEHAVIOR" below to see how to augment it to support NETMF 4.2
   - remember to copy over the image
   - copy over the details above the line in the common.wxi file in the WiX directory 
3) Before building the installer, you need to copy over TWO GUIDs in order to make the upgrade work.  
   In common.wxi, just copy over the GUIDs for guid_msi_upgrade_code and guid_msi_package_id from the old version.
4) Make sure to use a higher version than the old one in THREE places - two Properties\AssemblyInfo.cs files and common.wxi 

If you follow these steps, the new installer should upgrade correctly over the old installer.

==============================================

NEW DESIGNER BEHAVIOR

As of 2.42.XXX, the designer supports a number of constraints/user messages based on GadgeteerHardware.xml.
(NB this support is present for both NETMF 4.1 and NETMF 4.2)
With point (2) particularly, this will cause some modules ported over from NETMF 4.1 to NOT WORK with NETMF 4.2 unless changes are made.

1) Only hardware supporting the current project's framework version (i.e. having least one Assembly for that version) will be shown.
   When porting from 4.1, you must add <Assembly MFVersion="4.2" Name="drivername"/> in the <Assemblies> element.

2) A few components of Gadgeteer have been split into separate assemblies to make it possible to exclude them when not required.
   This saves RAM and flash space when deployed. The designer can automatically include such core "fragments" when including a module
   that relies on them or is commonly used with them.  The fragment libraries should be listed in the Assemblies section of the module
   alongside that module's driver, so that the designer automatically includes a reference to them when that module is included.
   The fragments are: Gadgeteer.SPI, Gadgeteer.Serial, Gadgeteer.DaisyLink (inc. SoftwareI2C), Gadgeteer.WebClient and Gadgeteer.WebServer
   If you use any of these in your module, then it will NOT work in 4.2 unless you add an Assemblies entry in GadgeteerHardware.xml

3) A mainboard with built-in modules should nonetheless provide separate module classes for each type of functionality.  
   These modules should be named in a way that makes it clear that they only apply to one mainboard, e.g. ModulenameForMainboardname.
   The mainboard should list its driver under LibrariesProvided; the module should list the mainboard driver in ExtraLibrariesRequired.
   The ErrorMessage attribute of the module will be shown if the module is used with any other mainboard, and should make it 
   clear why that does not work, e.g.: "This module is built-in to MainboardName and cannot be used with any other mainboard."

4) A mainboard with custom firmware support libraries that modules might rely directly (so that the modules do not work with all mainboards)
   should list the assembly names in LibrariesProvided.  A module requiring a custom mainboard firmware library should list that under 

5) The MinimumGadgeteerCoreVersion attribute is supported, and the designer will present the user with an error message if the installed
   version of GadgeteerCore is not high enough, pointing them at http://gadgeteer.codeplex.com/ to get a newer version.

Examples are provided in comments in GadgeteerHardware.xml. 



