ARMmbed · iriark01 · May 11, 2020 · Apr 22, 2020 · Apr 22, 2020 · Apr 22, 2020
diff --git a/docs/api/api.md b/docs/api/api.md
@@ -5,7 +5,6 @@
 
 The Mbed OS RTOS capabilities include managing objects such as threads, synchronization objects and timers. It also provides interfaces for attaching an application-specific idle hook function, reads the OS tick count and implements functionality to report RTOS errors.
 
-
 <table>
 <tbody>
 <tr>

diff --git a/docs/program-setup/bare_metal/bare_metal.md b/docs/program-setup/bare_metal/bare_metal.md
@@ -1,22 +1,19 @@
 # Mbed OS bare metal profile
 
-There are many use cases for IoT devices. Different use cases require different configurations, connectivity and security. They also have different requirements for resource consumption. Many products must operate in ultraconstrained environments on tiny MCUs with low memory and compute power available. We created the Mbed OS bare metal profile for IoT devices that require ultraconstrained resources.
+Bare metal is a profile of Mbed OS for ultraconstrained devices. Unlike the full Mbed OS, which by default includes all APIs, the bare metal profile starts with a minimal set of APIs to which you can add only the APIs your application or hardware demand. This helps you control the size of your final binary.<!--not sure that's a good term-->
 
-<span class="images">![Mbed OS bare metal profile block diagram](../../images/bare_metal_block_diagram.png)<span>Mbed OS bare metal profile block digram</span></span>
+Bare metal doesn't use the RTOS APIs. Instead, it relies on timers to control the workflow.
+<!--not sure I get it - I looked at both Blinky examples and they both use thread_sleep_for, even though the bare metal one doesn't include mbed_thread.h-->
+<!--what other APIs does it have or not have by default?-->
+
+The Mbed OS tools - Mbed CLI, Mbed Online Compiler and Mbed Studio all support working with the bare metal profile.
 
-The Mbed OS bare metal profile is a compact profile of Mbed OS without an RTOS. The Mbed OS bare metal profile is API compatible with Mbed OS and supports a subset of Mbed OS features, such as analog I/O, digital I/O, timers and digital interfaces, such as SPI, I2C, Serial and CAN. Mbed Studio, Mbed CLI and the Mbed Online Compiler all support the Mbed OS bare metal profile.
+Note that Mbed TLS and Mbed Crypto are not supported for bare metal.
+
+<span class="images">![Mbed OS bare metal profile block diagram](../../images/bare_metal_block_diagram.png)<span>Mbed OS bare metal profile block digram</span></span>
 
-| Features | Mbed OS bare metal  | Mbed OS |
-| --- | ---  | --- |
-| Analog I/O | Available | Available |
-| Digital I/O | Available | Available |
-| Digital interfaces | Available | Available |
-| Timers | Available | Available |
-| Development tools<br> (For example, Mbed CLI, Mbed Studio, Mbed Online Compiler, GCC, Arm Compiler 6 and so on) | Available | Available |
-| Support for Mbed Enabled development boards | Available | Available |
-| RTOS | Not available | Available |
-| Storage | Ecosystem libraries | Available |
-| Mbed TLS | Not available | Available |
-| Mbed PSA | Not available | Available |
+## Documentation
 
-To begin using the Mbed OS bare metal profile from Mbed OS 2, please follow our [instructions](../tutorials/migrating-to-mbed-os-5.html).
+- To see how to enable the profile, or to try the bare metal Blinky, see [our example page]().
+- To learn how to add APIs, [see the bare metal API page]().
+- If you're an Mbed OS 2 user, migrate to the Mbed OS 6 bare metal profile by following [our migration guide]().<!--that's not application develoeprs though, right? it's for hardware people?-->
diff --git a/docs/program-setup/bare_metal/bare_metal_api.md b/docs/program-setup/bare_metal/bare_metal_api.md
@@ -1,47 +1,26 @@
 # Bare metal APIs
 
-Mbed OS bare metal supports the following APIs:
+The bare metal profile starts with a restricted list of API, to which you can add what you need. However, bare metal doesn't support all Mbed OS APIs.
 
