mbed OS quickstart

docs/tutorials/first_app/blinky_cli.md

@@ -1,128 +1,165 @@
-## Blinky on Arm Mbed CLI
+## Offline - 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
+Please skip to the sub section for your host OS. The setup instructions will walk you through how to get mbed CLI installed locally on your system. 
 
-<span class="tips">Please create a <a href="https://os.mbed.com/account/signup/" target="_blank">developer account</a>. It's free, and we don't spam.</span>
+[**Windows**](#windows) | [**OSX**](#mac-osx) | [**Linux**](#linux)
 
-### Blinky's code
+#### Windows
 
-Blinky's code is a simple `while` loop inside the `main()` function:
+##### 1. Install mbed CLI
 
+Download and run the [mbed CLI Windows .exe installer](https://github.com/ARMmbed/mbed-cli-windows-installer/releases).
+
+You can check to make sure the mbed CLI installed correctly by running `mbed help`.
+
+**Note:** the Windows installer only installs the GNU Arm embedded toolchain, if you would like to compile using the ARM Compiler 5 or IAR visit the [supported compilers page](/docs/latest/tools/index.html#compiler-versions).
+
+##### 2. Setup Environment
+
+For any toolchain that is installed make sure to add the Mbed CLI global config:
 ```
-#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);
- }
-}
+> 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\>
+
 ```
 
-### Quick start video
+**Note:** The same config can also be applied to IAR and GNU toolchains using `IAR_PATH` or `GCC_ARM_PATH`
 
-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):
+#### Mac OSX
 
-<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>
+##### 1. Install Python & Pip
 
-### Installing Mbed CLI and a toolchain
+Mac OS X 10.8+ comes with Python 2.7 pre-installed 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/).
 
-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 <a href="/docs/v5.6/tools/setup.html" target="_blank">Mbed CLI setup page</a>, and come back here when you're done.
+To install Pip, run `sudo easy_install pip` from your command line.
 
-### Setting context
+##### 2. Install a Compiler
 
-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`:
+Download and install a compiler:
 
+**Note:** To download the latest toolchains visit the [supported compilers page](/docs/latest/tools/index.html#compiler-versions).
+
+##### 3. Install mbed CLI
+
+To install the mbed CLI, run `pip install mbed-cli` from your command line.
+
+You can check to make sure the mbed CLI installed correctly by running `mbed help`.
+
+##### 4. Setup Environment
+
+For any toolchain that is installed make sure to add the Mbed CLI global config:
 ```
-cd my_program
-```
+$ mbed config -G ARM_PATH <path to ARM bin\>"
+[mbed] <path to ARM bin\> now set as global ARM_PATH
 
-You can then start running Mbed CLI commands, and they will run in the correct context.
+$ mbed config --list
+[mbed] Global config:
+ARM_PATH=<path to ARM bin\>
 
-### Getting Blinky
+```
 
-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).
+**Note:** The same config can also be applied to IAR and GNU toolchains using `IAR_PATH` or `GCC_ARM_PATH`
 
-To import Blinky, from the command-line:
+#### Linux 
 
-1. Navigate to a directory of your choice. We're navigating to our development directory:
+##### 1. Install Python & Pip
 
