I find mbed OS 5 handbook is a great resource to learn mbed OS 5. However it is inconvenient to resume the reading on browser, is there a way to convert the documentation into a pdf file for offline reading?

Just noticed 5.6 documentation went live but I can't find sources to create an issue against.

There is an article in the Handbook describing the use of a VSC debugger.

https://docs.mbed.com/docs/mbed-os-handbook/en/latest/debugging/vscode/

The CLI command

$ mbed export -i vscode_gcc_arm -m K64F

should export a program to VSC but there is no such exporter

The download link for mbed CLI for Windows is extremely difficult to find due to it being a code block

https://os.mbed.com/docs/v5.7/tools/installing-with-the-windows-installer.html

It took me and 2 others over 5 minutes to realize that "mbed-windows-installer v0.4.3" was a link and not a command for the CLI.

Document docs/advanced/config_system.md contains broken links to something which seems to be a porting guide in particular to this page. Where can I find this "Porting Guide"?

In https://github.com/ARMmbed/Handbook/blob/5.6/docs/tutorials/using_apis/events_tutorial.md we do printf() calls in ISRs to show how the code is ran. This is not supported. It used to work in GCC but not with latest mbed OS (throws 'not supported in interrupt context' or something similar on the serial) and never worked in ARMCC.

I'm not sure who wrote this article, but it needs to be rewritten.

@AnotherButler

Note that I wrote https://developer.mbed.org/blog/entry/Simplify-your-code-with-mbed-events/ some time ago, maybe it fits this section too.

It is clear that I2C Slave is not interrupt safe. What is maybe ambiguous is I2C Master. This document does not state it explicitly, and students have been asking.

https://github.com/ARMmbed/Handbook/blob/5.5/docs/concepts/thread_safety.md#drivers

Main issue, documentation for mesh is broken. Breakdown of APIs is inconsistent.
https://os.mbed.com/docs/v5.7/reference/network-socket.html NetworkInterface does not list mesh.

https://os.mbed.com/docs/v5.7/reference/network-socket.html, In network socket list, link for the mesh is broken.

As a general comment, I would like to point out that the current style of documentation for network technologies is unattractive and 'way too' concise. Documentation for other bits of operating system is fine but network technologies which are the heart of all what IoT stands for is dismal.

In the coding guideline, under the rules section the following rule is enunciated:

For pointers, * is adjacent to a name (analogin_t *obj).

It raise several questions:

• Should this rule be applied to references ?
• What if the name is omitted ? This can be the case in function declaration. Shall it be void foo(int*) or void foo(int *)
• Is that rule valid for function return type ? Shall it be int *foo(void) or int* foo(void) ?
• What shall be used to declare immutable pointers ? The rule cannot be applied because the const modifier have to go to the right of the pointer according to the C and C++ standards.
• How pointer to pointer and reference to pointer shall be written int* &foo or int *&foo ?

I also want to point out that C and C++ standard takes different stances on the subject (even if both constructs are valid). In the C standard there is always a space between the pointee type and the pointer declarator followed by another space if a qualifiers follow. In C++ standard pointer and references declarator are always weld to the type they point to.

It may be interesting to had a bit of background behind the choice.

Another note, when doxygen generate a function documentation, the rule is broken and the pointer goes next to the type it points to (example)

Reference: https://github.com/ARMmbed/Handbook/blob/5.7/docs/reference/api/drivers/Serial.md#example-three

It should either be doing buffering in ISR or use RawSerial (the api is regarding Serial thus would probably need to be rewritten to capture characters and process them in the main thread?)

On the Reference Manual's Contributing page the following links are dead.

WiFiInterface.h

CellularInterface.h

MeshInterface.h

The Lora intro docs has been moved to the Technology section
https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/technology/connectivity/intro-to-lora.md

This is great. However, there are parts of the docs that should be moved to Tutorial section, as provide step-by-step instructions on how to do things.

@janjongboom
I have a customer who would prefer to use windows to host their toolchain.

The documentation for vscode debugging seems to indicate that all you'll need to do is install ARM embedded toolchain, export for vscode and everything will build. Which would probably be the case in linux.

However, I was under the impression that ARM embedded toolchain windows installer doesn't include make.

Can the documentation be clarified as to how to set up the ARM embedded toolchain to work with an exported vscode project on windows?

As of this moment it seems to only link to mcu on eclipse documentation which is eclipse specific.

