├── Docs ├── Extended_LED.md ├── FirstProjectmbedOS.md ├── Full_Guide │ ├── Code_Style.md │ ├── Debugging.md │ ├── I2C.md │ ├── Images │ │ ├── HAL_Tree.png │ │ ├── async.png │ │ ├── frdm_k64f_pinnout.jpg │ │ ├── mbed_OS_app.png │ │ ├── module_struct.png │ │ ├── networkstacks.png │ │ ├── pins.png │ │ ├── post_callback.png │ │ ├── post_callback_d_i.png │ │ ├── post_callback_t.png │ │ ├── post_callback_t_2.png │ │ ├── yotta_dep.png │ │ └── yotta_init.png │ ├── Interfacing.md │ ├── MINAR.md │ ├── app_on_mbed_os.md │ ├── app_on_yotta.md │ ├── contributing.md │ ├── mbed_tls.md │ ├── memory.md │ └── networking.md ├── FurtherReading.md ├── GetTheCode.md ├── GettingStartedmbedOS.md ├── Images │ ├── bb-sketch-btn.png │ ├── bb-sketch-led.png │ ├── bb01.png │ ├── bb02.png │ ├── bb03.gif │ └── bb04.png ├── about_mbed_os.md ├── docker_install.md ├── index.md └── installation.md └── mkdocs.yml /Docs/Extended_LED.md: -------------------------------------------------------------------------------- 1 | # Blinky on a breadboard 2 | 3 | We've seen how to automatically blink the built-in LED, but the great thing about dev kits is that they allow us to add new sensors and peripherals and experiment with user interactions. Let's use an external LED instead of the on-board one, then add manual control. 4 | 5 | If you skipped Blinky, please go [get the code for it](FirstProjectmbedOS.md). You'll need to modify that code to get this example working. 6 | 7 | ## The hardware 8 | 9 | Get a breadboard, a 220 ohm resistor (or something close to 220 ohm), and two wires. 10 | 11 | To know how we should connect everything together we need to take a look at the pinout of the board. Normally, this is listed on the board's page on the mbed website (for example, here is the [FRDM-K64F pinout](https://www.mbed.com/en/development/hardware/boards/nxp/frdm_k64f/)). You can also do an image search for '[board-name] pinout'. 12 | 13 | ![Finding pinouts with your favourite search engine](Images/bb01.png)Finding pinouts with your favourite search engine 14 | 15 | 16 | We need a digital pin for the LED. Since I'm using the FRDM-K64F, I selected pin PTB23/D4. 17 | 18 | ![Choosing a digital pin](Images/bb04.png) 19 | 20 | Now we're ready to set up the circuit. 21 | 22 | ![Sketch of a LED wired up on a breadboard](Images/bb-sketch-led.png)*Black wire running from GND to the short leg of the LED. Orange wire running from PTB23 through a resistor to the long leg of the LED.* 23 | 24 | ## Changing the pin association in the code 25 | 26 | Now we need to configure the LED in our [Blinky code](https://github.com/ARMmbed/example-mbedos-blinky/blob/master/source/blinky.cpp) to no longer reference `LED1`. To reference our pin we can use the name of the pin directly (`PTB23`) or we can use the standard name 'D4', which is mapped automatically to the right pin through [yotta](http://yottadocs.mbed.com/reference/config.html). The latter is prefered, as it makes it easier to port your code to other hardware. 27 | 28 | Change [the ``blinky`` function](https://github.com/ARMmbed/example-mbedos-blinky/blob/master/source/blinky.cpp) to: 29 | 30 | ```cpp 31 | static void blinky(void) { 32 | // If we use the standard name (D4), we need to prefix the pin name. 33 | // If we use PTB23, we do not need to do this. 34 | static DigitalOut led(YOTTA_CFG_HARDWARE_PINS_D4); 35 | led = !led; 36 | printf("LED = %d \r\n",led.read()); 37 | } 38 | ``` 39 | 40 | Now the LED on the breadboard blinks, rather than the LED on the board. 41 | 42 | ![LED wired up on a breadboard](Images/bb02.png) 43 | 44 | ## Adding a button 45 | 46 | Since we have the breadboard ready anyway, we can also change this program to toggle the LED when a button is being pressed, rather than every 500ms. 47 | 48 | First we need to take another digital pin (in my case PTA2/D5), and wire the button up on the breadboard. Make sure to also have a pull-down resistor to ground. 49 | 50 | ![Sketch of a button and a LED on a breadboard](Images/bb-sketch-btn.png) 51 | 52 | Now we can configure PTA2/D5 as an [`InterruptIn`](https://developer.mbed.org/handbook/InterruptIn) pin and get notified when the button gets pressed or released. Change 'source/app.cpp' to read: 53 | 54 | ```cpp 55 | #include "mbed-drivers/mbed.h" 56 | 57 | static DigitalOut led(YOTTA_CFG_HARDWARE_PINS_D4); 58 | 59 | static void led_toggle(void) { 60 | led = !led; 61 | printf("LED = %d \r\n", led.read()); 62 | } 63 | 64 | void app_start(int, char**) { 65 | static InterruptIn button(YOTTA_CFG_HARDWARE_PINS_D5); 66 | 67 | // when we press the button the circuit closes and the LED state is toggled 68 | button.rise(&led_toggle); 69 | // when we release the button the circuit opens again and the LED state is toggled again 70 | button.fall(&led_toggle); 71 | } 72 | ``` 73 | 74 | ![Button and a LED on a breadboard](https://raw.githubusercontent.com/ARMmbed/GettingStartedmbedOS/master/Docs/Images/bb03.gif) 75 | 76 | ## Making the code safe 77 | 78 | The LED state changes as it should and it might look like everything is fine, but there's actually a very important change in the code above when compared with its original version: the use of `rise` and `fall`: 79 | 80 | ```cpp 81 | button.rise(&led_toggle); 82 | button.fall(&led_toggle); 83 | ``` 84 | 85 | `rise` and `fall` set the functions that will be called when the logic level on `button` changes from 0 to 1 and 1 to 0 respectively. However, `rise` and `fall` are legacy functions from mbed Classic, so they bypass [MINAR](Full_Guide/MINAR.md) and call their arguments (`led_toggle` in this case) in an interrupt cotext. As explained in the [InterruptIn documentation](https://developer.mbed.org/handbook/InterruptIn), it is not safe to call some C library functions from an interrupt context. `printf` is one of these functions, so the code above might actually be problematic. Even if it works fine in this particular case, calling `printf` from an interrupt context should generally be avoided. Fortunately, this is one of the things that [MINAR](Full_Guide/MINAR.md) is good at: deferring code executing from interrupt context to user context. Since calling MINAR from an interrupt context is safe, all we need to do is schedule a callback from an interrupt handler. MINAR will safely execute that callback later from the user context: 86 | 87 | ```cpp 88 | #include "mbed-drivers/mbed.h" 89 | #include "minar/minar.h" 90 | #include "core-util/FunctionPointer.h" 91 | 92 | using namespace mbed::util; 93 | 94 | static DigitalOut led(YOTTA_CFG_HARDWARE_PINS_D4); 95 | 96 | static void led_toggle_user(void) { 97 | led = !led; 98 | printf("LED = %d \r\n", led.read()); 99 | } 100 | 101 | static void led_toggle_irq(void) { 102 | minar::Scheduler::postCallback(FunctionPointer0(&led_toggle_user).bind()); 103 | } 104 | 105 | void app_start(int, char**) { 106 | static InterruptIn button(YOTTA_CFG_HARDWARE_PINS_D5); 107 | 108 | // when we press the button the circuit closes and the LED state is toggled 109 | button.rise(&led_toggle_irq); 110 | // when we release the button the circuit opens again and the LED state is toggled again 111 | button.fall(&led_toggle_irq); 112 | } 113 | ``` 114 | **Tip:** You can read more [about MINAR here](Full_Guide/MINAR.md). 115 | -------------------------------------------------------------------------------- /Docs/FirstProjectmbedOS.md: -------------------------------------------------------------------------------- 1 | # Running your first mbed OS application 2 | 3 | Your first application makes the LED on your board blink, and prints some commands to the terminal. You use yotta to build your application for mbed OS. 4 | 5 | ## Using yotta as a command-line tool 6 | 7 | yotta is the build system we use for mbed OS. We'll get into the details of it later, but what you need to understand at this point is that mbed OS applications cannot be built without yotta. 8 | 9 | If you haven't already installed yotta, please follow these [installation instructions](installation.md). 10 | 11 | ## Regular method: creating a new application 12 | 13 | This method uses yotta to initialize an application and manually add our code to it. 14 | 15 | ### Step 1: create an application 16 | 17 | 1. Create an empty folder, then move into that folder: 18 | 19 | ``` 20 | $ mkdir blinky 21 | $ cd blinky 22 | ``` 23 | 24 | 1. Initialize the module with `yotta init` and fill in the details. Make sure you select **executable** as the module type: 25 | 26 | 27 | ![](Full_Guide/Images/yotta_init.png) 28 | 29 | You should now have several folders and files in the directory: 30 | 31 | ``` 32 | $ ls 33 | blinky module.json source test 34 | ``` 35 | 36 | * The `module.json` file contains all the settings for your application; everything you just entered can be found in that file, so if you want to edit it later, for example to add a repository URL, that's not a problem. 37 | 38 | * The `/source` directory contains all the source files. 39 | 40 | * The `/test` directory contains all tests you'll write to [test your module](https://github.com/ARMmbed/GettingStartedmbedOS/blob/master/Docs/docs.yottabuild.org/tutorial/testing.html). 41 | 42 | * The `/blinky` directory is where header files for your application will be created. 43 | 44 | **Tip:** if you want to learn about other module types, [start here](http://docs.yottabuild.org/). 45 | 46 | ### Step 2: select a target board 47 | 48 | yotta can build the [same code for multiple targets](Full_Guide/app_on_yotta/#yotta-targets); it therefore needs to be told which target every build is for. So now that you have created a basic application, you need to set the target. 49 | 50 | For a full list of available targets run the following `search` command: 51 | 52 | ``` 53 | $ yotta search --limit 1000 target 54 | frdm-k64f-gcc 0.0.21: Official mbed build target 55 | for the mbed frdm-k64f development board. 56 | st-nucleo-f401re-gcc 0.1.0: Official mbed build target 57 | for the mbed st-nucleo-f401re development board. 58 | frdm-k64f-armcc 0.0.13: Official mbed build target 59 | for the mbed frdm-k64f development board, using the armcc toolchain. 60 | ... 61 | ``` 62 | 63 | In this example you are going to use the Freescale FRDM-K64F board configured for building with gcc, so you use `target frdm-k64f-gcc`. 64 | 65 | ``` 66 | $ yotta target frdm-k64f-gcc 67 | ``` 68 | 69 | **Note:** The first time you access the yotta Registry, you need to log into your mbed user account. 70 | 71 | To check that the target has been set correctly run the target command without parameters. It shows what yotta is currently targeting for its builds: 72 | 73 | ``` 74 | $ yotta target 75 | frdm-k64f-gcc,* 76 | ``` 77 | 78 | *The information for this target has been downloaded to a directory named `/yotta_targets`. Do not edit or modify files here because they can be modified without your knowledge.* 79 | 80 | ### Step 3: install dependencies 81 | 82 | Now you need to install the dependencies. In this application, you have `mbed-drivers` as your dependency: 83 | 84 | ``` 85 | $ yotta install mbed-drivers 86 | info: ... messages about stuff being downloaded ... 87 | ``` 88 | 89 | You could at this point add other yotta modules. Check out the `yotta search` command above to search for other available modules. 90 | 91 | yotta downloads and installs the modules to a directory named `/yotta_modules`. Do not edit or modify files here as they can be modified without your knowing. 92 | 93 | ### Step 4: add source files 94 | 95 | Now that you have an application and its dependencies, you need source code to make the module useful. 96 | 97 | In the `/source` folder, create a file called `app.cpp` with the following contents: 98 | 99 | ```c++ 100 | #include "mbed-drivers/mbed.h" 101 | 102 | static void blinky(void) { 103 | static DigitalOut led(LED1); 104 | led = !led; 105 | printf("LED = %d \r\n",led.read()); 106 | } 107 | 108 | void app_start(int, char**) { 109 | minar::Scheduler::postCallback(blinky).period(minar::milliseconds(500)); 110 | } 111 | ``` 112 | 113 | This application causes LED1 on the board to flash and prints the status of LED1 to the terminal. 114 | 115 | **Tip:** When setting up your terminal, note that the default terminal speed is 9600 baud at 8-N-1. 116 | 117 | ### Step 5: build 118 | 119 | To build the application: 120 | 121 | 1. Run the `yotta build` command in the top level directory: 122 | 123 | ``` 124 | $ yt build 125 | info: generate for target: frdm-k64f-gcc 0.0.21 126 | at ~\blinky\yotta_targets\frdm-k64f-gcc 127 | GCC version is: 4.9.3 128 | -- The ASM compiler identification is GNU 129 | -- Found assembler: GNU Tools ARM Embedded/4.9 2014q4/bin/arm-none-eabi-gcc.exe 130 | -- Configuring done 131 | -- Generating done 132 | -- Build files have been written to: ~/blinky/build/frdm-k64f-gcc 133 | [135/135] Linking CXX executable source/blinky 134 | ``` 135 | 136 | 1. yotta compiles the binary to the `/build` folder. 137 | 138 | ### Step 6: run the application on your board 139 | 140 | 1. Connect your board to your computer over USB. It should appear as removable storage. 141 | 142 | 1. Copy the binary `/build/frdm-k64f-gcc/source/blinky.bin` to your mbed board and see the LED blink. 143 | 144 | 1. If you hook up a terminal to the board, you can see the output being printed. It should look like this:. 145 | 146 | ``` 147 | LED = 1 148 | LED = 0 149 | LED = 1 150 | LED = 0 151 | ... 152 | ``` 153 | 154 | ## Alternative method: cloning an existing application 155 | 156 | Instead of setting up your own application from scratch, you could clone an existing one and modify it. We have published the above [blinky example application](https://github.com/armmbed/example-mbedos-blinky) on GitHub so you can clone the repo and build it. 157 | 158 | ### Step 1: clone the repo 159 | 160 | 161 | ``` 162 | $ git clone https://github.com/ARMmbed/example-mbedos-blinky.git 163 | $ cd example-mbedos-blinky 164 | ``` 165 | 166 | **Note:** This repo includes ``mbed-drivers`` as a dependency, so there is no need to manually install it as you did in the previous method (yotta will install it when you build the application). 167 | 168 | ### Step 2: select a target platform 169 | 170 | ``` 171 | $ yotta target frdm-k64f-gcc 172 | ``` 173 | 174 | ### Step 3: build the application to your target 175 | 176 | ``` 177 | $ yotta build 178 | ... bunch of build messages ... 179 | [135/135] Linking CXX executable source/example-mbedos-blinky 180 | ``` 181 | 182 | As in the previous method, the compiled binary is at `/build/frdm-k64f-gcc/source/example-mbedos-blinky.bin`. You can copy it to your board to run it, and hook your board up to a terminal to see the output, as explained in step 6 above. 183 | -------------------------------------------------------------------------------- /Docs/Full_Guide/Code_Style.md: -------------------------------------------------------------------------------- 1 | # Code contributions: GitHub pull requests and code style guide 2 | 3 | The mbed OS code base is hosted on GitHub, and you can submit new features or bug fixes. Please follow the [guidelines for GitHub pull requests](#guidelines-for-github-pull-requests) and the [coding style guide](#coding-style) in your submissions. 4 | 5 | **Tip:** Please also read the section [Creating and publishing your own libraries and contributing to mbed OS](contributing.md) for a review of the process and legal requirements. 6 | 7 | ## Guidelines for GitHub pull requests 8 | 9 | Pull requests on GitHub have to meet a number of requirements in order to keep the code and commit history clean: 10 | 11 | * Commits should always contain a proper description of their content. Start with a concise and sensible one-line description, then elaborate on reasoning of the choices taken, descriptions for reviewers and other information that might otherwise  be lost. 12 | * Commits should always be written to allow publication, so they can never contain confidential information, reference private documents, links to intranet locations, or rude language. 13 | * Each commit should be the minimum self-contained commit for a change. A commit should always result in a new state that is again in a compilable state. Large changes should (if possible) be split up into logical smaller commits that help reviewers follow the reasoning behind the full change. 14 | * Commits should follow [Chris Beam’s seven rules of great commit messages](http://chris.beams.io/posts/git-commit#seven-rules): 15 | 1. Separate subject from body with a blank line. 16 | 1. Limit the subject line to 72 characters (note that this is a deviation from Beam's standard). 17 | 1. Capitalize the subject line. 18 | 1. Do not end the subject line with a period. 19 | 1. Use the imperative mood in the subject line. 20 | 1. Wrap the body at 72 characters. 21 | 1. Use the body to explain _what_ and _why_ vs _how_. 22 | * Since we use GitHub and explicit CLAs, special commit tags that other projects might use, like “Reviewed-by”, or “Signed-off-by”, are redundant and should be omitted. GitHub keeps track of who reviewed what and when, and our stack of signed CLAs shows us who has agreed to our development contribution agreement. 23 | * Prefixing your commit message with a domain is acceptable and recommended where it makes sense to do so. However, prefixing one's domain with the name of the repo is not useful. For example, making a commit entitled "mbed-drivers: Fix doppelwidget frobulation" to the mbed-drivers repo would not be acceptable, as it is already understood that the commit applies to "mbed-drivers". Renaming the commit to "doppelwidget: Fix frobulation" would be better, if we presume that "doppelwidget" is a meaningful domain for changes, as it communicates that the change applies to the doppelwidget area of mbed-drivers. 24 | 25 | ## Code acceptance 26 | 27 | [After the CLA](contributing.md) is in place and the code has gone through automated testing, developers will take a look and comment on the pull request. If all is well and acceptable, your code will be ready for merging into the central development branch. 28 | 29 | ## Coding style 30 | 31 | Whether you're writing new code or fixing bugs in existing code, please follow the mbed OS coding style. 32 | 33 | mbed OS follows the [K&R style](https://en.wikipedia.org/wiki/Indent_style#K.26R_style), with at least two exceptions (which can be found in the list below the code sample). 34 | 35 | #### Code sample 36 | 37 | ```c 38 | static const PinMap PinMap_ADC[] = { 39 | {PTC2, ADC0_SE4b, 0}, 40 | {NC , NC , 0} 41 | }; 42 | 43 | uint32_t adc_function(analogin_t *obj, uint32_t options) 44 | { 45 | uint32_t instance = obj->adc >> ADC_INSTANCE_SHIFT; 46 | switch (options) { 47 | case 1: 48 | timeout = 6; 49 | break; 50 | default: 51 | timeout = 10; 52 | break; 53 | } 54 | 55 | while (!adc_hal_is_conversion_completed(instance, 0)) { 56 | if (timeout == 0) { 57 | break; 58 | } else { 59 | timeout--; 60 | } 61 | } 62 | 63 | if (obj->adc == ADC_CHANNEL0) { 64 | adc_measure_channel(instance); 65 | adc_stop_channel(instance); 66 | } else { 67 | error("channel not available"); 68 | } 69 | 70 | #if DEBUG 71 | for (uint32_t i = 0; i < 10; i++) { 72 | printf("Loop : %d", i); 73 | } 74 | #endif 75 | return adc_hal_get_conversion_value(instance, 0); 76 | } 77 | ``` 78 | #### Rules 79 | 80 | * Indentation - four spaces. Please do not use tabs. 81 | 82 | * Braces - K&R style 83 | 84 | * One true brace style (1TBS) - use braces for statements of type `if`, `else`, `while` and `for` (exception [from K&R](http://en.wikipedia.org/wiki/Indent_style#Variant:_1TBS)). 85 | 86 | * One line per statement 87 | 88 | * Preprocessor macro starts at the beginning of a new line, the code inside is indented according to the code above it. 89 | 90 | * Cases within `switch` are indented (exception from K&R). 91 | 92 | * Space after statements of type `if`, `while`, `for`, `switch`. The same applies to binary operators (like, `+` and `*`) and the ternary operator (`?` and `:`). 93 | 94 | * Each line preferably has at most 120 characters. 95 | 96 | * Comments should use proper spelling and grammar. 97 | 98 | * For pointers, '*' is adjacent to a name (analogin_t *obj). 99 | 100 | * Don't leave trailing spaces at the end of lines. 101 | 102 | * Empty lines should have no trailing spaces. 103 | 104 | * Unix line endings are default option for files. 105 | 106 | * Use capital letters for macros. 107 | 108 | * A file should have an empty line at the end. 109 | 110 | #### Naming conventions 111 | 112 | __Classes__ 113 | 114 | * Begins with a capital letter, and each word in it also begins with a capital letter (AnalogIn, BusInOut). 115 | 116 | * Methods contain small letters, with words separated by underscore. 117 | 118 | * Private members starts with an underscore: ``__User defined types (typedef)))``. 119 | 120 | * Structures - suffix _t - to denote it is a user defined type. 121 | 122 | * Enumeration - the type name and values name - same naming convention as classes (for example MyNewEnum). 123 | 124 | __Functions__ 125 | 126 | * Contain lower case letters (as methods within classes) 127 | 128 | * Words separated by underscore (wait_ms, read_u16) 129 | 130 | As an example: 131 | 132 | ```c 133 | #define ADC_INSTANCE_SHIFT 8
 134 | 135 | class AnalogIn { 136 | public: 137 | /** Create an AnalogIn connected to the specified pin. 138 | * 139 | * @param pin AnalogIn pin to connect to 140 | * @param name (optional) A string to identify the object 141 | */ 142 | AnalogIn(PinName pin) 143 | { 144 | analogin_init(&_adc, pin); 145 | } 146 | 147 | /** Read the input voltage, represented as a float in the range [0.0, 1.0]. 148 | * 149 | * @returns 150 | * A floating-point value representing the current input voltage, measured as a percentage 151 | */ 152 | uint32_t read() 153 | { 154 | return analogin_read(&_adc, operation); 155 | } 156 | protected: 157 | analogin_t _adc; 158 | }; 159 | 160 | typedef enum { 161 | ADC0_SE0 = (0 << ADC_INSTANCE_SHIFT) | 0, 162 | } ADCName; 163 | 164 | struct analogin_s { 165 | ADCName adc; 166 | }; 167 | 168 | typedef struct analogin_s analogin_t; 169 | ``` 170 | 171 | #### Doxygen documentation 172 | 173 | All functions and methods should contain documentation using Doxgyen. 174 | 175 | **Tip:** You can publish your documentation on docs.mbed.com. See our [publishing guide](https://docs.mbed.com/docs/writing-and-publishing-guides/en/latest/publishing_guide/) for more details. 176 | 177 | You can use [Artistic Style (AStyle)](http://sourceforge.net/projects/astyle/files/) to format your code. Use the command-line switch to select the correct style and point to the file you want to edit: 178 | 179 | ``` 180 | astyle.exe --style=kr --indent=spaces=4 --indents-switches $(full_path_to_file) 181 | ``` 182 | 183 | -------------------------------------------------------------------------------- /Docs/Full_Guide/Debugging.md: -------------------------------------------------------------------------------- 1 | # Debugging in mbed OS 2 | 3 | The [`example-mbedos-blinky`](../FirstProjectmbedOS.md) application you've used in this guide is simple and easy to understand, so it should work as expected right away. More complex applications might not work as expected. In that case, a debugger is a very useful tool. There are two main ways to debug mbed OS applications at the moment, depending on how they were compiled. 4 | 5 | ## Debugging applications compiled with ARMCC 6 | 7 | To debug applications compiled with ARMCC: 8 | 9 | 1. Install [Keil MDK](https://www.keil.com/download/product/). 10 | 11 | 1. Use the `yotta debug` command. 12 | 13 | For example, If you build `example-mbedos-blinky` for the target `frdm-k64f-armcc` (instead of `frdm-k64f-gcc`), you can debug it by running `yotta debug example-mbedos-blinky`. This automatically opens the uVision IDE, with your program ready for debugging. 14 | 15 | ## Debugging applications compiled with GCC 16 | 17 | The best way to debug applications compiled with GCC is to use the `gdb` debugger. You need: 18 | 19 | - `arm-none-eabi-gdb`, which is installed as part of the [GCC ARM Embedded](https://launchpad.net/gcc-arm-embedded) installation procedure. 20 | - `pyocd-gdbserver`, which is installed as part of the yotta installation procedure. 21 | 22 | For example, to debug `example-mbedos-blinky`: 23 | 24 | ``` 25 | $ yt debug example-mbedos-blinky 26 | info: found example-mbedos-blinky at source/example-mbedos-blinky 27 | info: starting PyOCD gdbserver... 28 | info: new board id detected: 02400201C37A4E793E84B3C1 29 | info: board allows 5 concurrent packets 30 | info: DAP SWD MODE initialised 31 | info: IDCODE: 0x2BA01477 32 | info: K64F not in secure state 33 | info: 6 hardware breakpoints, 4 literal comparators 34 | info: CPU core is Cortex-M4 35 | info: FPU present 36 | info: 4 hardware watchpoints 37 | info: Telnet: server started on port 4444 38 | info: GDB server started at port:3333 39 | GNU gdb (GNU Tools for ARM Embedded Processors) 7.6.0.20140731-cvs 40 | Copyright (C) 2013 Free Software Foundation, Inc. 41 | License GPLv3+: GNU GPL version 3 or later 42 | This is free software: you are free to change and redistribute it. 43 | There is NO WARRANTY, to the extent permitted by law. Type "show copying" 44 | and "show warranty" for details. 45 | This GDB was configured as "--host=x86_64-apple-darwin10 --target=arm-none-eabi". 46 | For bug reporting instructions, please see: 47 | ... 48 | Reading symbols 49 | from 50 | /examples/example-mbedos-blinky/build/frdm-k64f-gcc/source/example-mbedos-blinky 51 | ...done. 52 | info: One client connected! 53 | (gdb) 54 | ``` 55 | -------------------------------------------------------------------------------- /Docs/Full_Guide/I2C.md: -------------------------------------------------------------------------------- 1 | ##Experimental version 2 asynchronous I2C API 2 | 3 | 4 | !{https://raw.githubusercontent.com/ARMmbed/mbed-drivers/master/docs/I2C.md} 5 | -------------------------------------------------------------------------------- /Docs/Full_Guide/Images/HAL_Tree.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ARMmbed/GettingStartedmbedOS/12a5a0d5c1b8afadbe8e21be5906470ad7810bd3/Docs/Full_Guide/Images/HAL_Tree.png -------------------------------------------------------------------------------- /Docs/Full_Guide/Images/async.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ARMmbed/GettingStartedmbedOS/12a5a0d5c1b8afadbe8e21be5906470ad7810bd3/Docs/Full_Guide/Images/async.png -------------------------------------------------------------------------------- /Docs/Full_Guide/Images/frdm_k64f_pinnout.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ARMmbed/GettingStartedmbedOS/12a5a0d5c1b8afadbe8e21be5906470ad7810bd3/Docs/Full_Guide/Images/frdm_k64f_pinnout.jpg -------------------------------------------------------------------------------- /Docs/Full_Guide/Images/mbed_OS_app.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ARMmbed/GettingStartedmbedOS/12a5a0d5c1b8afadbe8e21be5906470ad7810bd3/Docs/Full_Guide/Images/mbed_OS_app.png -------------------------------------------------------------------------------- /Docs/Full_Guide/Images/module_struct.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ARMmbed/GettingStartedmbedOS/12a5a0d5c1b8afadbe8e21be5906470ad7810bd3/Docs/Full_Guide/Images/module_struct.png -------------------------------------------------------------------------------- /Docs/Full_Guide/Images/networkstacks.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ARMmbed/GettingStartedmbedOS/12a5a0d5c1b8afadbe8e21be5906470ad7810bd3/Docs/Full_Guide/Images/networkstacks.png -------------------------------------------------------------------------------- /Docs/Full_Guide/Images/pins.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ARMmbed/GettingStartedmbedOS/12a5a0d5c1b8afadbe8e21be5906470ad7810bd3/Docs/Full_Guide/Images/pins.png -------------------------------------------------------------------------------- /Docs/Full_Guide/Images/post_callback.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ARMmbed/GettingStartedmbedOS/12a5a0d5c1b8afadbe8e21be5906470ad7810bd3/Docs/Full_Guide/Images/post_callback.png -------------------------------------------------------------------------------- /Docs/Full_Guide/Images/post_callback_d_i.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ARMmbed/GettingStartedmbedOS/12a5a0d5c1b8afadbe8e21be5906470ad7810bd3/Docs/Full_Guide/Images/post_callback_d_i.png -------------------------------------------------------------------------------- /Docs/Full_Guide/Images/post_callback_t.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ARMmbed/GettingStartedmbedOS/12a5a0d5c1b8afadbe8e21be5906470ad7810bd3/Docs/Full_Guide/Images/post_callback_t.png -------------------------------------------------------------------------------- /Docs/Full_Guide/Images/post_callback_t_2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ARMmbed/GettingStartedmbedOS/12a5a0d5c1b8afadbe8e21be5906470ad7810bd3/Docs/Full_Guide/Images/post_callback_t_2.png -------------------------------------------------------------------------------- /Docs/Full_Guide/Images/yotta_dep.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ARMmbed/GettingStartedmbedOS/12a5a0d5c1b8afadbe8e21be5906470ad7810bd3/Docs/Full_Guide/Images/yotta_dep.png -------------------------------------------------------------------------------- /Docs/Full_Guide/Images/yotta_init.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ARMmbed/GettingStartedmbedOS/12a5a0d5c1b8afadbe8e21be5906470ad7810bd3/Docs/Full_Guide/Images/yotta_init.png -------------------------------------------------------------------------------- /Docs/Full_Guide/Interfacing.md: -------------------------------------------------------------------------------- 1 | # Interfacing to hardware 2 | 3 | mbed OS offers the APIs that interface directly with the hardware. While each API's hardware-facing side can delve into board-specific details, the side facing you - and your application - remains constant. That allows you to write a single piece of code and run it on all supported boards. 4 | 5 | Hardware interfaces are handled by the mbed Hardware Abstraction Layer (HAL). The mbed HAL is an [interface](https://github.com/ARMmbed/mbed-hal/tree/master/mbed-hal) that has various generic manufacturer implementations, such as [Nordic](https://github.com/ARMmbed/mbed-hal-nordic) and [Freescale](https://github.com/ARMmbed/mbed-hal-freescale), as well as various board implementations. 6 | 7 | 8 | ![](../Full_Guide/Images/HAL_Tree.png) 9 | 10 | When you delve into board-specific implementations you get the mapping that HAL requires. The following example focuses on the FRDM-K64F implementation, which is the same board we use in this document's code examples. 11 | 12 | ## yotta and HAL selection 13 | 14 | When you tell yotta which board you're building for (your target), yotta knows which modules that board requires. So when you say ``yotta target frdm-k64g-gcc`` and then ``yotta build``, the build is performed with your board's specific HAL. 15 | 16 | **Tip:** to learn about yotta targets, read [the chapter about mbed OS applications with yotta](app_on_yotta.md). 17 | 18 | We can see this when we run ``yotta ls`` in the Blinky directory we built earlier ([please refer to the quick guide if you haven't built Blinky yet](../FirstProjectmbedOS.md)): 19 | 20 | ``` 21 | user$ cd blinky 22 | user$ yotta ls 23 | 24 | my_blinky 0.0.1 25 | ┗─ mbed-drivers 0.8.3 26 | ┣─ mbed-hal 0.6.4 yotta_modules/mbed-hal 27 | ┃ ┗─ mbed-hal-freescale 0.5.2 yotta_modules/mbed-hal-freescale 28 | ┃ ┗─ mbed-hal-ksdk-mcu 0.5.4 yotta_modules/mbed-hal-ksdk-mcu 29 | ┃ ┣─ uvisor-lib 0.7.25 yotta_modules/uvisor-lib 30 | ┃ ┗─ mbed-hal-k64f 0.3.5 yotta_modules/mbed-hal-k64f 31 | ┃ ┗─ mbed-hal-frdm-k64f 0.4.4 yotta_modules/mbed-hal-frdm-k64f 32 | ┣─ cmsis-core 0.2.7 yotta_modules/cmsis-core 33 | ┃ ┗─ cmsis-core-freescale 0.1.4 yotta_modules/cmsis-core-freescale 34 | ┃ ┗─ cmsis-core-k64f 0.1.5 yotta_modules/cmsis-core-k64f 35 | ┣─ ualloc 0.1.0 yotta_modules/ualloc 36 | ┃ ┗─ dlmalloc 0.0.6 yotta_modules/dlmalloc 37 | ┣─ minar 0.7.1 yotta_modules/minar 38 | ┃ ┗─ minar-platform 0.3.4 yotta_modules/minar-platform 39 | ┃ ┗─ minar-platform-mbed 0.1.5 yotta_modules/minar-platform-mbed 40 | ┣─ core-util 0.1.2 yotta_modules/core-util 41 | ┗─ compiler-polyfill 1.0.4 yotta_modules/compiler-polyfill 42 | ``` 43 | Focusing on HAL, we can see that the board-specific implementation is actually multilayered: some is implemented for the manufacturer, in our case Freescale; some for the MCU, the K64F; and finally the specific combination for K64F and a Freescale board - the FRDM-K64F. 44 | 45 | We'll see an implementation example in the next section, after we introduce our first hardware interface: GPIO. 46 | 47 | ## GPIO 48 | 49 | General-purpose input/output (GPIO) is handled twice: in ``mbed-drivers``, to interface with your code; and in HAL, to interface with the board. There is a general GPIO header, but mbed-drivers and HAL include headers for different input and output types, and HAL further includes pin names, peripheral names and so on. 50 | 51 | You can use the GPIO related APIs for digital input and output. You can also get a notification (an interrupt) when the logic value on a GPIO pin changes from 0 to 1 or from 1 to 0. 52 | 53 | ### HAL implementation example - from the APIs to the hardware 54 | 55 | This example focuses on the LEDs on our boards, but it introduces general principles and file structures that apply to all GPIO functionalities. 56 | 57 | #### Mapping the user-facing API to pinouts 58 | 59 | To support board-agnostic programming, the mapping of a functionality to a pin is handled by board-specific HAL implementations. Let's look at how our sample application, Blinky, uses a LED on the board: 60 | 61 | ``` 62 | static DigitalOut led(LED1); 63 | ``` 64 | 65 | The key here is the use of ``DigitalOut`` and ``LED1``. 66 | 67 | ``DigitalOut.h`` is a header in ``mbed-drivers``. The class ``DigitalOut`` in that header creates a digital output connected to a pin specified in the code. 68 | 69 | Of course, we don't want you to have to specify the exact pin every time you write an application, as that will change on every board. So you only specify a generic LED1. ``DigitalOut`` then follows the ``mbed-drivers`` code (and its includes) to discover which pin LED1 is on the current board. 70 | 71 | ``DigitalOut.h`` #includes ``platform.h``, which #includes ``PinNames.h``, which is in turn the header that maps the board's pins to our generic names. It is part of HAL, and is therefore board-specific. In our example, Blinky, we can find it in the ``yotta_module`` directory under the target name: ``/blinky/yotta_modules/mbed-hal-frdm-k64f/mbed-hal-frdm-k64f/``. 72 | 73 | 74 | ![](../Full_Guide/Images/pins.png) 75 | 76 | Let's look at how the LEDs are mapped in ``PinNames.h`` for the FRDM-K64F: 77 | 78 | ``` 79 | LED_RED = PTB22, 80 | LED_GREEN = PTE26, 81 | LED_BLUE = PTB21, 82 | 83 | // mbed original LED naming 84 | LED1 = LED_RED, 85 | LED2 = LED_GREEN, 86 | LED3 = LED_BLUE, 87 | LED4 = LED_RED, 88 | ``` 89 | 90 | LED1 is mapped to LED_RED above it. LED_RED is mapped to PTB22. If we look further up the code, we can see the PTB and PTE definitions of all three LED colours: 91 | 92 | ``` 93 | PTB22 = (1 << GPIO_PORT_SHIFT | 22), 94 | PTE26 = (4 << GPIO_PORT_SHIFT | 26), 95 | PTB21 = (1 << GPIO_PORT_SHIFT | 21), 96 | ``` 97 | 98 | The numbers PTB22, PTE26 and PTB21 are taken directly from the board's pinout: 99 | 100 | 101 | ![](../Full_Guide/Images/frdm_k64f_pinnout.jpg) 102 | 103 | This brings us all the way from a generic LED1 call in your code to a board-specific pin use. 104 | 105 | ## Further reading 106 | 107 | You might be interested in the Doxygen for [mbed-drivers](https://docs.mbed.com/docs/mbed-drivers-api/en/latest/api/index.html) and [mbed-hal](https://docs.mbed.com/docs/mbed-hal-api/en/latest/api/index.html). 108 | -------------------------------------------------------------------------------- /Docs/Full_Guide/MINAR.md: -------------------------------------------------------------------------------- 1 | # Introduction to using MINAR 2 | 3 | MINAR is a component in mbed OS for scheduling code to run later, either after a timeout or periodically. The act of scheduling code to be run later is called **posting** a callback. 4 | 5 | Typically on embedded systems, you might use interrupts and timers to do this, but then your code runs in interrupt context and tasks are not serialised, adding complexities around locking and exclusion. Using MINAR, code runs in thread mode: 6 | 7 | * Cooperatively multi-tasking, MINAR is not an RTOS. 8 | * Tasks don’t interrupt each other. 9 | * Tasks run to completion. 10 | * Tasks can be posted from interrupt handlers and other tasks. 11 | 12 | 13 | The starting point for scheduling code to run later is the `postCallback` function 14 | ```c 15 | minar::Scheduler::postCallback(callbackTask); 16 | ``` 17 | 18 | ## Run code some fixed time later 19 | 20 | The following code example runs a function five seconds after initializing: 21 | 22 | ```c 23 | #include "mbed-drivers/mbed.h" 24 | 25 | 26 | static void blinky(void) { 27 | printf("5 second later!"); 28 | } 29 | 30 | void app_start(int, char**){ 31 | printf("Hi"); 32 | 33 | // Run a task in 5 seconds 34 | minar::Scheduler::postCallback(blinky).delay(minar::milliseconds(5000)); 35 | } 36 | ``` 37 | Tolerance is how sensitive your task is to being run at the exact scheduled time. MINAR will decide when to run a task (the current workload permitting) based on the scheduled time plus/minus the tolerance. By default the tolerance is 50ms: 38 | 39 | ```c 40 | minar::Scheduler::postCallback(blinky) 41 | .delay(minar::milliseconds(5000) // the postCallback method returns an object that lets us set more parameters 42 | .tolerance(minar::milliseconds(100)); // so now we can also set the tolerance 43 | ``` 44 | 45 | ## Run code periodically 46 | 47 | The following example, which is the same as the [mbed OS Blinky example](https://github.com/ARMmbed/example-mbedos-blinky), uses `minar` to run a callback periodically: 48 | 49 | ```c 50 | #include "mbed-drivers/mbed.h" 51 | 52 | // If we use the Scheduler class we simplify our code later on 53 | using minar::Scheduler; 54 | 55 | DigitalOut led(LED1); 56 | 57 | static void blinky(void) { 58 | led = !led; 59 | } 60 | 61 | void app_start(int, char**){ 62 | 63 | // we don't need minar:: here because of the 'using' line above' 64 | Scheduler::postCallback(blinky).period(minar::milliseconds(500)); 65 | 66 | } 67 | 68 | ``` 69 | 70 | ## Perform a task when a button is pressed 71 | 72 | This example uses the InterruptIn class from mbed, but defers all the work to MINAR in thread mode: 73 | 74 | ```c 75 | #include "mbed-drivers/mbed.h" 76 | 77 | InterruptIn button(BUTTON1); 78 | DigitalOut led(LED1); 79 | 80 | // If we use the Schedur class from the minar namespace we simplify our code later on 81 | using minar::Scheduler; 82 | 83 | void buttonTask() { 84 | printf("Hello mbed!"); 85 | led = !led; 86 | } 87 | 88 | void buttonISR() { 89 | Scheduler::postCallback(buttonTask); 90 | } 91 | 92 | void app_start(int, char *[]) { 93 | button.fall(buttonISR); 94 | } 95 | ``` 96 | 97 | ## Cancel a callback 98 | 99 | In order to cancel a callback that we've previously scheduled, we need a handle to it. We can do this by calling the getHandle() method on the object returned by postCallback. 100 | 101 | ```C++ 102 | #include "mbed-drivers/mbed.h" 103 | 104 | using minar::Scheduler; 105 | 106 | InterruptIn button(p17); 107 | DigitalOut led(p22); 108 | 109 | static minar::callback_handle_t handle = 0; 110 | 111 | static void blinky(void) { 112 | led = !led; 113 | } 114 | 115 | void buttonTask() { 116 | Scheduler::cancelCallback(handle); 117 | handle = 0; 118 | } 119 | 120 | void buttonISR() { 121 | Scheduler::postCallback(buttonTask); 122 | } 123 | 124 | void app_start(int, char**){ 125 | button.fall(buttonISR); 126 | handle = Scheduler::postCallback(blinky) 127 | .period(minar::milliseconds(500)) 128 | .getHandle(); 129 | } 130 | ``` 131 | 132 | 133 | The following images show the relationship between MINAR event attributes and the execution order of callbacks: 134 | 135 | * Compare tasks that aren't posted by an interrupt with tasks that are posted by an interrupt (note that the system sleeps while waiting for the IRQ): 136 | 137 | ![Interrupt-based tasks](../Full_Guide/Images/post_callback.png) 138 | 139 | * Tasks with delays, and a single task with intervals: 140 | 141 | ![These tasks have delay or interval parameters](../Full_Guide/Images/post_callback_d_i.png) 142 | 143 | * You can use tolerance to optimize MINAR's scheduling, because a task with low tolerance will push ahead of tasks with higher tolerance. Tasks are ordered in the queue by the last possible time to run them. Task 3 runs before Task 2, because Task 3 has no tolerance - its last possible executable time is earlier than Task 2's last possible executable time: 144 | 145 | ![Task 2 is executed only after Task 3](../Full_Guide/Images/post_callback_t_2.png) 146 | 147 | * Tolerance can be used to prevent the MCU from going to sleep, but not to wake it up. Task 2 is performed right after Task 1, because the MCU is already running and Task 2's tolerance allows it to run this early. But Task 3 happens after a sleep (its scheduled time), because its tolerance isn't big enough to push it to the end of Task 2, and so the MCU goes to sleep - and will not wake up to run something earlier than its scheduled execution time: 148 | 149 | ![Two of these tasks have a tolerance, giving MINAR some execution freedom](../Full_Guide/Images/post_callback_t.png) 150 | -------------------------------------------------------------------------------- /Docs/Full_Guide/app_on_mbed_os.md: -------------------------------------------------------------------------------- 1 | 2 | # Writing applications for mbed OS 3 | 4 | This section shows the general structure of an application running on mbed OS, and discusses best practices for coding (coming soon). 5 | 6 | **Tip:** You'll be using Blinky, the same application you used earlier to learn about yotta and the project build process. You should already have Blinky built. If you don't, please take a look at the [quick guide](https://docs.mbed.com/docs/getting-started-mbed-os/en/latest/FirstProjectmbedOS/) and follow the instructions there. 7 | 8 | ## Blinky's code 9 | 10 | Blinky's code is quite short, but it's enough to show a few general mbed OS application concepts: 11 | 12 | ```c++ 13 | #include "mbed-drivers/mbed.h" 14 | 15 | static void blinky(void) { 16 | static DigitalOut led(LED1); 17 | led = !led; 18 | printf("LED = %d \r\n",led.read()); 19 | } 20 | 21 | void app_start(int, char**) { 22 | minar::Scheduler::postCallback(blinky).period(minar::milliseconds(500)); 23 | } 24 | ``` 25 | ## Including headers and libraries in your application 26 | 27 | All of the features reviewed in the guide - MINAR, memory management, security and so on - are available for all hardware unless explicitly documented otherwise. Some are available through mbed OS, some through additional functionality. For either case, your application code must explicitly include the sources of this functionality. 28 | 29 | You can include headers and libraries in your application by using the standard C++ ``#include`` directive. 30 | 31 | Note that including requires the full path to the file: 32 | 33 | ```c++ 34 | #include "mbed-drivers/mbed.h" 35 | ``` 36 | 37 | **Note:** There are limitations on the path and file names. For more information about this, please see the [yotta documentation](http://yottadocs.mbed.com/tutorial/tutorial.html). 38 | 39 | Please remember that for the compilation to work correctly, yotta has to know where the included file comes from. That requires listing dependencies in the ``module.json`` file, as [explained in the yotta chapter](app_on_yotta/#installing-dependencies). In this example, ``mbed.h`` is part of ``mbed-drivers``, which you installed when you built your code. 40 | 41 | ### Including mbed OS functionality 42 | 43 | You must explicitly include ``mbed.h``; the rest of the mbed OS code base is then included either by ``mbed.h`` itself or by one of the files it includes. 44 | 45 | ### Including other functionality 46 | 47 | Including functionality that is not part of the mbed OS base code, such as certain connectivity features, requires more complicated inclusion lists, although ideally you should be able to include only the header file for each library you need. 48 | 49 | If you're not sure whether or not you need to explicitly include something in your application, ask for advice [on the forums](https://forums.mbed.com). 50 | 51 | ## app_start() - starting the application 52 | 53 | To start an application in mbed OS, you need an ``app_start()`` function, replacing the standard ``main()`` of other CPP programs: 54 | 55 | 56 | ```c++ 57 | void app_start(int, char**) { 58 | 59 | } 60 | ``` 61 | ``app_start()`` should be in a file called ``main.cpp``, and must be void. 62 | 63 | ### MINAR 64 | 65 | mbed OS starts MINAR implicitly; you only need to call it explicitly if you want to pass to it a particular function that will be executed later (using ``postCallback``). 66 | 67 | **Note:** See the [MINAR chapter](MINAR.md) for more information. 68 | 69 | ## Debugging and testing your application 70 | 71 | Debugging and testing are subjects worthy of their own guides. Until we have those written, please see: 72 | 73 | * [The current debugging articles](https://docs.mbed.com/docs/debugging-on-mbed/en/latest/). Note that they currently focus on mbed Classic, but many of the ideas they present are applicable to mbed OS. 74 | 75 | * The testing suite, Greentea. It is currently documented only in its [GitHub repositories](https://github.com/ARMmbed/greentea). We're working on a new guide for it. 76 | 77 | ## Flashing an application to the board 78 | 79 | mbed OS applications are binary files (or, for certain boards, HEX). They're built locally (in your computer's project directory) and must be flashed (copied to) the board. 80 | 81 | **Tip:** yotta builds a separate application binary for each target under you application directory. In our example, the binary will be at ``/blinky/build/frdm-k64f-gcc/source/``. The file is ``my_blink.bin``. 82 | 83 | To flash an application to your board: 84 | 85 | 1. Connect the board to your computer using a micro-USB cable. 86 | 87 | 1. The board is shown as removable storage. 88 | 89 | 1. From your file explorer, drag and drop the file onto the board. 90 | 91 | 1. The application is now on your board and should start working immediately. Note that some boards need a reset. 92 | 93 | ## Publishing your application 94 | 95 | You can make your code public by committing it to version control (we commit ours to GitHub). You can go one step further and [publish your module](http://yottadocs.mbed.com/tutorial/release.html) to the yotta registry (but please note that publishing an application (as opposed to a library) to the registry is not part of the regular yotta workflow and gives little to no additional benefit in practice). 96 | -------------------------------------------------------------------------------- /Docs/Full_Guide/app_on_yotta.md: -------------------------------------------------------------------------------- 1 | # Creating mbed OS applications with yotta 2 | 3 | This chapter covers: 4 | 5 | * [What a yotta executable - or mbed OS application - looks like](#mbed-os-applications-as-yotta-executables). 6 | 7 | * [Initializing and building a project with yotta](#building-an-application). 8 | 9 | * [Handling dependencies](#how-to-build-an-application). 10 | 11 | [You'll need to install yotta](../installation.md) to complete the examples in this chapter. 12 | 13 | ## mbed OS applications as yotta executables 14 | 15 | mbed OS applications are yotta executable modules, as opposed to yotta library modules. The [yotta documentation explains](http://yottadocs.mbed.com/tutorial/tutorial.html): 16 | 17 | >> "There are two sorts of things that yotta builds: libraries, and executables. Libraries are reusable, and the source code for them is distributed in the yotta registry. Executables are stand-alone programs that depend on libraries, and which are not normally published themselves." 18 | 19 | This chapter focuses on yotta executables, but much of its information is also relevant for libraries. 20 | 21 | ### Structure of a yotta module 22 | 23 | An application and a library have similar structures: 24 | 25 | * A ``module.json`` file. 26 | 27 | * A ``source`` directory containing source files to compile. 28 | 29 | * A ``headers`` directory with the same name as the module. 30 | 31 | * A ``test`` directory. 32 | 33 | * A ``readme.md`` file summarizing the API of the module. 34 | 35 | 36 | 37 | ![](../Full_Guide/Images/module_struct.png) 38 | 39 | **The ``module.json`` file** describes: 40 | 41 | * The name, [semantic version](http://semver.org/) and license information of the module. 42 | 43 | * Any [dependencies](#installing-dependencies) that the module has. 44 | 45 | * Executable indication. If this is missing, the module is a library. The executable indication is the parameter ``bin``, which holds the subdirectory that yotta should build into an executable. 46 | 47 | **The source directory** and any subdirectories contain the source files that yotta will automatically use to build the library. Source files in any other top-level directories will normally be ignored. 48 | 49 | **The headers directory** should have the same name as your module and should contain all (and only) the public headers that your module exposes to anyone that depends on it. The name must be the same as your module name so that `#include` directives look like `#include "modulename/a_header.h"`, which prevents conflicts between multiple modules that have headers with the same name. This directory is optional for applications, since applications don’t normally export an interface that can be used by other modules. 50 | 51 | **The test directory** contains source files and subdirectories to compile into tests. yotta strongly encourages writing tests for modules (and makes it really easy!), because thorough testing is an important part of making software truly reusable. Any source files at the top-level of the test directory will be compiled into separate test executables, and the (recursive) contents of any subdirectories will each be compiled into a single test executable. You can use the [`yotta test` subcommand](http://yottadocs.mbed.com/tutorial/testing.html) to automatically build and run these tests. 52 | 53 | ## Building an application 54 | 55 | This section builds the sample application ``blinky``, which turns a LED on your board on and off. The build target is the [FRDM-K64F board](https://www.mbed.com/en/development/hardware/boards/freescale/frdm_k64f/) with the [gcc toolchain](https://launchpad.net/gcc-arm-embedded). You'll be using this sample several times in the guide, so it's well worth your time to build it. 56 | 57 | ### Overview 58 | 59 | To build your application with mbed OS and yotta, you need to: 60 | 61 | 1. [Initialize a yotta module as an executable](#initializing-a-yotta-executable-module). 62 | 63 | 1. [Set a target](#yotta-targets). 64 | 65 | 1. [Install dependencies](#installing-dependencies). 66 | 67 | 1. [Add application files](#adding-project-code) to the ``source`` folder. 68 | 69 | 1. [Build the module](#building-the-module). 70 | 71 | **Tip:** When working with yotta in a command line prompt or terminal, you must navigate to your module directory before calling yotta. 72 | 73 | ### Initializing a yotta executable module 74 | 75 | If you have [yotta installed](../installation.md) on your computer, you can use ``yotta init`` to construct a new skeleton module in an empty directory by answering a simple series of questions. For example, here is how to initialize the [Blinky sample application](https://github.com/ARMmbed/example-mbedos-blinky): 76 | 77 | **Tip:** There is only one difference between initializing a library module and an executable module, and that is the selection between library and executable. You'll see soon where to make that selection. 78 | 79 | * Create a directory called ``blinky``. In a terminal or CMD, run: 80 | 81 | ``user$ mkdir blinky`` 82 | 83 | * Navigate to the directory, because you need to call yotta from the directory in which you expect it to work: 84 | 85 | ``user$ cd blinky`` 86 | 87 | * To initialize the module, run: 88 | 89 | ``user$ yotta init`` 90 | 91 | * yotta begins to ask questions about the module. It offers a default answer for all questions; press Enter to accept the default, or input a different answer and press Enter. Please note: 92 | 93 | * "Enter the initial version": The default version is 0.0.0. You can use [``yotta version``](#Versioning-an-existing-yotta-module) to edit the version before every release. 94 | 95 | * "Is this an executable?": The default setting of a project is as a library. Please enter "yes" if your project is an executable. Only library modules can be reused by other modules and executables, so choose "no" if you're writing a reusable module. 96 | 97 | * "Keywords": Enter keywords with a comma between them. Keywords help people find your module, so they should describe what it does. 98 | 99 | * "Repository URL": This is where people can find your code to help improve your module or suggest changes. The default repository address is empty, and you may leave it like that. For a GitHub repository, note that you must use the SSH clone URL. In our example that is ``ssh://git@github.com:ARMmbed/example-mbedos-blinky.git``. The repository URL is for information purposes only; yotta doesn't download code from the repo. 100 | 101 | * "What is the license for this project": The default license is Apache-2.0, but you can enter a different one, such as ISC or MIT. 102 | 103 | 104 | ![](../Full_Guide/Images/yotta_init.png) 105 | 106 | * When you've answered all of the questions, yotta creates the basic file structure you need. You can view it with the command ``ls``: 107 | 108 | ``` 109 | user$ ls 110 | module.json my_blinky source test 111 | ``` 112 | 113 | **Tip:** You can use ``yotta init`` in an existing module to modify it at any time. Your previous answers are shown as the default, so you can edit only the ones that need to change; simply press Enter to accept the answers you don't want to change. 114 | 115 | ### Versioning an existing yotta module 116 | 117 | A yotta module's version structure is major.minor.patch, and the default for a new module is 0.0.0. The version is listed in the ``module.json`` file of your module. 118 | 119 | As your project progresses, you will of course want to change versions. Please: 120 | 121 | * Change the *major* if you have new functionality that is *not* backwards compatible. 122 | 123 | * Change the *minor* if you have new functionality that is *fully* backwards compatible. 124 | 125 | * Change the *patch* if you have only backwards compatible bug fixes or changes that don't affect behavior, like whitespace edits. 126 | 127 | To change the version: 128 | 129 | 1. Use ``yotta version`` to check the current version of your module. 130 | 131 | 1. Use ``yotta version `` to bump the version number. The ``patch``, ``minor`` and ``major`` actions each increase the relevant part of the version number by 1, and set the less significant parts to zero. For example ``yotta version minor`` in a module with version ``1.2.3`` will increase the version number to ``1.3.0``: 132 | 133 | 134 | ``` 135 | user$ cd Blinky 136 | user$ yotta version 137 | info: @1.2.3 //current version of Blinky 138 | user$ yotta version minor // new minor version (goes up by 1) 139 | user$ yotta version 140 | info: @1.3.0 // minor went up by 1, and patch changed to 0 141 | ``` 142 | 143 | You could also have used ``yotta version major`` for a major version (2.0.0) or ``yotta version patch`` for a patch version (1.2.4). 144 | 145 | ### yotta targets 146 | 147 | **Tip:** The full explanation for yotta targets is on the [yotta documentation site](http://yottadocs.mbed.com/tutorial/targets.html). Earlier in this document (that chapter will be published soon), you saw how yotta targets and the hardware implementation work together. This chapter explains only a couple of concepts and the basic yotta commands. 148 | 149 | yotta can build your code for different targets: different boards and operating systems. It can also use different compilers. This means you don't have to re-write code every time you want to test or deploy on a new kind of board. It also means you need to explicitly identify your target to yotta. Identifying a target means naming both the hardware and build toolchain you'll be using. The following sections explain how to work with targets. 150 | 151 | #### Searching for targets 152 | 153 | The yotta registry has a list of targets. You can search it using ``yotta search target ``: 154 | 155 | ``` 156 | yotta search target "k64f" 157 | ``` 158 | 159 | **Tip:** You can use the ``--limit`` option to change the number of results displayed. 160 | 161 | Here are the top two results: 162 | 163 | ``` 164 | frdm-k64f-gcc 1.0.1: 165 | Official mbed build target for the mbed frdm-k64f development board. 166 | mbed-target:k64f, mbed-official, mbed, k64f, frdm-k64f, gcc 167 | 168 | frdm-k64f-armcc 1.0.0: 169 | Official mbed build target for the mbed frdm-k64f development board, 170 | using the armcc toolchain. 171 | mbed-target:k64f, mbed-official, mbed, k64f, frdm-k64f, armcc 172 | 173 | ``` 174 | 175 | Each target returns a name and a version, as well as a description. Note that the name includes a build toolchain - ``gcc`` or ``armcc`` - because a target description includes everything about how modules must be compiled to run on the target, including how to run the compiler. 176 | 177 | #### Setting a target 178 | 179 | The ``target`` command has two uses: to check what the current target is, and to set a new target. 180 | 181 | * Used on its own, ``target`` tells you what the current target is. Since targets can depend on other targets, ``yotta target`` might list more than one target. In this case, the first target in the list is the actual build target and the rest are the targets from which the current build target inherits: 182 | 183 | ``` 184 | yotta target 185 | frdm-k64f-gcc 1.0.1 186 | kinetis-k64-gcc 1.0.0 187 | mbed-gcc 0.0.14 188 | ``` 189 | 190 | * Used with a target name, ``target`` sets a new target: 191 | 192 | ``` 193 | yotta target bbc-microbit-classic-armcc 194 | ``` 195 | 196 | **Note:** The first time you access the yotta Registry, you need to log into your mbed user account. 197 | 198 | #### Creating your own target 199 | 200 | To learn about creating a new target, please see the [yotta documentation site](http://yottadocs.mbed.com/tutorial/targets.html). 201 | 202 | ### Module dependencies 203 | 204 | mbed OS is structured as a set of modules. Each module declares which other modules it depends on. When you build a module, yotta looks at these dependencies and installs the necessary modules before completing the build. 205 | 206 | This is also how you build applications for mbed OS: each application declares dependencies that are either mbed OS official modules, or modules created by the community or the developer to provide a specific functionality. 207 | 208 | When you build your application, yotta downloads from the yotta Registry: 209 | 210 | * Modules you listed in your ``module.json``. 211 | 212 | * For each of the modules you listed, the other modules that module itself lists in its ``module.json``. 213 | 214 | **Note:** Because yotta downloads dependencies from the yotta Registry, you must be online the first time you build. 215 | 216 | #### mbed-drivers 217 | 218 | We saw the [core modules mbed OS needs](../index.md). Each of these modules depends on other modules. All mbed OS modules are available on the yotta Registry. 219 | 220 | For example, here is a partial tree for **Blinky**. It shows Blinky's two dependencies: ``mbed-drivers`` and ``uvisor-lib``. Then it shows the start of the next level of dependencies: ``uvisor-lib`` has only one dependency, whereas ``mbed-drivers`` has several. These, in turn, have their own dependencies. And so on: 221 | 222 | 223 | ![](../Full_Guide/Images/yotta_dep.png) 224 | 225 | **Note:** The list of dependencies for any application may change without warning; Blinky's changed while we were writing this chapter. 226 | 227 | Your dependencies are listed in the [``module.json``](#Structure-of-a-yotta-module) file for your module. Below, you can see how to list dependencies from the yotta Registry, GitHub and privately hosted sources. 228 | 229 | ##### module.json: dependencies from the yotta registry 230 | 231 | To add dependencies from the yotta registry, list them in the ``module.json`` file by name and version: 232 | 233 | 234 | ``` 235 | "dependencies": { 236 | "mbed-drivers": "~0.8.3", 237 | "my_dependency": "^1.2.3" 238 |  }, 239 | ``` 240 | 241 | Selecting the dependency version: 242 | 243 | * When you add a dependency to ``module.json``, you want to list the current version number, for example 1.2.3. 244 | 245 | * In front of the version number, you can add a specifier (^ or ~, or even something like ">=1.2.3,<2.3.4") that controls version updates. It limits the versions yotta allows updates to when using ``yotta update``: 246 | * ^: Update to any semantic-version-compatible module (matching major version for >=1.x versions). 247 | * ~: Accept patch-version updates only. 248 | 249 | Using ``yotta install ``, rather than manually editing ``module.json``, uses the correct version specifier automatically. So you can run ``yotta install mbed-drivers`` in your project's directory to automatically include ``mbed-drivers`` with a correct version 250 | 251 | For modules with a 0.x version number, we recommend using ``~`` rather than ^. Even though semantic versioning specifies that any update may break compatibility, if you are using 0.x versions of something you're accepting some breakage anyway, and using ^ prevents you from getting any updates. 252 | 253 | **Tip:** For more information about versions and specifiers, see the [yotta documentation site](http://yottadocs.mbed.com/reference/module.html#dependencies). 254 | 255 | ##### module.json: dependencies from GitHub repositories 256 | 257 | You can use modules from GitHub repositories - private or public: 258 | 259 | 260 | ``` 261 | "dependencies": {"my_github_dependency": "username/reponame"} 262 | ``` 263 | 264 | yotta uses a shorthand for GitHub URLs. It has two parts: /. For example, to include yotta itself: 265 | 266 | 267 | ``` 268 | "dependencies": {"yotta": "ARMmbed/yotta"} 269 | ``` 270 | 271 | yotta supports GitHub formats to specify branches and tags: 272 | 273 | * ``username/reponame#`` 274 | 275 | * ``username/reponame#`` 276 | 277 | * ``username/reponame#`` 278 | 279 | 280 | ##### module.json: dependencies from other sources 281 | 282 | 283 | The yotta Registry and GitHub are the two methods we recommend, but we do support using git and mercurial directly. 284 | 285 | The options are: 286 | 287 | * ``git+ssh://example.com/path/to/repo`` 288 | 289 | * ``anything://example.com/path/to/repo.git`` 290 | 291 | * ``hg+ssh://example.com/path/to/repo`` (mercurial) 292 | 293 | * ``anything://example.com/path/to/repo.hg`` (mercurial) 294 | 295 | For example, to include a privately hosted git repository from ``example.com``: 296 | 297 | ```"dependencies": {"usefulmodule": "git+ssh://user@example.com:path/to/repo"}``` 298 | 299 | Git URLs support branch, version and tags specifications: 300 | 301 | * ``git+ssh://example.com/path/to/repo#`` 302 | 303 | * ``anything://example.com/path/to/repo.git#`` 304 | 305 | Currently, mercurial URLs only support a version specification: 306 | 307 | * ``hg+ssh://example.com/path/to/repo#`` 308 | 309 | * ``anything://example.com/path/to/repo.hg#`` 310 | 311 | #### Installing dependencies 312 | 313 | When you have a dependency, you need to install it before you can build your own project. You need to do this from the module directory. 314 | 315 | In the Blinky example, you need to install ``mbed-drivers``: 316 | 317 | ``` 318 | user$ cd blinky 319 | user$ yotta install mbed-drivers 320 | ``` 321 | 322 | You need to be online for the installation to work, because yotta downloads the modules from the yotta Registry. 323 | 324 | ### Adding project code 325 | 326 | To complete the build: 327 | 328 | 1. Download the ``blinky.cpp`` file from the [example directory's ``source`` subdirectory](https://github.com/ARMmbed/example-mbedos-blinky/tree/master/source). 329 | 330 | 1. Save the file in the ``source`` directory under your own ``blinky`` directory. 331 | 332 | 1. Name the file ``main.`` 333 | 334 | You should now have: 335 | 336 | /blinky/source/main.cpp 337 | 338 | 339 | ### Building the module 340 | 341 | The build command (like the target command) must be performed from within the directory of the module you're trying to build. It must also be performed after selecting a yotta target, as explained above. 342 | 343 | For example, if you're working with the ``blinky`` directory you created above: 344 | 345 | ``` 346 | user$ cd blinky 347 | user$ yotta target frdm-k64f-gcc 348 | user$ yotta build 349 | ``` 350 | 351 | The built executable (a binary) is created at ``./build//source/``. So the result of that build is at ``blinky/build/frdm-k64f-gcc/source/``. 352 | 353 | **Tip:** Some targets require a HEX file, not a BIN. yotta knows which file type to build based on the target description. 354 | 355 | #### Flashing the application to the board 356 | 357 | The file you need to flash onto the mbed-enabled board is ``my_blinky.bin``: 358 | 359 | 1. Connect the board to your computer using a micro-USB cable. 360 | 361 | 1. The board is shown as removable storage. 362 | 363 | 1. From your file explorer, drag and drop the file onto the board. 364 | 365 | 1. The application is now on your board and should start working immediately. Note that some boards need a reset. 366 | 367 | ## yotta and private GitHub repositories 368 | 369 | If your GitHub repo is private, yotta will only be able to access it if you add yotta as an authorized application. Please read the [GitHub help page on this topic](https://help.github.com/articles/connecting-with-third-party-applications/) for more information. 370 | 371 | ## Building a project: summary 372 | 373 | To build your ``blinky`` project with mbed OS and yotta, you: 374 | 375 | 1. Created a new directory and navigated to it in your Terminal or other command-line tool. 376 | 377 | 1. Initialized a yotta module: 378 | 1. ``yotta init``. 379 | 380 | 1. Set a target: 381 | 1. ``yotta search`` to search for one. 382 | 1. ``yotta target `` to set one. 383 | 1. ``yotta target`` to check that the target was set. 384 | 385 | 1. Installed dependencies: 386 | 1. ``yotta install mbed-drivers``. 387 | 388 | 1. Added application files to the ``source`` folder: 389 | 1. File copied from the example GitHub repository and renamed ``main.cpp``. 390 | 391 | 1. Built the module: 392 | 1. ``yotta build``. 393 | 394 | 1. Copied your binary to the board over micro-USB. 395 | 396 | -------------------------------------------------------------------------------- /Docs/Full_Guide/contributing.md: -------------------------------------------------------------------------------- 1 | # Creating and publishing your own libraries and contributing to mbed OS 2 | 3 | This chapter covers the different aspects of developing your own libraries for use in mbed devices, as well as items to keep in mind during development, like licensing. It covers: 4 | 5 | 1. [The mbed OS code base](#contributing-to-the-mbed-os-code-base): Use GitHub to contribute additions and bug fixes to mbed OS itself. 6 | 7 | [//]: # (TODO add section about the index service when available) 8 | 9 | ### Licensing binaries and libraries 10 | 11 | When you write original code you own the copyright and can choose to make it available to others under a license of your choice. A license gives rights and puts limitations on the reuse of your code by others. Not having a license means others cannot use your code. We encourage you to choose a license that makes possible (and encourages!) reuse by others. 12 | 13 | If you create new software, such as drivers, libraries and examples, you can apply whatever license you like as the author and copyright holder of that code. Having said that, we encourage you to use a well known license such as one of the ones listed [on spdx.org](http://spdx.org/licenses/), preferably an [OSI-approved] (https://opensource.org/licenses/alphabetical), permissive open source software license. Specifically, we recommend the following: 14 | 15 | * For original source code, use the Apache 2.0 license.   16 | 17 | * For binary releases (for example, private source code you can’t or don’t want to release but want to share as a binary library and headers available for others to use), consider the [Permissive Binary License](https://www.mbed.com/licenses/PBL-1.0). This is designed to be compatible with Apache 2.0 and the mbed OS code base. 18 | 19 | * If your software incorporates or is derived from other third party open source code, please be sure to retain all notices and identify the license for the third party licensed code in the same manner as described below. Remember, you cannot change the license on someone else’s code, because you are not the copyright holder! Instead, choose a license that is compatible with the license used by the third party open source code, or use the same license as that code. For example, if your software is derived from GPL source code, GPL requires you to license the rest of your code in that software under the GPL too. Note that many commercial users won’t be able to use GPL source code in their products, so we don't recommend this license if you're not obligated to use it. 20 | 21 | You must either write all the code you provide yourself, or have the necessary rights to provide code written by someone else. 22 | 23 | In all cases, whatever license you use, please use an [SPDX](https://spdx.org/about-spdx/what-is-spdx) [license identifier](http://spdx.org/licenses/) to make it easier for users to understand and legally review licenses. 24 | 25 | #### When to use Apache 2.0 26 | 27 | Apache 2.0 is a permissive, free and open source software license that allows other parties to use, modify, and redistribute the code in source and binary form. Compared to the often used BSD license, Apache 2.0 provides an express patent grant from contributors to users. 28 | 29 | The full text of the license can be found on the [Apache website](http://www.apache.org/licenses/LICENSE-2.0). For more information about Apache 2.0, see [the FAQ](http://www.apache.org/foundation/license-faq.html). 30 | 31 | #### How to apply Apache 2.0 correctly 32 | 33 | In order to clearly reflect the Apache 2.0 license, please create two text files: 34 | 35 | * A *LICENSE* file with the following text:
