This tutorial assumes that you have read the Device Management with Newt Manager 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:
See Other Configuration Options on how to customize your application.
Ensure that you have met the following prerequisites before continuing with this tutorial:
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 or application pkg.yml
file:
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
commandsys/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:
syscfg.vals: LOG_NEWTMGR: 1 STATS_NEWTMGR: 1 CONFIG_NEWTMGR: 1 CRASH_TEST_NEWTMGR: 1 RUNTEST_NEWTMGR: 1 SHELL_TASK: 1 SHELL_NEWTMGR: 1
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
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 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 modify your main.c
to add the call to the mgmt_evq_set()
function as follows:
Add the mgmt/mgmt.h
header file:
#include <mgmt/mgmt.h>
mgmt_evq_set(&my_eventq)
where 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/apps/boot/boot.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 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:
# newtmgr -c myconn echo hello hello
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, modify the pkg.yml
and syscfg.yml
files as follows:
mgmt/newtmgr/transport/ble
package to the pkg.deps
parameter to enable BLE transport.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 Shell.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 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.To use the oicmgr framework instead of the newtmgr framework, modify the pkg.yml
and syscfg.yml
files as follows:
mgmt/oicmgr
package (instead of the mgmt/newtmgr
and mgmt/newtmgr/transport
packages as described previously) to the pkg.deps
parameter.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:
OC_TRANSPORT_IP: 1
to enable IP transport.OC_TRANSPORT_GATT: 1
to enable BLE transport.OC_TRANSPORT_SERIAL: 1
, SHELL_TASK: 1
, SHELL_NEWTMGR:1
to 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: 1
to enable support for the newtmgr log
command.STATS_NEWTMGR: 1
to enable support for the newtmgr stat
command.CONFIG_NEWTMGR: 1
to enable support for the newtmgr config
command.CRASH_TEST_NEWTMGR: 1
to enable support for the newtmgr crash
command.RUNTEST_NEWTMGR: 1
to enable support for the newtmgr crash
command.Notes:
echo
, taskstat
, mpstat
, datetime
, and reset
commands. These commands cannot be configured individually.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.