Getting Started

Getting Started

Setting up your local repository

1. Fork the repository from GitHub
   This will create public copy of the repository in your GitHub account on the GitHub servers. All pull requests must come from a public GitHub repository. Forking the repository is a simple click on the "Fork" button on the repositories page in GitHub.
2. Clone your forked repository to your local system
   When deciding on the location on your local system it is recommended to use a path that will leave at least one level of directory hierarchy from the root to accommodate the additional binaries from step #4 (See the example following these steps for more details, the cloned folder is named netmf-interpreter in the example. ) The git command for cloning is:
   git clone https://github.com/<your GitHub ID>/netmf-interpreter.git
3. In your local repository, configure a remote to "upstream" NETMF repository
   Establishing the official repository as the "Upstream" repository for your local clone enables you to pull changes from the latest official commits into your repository and resolve merge issues locally before submitting a pull request. The command for establishing the Upstream remote is:
   git remote add upstream https://github.com/NETMF/netmf-interpreter.git
4. Install the binary tools.
   The easiest way to install the required binary tools is to run the Install-BinTools.ps1 PowerShell Script from the root of your repository. The binary tools contains binaries necessary to build the SDK along with support files needed to build custom device images. Our longer term goal is to remove the need for these binaries - so they are a separate download at present. The PowerShell script will download and unpack the files into the parent folder of the repository The tools and bin folders in the zip should become siblings of the folder containing the repository. This is why the repository must not be at the root of a drive/volume.
5. Download and install the CMSIS library source from ARM.
   The specifics for the currently supported version are documented in the readme.md in the CMSIS folder of the source tree. The easiest way to do this is to run the Install-CMSIS.ps1 PowerShell script from the root of the repository.
6. Download and install the .NET Micro Framework Cryptographic Libraries

• The cryptographic libraries are provided in binary form only. They provide support for cryptographic signature creation and validation. The cryptographic libraries work with TinyBooter and MFDeploy as part of the process of building a secure firmware update solution.
• When prompted for an install location you should select the root of your local repository.
• If you need or want to maintain multiple NETMF based repositories you can simply copy the contents of the crypto folder between repositories since the MSI will only allow installing to one place.

Building the Code

NOTE: There are a number of online tutorials for how to build the NETMF code that list additional steps that are not applicable to the v4.4 and later GitHub repositories. You should treat these articles as highly advanced optimization hints and reviewed with a skeptical eye as the issues the original authors faced and wrote the article to deal with, may not exist anymore. Some contained steps that were simply unnecessary. However, in some cases the instructions are just wrong or potentially problematic due to a confusion on the differences between the Porting Kit and raw source tree builds that previously existed. Hopefully with the move to GitHub, a regularly updated WIKI and the simpler build support in V4.4 we can eliminate the confusion.

Building the SDK

Pre-Requisites for Building the SDK

• Visual Studio 2015 (Community, Pro or Ultimate editions)
• Visual Studio Extensibility tools To build the VSIX packages for integration with Visual Studio, you must have the Visual Studio SDK matching the version of VS you intend to target (e.g. VS2013 or VS2015). At a minimum you must have the VS 2015 SDK installed as generation of the project templates requires that version. The build system will automatically skip generation of additional VSIX packages for a given version of VS if the corresponding VSSDK is not found.
  The Visual Studio SDK was renamed to Visual Studio Extensibility Tools in VS 2015. Furthermore, the SDK is no longer a separate download, it's part of the main installer. (See the MSDN documentation on the extensibility tools installation for more information)
• Supported CMSIS package from ARM. The specifics for the currently supported version are documented in the readme.md file in the CMSIS folder of the source tree.

Running build_sdk.cmd

NOTE: Building the SDK is only needed for pre-release versions of the NETMF. A fully signed binary for the current version is available from the Visual Studio Gallery (on the web or directly from within Visual Studio Tools | Extensions and Updates) and from the Releases section of the NETMF GitHub site.

1. Open a command prompt and navigate to the root of the repository
2. Run the build_sdk.cmd command script to generate a new SDK MSI and VSIX packages.
   This will generate the SDK installer MSI and the VSIX packages in the BuildOutput folder:
   ...\netmf-interpreter\BuildOutput\public\Release\Server\msm\MicroFrameworkSDK.MSI
...\netmf-interpreter\BuildOutput\public\Release\Server\dll\netmfvs2012.vsix
...\netmf-interpreter\BuildOutput\public\Release\Server\dll\netmfvs2013.vsix
...\netmf-interpreter\BuildOutput\public\Release\Server\dll\netmfvs2015.vsix

Building a firmware solution

1. Open a command prompt and navigate to the root of the repository
2. Run setenv_<toolset> <args> to set up the build environment for the tool-set you have.
   Example: C:\GitHub\Netmf\netmf-interpreter>setenv_mdk 5.05
   NOTE: For the ARMCC tool chain the version number provided to setenv_mdk.cmd is the compiler version number and NOT the KEIL MDK/uVision version number. (e.g. for KEIL MDK v5.14 the ARMCC version is 5.05) This is to keep the settings consistent between the KEIL and ARM DS-x tool suites, which share the same compiler.
3. Navigate to the Solutions\<platformname> folder for the platform you wish to build
4. Run msbuild to build the firmware
   While a simple msbuild with no arguments is enough it tends to make for a noisy display. An easier to follow and faster build is achieved by providing the options for generating a detailed log file but use only minimal logging to the console window as follows:
   msbuild /flp:verbosity=detailed /clp:verbosity=minimal
   This will build the Release version of the firmware for FLASH. If you want to build the debug version simply add /p:FLAVOR=Debug to the command line to set the FLAVOR property to Debug.

Command Alias Support

To make common shortcuts for command line builds easier the setenv_xxx scripts now include support to configure an optional alias.txt file via DOSKEY. If the %SPOCLIENT%\alias.txt file is present the setenv_xxx.cmd scripts will load the macros in the file via DOSKEY /macrofile=alias.txt.
A commonly used shortcut for the previously mentioned build command in alias.txt would be:
mfbld=cls$Tmsbuild /flp:verbosity=detailed /clp:verbosity=minimal $*
This sets up an alias command mfbld that clears the screen and runs msbuild with the previously mentioned logging settings. Furthermore, any additional arguments specified on the command line when using the mfbld alias are passed directly on to msbuild.

Flashing the firmware

The steps required to flash the firmware vary based on the interfaces available on a particular SoC or board.

• Flashing STM32Fx firmware

Diagnostics and Troubleshooting

Diagnostics and Troubleshooting wiki page provides information about configuring NETMF solutions to enable diagnostics and tracing messages, viewing output etc.