nanoframework · josesimoes · Jul 8, 2017 · Jul 7, 2017
diff --git a/docs/build-instructions.md b/docs/build-instructions.md
@@ -29,7 +29,7 @@ In case you specify an RTOS and you want its source to be downloaded from the of
 
 # Preparation
 
-It's ***highly*** recommended that run the build outside the source tree. This prevents you from cluttering the source tree with CMake artifacts, temporary files and like. 
+It's ***highly*** recommended that run the build outside the source tree. This prevents you from cluttering the source tree with CMake artifacts, temporary files etc. 
 In fact this is enforced and checked by the CMake script.
 
 In case you need to clean up or start a fresh build all you have to do is simply delete the contents of the build directory.
@@ -50,6 +50,8 @@ The build script accepts the following parameters (some of them are mandatory).
 - CHIBIOS_VERSION: specifies the ChibiOS version to grab the source files. It has to match one of the official versions from the ChibiOS repository. If none is specified it will download the 'trunk' version. This parameter is ignored if CHIBIOS_SOURCE is specified. 
 - CHIBIOS_BOARD: specifies the ChibiOS board. This parameter is mandatory when specifying CHIBIOS as the RTOS choice parameter above. It has to be a valid board listed in ChibiOS boards folder.
 - NF_FEATURE_DEBUGGER: specifies if the debugger feature is to be included. If not supplied the default value will be used. The default is true (debugger will be included).
+- NF_FEATURE_RTC: Allows you to specify whether the board contains a real time clock that can be used for date & time functions. The default is off.
+- API_Windows.Devices.Gpio: Allows you to specify whether GPIO functions are available to your application. The default is off.
 
 _Note 1: The RTOS currently supported is ChibiOS. If no source path is specified the source files will be downloaded from it's official GitHub mirror._
 _Note 2: the very first build will take more or less time depending on the download speed of the Internet connection of the machine were the build is running. This is because the source code of the RTOS of your choice will be downloaded from its repository. On the subsequent builds this won't happen._
@@ -66,15 +68,16 @@ The following is a working example:
 ```
 cmake \
 -DTOOLCHAIN_PREFIX="E:/GNU_Tools_ARM_Embedded/5_4_2016q3" \
--DCHIBIOS_VERSION=16.1.7 \
+-DCHIBIOS_VERSION=17.6.0 \
 -DCHIBIOS_BOARD=ST_NUCLEO_F091RC \
 -DTARGET_SERIES=STM32F0xx \
 -DNF_FEATURE_DEBUGGER=TRUE \
 -DAPI_Windows.Devices.Gpio=ON \
+-DNF_FEATURE_RTC=ON \
 -G "NMake Makefiles" ../ 
 ```
 
-This will call CMake (on your *build* directory that is assumed to be under the repository root) specifying the location of the toolchain install, specifying ChibiOS v16.1.7 as the RTOS version, that the target board is named ST_NUCLEO_F091RC, that STM32F0xx is the series name that it belongs to, debugger feature is to be included, Windows.Devices.Gpio API is to be included and that the build files suitable for NMake are to be generated.
+This will call CMake (on your *build* directory that is assumed to be under the repository root) specifying the location of the toolchain install, specifying ChibiOS v17.6.0 as the RTOS version, that the target board is named ST_NUCLEO_F091RC, that STM32F0xx is the series name that it belongs to, debugger feature is to be included, Windows.Devices.Gpio API is to be included and that the build files suitable for NMake are to be generated.
 
 Another example:
 
@@ -87,10 +90,11 @@ cmake \
 -DUSE_FPU=TRUE \
 -DNF_FEATURE_DEBUGGER=TRUE \
 -DAPI_Windows.Devices.Gpio=ON \