36 | 37 | 
Unless specifically indicated otherwise in a file, files are licensed under the Apache 2.0 license, 
 38 | as can be found in: LICENSE-apache-2.0.txt
39 | 40 | * The full original [Apache 2.0 license text](http://www.apache.org/licenses/LICENSE-2.0) in *LICENSE-apache-2.0.txt* 41 | 42 | Each source header should *start with* your copyright line, the SPDX identifier and the Apache 2.0 header as shown here: 43 | 44 | ``` 45 | Copyright (c) [First year]-[Last year], **Your Name or Company Here**, All Rights Reserved 46 | SPDX-License-Identifier: Apache-2.0 47 | 48 | Licensed under the Apache License, Version 2.0 (the "License"); 49 | you may not use this file except in compliance with the License. 50 | 51 | You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 52 | 53 | Unless required by applicable law or agreed to in writing, software 54 | distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, 55 | either express or implied. 56 | 57 | See the License for the specific language governing permissions and limitations under the License. 58 | ``` 59 | 60 | #### When to use the Permissive Binary License 61 | 62 | The Permissive Binary License (PBL) is a permissive license based on BSD-3-Clause and designed specifically for binary blobs. It's minimal, but covers the basics, including an express patent grant. 63 | 64 | It allows you to share a binary blob and the relevant headers, and allows others to use that binary blob as part of their product - as long as they provide it with all the relevant dependencies and don't modify it or reverse engineer it. 65 | 66 | The full text can be found on [mbed.com](https://www.mbed.com/licenses/PBL-1.0). 67 | 68 | #### How to apply PBL correctly 69 | 70 | In order to clearly reflect the PBL license, please create three text files: 71 | 72 | * A *LICENSE* file with: 73 | 74 | 
Unless specifically indicated otherwise in a file, files are licensed under the Public Binary License, 
 75 | as can be found in: LICENSE-permissive-binary-license-1.0.txt
76 | 77 | * The full original [Public Binary License 1.0 text](https://www.mbed.com/licenses/PBL-1.0) in *LICENSE-permissive-binary-license-1.0.txt*. 78 | 79 | * A *DEPENDENCIES* file with the dependencies that this binary requires to work properly. This is to make sure that third parties integrating the binary in their own distribution are aware that they need to include the relevant dependencies. If your binary does not have any dependencies, the file should state so (that is, say “No dependencies”); don't omit this file. 80 | 81 | Each source header should *start with* your copyright line, the SPDX identifier and the BPL header: 82 | 83 | ``` 84 | Copyright (c) [First year]-[Last year], **Your Name Here**, All Rights Reserved 85 | SPDX-License-Identifier: LicenseRef-PBL 86 | 87 | Licensed under the Permissive Binary License, Version 1.0 (the "License"); 88 | you may not use this file except in compliance with the License. 89 | 90 | You may obtain a copy of the License at https://www.mbed.com/licenses/PBL-1.0 91 | 92 | See the License for the specific language governing permissions and limitations under the License. 93 | ``` 94 | 95 | ### Using a different license 96 | 97 | If you decide to use a different license for your work, follow the same pattern: 98 | 99 | * Create a *LICENSE* file with a description of the license situation, following the pattern described in the sections above. 100 | 101 | * Put the full original license texts in separate documents named *LICENSE-XYZ.txt*, where XYZ is the corresponding [SPDX identifier](http://spdx.org/licenses/) for your license. 102 | 103 | * Begin each source header with your copyright line, the SPDX identifier and the standard header for the license that applies to that single file, if it has one. 104 | 105 | * If more than one license applies to the source file, then use an SPDX license expression (see Appendix IV in [this document](http://spdx.org/sites/spdx/files/SPDX-2.0.pdf)), to reflect the presence of multiple licenses in your *LICENSE* file and in each source file. 106 | 107 | ## Contributing to the mbed OS code base 108 | 109 | ### mbed OS principles 110 | 111 | mbed OS uses these same basic principles for its source code and library distributions. So source code we own is distributed under the Apache 2.0 license and binary blobs are released under the Permissive Binary License. Software parts from third parties that were already licensed under a different license are available under that original license. 112 | 113 | All the source code and binary blobs that end up in mbed OS are maintained in public GitHub repositories. 114 | 115 | ### Contributions 116 | 117 | All code changes and additions to mbed OS are handled through GitHub. If you want to contribute, either by adding features or by fixing bugs, please follow the guidelines for [new features](#contributing-new-features-to-mbed-os) and [bugs](#reporting-and-fixing-bugs), and in both cases please follow the [code style guide and GitHub pull request guidelines](Code_Style.md). 118 | 119 | ### Licensing 120 | 121 | If you want to contribute code to mbed OS, you must sign an mbed Contributor License Agreement (CLA). Please ask for a CLA before submitting any code (for example, while discussing the issue on GitHub), then wait for ARM to confirm acceptance of your CLA before making contributions. 122 | 123 | **Note:** If you publish a feature or a solution to a problem before signing the CLA, then find out that you are not able or allowed to sign the CLA, we will not be able to use your solution anymore. That may prevent us from solving the problem for you. 124 | 125 | When you ask for the CLA, we'll send you the agreement and ask you to sign it *before* we handle any pull request from you: 126 | 127 | * Individuals who want to contribute their own work must sign and return an Individual CLA. 128 | 129 | * Companies that want employees to contribute on its behalf must sign and return a Corporate CLA. 130 | 131 | The same agreement is then valid for all future pull requests from that GitHub username.   132 | 133 | ### Contributing new features to mbed OS 134 | 135 | Before contributing an enhancement (new feature, new port and so on) please [discuss it on the forums](https://developer.mbed.org/forum/) to avoid duplication of work, as we or others might be working on a related feature. 136 | 137 | Patch contributions can only be accepted through GitHub by creating a pull request from forked versions of our repositories. This allows us to review the contributions in a user friendly and reliable way, under public scrutiny. 138 | 139 | Please create separate patches for each concern; each patch should have a clear unity of purpose. In particular, separate code formatting and style changes from functional changes. This makes each patch’s true contribution clearer, and therefore quicker and easier to review. 140 | 141 | ### Reporting and fixing bugs 142 | 143 | Before submitting a bug report or a bug fix, please [discuss it on the forums](https://developer.mbed.org/forum/) to avoid duplication of work, as we or others might be working on it already. 144 | 145 | #### Bug reports (issues) on GitHub 146 | 147 | All mbed OS is on GitHub; please use GitHub's [issues mechanism](https://guides.github.com/features/issues/) to open a bug report directly against the relevant GitHub repository. 148 | 149 | #### Bug fixes 150 | 151 | Please refer to the [code contributions chapter](Code_Style.md). 152 | 153 | Bug fixes must be verified by a member of the mbed team before they're pulled into the main branch. You must therefore use GitHub to fork the repo, then submit a pull request with your changes. 154 | 155 | The last line in your commit message description should say “Fixes #deadbeef”, where “deadbeef” is the issue number in GitHub. This allows GitHub to automatically close the issue when the commit is merged into the default branch. 156 | 157 | ## Further reading 158 | 159 | Please see the [code contributions chapter](Code_Style.md) for the guidelines to GitHub pull requests and the coding style guide. 160 | -------------------------------------------------------------------------------- /Docs/Full_Guide/mbed_tls.md: -------------------------------------------------------------------------------- 1 | # mbed TLS 2 | 3 | mbed TLS makes it trivially easy for developers to include cryptographic and SSL/TLS capabilities in their embedded products, with a minimal code footprint. It offers an SSL library with an intuitive API and readable source code. 4 | 5 | **Note:** The current release of mbed TLS for mbed OS is beta, and implements no secure source of random numbers, weakening its security. We therefore consider it an evaluation version, not a production version. If you want a production version, please consider the standalone available at [https://tls.mbed.org/](https://tls.mbed.org/) 6 | 7 | Currently the only supported yotta targets are: 8 | 9 | - `frdm-k64f-gcc` 10 | - `frdm-k64f-armcc` 11 | - `x86-linux-native` 12 | - `x86-osx-native` 13 | 14 | ## Differences between the standalone and mbed OS editions 15 | 16 | mbed TLS has a standalone edition for devices that are not running mbed OS. However, this guide focuses on the mbed OS integration. While the two editions share a code base, there are a number of differences, mainly in configuration and integration. You should keep those differences in mind when reading some articles in our [knowledge base](https://tls.mbed.org/kb), as currently all the articles are about the standalone edition. 17 | 18 | The key differences are: 19 | 20 | * To reduce its footprint, the mbed OS edition enables a smaller set of features in `config.h` by default. While the default configuration of the standalone edition puts more emphasize on maintaining interoperability with old peers, the mbed OS edition only enables the most modern ciphers and the latest version of TLS and DTLS. 21 | 22 | * The following components of mbed TLS are disabled in the mbed OS edition: `net.c` and `timing.c`. This is because mbed OS includes their equivalents. 23 | 24 | * The mbed OS edition comes with a fully integrated API for TLS and DTLS connections in a companion module: [mbed-tls-sockets](https://github.com/ARMmbed/mbed-tls-sockets). See ["Performing TLS and DTLS connections"](#Performing-TLS-and-DTLS-connections). 25 | 26 | 27 | ## Performing TLS and DTLS connections 28 | 29 | mbed TLS provides a high-level API for performing TLS and DTLS connections in mbed OS. The API is in a separate yotta module: [mbed-tls-sockets](https://github.com/ARMmbed/mbed-tls-sockets). We recommend using this API for TLS and DTLS connections. It is very similar to the API provided by the [``sockets``](https://github.com/ARMmbed/sockets) module for unencrypted TCP and UDP connections. 30 | 31 | The `mbed-tls-sockets` module includes a complete [example TLS client](https://github.com/ARMmbed/mbed-tls-sockets/blob/master/test/tls-client/main.cpp) with [usage instructions](https://github.com/ARMmbed/mbed-tls-sockets/blob/master/test/tls-client/README.md). 32 | 33 | ## Configuring mbed TLS features 34 | 35 | mbed TLS makes it easy to disable any feature during compilation, if that feature isn't required for a particular project. The default configuration: 36 | 37 | * Enables all modern and widely-used features, to meet the needs of new projects. 38 | 39 | * Disables all features that are older or less common, to minimize the code footprint. 40 | 41 | The list of compilation flags is available in the fully documented [``config.h`` file](https://github.com/ARMmbed/mbedtls/blob/development/include/mbedtls/config.h). 42 | 43 | If you need to adjust those flags, you can provide your own configuration-adjustment file: 44 | 45 | 1. Create a configuration file. You can name it freely. 46 | 1. Put the file in your application's ``include`` directory. 47 | 1. Add suitable `#define` and `#undef` statements in your file. 48 | 1. mbed TLS needs to know your file's name. To do that, you need to use yotta's [configuration system](http://docs.yottabuild.org/reference/config.html): 49 | - In your ``config.json`` file, under ``mbedtls``, fine the key ``user-config-file``. 50 | - Enter your filename as the value of that key. 51 | 52 | ``config.h`` includes your file between the default definitions and the sanity checks. 53 | 54 | For example, in an application called `myapp`, if you want to enable the EC J-PAKE key exchange and disable the CBC cipher mode, you can create a file named  `mbedtls-config-changes.h` in the `myapp` directory containing the following lines: 55 | 56 | #define MBEDTLS_ECJPAKE_C 57 | #define MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED 58 | 59 | #undef MBEDTLS_CIPHER_MODE_CBC 60 | 61 | And then create a file named `config.json` at the root of your application with the following contents: 62 | 63 | { 64 | "mbedtls": { 65 | "user-config-file": "\"myapp/mbedtls-config-changes.h\"" 66 | } 67 | } 68 | 69 | **Note:** You need to provide the exact name that you use in the `#include` directive, including the `<>` or quotes around the name. 70 | 71 | ## Getting mbed TLS from GitHub 72 | 73 | Like most components of mbed OS, mbed TLS is developed in the open and its source can be found on GitHub: [ARMmbed/mbedtls](https://github.com/ARMmbed/mbedtls). Unlike most other mbed OS components, however, you cannot just clone the repository and run `yotta build` from its root. This is because mbed TLS also exists as an independent component, so its repository includes things that are not relevant for mbed OS. 74 | 75 | If you want to use mbed TLS from the GitHub repo: 76 | 77 | 1. Create a local clone. 78 | 79 | 1. From the root of the clone, run the shell script: 80 | 81 | ``` 82 | yotta/create-module.sh 83 | cd yotta/module 84 | ``` 85 | 86 | You can then run any [yotta command](app_on_yotta.md) you would normally run, such as [`yotta build`] or [`yotta link`]. 87 | 88 | ## Sample programs 89 | 90 | This release includes the following examples: 91 | 92 | 1. [**Self test:**](https://github.com/ARMmbed/mbedtls/blob/development/yotta/data/example-selftest) Tests different basic functions in the mbed TLS library. 93 | 94 | 2. [**Benchmark:**](https://github.com/ARMmbed/mbedtls/blob/development/yotta/data/example-benchmark) Measures the time taken to perform basic cryptographic functions used in the library. 95 | 96 | 3. [**Hashing:**](https://github.com/ARMmbed/mbedtls/blob/development/yotta/data/example-hashing) Demonstrates the various APIs for computing hashes of data (also known as message digests) with SHA-256. 97 | 98 | 4. [**Authenticated encryption:**](https://github.com/ARMmbed/mbedtls/blob/development/yotta/data/example-authcrypt) Demonstrates using the Cipher API for encrypting and authenticating data with AES-CCM. 99 | 100 | These examples are integrated as yotta tests, so they are built automatically when you build mbed TLS. Each of them comes with complete usage instructions as a Readme file in the repository. 101 | 102 | ## Other resources 103 | 104 | The [mbed TLS website](https://tls.mbed.org) contains many other useful resources for developers, such as [developer 105 | documentation](https://tls.mbed.org/dev-corner), [knowledge base articles](https://tls.mbed.org/kb), and a [support forum](https://tls.mbed.org/discussions). 106 | 107 | ## Contributing 108 | 109 | We gratefully accept bug reports and contributions from the community. There are some requirements we need to fulfill in order to be able to integrate contributions: 110 | 111 | * Simple bug fixes to existing code do not contain copyright themselves and we can integrate without issue. The same is true of trivial contributions. 112 | 113 | * For larger contributions, such as a new feature, the code can possibly fall under copyright law. We then need your consent to share in the ownership of the copyright. We have a form for this, which we will send to you in case you submit a contribution or pull request that we deem this necessary for. 114 | 115 | To contribute, please: 116 | 117 | * [Check for open issues](https://github.com/ARMmbed/mbedtls/issues) or [start a discussion](https://tls.mbed.org/discussions) around a feature idea or a bug. 118 | 119 | * Fork the [mbed TLS repository on GitHub](https://github.com/ARMmbed/mbedtls) to start making your changes. As a general rule, you should use the "development" branch as a basis. 120 | 121 | * Write a test that shows that the bug was fixed or that the feature works as expected. 122 | 123 | * Send a pull request and nag us until it gets merged and published. We will include your name in the ChangeLog. 124 | -------------------------------------------------------------------------------- /Docs/Full_Guide/memory.md: -------------------------------------------------------------------------------- 1 | # Memory in mbed OS 2 | mbed OS provides memory allocation services that are based on a standard memory organization, described below. The memory allocation services provide for most use-cases in memory allocation, including heap allocation, pool allocation, and extendable pools. 3 | 4 | ## Memory organization in mbed OS 5 | In a conventional embedded system, there are four areas of memory: Code, Global Data, the heap, and the stack. Frequently, the heap and the stack are organized so that they occupy the same block of memory. In mbed OS, we add two additional areas of memory: uVisor memory and the never free heap. Memory is organized as below. Note that code generally lives in ROM, so it is not included in this diagram. 6 | 7 | ``` 8 | Cortex-M3/M4            Cortex-M0/M+         9 | Largest RAM address     Largest RAM address 10 | +-----------------+     +-----------------+ 11 | | Never Free Heap |     | Never Free Heap | 12 | |                 |     |                 | 13 | |      Heap       |     |      Heap       | 14 | +-----------------+     +-----------------+ 15 | |   Global Data   |     |   Global Data   | 16 | +-----------------+     +-----------------+ 17 | |      Stack      |     |      Stack      | 18 | +-----------------+     +-----------------+ 19 | |  uVisor Memory  |     Smallest RAM address 20 | +-----------------+    21 | Smallest RAM address   22 | ``` 23 | 24 | ### uVisor Memory 25 | On Cortex-M3/M4, the uVisor reserves a small portion of memory at the beginning of RAM for itself and for secured features (boxes). The uVisor secures this area using the MPU. For more information on the uVisor, see [our main site](https://www.mbed.com/en/technologies/security/uvisor/) 26 | 27 | ### Stack 28 | The stack is placed at the bottom of the memory, and it grows downwards. This location is selected explicitly because it allows stack overflows to be easily caught. In a Cortex-M3/M4 system, where the uVisor is in use, the first access below the bottom of the stack will trigger a [MemManage](http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0552a/Cihgggbh.html) exception, handled by the uVisor. In a Cortex-M0/M0+ system, it will trigger a [HardFault](http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0497a/Babcefea.html). This allows applications to recover from stack overflows, generally through a reset. 29 | 30 | This organization does mean that a stack must be sized to match the application. Currently, this is a value set in the target, but a future version will expose stack configuration through yotta config. 31 | 32 | ### Global Data 33 | Global Data is the typical ``.bss`` and ``.data`` sections generated by the compiler. This section's size depends on the application and requires no configuration. 34 | 35 | ### Heaps 36 | There are two kinds of heap in mbed OS. The heap grows upwards from the bottom of the heap section, while the never free heap grows downwards from the top. 37 | 38 | #### The standard heap 39 | The standard heap is a typical dlmalloc heap, which grows upwards from the bottom of the heap section using the ```sbrk``` function provided by the [core-util](https://github.com/ARMmbed/core-util) module. 40 | 41 | #### The never free heap 42 | The never free heap grows downwards from the end of memory. The never free heap is intended for use with data that need not be freed, such as memory pools. Memory is allocated from the never free heap using the reverse sbrk function (```krbs```) provided by the [core-util](https://github.com/ARMmbed/core-util) module. 43 | 44 | ## Memory Allocation in mbed OS 45 | mbed OS provides several memory allocation services, including a traits allocator, a typical dlmalloc heap, a never free heap, a pool allocator and an extendable pool allocator. These facilities are built on top of two trivial, but lock-free, allocators: ```sbrk()``` and ```krbs()``` (a reverse ```sbrk```). 46 | 47 | ### Usage Notes 48 | In general, you should use ```mbed_ualloc()``` where malloc-type allocation is necessary. Standard library functions, such as ```malloc()```, ```realloc()```, and ```calloc``` can also be used, but they are not as flexible as ```mbed_ualloc()```. You should avoid using ```sbrk()``` and ```krbs()``` where possible; these are low-level functions, intended for use by other memory allocators. 49 | 50 | Where memory is allocated in interrupt context, or similarly sized memory is used frequently, it can be advantageous to use ```PoolAllocator``` or ```ExtendablePoolAllocator```. ```malloc()```, ```realloc()```, and ```calloc``` should not be called from an interrupt context. ```mbed_ualloc()``` should only be called from an interrupt context with the ```UALLOC_TRAITS_NEVER_FREE``` trait set. 51 | 52 | 53 | ### ualloc traits allocator 54 | In mbed OS, all memory allocation is done through a traits allocator, [ualloc](https://github.com/ARMmbed/ualloc). ualloc provides features that support both the dlmalloc heap and the never free heap. Currently, only two traits are supported in ualloc: ```UALLOC_TRAITS_NEVER_FREE```, which allocates from the never-free region, and ```UALLOC_TRAITS_ZERO_FILL```, which zeros the allocated space prior to returning it, much like ```calloc```. ```ualloc``` hooks several of the standard library functions: 55 | 56 | * ```malloc``` 57 | * ```calloc``` 58 | * ```realloc``` 59 | * ```free``` 60 | 61 | This is to ensure that all allocations are done via ualloc, which in turn ensures that all compilers with all libc's will produce the same memory behavior. Using ualloc as a the channel for all memory allocations also provides a common point for memory allocation analysis. By analyzing calls to ualloc functions, it is possible to monitor all memory allocation behavior. 62 | 63 | For allocations with the ```UALLOC_TRAITS_NEVER_FREE``` trait, ualloc calls ```krbs()``` directly. Without the never-free trait, ualloc calls dlmalloc functions. 64 | 65 | ### The standard heap 66 | The standard heap is managed by [dlmalloc](https://github.com/ARMmbed/dlmalloc). For standard heap operations, ualloc forwards operations to dlmalloc. dlmalloc, in turn, uses ```sbrk()``` to obtain more memory. 67 | 68 | ### The pool allocator 69 | mbed OS provides a pool allocator in the [core-util](https://github.com/ARMmbed/core-util) module, called ```PoolAllocator```. This allocator divides its block of memory into 4-byte aligned regions of fixed size. The pool allocator is lock-free and very fast, so it is suitable for use in interrupt context. ```PoolAllocator``` can run out of memory, however, so for some operations, ```ExtendablePoolAllocator``` is more useful. 70 | 71 | ### The extendable pool allocator 72 | mbed OS also provides an extendable pool allocator in the [core-util](https://github.com/ARMmbed/core-util) module, called ```ExtendablePoolAllocator```. It is built on top of PoolAllocator, with the sole difference that, when ```ExtendablePoolAllocator``` runs out of pool elements to allocate, it can request more from the never free heap, using ```ualloc()```, with the ```UALLOC_TRAITS_NEVER_FREE``` flag set. 73 | 74 | ### sbrk 75 | sbrk is a trivial allocator implemented in the [core-util](https://github.com/ARMmbed/core-util) module. It supports linear allocation and deallocation. It is completely lock-free. 76 | 77 | ### krbs 78 | krbs is effectively the reverse of ```sbrk()```, allocating memory from the end of a section, rather than the beginning. The one exception in behavior is that ```krbs()``` does not support deallocation. 79 | 80 | 81 | -------------------------------------------------------------------------------- /Docs/Full_Guide/networking.md: -------------------------------------------------------------------------------- 1 | # Networking and connectivity 2 | mbed OS provides several facilities for networking and connectivity. For high level applications, mbed OS provides mbed Client, the C++ Socket API, and the BLE API. mbed Client is a high level communication mechanism designed for working directly with mbed Device Server over CoAP. The C++ Socket API is a fully non-blocking, event-based, object-oriented socket API. The BLE API is a C++ API for creating Bluetooth Low Energy applications. These APIs abstract several protocols, including Ethernet, 6LoWPAN over 802.15.4, and Bluetooth Low Energy. 3 | 4 | Using these three high level APIs, it is possible to create rich connected applications. 5 | 6 | ## Networking in mbed OS: the components 7 | 8 | Networking in mbed OS is broken down into several components: 9 | 10 | * The application. 11 | 12 | * (optionally) The mbed Client API. 13 | 14 | * The C++ Socket API. 15 | 16 | * The Socket Abstraction Layer (SAL). 17 | 18 | * The IP stack. 19 | 20 | * The network driver. 21 | 22 | * The network interface. 23 | 24 | ![](../Full_Guide/Images/networkstacks.png) 25 | 26 | Some parts of this infrastructure are still in development but most of it is quite stable. 27 | 28 | ### The application 29 | 30 | The application is the user's program. The application layer is responsible for: 31 | 32 | * Initializing the IP stack (Note: when yotta supports module init, this requirement will be removed). 33 | 34 | * Initializing the network interface. 35 | 36 | * Sending data. 37 | 38 | * Reacting to received data. 39 | 40 | ### The C++ Socket API 41 | 42 | The C++ Socket API provides a number of state management facilities and convenience functions. The API also provides a mechanism for event demultiplexing, so that each class of event is dispatched to a separate handler. The C++ Socket API is built on top of the MINAR scheduler. This means that C++ Socket API callbacks do not execute in IRQ context, so complex computations, memory allocation and so on will not interfere with interrupt processing. More information on using the C++ socket API can be found in the sockets readme. 43 | 44 | The C++ Socket API is built on top of the Socket Abstraction Layer. 45 | 46 | __Known issues__ 47 | 48 | Currently the C++ Socket API is responsible for scheduling the periodic callback of each underlying stack. However, it only supports calling the periodic callback of a single stack and so does not support two coexisting IP stacks. 49 | 50 | ### The Socket Abstraction Layer 51 | 52 | The Socket Abstraction Layer (SAL) provides a common C interface to all of the common features that an IP stack provides. Much of the SAL is implemented as wrappers around the structures provided by IP stacks. Some features of the SAL require that data types be converted to and from IP stack structures. The primary example of this is the ```struct socket_addr```: this structure is implemented as a 128-bit big-endian integer. This is so that the SAL can treat all IP addresses the same way, and so that the application can have some guarantees about how it accesses the IP addresses. In most stacks, the IP address is stored as a big-endian integer anyway, so this creates very little overhead. 53 | 54 | Typically, applications will not use SAL APIs directly. While it is possible to do this, the C++ Socket API provides a much more convenient interface, with very little overhead. 55 | 56 | The SAL has been designed to support multiple, coexisting IP stacks, running simultaneously. However, this feature is not currently supported by the C++ Socket API. The SAL is configured to use a maximum of two IP stacks. In a future version of the SAL, it will be possible to change the number of supported stacks. 57 | 58 | #### SAL development 59 | 60 | The SAL is not complete: an interface abstraction API is still in development. This abstraction is necessary because the stack needs to know about network interface state changes; it also needs to do IP address configuration, either through static configuration or through DHCP. Because these configuration options are largely stack-level, they require an API to control the stack, so the SAL forms a natural interface point. 61 | 62 | #### SAL dependencies 63 | 64 | The SAL contains very little code - it is mostly a set of API definitions. The SAL depends on an IP stack to implement its APIs. The IP stack is selected via the [yotta config mechanism](http://yottadocs.mbed.com/reference/config.html). 65 | 66 | For example, when using a Freescale FRDM-K64F, LwIP is enabled by default. If 6LoWPAN is the target for the application, then application-level config can override this choice in an application-supplied ```config.json```: 67 | 68 | 69 | ```JSON 70 | { 71 | "mbed-os": { 72 | "net": { 73 | "stacks": { 74 | "lwip":false, 75 | "nanostack": true 76 | } 77 | } 78 | } 79 | } 80 | ``` 81 | 82 | ### The IP stack 83 | 84 | The IP stack is typically wrapped with a lightweight shim that implements the APIs of the SAL. Currently, there are two supported stacks: LwIP (IPv4 only), and nanostack (IPv6 only). 85 | 86 | Please note that some mbed C++ Socket API methods may not be available for the selected IP stack. Therefore, it is important to check the API method return value. 87 | ### The network driver 88 | 89 | This component provides the IP stack with the interface it needs to control the hardware. One driver is required for each combination of IP stack and network hardware. 90 | 91 | ### The network interface 92 | 93 | The network interface provides management functions for the interface hardware, such as power up/down and configuration. It is currently bound to the IP stack, but future development of the SAL will permit the network interface to be decoupled from the IP stack. 94 | 95 | 96 | ### Examples 97 | 98 | There are several complete examples provided in [mbed-example-network](https://github.com/ARMmbed/mbed-example-network). In addition to these examples, a plain DNS resolution is provided below. 99 | 100 | #### DNS example 101 | 102 | This is a simple example of resolving an address with DNS: 103 | 104 | ```C++ 105 | #include "sockets/v0/UDPSocket.h" 106 | #include "sal-stack-lwip/lwipv4_init.h" 107 | #include "sal-iface-eth/EthernetInterface.h" 108 | using namespace mbed::Sockets::v0; 109 | class Resolver { 110 | private: 111 | UDPSocket _sock; 112 | public: 113 | Resolver() : _sock(SOCKET_STACK_LWIP_IPV4) { 114 | _sock.open(SOCKET_AF_INET4); 115 | } 116 | void onDNS(Socket *s, struct socket_addr addr, const char *domain) { 117 | (void) s; 118 | SocketAddr sa; 119 | char buf[16]; 120 | sa.setAddr(&addr); 121 | sa.fmtIPv4(buf,sizeof(buf)); 122 | printf("Resolved %s to %s\r\n", domain, buf); 123 | } 124 | socket_error_t resolve(const char * address) { 125 | printf("Resolving %s...\r\n", address); 126 | return _sock.resolve(address, 127 | UDPSocket::DNSHandler_t(this, &Resolver::onDNS)); 128 | } 129 | }; 130 | 131 | EthernetInterface eth; 132 | Resolver *r; 133 | void app_start(int argc, char *argv[]) { 134 | (void) argc; 135 | (void) argv; 136 | static Serial pc(USBTX, USBRX); 137 | pc.baud(115200); 138 | printf("Connecting to network...\r\n"); 139 | eth.init(); 140 | eth.connect(); 141 | printf("Connected\r\n"); 142 | lwipv4_socket_init(); 143 | r = new Resolver(); 144 | r->resolve("mbed.org"); 145 | } 146 | 147 | ``` 148 | 149 | 150 | ## IPv6 (6LoWPAN) 151 | 152 | The 6LoWPAN stack is a robust, scalable and self-healing mesh networking stack for low power, less complex constrained devices. The 6LoWPAN stack [documentation](http://docs.mbed.com/docs/arm-ipv66lowpan-stack/en/latest/) gives an overview of the 6LoWPAN technology and reference to the 6LoWPAN stack C API. 153 | 154 | In mbed OS, the 6LoWPAN stack should be used through [mbed-mesh-api](https://github.com/ARMmbed/mbed-mesh-api) and the [mbed C++ Socket API](https://github.com/ARMmbed/sockets/blob/master/README.md). The mbed mesh API is responsible for initializing the 6LoWPAN stack when used for the first time; applications must therefore connect to a wireless network by using the mbed-mesh-api before using any other method from the socket API. 155 | 156 | The mbed C++ Socket API is not fully supported by the 6LoWPAN adaptation layer. You can see the 6LoWPAN stack deviations from the mbed Socket C++ API in the [sal-iface-6lowpan](https://github.com/ARMmbed/sal-iface-6lowpan) documentation. 157 | 158 | The mbed-mesh-api is in an experimental state and uses static configuration. It does not provide API for selecting the node operating mode, security option, radio channel or other options that are needed for connecting to a 6LoWPAN network. Support for these configurations will be available in the future. 159 | 160 | ## Thread 161 | 162 | Thread support is built-in to the 6LoWPAN stack. See [Introduction to Thread](https://docs.mbed.com/docs/arm-ipv66lowpan-stack/en/latest/thread_overview/index.html) for more information. 163 | 164 | ## Bluetooth Low Energy (BLE) 165 | 166 | The BLE libraries in mbed OS abstract the BLE protocol, so that no matter which manufacturer’s stack you’re using, the API remains the same and you don’t need to rewrite your code. By moving to yotta, we have gained the ability to switch between API implementations depending on which target we select. 167 | 168 | To learn more about BLE on mbed OS, see our [BLE Intros](https://docs.mbed.com/docs/ble-intros/). 169 | 170 | ## Including networking headers in your code 171 | 172 | All mbed OS applications need ``mbed-drivers``, which includes most mbed OS functionality. However, for networking, you will have to explicitly include additional headers. 173 | 174 | __For IPv4:__ 175 | 176 | ```c++ 177 | #include "sal-iface-eth/EthernetInterface.h" 178 | #include "sockets/UDPSocket.h" //if you want UDP 179 | #include "sockets/TCPStream.h" //if you want a TCP Client 180 | #include "sockets/TCPListener.h" //if you want a TCP Server 181 | #include "sal-stack-lwip/lwipv4_init.h" 182 | ``` 183 | 184 | And please ensure that you have the following call in your code: 185 | 186 | ```c++ 187 | void app_start(int argc, char *argv[]) 188 | { 189 | socket_error_t err = lwipv4_socket_init(); 190 | ... 191 | } 192 | ``` 193 | 194 | __For 6LoWPAN and Thread:__ 195 | 196 | ```c++ 197 | #include "mbed-mesh-api" 198 | #include "mbedclient.h" 199 | 200 | // if you are using network modules other than mbed Client: 201 | #include "sockets.h" 202 | ``` 203 | 204 | You might need to include board specific drivers, for example ``#include "atmel-rf-driver"``. 205 | 206 | __For BLE:__ 207 | 208 | ```c++ 209 | #include "ble/BLE.h" 210 | 211 | // If you're using a standard service, include its header: 212 | #include "ble/services/iBeacon.h" 213 | ``` 214 | 215 | __module.json updates__ 216 | 217 | You will need to add these dependencies to your project's ``module.json`` file. The following example shows includes for 6LoWPAN: 218 | 219 | ```json 220 | "dependencies": { 221 | "mbed-drivers": "*", 222 | "mbed-client": "^1.0.0", 223 | "atmel-rf-driver": "^1.0.0", 224 | "mbed-mesh-api": "^1.0.0" 225 | } 226 | ``` 227 | 228 | And these are for BLE: 229 | 230 | ```json 231 | "dependencies": { 232 | "mbed-drivers": "*", 233 | "ble": "^2.0.0" 234 | } 235 | ``` 236 | -------------------------------------------------------------------------------- /Docs/FurtherReading.md: -------------------------------------------------------------------------------- 1 | # Further reading and other links 2 | 3 | To learn more about mbed, see the [main site](http://mbed.com). 4 | 5 | ## Release notes 6 | 7 | All release notes for mbed OS and mbed Client are [in the mbed Release Documents project](https://docs.mbed.com/docs/release-documents/en/latest/). 8 | 9 | ## Software 10 | 11 | To learn about mbed [software](http://mbed.com/en/development/software/): 12 | 13 | * [The mbed OS device software](http://mbed.com/en/development/software/mbed-os/). 14 | 15 | * [The yotta build tool](http://mbed.com/en/development/software/tools/yotta/). 16 | 17 | * [The testing tools](http://mbed.com/en/development/software/tools/testing/). 18 | 19 | * Security with [mbed TLS and mbed OS uVisor](http://mbed.com/en/technologies/security/). 20 | 21 | ## Connectivity 22 | 23 | Learn about [connectivity on mbed](http://mbed.com/en/technologies/connectivity/) and [mbed cloud services](http://mbed.com/en/development/cloud/). 24 | 25 | You might want to pay special attention to [mbed Client](/http://mbed.com/en/development/cloud/mbed-client/), the software library that connects constrained devices to mbed Device Server. 26 | 27 | ## Hardware and production 28 | 29 | * The [mbed Enabled hardware list](http://mbed.com/en/development/hardware/). 30 | 31 | * Moving from [prototyping to production](http://mbed.com/en/development/hardware/prototyping-production/), including an introduction to the hardware development kit (HDK). 32 | 33 | ## APIs 34 | 35 | If you're interested in reviewig the APIs, [see the list here](https://docs.mbed.com/docs/api-documentation-list/en/latest/). 36 | 37 | ## Third party integeration 38 | 39 | Read about using mbed OS [with third party tools](https://docs.mbed.com/docs/third-party-integrations/en/latest/). 40 | 41 | ## mbed and the development community 42 | 43 | Learn how to [get help](http://mbed.com/en/development/community-help/) from other developers and on-line sources, and [engage with mbed](http://mbed.com/en/about-mbed/engage-with-us/). 44 | 45 | ## Partner program 46 | 47 | Learn about [our partners or become a partner](http://mbed.com/en/partners/). 48 | -------------------------------------------------------------------------------- /Docs/GetTheCode.md: -------------------------------------------------------------------------------- 1 | # Code resources 2 | 3 | ## Example applications 4 | 5 | These example applications can help you get started with various functions of mbed OS. 6 | 7 | !{https://raw.githubusercontent.com/ARMmbed/Sample_List/master/Docs/index.md} 8 | 9 | ## Key yotta modules 10 | 11 | If your'e interested in specific yotta modules: 12 | 13 | * [``mbed-drivers``](https://www.mbed.com/en/development/software/mbed-yotta/search/result/module/mbed-drivers/) is the heart of mbed OS. You can [review its documentation here](https://docs.mbed.com/docs/mbed-drivers-api/en/latest/api/index.html). 14 | 15 | * [``mbed-client``](https://www.mbed.com/en/development/software/mbed-yotta/search/result/module/mbed-client/) is best explored through its [getting started guide](https://docs.mbed.com/docs/mbed-client-guide/en/latest/). 16 | 17 | * [``mbedtls``](https://www.mbed.com/en/development/software/mbed-yotta/search/result/module/mbedtls/) is the mbed connectivity security module, and explored in greater detail in [the user guide chapter covering its use in mbed OS](Full_Guide/mbed_tls.md). 18 | 19 | * Some other modules that might interest you are [``sockets``](https://www.mbed.com/en/development/software/mbed-yotta/search/result/module/sockets/), [``ble``](https://www.mbed.com/en/development/software/mbed-yotta/search/result/module/ble/) and [``sal-stack-nanostack``](https://www.mbed.com/en/development/software/mbed-yotta/search/result/module/sal-stack-nanostack/) for connectivity. 20 | 21 | You can search for other modules [on our main site](https://www.mbed.com/en/development/software/mbed-yotta/). 22 | 23 | ## Key code repositories 24 | 25 | For a list of key code repositories and the documentation they contain, see [our main site](http://mbed.com/en/development/getting-started/get-code/). 26 | 27 | To view all mbed repositories, you can go directly to our [GitHub list](https://github.com/ARMmbed). 28 | -------------------------------------------------------------------------------- /Docs/GettingStartedmbedOS.md: -------------------------------------------------------------------------------- 1 | # mbed OS overview 2 | 3 | This section is a short introduction to mbed OS. It's followed by a sample application that you can build and run on your board. 4 | 5 | ## What's new with mbed: yotta build and registry 6 | 7 | We have created yotta: a command-line tool that takes care of building, assembling and distributing programs and libraries. It’s available on Mac, Windows and Linux. It will soon be integrated with popular desktop and cloud IDEs. 8 | 9 | yotta organises software into modules. A yotta module is a collection of source files with the addition of a file called ``module.json``. This file contains details such as the version, description, author, homepage, and a link to the repository containing the code. It also includes a list of other modules it depends on. You can use modules from many sources, including GitHub and other version control services. 10 | 11 | The yotta registry indexes public modules and you can search it for libraries from within the yotta command-line tool. 12 | 13 | To build a yotta program you can either create a new yotta executable or clone an existing one from a repository. Then set the target and run 'yotta build' from the command line. yotta pulls in the program’s dependencies from the web and generates the executable. Pretty cool, huh? 14 | 15 | For more information about yotta, see the [chapter about building mbed OS applications with yotta](Full_Guide/app_on_yotta/) or [a general review on our main site](http://mbed.com/en/development/software/tools/yotta/). 16 | 17 | ## Working with targets 18 | 19 | yotta can build the same application code for any supported target. So before you build anything with yotta, you select the target that you want to build for. 20 | 21 | The instructions for a particular development board tell you which target to use. You can also find target descriptions by searching the yotta registry. We review targets in more detail when we discuss [building mbed OS applications with yotta](Full_Guide/app_on_yotta/#yotta-targets). 22 | 23 | ## A first application 24 | 25 | 26 | Now that you've been briefed, you can jump on over to the next section and get started with [your first application](FirstProjectmbedOS.md). 27 | 28 | -------------------------------------------------------------------------------- /Docs/Images/bb-sketch-btn.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ARMmbed/GettingStartedmbedOS/12a5a0d5c1b8afadbe8e21be5906470ad7810bd3/Docs/Images/bb-sketch-btn.png -------------------------------------------------------------------------------- /Docs/Images/bb-sketch-led.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ARMmbed/GettingStartedmbedOS/12a5a0d5c1b8afadbe8e21be5906470ad7810bd3/Docs/Images/bb-sketch-led.png -------------------------------------------------------------------------------- /Docs/Images/bb01.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ARMmbed/GettingStartedmbedOS/12a5a0d5c1b8afadbe8e21be5906470ad7810bd3/Docs/Images/bb01.png -------------------------------------------------------------------------------- /Docs/Images/bb02.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ARMmbed/GettingStartedmbedOS/12a5a0d5c1b8afadbe8e21be5906470ad7810bd3/Docs/Images/bb02.png -------------------------------------------------------------------------------- /Docs/Images/bb03.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ARMmbed/GettingStartedmbedOS/12a5a0d5c1b8afadbe8e21be5906470ad7810bd3/Docs/Images/bb03.gif -------------------------------------------------------------------------------- /Docs/Images/bb04.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ARMmbed/GettingStartedmbedOS/12a5a0d5c1b8afadbe8e21be5906470ad7810bd3/Docs/Images/bb04.png -------------------------------------------------------------------------------- /Docs/about_mbed_os.md: -------------------------------------------------------------------------------- 1 | # Overview of mbed OS 2 | 3 | mbed OS is the operating system we created for mbed-enabled boards. It allows your C++ applications to run on these boards by providing APIs that you can use from your application to control the hardware. 4 | 5 | ## Features 6 | 7 | We designed mbed OS specifically for constrained devices, so it works behind the scenes to automatically make the most of the limited hardware and network resources available: 8 | 9 | * It's modular: it has a code base that is common to all applications running on all hardware, and additional modules that extend functionality and create hardware-specific interfaces. The modules are only compiled if your application needs them; you don't need to waste memory on unused code. 10 | 11 | * It's single-threaded and event-driven, so you can use it even on small devices. 12 | 13 | * It abstracts the hardware, so that an application always "sees" the same interface, no matter which board it's running on. mbed OS then matches the interface to the actual hardware without you manually changing the code. This allows you to write the application once, then deploy it on any supported board. mbed OS also works seamlessly with peripherals and extension boards. 14 | 15 | * It efficiently manages power and schedules tasks, so that even demanding applications can operate on low-power devices. 16 | 17 | * It manages both device and communication security using mbed OS uVisor and mbed TLS, respectively. 18 | 19 | * It supports multiple networking options: Bluetooth Low Energy, Ethernet, WiFi (coming soon), Thread and 6LoWPAN. 20 | 21 | * It works with device management protocols - LWM2M and CoAP - so that you can perform large-scale remote updates. 22 | 23 | mbed OS also works with other ARM mbed tools, like our testing tool (Greentea) and mbed Device Server. To learn more about these tools, see the [main site](https://www.mbed.com/en/). 24 | 25 | 26 | ## Code base 27 | 28 | As explained above, mbed OS is modular. This section gives a short review of the main modules. Some of these will be reviewed in greater detail later. 29 | 30 | ### Core modules 31 | 32 | * [_compiler-polyfill_](https://github.com/ARMmbed/compiler-polyfill): Common compiler intrinsics and attributes made portable across toolchains. 33 | 34 | * [_core-util_](https://github.com/ARMmbed/core-util): Core data structures and primitives for the OS. 35 | 36 | * [_minar_](https://github.com/ARMmbed/minar): The mbed OS event scheduler. 37 | 38 | * [_ualloc_](https://github.com/ARMmbed/ualloc) and [_dlmalloc_](https://github.com/ARMmbed/dlmalloc): Memory allocation for mbed OS. 39 | 40 | * [_uvisor_](https://github.com/ARMmbed/uvisor): mbed OS uVisor is a supervisory kernel for security on mbed OS. 41 | 42 | ### Hardware abstraction and drivers 43 | 44 | * [_mbed-drivers_](https://github.com/ARMmbed/mbed-drivers): Abstract drivers for common hardware peripherals and communications interfaces such as SPI and I2C. Provides a higher level interface than the mbed HAL; these are the APIs that applications should use. 45 | 46 | * [_cmsis-core_](https://github.com/ARMmbed/cmsis-core): ARM's official low level hardware abstraction for Cortex-M. 47 | 48 | * [_mbed-hal_](https://github.com/ARMmbed/mbed-hal): The mbed Hardware Abstraction Layer (HAL). 49 | 50 | ### Networking and connectivity 51 | 52 | * [_ble_](https://github.com/ARMmbed/ble): APIs for using Bluetooth Low Energy. 53 | 54 | * [_mbed-mesh-api_](https://github.com/ARMmbed/mbed-mesh-api): APIs for initialising and using the mesh network. 55 | 56 | * [_mbedtls_](https://github.com/ARMmbed/mbedtls): mbed TLS, the SSL/TLS stack (including cryptographic and certificates handling functionality). 57 | 58 | * [_sal_](https://github.com/ARMmbed/sal): The mbed OS socket abstraction layer (SAL). Provides a common interface for networking stacks from ARM and partners. 59 | 60 | * [_sal-stack-nanostack_](https://github.com/ARMmbed/sal-stack-nanostack): Our IPv6/6LoWPAN stack. 61 | 62 | * [_sockets_](https://github.com/ARMmbed/sockets): High level portable socket layer (sitting on top of the SAL). 63 | 64 | ### mbed Client 65 | 66 | * [_mbed-client-c_](https://github.com/ARMmbed/mbed-client-c): Core library in C. 67 | 68 | * [_mbed-client_](https://github.com/ARMmbed/mbed-client): C++ API (use this one rather than the C one, as it's much easier to use correctly). 69 | 70 | * [_mbed-client-mbed-os_](https://github.com/ARMmbed/mbed-client-mbed-os): mbed OS-specific implementation for mbed Client. 71 | 72 | * [_mbed-client-mbedtls_](https://github.com/ARMmbed/mbed-client-mbed-tls): mbed TLS-specific implementation for mbed Client. 73 | 74 | ## mbed OS and yotta 75 | 76 | yotta is the build system we use for mbed OS. We'll get into the details of it [later](Full_Guide/app_on_yotta.md), but what you need to understand at this point is that mbed OS applications cannot be built without yotta. 77 | 78 | yotta combines our code (application) with the mbed OS code-base and any other module (reusable library) that we may need. To tell yotta what our application needs, we add a list of dependencies to each application we write. The easiest way to add mbed OS to our application when we build it is to describe the component ``mbed-drivers`` as a dependency of our application, because ``mbed-drivers`` has most other components as its own dependencies, so yotta will build what we need. 79 | 80 | **Tip:** Some components must be manually included; we'll tell you about that when we review them in this guide. 81 | 82 | What this all means is that to build applications that can run on top of mbed OS, you need: 83 | 84 | * yotta. 85 | 86 | * mbed OS modules and optional additional libraries, which yotta gets for you. 87 | 88 | * Your own application code. 89 | 90 | 91 | ![](Full_Guide/Images/mbed_OS_app.png) 92 | 93 | **Note:** IDE support is not available yet. If you're interested in a particular IDE, talk to us on [the forum](http://forums.mbed.com). 94 | 95 | 96 | 97 | -------------------------------------------------------------------------------- /Docs/docker_install.md: -------------------------------------------------------------------------------- 1 | # yotta in a Docker container 2 | 3 | Docker containers let you run an application such as yotta, with all of its dependencies (like Python), without installing anything directly on your machine. This protects you from version conflicts and other installation problems. 4 | 5 | We’ve built a yotta Docker container and a bash script (``yotta.sh``), which allows you to use the yotta Docker container to mimic a yotta installation on your system; yotta will be fully functional. 6 | 7 | ## Prerequisites 8 | 9 | [Please install Docker](https://www.docker.com/docker-toolbox). 10 | 11 | ## Installation 12 | 13 | 1. Start Docker. 14 | 15 | 1. In the prompt, run: 16 | 17 | docker pull mbed/yotta 18 | 19 | 1. Save the [yotta.sh script](https://github.com/ARMmbed/yotta-docker/blob/master/yotta.sh) on your computer. You’ll need to refer to its path when you use it in Docker later, so remember where it is. 20 | 21 | ## Using the yotta Docker and script to build projects 22 | 23 | There is one difference between a regular installation and a Docker Container: in Docker, you have to precede each yotta command with the path to the bash script you saved in the previous section. For example: 24 | 25 | ```shell 26 | ..//yotta.sh target frdm-k64f-gcc //sets the target 27 | ..//yotta.sh build //builds our project 28 | ``` 29 | 30 | **Note:** If you saved your script under a name other than ```yotta.sh```, you may need to enter the script’s full name, including extension. Our example will become ``..// target frdm-k64f-gcc``. 31 | 32 | If you want to use yotta commands without specifying the full path to the script, you can add the yotta script’s path to your system’s ```path``` variable (Windows) or create a symbolic link (symlink) to your bin directory (Linux and Mac OS X). For example, to create a symlink: 33 | 34 | ``` 35 | ln -s /usr/local/bin/yotta 36 | ``` 37 | 38 | Now you can use yotta directly: 39 | 40 | ``` 41 | git clone 42 | cd 43 | yotta target frdm-k64f-gcc 44 | yotta build 45 | ``` 46 | 47 | ## Open Source 48 | 49 | The yotta Docker image is open source, so [feel free to fork it](https://github.com/ARMmbed/yotta-docker). 50 | -------------------------------------------------------------------------------- /Docs/index.md: -------------------------------------------------------------------------------- 1 | # The mbed OS 3 User Guide 2 | 3 | Welcome to the ARM® mbed™ OS 3 user guide. 4 | 5 | For mbed OS 5, please [see here](https://docs.mbed.com/docs/mbed-os-handbook/en/5.1/). 6 | 7 | ## Getting started 8 | 9 | * [Set up your machine](installation.md): Installing yotta, the build tool for mbed OS. 10 | 11 | * [Build your first mbed OS application](FirstProjectmbedOS.md): A simple example to get you going. 12 | 13 | * [Extend the first application](Extended_LED.md) and review [other samples](GetTheCode). 14 | 15 | * [Learn about mbed OS](about_mbed_os.md): A quick review of mbed OS features and code base, as well as its use of yotta. 16 | 17 | ## Applications on mbed OS 18 | 19 | A general review of how to write applications for mbed OS: 20 | 21 | * [mbed OS applications with yotta](Full_Guide/app_on_yotta.md): The relationship between yotta and mbed OS, and how you can create yotta-based mbed OS applications. 22 | 23 | * [Writing applications for mbed OS](Full_Guide/app_on_mbed_os.md): Some general principles of mbed OS applications. 24 | 25 | ## mbed OS features 26 | 27 | These chapters explain how to work with the various mbed OS features: 28 | 29 | * [Interfacing to hardware](Full_Guide/Interfacing.md): How mbed OS controls different hardware. 30 | 31 | * [Debugging mbed OS applications](Full_Guide/Debugging.md): Debugging for applications built with ARMCC and GCC. 32 | 33 | * [Security with mbed TLS](Full_Guide/mbed_tls.md): Using mbed TLS for communication security in mbed OS. 34 | 35 | * [Asynchronous programming with MINAR](Full_Guide/MINAR.md): Using the mbed OS schedular MINAR for asynchronous programming. 36 | 37 | * [Memory in mbed OS](Full_Guide/memory.md): Memory management and allocation in mbed OS. 38 | 39 | * [Networking with mbed OS](Full_Guide/networking.md): Networking options and structure on mbed OS. 40 | 41 | * [Asynchronous I2C](Full_Guide/I2C.md): Two-wire serial bus protocol on mbed OS. 42 | 43 | ## Contributing to mbed OS and publishing modules 44 | 45 | * [Creating and publishing your own modules and contributing to mbed OS](Full_Guide/contributing.md): The process and legal requirements for publishing modules as stand-alone or as part of the mbed OS code base. 46 | 47 | * [Coding style and GitHub pull request guidelines](Full_Guide/Code_Style.md): Style guidelines for code and GitHub pull requests. 48 | 49 | ## What you need to know before reading the guide 50 | 51 | This guide assumes that you are familiar with C++. While we do discuss how we applied some concepts in mbed OS, we don't explain the background to these concepts in any great detail. If you know C but not C++, you might find this [Coursera module](https://www.coursera.org/course/cplusplus4c) helpful. 52 | 53 | The examples in this guide focus on the FRDM-K64F board. If you have another board, you'll have to check if it's already [supported on mbed OS](https://www.mbed.com/en/development/hardware/boards/) before you run the sample code. You should be able to follow the code and explanations even if you don't have compatible hardware. 54 | 55 | ### Additional sources 56 | 57 | * [Further reading sources](FurtherReading.md): other mbed tools, hardware, community and partners. 58 | 59 | * Links to [our main code repositories and their documentation, as well as examples](GetTheCode.md). 60 | 61 | **Tip:** For more details about mbed, [see our main site](http://mbed.com/en/about-mbed/what-mbed/). 62 | 63 | 64 | -------------------------------------------------------------------------------- /Docs/installation.md: -------------------------------------------------------------------------------- 1 | # Installing mbed OS and yotta 2 | 3 | For mbed OS 5, please [see here](https://docs.mbed.com/docs/mbed-os-handbook/). 4 | 5 | Like many open source operating systems, mbed OS is distributed as source code. You use yotta to fetch all the modules that you require to build for your hardware. Once you’ve done that, yotta works as an offline build tool that combines mbed OS and your application code into a single executable. All this means that you don't install mbed OS on your computer - you simply install yotta, and let it work for you. 6 | 7 | There are three ways to install yotta: 8 | 9 | * [Our installers](#installers), which include the yotta dependencies. 10 | 11 | * [A Docker container](#docker-container), which includes the yotta dependencies. 12 | 13 | * [Manual installation](#manual-installation) of yotta and all its dependencies. 14 | 15 | ## Installers 16 | 17 | yotta has installers for OS X and Windows. They include an installation of all yotta dependencies. 18 | 19 | ### OS X installer 20 | 21 | 1. Download the latest [OS X yotta.app](https://www.mbed.com/en/development/software/mbed-yotta/#Installing_yotta). 22 | 23 | 1. Drag ``yotta.app`` from the disk image into your Applications folder. 24 | 25 | 1. When you run ``yotta.app``, it opens a terminal where you can use yotta commands. 26 | 27 | ### Windows installer 28 | 29 | 1. Download the latest [yotta Windows installer](https://www.mbed.com/en/development/software/mbed-yotta/#Installing_yotta). 30 | 31 | 1. Run the installer. 32 | 33 | 1. Click the ``Run Yotta`` shortcut on the desktop or in the start menu to run a session with the yotta path temporarily pre-pended to system path. 34 | 35 | ## Docker container 36 | 37 | [See the Docker container instructions](docker_install.md). 38 | 39 | ## Manual installation 40 | 41 | If you want to manually install yotta, please ensure you have your dependencies, then follow the instructions for your operating system. 42 | 43 | ### Dependencies 44 | 45 | Before installing yotta, make sure you have: 46 | 47 | * [Python 2.7](https://www.python.org/download/releases/2.7/). Python 3 support is experimental. 48 | 49 | * [pip](https://pypi.python.org/pypi/pip). 50 | 51 | ### Manual installation instructions 52 | 53 | * [OS X](http://yottadocs.mbed.com/#installing-on-osx). 54 | 55 | * [Windows](http://yottadocs.mbed.com/#installing-on-windows). 56 | 57 | * [Linux](http://yottadocs.mbed.com/#installing-on-linux). 58 | 59 | ## What's next? 60 | 61 | Try the [Blinky quick guide](FirstProjectmbedOS.md) to get a first sample application working, or see the [full list of samples](GetTheCode.md). 62 | 63 | You can also read the [full guide](Full_Guide/app_on_yotta.md) to understand how mbed OS and yotta work together. 64 | -------------------------------------------------------------------------------- /mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: mbed OS 3.0 Guides 2 | 3 | docs_dir: Docs 4 | 5 | pages: 6 | - ['index.md','Welcome to the mbed OS 3.0 User Guides'] 7 | - ['about_mbed_os.md','Overview of mbed OS 3.0'] 8 | - ['installation.md', 'Getting Started', 'Installation'] 9 | - ['FirstProjectmbedOS.md', 'Getting Started', 'Blinky - your first application'] 10 | - ['Extended_LED.md', 'Getting Started', 'Extending Blinky'] 11 | - ['GetTheCode.md', 'Getting Started', 'Additional examples and code'] 12 | - ['Full_Guide/app_on_yotta.md', 'Applications on mbed OS', 'mbed OS applications with yotta'] 13 | - ['Full_Guide/app_on_mbed_os.md', 'Applications on mbed OS', 'Writing applications for mbed OS'] 14 | - ['Full_Guide/Interfacing.md', 'mbed OS features', 'Interfacing to hardware'] 15 | - ['Full_Guide/Debugging.md', 'mbed OS features', 'Debugging mbed OS applications'] 16 | - ['Full_Guide/mbed_tls.md', 'mbed OS features', 'Security with mbed TLS'] 17 | - ['Full_Guide/MINAR.md', 'mbed OS features', 'Asynchronous programming with MINAR'] 18 | - ['Full_Guide/memory.md', 'mbed OS features', 'Memory in mbed OS'] 19 | - ['Full_Guide/networking.md', 'mbed OS features', 'Networking in mbed OS'] 20 | - ['Full_Guide/I2C.md', 'mbed OS features', 'Asynchronous I2C'] 21 | - ['Full_Guide/contributing.md', 'Contributing and publishing', 'Module publishing guidelines'] 22 | - ['Full_Guide/Code_Style.md', 'Contributing and publishing', 'Code style and GitHub'] 23 | - ['FurtherReading.md', 'Additional Resources', 'Further reading'] 24 | 25 | --------------------------------------------------------------------------------