- ```
- cd dev_directory
- ```
+Download and install [Python 2.7.12+](https://www.python.org/downloads/source/) or run the following from your command line:
 
-2. Import the example:
+```console
+$ sudo apt-get install python2.7
+$ sudo apt-get install python-pip
+$ sudo apt-get update
+```
 
- ```
- mbed import mbed-os-example-blinky
- cd mbed-os-example-blinky
- ```
+##### 2. Install a Compiler
 
-<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>
+Download and install a compiler:
 
-Blinky is now under `dev_directory` > `mbed-os-example-blinky`. You can look at `main.cpp` to familiarize yourself with the code.
+**Note:** To download the latest toolchains visit the [supported compilers page](/docs/latest/tools/index.html#compiler-versions).
 
-### Compiling
+##### 3. Install mbed CLI
 
-Invoke `mbed compile`, specifying:
+To install the mbed CLI, run `pip install mbed-cli` from your command line.
 
-* Your board: `-m <board_name>`.
-* Your toolchain: `-t <GCC_ARM, ARM, ARMC6 or IAR>`.
+You can check to make sure the mbed CLI installed correctly by running `mbed help`.
 
-For example, for the board K64F and the Arm Compiler 5:
+##### 4. Setup Environment
 
+For any toolchain that is installed make sure to add the Mbed CLI global config:
 ```
-mbed compile -m K64F -t ARM
+$ 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\>
+
 ```
 
-If you don't know the name of your target board, there are several ways to tell.
+**Note:** The same config can also be applied to IAR and GNU toolchains using `IAR_PATH` or `GCC_ARM_PATH`
 
-- 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:
+### Code
 
+#### 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
 ```
-[mbed] Detected "K64F" connected to "D:" and using com port "COM3"
-```
+ 
+#### 2. Compile and Program Board
 
-- Check the board information page on the list of <a href="https://developer.mbed.org/platforms/" target="_blank">Mbed Enabled boards</a>. The right side of each information page lists the name of the target.
+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
+``` 
 
-- If you only have one Mbed Enabled board connected, Mbed CLI can automatically detect the target by specifing `-m detect`.
+The `--flash` argument will automatically flash the compiled program onto your board if it is connected to your computer. You can see which boards are connected with `mbed detect`. 
 
-Your PC may take a few minutes to compile your code. At the end you should get the following result:
+After the program has been flashed to the board, press the board's "reset" button and you should now see the LED blinking.
 
-```
-[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 
-```
+**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 / targets by running the `mbed compile --supported`
+
+
+### Debug
+
+#### Desktop IDE
+
+To debug using a desktop IDE such as Keil uVision, IAR, or Eclipse you can use the `mbed export` command to generate project files. For example, for a K64F and Keil uVision:
+
+```console
+$ mbed export --ide uvision --target K64F
+``` 
+**NOTE** for a full list of exporters supported run the `mbed export --supported` command. 
+
+
+#### Printf
+
+Another way to do basic debugging is to use the `printf` command in your code, 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, then recompile the program and flash it to your device.
 
-The program file, `mbed-os-example-blinky.bin`, is under your `mbed-os-example-blinky\build\K64F\ARM\` folder.
+Invoke `mbed detect` from your command line to determine which communication port your board is connected to (i.e. `COM18`, `/dev/ttyACM0`, etc.). Unless otherwise specified, `printf` defaults to a baud rate/speed 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 API's](https://os.mbed.com/docs/v5.6/reference/apis.html) - List of all API's available in Mbed OS
+ - [Peripheral Drivers](https://os.mbed.com/docs/v5.6/reference/drivers.html) - IO Driver API's (I2C, SPI, UART, ... etc)
 
-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/v5.6/tutorials/debugging.html)
+ - [Serial Communications](https://os.mbed.com/docs/v5.6/tutorials/serial-communication.html)
+ - [Optimizing binary size](https://os.mbed.com/docs/v5.6/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/) - great resource full of knowledge and active user community. Ask your questions here first!
+ - [Youtube Channel](http://youtube.com/armmbed) - videos and workshop content

docs/tutorials/first_app/blinky_compiler.md

@@ -1,70 +1,81 @@
-## Blinky on the Arm Mbed Online Compiler
+## 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 <a href="https://os.mbed.com/account/signup/" target="_blank">developer account</a>. It's free, and we don't spam.</span>
+#### Create an Mbed developer account
+Go to os.mbed.com and [create an account](https://developer.mbed.org/account/signup/?next=%2F)
 
-### Importing Blinky
+#### Setup Environment
+- Plug your mbed board into your computer and open its USB device folder
+- Double click on the MBED.HTM file (this will add your mbed platform to the online compiler)
 
-To get Blinky into the Mbed Online Compiler, click the **`Import into Mbed IDE`** button below:
+If you do not have an Mbed board, go to [os.mbed.org/platforms](http://os.mbed.org/platforms), select a board and click the “Add to your mbed Compiler” button.
+<span class="images">![](https://sarahmarshy.github.io/img/add-to-compiler.png)
+</span>
 
-[![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)
+### Code
 
-You're taken to the online IDE, and the **Import Program** dialog box opens:
+#### Import 
+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.
+
+<span class="images">![](https://sarahmarshy.github.io/img/import-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>
+#### Compile
+Click on the "Compile" button, your browser will then download the program as a executable file.
 
-The import mechanism offers a default name, but you're free to change it. When you're done, click **Import**.
+<span class="images">![](https://sarahmarshy.github.io/img/compile.png)
+</span>
 
-### Viewing Blinky
+#### Program
+Open the folder where the executable file was downloaded, then click and drag (or copy and paste) the file to your mbed board's USB device folder.
 
-The imported Blinky has two interesting parts:
+Once the file has been flashed to the board, press the board's "reset" button and you should now see the LED blinking.
 
-- `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.
 
-Later we'll compile the code; this will take both of these parts and create a single application file from them.
+### Debug
 
-<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>
+#### Desktop IDE
 
-### Selecting a target 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 will then download a zip file with the project files.
 
-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.
+<span class="images">![](https://sarahmarshy.github.io/img/export.png)
+</span>
 
-#### Adding a board to your list
+#### Printf
 
-To add a board to your list, go to <a href="https://os.mbed.com/platforms/" target="_blank">the board's page on `os.mbed.com`</a>, and click the **`Add to your Mbed Compiler`** button:
+Another way to do basic debugging is to use the `printf` command in your code, 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, then recompile the program and flash it to your device.
 
-<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>
+Unless otherwise specified, `printf` defaults to a baud rate/speed of `9600` on mbed OS. To determine which communication port your board is connected to, follow the instructions for your operating system below:
 
-#### Selecting a board
+##### Windows
 
-The compiler shows the current build board's name on the upper right corner:
+Open the Device Manager by pressing `Windows key + R`, type `devmgmt.msc` and click "OK." Under "Ports (COM & LPT)" your mbed board will be listed as a "USB Serial Device" next to its COM port.
 
-<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>
+##### Linux
 
-Click the name to change your board as needed:
+Run `dmesg | grep tty` from your command line. 
 
-<span class="images">![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/select_board.png)<span>Selecting a board</span></span>
+##### Mac
 
-### Compile and install
+Run `ls /dev/tty.*` from your command line. 
 
-The Mbed Online Compiler builds your program as a `.bin` file that you can install on your board.
 
-1. Click **Compile**.
 
-<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>
+### Further Reading
 
-1. The program compiles:
+- Documentation
+- [Mbed OS API's](https://os.mbed.com/docs/v5.6/reference/apis.html) - List of all API's available in Mbed OS
+- [Peripheral Drivers](https://os.mbed.com/docs/v5.6/reference/drivers.html) - IO Driver API's (I2C, SPI, UART, ... etc)
 
-<span class="images">![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/compiling.png)<span>Compilation progress</span></span>
+- Tutorials
+- [Advanced Debugging](https://os.mbed.com/docs/v5.6/tutorials/debugging.html)
+- [Serial Communications](https://os.mbed.com/docs/v5.6/tutorials/serial-communication.html)
+- [Optimizing binary size](https://os.mbed.com/docs/v5.6/tutorials/optimizing.html)
 
-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.
+- 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/) - great resource full of knowledge and active user community. Ask your questions here first!
+- [Youtube Channel](http://youtube.com/armmbed) - videos and workshop content
 
-1. Connect your board to your computer over USB. Mbed boards are shown as "removable storage".
 
-<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>
-
-1. Drag and drop your program to the board. The board installs the program.
-
-1. Reset the board, and see the LED blink.