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 Device Management with
Newt Manager guide and are familiar
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 Other Configuration Options on how to customize your application.
- Use an Existing Project
- Modify Package Dependencies and Configurations
- Modify the Source
- Build the Targets
- Create the Application Image
- Load the Image
- Set Up a Connection Profile
- Communicate with Your Application
- Other Configuration Options
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 Basic Setup).
- Install the newtmgr tool.
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.
Add the following packages to the
pkg.deps parameter in your target
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
mgmt/newtmgr/transport/nmgr_shell: Supports serial transport.
mgmt/imgmgr: Supports the
sys/log/full: Supports the
sys/stats/full: Supports the
sys/config: Supports the
test/crash_test: Supports the
test/runtest: Supports the
Add the following configuration setting values to the
parameter in the target or application
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
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.
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_evq_set() function that allows you to specify an
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 Events and Event
Queues for details on how to initialize an event
queue and create a task to process the events. You will also need to
main.c to add the call to the
function as follows:
mgmt/mgmt.h header file:
Add the call to specify the event queue. In the
scroll down to the
while (1) loop and add the following statement
above the loop:
my_eventq is an event queue that you have initialized.
Build the two targets as follows:
$ newt build nrf52_boot <snip> App successfully built: ./bin/nrf52_boot/boot/mynewt/mynewt.elf $ newt build myble Compiling hci_common.c Compiling util.c Archiving nimble.a Compiling os.c <snip>
Generate an application image for the
myble target. You can use any
version number you choose.
$ 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
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.
$ newt load nrf52_boot $ newt load myble
The newtmgr tool requires a connection profile in order to connect to your board. If you have not done so, follow the instructions for setting up your connection profile.
Once you have a connection profile set up, you can connect to your
newtmgr -c myconn <command> to run commands in your
echo command to ensure that your application is
communicating with the newtmgr tool:
$ 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
command to see the BLE stats.
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.
This section explains how to customize your application to use other Newt Manager protocol options.
The newtmgr framework currently supports BLE and serial transport
protocols. To configure the transport protocols that are supported,
syscfg.yml files as follows:
- Add the
mgmt/newtmgr/transport/blepackage to the
pkg.depsparameter to enable BLE transport.
- Add the
mgmt/newtmgr/transport/nmgr_shellpackage to the
pkg.depsparameter, and add
syscfg.valsparameter to enable serial transport when your application also uses the Shell.
- Add the
mgmt/newtmgr/transport/nmgr_uartpackage to the
pkg.depsparameter to enable serial transport over a UART port. You can use this package instead of the
nmgr_shellpackage when your application does not use the Shell or you want to use a dedicated UART port to communicate with newtmgr. You can change the
NMGR_URART_SPEEDsysconfig values to specify a different port.
To use the oicmgr framework instead of the newtmgr framework, modify the
syscfg.yml files as follows:
- Add the
mgmt/oicmgrpackage (instead of the
mgmt/newtmgr/transportpackages as described previously) to the
OC_SERVER: 1to the
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
OC_TRANSPORT_IP: 1to enable IP transport.
OC_TRANSPORT_GATT: 1to enable BLE transport.
SHELL_NEWTMGR:1to enable serial transport.
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:
LOG_NEWTMGR: 1to enable support for the
STATS_NEWTMGR: 1to enable support for the
CONFIG_NEWTMGR: 1to enable support for the
CRASH_TEST_NEWTMGR: 1to enable support for the
RUNTEST_NEWTMGR: 1to enable support for the
- When you enable Newt Manager support, using either the newtmgr or
oicmgr framework, your application automatically supports the Newt
resetcommands. These commands cannot be configured individually.
mgmt/imgmgrpackage does not provide a configuration setting to enable or disable support for the
newtmgr imagecommand. Do not specify the package in the
pkg.depsparameter if your device has limited flash memory and cannot support Over-The-Air (OTA) firmware upgrades.