-<h2 id="analog-i-o">Analog I/O</h2>
+## Initial list of APIs
 
-- AnalogIn - Read the voltage applied to an analog input pin.
-- AnalogOut - Set the voltage of an analog output pin.
+By default, bare metal includes the following APIs:
 
-<h2 id="digital-i-o">Digital I/O</h2>
+## Adding APIs
 
-- DigitalIn - Configure and control a digital input pin.
-- DigitalOut - Configure and control a digital output pin.
-- DigitalInOut - Bidirectional digital pins.
+<!--how?-->
 
-- BusIn - Flexible way to read multiple DigitalIn pins as one value.
-- BusOut - Flexible way to write multiple DigitalOut pins as one value.
-- BusInOut - Flexible way to read and write multiple DigitalInOut pins as one value.
+## Full list of APIs
 
-- PortIn - Fast way to read multiple DigitalIn pins as one value.
-- PortOut - Fast way to write multiple DigitalOut pins as one value.
-- PortInOut - Fast way to read and write multiple DigitalInOut pins as one value.
+The [Mbed OS API list]() indicates which APIs are supported by bare metal.
 
-- PwmOut - Pulse-width modulated output.
+<!--
+Evelyne, my suggestion is to use something like
 
-- InterruptIn - Trigger an event when a digital input pin changes.
 
-<h2 id="timers">Timers</h2>
+| API | Full Mbed OS | Bare metal |
+| - | - | - |
+| AnalogIn | &#9745; | &#9745; |
 
-- Timer - Create, start, stop and read a timer.
-- Timeout - Call a function after a specified delay.
-- Ticker - Repeatedly call a function.
-
-- Wait - Wait for a specified time.
-- Time - Get and set the realtime clock.
-
-<h2 id="digital-interfaces">Digital Interfaces</h2>
-
-- Serial - Serial/UART bus.
-
-- SPI - SPI bus master.
-- SPISlave - SPI bus slave.
-
-- I2C - I²C bus master.
-- I2CSlave - I²C bus slave.
-
-- CAN - Controller-area network bus.
+Although it's a bit silly, because of course it's supported in the full Mbed OS... I'd love some suggestions
+-->
diff --git a/docs/program-setup/bare_metal/baremetal_example.md b/docs/program-setup/bare_metal/baremetal_example.md
@@ -1,6 +1,6 @@
 # Bare metal example
 
-To enable Mbed OS bare metal, create an `mbed_app.json` with the following contents:
+By default, Mbed OS is built in full whenever you create an application binary. To build only the bare metal profile, create an `mbed_app.json` in your application with the following contents:
 
 ```
 {

diff --git a/docs/program-setup/bare_metal/c_small_libs.md b/docs/program-setup/bare_metal/c_small_libs.md
@@ -1,5 +1,7 @@
 <h1 id="using-small-c-libraries">Using small C libraries in Mbed OS bare metal</h1>
-
+<!--is this page for app developers? do we expect them to always manually specify for their app that they want to use bare metal?-->
+<!--I'm also intriggued by the phrasing "if your application doesn't use an RTOS". Of course it doesn't; we're talking about bare metal-->
+<!--in other words: who should read this page, and when/why?-->
 If your application does not use an RTOS, build it in the bare metal mode to achieve memory savings. Both the `ARM` and `GCC_ARM` toolchains support code optimized versions of their C standard libraries, `microlib` and `newlib-nano`. It is safe to use these smaller C libraries in bare metal mode, and we recommend using them.
 
 You can build with the smaller C libraries by creating an `mbed_app.json` with the following contents:
-Original file line number
+Diff line change
@@ Expand Up / @@ -5,7 +5,6 @@ @@
     The Mbed OS RTOS capabilities include managing objects such as threads, synchronization objects and timers. It also provides interfaces for attaching an application-specific idle hook function, reads the OS tick count and implements functionality to report RTOS errors.
     <table>
     <tbody>
     <tr>
@@ Expand Down @@