Repository: incubator-mynewt-site Updated Branches: refs/heads/master 274e59de4 -> 296699c82
Reordered tutorials. This closes #167 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/296699c8 Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/296699c8 Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/296699c8 Branch: refs/heads/master Commit: 296699c829a539aa3b273fb098b65047c9017742 Parents: 274e59d Author: aditihilbert <ad...@runtime.io> Authored: Fri Apr 7 17:31:50 2017 -0700 Committer: aditihilbert <ad...@runtime.io> Committed: Fri Apr 7 17:31:50 2017 -0700 ---------------------------------------------------------------------- docs/os/tutorials/blinky.md | 47 ++++++ docs/os/tutorials/project-nrf52-slinky.md | 208 +++++++++++++++++++++++++ docs/os/tutorials/project-sim-slinky.md | 119 ++++++++++++++ 3 files changed, 374 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/296699c8/docs/os/tutorials/blinky.md ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/blinky.md b/docs/os/tutorials/blinky.md new file mode 100644 index 0000000..59d9ad1 --- /dev/null +++ b/docs/os/tutorials/blinky.md @@ -0,0 +1,47 @@ +## Blinky, your "Hello World!" on a Target Board +The set of Blinky tutorials show you how to create, build, and run a "Hello World" application that blinks a LED on the various target boards that Mynewt supports. The tutorials use the same Blinky application from the [Creating Your First Project](/os/get_started/project_create) tutorial. + +### Objective + +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 a LED light on the target board. + +###Available Tutorials +Tutorials are available for the following boards: + +* [Blinky on an Arduino Zero](/os/tutorials/arduino_zero.md) +* [Blinky on an Arduino Primo](/os/tutorials/blinky_primo.md) +* [Blinky on an Olimex](/os/tutorials/olimex.md) +* [Blinky on a nRF52](/os/tutorials/nRF52.md) +* [Blinky on a RedBear Nano 2](/os/tutorials/rbnano2.md) + +We also have a tutorial that shows you how to add [Console and Shell to the Blinky Application](/os/tutorials/blinky_console.md). +<br> +### Prerequisites +Ensure that you meet the following prerequisites before continuing with one of the tutorials. + +* Have Internet connectivity to fetch remote Mynewt components. +* Have a computer to build a Mynewt application and connect to the board over USB. +* Have a Micro-USB cable to connect the board and the computer. +* Install the Newt tool and toolchains (See [Basic Setup](/os/get_started/get_started.md)). +* Install either the Jlink or OpenOCD debugger. +* Create a project space (directory structure) and populate 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> +###Overview of Steps +These are the general steps to create, load and run the Blinky application on your board: + +* Create a project. +* Define the bootloader and Blinky application targets for the board. +* Build the bootloader target. +* Build the Blinky application target and create an application image. +* Connect to the board. +* Load the bootloader onto the board. +* Load the Blinky application image onto the board. +* See the LED on your board blink. + +<br> + +After you try the Blinky application on your boards, checkout out other tutorials to enable additional functionality such as [remote comms](project-slinky.md) on the current board. If you have BLE (Bluetooth Low Energy) chip (e.g. nRF52) on your board, you can try turning it into an [iBeacon](ibeacon.md) or [Eddystone Beacon](eddystone.md)! + +If you see anything missing or want to send us feedback, please sign up for +appropriate mailing lists on our [Community Page](../../community.md). http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/296699c8/docs/os/tutorials/project-nrf52-slinky.md ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/project-nrf52-slinky.md b/docs/os/tutorials/project-nrf52-slinky.md new file mode 100644 index 0000000..dfc4c57 --- /dev/null +++ b/docs/os/tutorials/project-nrf52-slinky.md @@ -0,0 +1,208 @@ +## Project Slinky using the Nordic nRF52 Board +This tutorial shows you how to create, build and run the Slinky application and communicate with newtmgr for a Nordic nRF52 board. + +### Prerequisites +* Meet the prerequisites listed in [Project Slinky](/os/tutorials/project-slinky.md). +* Have a Nordic nRF52-DK board. + +### Create a New 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 or completed the [Sim Slinky](project-slinky.md) tutorial. + +Run the following commands to create a new project. We name the project `slinky`. + +```no-highlight +$ newt new slinky +Downloading project skeleton from apache/incubator-mynewt-blinky... +... +Installing skeleton in slink... +Project slinky successfully created +$ cd slinky +$newt install +apache-mynewt-core +``` + +<br> + +###<a name="create_targets"></a> Create the Targets + +Create two targets for the nRF52-DK board - one for the bootloader and one for the Slinky application. + +Run the following `newt target` commands, from your project directory, to create a bootloader target. We name the target `nrf52_boot`. + +```no-highlight +$ newt target create nrf52_boot +$ newt target set nrf52_boot bsp=@apache-mynewt-core/hw/bsp/nrf52dk +$ newt target set nrf52_boot build_profile=optimized +$ newt target set nrf52_boot app=@apache-mynewt-core/apps/boot +``` +<br> +Run the following `newt target` commands to create a target for the Slinky application. We name the target `nrf52_slinky`. + +```no-highlight +$ newt target create nrf52_slinky +$ newt target set nrf52_slinky bsp=@apache-mynewt-core/hw/bsp/nrf52dk +$ newt target set nrf52_slinky build_profile=debug +$ newt target set nrf52_slinky app=@apache-mynewt-core/apps/slinky +``` + +<br> + +### Build the Targets + +Run the `newt build nrf52_boot` command to build the bootloader: + +```no-highlight +$ newt build nrf52-boot +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/slinky/bin/targets/nrf52_boot/app/apps/boot/boot.elf +Target successfully built: targets/nrf52_boot +``` +<br> + +Run the `newt build nrf52_slinky` command to build the Slinky application: + +```no-highlight +$newt build nrf52_slinky +Building target targets/nrf52_slinky +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/boot/split/src/split.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/boot/split/src/split_config.c +Compiling repos/apache-mynewt-core/crypto/mbedtls/src/aesni.c +Compiling repos/apache-mynewt-core/boot/bootutil/src/image_validate.c +Compiling repos/apache-mynewt-core/crypto/mbedtls/src/aes.c +Compiling repos/apache-mynewt-core/apps/slinky/src/main.c + + ... + +Archiving util_mem.a +Linking ~/dev/slinky/bin/targets/nrf52_slinky/app/apps/slinky/slinky.elf +Target successfully built: targets/nrf52_slinky +``` + +<br> + +### Sign and Create the Slinky Application Image + +Run the `newt create-image nrf52_slinky 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 nrf52_slinky 1.0.0 +App image succesfully generated: ~/dev/slinky/bin/targets/nrf52_slinky/app/apps/slinky/slinky.img +$ +``` +<br> + +### Connect to the Board + +* Connect a micro-USB cable from your computer to the micro-USB port on the nRF52-DK board. +* Turn the power on the board to ON. You should see the green LED light up on the board. + +<br> +### Load the Bootloader and the Slinky Application Image + +Run the `newt load nrf52_boot` command to load the bootloader onto the board: + +```no-highlight +$ newt load nrf52_boot +Loading bootloader +$ +``` +<br> +Run the `newt load nrf52_slinky` command to load the Slinky application image onto the board: +```no-highlight +$ newt load nrf52_slinky +Loading app image into slot 1 +$ +``` +<br> + + +### Connect Newtmgr with the Board using a Serial Connection + +Set up a serial connection from your computer to the nRF52-DK board (See [Serial Port Setup](/os/get_started/serial_access.md)). + +Locate the port, in the /dev directory on your computer, that the serial connection uses. It should be of the type `tty.usbserial-<some identifier>`. + +```no-highlight +$ ls /dev/tty*usbserial* +/dev/tty.usbserial-1d11 +$ +``` +<br> +Setup a newtmgr connection profile for the serial port. For our example, the port is `/dev/tty.usbserial-1d11`. + +Run the `newtmgr conn add` command to define a newtmgr connection profile for the serial port. We name the connection profile `nrf52serial`. You will need to replace the `connstring` with the specific port for your serial connection. + +```no-highlight +$ newtmgr conn add nrf52serial type=serial connstring=/dev/tty.usbserial-1d11 +Connection profile nrf52serial successfully added +$ +``` +<br> +You can run the `newt conn show` command to see all the newtmgr connection profiles: + +```no-highlight +$ newtmgr conn show +Connection profiles: + nrf52serial: type=serial, connstring='/dev/tty.usbserial-1d11' + sim1: type=serial, connstring='/dev/ttys012' +$ +``` + +<br> +### Use Newtmgr to Query the Board +Run some newtmgr commands to query and receive responses back from the board (See the [Newt Manager Guide](newtmgr/overview) for more information on the newtmgr commands). + + +Run the `newtmgr echo hello -c nrf52serial` command. This is the simplest command that requests the board to echo back the text. + +```no-highlight +$ newtmgr echo hello -c nrf52serial +hello +$ +``` +<br> +Run the `newtmgr image list -c nrf52serial` command to list the images on the board: + +```no-highlight +$ newtmgr image list -c nrf52serial +Images: + slot=0 + version: 1.0.0 + bootable: true + flags: active confirmed + hash: f411a55d7a5f54eb8880d380bf47521d8c41ed77fd0a7bd5373b0ae87ddabd42 +Split status: N/A +$ +``` + +<br> +Run the `newtmgr taskstats -c nrf52serial` command to display the task statistics on the board: + +```no-highlight +$ newtmgr taskstats -c nrf52serial +Return Code = 0 + task pri tid runtime csw stksz stkuse last_checkin next_checkin + task1 8 2 0 1751 192 110 0 0 + task2 9 3 0 1751 64 31 0 0 + idle 255 0 224081 2068 64 32 0 0 + main 127 1 3 29 1024 365 0 0 +$ +``` http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/296699c8/docs/os/tutorials/project-sim-slinky.md ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/project-sim-slinky.md b/docs/os/tutorials/project-sim-slinky.md new file mode 100644 index 0000000..8a6eb4e --- /dev/null +++ b/docs/os/tutorials/project-sim-slinky.md @@ -0,0 +1,119 @@ +## Project Sim Slinky + +This tutorial shows you how to create, build and run the Slinky application and communicate with newtmgr for a simulated device. + +<br> +### Prerequisites + +Meet the prerequisites listed in [Project Slinky](/os/tutorials/project-slinky.md). + +### Creating a new project + +Instructions for creating a project are located in the [Basic Setup](../get_started/project_create/) section of the [Mynewt Documentation](../introduction/) + +We will list only the steps here for brevity. We will name the project `slinky`. + +```no-highlight +$ newt new slinky +Downloading project skeleton from apache/incubator-mynewt-blinky... +... +Installing skeleton in slink... +Project slinky successfully created +$ cd slinky +$newt install +apache-mynewt-core +``` + +### Setting up your target build + +Create a target for `slinky` using the native bsp. We will list only the steps and suppress the tool output here for brevity. + +```no-highlight + $ newt target create sim_slinky + $ newt target set sim_slinky bsp=@apache-mynewt-core/hw/bsp/native + $ newt target set sim_slinky build_profile=debug + $ newt target set sim_slinky app=@apache-mynewt-core/apps/slinky +``` + +### Building Your target + +To build your target, use `newt build`. When complete, an executable file +is created. + +```no-highlight + $ newt build sim_slinky + 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 + +Run the executable you have build for the simulated environment. The serial port name on which the simulated target is connected is shown in the output when mynewt slinky starts. + +```no-highlight + $ ~/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. + +**NOTE:** This application will block. You will need to open a new console (or execute this in another console) to continue the tutorial.* + +<br> + +### Setting up a connection profile + +You will now set up a connection profile using `newtmgr` for the serial port connection and start communicating with the simulated remote device. + +```no-highlight + $ newtmgr conn add sim1 type=serial connstring=/dev/ttys005 + Connection profile sim1 successfully added + $ newtmgr conn show + Connection profiles: + 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_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 + 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 +will echo that string back in a response to newtmgr. + +```no-highlight + $ newtmgr -c sim1 echo "Hello Mynewt" + Hello Mynewt +``` + +In addition to these, you can also examine running tasks, statistics, +logs, image status (not on sim), and configuration.