Document how to use custom mbed-os version in platformio

frameworks/mbed_extra.rst

@@ -101,6 +101,74 @@ An example of :ref:`projectconf` with enabled ``rtos``
     build_flags = -D PIO_FRAMEWORK_MBED_RTOS_PRESENT
 
 
+Custom version of Mbed
+^^^^^^^^^^^^^^^^^^^^^^
+
+PlatformIO comes with only a few versions of Mbed supported out of the box. If you want
+to use another release of the Mbed framework, you can use the `plateform_packages` config
+option. It should reference a directory containing `mbed-os <https://github.com/ARMmbed/mbed-os>`_
+plus the platformio `mbed builder code <https://github.com/platformio/builder-framework-mbed>`_
+and a `package.json` file like:
+
+.. code-block:: json
+
+   {
+     "name": "framework-mbed",
+     "version": "6.61500.211003",
+     "description": "Arm Mbed OS is a platform operating system designed for the internet of things",
+     "keywords": [
+       "framework",
+       "os",
+       "arm",
+       "hal"
+     ],
+     "homepage": "http://mbed.org",
+     "repository": {
+       "type": "git",
+       "url": "https://github.com/ARMmbed/mbed-os"
+     }
+   }
+
+For example, to use the version 6.15 of mbed-os, you may:
+
+.. code-block:: bash
+
+   ~$ git clone https://github.com/ARMmbed/mbed-os framework-mbed
+   ~$ cd framework-mbed
+   ~/framework-mbed$ git checkout mbed-os-6.15.0
+   ~/framework-mbed$ git clone https://github.com/platformio/builder-framework-mbed# platformio
+   ~/framework-mbed$ cat >package.json <<EOF
+   {
+     "name": "framework-mbed",
+     "version": "6.61500.211003",
+     "description": "Arm Mbed OS is a platform operating system designed for the internet of things",
+     "keywords": [
+       "framework",
+       "os",
+       "arm",
+       "hal"
+     ],
+     "homepage": "http://mbed.org",
+     "repository": {
+       "type": "git",
+       "url": "https://github.com/ARMmbed/mbed-os"
+     }
+   }
+   EOF
+
+Then one ca use the following `platformio.ini` file:
+
+.. code-block:: ini
+
+   [env:mproject]
+   platform = ststm32
+   framework = mbed
+   platform_packages =
+     framework-mbed @ file://framework-mbed
+
+To build the project using mbed-os 6.15.0.
+
+
 Build profiles
 ~~~~~~~~~~~~~~