📝 (docs): Update & clean up install/how-to documentation

- remove Linux/Ubuntu instructions
- fix typos, old links, etc.
- add vscode plugins and instructions

docs/INSTALL.md

@@ -5,13 +5,13 @@
 LekaOS repository is made to be easy to use:
 
 - simple directory structure
-- CMake based with [USCRPL/mbed-cmake](https://github.com/USCRPL/mbed-cmake/)
-- Code completion with VSCode + [CMake Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools)
+- compile with CMake (based on [USCRPL/mbed-cmake](https://github.com/USCRPL/mbed-cmake/))
+- code completion with VSCode + [CMake Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools) + [clangd/vscode-clangd](https://github.com/clangd/vscode-clangd)
 - format with `.clang-format` and `.editorconfig`
 
 ## How to install
 
-Before starting, make sure you've read the [mbed documentation](https://os.mbed.com/docs/mbed-os/v6.8/introduction/index.html).
+Before starting, make sure you've read the [mbed documentation](https://os.mbed.com/docs/mbed-os/v6.15/introduction/index.html).
 
 We'll guide you in the process, just follow the steps.
 
@@ -36,7 +36,7 @@ Then install the tools:
 ```bash
 # first install GNU core utilities
 brew install coreutils
-# don’t forget to add `$(brew --prefix coreutils)/libexec/gnubin` to your `$PATH`
+# 💡 don’t forget to add `$(brew --prefix coreutils)/libexec/gnubin` to your `$PATH`
 
 # then the prerequisites
 brew install git curl python
@@ -45,21 +45,6 @@ brew install git curl python
 brew install make cmake ninja lcov gcovr stlink ccache open-ocd clang-format
 ```
 
-#### Ubuntu/Linux
-
-*Note: The following instructions have not really been tested, so you might need to modify the names of the packages.*
-
-```bash
-# first update
-sudo apt update
-
-# then the prerequisites
-sudo apt install build-essential git python-minimal
-
-# and finally the needed tools
-sudo apt install make cmake ninja-build lcov gcovr stlink ccache open-ocd
-```
-
 ### 1. Clone the repository
 
 To start with:
@@ -68,20 +53,15 @@ To start with:
 # Clone the repository
 git clone https://github.com/leka/LekaOS && cd LekaOS
 
-# Clone or curl Mbed OS using the Makefile
-make mbed_clone
-# or
-make mbed_curl
-
-# With mbed_clone You can specify a branch
-make mbed_clone BRANCH=master
+# Pull dependencies: mbed-os & mcuboot
+make pull_deps
 ```
 
 ### 2. Install mbed-cli & co
 
 I recommend the manual install. Make sure to follow the instructions from mbed:
 
-> <https://os.mbed.com/docs/mbed-os/v6.3/build-tools/install-and-set-up.html>
+> <https://os.mbed.com/docs/mbed-os/v6.15/build-tools/install-and-set-up.html>
 
 ```bash
 # install mbed-cli and mbed-tools (mbed-cli2)
@@ -103,31 +83,12 @@ brew tap ArmMbed/homebrew-formulae
 brew install arm-none-eabi-gcc
 ```
 
-#### Ubuntu/Linux
-
-You can download the toolchain here:
-
-> <https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads>
-
-The file to download should have a name looking like this: `gcc-arm-none-eabi-10-2020-q4-major-x86_64-linux.tar.bz2`, save it to your `$HOME` directory (or anywhere you can remember).
-
-Then do the following (you might need to change the name of the file depending on the version):
-
-```bash
-# untar the new package in the directory of your choosing
-tar -xjvf gcc-arm-none-eabi-10-2020-q4-major-x86_64-linux.tar.bz2
-
-# add the new toolchain to your path
-export PATH=$PATH:$HOME/gcc-arm-none-eabi-10-2020-q4-major-x86_64-linux/bin/
-
-# test it works
-arm-none-eabi-gcc --version
-```
-
 ## How to use
 
 We put together an handy [`Makefile`](./Makefile) to make it easier to configure and compile your projects.
 
+### Building the project
+
 ```bash
 # first configure the project
 make config
@@ -141,16 +102,50 @@ make
 
 ### Flashing the board
 
-> ⚠️ // TODO - add instructions for openOCD
+Make sure you have [OpenOCD](https://openocd.org/) installed.
 
 ```bash
 make flash BIN_PATH=_build/path/to/binary_file.bin
 ```
 
+### Building & running unit tests
+
+```bash
+# first configure unit tests
+make config_unit_tests
+
+# build and run them
+make ut
+
+# if you want to see coverage
+make utc
+```
+
 ## LekaOS, spikes & tests
 
-The main idea behind this template is to have your main source files (those for the big project you're working on) under the [`./src`](./src) directory.
+The firmware of the robot is located in [`./app/os`](./app/os) & [`./app/bootloader`](./app/bootloader).
+
+> `firmware = bootloader + os`
+
+Sometimes, you might need to create a simple, very basic example project to test a new features, investigate a bug or try a different solution to a problem.
+
+These can be added to the [`spikes`](./spikes) directory inside their own directory. You'll need at leat a `main.cpp` and a `CMakeLists.txt`. See [`mbed_blinky`](./spikes/mbed_blinky) for a working example.
+
+## VSCode & useful tools
+
+We use VSCode and a handful of plugins to work on LekaOS:
+
+- [Better C++ Syntax](https://github.com/jeff-hykin/better-cpp-syntax)
+- [Better Comments](https://github.com/aaron-bond/better-comments)
+- [Clang-Format](https://github.com/xaverh/vscode-clang-format-provider)
+- [clangd](https://github.com/clangd/vscode-clangd)
+- [CMake](https://github.com/twxs/vs.language.cmake)
+- [CMake Tools](https://github.com/microsoft/vscode-cmake-tools)
+- [Cortex-Debug](https://github.com/Marus/cortex-debug)
+- [EditorConfig for VSCode](https://github.com/editorconfig/editorconfig-vscode)
+
+It is highly recommended to install them for a better experience and to make sure you comply with our coding style.
 
-Now, you sometimes need to create a simple, very basic example project to test a new features, investigate a bug or try a different solution to a problem.
+Settings for those plugins are shared in the repos and should not be modified.
 
-These can be added to the [`spikes`](./spikes) directory inside their own directory. You'll need at leat a `main.cpp` and a `CMakeLists.txt`. See [`blinky`](./spikes/blinky) for a working example.
+To configure autocompletion and code checking using `clangd`, simply run `make config_tools` in your terminal. And then in VSCode, run `CMake: Configure`.