References:
https://os.mbed.com/docs/v5.6/tutorials/visual-studio-code.html
https://os.mbed.com/docs/v5.6/tools/setting-up-a-local-debug-toolchain.html
https://os.mbed.com/docs/v5.6/tools/setting-up-a-local-debug-toolchain.html
https://os.mbed.com/docs/v5.6/tools/exporting.html (IMO especially confusing document, maybe break it into multiple docs for each exporter)

In docs/advanced/exporters.md there is

## Eclipse and Make 

Eclipse project export uses a generated Makefile for building. To provide support for 
Make export, you only have to provide the target configuration within the 
[config system](https://github.com/ARMmbed/mbed-os/blob/master/docs/mbed_targets.md).

As far as I can tell, the link is broken.

@theotherjimmy, can you clarify what does this phrase mean? I would like to add here a reference to the GNU ARM Eclipse exporter, but I don't know how to cope with this phrase.

the files were restructured in the mbedmicro/mbed library on github. there are several links in the handbook that reference files that have been moved. The links need to be updated. See page:
https://developer.mbed.org/handbook/mbed-SDK-porting

For example, the link to the file, sleep_api.h, formerly was here:
https://github.com/mbedmicro/mbed/tree/master/libraries/mbed/hal/sleep_api.h

but now is located here.
https://github.com/mbedmicro/mbed/blob/master/hal/hal/sleep_api.h

Please change the links. Otherwise people get 404 errors!

thanks

VSCode feature is now landed, but the page was removed from handbook.

Can we put it back?

@AnotherButler

bluetooth.md has a reference to nRF Master Control Panel which is now called nRF connect.

Also, I've seen similar references in mbed BLE examples elsewhere.

The following screen capture comes from the page shown when I select Reference in the navigation pane.

As shown selecting Reference actually takes you down 2 extra levels to the "MBED OS Reference Book" page.

All other top level Navigation links (Introduction, Tools, Tutorials) behave similarly.

Compare this behavior to when Configuration is selected.

I would greatly prefer the behavior exhibited in the latter example for the top level navigation links.

Let me know if this is confusing.

https://github.com/ARMmbed/Handbook/blob/5.3/docs/dev_tools/options.md#mbed-studio

"mbed Studio is an mbed Enabled IDE based on Cloud9 and offers a rich development environment. It is currently in alpha and should be considered experimental. You can try it by selecting mbed Studio from the Import Program drop-down on our code samples."

I still hunt for this magical drop-down option every couple days.

In the https://github.com/ARMmbed/Handbook/blob/5.4/docs/cont/contributing.md#how-to-apply-pbl-correctly section of the Handbook the PBL is sometimes expanded to Public Binary License but in most places (including the legal license description), it is referred to as the Permissive Binary License.

Examples of where it appears to be named incorrectly in this section:

Unless specifically indicated otherwise in a file, files are licensed under the Public Binary License, 
as can be found in: LICENSE-permissive-binary-license-1.0.txt

• The full original Public Binary License 1.0 text in LICENSE-permissive-binary-license-1.0.txt.

From what I recall the doc pages are rendered with an ARM proprietary system.
If I wanted to make changes to the docs how would you recommend I test?

Would be nice to have CI going for this repository...

The home of ARM embedded toolchain has moved to:

https://developer.arm.com/open-source/gnu-toolchain/gnu-rm

Clicking on the BLE Class Reference url throws "Page error" and the class reference does not render.
https://os.mbed.com/docs/v5.6/mbed-os-api-doxy/class_b_l_e.html
This seems to be the case for all BLE APIs
https://os.mbed.com/docs/v5.6/mbed-os-api-doxy/class_heart_rate_service.html
https://os.mbed.com/docs/v5.6/reference/ibeacon.html#ibeacon-class-reference
@AnotherButler

I cannot find the source against which to file issues for the Handbook, Dev Tools, CLI. The closest I could find the documentation is here:
https://github.com/ARMmbed/Handbook/blob/5.4/docs/dev_tools/cli.md

Which refers to:
https://raw.githubusercontent.com/ARMmbed/mbed-cli/master/README.md%7D

Which says 404.

Request

Document which classes/functions use dynamic memory.

Motivation

Developers often avoid or minimize use of dynamic memory in embedded system, to avoid memory fragmentation or overflow, to aid in determinism, etc. Also, an easy way to manage external memory is to make all dynamic allocations go there, and to have all static/stack allocations go to internal memory.

Developers should be able to choose consciously whether and when to use dynamic memory. Thus we need to know when the OS is using it.

On this page

https://os.mbed.com/docs/v5.8/reference/eventqueue.html

in the example "Shared event example: deferring from interrupt context", it says, "Like the previous example, this defers from interrupt to an event queue thread." However, that's not what either of the two preceding examples do.

I think it should immediately follow the first example, which is titled "EventQueue example: deferring from interrupt context". The titles differ by only 1-2 words, and the code only by a few lines.

ARM Mbed OS Software Design Guide
is generated as a subheading of: Memory Optimization

Should it be it's own, or on a different page?

It could be nice to have some way of navigating beyond the great wall of templates on the eventQueue page.

Link at the bottom of this doc is broken:
https://docs.mbed.com/docs/mbed-os-handbook/en/5.2/advanced/tls_porting/

It's pointing at this location (https://docs.mbed.com/docs/mbed-os-handbook/en/5.2/advanced/mbed_OS/Config_sys.md) which is not available.

"
You can read more about how to add a macro for your application here.
"

I just encountered compatible issue while using latest pyocd with mbed-cli 1.1.1, after update to 1.2.0, it works. so recommend to add particular note to highlight it.

At the end of the advanced/mbed_targets page, there is a link to exporter.
It links to https://docs.mbed.com/docs/mbed-os-handbook/en/5.3/advanced/mbed_targets/exporters.md.

While this link seems to be broken, we got 404 error for that link.

There are some reference commend in the porting chapter as below.
Actually there is no "mbed-os-example-new-target" repository and mbed import will be fail.
Is it a typo which want to use "mbed new" or there was such a repository?

ps:

• mbed import mbed-os-example-new-target
• cd mbed-os-example-new-target\mbed-os
• git checkout master
• git pull
• git checkout -b my-new-target
• git remote set-url origin https://github.com/USERNAME/mbed-os
• cd ..

For the blinky_compiler document, the Compile and Install section, step 6 says:
6. The board installs the program and then runs it. You should see the LED blink.

For us, this required a reset before the program took effect; flashing does not reload the program.

Sleeping in Mbed OS 5 is fundamentally different from earlier versions (SleepManager.md). We need to emphasize that sleep() should never be called manually and add some extra examples how this works with multiple threads pinging. Also, how does sleep behave when you wait on a Semaphore instead of via wait()? Also, need more info that on develop profile the device might not go to sleep properly, and how to enable release mode from online compiler.

Another issue is that the new docs are unfindable through Google: https://www.google.co.uk/search?q=sleep+mbed&oq=sleep+mbed&aqs=chrome..69i57.1087j0j1&sourceid=chrome&ie=UTF-8 We need to put some notes on the old pages that this has changed now.

@AnotherButler @senthilr

I don't have time to study and explain why I believe this isn't working.
I just know it must not be working because it completely inhibits me from getting into flow

I was checking out the recent content improvements to the handbook and had to literally close the tab to prevent myself from trying to figure out what I was looking at.

While I suspect there might be an issue with the heading levels in this instance, I think my main concern has something to do with the blue lines as a whole.

Github search engine restrict indexation for search to a repository default branch.

This repository default branch, master, is empty and is not updated. All developments happen in the new_engine branch.

Would it be possible to make the new_engine branch the default branch or bring back development on master so we can search the repository via Github ?

Any chance of this happening?

What is preventing if not?

https://os.mbed.com/docs/v5.8/reference/workflow.html
https://os.mbed.com/docs/v5.8/reference/how-we-release-arm-mbed-os.html <- dead

Content in sources and rendered website differ, it's not due to recent chances to docs, as the docs are quite old.
https://github.com/ARMmbed/Handbook/blob/5.5/docs/dev_tools/build_profiles.md
https://docs.mbed.com/docs/mbed-os-handbook/en/latest/dev_tools/build_profiles/

This part is missing from the website:

  * Debugger is likely to drop connection.
  * Breaks the local file system on the [mbed interface](https://docs.mbed.com/docs/mbed-os-handbook/en/latest/getting_started/mbed_interface/) on some boards.

for both develop and release profiles.

@AnotherButler

At https://github.com/ARMmbed/Handbook/blob/5.4/docs/dev_tools/online_comp.md#compile-and-download , I see the first two compile options described like this:

1. Compile: builds your code and downloads a binary file. Current program only.
2. Compile All: same as compile, but for all programs.

The difference between these two options isn't what programs in your workspace are built but whether an incremental or clean build is performed. The following descriptions would be closer to what I expect to see here in the documentation:

1. Compile: builds code that you have modified since your last compile and downloads the resulting binary file.
2. Compile All: same as compile, but rebuilds all source code, even if it hasn't changed since the last compile.

From:
https://github.com/ARMmbed/Handbook/blob/new_engine/docs/tutorials/optimize/memory/runtime_stats.md#L11

To enable heap stats:
1. Add the command-line flag -DMBED_HEAP_STATS_ENABLED=1.
2. Use the function mbed_stats_heap_get() to take a snapshot of heap stats.

Should this be enabled via command line flag or by adding it to macros in the app config json file?

Also why isn't this defined and described as a macro in https://github.com/ARMmbed/mbed-os/blob/master/platform/mbed_lib.json

When click the link in the left menu Reference > APIs > Drivers > Serial, description of Serial API is expected. However, the contents of Reference > Contributing > Porting targets > Serial is shown. This problem is on v5.8.

Based on latest PR after we introduced PR type, I noticed that sometimes it is not clear what type a pull request belongs to. This might be due to not specifying each of these types.

Questions that I would like to answer and point to when not clear in contributions:

What is a fix or feature or refactor? When is it a breaking change?

We will send a proposal for clarification

@AnotherButler There used to be a public repository for meta-documentation of this repository.

Can it be made public again?

I believe it also documented how the "new_engine" operates which would be useful for the community to make better merge requests.

On the Platform Overview page in the Reference manual there is a "Callbacks" section that seems out of place.

The Callback page references the previously mentioned section as the "the introduction to callbacks".

I found it confusing that Callbacks were the only platform feature to be introduced as a section in the top level the Reference manual's Platform page.

https://docs.mbed.com/docs/mbed-os-handbook/en/5.1/
Link to mbed Studio is broken

I don't understand how to use the Mbed OS configuration system. I think the reference documentation regarding it is unclear. If I'm missing something(s) obvious, please point me to it. Otherwise, please clarify the documentation to answer questions such as those I pose below. (Also, I'd appreciate some quick answers here, if possible.)

For instance, the page linked above provides an example of how to configure the stack size for the main thread, by putting this in mbed_app.json:

{
    "config": {
        "main-stack-size": {
            "value": 2000
        }
    }
}

But how does this work? What does it do? I couldn't find "main-stack-size" anywhere in the mbed-os or mbed-cli code trees. (I used grep -R.)

On further searching (grep -Ri "main[^ ]stack[^ ]size" .), I find the conditional #define MBED_CONF_APP_MAIN_STACK_SIZE in mbed_boot.c, so I infer that lower-case-hyphenated labels in .json files get somehow translated to MBED_CONF_ALL_CAPS #defines - but how? Where is the code that does this so I can learn more when the documentation falls short, or I want to improve something? How/where do the custom #defines I configure get made visible to my code? (e.g. In makefiles, or is a new header file generated? What about when I use mbed export?) [EDIT: I see that it generates mbed_config.h. Please consider mentioning this in the documentation.]

Where can I find the list of configurable items? Are there more than what are listed on the pages linked below?

How does the info on the Platform, Drivers, RTOS, and Connectivity pages translate to what I should put in a .json file? And how do the .json files get named?

For instance, the Platform page begins with this:

Configuration parameters
------------------------

Name: platform.default-serial-baud-rate
    Description: Default baud rate for a Serial or RawSerial instance (if not specified in the constructor)
    Defined by: library:platform
    Macro name: MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE
    Value: 9600 (set by library:platform)

What do I put in a .json file to #define MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE to the desired value? How do I name the .json file? What is the meaning of the . separator in the Name? What is the meaning of the : separator in Defined by?

Hi,

https://os.mbed.com/docs/v5.6/tutorials/eclipse.html

This document explains how to build and debug Arm Mbed OS applications using Eclipse. Before starting, please configure your local debug toolchain.

The above text should be elaborated like following.

This document explains how to build and debug Arm Mbed OS applications using Eclipse. Before starting, please check which debug toolchains you are targeting from this list.

Or maybe I am not understanding the intention well. Please elaborate.

In the image below, I couldn't see the current page indication "light gray-blue highlight".

Looking at this on a different monitor indicated my monitor needed adjusting.

However, I still think the current page indication is either too light or needs a different indicator altogether.