1) Updated blinky for arduino zero, arduino primo, olimex, nRF52 - Removed features, updated paths, general cleanup to make tutorials more consistent 2) Use updated olimex diagrams that include power input select jumper location so user can configure power source from JTAG/SWD 3) Fix typo in bleprph tutorial. 4) Updated Concepts section to use updated newt target -h output 5) Updated newt install for Mac and linux to use updated newt -h output. 6) Updated newt install for linux to install GO version 1.6 7) Remove duplicate instance of Air Quality Sensor project from document tree 8) Removed embedded LUA from doc tree. 9) Fix newtmgr echo and mpstats output for slinky_sim tutorial.
Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/commit/c37f02b9 Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/c37f02b9 Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/c37f02b9 Branch: refs/heads/develop Commit: c37f02b90b4e8b3a28efe3979c80a0874d81cc41 Parents: df02a73 Author: cwanda <[email protected]> Authored: Thu Mar 23 17:27:57 2017 -0700 Committer: cwanda <[email protected]> Committed: Thu Mar 23 18:24:14 2017 -0700 ---------------------------------------------------------------------- docs/newt/install/newt_linux.md | 72 +++-- docs/newt/install/newt_mac.md | 67 +++-- docs/os/get_started/vocabulary.md | 18 +- docs/os/tutorials/arduino_zero.md | 285 +++++++++---------- docs/os/tutorials/bleprph/bleprph-app.md | 2 +- docs/os/tutorials/blinky_primo.md | 171 ++++++----- docs/os/tutorials/nRF52.md | 168 ++++++----- docs/os/tutorials/olimex.md | 196 +++++++------ docs/os/tutorials/pics/STM32-E407_bot_small.jpg | Bin 0 -> 140793 bytes docs/os/tutorials/pics/STM32-E407_top_small.jpg | Bin 0 -> 165366 bytes docs/os/tutorials/project-slinky.md | 47 +-- mkdocs.yml | 8 - 12 files changed, 567 insertions(+), 467 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c37f02b9/docs/newt/install/newt_linux.md ---------------------------------------------------------------------- diff --git a/docs/newt/install/newt_linux.md b/docs/newt/install/newt_linux.md index f8147c4..89be99a 100644 --- a/docs/newt/install/newt_linux.md +++ b/docs/newt/install/newt_linux.md @@ -48,7 +48,7 @@ If you want to build the *newt* tool from its source code, follow the following * Next, install Go. When installed, Go offers you as a developer a language environment (to compile Go code), construct Go packages (to assemble Go packages) and import Go code (from github). In the next step, you will use the Go commands to import *newt* repo into your local Go environment. - **Note**: The Newt tool requires Go version 1.5 or later. It uses the support for "vendoring" that was added in Go 1.5. Depending on the Ubuntu version you have, the following may install an earlier version. In that case, download the latest package of Go 1.5 or 1.6 from [https://golang.org/dl/](https://golang.org/dl/). You can search for more detailed instructions such as installing Go 1.6 on Ubuntu 14.04 which can be found at [https://www.digitalocean.com/community/tutorials/how-to-install-go-1-6-on-ubuntu-14-04](https://www.digitalocean.com/community/tutorials/how-to-install-go-1-6-on-ubuntu-14-04). + **Note**: The Newt tool requires Go version 1.6 or later. Depending on the Ubuntu version you have, the following may install an earlier version. In that case, download the latest package of Go 1.6 from [https://golang.org/dl/](https://golang.org/dl/). You can search for more detailed instructions such as installing Go 1.6 on Ubuntu 14.04 which can be found at [https://www.digitalocean.com/community/tutorials/how-to-install-go-1-6-on-ubuntu-14-04](https://www.digitalocean.com/community/tutorials/how-to-install-go-1-6-on-ubuntu-14-04). ```no-highlight $ sudo apt-get install golang @@ -92,48 +92,60 @@ If you want to build the *newt* tool from its source code, follow the following (Note: If you are going to be modifying the *newt* often and going to be compile the program every time you call it, you will want to store the command in a variable in your .bash_profile. So type in `export newt="go run $GOPATH/mynewt.apache.org/newt/newt/newt.go"` in your .bash_profile and execute it by calling `$newt` at the prompt instead of `newt`. Essentially, `$newt` calls `go run` which runs the compiled binary directly without producing an executable. Don't forget to reload the updated bash profile by typing `source ~/.bash_profile` at the prompt! ) -``` +```no-highlight $ newt version Newt version: 1.0 $ newt -h - Newt allows you to create your own embedded project based on the Mynewt - operating system. Newt provides both build and package management in a - single tool, which allows you to compose an embedded workspace, and set - of projects, and then build the necessary artifacts from those projects. - For more information on the Mynewt operating system, please visit - https://www.github.com/mynewt/documentation. + Newt allows you to create your own embedded application based on the Mynewt + operating system. Newt provides both build and package management in a single + tool, which allows you to compose an embedded application, and set of + projects, and then build the necessary artifacts from those projects. For more + information on the Mynewt operating system, please visit + https://mynewt.apache.org/. - Please use the newt help command, and specify the name of the command - you want help for, for help on how to use a specific command + Please use the newt help command, and specify the name of the command you want + help for, for help on how to use a specific command Usage: - newt [flags] - newt [command] + newt [flags] + newt [command] Examples: - newt - newt help [<command-name>] - For help on <command-name>. If not specified, print this message. - + newt + newt help [<command-name>] + For help on <command-name>. If not specified, print this message. Available Commands: - version Display the Newt version number. - target Set and view target information - egg Commands to list and inspect eggs on a nest - nest Commands to manage nests & clutches (remote egg repositories) - help Help about any command + build Build one or more targets + clean Delete build artifacts for one or more targets + create-image Add image header to target binary + debug Open debugger session to target + info Show project info + install Install project dependencies + load Load built target to board + mfg Manufacturing flash image commands + new Create a new project + pkg Create and manage packages in the current workspace + run build/create-image/download/debug <target> + size Size of target components + sync Synchronize project dependencies + target Commands to create, delete, configure, and query targets + test Executes unit tests for one or more packages + upgrade Upgrade project dependencies + vals Display valid values for the specified element type(s) + version Display the Newt version number Flags: - -h, --help=false: help for newt - -l, --loglevel="WARN": Log level, defaults to WARN. - -q, --quiet=false: Be quiet; only display error output. - -s, --silent=false: Be silent; don't output anything. - -v, --verbose=false: Enable verbose output when executing commands. - - - Use "newt help [command]" for more information about a command. + -h, --help Help for newt commands + -j, --jobs int Number of concurrent build jobs (default 8) + -l, --loglevel string Log level (default "WARN") + -o, --outfile string Filename to tee output to + -q, --quiet Be quiet; only display error output + -s, --silent Be silent; don't output anything + -v, --verbose Enable verbose output when executing commands + + Use "newt [command] --help" for more information about a comma ``` - <br> #### 5. Updating the Newt tool http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c37f02b9/docs/newt/install/newt_mac.md ---------------------------------------------------------------------- diff --git a/docs/newt/install/newt_mac.md b/docs/newt/install/newt_mac.md index f1eb586..8b10e57 100644 --- a/docs/newt/install/newt_mac.md +++ b/docs/newt/install/newt_mac.md @@ -101,42 +101,55 @@ If you want to build the *newt* tool from its source code, follow the following $ newt version Newt version: 1.0 $ newt -h - Newt allows you to create your own embedded project based on the Mynewt - operating system. Newt provides both build and package management in a - single tool, which allows you to compose an embedded workspace, and set - of projects, and then build the necessary artifacts from those projects. - For more information on the Mynewt operating system, please visit - https://www.github.com/mynewt/documentation. + Newt allows you to create your own embedded application based on the Mynewt + operating system. Newt provides both build and package management in a single + tool, which allows you to compose an embedded application, and set of + projects, and then build the necessary artifacts from those projects. For more + information on the Mynewt operating system, please visit + https://mynewt.apache.org/. - Please use the newt help command, and specify the name of the command - you want help for, for help on how to use a specific command + Please use the newt help command, and specify the name of the command you want + help for, for help on how to use a specific command Usage: - newt [flags] - newt [command] + newt [flags] + newt [command] Examples: - newt - newt help [<command-name>] - For help on <command-name>. If not specified, print this message. - + newt + newt help [<command-name>] + For help on <command-name>. If not specified, print this message. Available Commands: - version Display the Newt version number. - target Set and view target information - egg Commands to list and inspect eggs on a nest - nest Commands to manage nests & clutches (remote egg repositories) - help Help about any command + build Build one or more targets + clean Delete build artifacts for one or more targets + create-image Add image header to target binary + debug Open debugger session to target + info Show project info + install Install project dependencies + load Load built target to board + mfg Manufacturing flash image commands + new Create a new project + pkg Create and manage packages in the current workspace + run build/create-image/download/debug <target> + size Size of target components + sync Synchronize project dependencies + target Commands to create, delete, configure, and query targets + test Executes unit tests for one or more packages + upgrade Upgrade project dependencies + vals Display valid values for the specified element type(s) + version Display the Newt version number Flags: - -h, --help=false: help for newt - -l, --loglevel="WARN": Log level, defaults to WARN. - -q, --quiet=false: Be quiet; only display error output. - -s, --silent=false: Be silent; don't output anything. - -v, --verbose=false: Enable verbose output when executing commands. - - - Use "newt help [command]" for more information about a command. + -h, --help Help for newt commands + -j, --jobs int Number of concurrent build jobs (default 8) + -l, --loglevel string Log level (default "WARN") + -o, --outfile string Filename to tee output to + -q, --quiet Be quiet; only display error output + -s, --silent Be silent; don't output anything + -v, --verbose Enable verbose output when executing commands + + Use "newt [command] --help" for more information about a comma ``` <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c37f02b9/docs/os/get_started/vocabulary.md ---------------------------------------------------------------------- diff --git a/docs/os/get_started/vocabulary.md b/docs/os/get_started/vocabulary.md index f35f019..6401d55 100644 --- a/docs/os/get_started/vocabulary.md +++ b/docs/os/get_started/vocabulary.md @@ -32,7 +32,7 @@ project.repositories: # repository.apache-mynewt-core: type: github - vers: 0-latest + vers: 1-latest user: apache repo: incubator-mynewt-core $ @@ -46,9 +46,9 @@ relies upon. * ```repository.apache-mynewt-core```: Defines the repository information for the ```apache-mynewt-core``` repository. -* ```vers=0-latest```: Defines the repository version. This string will use the +* ```vers=1-latest```: Defines the repository version. This string will use the latest code in the 'Master' github branch. To use the latest version in the -develop branch, just change it to ```vers=0-dev``` +develop branch, just change it to ```vers=1-dev``` Repositories are versioned collections of packages. @@ -134,20 +134,25 @@ In order to create and manipulate targets, the *newt* tool offers a set of helpe you can find more information about these by issuing: $ newt target -```no-highligh +```no-highlight +newt target Usage: newt target [flags] newt target [command] Available Commands: - config View target system configuration + config View or populate a target's system configuration copy Copy target create Create a target delete Delete target + dep View target's dependency graph + revdep View target's reverse-dependency graph set Set target configuration variable show View target configuration variables Global Flags: + -h, --help Help for newt commands + -j, --jobs int Number of concurrent build jobs (default 8) -l, --loglevel string Log level (default "WARN") -o, --outfile string Filename to tee output to -q, --quiet Be quiet; only display error output @@ -155,6 +160,7 @@ Global Flags: -v, --verbose Enable verbose output when executing commands Use "newt target [command] --help" for more information about a command. + $ ``` @@ -168,7 +174,7 @@ directory rather than editing the package configurations directly. To see all **all** the system configuration settings, simply type ```no-highlight -$ newt target config <target-name> +$ newt target config show <target-name> ... * PACKAGE: sys/stats * Setting: STATS_CLI http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c37f02b9/docs/os/tutorials/arduino_zero.md ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/arduino_zero.md b/docs/os/tutorials/arduino_zero.md index d37b280..78af86f 100644 --- a/docs/os/tutorials/arduino_zero.md +++ b/docs/os/tutorials/arduino_zero.md @@ -5,19 +5,16 @@ Learn how to use packages from a default application repository of Mynewt to bui This tutorial describes how to run Mynewt OS on Arduino Zero. Follow these simple steps and your board will be blinking in no time! ### Prerequisites +Ensure that you have met the following prerequisites before continuing with this tutorial: -Before tackling this tutorial, it's best to read about Mynewt in the [Introduction](../get_started/get_started) section of this documentation. - -### Equipment - -You will need the following equipment - -* An Arduino Zero board. NOTE: There are many flavors of Arduino. Ensure that -you have an Arduino Zero. See below for the versions of Arduino Zero that are -compatible with this tutorial -* A computer that can connect to the Arduino Zero over USB -* A USB cable (Type A to micro B) that can connect the computer to the Arduino -* The Mynewt Release +* Have an Arduino Zero board. +Note: There are many flavors of Arduino. Make sure you are using an Arduino Zero. See below for the versions of Arduino Zero that are compatible with this tutorial. +* Have Internet connectivity to fetch remote Mynewt components. +* Have a Micro-USB cable to connect the board and the computer. +* Have a computer to build a Mynewt application and connect to your board over USB. +* Install the Newt tool and toolchains (See [Basic Setup](/os/get_started/get_started.md)). +* Create a project space (directory structure) and populated it with the core code repository (apache-mynewt-core) or know how to as explained in [Creating Your First Project](/os/get_started/project_create). +* Read the Mynewt OS [Concepts](/os/get_started/vocabulary.md) section. This tutorial has been tested on the following three Arduino Zero boards - Zero, M0 Pro, and Zero-Pro. @@ -27,14 +24,29 @@ This tutorial has been tested on the following three Arduino Zero boards - Zero, Mynewt has not been tested on Arduino M0 which has no internal debugger support. -### Install Mynewt and Newt +<br> + +### Create a Project +Create a new project if you do not have an existing one. You can skip this step and proceed to [fetch external packages](#fetchexternal) if you already created a project. -* If you have not already done so, install Newt as shown in the [Newt install tutorial](../../newt/install/newt_mac.md) -* If you have not already done so, create a project as shown in the Quick Start guide on how to [Create Your First Project](../get_started/project_create.md). Skip the testing and building the project steps in that tutorial since you will be defining a target for your Arduino board in this tutorial. +Run the following commands to create a new project: + +```no-highlight + $ mkdir ~/dev + $ cd ~/dev + $ newt new myproj + Downloading project skeleton from apache/incubator-mynewt-blinky... + Installing skeleton in myproj... + Project myproj successfully created. + $ cd myproj + $ newt install + apache-mynewt-core + $ +``` <br> -### Fetch External Packages +###<a name="fetchexternal"></a> Fetch External Packages Mynewt uses source code provided directly from the chip manufacturer for low level operations. Sometimes this code is licensed only for the specific manufacturer of the chipset and cannot live in the Apache Mynewt repository. That happens to be the case for the Arduino Zero board which uses Atmel SAMD21. Runtime's github repository hosts such external third-party packages and the Newt tool can fetch them. @@ -56,24 +68,20 @@ project.repositories: repository.apache-mynewt-core: type: github - vers: 0-latest + vers: 1-latest user: apache repo: incubator-mynewt-core repository.mynewt_arduino_zero: type: github - vers: 0-latest + vers: 1-latest user: runtimeinc repo: mynewt_arduino_zero $ ``` <br> - -Once you've edited your ```project.yml``` file, the next step is to install the -project dependencies, this can be done with the ```newt install``` command -(to see more output, provide the ```-v``` verbose option.): - +Install the project dependencies using the `newt install` command (You can specify ```-v``` for verbose output): ```no-highlight $ newt install apache-mynewt-core @@ -83,16 +91,13 @@ $ <br> -**NOTE:** If there has been a new release of a repo used in your project since you last installed it, the `0-latest` version for the repo in the `project.yml` file will refer to the new release and will not match the installed files. In that case you will get an error message saying so and you will need to run `newt upgrade` to overwrite the existing files with the latest codebase. +**NOTE:** If there has been a new release of a repo used in your project since you last installed it, the `1-latest` version for the repo in the `project.yml` file will refer to the new release and will not match the installed files. In that case you will get an error message saying so and you will need to run `newt upgrade` to overwrite the existing files with the latest codebase. <br> - -### Create your bootloader target - -Next, you need to tell Newt what to build. For the Arduino Zero, we are going to -generate both a bootloader, and an image target. - -To generate the bootloader target, you need to specify the following options. The output of the commands (indicating success) have been suppressed for easier readability. +### Create a Target for the Bootloader +You need to create two targets, one for the bootloader and one for the Blinky application. +<br> +Run the following `newt target` commands, from your project directory (ex. ~/dev/myproj), to create a bootloader target for the Arduino Zero Pro board. We name the target `arduino_boot`. ```no-highlight $ newt target create arduino_boot @@ -105,12 +110,11 @@ Target targets/arduino_boot successfully set target.build_profile to optimized $ newt target set arduino_boot syscfg=BSP_ARDUINO_ZERO_PRO=1 Target targets/arduino_boot successfully set target.syscfg to BSP_ARDUINO_ZERO_PRO=1 ``` +**Note:** If you have an Arduino Zero instead of a Arduino Zero Pro board, replace `BSP_ARDUINO_ZERO_PRO` with `BSP_ARDUINO_ZERO` in the last `newt target set` command. -<br> - -These commands do a few things: +These commands perform the following: - * Create a target named ```arduino_boot```, in order to build the Arduino Zero Bootloader. + * Create a target named ```arduino_boot``` for the Arduino Zero Bootloader. * Set the application for the ```arduino_boot``` target to the default Apache Mynewt bootloader (```@apache-mynewt-core/apps/boot```) * Set the board support package for the target to @@ -119,66 +123,14 @@ These commands do a few things: * Use the "optimized" build profile for the `arduino_boot` target. This instructs Newt to generate smaller and more efficient code for this target. This setting is necessary due to the bootloader's strict size constraints. - * Tells the Board Support Package to enable support for the Arduino Zero Pro or the Arduino Zero. Set it to `arduino_zero` or `arduino_zero_pro` depending on the board you have. + * Sets the system configuration setting for Board Support Package to support the Arduino Zero Pro. +See the [Concepts](../get_started/vocabulary.md) section for more information on setting options. <br> - -If you'd rather, you can also take care of that last part by editing the `syscfg.yml` file -for the target to set options -- at least one that is *required*. -Look in the directory for the target, as defined by the target (in this case `targets/arduino_boot`) -and edit the syscfg.yml file. It should look like this when you're done: +###Create a Target for the Blinky Application +Run the following `newt target` commands to create your Blinky application target. We name the application target `arduino_blinky`. ```no-highlight -### Package: targets/arduino_boot - -syscfg.vals: - BSP_ARDUINO_ZERO_PRO: 1 - - -``` - -If you have an Arduino Zero Pro or M0 Pro, you'll want `BSP_ARDUINO_ZEZRO_PRO: 1`. If you have the Arduino Zero, -you'll want `BSP_ARDUINO_ZERO: 1` instead. - -For more information on setting options, see the section on [Concepts](../get_started/vocabulary.md). - -For now, we're not going to set any more options or enable any more features of Mynewt OS. - -<br> - -### Build your bootloader - -Once you've configured the bootloader target, the next step is to build the bootloader for your Arduino. You can do this by using the ```newt build``` command: - -```no-highlight -$ newt build arduino_boot -Compiling asprintf.c -Compiling atoi.c -Compiling atol.c -Compiling atoll.c -Compiling bsearch.c -Compiling bzero.c -Compiling calloc.c -Compiling fgets.c -Compiling inline.c -<snip> -App successfully built: myproject/bin/arduino_boot/apps/boot/boot.elf -``` - -If this command finishes successfully, you have successfully built the Arduino -bootloader, and the next step is to build your application for the Arduino -board. - -<br> - -### Build your blinky app - -To create and download your application, you create another target, this one pointing to the application you want to download to the Arduino board. -In this tutorial, we will use the default application that comes with your project, ```apps/blinky```: - -**Note**: Remember to set features to `arduino_zero` if your board is Arduino Zero and not a Pro! - -```hl_lines="9" $ newt target create arduino_blinky Target targets/arduino_blinky successfully created $ newt target set arduino_blinky app=apps/blinky @@ -187,63 +139,98 @@ $ newt target set arduino_blinky bsp=@mynewt_arduino_zero/hw/bsp/arduino_zero Target targets/arduino_blinky successfully set target.bsp to @mynewt_arduino_zero/hw/bsp/arduino_zero $ newt target set arduino_blinky build_profile=debug Target targets/arduino_blinky successfully set target.build_profile to debug -$ newt target set arduino_blinky features=arduino_zero_pro -Target targets/arduino_blinky successfully set pkg.features to arduino_zero_pro +$ newt target set arduino_blinky syscfg=BSP_ARDUINO_ZERO_PRO=1 +Target targets/arduino_boot successfully set target.syscfg to BSP_ARDUINO_ZERO_PRO=1 $ ``` +**Note:** If you have an Arduino Zero instead of a Arduino Zero Pro board, replace `BSP_ARDUINO_ZERO_PRO` with `BSP_ARDUINO_ZERO` in the last `newt target set` command. <br> -You can now build the target, with ```newt build```: + +### Build the Bootloader + +Run the `newt build arduino_boot` command to build a bootloader for your arduino board: ```no-highlight -$ newt build arduino_blinky -Compiling main.c -Archiving blinky.a -Compiling cons_fmt.c -Compiling cons_tty.c -Archiving full.a -Compiling case.c -Compiling suite.c -Compiling testutil.c -Archiving testutil.a -<snip> -App successfully built: myproject/bin/arduino_blinky/apps/blinky/blinky.elf -``` -<font color="#FF0000"> Congratulations! </font> You have successfully built your application. Now it's time to load both the bootloader and application onto the target. +$ newt build arduino_boot +Building target targets/arduino_boot +Compiling bin/targets/arduino_boot/generated/src/arduino_boot-sysinit-app.c +Compiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c +Compiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c +Compiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c +Compiling bin/targets/arduino_boot/generated/src/arduino_boot-sysflash.c +Compiling repos/apache-mynewt-core/boot/bootutil/src/image_validate.c +Compiling repos/apache-mynewt-core/boot/bootutil/src/bootutil_misc.c +Compiling repos/apache-mynewt-core/apps/boot/src/boot.c +Compiling repos/apache-mynewt-core/crypto/mbedtls/src/arc4.c +Compiling repos/apache-mynewt-core/boot/bootutil/src/loader.c +Compiling repos/apache-mynewt-core/crypto/mbedtls/src/aes.c + + .... + +Archiving sys_mfg.a +Archiving sys_sysinit.a +Archiving util_mem.a +Linking ~/dev/myproj/bin/targets/arduino_boot/app/apps/boot/boot.elf +Target successfully built: targets/arduino_boot +``` <br> -### Connect the Target + +### Build the Blinky Application + +Run the `newt build arduino_blinky` command to build your Blinky application image: + +```no-highlight +$ newt build arduino_blinky +Building target targets/arduino_blinky +Compiling repos/apache-mynewt-core/hw/hal/src/hal_flash.c +Compiling apps/blinky/src/main.c +Compiling repos/mynewt_arduino_zero/hw/mcu/atmel/samd21xx/src/sam0/drivers/i2s/i2s.c +Compiling repos/mynewt_arduino_zero/hw/bsp/arduino_zero/src/hal_bsp.c +Compiling repos/mynewt_arduino_zero/hw/mcu/atmel/samd21xx/src/sam0/drivers/i2s/i2s_callback.c +Compiling repos/mynewt_arduino_zero/hw/mcu/atmel/samd21xx/src/sam0/drivers/nvm/nvm.c + + ... + +Archiving sys_mfg.a +Archiving sys_sysinit.a +Archiving util_mem.a +Linking ~/dev/myproj/bin/targets/arduino_blinky/app/apps/blinky/blinky.elf +Target successfully built: targets/arduino_blinky +``` +<br> +### Connect to the Board Connect your computer to the Arduino Zero (from now on we'll call this the -target) with the Micro-USB cable through the Programming Port as shown below. -Mynewt will download and debug the target through this port. You should see a +target) with a Micro-USB cable through the Programming Port as shown below. +Mynewt will load the image onto the board and debug the target through this port. You should see a little green LED come on. That means the board has power. No external debugger is required. The Arduino Zero comes with an internal debugger that can be accessed by Mynewt. -A image below shows the Arduino Zero Programming Port. +The images below show the Arduino Zero Programming Port. <img src="https://www.arduino.cc/en/uploads/Main/Zero_Usb_Ports.jpg"; alt="Drawing" style="width: 400px;"/> <img src="http://www.arduino.org//images/products/ArduinoZeroPro-flat-org.jpg"; alt="Drawing" style="width: 330px;"/> <br> -### Download the Bootloader +### Load the Bootloader onto the Board -Execute the command to download the bootloader. +Run the `newt load arduino_boot` command to load the bootloader onto your board: -```c - $ newt load arduino_boot +```no-highlight +$ newt load arduino_boot +Loading bootloader +$ ``` +The bootloader is loaded onto your board succesfully when the `newt load` command returns to the command prompt with no messages. You can proceed to load and run your Blinky application image (See [Run the Blinky Application](#runimage)). -If the newt tool finishes without error, that means the bootloader has been -successfully loaded onto the target. - -If, on the other hand, you get errors like the following: - +If the `newt load` command outputs the following error messages, you will need to erase your board. ``` $ newt load arduino_boot -v Loading bootloader @@ -267,13 +254,10 @@ Info : SWD IDCODE 0x0bc11477 Info : at91samd21g18.cpu: hardware has 4 breakpoints, 2 watchpoints Error: Target not halted ``` - -Then you'll need to erase your board first before downloading the `arduino_boot` application. Here's how you do that using gdb, -the GNU Debugger. - -```gdb +<br> +To erase your board, start a debug session and enter the highlighted commands at the `(gdb)` prompts: +```hl_lines="2, 5, 14" $ newt debug arduino_blinky - (gdb) mon at91samd chip-erase chip erased chip erased @@ -288,32 +272,27 @@ chip erased 0x70: 0xffffffff 0xffffffff 0xffffffff 0xffffffff (gdb) q ``` - -Once the chip is erased, go back and download the `arduino_boot` image to the board as above. - <br> +Run the `newt load arduino_boot` command again after erasing the board. <font color="#FF0000"> Reminder if you are using Docker: </font> When working with actual hardware, remember that each board has an ID. If you swap boards and do not refresh the USB Device Filter on the VirtualBox UI, the ID might be stale and the Docker instance may not be able to see the board correctly. For example, you may see an error message like `Error: unable to find CMSIS-DAP device` when you try to load or run an image on the board. In that case, you need to click on the USB link in VirtualBox UI, remove the existing USB Device Filter (e.g. "Atmel Corp. EDBG CMSIS-DAP[0101]") by clicking on the "Removes selected USB filter" button, and add a new filter by clicking on the "Adds new USB filter" button. <br> -### Run the Image +### <a name="runimage"></a>Run the Blinky Application -Now that the bootloader is downloaded to the target, the next step is to load -your image onto the Arduino Zero. The easiest way to do this, is to use the -```newt run``` command. ```newt run``` will automatically rebuild your program -(if necessary), create an image, and load it onto the target device. - -Here, we will load our ```arduino_blinky``` target onto the device, and we -should see it run: +After you load the bootloader successfully onto your board, you can load and run the Blinky application. +Run the `newt run arduino_blinky 0.0.0` command to build the arduino_blinky target (if necessary), create an image with verison 0.0.0, load the image onto the board, and start a debugger session. ```no-highlight $ newt run arduino_blinky 0.0.0 -Debugging myproject/bin/arduino_blinky/apps/blinky/blinky.elf -Open On-Chip Debugger 0.9.0 (2015-09-23-21:46) +App image succesfully generated: ~/dev/myproj/bin/targets/arduino_blinky/app/apps/blinky/blinky.img +Loading app image into slot 1 +[~/dev/myproj/repos/mynewt_arduino_zero/hw/bsp/arduino_zero/arduino_zero_debug.sh ~/dev/myproj/repos/mynewt_arduino_zero/hw/bsp/arduino_zero ~/dev/myproj/bin/targets/arduino_blinky/app/apps/blinky/blinky] +Open On-Chip Debugger 0.9.0 (2015-11-15-13:10) Licensed under GNU GPL v2 For bug reports, read - http://openocd.org/doc/doxygen/bugs.html +http://openocd.org/doc/doxygen/bugs.html Info : only one transport option; autoselect 'swd' adapter speed: 500 kHz adapter_nsrst_delay: 100 @@ -327,6 +306,9 @@ Info : CMSIS-DAP: Interface ready Info : clock speed 500 kHz Info : SWD IDCODE 0x0bc11477 Info : at91samd21g18.cpu: hardware has 4 breakpoints, 2 watchpoints +target state: halted +target halted due to debug-request, current mode: Thread +xPSR: 0x21000000 pc: 0x0000fca6 psp: 0x20002408 GNU gdb (GNU Tools for ARM Embedded Processors) 7.8.0.20150604-cvs Copyright (C) 2014 Free Software Foundation, Inc. License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> @@ -341,13 +323,16 @@ Find the GDB manual and other documentation resources online at: <http://www.gnu.org/software/gdb/documentation/>. For help, type "help". Type "apropos word" to search for commands related to "word"... -Reading symbols from myproject/bin/arduino_blinky/apps/blinky/blinky.elf...done. -target state: halted -target halted due to debug-request, current mode: Thread -xPSR: 0x21000000 pc: 0x0000030e msp: 0x20008000 +Reading symbols from ~/dev/myproj/bin/targets/arduino_blinky/app/apps/blinky/blinky.elf...(no debugging symbols found)...done. Info : accepting 'gdb' connection on tcp/3333 Info : SAMD MCU: SAMD21G18A (256KB Flash, 32KB RAM) -0x0000030e in ?? () +0x0000fca6 in os_tick_idle () +target state: halted +target halted due to debug-request, current mode: Thread +xPSR: 0x21000000 pc: 0x000000b8 msp: 0x20008000 +target state: halted +target halted due to debug-request, current mode: Thread +xPSR: 0x21000000 pc: 0x000000b8 msp: 0x20008000 (gdb) r The "remote" target does not support "run". Try "help target" or "continue". (gdb) c @@ -356,9 +341,7 @@ Continuing. <br> -**NOTE:** The 0.0.0 specified after the target name to `newt run` is the version -of the image to load. If you are not providing remote upgrade, and are just -developing locally, you can provide 0.0.0 for every image version. +**NOTE:** The 0.0.0 is the version number to assign to the images. If you are not providing remote upgrade, and are just developing locally, you can provide 0.0.0 for every image version. If you want the image to run without the debugger connected, simply quit the debugger and restart the board. The image you programmed will come up and run on @@ -366,9 +349,9 @@ the Arduino on the next boot! <br> -### Watch the LED blink +### Watch the LED Blink -Congratulations! You have created a Mynewt operating system running on the +Congratulations! You have created an Mynewt application running on the Arduino Zero. The LED right next to the power LED should be blinking. It is toggled by one task running on the Mynewt OS. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c37f02b9/docs/os/tutorials/bleprph/bleprph-app.md ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/bleprph/bleprph-app.md b/docs/os/tutorials/bleprph/bleprph-app.md index 4a8cff3..d086fc9 100644 --- a/docs/os/tutorials/bleprph/bleprph-app.md +++ b/docs/os/tutorials/bleprph/bleprph-app.md @@ -32,7 +32,7 @@ $ newt target set myperiph app=@apache-mynewt-core/apps/bleprph Target targets/myperiph successfully set target.app to @apache-mynewt-core/apps/bleprph $ newt target set myperiph build_profile=optimized Target targets/myperiph successfully set target.build_profile to optimized -$ newt build blerph +$ newt build myblerph Building target targets/myperiph ... Linking ~/dev/nrf52dk/bin/targets/myperiph/app/apps/bleprph/bleprph.elf http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c37f02b9/docs/os/tutorials/blinky_primo.md ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/blinky_primo.md b/docs/os/tutorials/blinky_primo.md index 07d1dc6..358be33 100644 --- a/docs/os/tutorials/blinky_primo.md +++ b/docs/os/tutorials/blinky_primo.md @@ -12,13 +12,16 @@ Note that the Mynewt OS will run on the nRF52 chip in the Arduino Primo board. H <br> -### Hardware and Software needed - -* Arduino Primo -* Laptop running Mac OS -* A micro USB 2.0 cable to power the Arduino primo board -* It is assumed you have already installed newt tool. -* It is assumed you already installed native tools as described [here](../get_started/native_tools.md) +### Prerequisites +Ensure that you have met the following prerequisites before continuing with this tutorial: + +* Have an Arduino Primo +* Have Internet connectivity to fetch remote Mynewt components. +* Have a Micro-USB cable to connect the board and the computer. +* Have a computer to build a Mynewt application and connect to your board over USB. +* Install the Newt tool and toolchains (See [Basic Setup](/os/get_started/get_started.md)). +* Create a project space (directory structure) and populated it with the core code repository (apache-mynewt-core) or know how to as explained in [Creating Your First Project](/os/get_started/project_create). +* Read the Mynewt OS [Concepts](/os/get_started/vocabulary.md) section. * Debugger - choose one of the two options below. Option 1 requires additional hardware but very easy to set up. Option 2 is free software install but not as simple as Option 1. <br> @@ -68,67 +71,54 @@ In order to be able to communicate with the SEGGER J-Link debugger on the dev bo <br> -### Create a project. +### Create a Project +Create a new project if you do not have an existing one. You can skip this step and proceed to [create the targets](#create_targets) if you already created a project. -Create a new project to hold your work. For a deeper understanding, you can read about project creation in -[Get Started -- Creating Your First Project](../get_started/project_create.md) -or just follow the commands below. +Run the following commands to create a new project: -``` +```no-highlight $ mkdir ~/dev $ cd ~/dev $ newt new myproj Downloading project skeleton from apache/incubator-mynewt-blinky... Installing skeleton in myproj... Project myproj successfully created. - $ cd myproj - - $ newt install -v + $ newt install apache-mynewt-core - Downloading repository description for apache-mynewt-core... success! - ... - apache-mynewt-core successfully installed version 0.9.0 -``` + $ +``` <br> +### <a name="create_targets"></a>Create the Targets -If you are working with 0.9.0 release (and not any subsequent releases), you will have to instruct newt to download code for the Arduino Primo Board Support Package (bsp) from the `develop` branch. You first edit the `project.yml` file in your project directory to change `vers:0-latest` to `0-dev`: - -```hl_lines="5" -<snip> -# -repository.apache-mynewt-core: - type: github - vers: 0-dev - user: apache - repo: incubator-mynewt-core -``` +Create two targets for the Arduino Primo board - one for the bootloader and one for the Blinky application. -Then you run `newt upgrade`: +Run the following `newt target` commands to create a bootloader target. We name the target `primo_boot`: +```no-highlight +$ newt target create primo_boot +$ newt target set primo_boot app=@apache-mynewt-core/apps/boot bsp=@apache-mynewt-core/hw/bsp/arduino_primo_nrf52 build_profile=optimized ``` -$ newt upgrade -apache-mynewt-core -Would you like to upgrade repository apache-mynewt-core from 0.9.0-none to 0.0.0-none ? [Yn] Y +<br> +Run the following `newt target` commands to create a target for your Blinky application. We name the target `primoblinky`: +```no-highlight +$ newt target create primoblinky +$ newt target set primoblinky app=apps/blinky bsp=@apache-mynewt-core/hw/bsp/arduino_primo_nrf52 build_profile=debug ``` - - -**Note**: With the next release, the Arduino Primo bsp will be included in the main release package. The above edit and `newt upgrade` step will not be required. - <br> +If you are using openocd, run the following `newt target set` commands: -### Create the targets - -Create two targets - one for the bootloader and one for the Primo board. +```no-highlight +$ newt target set primoblinky syscfg=OPENCD_DEBUG=1 +$ newt target set primo_boot syscfg=OPENCD_DEBUG=1 ``` -$ newt target create primoblinky -$ newt target set primoblinky app=@apache-mynewt-core/apps/blinky bsp=@apache-mynewt-core/hw/bsp/arduino_primo_nrf52 build_profile=debug -$ newt target create primo_boot -$ newt target set primo_boot app=@apache-mynewt-core/apps/boot bsp=@apache-mynewt-core/hw/bsp/arduino_primo_nrf52 build_profile=optimized +<br> +You can run the `newt target show` command to verify your target settings: +```no-highlight $ newt target show targets/my_blinky_sim app=apps/blinky @@ -144,47 +134,68 @@ targets/primoblinky build_profile=optimized ``` -If you are using openocd you must set the openocd_debug feature for both primo_boot and primoblinky. - -``` -$ newt target set primo_boot features=openocd_debug -$ newt target set primoblinky features=openocd_debug -``` <br> -### Build the target executables - -``` +### Build the Target Executables +Run the `newt build primo_boot` command to build the bootloader: +```no-highlight $ newt build primo_boot -<snip> -Compiling log_shell.c -Archiving log.a -Linking boot.elf -App successfully built: ~/dev/myproj/bin/primo_boot/apps/boot/boot.elf -``` +Building target targets/primo_boot +Compiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c +Compiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c +Compiling repos/apache-mynewt-core/crypto/mbedtls/src/aes.c +Compiling repos/apache-mynewt-core/apps/boot/src/boot.c +Compiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c +Compiling repos/apache-mynewt-core/boot/bootutil/src/loader.c +Compiling repos/apache-mynewt-core/boot/bootutil/src/bootutil_misc.c + + ... + +Archiving sys_mfg.a +Archiving sys_sysinit.a +Archiving util_mem.a +Linking ~/dev/myproj/bin/targets/primo_boot/app/apps/boot/boot.elf +Target successfully built: targets/primo_boot ``` +<br> +Run the `newt build primoblinky` command to build the Blinky application: + +```no-highlight $ newt build primoblinky -<snip> -Compiling stats_shell.c -Archiving stats.a -Linking blinky.elf -App successfully built: ~/dev/myproj/bin/primoblinky/apps/blinky/blinky.elf +Building target targets/primoblinky +Compiling repos/apache-mynewt-core/hw/drivers/uart/src/uart.c +Assembling repos/apache-mynewt-core/hw/bsp/arduino_primo_nrf52/src/arch/cortex_m4/gcc_startup_nrf52.s +Compiling repos/apache-mynewt-core/hw/bsp/arduino_primo_nrf52/src/sbrk.c +Compiling repos/apache-mynewt-core/hw/cmsis-core/src/cmsis_nvic.c +Assembling repos/apache-mynewt-core/hw/bsp/arduino_primo_nrf52/src/arch/cortex_m4/gcc_startup_nrf52_split.s +Compiling apps/blinky/src/main.c +Compiling repos/apache-mynewt-core/hw/drivers/uart/uart_bitbang/src/uart_bitbang.c +Compiling repos/apache-mynewt-core/hw/bsp/arduino_primo_nrf52/src/hal_bsp.c + + +Archiving sys_mfg.a +Archiving sys_sysinit.a +Archiving util_mem.a +Linking ~/dev/myproj/bin/targets/primoblinky/app/apps/blinky/blinky.elf +Target successfully built: targets/primoblinky ``` <br> -### Sign and create the blinky application image +### Sign and Create the Blinky Application Image -You must sign and version your application image to download it using newt to the board. Use the newt create-image command to perform this action. You may assign an arbitrary version (e.g. 1.0.0) to the image. +Run the `newt create-image primoblinky 1.0.0` command to create and sign the application image. You may assign an arbitrary version (e.g. 1.0.0) to the image. -``` +```no-highlight $ newt create-image primoblinky 1.0.0 +App image succesfully generated: ~/dev/myproj/bin/targets/primoblinky/app/apps/blinky/blinky.img + ``` <br> -### Connect the board +### Connect to the Board Connect the Segger J-Link debug probe to the JTAG port on the Primo board using the Jlink 9-pin adapter and cable. Note that there are two JTAG ports on the board. Use the one nearest to the reset button as shown in the picture. Also use a micro USB 2.0 cable to connect the Primo board to one of your laptop's USB host ports. @@ -194,15 +205,27 @@ Connect the Segger J-Link debug probe to the JTAG port on the Primo board using **Note:** If you are going the OpenOCD route, you do not need to attach this connector. -### Download to the target - -Download the bootloader first and then the blinky executable to the target platform. Don't forget to reset the board if you don't see the LED blinking right away. If the reset button doesn't work, powercycle the board! +### Load the Bootloader and the Blinky Application Image +Run the `newt load primo_boot` command to load the bootloader onto your board: +```no-highlight +$ newt load primo_boot +Loading bootloader +$ ``` -$ newt -v load primo_boot -$ newt -v load primoblinky +<br> +Run the `newt load primoblinky` command to load Blinky application image onto your board. +```no-highlight +$ newt load primoblinky +Loading app image into slot 1 +$ ``` +You should see the LED on your board blink! + +Note: If the LED does not blink, try resetting your board. + + <br> **Note:** If you want to erase the flash and load the image again, you can use JLinkExe to issue an `erase` command. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c37f02b9/docs/os/tutorials/nRF52.md ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/nRF52.md b/docs/os/tutorials/nRF52.md index 469bd6e..8ac5f33 100644 --- a/docs/os/tutorials/nRF52.md +++ b/docs/os/tutorials/nRF52.md @@ -12,72 +12,77 @@ Note that there are several versions of the nRF52 in the market. The boards test <br> -### Hardware needed +### Prerequistes -* nRF52 Development Kit (one of the following) +Ensure that you have met the following prerequisites before continuing with this tutorial: + +* Have a nRF52 Development Kit (one of the following) * Dev Kit from Nordic - PCA 10040 * Eval Kit from Rigado - BMD-300-EVAL-ES -* Laptop running Mac OS -* It is assumed you have already installed newt tool. -* It is assumed you already installed native tools as described [here](../get_started/native_tools.md) - -<br> - -### Install jlinkEXE - -In order to be able to communicate with the SEGGER J-Link debugger on the dev board, you have to download and install the J-Link GDB Server software on to your laptop. You may download the "Software and documentation pack for Mac OS X" from [https://www.segger.com/jlink-software.html](https://www.segger.com/jlink-software.html). +* Have Internet connectivity to fetch remote Mynewt components. +* Have a Micro-USB cable to connect the board and the computer. +* Have computer to build a Mynewt application and connect to your board over USB. +* Install the Newt tool and toolchains (See [Basic Setup](/os/get_started/get_started.md)). +* Create a project space (directory structure) and populated it with the core code repository (apache-mynewt-core) or know how to as explained in [Creating Your First Project](/os/get_started/project_create). +* Read the Mynewt OS [Concepts](/os/get_started/vocabulary.md) section. <br> -### Create a project. +### Create a Project +Create a new project if you do not have an existing one. You can skip this step and proceed to [create the targets](#create_targets) if you already have a project created. -Create a new project to hold your work. For a deeper understanding, you can read about project creation in -[Get Started -- Creating Your First Project](../get_started/project_create.md) -or just follow the commands below. +Run the following commands to create a new project: -``` +```no-highlight $ mkdir ~/dev $ cd ~/dev $ newt new myproj Downloading project skeleton from apache/incubator-mynewt-blinky... Installing skeleton in myproj... Project myproj successfully created. - $ cd myproj - - $ newt install -v + $ newt install apache-mynewt-core - Downloading repository description for apache-mynewt-core... success! - ... - apache-mynewt-core successfully installed version 0.9.0-none + $ ``` <br> -### Create the targets +### <a name="create_targets"></a>Create the Targets -Create two targets - one for the bootloader and one for the nrf52 board. +Create two targets for the nRF52-DK board - one for the bootloader and one for the Blinky application. + +Run the following `newt target` commands, from your project directory (~/dev/myproj), to create a bootloader target. We name the target `nrf52_boot`: <font color="#F2853F"> -Note: The correct bsp must be chosen for the board you are using. </font> +Note: For this tutorial, we are using the nRF52-DK board. You must specify the correct bsp for the board you are using. </font> * For the Nordic Dev Kit choose @apache-mynewt-core/hw/bsp/nrf52dk instead (in the highlighted lines) * For the Rigado Eval Kit choose @apache-mynewt-core/hw/bsp/bmd300eval instead (in the highlighted lines) - -```hl_lines="3 8" -$ newt target create blink_nordic -$ newt target set blink_nordic app=apps/blinky -$ newt target set blink_nordic bsp=@apache-mynewt-core/hw/bsp/nrf52dk -$ newt target set blink_nordic build_profile=debug - +```hl_lines="3" $ newt target create nrf52_boot $ newt target set nrf52_boot app=@apache-mynewt-core/apps/boot $ newt target set nrf52_boot bsp=@apache-mynewt-core/hw/bsp/nrf52dk $ newt target set nrf52_boot build_profile=optimized +``` + +<br> +Run the following `newt target` commands to create a target for your Blinky application. We name the target `nrf52_blinky`: + +```hl_lines="3" +$ newt target create nrf52_blinky +$ newt target set nrf52_blinky app=apps/blinky +$ newt target set nrf52_blinky bsp=@apache-mynewt-core/hw/bsp/nrf52dk +$ newt target set nrf52_blinky build_profile=debug +``` +<br> +You can run the `newt target show` command to verify your target settings: + +```no-highlight $ newt target show -targets/blink_nordic +targets/nrf52_blinky app=apps/blinky bsp=@apache-mynewt-core/hw/bsp/nrf52dk build_profile=debug @@ -86,57 +91,93 @@ targets/nrf52_boot bsp=@apache-mynewt-core/hw/bsp/nrf52dk build_profile=optimized ``` - <br> -### Build the target executables +### Build the Target Executables -``` +Run the `newt build nrf52_boot` command to build the bootloader: + +```no-highlight $ newt build nrf52_boot -... -Compiling boot.c -Archiving boot.a -Linking boot.elf -App successfully built: ~/dev/myproj/bin/nrf52_boot/apps/boot/boot.elf -``` +Building target targets/nrf52_boot +Compiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c +Compiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c +Compiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c +Compiling repos/apache-mynewt-core/crypto/mbedtls/src/aes.c +Compiling repos/apache-mynewt-core/boot/bootutil/src/loader.c +Compiling repos/apache-mynewt-core/boot/bootutil/src/image_validate.c +Compiling repos/apache-mynewt-core/boot/bootutil/src/bootutil_misc.c +Compiling repos/apache-mynewt-core/apps/boot/src/boot.c + ... + +Archiving sys_mfg.a +Archiving sys_sysinit.a +Archiving util_mem.a +Linking ~/dev/myproj/bin/targets/nrf52_boot/app/apps/boot/boot.elf +Target successfully built: targets/nrf52_boot ``` -$ newt build blink_nordic -... -Compiling main.c -Archiving blinky.a -Linking blinky.elf -App successfully built: ~/dev/myproj/bin/blink_nordic/apps/blinky/blinky.elf + +<br> +Run the `newt build nrf52_blinky` command to build the Blinky application: + +```no-highlight +$ newt build nrf52_blinky +Building target targets/nrf52_blinky +Assembling repos/apache-mynewt-core/hw/bsp/nrf52dk/src/arch/cortex_m4/gcc_startup_nrf52_split.s +Compiling repos/apache-mynewt-core/hw/bsp/nrf52dk/src/sbrk.c +Compiling repos/apache-mynewt-core/hw/cmsis-core/src/cmsis_nvic.c +Compiling repos/apache-mynewt-core/hw/drivers/uart/uart_hal/src/uart_hal.c +Assembling repos/apache-mynewt-core/hw/bsp/nrf52dk/src/arch/cortex_m4/gcc_startup_nrf52.s +Compiling apps/blinky/src/main.c + + ... + +Archiving sys_mfg.a +Archiving sys_sysinit.a +Archiving util_mem.a +Linking ~/dev/myproj/bin/targets/nrf52_blinky/app/apps/blinky/blinky.elf +Target successfully built: targets/nrf52_blinky ``` <br> -### Sign and create the blinky application image +### Sign and Create the Blinky Application Image -You must sign and version your application image to download it using newt to the board. Use the newt create-image command to perform this action. You may assign an arbitrary version (e.g. 1.0.0) to the image. +Run the `newt create-image nrf52_blinky 1.0.0` command to create and sign the application image. You may assign an arbitrary version (e.g. 1.0.0) to the image. -``` -$ newt create-image blink_nordic 1.0.0 -App image successfully generated: ~/dev/myproj/bin/blink_nordic/apps/blinky/blinky.img -Build manifest: ~/dev/myproj/bin/blink_nordic/apps/blinky/manifest.json +```no-highlight +$ newt create-image nrf52_blinky 1.0.0 +newt create-image nrf52_blinky 1.0.0 +App image succesfully generated: ~/dev/myproj/bin/targets/nrf52_blinky/app/apps/blinky/blinky.img ``` <br> -### Connect the board +### Connect to the Board -Connect the evaluation board via micro-USB to your PC via USB cable. +* Connect a micro-USB cable from your computer to the micro-USB port on your nRF52-DK board. +* Turn the power on the board to ON. You should see the green LED light up on the board. -<br> - -### Download to the target +### Load the Bootloader and the Blinky Application Image -Download the bootloader first and then the blinky executable to the target platform. Don't forget to reset the board if you don't see the LED blinking right away! +Run the `newt load nrf52_boot` command to load the bootloader onto your board: +```no-highlight +$ newt load nrf52_boot +Loading bootloader +$ ``` -$ newt -v load nrf52_boot -$ newt -v load blink_nordic +<br> +Run the `newt load nrf52_blinky` command to load Blinky application image onto your board. +```no-highlight +$ newt -v load nrf52_blinky +Loading app image into slot 1 ``` +You should see the LED1 on your board blink! + +Note: If the LED does not blink, try resetting your board. + <br> **Note:** If you want to erase the flash and load the image again, you can use JLinkExe to issue an `erase` command. @@ -169,8 +210,7 @@ $ ### Conclusion -You have created, setup, compiled, loaded, and ran your first mynewt application -for an nrf52 board. +You have created, setup, compiled, loaded, and ran your first mynewt application for an nrf52 board. We have more fun tutorials for you to get your hands dirty. Be bold and work on the OS with tutorials on [writing a test suite](unit_test.md) or try enabling additional functionality such as [remote comms](project-target-slinky.md) or [Bluetooth Low Energy](bletiny_project.md) on your current board. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c37f02b9/docs/os/tutorials/olimex.md ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/olimex.md b/docs/os/tutorials/olimex.md index 398bfe1..e4d005b 100644 --- a/docs/os/tutorials/olimex.md +++ b/docs/os/tutorials/olimex.md @@ -4,36 +4,30 @@ Learn how to use packages from a default application repository of Mynewt to build your first *Hello World* application (Blinky) on a target board. Once built using the *newt* tool, this application will blink the LED lights on the target board. Fun stuff! -This tutorial shows you how to create a runtime image for an Olimex board to make its LED blink. Download the image to its flash memory and see the LED blink! +This tutorial shows you how to create a blinky application for the Olimex board. It also shows you how to load the application onto the board's flash memory and run the application. <br> -### What you need +### Prerequisites +Ensure that you have met the following prerequisites before continuing with this tutorial: -1. STM32-E407 development board from Olimex. You can order it from [http://www.mouser.com](http://www.mouser.com/search/ProductDetail.aspx?R=0virtualkey0virtualkeySTM32-E407), [http://www.digikey.com](http://www.digikey.com/product-detail/en/STM32-E407/1188-1093-ND/3726951), and other places. -2. ARM-USB-TINY-H connector with JTAG interface for debugging ARM microcontrollers (comes with the ribbon cable to hook up to the board) -3. USB A-B type cable to connect the debugger to your personal computer -4. Personal Computer with Mac OS (Mac: OS X Yosemite Version 10.10.5) or Linux box (Ubuntu 14.10: Utopic Unicorn) -5. An account on Github repository and *git* installed on your computer. -6. It is assumed you have already installed newt tool. -7. It is assumed you already installed native tools as described [here](../get_started/native_tools.md) +* Have a STM32-E407 development board from Olimex. +* Have a ARM-USB-TINY-H connector with JTAG interface for debugging ARM microcontrollers (comes with the ribbon cable to hook up to the board) +* Have USB A-B type cable to connect the debugger to your personal computer. +* Have Internet connectivity to fetch remote Mynewt components. +* Have a computer to build a Mynewt application and connect to your board over USB. +* Install the Newt tool and toolchains (See [Basic Setup](/os/get_started/get_started.md)). +* Create a project space (directory structure) and populated it with the core code repository (apache-mynewt-core) or know how to as explained in [Creating Your First Project](/os/get_started/project_create). +* Read the Mynewt OS [Concepts](/os/get_started/vocabulary.md) section. -Also, we assume that you're familiar with UNIX shells. Let's gets started! <br> -### Prepare the Software +### Create a Project +Create a new project if you do not have an existing one. You can skip this step and proceed to [create the targets](#create_targets) if you already created a project. -* Make sure the PATH environment variable includes the $HOME/dev/go/bin directory. - -<br> - -### Create a project. - -Create a new project to hold your work. For a deeper understanding, you can read about project creation in -[Get Started -- Creating Your First Project](../get_started/project_create.md) -or just follow the commands below. +Run the following commands to create a new project: ```no-highlight $ mkdir ~/dev @@ -45,119 +39,147 @@ or just follow the commands below. $cd myproj - $ newt install -v + $ newt install apache-mynewt-core - Downloading repository description for apache-mynewt-core... success! - ... - apache-mynewt-core successfully installed version 0.7.9-none + $ ``` <br> -### Create targets +### <a name="create_targets"></a>Create the Targets -Change directory to ~/dev/myproj directory and define the *blinky* target inside myproj, using the *newt* tool. Starting with the target name, assign specific aspects of the project, as shown below, to pull the appropriate packages and build the right bundle or list for the board. For example, we set the build_profile, board support package (bsp), and app. +Create two targets for the Olimex board - one for the bootloader and one for the Blinky application. +Run the following `newt target` commands to create a bootloader target. We name the target `boot_olimex`: ```no-highlight - $ newt target create blinky - $ newt target set blinky build_profile=debug - $ newt target set blinky bsp=@apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard - $ newt target set blinky app=apps/blinky - - $ newt target create boot_olimex - $ newt target set boot_olimex app=@apache-mynewt-core/apps/boot - $ newt target set boot_olimex bsp=@apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard - $ newt target set boot_olimex build_profile=optimized - - $ newt target show - targets/blinky - app=apps/blinky - bsp=@apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard - build_profile=debug - targets/boot_olimex - app=@apache-mynewt-core/apps/boot - bsp=@apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard - build_profile=optimized +$ newt target create boot_olimex +$ newt target set boot_olimex build_profile=optimized +$ newt target set boot_olimex app=@apache-mynewt-core/apps/boot +$ newt target set boot_olimex bsp=@apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard ``` <br> +Run the following `newt target` commands to create a target for your Blinky application. We name the target `olimex_blinky`: -### Build the images +```no-highlight +$ newt target create olimex_blinky +$ newt target set olimex_blinky build_profile=debug +$ newt target set olimex_blinky bsp=@apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard +$ newt target set olimex_blinky app=apps/blinky -Next, let's build the images for the above targets. Afer you build the target, you can find the executable *blinky.elf* in the project directory *~/dev/myproj/bin/blinky/apps/blinky/.* +``` +<br> + +### Build the Bootloader +Run the `newt build boot_olimex` command to build the boot loader image: ```no-highlight - $ newt build blinky - Compiling case.c - Compiling suite.c - ... - Linking blinky.elf - App successfully built:~/dev/myproj/bin/blinky/apps/blinky/blinky.elf - $ ls ~/dev/myproj/bin/blinky/apps/blinky/ - blinky.elf blinky.elf.bin blinky.elf.cmd - blinky.elf.lst blinky.elf.map - - $ newt build boot_olimex - Building target targets/boot_olimex - App successfully built: ~/dev/myproj/bin/boot_olimex/apps/boot/boot.elf +$ newt build boot_olimex +Building target targets/boot_olimex +Compiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c +Compiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c +Compiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c +Compiling bin/targets/boot_olimex/generated/src/boot_olimex-sysflash.c + + ... + +Archiving libc_baselibc.a +Archiving sys_flash_map.a +Archiving sys_mfg.a +Archiving sys_sysinit.a +Archiving util_mem.a +Linking ~/dev/myproj/bin/targets/boot_olimex/app/apps/boot/boot.elf +Target successfully built: targets/boot_olimex ``` - <br> +### Build the Blinky Application +Run the `newt build olimex_blinky` command to build the blinky application: -### Sign and create the blinky application image - -You must sign and version your application image to download it using newt to the board. Use the newt create-image command to perform this action. You may assign an arbitrary version (e.g. 1.0.0) to the image. +```no-highlight +$ newt build olimex_blinky +Building target targets/olimex_blinky +Assembling repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard/src/arch/cortex_m4/startup_STM32F40x.s +Compiling repos/apache-mynewt-core/hw/drivers/uart/src/uart.c +Compiling repos/apache-mynewt-core/hw/cmsis-core/src/cmsis_nvic.c +Compiling repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard/src/sbrk.c +Compiling apps/blinky/src/main.c +Compiling repos/apache-mynewt-core/hw/drivers/uart/uart_hal/src/uart_hal.c +Compiling repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard/src/hal_bsp.c +Compiling repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard/src/system_stm32f4xx.c +Compiling repos/apache-mynewt-core/hw/hal/src/hal_common.c +Compiling repos/apache-mynewt-core/hw/hal/src/hal_flash.c + + ... + +Archiving sys_mfg.a +Archiving sys_sysinit.a +Archiving util_mem.a +Linking ~/dev/myproj/bin/targets/olimex_blinky/app/apps/blinky/blinky.elf +Target successfully built: targets/olimex_blinky ``` -$ newt create-image blinky 1.0.0 -App image successfully generated: ~/dev/myproj/bin/blinky/apps/blinky/blinky.img -Build manifest: ~/dev/myproj/bin/blinky/apps/blinky/manifest.json -``` <br> -### Prepare the hardware to boot from flash +### Sign and Create the Blinky Application Image +Run the `newt create-image olimex_blinky 1.0.0` command to sign and create an image file for your blinky application. You may assign an arbitrary version (e.g. 1.0.0) number. -* Locate the boot jumpers on the board. +```no-highlight +$ newt create-image olimex_blinky 1.0.0 +App image succesfully generated: ~/dev/myproj/bin/targets/olimex_blinky/app/apps/blinky/blinky.img +``` <br> - - +### Connect to the Board + +Configure your board to bootload from flash memory and to use the JTAG/SWD for the power source. Refer to the following diagrams to locate the boot jumpers and power input select jumpers on your board. +<br> + +<p align="center"> +<img src="../pics/STM32-E407_top_small.jpg"></img> +<br> +<img src="../pics/STM32-E407_bot_small.jpg"></img> +</p> <br> -* B1_1/B1_0 and B0_1/B0_0 are PTH jumpers. Note that because the markings on the board may not always be accurate, when in doubt, you should always refer to the manual for the correct positioning. Since the jumpers are a pair, they should move together, and as such, the pair is responsible for the boot mode when bootloader is present. -To locate the bootloader, the board searches in three places: User Flash Memory, System Memory or the Embedded SRAM. For this Blinky project, we will configure it to boot from flash by jumpering **B0_0** and **B1_0**. +* Locate the boot jumpers on the lower right corner of the board. **B1_1/B1_0** and **B0_1/B0_0** are PTH jumpers to control the boot mode when a bootloader is present. These two jumpers must be moved together. The board searches for the bootloader in three places: User Flash Memory, System Memory or the Embedded SRAM. For this Blinky project, we configure the board to boot from flash by jumpering **B0_0** and **B1_0**. +**Note:** The markings on the board may not always be accurate, and you should always refer to the manual for the correct positioning. -* Connect USB-OTG#2 in the picture above to a USB port on your computer (or a powered USB hub to make sure there is enough power available to the board). +* Locate the **Power Input Select** jumpers on the lower left corner of the board. Set the Power Select jumpers to position 3 and 4 to use the JTAG/SWD for the power source. If you would like to use a different power source, refer to [OLIMEZ STM32-E407] user manual](https://www.olimex.com/Products/ARM/ST/STM32-E407/resources/STM32-E407.pdf) to pin specificiation. + -* The red PWR LED should be lit. +* Connect the JTAG connector to the JTAG/SWD interface on the board. -* Connect the JTAG connector to the SWD/JTAG interface on the board. The other end of the cable should be connected to the USB port or hub of your computer. +* Connect the USB A-B cable to the ARM-USB-TINY-H connector and your personal computer. +* Check that the red PWR LED lights up. <br> -### Let's Go! +### Load the Bootloader and Blinky Application -* Load the images +Run the `newt load boot_olimex` command to load the bootloader image onto the board: ```no-highlight -$ newt -v load boot_olimex -Loading image with: ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard/olimex_stm32-e407_devboard_download.sh ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard/ ~/dev/myproj/bin/boot_olimex/apps/boot/boot BASELIBC FS LIBC NFFS bootloader +$newt load -v boot_olimex +Loading bootloader +Load command: ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard/olimex_stm32-e407_devboard_download.sh ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard ~/dev/myproj/bin/targets/boot_olimex/app/apps/boot/boot Successfully loaded image. - -$ newt -v load blinky -Loading image with: ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard/olimex_stm32-e407_devboard_download.sh ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard/ ~/dev/myproj/bin/blinky/apps/blinky/blinky BASELIBC LIBC +``` +Run the `newt load olimex_blinky` command to load the blinky application image onto the board: +```no-highlight +newt load -v olimex_blinky +Loading app image into slot 1 +Load command: ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard/olimex_stm32-e407_devboard_download.sh ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard ~/dev/myproj/bin/targets/olimex_blinky/app/apps/blinky/blinky Successfully loaded image. + ``` <br> - -* Voilà ! The LED should be blinking! Success! +The LED should be blinking! <br> - **But wait...not so fast.** Let's double check that it is indeed booting from flash and making the LED blink from the image in flash. Pull the USB cable off the Olimex JTAG adaptor, severing the debug connection to the JTAG port. Next power off the Olimex board by pulling out the USB cable from the board. Wait for a couple of seconds and plug the USB cable back to the board. The LED light will start blinking again. Success! http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c37f02b9/docs/os/tutorials/pics/STM32-E407_bot_small.jpg ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/pics/STM32-E407_bot_small.jpg b/docs/os/tutorials/pics/STM32-E407_bot_small.jpg new file mode 100755 index 0000000..da1889e Binary files /dev/null and b/docs/os/tutorials/pics/STM32-E407_bot_small.jpg differ http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c37f02b9/docs/os/tutorials/pics/STM32-E407_top_small.jpg ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/pics/STM32-E407_top_small.jpg b/docs/os/tutorials/pics/STM32-E407_top_small.jpg new file mode 100755 index 0000000..938a04b Binary files /dev/null and b/docs/os/tutorials/pics/STM32-E407_top_small.jpg differ http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c37f02b9/docs/os/tutorials/project-slinky.md ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/project-slinky.md b/docs/os/tutorials/project-slinky.md index 5537001..40f93e3 100644 --- a/docs/os/tutorials/project-slinky.md +++ b/docs/os/tutorials/project-slinky.md @@ -74,10 +74,26 @@ is created. ```no-highlight $ newt build sim_slinky - Compiling main.c - ... - Linking slinky.elf - App successfully built: ~/dev/slinky/bin/sim_slinky/apps/slinky/slinky.elf + Building target targets/sim_slinky + Compiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c + Compiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c + Compiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c + Compiling repos/apache-mynewt-core/boot/split/src/split.c + Compiling repos/apache-mynewt-core/boot/bootutil/src/image_validate.c + Compiling repos/apache-mynewt-core/boot/bootutil/src/loader.c + Compiling repos/apache-mynewt-core/boot/bootutil/src/bootutil_misc.c + Compiling repos/apache-mynewt-core/crypto/mbedtls/src/aesni.c + Compiling repos/apache-mynewt-core/crypto/mbedtls/src/aes.c + Compiling repos/apache-mynewt-core/boot/split/src/split_config.c + Compiling repos/apache-mynewt-core/apps/slinky/src/main.c + + ... + + Archiving util_crc.a + Archiving util_mem.a + Linking ~/dev/slinky/bin/targets/sim_slinky/app/apps/slinky/slinky.elf + Target successfully built: targets/sim_slinky + ``` ### Run the target @@ -86,14 +102,13 @@ Run the executable you have build for the simulated environment. The serial port when mynewt slinky starts. ```no-highlight - $ ~/dev/slinky/bin/sim_slinky/apps/slinky/slinky.elf + $ ~/dev/slinky/bin/targets/sim_slinky/app/apps/slinky/slinky.elf uart0 at /dev/ttys005 ``` <br> -In this example, the slinky app opened up a com port `/dev/ttys005` -for communications with newtmgr. +In this example, the slinky app opened up a com port `/dev/ttys005` for communications with newtmgr. **NOTE:** This application will block. You will need to open a new console (or execute this in another console) to continue the tutorial.* @@ -108,25 +123,21 @@ You will now set up a connection profile using `newtmgr` for the serial port con Connection profile sim1 successfully added $ newtmgr conn show Connection profiles: - sim1: type=serial, connstring='/dev/ttys007' + sim1: type=serial, connstring='/dev/ttys005' ``` ### Executing newtmgr commands with the target -You can now use connection profile `sim1` to talk to the running sim_blinky. +You can now use connection profile `sim1` to talk to the running sim_slinky. As an example, we will query the running mynewt OS for the usage of its memory pools. ```no-highlight $ newtmgr -c sim1 mpstats Return Code = 0 - nffs_cache_inode_pool (blksize=36 nblocks=4 nfree=4) - nffs_cache_block_pool (blksize=32 nblocks=64 nfree=64) - nffs_dir_pool (blksize=8 nblocks=4 nfree=4) - default_mbuf_data (blksize=256 nblocks=10 nfree=8) - nffs_file_pool (blksize=12 nblocks=4 nfree=4) - nffs_inode_entry_pool (blksize=24 nblocks=100 nfree=98) - nffs_block_entry_pool (blksize=12 nblocks=100 nfree=100) + name blksz cnt free min + msys_1 292 12 10 10 + ``` As a test command, you can send an arbitrary string to the target and it @@ -134,10 +145,8 @@ will echo that string back in a response to newtmgr. ```no-highlight $ newtmgr -c sim1 echo "Hello Mynewt" - {"r": "Hello Mynewt"} + Hello Mynewt ``` -The response comes back as a json string. - In addition to these, you can also examine running tasks, statistics, logs, image status (not on sim), and configuration. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/c37f02b9/mkdocs.yml ---------------------------------------------------------------------- diff --git a/mkdocs.yml b/mkdocs.yml index 21502c4..6119efc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -46,9 +46,6 @@ pages: - 'Tasks and Priority Management': 'os/tutorials/tasks_lesson.md' - 'Enable Wi-Fi on Arduino Zero': 'os/tutorials/wi-fi_on_arduino.md' - 'Write a Test Suite for a Package': 'os/tutorials/unit_test.md' - - 'Air-quality Sensor project': - - 'Basic Air Quality Sensor': 'os/tutorials/air_quality_sensor.md' - - 'Bluetooth-enabled Air Quality Sensor': 'os/tutorials/air_quality_ble.md' - 'Events and Event Queues': 'os/tutorials/event_queue.md' - 'Project Slinky for remote comms': - 'Slinky on sim device': 'os/tutorials/project-slinky.md' @@ -335,11 +332,6 @@ pages: - 'imgr_ver_parse': 'os/modules/imgmgr/imgr_ver_parse.md' - 'imgr_ver_str': 'os/modules/imgmgr/imgr_ver_str.md' - 'Baselibc library': 'os/modules/baselibc.md' - - Embedded Lua: - - toc: 'os/modules/elua/elua.md' - - 'Functions': - - 'lua_init': 'os/modules/elua/lua_init.md' - - 'lua_main': 'os/modules/elua/lua_main.md' - JSON: - toc: 'os/modules/json/json.md' - 'Functions':
![https://www.arduino.cc/en/uploads/Main/Zero_Usb_Ports.jpg"](https://www.arduino.cc/en/uploads/Main/Zero_Usb_Ports.jpg"){kind=link}
![http://www.arduino.org//images/products/ArduinoZeroPro-flat-org.jpg"](http://www.arduino.org//images/products/ArduinoZeroPro-flat-org.jpg"){kind=link}
