| Enabling Newt Manager in Your Application |
| ----------------------------------------- |
| |
| In order for your application to communicate with the newtmgr tool and |
| process Newt Manager commands, you must enable Newt Manager device |
| management and the support to process Newt Manager commands in your |
| application. This tutorial explains how to add the support to your |
| application. |
| |
| This tutorial assumes that you have read the :doc:`Device Management with |
| Newt Manager <../../../os/modules/devmgmt/newtmgr>` guide and are familiar |
| with the ``newtmgr`` and ``oicmgr`` frameworks and all the options that |
| are available to customize your application. |
| |
| This tutorial shows you how to configure your application to: |
| |
| - Use the newtmgr framework. |
| - Use serial transport to communicate with the newtmgr tool. |
| - Support all Newt Manager commands. |
| |
| See :doc:`Other Configuration Options <#other-configuration-options>` on |
| how to customize your application. |
| |
| .. contents:: |
| :local: |
| :depth: 2 |
| |
| Prerequisites |
| ~~~~~~~~~~~~~ |
| |
| Ensure that you have met the following prerequisites before continuing |
| with this tutorial: |
| |
| - Have Internet connectivity to fetch remote Mynewt components. |
| - Have a cable to establish a serial USB connection between the board |
| and the laptop. |
| - Install the newt tool and toolchains (See :doc:`Basic |
| Setup <../../get_started/index>`). |
| - Install the :doc:`newtmgr tool <../../newtmgr/docs/install/index>`. |
| |
| Use an Existing Project |
| ~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| We assume that you have worked through at least some of the other |
| tutorials and have an existing project. In this example, we modify the |
| ``btshell`` app to enable Newt Manager support. We call our target |
| ``myble``. You can create the target using any name you choose. |
| |
| Modify Package Dependencies and Configurations |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| Add the following packages to the ``pkg.deps`` parameter in your target |
| or application ``pkg.yml`` file: |
| |
| .. code-block:: console |
| |
| pkg.deps: |
| - mgmt/newtmgr |
| - mgmt/newtmgr/transport/nmgr_shell |
| - mgmt/imgmgr |
| - sys/log/full |
| - sys/stats/full |
| - sys/config |
| - test/crash_test |
| - test/runtest |
| |
| Each package provides the following Newt Manager functionality: |
| |
| - ``mgmt/newtmgr``: Supports the newtmgr framework and the Newt Manager |
| ``echo``, ``taskstat`` ``mpstat``, ``datetime``, and ``reset`` |
| commands. |
| - ``mgmt/newtmgr/transport/nmgr_shell``: Supports serial transport. |
| - ``mgmt/imgmgr``: Supports the ``newtmgr image`` command |
| - ``sys/log/full`` : Supports the ``newtmgr log`` command. |
| - ``sys/stats/full``: Supports the ``newtmgr stat`` command. |
| - ``sys/config``: Supports the ``newtmgr config`` command. |
| - ``test/crash_test``: Supports the ``newtmgr crash`` command. |
| - ``test/runtest``: Supports the ``newt run`` command. |
| |
| Add the following configuration setting values to the ``syscfg.vals`` |
| parameter in the target or application ``syscfg.yml`` file: |
| |
| .. code-block:: console |
| |
| |
| syscfg.vals: |
| LOG_NEWTMGR: 1 |
| STATS_NEWTMGR: 1 |
| CONFIG_NEWTMGR: 1 |
| CRASH_TEST_NEWTMGR: 1 |
| RUNTEST_NEWTMGR: 1 |
| SHELL_TASK: 1 |
| SHELL_NEWTMGR: 1 |
| |
| The first five configuration settings enable support for the Newt |
| Manager ``log``, ``stat``, ``config``, ``crash``, and ``run`` commands. |
| The ``SHELL_TASK`` setting enables the shell for serial transport. The |
| ``SHELL_NEWTMGR`` setting enables newtmgr support in the shell. |
| |
| Note that you may need to override additional configuration settings |
| that are specific to each package to customize the package |
| functionality. |
| |
| Modify the Source |
| ~~~~~~~~~~~~~~~~~ |
| |
| By default, the ``mgmt`` package uses the Mynewt default event queue to |
| receive request events from the newtmgr tool. These events are processed |
| in the context of the application main task. |
| |
| You can specify a different event queue for the package to use. If you |
| choose to use a dedicated event queue, you must create a task to process |
| events from this event queue. The ``mgmt`` package executes and handles |
| newtmgr request events in the context of this task. The ``mgmt`` package |
| exports the ``mgmt_evq_set()`` function that allows you to specify an |
| event queue. |
| |
| This example uses the Mynewt default event queue and you do not need to |
| modify your application source. |
| |
| If you choose to use a different event queue, see :doc:`Events and Event |
| Queues <../os_fundamentals/event_queue>` for details on how to initialize an event |
| queue and create a task to process the events. You will also need to |
| modify your ``main.c`` to add the call to the ``mgmt_evq_set()`` |
| function as follows: |
| |
| Add the ``mgmt/mgmt.h`` header file: |
| |
| .. code-block:: c |
| |
| #include <mgmt/mgmt.h> |
| |
| Add the call to specify the event queue. In the ``main()`` function, |
| scroll down to the ``while (1)`` loop and add the following statement |
| above the loop: |
| |
| .. code-block:: c |
| |
| mgmt_evq_set(&my_eventq) |
| |
| where ``my_eventq`` is an event queue that you have initialized. |
| |
| Build the Targets |
| ~~~~~~~~~~~~~~~~~ |
| |
| Build the two targets as follows: |
| |
| .. code-block:: console |
| |
| $ newt build nrf52_boot |
| <snip> |
| App successfully built: ./bin/nrf52_boot/apps/boot/boot.elf |
| $ newt build myble |
| Compiling hci_common.c |
| Compiling util.c |
| Archiving nimble.a |
| Compiling os.c |
| <snip> |
| |
| Create the Application Image |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| Generate an application image for the ``myble`` target. You can use any |
| version number you choose. |
| |
| .. code-block:: console |
| |
| $ newt create-image myble 1.0.0 |
| App image successfully generated: ./bin/makerbeacon/apps/btshell/btshell.img |
| Build manifest: ./bin/makerbeacon/apps/btshell/manifest.json |
| |
| Load the Image |
| ~~~~~~~~~~~~~~ |
| |
| Ensure the USB connector is in place and the power LED on the board is |
| lit. Turn the power switch on your board off, then back on to reset the |
| board after loading the image. |
| |
| .. code-block:: console |
| |
| $ newt load nrf52_boot |
| $ newt load myble |
| |
| Set Up a Connection Profile |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| The newtmgr tool requires a connection profile in order to connect to |
| your board. If you have not done so, follow the |
| :doc:`instructions <../../newtmgr/command_list/newtmgr_conn>` for |
| setting up your connection profile. |
| |
| Communicate with Your Application |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| Once you have a connection profile set up, you can connect to your |
| device with ``newtmgr -c myconn <command>`` to run commands in your |
| application. |
| |
| Issue the ``echo`` command to ensure that your application is |
| communicating with the newtmgr tool: |
| |
| .. code-block:: console |
| |
| $ newtmgr -c myconn echo hello |
| hello |
| |
| Test your application to ensure that it can process a Newt Manager |
| command that is supported by a different package. Issue the ``stat`` |
| command to see the BLE stats. |
| |
| .. code-block:: console |
| |
| stat group: ble_att |
| 0 error_rsp_rx |
| 0 error_rsp_tx |
| 0 exec_write_req_rx |
| 0 exec_write_req_tx |
| 0 exec_write_rsp_rx |
| 0 exec_write_rsp_tx |
| 0 find_info_req_rx |
| 0 find_info_req_tx |
| 0 find_info_rsp_rx |
| 0 find_info_rsp_tx |
| 0 find_type_value_req_rx |
| |
| ... |
| |
| 0 read_type_req_tx |
| 0 read_type_rsp_rx |
| 0 read_type_rsp_tx |
| 0 write_cmd_rx |
| 0 write_cmd_tx |
| 0 write_req_rx |
| 0 write_req_tx |
| 0 write_rsp_rx |
| 0 write_rsp_tx |
| |
| Your application is now able to communicate with the newtmgr tool. |
| |
| Other Configuration Options |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| This section explains how to customize your application to use other |
| Newt Manager protocol options. |
| |
| Newtmgr Framework Transport Protocol Options |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| 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 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`` and |
| ``SHELL_NEWTMGR`` to the ``syscfg.vals`` parameter to enable serial |
| transport when your application also uses the |
| :doc:`Shell <../../../os/modules/shell/shell>`. |
| - 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 |
| :doc:`Shell <../../../os/modules/shell/shell>` 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. |
| |
| Oicmgr Framework Options |
| ^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| To use the oicmgr framework instead of the newtmgr framework, modify the |
| ``pkg.yml`` and ``syscfg.yml`` files as follows: |
| |
| - Add the ``mgmt/oicmgr`` package (instead of the ``mgmt/newtmgr`` and |
| ``mgmt/newtmgr/transport`` packages as described previously) to the |
| ``pkg.deps`` parameter. |
| - Add ``OC_SERVER: 1`` to the ``syscfg.vals`` parameter. |
| |
| Oicmgr supports the IP, serial, and BLE transport protocols. To |
| configure the transport protocols that are supported, set the |
| configuration setting values in the ``syscfg.vals`` parameter as |
| follows: |
| |
| - Add ``OC_TRANSPORT_IP: 1`` to enable IP transport. |
| - Add ``OC_TRANSPORT_GATT: 1`` to enable BLE transport. |
| - Add ``OC_TRANSPORT_SERIAL: 1``, ``SHELL_TASK: 1``, |
| ``SHELL_NEWTMGR:1`` to enable serial transport. |
| |
| Customize the Newt Manager Commands that Your Application Supports |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| We recommend that you only enable support for the Newt Manager commands |
| that your application uses to reduce your application code size. To |
| configure the commands that are supported, set the configuration setting |
| values in the ``syscfg.vals`` parameter as follows: |
| |
| - Add ``LOG_NEWTMGR: 1`` to enable support for the ``newtmgr log`` |
| command. |
| - Add ``STATS_NEWTMGR: 1`` to enable support for the ``newtmgr stat`` |
| command. |
| - Add ``CONFIG_NEWTMGR: 1`` to enable support for the |
| ``newtmgr config`` command. |
| - Add ``CRASH_TEST_NEWTMGR: 1`` to enable support for the |
| ``newtmgr crash`` command. |
| - Add ``RUNTEST_NEWTMGR: 1`` to enable support for the |
| ``newtmgr crash`` command. |
| |
| Notes: |
| |
| - When you enable Newt Manager support, using either the newtmgr or |
| oicmgr framework, your application automatically supports the Newt |
| Manager ``echo``, ``taskstat``, ``mpstat``, ``datetime``, and |
| ``reset`` commands. These commands cannot be configured individually. |
| - The ``mgmt/imgmgr`` package does not provide a configuration setting |
| to enable or disable support for the ``newtmgr image`` command. Do |
| not specify the package in the ``pkg.deps`` parameter if your device |
| has limited flash memory and cannot support Over-The-Air (OTA) |
| firmware upgrades. |