blinky tutorials

docs/index.rst

@@ -10,6 +10,7 @@ Introduction
    self
    get_started/index
    concepts
+   tutorials/tutorials
    os/os_user_guide
    newt/index
    misc/index

docs/misc/ide.rst

@@ -31,7 +31,7 @@ Prerequisites:
 -  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.
--  Complete one of the :doc:`Blinky Tutorials <../tutorials/blinky/index>`.
+-  Complete one of the :doc:`Blinky Tutorials <../tutorials/blinky/blinky>`.
 
 **Notes:**
 

docs/tutorials/blinky/blinky.rst

@@ -0,0 +1,85 @@
+Blinky, your "Hello World!" on a Target Board
+=============================================
+
+.. toctree::
+   :hidden:
+
+   arduino_zero
+   blinky_primo
+   olimex
+   nRF52
+   rbnano2
+   blinky_stm32f4disc
+   blinky_console
+
+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 :doc:`../../get_started/project_create` tutorial.
+
+.. contents::
+  :local:
+  :depth: 2
+
+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:
+
+-  :doc:`arduino_zero`
+-  :doc:`blinky_primo`
+-  :doc:`olimex`
+-  :doc:`nRF52`
+-  :doc:`rbnano2`
+-  :doc:`blinky_stm32f4disc`
+
+We also have a tutorial that shows you how to add :doc:`blinky_console`.
+
+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 :doc:`../../get_started/index`).
+-  Read the Mynewt OS :doc:`../../concepts` section.
+-  Create a project space (directory structure) and populate it with the
+   core code repository (apache-mynewt-core) or know how to as explained
+   in :doc:`../../get_started/project_create`.
+
+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.
+
+After you try the Blinky application on your boards, checkout out other
+tutorials to enable additional functionality such as :doc:`remote
+comms <../slinky/project-slinky>` 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 :doc`iBeacon <../ble/ibeacon>` or :doc:`Eddystone
+Beacon <../ble/eddystone>`!
+
+If you see anything missing or want to send us feedback, please sign up
+for appropriate mailing lists on our `Community
+Page </community.html>`__.

docs/tutorials/blinky/blinky_console.rst

@@ -0,0 +1,239 @@
+Enabling The Console and Shell for Blinky
+-----------------------------------------
+
+This tutorial shows you how to add the Console and Shell to the Blinky
+application and interact with it over a serial line connection.
+
+Prerequisites
+~~~~~~~~~~~~~
+
+-  Work through one of the Blinky Tutorials to create and build a Blinky
+   application for one of the boards.
+-  Have a `serial setup </os/get_started/serial_access.html>`__.
+
+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.html>`__ project to enable the
+shell and console connectivity. You can use blinky on a different board.
+
+Modify the Dependencies and Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Modify the package dependencies in your application target's ``pkg.yml``
+file as follows:
+
+-  Add the shell package: ``@apache-mynewt-core/sys/shell``.
+-  Replace the ``@apache-mynewt-core/sys/console/stub`` package with the
+   ``@apache-mynewt-core/sys/console/full`` package.
+
+   **Note**: If you are using version 1.1 or lower of blinky, the
+   ``@apache-mynewt-core/sys/console/full`` package may be already
+   listed as a dependency.
+
+The updated ``pkg.yml`` file should have the following two lines:
+
+.. code-block:: console
+
+    pkg.deps:
+        - "@apache-mynewt-core/sys/console/full"
+        - "@apache-mynewt-core/sys/shell"
+
+This lets the newt system know that it needs to pull in the code for the
+console and the shell.
+
+Modify the system configuration settings to enable Shell and Console
+ticks and prompt. Add the following to your application target's
+``syscfg.yml`` file:
+
+.. code-block:: console
+
+    syscfg.vals:
+        # Enable the shell task.
+        SHELL_TASK: 1
+        SHELL_PROMPT_MODULE: 1
+
+Use the OS Default Event Queue to Process Blinky Timer and Shell Events
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Mynewt creates a main 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 main task.
+
+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:
+
+-  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()``.
+
+This allows the main task to process both Shell events and the timer
+events to toggle the LED from the OS default event queue.
+
+Modify main.c
+~~~~~~~~~~~~~
+
+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:
+
+.. code:: c
+
+    /* 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);
+
+        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);
+    }
+
+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 hl\_lines="15 17" int 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(os_eventq_dflt_get());
+    }
+    assert(0);
+    return rc;
+
+}
+
+\`\`\`
+
+Build, Run, and Upload 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.
+
+We will use the ``newt run`` command to build and deploy our improved
+blinky image. The run command performs the following tasks for us:
+
+1. Builds a binary Mynewt executable
+2. Wraps the executable in an image header and footer, turning it into a
+   Mynewt image.
+3. Uploads the image to the target hardware.
+4. Starts a gdb process to remotely debug the Mynewt device.
+
+Run the ``newt run nrf52_blinky 0`` command. The ``0`` is the version
+number that should be written to the image header. Any version will do,
+so we choose 0.
+
+.. code-block:: console
+
+    $ newt run nrf52_blinky 0
+
+       ...
+
+    Archiving util_mem.a
+    Linking /home/me/dev/myproj/bin/targets/nrf52_blinky/app/apps/blinky/blinky.elf
+    App image succesfully generated: /home/me/dev/myproj/bin/targets/nrf52_blinky/app/apps/blinky/blinky.elf
+    Loading app image into slot 1
+    [/home/me/dev/myproj/repos/apache-mynewt-core/hw/bsp/nrf52dk/nrf52dk_debug.sh /home/me/dev/myproj/repos/apache-mynewt-core/hw/bsp/nrf52dk /home/me/dev/myproj/bin/targets/nrf52_blinky/app/apps/blinky]
+    Debugging /home/me/dev/myproj/bin/targets/nrf52_blinky/app/apps/blinky/blinky.elf
+
+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.html>`__ Tutorial for more information
+on setting up your serial communication.
+
+Communicate with the Application
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Once you have a connection set up, you can connect to your device as
+follows:
+
+-  On Mac OS and Linux platforms, you can run
+   ``minicom -D /dev/tty.usbserial-<port> -b 115200`` to connect to the
+   console of your app. Note that on Linux, the format of the port name
+   is ``/dev/ttyUSB<N>``, where N is a number.
+
+-  On Windows, you can use a terminal application such as PuTTY to
+   connect to the device.
+
+If you located your port from a MinGW terminal, the port name format is
+``/dev/ttyS<N>``, where ``N`` is a number. You must map the port name to
+a Windows COM port: ``/dev/ttyS<N>`` maps to ``COM<N+1>``. For example,
+``/dev/ttyS2`` maps to ``COM3``.
+
+You can also use the Windows Device Manager to locate the COM port.
+
+To test and make sure that the Shell is running, first just hit :
+
+.. code-block:: console
+
+    004543 shell>
+
+You can try some commands:
+
+.. code-block:: console
+
+    003005 shell> help
+    003137 Available modules:
+    003137 os
+    003138 prompt
+    003138 To select a module, enter 'select <module name>'.
+    003140 shell> prompt
+    003827 help
+    003827 ticks                         shell ticks command
+    004811 shell> prompt ticks off
+    005770  Console Ticks off
+    shell> prompt ticks on
+    006404  Console Ticks on
+    006404 shell>