+-DNF_FEATURE_RTC=ON \
 -G "NMake Makefiles" ../ 
 ```
 
-This will call CMake (on your *build* directory that is assumed to be under the repository root) specifying the location of the toolchain install, specifying that ChibiOS sources to be used are located in the designated path (mind the forward slash and no ending slash),  that the target board is named ST_NUCLEO144_F746ZG, that STM32F7xx is the series name that it belongs to, hardware floating point unit is to be used, debugger feature is to be included, Windows.Devices.Gpio API is to be included and that the build files suitable for NMake are to be generated.
+This will call CMake (on your *build* directory that is assumed to be under the repository root) specifying the location of the toolchain install, specifying that ChibiOS sources to be used are located in the designated path (mind the forward slash and no ending slash),  that the target board is named ST_NUCLEO144_F746ZG, that STM32F7xx is the series name that it belongs to, hardware floating point unit is to be used, debugger feature is to be included, Windows.Devices.Gpio API is to be included, RTC is used and that the build files suitable for NMake are to be generated.
 
 After successful completion you'll have the build files ready to be used in the target build tool.
 
@@ -100,7 +104,7 @@ After successful completion you'll have the build files ready to be used in the
 We've added the required files and configurations to help you launch your build from VS Code.
 Follows a brief explanation on the files you might want to tweak.
 
-- settings.json (inside .vscode folder) here you can change the generator that CMage uses to generate the build. The default is ```"cmake.generator": "NMake Makefiles"```.
+- settings.json (inside .vscode folder) here you can change the generator that CMake uses to generate the build. The default is ```"cmake.generator": "NMake Makefiles"```.
 - launch.json (inside .vscode folder) here you can set up your launch configurations, such as gdb path or openocd configuration.
 - cmake-variants.json (at the repository root) here you can add several build flavors. You can even add variants to each one. Check the documentation extension [here](https://github.com/vector-of-bool/vscode-cmake-tools/blob/develop/docs/build_variants.md).
 

diff --git a/docs/cmake-tools-cmake-variants.md b/docs/cmake-tools-cmake-variants.md
@@ -12,31 +12,31 @@
 
 This document describes how to use and modify the **cmake-variants.TEMPLATE.json** file to suit your needs.
 
-_Note : this first revision of the document is focusing on using the ChibiOS RTOS. Other RTOSes will follow._
+_Note : the current revision of the document only focuses on using ChibiOS RTOS. Other RTOSes will follow in a future revision._
 
 ## What is it
 
-This file is a template containing a minimal set of configurations examples needed to build nanoFramework for you board.
+cmake-variants.TEMPLATE.json is a template containing a minimal set of configuration examples needed to build nanoFramework for you board.
 
-Its content describes what kind of build you will get, which toolchain(s) you will use, which MCU is on the board, and some other options that will be described later in this document.
+Its content describes what kind of build you will get, which toolchain(s) you will use, which type of MCU is on the board, and some other options that will be described later in this document.
 
 ## How to use it
 
-First, you have to either rename it or copy it to **cmake-variants.json**. Then, you will have to modify the different settings to match your environment.
+First, you have to either rename the file or copy the contents to **cmake-variants.json**. Then, you will have to modify the content to match your environment.
 
 
 ## Brief description
 
 There are two sets of parameters that need to be present in this file :
-- the build type : debug or release, for example
+- the build type : 'debug' or 'release', for example
 - the board's environment : MCU, toolchain, RTOS
 
 You should not have to modify the *BuildType* section unless you have good reasons to do so. However, the *Linkage* section is the one you will have to take care of.
 
-For each *board* you want a build, you will have to create a dedicated section in this *Linkage* area, describing precisely the MCU, the toolchain, the build type and the RTOS you will use.
+For each *board* you want to build, you will have to create a dedicated section in the *Linkage* area, precisely describing the MCU, the toolchain, the build type and the RTOS you will use.
 
 ## Content explained
-Now, we will explain each line of the *linkage* section. A text in **bold** is an information that you will have to provide.
+The following explains each line of the *linkage* section. Text highlighted in **bold** is an information that you will have to provide.
 
 **_Note : Mind the forward slash ('/') in paths strings !_**
 
@@ -57,22 +57,28 @@ Now, we will explain each line of the *linkage* section. A text in **bold** is a
 - "RTOS" : "**<one-of-valid-rtos-options>**"
 	- Defines the RTOS that will be used to build nanoFramework. It can be CHIBIOS, FREERTOS or MBEDOS. Currently, only CHIBIOS is supported.
 - "CHIBIOS_SOURCE" : "**<path-to-chibios-source-mind-the-forward-slash>**"
-	- Path to an optionnal local installation of ChibiOS source files. If no path is given, then CMake will download the sources from the official repository when needed
+	- Path to an optional local installation of ChibiOS source files. If no path is given, then CMake will download the sources from the projects ChibiOS repository when needed
 - "CHIBIOS_VERSION" : "**<N.N.N>**"
-	- Version of the local/distant distribution of ChibiOS that will be used
+	- Version of the local/distant distribution of ChibiOS that will be used. If no version is provided, CMake will use the master branch.
 - "CHIBIOS_BOARD" : "**<valid-chibios-board-name-from-boards-collection>**"
 	- Name of your board, chosen from the available boards collection that can be found in the \os\hal\boards folder of the ChibiOS installation (or distant repository)
+- "NF_FEATURE_DEBUGGER" : "**<TRUE-to-include-nF-debugger>**"
+	- A boolean switch to specify whether the debugger feature is to be included.
+- "NF_FEATURE_RTC" : "**<OFF-default-ON-to-enable-hardware-RTC>**"
+	- Allows you to specify whether the board contains a real time clock that can be used for date & time functions.
+- "API_Windows.Devices.Gpio" : "**<OFF-default-ON-to-add-this-API>**"
+	- Allows you to specify whether GPIO functions are available to your application.
 - "FREERTOS_VERSION" : "**<N.N.N>**"
 	- Version of the local/distant distribution of FREERTOS that will be used
 - "FREERTOS_SOURCE" : "**<path-to-freertos-source-mind-the-forward-slash>**"
-	- Path to an optionnal local installation of FREERTOS source files. If no path is given, then CMake will download the sources from the official repository when needed
+	- Path to an optional local installation of FREERTOS source files. If no path is given, then CMake will download the sources from the official repository when needed
 - "MBEDOS_SOURCE" : "**<path-to-mbedos-source-mind-the-forward-slash>**"
-	- Path to an optionnal local installation of MBEDOS source files. If no path is given, then CMake will download the sources from the official repository when needed
+	- Path to an optional local installation of MBEDOS source files. If no path is given, then CMake will download the sources from the official repository when needed
 - "MBED_TARGET" : "**<valid-target-name-from-targets-json-file>**"
 	- ????
 
 ## Working example
-The followinf linkage section is a real example used to build nanoFramework for the MBN Quail board. It is using the minimal mandatory informations :
+The following linkage section is a real example used to build nanoFramework for the MBN Quail board. It is using the minimal mandatory information :
 
 ```
 "MBNQUAIL":
