Repository: incubator-mynewt-site Updated Branches: refs/heads/develop b8cab1b93 -> 51ea3d02f
1) Added Blinky RedBear Nano 2 tutorial 2) Updated Blinky for Olimex: - Add instruction to use USB-OTG2 port for power source instead of JTG/SWD. - Add note that the diagram has USB-OTG2 and USB-OTG1 labels reversed. 3) Added back and updated Project Slinky for Olimex board 4) Clarify description for newtmgr_uart in enabling newtmgr app tutorial. 5) Updated Blinky for Primo: - Move Install JlinkExe to Debugger option 1 (using jlink probe) - Specify Blinky blinks the orange LED (L13) to distiguish the wifi green led on board the blinks too. - Added command to erase flash when using OpenOCD 6) Updated Add Shell and Console to Blinky tutorial to use default OS eventq and default task instead of defining a dedicated task for shell events. 7) Add install JLink to Blinky NRF52 since it uses the JlinkEXE in the tutorial. 8) Cleaned Project Slinky Sim tutorial 9) Fix typo in os_task_remove 10) Removed Blinky Boot from Olimex SRAM 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/3a6e4ff0 Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/3a6e4ff0 Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/3a6e4ff0 Branch: refs/heads/develop Commit: 3a6e4ff0ef247378aec02ee856fa146b17aab305 Parents: b8cab1b Author: cwanda <[email protected]> Authored: Tue Mar 28 10:43:54 2017 -0700 Committer: cwanda <[email protected]> Committed: Tue Mar 28 23:53:22 2017 -0700 ---------------------------------------------------------------------- docs/os/core_os/task/os_task_remove.md | 2 +- docs/os/tutorials/add_newtmgr.md | 6 +- docs/os/tutorials/blinky_console.md | 163 +++++++++-------- docs/os/tutorials/blinky_primo.md | 44 +++-- docs/os/tutorials/nRF52.md | 5 +- docs/os/tutorials/olimex.md | 14 +- docs/os/tutorials/project-slinky.md | 26 +-- docs/os/tutorials/project-stm32-slinky.md | 243 +++++++++++++++++++++++++ docs/os/tutorials/rbnano2.md | 206 +++++++++++++++++++++ mkdocs.yml | 3 +- 10 files changed, 583 insertions(+), 129 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/3a6e4ff0/docs/os/core_os/task/os_task_remove.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/task/os_task_remove.md b/docs/os/core_os/task/os_task_remove.md index 79f18c3..02af47c 100644 --- a/docs/os/core_os/task/os_task_remove.md +++ b/docs/os/core_os/task/os_task_remove.md @@ -22,7 +22,7 @@ Removes a task, `t`, from the task list. A task cannot be removed when it is in `OS_OK`: Task `t` is removed sucessfully. <br>`OS_INVALID_PARM`: Task `t` is the calling task. A task cannot remove itself. <br>`OS_NOT_STARTED`: Task `t` is not initialized. -<br>`OS_EBUSY`: Task `t` is either holding a lock or suspended waiting on lock on event. +<br>`OS_EBUSY`: Task `t` is either holding a lock or suspended waiting for a lock or an event. <br> #### Example http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/3a6e4ff0/docs/os/tutorials/add_newtmgr.md ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/add_newtmgr.md b/docs/os/tutorials/add_newtmgr.md index 5d975cc..658560f 100644 --- a/docs/os/tutorials/add_newtmgr.md +++ b/docs/os/tutorials/add_newtmgr.md @@ -220,10 +220,10 @@ The newtmgr framework currently supports BLE and serial transport protocols. To configure the transport protocols that are supported, modify the `pkg.yml` and `syscfg.yml` files as follows: -* Add the `mgmt/newtmgr/transport/ble` package to `pkg.deps` parameter to enable BLE transport. +* Add the `mgmt/newtmgr/transport/ble` package to the `pkg.deps` parameter to enable BLE transport. * Add the `mgmt/newtmgr/transport/nmgr_shell` package to -the `pkg.deps` parameter, and add `SHELL_TASK: 1` to the `syscfg.vals` parameter to enable serial transport. -* Add the `mgmt/newtmgr/transport/nmgr_uart` package, and add `SHELL_TASK: 1` to enable serial communication over a UARTport. +the `pkg.deps` parameter, and add `SHELL_TASK: 1` to the `syscfg.vals` parameter to enable serial transport when your application also uses the [Shell](/os/modules/shell/shell.md). +* Add the `mgmt/newtmgr/transport/nmgr_uart` package to the `pkg.deps` parameter to enable serial transport over a UART port. You can use this package instead of the `nmgr_shell` package when your application does not use the [Shell](/os/modules/shell/shell.md) or you want to use a dedicated UART port to communicate with newtmgr. You can change the `NMGR_UART` and `NMGR_URART_SPEED` sysconfig values to specify a different port. <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/3a6e4ff0/docs/os/tutorials/blinky_console.md ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/blinky_console.md b/docs/os/tutorials/blinky_console.md index f3fd9ff..81c9afe 100644 --- a/docs/os/tutorials/blinky_console.md +++ b/docs/os/tutorials/blinky_console.md @@ -2,37 +2,28 @@ <br> -This tutorial explains how to add the Console and Shell task to the blinky app so that you -can interact with it over a serial line connection. +This tutorial explains how to add the Console and Shell task to the blinky application so that you can interact with it over a serial line connection. <br> -### Pre-Requisites +### Prerequisites -* Ensure you have installed [newt](../../newt/install/newt_mac.md) and that the -newt command is in your system path. -* You must have Internet connectivity to fetch remote Mynewt components. -* You must [install the compiler tools](../get_started/native_tools.md) to -support native compiling to build the project this tutorial creates. -* You must install the [Segger JLINK package]( https://www.segger.com/jlink-software.html) to -load your project on the board. -* Cable to establish a serial USB connection between the board and the laptop +* Work through one of the Blinky Tutorials to create and build a Blinky application for one of the boards. <br> -### Use an existing project +### Use an Existing Project Since all we're doing is adding the shell and console capability to blinky, we assume that you have worked through at least some of the other tutorials, and have an existing project. For this example, we'll be modifying the [blinky on nrf52](./nRF52.md) project to enable -the shell and console connectivity. Feel free to use whatever version of blinky you'd like though. +the shell and console connectivity. You can use blinky on a different board. <br> ###Modify the Dependencies and Configuration -The first thing you'll need to add is a few new dependencies for your app. To add shell support to -your app make sure the following `pkg.deps` are defined in your target's pkg.yml file: +Add the following dependencies to your application target's `pkg.yml` file: ``` pkg.deps: @@ -43,12 +34,9 @@ pkg.deps: This lets the newt system know that it needs to pull in the code for the console and the shell. -Now we'll need to modify the settings for the app to turn on the shell, etc. by modifying the -`syscfg.yml` file for your target. (Remember, these files are in the targets/<app-name> directory.) -If there isn't a `syscfg.yml` file in your target's directory, you will need to create one. +Modify the system configuration settings to enable Shell and Console ticks and prompt. Add the following to your application target's `syscfg.yml` file: ```no-highlight -# Package: apps/bletiny syscfg.vals: # Enable the shell task. @@ -59,104 +47,130 @@ syscfg.vals: CONSOLE_PROMPT: 1 ``` -### Add an Event Queue +<br> +### Use the OS Default Event Queue to Process Blinky Timer and Shell Events +Mynewt creates a default task that executes the application `main()` function. It also creates an OS default event queue that packages can use to queue their events. Shell uses the OS default event queue for Shell events, and `main()` can process the events in the context of the default task. -Blinky is a small app that doesn't make use of tasks or an event queue as many other apps do, so -we'll have to modify the source for the app in order to add one. +Blinky's main.c is very simple. It only has a `main()` function that executes an infinite loop to toggle the LED and sleep for one second. We will modify blinky: -```c -/* System event queue task handler */ -#define SYSEVQ_PRIO (1) -#define SYSEVQ_STACK_SIZE OS_STACK_ALIGN(512) -static struct os_task task_sysevq; -os_stack_t sysevq_stack[SYSEVQ_STACK_SIZE]; +* To use os_callout to generate a timer event every one second instead of sleeping. The timer events are added to the OS default event queue. +* To process events from the OS default event queue inside the infinite loop in `main()`. -/* Event queue for events handled by the system (shell, etc.) */ -static struct os_eventq sys_evq; -``` +This allows the default task to process both Shell events and the timer events to toggle the LED from the OS default event queue. -We define a new `os_task` a task stack (`sysevq_stack`) and new system event queue -(`sys_evq`) so that the shell and console will have an event queue to run in. +<br> +### Modify main.c -Next we go down to our `init_tasks()` function and initialize it +Initialize a os_callout timer and move the toggle code from the while loop in `main()` to the event callback function. Add the following code above the `main()` function: ```c -os_task_init(&task_sysevq, "sysevq", sysevq_handler, NULL, - SYSEVQ_PRIO, OS_WAIT_FOREVER, sysevq_stack, SYSEVQ_STACK_SIZE); -os_eventq_init(&sys_evq); -os_eventq_dflt_set(&sys_evq); -``` +/* The timer callout */ +static struct os_callout blinky_callout; + +/* + * Event callback function for timer events. It toggles the led pin. + */ +static void timer_ev_cb(struct os_event *ev) +{ + assert(ev != NULL); + + ++g_task1_loops; + hal_gpio_toggle(g_led_pin); -This will initialize the task, initialize the event queue, and then set the new event queue as -the default event queue. + os_callout_reset(&blinky_callout, OS_TICKS_PER_SEC); +} + +static void init_timer(void) +{ + /* + * Initialize the callout for a timer event. + */ + os_callout_init(&blinky_callout, os_eventq_dflt_get(), + timer_ev_cb, NULL); + + os_callout_reset(&blinky_callout, OS_TICKS_PER_SEC); + +} +``` -Finally, we need to add the task handler for the event queue: +In `main()`, add the call to the `init_timer()` function before the while loop and modify the while loop to process events from the OS default event queue: ```c -/** - * This task serves as a container for the shell and newtmgr packages. These - * packages enqueue timer events when they need this task to do work. - */ -static void -sysevq_handler(void *arg) +main(int argc, char **argv) { + + int rc; + +#ifdef ARCH_sim + mcu_sim_parse_args(argc, argv); +#endif + + sysinit(); + + g_led_pin = LED_BLINK_PIN; + hal_gpio_init_out(g_led_pin, 1); + init_timer(); while (1) { - os_eventq_run(&sys_evq); + os_eventq_run(os_eventq_dflt_get()); } + assert(0) + return rc; } -``` -### Build targets +``` +<br> +### Build the Blinky Application Target We're not going to build the bootloader here since we are assuming that you have already built and loaded it during previous tutorials. +Run the `newt build nrf52_blinky` command to build the Blinky application: + ```no-highlight -$ newt build blinky -Archiving cbmem.a -Compiling crc16.c -Compiling crc8.c -Archiving crc.a -Compiling mem.c -Archiving mem.a -Linking ~/dev/myproj/bin/targets/blinky/app/apps/blinky/blinky.elf -Target successfully built: targets/blinky +$ newt build nrf52_blinky + + ... + +Archiving util_mem.a +Linking ~/dev/myproj/bin/targets/nrf52_blinky/app/apps/blinky/blinky.elf +Target successfully built: targets/nrf52_blinky ``` <br> -### Create the app image +### Sign and Create the Blinky Application Image -Generate a signed application image for the `blinky` target. The version number is arbitrary. +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 blinky 1.0.0 -App image succesfully generated: ~/dev/myproj/bin/targets/blinky/app/apps/blinky/blinky.img +```no-highlight +$ newt create-image nrf52_blinky 1.0.0 +App image succesfully generated: ~/dev/myproj/bin/targets/nrf52_blinky/app/apps/blinky/blinky.img ``` <br> -### Load the image +### Load the Image Make sure the USB connector is in place and the power LED on the board is lit. Use the Power ON/OFF switch to reset the board after loading the image. -``` -$ newt load blinky +Run the `newt load nrf52_blinky` command to load the Blinky application image onto the board. +```no-highlight +$ newt load nrf52_blinky +Loading app image into slot 1 ``` <br> -### Set up Serial connection +### Set Up a Serial Connection You'll need a Serial connection to see the output of your program. You can reference the [Serial Port Setup](../get_started/serial_access.md) -Tutorial for more information on setting up your serial communications. +Tutorial for more information on setting up your serial communication. <br> -###Connecting with your app +###Communicate with the Application -Once you have a connection set up, you can connect to your device with ```minicom -D /dev/tty.usbmodem<port> -b 115200``` to run connect -to the console of your app. +Once you have a connection set up, run ```minicom -D /dev/tty.usbmodem<port> -b 115200``` to connect to the application console. To test and make sure that the Shell is running, first just hit <return>: @@ -164,7 +178,7 @@ To test and make sure that the Shell is running, first just hit <return>: 3534: > ``` -Remember, we turned the CONSOLE_PROMPT and the CONSOLE_TICKS on earlier. You can try some commands now: +You can try some commands: ```no-highlight 3609: > ? @@ -184,4 +198,3 @@ prompt on 39108: > ``` -And there you have the Console and Shell working in an app that previously had no event queue! \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/3a6e4ff0/docs/os/tutorials/blinky_primo.md ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/blinky_primo.md b/docs/os/tutorials/blinky_primo.md index 7bade06..cf769b9 100644 --- a/docs/os/tutorials/blinky_primo.md +++ b/docs/os/tutorials/blinky_primo.md @@ -22,7 +22,7 @@ Ensure that you have met the following prerequisites before continuing with this * 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. -* Install a 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. +* Install a debugger - choose one of the two options below. Option 1 requires additional hardware but very easy to set up. Option 2 is free software but not as simple as Option 1. <br> @@ -30,6 +30,8 @@ Ensure that you have met the following prerequisites before continuing with this * [Segger J-Link Debug Probe](https://www.segger.com/jlink-debug-probes.html) - any model (this tutorial has been tested with J-Link EDU and J-Link Pro) * [J-Link 9 pin Cortex-M Adapter](https://www.segger.com/jlink-adapters.html#CM_9pin) that allows JTAG, SWD and SWO connections between J-Link and Cortex M based target hardware systems +* Install the [Segger JLINK Software and documentation pack](https://www.segger.com/jlink-software.html). + ##### Option 2 @@ -48,29 +50,9 @@ Licensed under GNU GPL v2 For bug reports, read http://openocd.org/doc/doxygen/bugs.html ``` -Next, make sure that you have checked out the newt develop branch and rebuilt newt. -``` -$ cd $GOPATH/src/mynewt.apache.org/newt -$ git checkout develop -$ git pull -$ cd newt -$ go install -``` -**Note:** This step can be removed once the changes have been pushed to master. - You can now use openocd to upload to Arduino Primo board via the USB port itself. - - <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). - -<br> - ### 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. @@ -219,14 +201,14 @@ Loading app image into slot 1 $ ``` -You should see the LED on the board blink! +You should see the orange LED (L13), below the ON LED, on the board blink! Note: If the LED does not blink, try resetting the board. <br> -**Note:** If you want to erase the flash and load the image again, you can use JLinkExe to issue an `erase` command. +**Note:** If you want to erase the flash and load the image again, use JLinkExe and issue the `erase` command when you are using the Jlink debug probe: ``` $ JLinkExe -device nRF52 -speed 4000 -if SWD @@ -252,7 +234,23 @@ Erasing done. J-Link>exit $ ``` +<br> +If you are using the OpenOCD debugger, run the `newt debug primoblinky` command and issue the highlighted command at the (gdb) prompt: + +```hl_lines="11" +$newt debug primoblinky +[~/dev/myproj/repos/apache-mynewt-core/hw/bsp/arduino_primo_nrf52/primo_debug.sh ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/arduino_primo_nrf52 ~/dev/myproj/bin/targets/primoblinky/app/apps/blinky/blinky] +Open On-Chip Debugger 0.10.0-dev-snapshot (2017-03-28-11:24) + + ... + +os_tick_idle (ticks=128) + at repos/apache-mynewt-core/hw/mcu/nordic/nrf52xxx/src/hal_os_tick.c:200 +warning: Source file is more recent than executable. +200 if (ticks > 0) { +(gdb) mon nrf52 mass_erase +``` <br> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/3a6e4ff0/docs/os/tutorials/nRF52.md ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/nRF52.md b/docs/os/tutorials/nRF52.md index 2a14967..2b199bb 100644 --- a/docs/os/tutorials/nRF52.md +++ b/docs/os/tutorials/nRF52.md @@ -6,7 +6,7 @@ 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. -Create a project with a simple app that blinks an LED on the nRF52 board from Nordic Semiconductors. Download the application to the target and watch it blink! +Create a project with a simple application that blinks an LED on the nRF52 board from Nordic Semiconductors. Download the application to the target and watch it blink! Note that there are several versions of the nRF52 in the market. The boards tested with this tutorial are listed under "Prerequisites". @@ -23,11 +23,11 @@ Ensure that you have met the following prerequisites before continuing with this * 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 the [Segger JLINK package]( https://www.segger.com/jlink-software.html) to load your project on the board. * 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 uses the Nordic nRF52-DK board. -<br> ### 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. @@ -147,7 +147,6 @@ Run the `newt create-image nrf52_blinky 1.0.0` command to create and sign the ap ```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 ``` http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/3a6e4ff0/docs/os/tutorials/olimex.md ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/olimex.md b/docs/os/tutorials/olimex.md index c42a957..de1b0c2 100644 --- a/docs/os/tutorials/olimex.md +++ b/docs/os/tutorials/olimex.md @@ -15,7 +15,8 @@ Ensure that you have met the following prerequisites before continuing with this * 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 Internet connectivity to fetch remote Mynewt components. * Have a computer to build a Mynewt application and connect to the board over USB. -* Have USB A-B type cable to connect the debugger to your computer. +* Have a USB A-B type cable to connect the debugger to your computer. +* Have a USB Micro-A cable to connect your computer to the board. * 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. @@ -135,7 +136,9 @@ App image succesfully generated: ~/dev/myproj/bin/targets/olimex_blinky/app/apps ### Connect to the Board -Configure the 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 the board. +Configure the board to bootload from flash memory and to use USB-OTG2 for the power source. Refer to the following diagrams to locate the boot jumpers and power input select jumpers on the board. + +**Note:** The labels for the **USB-OTG1** and **USB-OTG2** ports on the diagram are reversed. The port labeled USB-OTG1 on the diagram is the USB-OTG2 port and the port labeled USB-OTG2 on the diagram is the USB-OTG1 port. <br> <p align="center"> @@ -149,8 +152,9 @@ Configure the board to bootload from flash memory and to use the JTAG/SWD for th * 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. -* 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 the [OLIMEX STM32-E407 user manual](https://www.olimex.com/Products/ARM/ST/STM32-E407/resources/STM32-E407.pdf) for pin specifications. - +* Locate the **Power Input Select** jumpers on the lower left corner of the board. Set the Power Select jumpers to position 5 and 6 to use the USB-OTG2 port for the power source. If you would like to use a different power source, refer to the [OLIMEX STM32-E407 user manual](https://www.olimex.com/Products/ARM/ST/STM32-E407/resources/STM32-E407.pdf) for pin specifications. + +* Connect the USB Micro-A cable to the USB-OTG2 port on the board. * Connect the JTAG connector to the JTAG/SWD interface on the board. @@ -180,7 +184,7 @@ Successfully loaded image. 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. +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/3a6e4ff0/docs/os/tutorials/project-slinky.md ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/project-slinky.md b/docs/os/tutorials/project-slinky.md index 40f93e3..2b39f61 100644 --- a/docs/os/tutorials/project-slinky.md +++ b/docs/os/tutorials/project-slinky.md @@ -8,14 +8,15 @@ The goal of the project is to use a sample app called "Slinky" included in the M If you have an existing project using a target that does not use the Slinky app and you wish to add newtmgt functonality to it, check out the tutorial titled [Enable newtmgr in any app](add_newtmgr.md). <br> +### Prerequisites -### What you need +Ensure that you have met the following prerequisites before continuing with this tutorial: -1.Personal Computer - -The instructions assume the user is using a Bourne-compatible shell (e.g. bash or zsh) on your computer. The given instructions have been tested with the following releases of operating systems: - -* Mac: OS X Yosemite Version 10.10.5 +* Have Internet connectivity to fetch remote Mynewt components. +* Have a computer to build a Mynewt application. +* Install the newt tool and the toolchains (See [Basic Setup](/os/get_started/get_started.md)). +* Install the [newtmgr tool](../../newtmgr/installing/). +* Read the Mynewt OS [Concepts](/os/get_started/vocabulary.md) section. ### Overview of steps @@ -26,16 +27,6 @@ The instructions assume the user is using a Bourne-compatible shell (e.g. bash o * Create a connection profile using the newtmgr tool * Use the newtmgr tool to communicate with the targets -### Installing newt - -If you have not already installed `newt` see the -[newt installation instructions](../get_started/get_started/) and ensure newt is installed an in your path. - -### Installing newtmgr - -If you have not already installed `newtmgr` see the -[newtmgr installation instructions](../../newtmgr/installing/) and ensure newtmgr is installed an in your path. - ### 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/) @@ -98,8 +89,7 @@ is created. ### 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. +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 http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/3a6e4ff0/docs/os/tutorials/project-stm32-slinky.md ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/project-stm32-slinky.md b/docs/os/tutorials/project-stm32-slinky.md new file mode 100644 index 0000000..926a459 --- /dev/null +++ b/docs/os/tutorials/project-stm32-slinky.md @@ -0,0 +1,243 @@ +## Project Slinky Using STM32 Board + +The goal of the project is to enable and demonstrate remote communications with the Mynewt OS via newt manager (newtmgr) by leveraging a sample app "Slinky" included under the /apps directory in the repository. In this project we will define a target for the STM32-E407 board and assign the app "Slinky" to it. + +If you have an existing project that has a different application and you wish to add newtmgr functionality to it, check out the [Enable newtmgr in any app](add_newtmgr.md) tutorial. + +<br> + + +###Prerequisites +Ensure that you have met the following prerequisites before continuing with this tutorial: + +* 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 a USB to TTL Serial Cable with female wiring harness. +* Have a USB Micro-A cable to connect your computer to the board. +* Have Internet connectivity to fetch remote Mynewt components. +* Have a computer to build a Mynewt application and connect to the board over USB. +* Install the newt tool and the toolchains (See Basic Setup). +* Install the newtmgr tool. +* 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. +* Read the Mynewt OS Concepts section. + +### Overview of Steps + +* Install dependencies +* Define a target using the newt tool +* Build executables for the targets using the newt tool +* Set up serial connection with the targets +* Create a connection profile using the newtmgr tool +* Use the newtmgr tool to communicate with the targets + +### 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. + +```no-highlight +$ newt new slinky +Downloading project skeleton from apache/incubator-mynewt-blinky... +... +Installing skeleton in slink... +Project slink successfully created +$ cd slinky +$newt install +apache-mynewt-core +``` + +<br> + +###<a name="create_targets"></a> Create the Targets +Create two targets for the STM32-E407 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 ` +stm32_boot`. + +```no-highlight +$ newt target create stm32_boot +$ newt target set stm32_bootr bsp=@apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard +$ newt target set stm32_boot build_profile=optimized +$ newt target set stm32_boot target.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 `stm32_slinky`. + +```no-highlight +$ newt target create stm32_slinky +$ newt target set stm32_slinky bsp=@apache-mynewt-core/hw/bsp/olimex_stm32-e407_devboard +$ newt target set stm32_slinky build_profile=debug +$ newt target set stm32_slinky app=@apache-mynewt-core/apps/slinky +``` +<br> + +### Build the Targets +Run the `newt build stm32_boot` command to build the bootloader: + +```no-highlight +$ newt build stm32_boot +Building target targets/stm32_boot +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/loader.c +Compiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.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/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/stm32_boot/app/apps/boot/boot.elf +Target successfully built: targets/stm32_boot +$ +``` +<br> +Run the `newt build stm32_slinky` command to build the Slinky application: + +```no-highlight +$newt build stm32_slinky +Building target targets/stm32_slinky +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/bootutil/src/image_ec256.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/split/src/split.c +Compiling repos/apache-mynewt-core/boot/bootutil/src/bootutil_misc.c +Compiling repos/apache-mynewt-core/apps/slinky/src/main.c + + ... + +Archiving util_crc.a +Archiving util_mem.a +Linking ~/dev/slinky/bin/targets/stm32_slinky/app/apps/slinky/slinky.elf +Target successfully built: targets/stm32_slinky +$ +``` +<br> +### Sign and Create the Slinky Application Image + +Run the `newt create-image stm32_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 +create-image stm32_slinky 1.0.0 +App image succesfully generated: ~/dev/slinky/bin/targets/stm32_slinky/app/apps/slinky/slinky.img +$ +``` +<br> + + +###Connect to the Board + +* Connect the USB A-B type cable to the ARM-USB-TINY-H debugger connector. +* Connect the ARM-USB-Tiny-H debugger connector to your computer and the board. +* Connect the USB Micro-A cable to the USB-OTG2 port on the board. +* Set the Power Sel jumper on the board to pins 5 and 6 to select USB-OTG2 as the power source. If you would like to use a different power source, refer to the [OLIMEX STM32-E407 user manual](https://www.olimex.com/Products/ARM/ST/STM32-E407/resources/STM32-E407.pdf) for pin specifications. + +You should see a red LED light up on the board. + +<br> +### Load the Bootloader and the Slinky Application Image + +Run the `newt load stm32_boot` command to load the bootloader onto the board: + +```no-highlight +$ newt load stm32_boot +Loading bootloader +$ +``` +<br> +Run the `newt load stm32_slinky` command to load the Slinky application image onto the board: +```no-highlight +$ newt load stm32_slinky +Loading app image into slot 1 +$ +``` +<br> + +### Connect Newtmgr with the Board using a Serial Connection + +Locate the PC6/USART6_TX (pin 3), PC7/USART6_RX (pin 4), and GND (pin 2) of the UEXT connector on the Olimex board. More information on the UEXT connector can be found at [https://www.olimex.com/Products/Modules/UEXT/](https://www.olimex.com/Products/Modules/UEXT/). The schematic of the board can be found at [https://www.olimex.com/Products/ARM/ST/STM32-E407/resources/STM32-E407_sch.pdf](https://www.olimex.com/Products/ARM/ST/STM32-E407/resources/STM32-E407_sch.pdf) for reference. + + + + +* Connect the female RX pin of the USB-TTL serial cable to the TX (Pin 3) of the UEXT connector on the board. +* Connect the female TX pin of the USB-TTL serial cable to the RX (Pin 4) of the UEXT connector on the board. +* Connect the GND pin of the USB-TTL serial cable to the GND (Pin 2) of the UEXT connector on the board. + +<br> +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-1d13 +$ +``` + +<br> +Setup a newtmgr connection profile for the serial port. For our example, the port is `/dev/tty.usbserial-1d13`. + +Run the `newtmgr conn add` command to define a newtmgr connection profile for the serial port. We name the connection profile `stm32serial`. You will need to replace the `connstring` with the specific port for your serial connection. + +```no-highlight +$ newtmgr conn add stm32serial type=serial connstring=/dev/tty.usbserial-1d13 +Connection profile stm32serial 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: + stm32serial: type=serial, connstring='/dev/tty.usbserial-1d13' + 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 stm32serial` command. This is the simplest command that requests the board to echo back the + text. + +```no-highlight +$ newtmgr echo hello -c stm32serial +hello +$ +``` +<br> +Run the `newtmgr image list -c stm32serial` command to list the images on the board: + +```no-highlight +$ newtmgr image list -c stm32serial +Images: + slot=0 + version: 1.0.0 + bootable: true + flags: active confirmed + hash: 9cf8af22b1b573909a8290a90c066d4e190407e97680b7a32243960ec2bf3a7f +Split status: N/A +$ +``` + + +<br> +Run the `newtmgr taskstats -c stm32serial` command to display the task statistics on the board: + +```no-highlight +$ newtmgr taskstats -c stm32serial +Return Code = 0 + task pri tid runtime csw stksz stkuse last_checkin next_checkin + task1 8 2 0 90 192 110 0 0 + task2 9 3 0 90 64 31 0 0 + idle 255 0 89460 89463 64 26 0 0 + main 127 1 4 26 1024 368 0 0 +$ +``` + + http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/3a6e4ff0/docs/os/tutorials/rbnano2.md ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/rbnano2.md b/docs/os/tutorials/rbnano2.md new file mode 100644 index 0000000..52883fa --- /dev/null +++ b/docs/os/tutorials/rbnano2.md @@ -0,0 +1,206 @@ +## Blinky, your "Hello World!", on RedBear Nano 2 + +<br> + +### 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 the LED lights on the target board. + +Create a project with a simple application that blinks an LED on a RedBear Nano 2 board. Download the application to the target and watch it blink! + +<br> + +### Prerequisites + +Ensure that you have met the following prerequisites before continuing with this tutorial: + +* Have a RedBear Nano 2 board. +* Have Internet connectivity to fetch remote Mynewt components. +* Have a computer to build a Mynewt application and connect to the 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. + +**Note:** You must install a patched version of OpenOCD .10.0 (See [Debugger Option 2 in the Arduino Primo Blinky Tutorial](/os/tutorials/blinky_primo)). + +### 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. + +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> + +### <a name="create_targets"></a>Create the Targets + +Create two targets for the RedBear Nano 2 board - one for the bootloader and one for the Blinky application. + +Run the following `newt target` commands, from your project directory, to create a bootloader target. We name the target `rbnano2_boot`: + +```no-highlight +$ newt target create rbnano2_boot +$ newt target set rbnano2_boot app=@apache-mynewt-core/apps/boot +$ newt target set rbnano2_boot bsp=@apache-mynewt-core/hw/bsp/rb-nano2 +$ newt target set rbnano2_boot build_profile=optimized +``` + +<br> +Run the following `newt target` commands to create a target for the Blinky application. We name the target `nrf52_blinky`. + +```no-highlight +$ newt target create rbnano2_blinky +$ newt target set rbnano2_blinky app=apps/blinky +$ newt target set rbnano2_blinky bsp=@apache-mynewt-core/hw/bsp/rb-nano2 +$ newt target set rbnano2_blinky build_profile=debug +``` +<br> +You can run the `newt target show` command to verify the target settings: + +```no-highlight +$ newt target show +targets/rbnano2_blinky + app=apps/blinky + bsp=@apache-mynewt-core/hw/bsp/rb-nano2 + build_profile=debug +targets/rbnano2_boot + app=@apache-mynewt-core/apps/boot + bsp=@apache-mynewt-core/hw/bsp/rb-nano2 + build_profile=optimized +``` +<br> + +### Build the Target Executables + +Run the `newt build rbnano2_boot` command to build the bootloader: + +```no-highlight +$newt build rbnano2_boot +Building target targets/rbnano2_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/boot/bootutil/src/loader.c +Compiling repos/apache-mynewt-core/crypto/mbedtls/src/aes.c +Compiling repos/apache-mynewt-core/boot/bootutil/src/image_validate.c +Compiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c +Compiling repos/apache-mynewt-core/boot/bootutil/src/bootutil_misc.c +Compiling repos/apache-mynewt-core/apps/boot/src/boot.c + + ... + +Archiving sys_sysinit.a +Archiving util_mem.a +Linking ~/dev/myproj/bin/targets/rbnano2_boot/app/apps/boot/boot.elf +Target successfully built: targets/rbnano2_boot +``` + +<br> +Run the `newt build rbnano2_blinky` command to build the Blinky application: + +```no-highlight +$newt build rbnano2_blinky +Building target targets/rbnano2_blinky +Assembling repos/apache-mynewt-core/hw/bsp/rb-nano2/src/arch/cortex_m4/gcc_startup_nrf52_split.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/rb-nano2/src/sbrk.c +Compiling apps/blinky/src/main.c + + ... + +Archiving sys_sysinit.a +Archiving util_mem.a +Linking ~/dev/myproj/bin/targets/rbnano2_blinky/app/apps/blinky/blinky.elf +Target successfully built: targets/rbnano2_blinky + +``` + +<br> + +### Sign and Create the Blinky Application Image + +Run the `newt create-image rbnano2_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. + +```no-highlight +$newt create-image rbnano2_blinky 1.0.0 +App image succesfully generated: ~/dev/myproj/bin/targets/rbnano2_blinky/app/apps/blinky/blinky.img +``` + +<br> + +### Connect to the Board + +Connect the RedBear Nano 2 USB to a USB port on your computer. You should see an orange LED light up on the board. + + +### Load the Bootloader and the Blinky Application Image + +Run the `newt load rbnano2_boot` command to load the bootloader onto the board: + +```no-highlight +$ newt load rbnano2_boot +Loading bootloader +$ +``` +<br> +Note: The flash memory on the RedBear Nano 2 comes write protected from the factory. If you get an error loading the bootloader and you are using a brand new chip, you need to clear the write protection from the debugger and then load the bootloader again. Run the `newt debug rbnano2_blinky` command and issue the following commands at the highlighted (gdb) prompts. + +```hl_lines="8 9 11 14" +$newt debug rbnano2_blinky +[~/dev/myproj/repos/apache-mynewt-core/hw/bsp/rb-nano2/rb-nano2_debug.sh ~/dev/myproj/repos/apache-mynewt-core/hw/bsp/rb-nano2 ~/dev/myproj/bin/targets/rbnano2_blinky/app/apps/blinky/blinky] +Open On-Chip Debugger 0.10.0-dev-snapshot (2017-03-28-11:24) +Licensed under GNU GPL v2 + + ... + +(gdb) set {unsigned long}0x4001e504=2 +(gdb) x/1wx 0x4001e504 +0x4001e504:0x00000002 +(gdb) set {unsigned long}0x4001e50c=1 +Info : SWD DPIDR 0x2ba01477 +Error: Failed to read memory at 0x00009ef4 +(gdb) x/32wx 0x00 +0x0:0xffffffff0xffffffff0xffffffff0xffffffff +0x10:0xffffffff0xffffffff0xffffffff0xffffffff +0x20:0xffffffff0xffffffff0xffffffff0xffffffff +0x30:0xffffffff0xffffffff0xffffffff0xffffffff +0x40:0xffffffff0xffffffff0xffffffff0xffffffff +0x50:0xffffffff0xffffffff0xffffffff0xffffffff +0x60:0xffffffff0xffffffff0xffffffff0xffffffff +0x70:0xffffffff0xffffffff0xffffffff0xffffffff +(gdb) +``` + +<br> +Run the `newt load rbnano2_blinky` command to load the Blinky application image onto the board. +```no-highlight +$ newt load rbnano2_blinky +Loading app image into slot 1 +``` + +You should see a blue LED on the board blink! + +Note: If the LED does not blink, try resetting your board. + + +### Conclusion + +You have created, setup, compiled, loaded, and ran your first mynewt application for a RedBear Nano 2 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. + +If you see anything missing or want to send us feedback, please do so by signing up for appropriate mailing lists on our [Community Page](../../community.md). + +Keep on hacking and blinking! + http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/3a6e4ff0/mkdocs.yml ---------------------------------------------------------------------- diff --git a/mkdocs.yml b/mkdocs.yml index ba52bb6..0080930 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -36,7 +36,7 @@ pages: - toc: 'os/tutorials/STM32F303.md' - 'Pinwheel Blinky': 'os/tutorials/pin-wheel-mods.md' - 'Blinky on nRF52': 'os/tutorials/nRF52.md' - - 'Run Blinky from SRAM, no bootloader': 'os/tutorials/blinky_sram_olimex.md' + - 'Blinky on RedBear Nano 2': 'os/tutorials/rbnano2.md' - 'Add Console and Shell to Blinky': 'os/tutorials/blinky_console.md' - 'Work with repositories': - toc: 'os/tutorials/repo/add_repos.md' @@ -50,6 +50,7 @@ pages: - 'Project Slinky for remote comms': - 'Slinky on sim device': 'os/tutorials/project-slinky.md' - 'Slinky on Nordic nRF52 board': 'os/tutorials/project-target-slinky.md' + - 'Slinky on STM32 board': 'os/tutorials/project-stm32-slinky.md' - 'Enable Newt Manager in any app': 'os/tutorials/add_newtmgr.md' - 'Enable the OS Shell and Console': 'os/tutorials/add_shell.md' - 'BLE app to check stats via console': 'os/tutorials/bletiny_project.md'
