ARMmbed · AnotherButler · Feb 6, 2018 · Dec 11, 2017 · Dec 11, 2017 · Dec 12, 2017
diff --git a/docs/images/add_to_compiler.png b/docs/images/add_to_compiler.png
diff --git a/docs/images/export_online_compiler.png b/docs/images/export_online_compiler.png
diff --git a/docs/images/import_into_compiler.png b/docs/images/import_into_compiler.png
diff --git a/docs/images/online_compile_button.png b/docs/images/online_compile_button.png
diff --git a/docs/tutorials/first_app/blinky_cli.md b/docs/tutorials/first_app/blinky_cli.md
@@ -1,128 +1,168 @@
-## Blinky on Arm Mbed CLI
+## Offline - Arm Mbed CLI
 
-This tutorial builds Blinky using the Arm Mbed CLI, which allows you to build Mbed OS applications on your own machine. You will need to install Mbed CLI and a toolchain before you can work with Blinky.
+### Setup
 
-<span class="tips">Please create a [developer account](https://os.mbed.com/account/signup/). It's free, and we don't spam.</span>
+The setup process for Arm Mbed CLI depends on your operating system. Please choose your host operating system. The setup instructions for each operating system walk you through how to install Mbed CLI locally. 
 
-### Blinky's code
+[**Windows**](#windows) | [**OSX**](#mac-osx) | [**Linux**](#linux)
 
-Blinky's code is a simple `while` loop inside the `main()` function:
+#### Windows
 
-```
-#include "mbed.h"
-#include "rtos.h"
-
-DigitalOut led1(LED1);
-
-// main() runs in its own thread in the OS
-// (note the calls to wait below for delays)
-int main() {
- while (true) {
- led1 = !led1;
- wait(0.5);
- }
-}
-```
+##### 1. Install Mbed CLI
 
-### Quick start video
+Download and run the [Mbed CLI Windows .exe installer](https://github.com/ARMmbed/mbed-cli-windows-installer/releases).
 
-This video shows how to use Mbed CLI to import and build Blinky. Note that it assumes you have already installed Mbed CLI (see next section):
+You can ensure Mbed CLI installed correctly by running `mbed help` from your command-line.
 
-<span class="images">[![Video tutorial](http://img.youtube.com/vi/PI1Kq9RSN_Y/0.jpg)](https://www.youtube.com/watch?v=PI1Kq9RSN_Y)<span>Watch how to create your first application on Arm Mbed CLI</span></span>
+<span class="notes">**Note:** The Windows installer only installs the GNU Arm embedded toolchain. If you want to compile using Arm Compiler 5 or IAR, visit the [supported compilers page](/docs/latest/tools/index.html#compiler-versions).</span>
 
-### Installing Mbed CLI and a toolchain
+##### 2. Setup environment
 
-Mbed CLI is an offline tool, meaning you'll have to install it before you can work. You will also need to install a toolchain. Please follow the installation instructions on the [Mbed CLI setup page](/docs/v5.6/tools/setup.html), and come back here when you're done.
+For any installed toolchain, be sure to add the Mbed CLI global configuration:
 
-### Setting context
+```
+> mbed config -G ARM_PATH <path to ARM bin\>"
+[mbed] <path to ARM bin\> now set as global ARM_PATH
 
-Whenever you work with Mbed CLI, you need to navigate your command-line terminal to the directory in which you want to work. For example, if your program is in a folder called `my_program`:
+> mbed config --list
+[mbed] Global config:
+ARM_PATH=<path to ARM bin\>
 
-```
-cd my_program
 ```
 
-You can then start running Mbed CLI commands, and they will run in the correct context.
+<span class="notes">**Note:** You can also apply the same configuration to the IAR and GNU toolchains using `IAR_PATH` or `GCC_ARM_PATH`.</span>
 
-### Getting Blinky
+#### Mac OSX
 
-Mbed CLI can import Blinky, along with the Arm Mbed OS codebase. The import process creates a new directory as a subdirectory of your current context (as explained above).
+##### 1. Install Python and Pip
 
-To import Blinky, from the command-line:
+Mac OS X 10.8+ comes with Python 2.7 preinstalled by Apple. If you are running an earlier version of Mac OS X, download and install [Python 2.7.12+](https://www.python.org/downloads/mac-osx/).
 
-1. Navigate to a directory of your choice. We're navigating to our development directory:
+To install Pip, run `sudo easy_install pip` from your command-line.
 
- ```
- cd dev_directory
- ```
+##### 2. Install a compiler
 
-2. Import the example:
+Download and install a compiler.
 
- ```
- mbed import mbed-os-example-blinky
- cd mbed-os-example-blinky
- ```
+<span class="notes">**Note:** To download the latest toolchains, visit the [supported compilers page](/docs/latest/tools/index.html#compiler-versions).</span>
 
-<span class="tips">**Tip:** `import` requires a full URL to Mercurial or GitHub. If you don't enter a full URL, Mbed CLI prefixes your snippet with `https://github.com/ARMmbed/`. We took advantage of this feature in our example; `import mbed-os-example-blinky` is interpreted as `https://github.com/ARMmbed/mbed-os-example-blinky`.</span>
+##### 3. Install Mbed CLI
 
-Blinky is now under `dev_directory` > `mbed-os-example-blinky`. You can look at `main.cpp` to familiarize yourself with the code.
+To install Mbed CLI, run `pip install mbed-cli` from your command-line.
 
-### Compiling
+You can ensure Mbed CLI installed correctly by running `mbed help`.
 
-Invoke `mbed compile`, specifying:
+##### 4. Setup environment
 
-* Your board: `-m <board_name>`.
-* Your toolchain: `-t <GCC_ARM, ARM, ARMC6 or IAR>`.
+For any installed toolchain, be sure to add the Mbed CLI global configuration:
 
-For example, for the board K64F and the Arm Compiler 5:
+```
+$ mbed config -G ARM_PATH <path to ARM bin\>"
+[mbed] <path to ARM bin\> now set as global ARM_PATH
+
+$ mbed config --list
+[mbed] Global config:
+ARM_PATH=<path to ARM bin\>
 
 ```
-mbed compile -m K64F -t ARM
+
+<span class="notes">**Note:** You can also apply the same configuration to the IAR and GNU toolchains using `IAR_PATH` or `GCC_ARM_PATH`.</span>
+
+#### Linux 
+
+##### 1. Install Python and Pip
+
+Download and install [Python 2.7.12+](https://www.python.org/downloads/source/) or run the following from your command-line:
+
+```console
+$ sudo apt-get install python2.7
+$ sudo apt-get install python-pip
+$ sudo apt-get update
 ```
 
-If you don't know the name of your target board, there are several ways to tell.
+##### 2. Install a compiler
+
+Download and install a compiler:
+
+<span class="notes">**Note:** To download the latest toolchains, visit the [supported compilers page](/docs/latest/tools/index.html#compiler-versions).</span>
+
+##### 3. Install Mbed CLI
+
+To install Mbed CLI, run `pip install mbed-cli` from your command-line.
+
+You can ensure Mbed CLI installed correctly by running `mbed help`.
+
+##### 4. Setup environment
 
-- Invoke `mbed detect`, and the Mbed CLI tool displays an output similar to below, where 'K64F' is the name of your target platform and COM3 is the name of the serial port that the platform connects to:
+For any installed toolchain, be sure to add the Mbed CLI global configuration:
 
 ```
-[mbed] Detected "K64F" connected to "D:" and using com port "COM3"
+$ mbed config -G ARM_PATH <path to ARM bin\>"
+[mbed] <path to ARM bin\> now set as global ARM_PATH
+
+$ mbed config --list
+[mbed] Global config:
+ARM_PATH=<path to ARM bin\>
+
 ```
 
-- Check the board information page on the list of [Mbed Enabled boards](https://developer.mbed.org/platforms/). The right side of each information page lists the name of the target.
+<span class="notes">**Note:** You can also apply the same configuration to the IAR and GNU toolchains using `IAR_PATH` or `GCC_ARM_PATH`.</span>
 
-- If you only have one Mbed Enabled board connected, Mbed CLI can automatically detect the target by specifing `-m detect`.
+### Code
 
-Your PC may take a few minutes to compile your code. At the end you should get the following result:
+#### 1. Get the code
 
+From your command-line, import the example:
+
+```console
+$ mbed import https://github.com/ARMmbed/mbed-os-example-blinky
+$ cd mbed-os-example-blinky
 ```
-[snip]
-+----------------------------+-------+-------+------+
-| Module | .text | .data | .bss |
-+----------------------------+-------+-------+------+
-| Misc | 13939 | 24 | 1372 |
-| core/hal | 16993 | 96 | 296 |
-| core/rtos | 7384 | 92 | 4204 |
-| features/FEATURE_IPV4 | 80 | 0 | 176 |
-| frameworks/greentea-client | 1830 | 60 | 44 |
-| frameworks/utest | 2392 | 512 | 292 |
-| Subtotals | 42618 | 784 | 6384 |
-+----------------------------+-------+-------+------+
-Allocated Heap: unknown
-Allocated Stack: unknown
-Total Static RAM memory (data + bss): 7168 bytes
-Total RAM memory (data + bss + heap + stack): 7168 bytes
-Total Flash memory (text + data + misc): 43402 bytes
-Image: .\.build\K64F\ARM\mbed-os-example-blinky.bin 
-```
 
-The program file, `mbed-os-example-blinky.bin`, is under your `mbed-os-example-blinky\build\K64F\ARM\` folder.
+#### 2. Compile and program board
+
+Invoke `mbed compile`, and specify the name of your platform and your installed toolchain (`GCC_ARM`, `ARM`, `IAR`). For example, for the K64F platform and Arm Compiler 5 toolchain:
+
+```console
+$ mbed compile --target K64F --toolchain ARM --flash
+``` 
+
+The `--flash` argument automatically flashes the compiled program onto your board if it is connected to your computer. You can see which boards are connected with `mbed detect`.
+
+After you have flashed the program to the board, press the board's reset button. The LED blinks.
+
+<span class="notes">**Note:** You can get the name of the board plugged into your computer by running `mbed detect`, and you can get a full list of supported toolchains and targets by running the `mbed compile --supported` command.</span>
+
+### Debug
+
+#### Desktop IDE
+
+To debug using a desktop IDE such as Keil uVision, IAR or Eclipse, use the `mbed export` command to generate project files. For example, for a K64F and Keil uVision:
+
+```console
+$ mbed export --ide uvision --target K64F
+``` 
+
+<span class="notes">**Note:** For a full list of supported exporters, run the `mbed export --supported` command.</span>
+
+#### Printf
+
+Another way to do basic debugging is to use the `printf` command in your code and read the output using a serial terminal, such as [PuTTY](http://www.putty.org/) or [CoolTerm](http://freeware.the-meiers.org/). For example, add `printf("Hello World!\n\r");` to the top of your main function, and then recompile the program and flash it to your device.
+
+Invoke `mbed detect` from your command-line to determine which communication port your board connects to (in other words, `COM18`, `/dev/ttyACM0` and so on). Unless otherwise specified, `printf` defaults to a baud rate of `9600` on Mbed OS.
 
-### Programming your board
+### Further reading
 
-Arm Mbed Enabled boards are programmable by drag and drop over a USB connection:
+- Documentation
+ - [Mbed OS APIs](https://os.mbed.com/docs/latest/reference/apis.html) - list of all APIs available in Mbed OS.
+ - [Peripheral drivers](https://os.mbed.com/docs/latest/reference/drivers.html) - IO driver APIs (I2C, SPI, UART and so on).
 
-1. Connect your mbed board to the computer over USB.
-1. Copy the binary file to the board. In the example above, the file is `mbed-os-example-blinky.bin`, and it's under the `mbed-os-example-blinky\build\K64F\ARM\` folder.
-1. Press the reset button to start the program.
+- Tutorials
+ - [Advanced debugging](https://os.mbed.com/docs/latest/tutorials/debugging.html).
+ - [Serial communications](https://os.mbed.com/docs/latest/tutorials/serial-communication.html).
+ - [Optimizing binary size](https://os.mbed.com/docs/latest/tutorials/optimizing.html).
 
-You should see the LED of your board turning on and off.
+- Other resources 
+ - [Components database](https://os.mbed.com/components/) - libraries and example code for various hardware and software components.
+ - [Mbed OS forum](https://os.mbed.com/forum/) - a resource of questions and answers and an active user community. Ask your questions here first.
+ - [Youtube channel](http://youtube.com/armmbed) - videos and workshop content.
diff --git a/docs/tutorials/first_app/blinky_compiler.md b/docs/tutorials/first_app/blinky_compiler.md
@@ -1,70 +1,81 @@
-## Blinky on the Arm Mbed Online Compiler
+## Arm Mbed Online Compiler
 
-This tutorial builds Blinky using the Arm Mbed Online Compiler, which allows you to build Mbed OS applications without installing a toolchain on your own machine.
+### Setup
 
-<span class="tips">Please create a [developer account](https://os.mbed.com/account/signup/). It's free, and we don't spam.</span>
+#### Create an Arm Mbed developer account
 
-### Importing Blinky
+Go to [os.mbed.com](os.mbed.com), and [create an account](https://os.mbed.com/account/signup/F).
 
-To get Blinky into the Mbed Online Compiler, click the **`Import into Mbed IDE`** button below:
+#### Setup environment
 
-[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-blinky/)](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-blinky/file/tip/main.cpp)
+- Plug your Mbed board into your computer, and open its USB device folder.
+- Double click on the `MBED.HTM` file. (This adds your Mbed platform to the Online Compiler.)
 
-You're taken to the online IDE, and the **Import Program** dialog box opens:
+If you do not have an Mbed board, go to [os.mbed.com/platforms](http://os.mbed.com/platforms), select a board and click the “Add to your Mbed Compiler” button.
+<span class="images">![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/add_to_compiler.png)
+</span>
 
-<span class="images">![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/import_dialog.png)<span>Importing Blinky</span></span>
+### Code
 
-The import mechanism offers a default name, but you're free to change it. When you're done, click **Import**.
+#### Import
 
-### Viewing Blinky
+Visit the Mbed OS [blinky example repository](https://developer.mbed.org/teams/mbed-os-examples/code/mbed-os-example-blinky/), and click the "Import into Compiler" button.
 
-The imported Blinky has two interesting parts:
+<span class="images">![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/import_into_compiler.png)
+</span>
 
-- `main.cpp`, where the Blinky-specific code is. You can double-click the file in the navigation pane on the left to view the code.
-- `mbed-os`, where the Arm Mbed OS codebase is.
+#### Compile
 
-Later we'll compile the code; this will take both of these parts and create a single application file from them.
+Click on the "Compile" button. Your browser downloads the program as an executable file.
 
-<span class="images">![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/maincpp.png)<span>Viewing the code in main.cpp</span></span>
+<span class="images">![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/online_compile_button.png)
+</span>
 
-### Selecting a target board
+#### Program
 
-The Mbed Online Compiler can build your application to match any Arm Mbed Enabled board. However, you have to select the target board before compiling.
+Open the folder where the executable file was downloaded, and then click and drag (or copy and paste) the file to your Mbed board's USB device folder.
 
-#### Adding a board to your list
+Once you have flashed the file to the board, press the board's reset button. The LED blinks.
 
-To add a board to your list, go to [the board's page on `os.mbed.com`](https://os.mbed.com/platforms/), and click the **`Add to your Mbed Compiler`** button:
+### Debug
 
-<span class="images">![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/add_board.png)<span>Adding a board to the Mbed Online Compiler's board list</span></span>
+#### Desktop IDE
 
-#### Selecting a board
+To debug using a desktop IDE such as Keil uVision, IAR or Eclipse, click the `Export` button under `Program Details`. Select your export platform and IDE, and click `Export`. Your browser downloads a `.zip` file with the project files.
 
-The compiler shows the current build board's name on the upper right corner:
+<span class="images">![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/export_online_compiler.png)
+</span>
 
-<span class="images">![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/show_board.png)<span>Opening the list of boards</span></span>
+#### Printf
 
-Click the name to change your board as needed:
+Another way to do basic debugging is to use the `printf` command in your code and then read the output using a serial terminal, such as [PuTTY](http://www.putty.org/) or [CoolTerm](http://freeware.the-meiers.org/). For example, add `printf("Hello World!\n\r");` to the top of your main function, and then recompile the program and flash it to your device.
 
-<span class="images">![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/select_board.png)<span>Selecting a board</span></span>
+Unless otherwise specified, `printf` defaults to a baud rate of `9600` on Mbed OS. To determine which communication port your board connects to, follow the instructions for your operating system:
 
-### Compile and install
+##### Windows
 
-The Mbed Online Compiler builds your program as a `.bin` file that you can install on your board.
+Open the Device Manager by pressing `Windows key + R`. Type `devmgmt.msc`, and click `OK`. Under `Ports (COM & LPT)`, your Mbed board is listed as a `USB Serial Device` next to its COM port.
 
-1. Click **Compile**.
+##### Linux
 
-<span class="images">![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/compileandinstall.png)<span>The Compile menu; choose Compile to build and download your application</span></span>
+Run `dmesg | grep tty` from your command-line.
 
-1. The program compiles:
+##### Mac
 
-<span class="images">![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/compiling.png)<span>Compilation progress</span></span>
+Run `ls /dev/tty.*` from your command-line.
 
-1. When the compiled file is ready, it's downloaded to your default download location (or opens a Download dialog box). The file format is `.bin`, and the file name is the same as your program name.
+### Further reading
 
-1. Connect your board to your computer over USB. Mbed boards are shown as "removable storage".
+- Documentation
+- [Mbed OS APIs](https://os.mbed.com/docs/latest/reference/apis.html) - list of all APIs available in Mbed OS.
+- [Peripheral drivers](https://os.mbed.com/docs/latest/reference/drivers.html) - IO driver APIs (I2C, SPI, UART and so on).
 
-<span class="images">![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/DeviceOnWindows.png)<span>The device is listed as `MBED` or `DAPLINK`, and its type is removable storage</span></span>
+- Tutorials
+- [Advanced debugging](https://os.mbed.com/docs/latest/tutorials/debugging.html).
+- [Serial communications](https://os.mbed.com/docs/latest/tutorials/serial-communication.html).
+- [Optimizing binary size](https://os.mbed.com/docs/latest/tutorials/optimizing.html).
 
-1. Drag and drop your program to the board. The board installs the program.
-
-1. Reset the board, and see the LED blink.
+- Other resources
+- [Components database](https://os.mbed.com/components/) - libraries and example code for various hardware and software components.
+- [Mbed OS forum](https://os.mbed.com/forum/) - a resource of questions and answers and an active user community. Ask your questions here first.
+- [Youtube channel](http://youtube.com/armmbed) - videos and workshop content.