@@ -89,6 +95,9 @@ The followinf linkage section is a real example used to build nanoFramework for
             "CHIBIOS_VERSION" : "16.1.7",
             "CHIBIOS_SOURCE" : "C:/dev/ChibiOS_16.1.7",
             "CHIBIOS_BOARD" : "MBN_QUAIL"
+			"NF_FEATURE_DEBUGGER" : "TRUE",
+            "NF_FEATURE_RTC" : "ON",
+            "API_Windows.Devices.Gpio" : "ON"
         },
         "buildType": "Debug"
       },

diff --git a/docs/rtos-source-for-build.md b/docs/rtos-source-for-build.md
@@ -10,11 +10,11 @@ This document aims to give you an brief overview of the differences between thes
 
 ### Source from official repository
 
-When running CMake if the parameter `-DCHIBIOS_SOURCE` is not not specified what happens is that Cake will connect to [ChibiOS repo](https://github.com/ChibiOS/ChibiOS) on GitHub and will download it from there. The time for this operation to complete will depend mostly on the speed of the Internet connection. Note that you need to specify `-CHIBIOS_VERSION` too otherwise the 'master' branch will be checked out instead of a stable branch.
+When running CMake if the parameter `-DCHIBIOS_SOURCE` is not not specified what happens is that Cake will connect to [ChibiOS repo](https://github.com/nanoframework/ChibiOS) on GitHub and will download it from there. The time for this operation to complete will depend mostly on the speed of the Internet connection. Note that you need to specify `-CHIBIOS_VERSION` too otherwise the 'master' branch will be checked out instead of a stable branch.
 
-On the next builds the download won't happen again, only a quick check for any changes in the repo. If there are any, those will be downloaded.
+ChibiOS will be cached in the build directory so the full download won't happen again unless the build directory is cleared. A check for any changes in the repo is made whenever a build is run. If there are any, the changes will be downloaded and merged.
 
-This option is good for automated builds or when you don't have (or don't want) the repo cloned into local disk.
+This option is good for automated builds or when you don't have (or don't want) the repo cloned to your local disk.
 
 Another advantage is that you don't have to manage the updates on the local clone.
 
@@ -25,14 +25,14 @@ An obvious disadvantage is that if the build folder is cleaned the 'cached' repo
 
 ### Source from local clone
 
-When running CMake if the parameter `-DCHIBIOS_SOURCE="....."` is specified a local clone located at the designated path will be used in the build. When using this option the `-CHIBIOS_VERSION` is not taken into account.
-The only time penalty is the one necessary for CMake to copy the contents of the repo to the build cache folder. This is a one time operation and it won't happen again unless the build folder is cleaned up, of course.
+When running CMake, if the parameter `-DCHIBIOS_SOURCE="....."` is specified a local clone located at the designated path will be used in the build. When using this option the `-CHIBIOS_VERSION` is not taken into account.
+The only time penalty is the one necessary for CMake to copy the contents of the repo to the build cache folder. This is a one time operation and it won't happen again unless the build folder is cleaned up.
 
 This option is good when you have a local clone of the repo and you don't want to increase the build time with checks on the repo and downloading it.
 
-The downside is that you have to manage the updates from the repo.
+The downside is that you have to manage the updates from the repo yourself.
 
 Another important aspect to consider is that you **have to _manually_ checkout** the branch that you want to use in the build. This is because CMake can't checkout branches for you.
-Not doing this is synonym of using the 'master' branch that contains the development files and not a stable version, which is probably what you want.
+Not doing this is synonym of using the 'master' branch that contains the development files and not a stable version, which is probably what you want to use.
 
 Also here, if the build folder is cleaned the 'cached' repo will be gone.
diff --git a/docs/wire-protocol.md b/docs/wire-protocol.md
@@ -15,7 +15,7 @@
 
 **About this document**
 
-This document describes the Wire Protocol used by **nanoFramework** for debug and booter stage.
+This document describes the Wire Protocol used by **nanoFramework** for debug and the booter stage.
 The protocol follows the implementation of the .NET Micro Framework Wire Protocol. The intention is to review it later in order to improve and simplify it.