mbed OS quickstart #363
mbed OS quickstart #363
Conversation
| @AnotherButler , do not merge, do not review. Still pending input from os tech and product leads, content will likely change slightly. @sg- any comments please make as changes here @senthilr for tracking |
| Can I see this rendered anywhere? |
| @sg- mbed-os-qs-rough-draft.zip |
| There actually is a preview mechanism. You just need to ask. |
| @iriark01 need a mechanism for preview that does not require external interraction and that cannot be overwritten by any other than the user. Something like the notebook pages fromt he old system would be great. |
| @sg- You can view it here: https://docs.internal.mbed.com/docs/master/quickstart/index.html |
| @AnotherButler , added changes / feedback from Sam G, please proceed with review |
| For reference: this is a rehash of the content generated by @yennster here : https://github.com/yennster/mbed-os-quickstart which can be viewed here http://jennyplunkett.me/mbed-os-quickstart/ |
| Nice work, @yennster I'm looking over this now, but I probably won't have edits ready for you to review until the new year. |
| @@ -1,14 +1,12 @@ | |||
| ## Your first Arm Mbed application | |||
There was a problem hiding this comment.
We should include some sort of introduction paragraph stating what the user is going to do. The user knows it's a quickstart, but explain what that means. Will the user blink a light at the end? Log in? Create and end-to-end product? Please clarify.
There was a problem hiding this comment.
@yennster Could you please help me create an intro paragraph? Or sit with me and verbalize what the user should expect to get out of this? Thanks so much.
There was a problem hiding this comment.
@AnotherButler Do you still need an intro paragraph before ## Choose your environment?
There was a problem hiding this comment.
@yennster Yes. I was waiting to write it until we knew whether we'd be including Mbed CLI, but it may not be a bad idea to start drafting something that we could use whether or not we include CLI.
| In the mbed ecosystem you have choice on how you want to develop, **Online** and **Offline**. | ||
| | ||
| We have an example application called Blinky that you can use to get to know Arm Mbed OS and the development tools. It's one of the simplest examples of Mbed OS. It shows the use of a DigitalOut object to represent an LED and the `wait()` call. This is good practice because if there were other threads, they could be scheduled and run while the first thread is waiting. | ||
| 1) Online there is the Mbed Compiler. This choice is great if you want an environment that 'just works'. All you need is a web browser and you're good to go. |
There was a problem hiding this comment.
Query: Is this accurate? The only thing you need is a web browser? I would argue that you also need some knowledge of C/C++, a cable and a board.
There was a problem hiding this comment.
thats always been our pitch. @sg- to see if thats changed
| 1) Online there is the Mbed Compiler. This choice is great if you want an environment that 'just works'. All you need is a web browser and you're good to go. | ||
| | ||
| You can use either of these tools: | ||
| 2) Offline there is Mbed CLI, a full suite of tools for use on the command line. Mbed CLI is compatible with Windows, Linux and OSX. This option provides more configuratino options but also requires slightly more setup. |
There was a problem hiding this comment.
Query: Is Mbed CLI a full suite of tools?
There was a problem hiding this comment.
Yes. mbed CLI is the command line interface for all things mbed.
There was a problem hiding this comment.
change to 'mbed CLI is the tool for using Mbed on thec ommand line"
| ## 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 |
There was a problem hiding this comment.
It seems weird for the first content to tell the reader to skip ahead.
There was a problem hiding this comment.
lets discuss in person
There was a problem hiding this comment.
Reviewed togetehr, amanda to re-write sentence and git 'er done.
| | ||
| ### Blinky's code | ||
| #### Windows | ||
| |
There was a problem hiding this comment.
For each section, it would be nice to see upfront any prereqs, time expected and so on. It feels like we may be getting ahead of ourselves jumping straight into installing a .exe.
There was a problem hiding this comment.
the .exe is the pre-reqs all wrapped up into one easy step, eventually want to have a similar thing for OSX too. but for now it doesnt exist
There was a problem hiding this comment.
Reviewed, amanda to add sentence and push. Git'er'done
| **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 |
There was a problem hiding this comment.
Query: Should debugging be part of the quickstart? It feels out of scope to me.
There was a problem hiding this comment.
This is a light touch, there is a more in depth tutorial for debugging. I believe it is fine.
| 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) |
There was a problem hiding this comment.
Query: Why do we link to the APIs and then link to a subsection of the APIs? They're included in the link above.
There was a problem hiding this comment.
This is based on interactions with users. majority of users still are interested in the 2.0 API's, now called peripheral drivers, so we link directly to them. Never hurts to have multiple paths
There was a problem hiding this comment.
agree to disagree and let it slide.
| - `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 |
There was a problem hiding this comment.
Again, is debugging part of the scope of the quickstart?
There was a problem hiding this comment.
yes, this is very limited in its scope, thus i feel it is appropriate
| 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 |
There was a problem hiding this comment.
This section feels out of place. In the offline section, we listed environment first. Here, we list it last. Also, I don't think we should talk about using the command-line in the section about the Mbed Online Compiler.
There was a problem hiding this comment.
Im not sure I understand what you are trying to say, lets discuss in person
| 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) |
There was a problem hiding this comment.
Again, why are we linking to the APIs and then linking to a subset of the APIs? They were included in the link above.
There was a problem hiding this comment.
see previous answer
Copy edit file for active voice, branding, consistent capitalization and tense across documents and other grammar and style issues.
| | ||
| You're taken to the online IDE, and the **Import Program** dialog box opens: | ||
| If you do not have an Mbed board, go to [os.mbed.com/platforms](http://os.mbed.com/platforms), select a board and click the “Add to your Mbed Compiler” button. | ||
| <span class="images"> |
There was a problem hiding this comment.
This image is out of date. Please update it and upload it to the "images" folder at a higher level of the Handbook.
There was a problem hiding this comment.
@yennster can you please update the image?
@AnotherButler where would you like us to upload the image? should we create a img folder or is there a master image folder we should upload to?
There was a problem hiding this comment.
As mentioned previously, there's an "images" folder at a high level in our documentation where we put all images: https://github.com/ARMmbed/Handbook/tree/new_engine/docs/images
| ### Viewing Blinky | ||
| 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"> |
There was a problem hiding this comment.
This image is out of date. Please update it and upload it to the "images" folder at a higher level of the Handbook.
There was a problem hiding this comment.
@yennster can you please update the image?
@AnotherButler where would you like us to upload the image? should we create a img folder or is there a master image folder we should upload to?
There was a problem hiding this comment.
As mentioned previously, there's an "images" folder at a high level in our documentation where we put all images: https://github.com/ARMmbed/Handbook/tree/new_engine/docs/images
| Click on the "Compile" button. Your browser downloads the program as an executable file. | ||
| | ||
| Later we'll compile the code; this will take both of these parts and create a single application file from them. | ||
| <span class="images"> |
There was a problem hiding this comment.
This image is out of date. Please update it and upload it to the "images" folder at a higher level of the Handbook.
There was a problem hiding this comment.
@yennster can you please update the image?
@AnotherButler where would you like us to upload the image? should we create a img folder or is there a master image folder we should upload to?
There was a problem hiding this comment.
As mentioned previously, there's an "images" folder at a high level in our documentation where we put all images: https://github.com/ARMmbed/Handbook/tree/new_engine/docs/images
| 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 downloads a `.zip` file with the project files. | ||
| | ||
| #### Selecting a board | ||
| <span class="images"> |
There was a problem hiding this comment.
This image is out of date. Please update it and upload it to the "images" folder at a higher level of the Handbook.
There was a problem hiding this comment.
@yennster can you please update the image?
@AnotherButler where would you like us to upload the image? should we create a img folder or is there a master image folder we should upload to?
There was a problem hiding this comment.
As mentioned previously, there's an "images" folder at a high level in our documentation where we put all images: https://github.com/ARMmbed/Handbook/tree/new_engine/docs/images
There was a problem hiding this comment.
@AnotherButler @BlackstoneEngineering Sorry, I just saw this note today. Do you still need those images uploaded?
There was a problem hiding this comment.
@yennster Yes, please. If you could upload these at your convenience, that would be great. Thanks for checking.
There was a problem hiding this comment.
@AnotherButler will do later today!
Copy edit file, and add introductory sentence.
Copy edit file.
Make minor branding changes.
Update pesky incorrect capitalization I lost earlier.
| Thanks. Please be sure to upload updated images as requested. Other than that, I believe my remaining question and request (confirming that all one needs for CLI is a browser and asking for an introductory paragraph) are the ones we agreed I need to speak to product and positioning experts about. |
Delete confusing sentence.
| I don't think the quick start should have Mbed CLI (which, last we checked, can take up to two hours to install on a Mac). Don't confuse people with two options - take them straight to the IDE, which is the quickest way to get started, and leave the Mbed CLI bit for later. Make it explicitly about Mbed CLI rather than the Mbed OS quick start. |
| Thinking about this a bit, I think it makes more sense to present both Online ide and CLI options upfront. It is clearly stated that Online ide is the easiest option that "just works" whereas offline provides more flexibility but does require some effort to set up. |
| Is there a rendered version of this work? It's really hard to review the flow from the change set. |
| @senthilr I remind you of the context - this isn't going to be part of the handbook, it's going to be a one-page quick start that's way higher in the site's hierarchy than the handbook. It is not the place to get into multiple processes, especially ones that take more than five minutes. |
| @sg- You can view the rendered documents here: https://docs.internal.mbed.com/docs/master/quickstart/index.html |
| @AnotherButler Those images are uploaded 👍 |
| Can we please get this published? …On Thu, Feb 1, 2018 at 2:51 PM, Amanda Butler ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In docs/tutorials/first_app/first_program.md <#363 (comment)>: > @@ -1,14 +1,12 @@ -## Your first Arm Mbed application @yennster <https://github.com/yennster> Yes. I was waiting to write it until we knew whether we'd be including Mbed CLI, but it may not be a bad idea to start drafting something that we could use whether or not we include CLI. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#363 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AE230-QtSyrYTig63mJCT1icE701c9lLks5tQiPUgaJpZM4RFntm> . |
| I will catch up with Simon F this week |
| @iriark01 why does Simon F come into this? Sam G is the content owner and we have his approval to proceed. I would really like to get this published ASAP as it is going on 2 months delayed. |
| Amanda, you can merge this for now if you want. Simon F and I will continue off line. |
| @AnotherButler I fixed those merge conflicts! |
| @yennster Go you. Thanks so much. Merging now. |
6 participants
This is the initial draft of the mbed os quickstart. I have chosen to over write the first application tutorial as this content is made redundant by the quickstart.
Please note that this does not include the docs.json changes as I was advised by @AnotherButler to not make those changes but request them to be made on my behalf. I would like to request the section be renamed from 'Your First Application' to
Quickstart.