newtmgr

Save Subscribe

newtmgr is an image management tool that can be used to interact with the bootloader and images on the device. For full details on the newtmgr tool and the entire command set see the official newtmgr documentation.

Installing newtmgr

For details on installing the newtmgr tool on your operating system of choice see:

Connection Profiles

The newtmgr tool works with connection profiles, such as serial or ble, depending on how you wish to communicate with the device under test.

Before you can use newtmgr you will need to setup at least one connection profile, as described below:

Adding a Serial Connection Profile

Download File
Copy Code 
$ newtmgr conn add serial1 type=serial connstring=/dev/tty.SLAB_USBtoUART

Or, on windows:

Download File
Copy Code 
$ newtmgr conn add serial1 type=serial connstring=COM14

Listing Existing Profiles

You can get a list of all defined connection profiles via:

Download File
Copy Code 
$ newtmgr conn show
Connection profiles: 
  serial1: type=serial, connstring='/dev/tty.SLAB_USBtoUART'

Test the Serial Connection Profile

You can test the connection profile with the 'image list' command, which will list any application images present in flash memory:

Download File
Copy Code 
$ newtmgr -c serial1 image list
Images:
 slot=0
    version: 0.1.0
    bootable: true
    flags: active confirmed
    hash: be52a255c25546dacc497d62faea910459903a1c1916ce831697d40fc2c20689
Split status: N/A (0)
The image shown above is the default image that the nRF52 Pro ships with

Common newtmgr Commands

The following commands are commonly used when doing day to day development and debugging with Mynewt based devices:

Display Scheduler Task Activity via 'taskstat'

You can also test the connection with newtmgr using the taskstat command, which will list some basic statistics about the tasks running in the task manager.

Enter the following command:

Download File
Copy Code 
$ newtmgr -c serial1 taskstat

Which should give you the following task statistics (output will vary depending on the Mynewt application that is running at the time):

Download File
Copy Code 
      task pri tid  runtime      csw    stksz   stkuse last_checkin next_checkin
    ble_ll   0   2       21     4381       80       58        0        0
   bleuart   5   3        0    12030      256       31        0        0
      idle 255   0    11980    16292       64       26        0        0
      main 127   1        0       27     1024      210        0        0

Uploading Application Images with newtmgr

If you don't have a Segger J-Link or similar debugger, the newtmgr tool can be used to upload an application image to the secondary bank of flash memory, and then switch application images during the next reset. This allows you to perform field updates over an inexpensive serial connection with no external HW required.

1. Build the Target Application (newt build)

The first step is of course to build the target application that you wish to deploy. The default bleuart project is used in this case:

Download File
Copy Code 
$ newt build bleuart
Building target targets/bleuart
...
Target successfully built: targets/bleuart

2. Sign and Version the Image (newt create-image)

You then need to 'sign' the image you just built with a version number and meta data used to validate the image when flashing, which is done via the create-image command:

Download File
Copy Code 
$ newt create-image bleuart 0.2.0
App image succesfully generated: [PATH]/bin/targets/bleuart/app/apps/bleuart/bleuart.img
Pay attention to the .img output filename since you will need this full path in the next step!

3. Upload the Image (newtmgr image upload)

Now that we have a signed and versioned firmware image, we can copy the image to bank 1 of flash memory using the serial bootloader and the newtmgr tool:

Download File
Copy Code 
$ newtmgr -c serial1 image upload [PATH]/bin/targets/bleuart/app/apps/bleuart/bleuart.img
353
704
...
157426
157612
Done

At this point, you can see that there are two images stored on the device in two different flash banks, the original 0.1.0 image that the board ships with, and the new 0.2.0 image we just built, signed and uploaded:

Download File
Copy Code 
$ newtmgr -c serial1 image list
Images:
 slot=0
    version: 0.1.0
    bootable: true
    flags: active confirmed
    hash: be52a255c25546dacc497d62faea910459903a1c1916ce831697d40fc2c20689
 slot=1
    version: 0.2.0
    bootable: true
    flags: 
    hash: 87276847693699896f68b3c26d378648cace2900db4145cd5ade6049ac5ec15a
Split status: N/A (0)
Pay attention to the 'flags' field, which indicates the state of images on the system. This value will change as we run through the update process.

4. Test the Image Upload (newtmgr image test [hash])

Now that the image has been uploaded successfully to the secondary bank of flash memory, we need to tell the system to 'test' the image during the next reset.

What the test command will do is check the signature of the image, and then try to switch the two flash banks so that the old application (0.1.0) is in the secondary flash bank, and the new application (0.2.0) is in the primary bank.

This happens at reset, and will cause a 15-20 second delay as the flash writes are happening, so be sure to wait for the testing process to complete before interacting or interferring with the device!

You can issue a test (and flash bank switch) request as follows, using the hash value from the image list command above:

Download File
Copy Code 
$ newtmgr -c serial1 image test 87276847693699896f68b3c26d378648cace2900db4145cd5ade6049ac5ec15a
Images:
 slot=0
    version: 0.1.0
    bootable: true
    flags: active confirmed
    hash: be52a255c25546dacc497d62faea910459903a1c1916ce831697d40fc2c20689
 slot=1
    version: 0.2.0
    bootable: true
    flags: pending
    hash: 87276847693699896f68b3c26d378648cace2900db4145cd5ade6049ac5ec15a
Split status: N/A (0)
Notice that the 0.2.0 image flag has been changed to PENDING, which means a test and flash bank switch is pending on the next reset!

5. Reset to Perform the Test and Image Bank Switch (newtmgr reset)

For the flash bank switch and test procedure to complete, you must reset the device, which can be done from the command line as follows:

Download File
Copy Code 
$ newtmgr -c serial1 reset
Done
Be sure to wait at least 20 seconds after issuing the reset command, since the flash write takes 15-20 seconds to complete and the device will appear unresponsive during the update process!

If you run the image list command again you will see that the banks and flags values have changed, with version 0.1.0 in the secondary bank and it's status set to 'confirmed':

Download File
Copy Code 
$ newtmgr -c serial1 image list
Images:
 slot=0
    version: 0.2.0
    bootable: true
    flags: active
    hash: 87276847693699896f68b3c26d378648cace2900db4145cd5ade6049ac5ec15a
 slot=1
    version: 0.1.0
    bootable: true
    flags: confirmed
    hash: be52a255c25546dacc497d62faea910459903a1c1916ce831697d40fc2c20689
Split status: N/A (0)

6. Confirm the Image Switch (newtmgr image confirm)

The final step is to 'confirm' the image update process to make it permanent, which is done via the image confirm sub-command:

Download File
Copy Code 
$ newtmgr -c serial1 image confirm
As of newtmgr 1.1.0 the 'confirm' command will always return "Error: 1", but the confirm process does work, as verified with the image list command below!

If you check the flags values again, you will see that version 0.2.0 is now 'confirmed' and will continue to execute every time you reset the device:

Download File
Copy Code 
$ newtmgr -c serial1 image list
Images:
 slot=0
    version: 0.2.0
    bootable: true
    flags: active confirmed
    hash: 87276847693699896f68b3c26d378648cace2900db4145cd5ade6049ac5ec15a
 slot=1
    version: 0.1.0
    bootable: true
    flags: 
    hash: be52a255c25546dacc497d62faea910459903a1c1916ce831697d40fc2c20689
Split status: N/A (0)
If you reset without confirming, the device will revert to the original (0.1.0) image!
Note: You can optionally skip the 'test + reset' phase, and go directly to confirming an image after the upload is finished by using 'newtmgr -c serial1 confirm [hash]' with the hash of the image to finalize. This is a more dangerous choice, but the option is there if you wish to save some time.

Display Internal Statistics

Mynewt has an internal statistics system that is very useful when debugging issues in the field or during development. You can defined individual statistics fields, and increment the values at appropriate moments, and access these from the command-line with the newtmgr stat command set.

List all Statistic Groups

Download File
Copy Code 
$ newtmgr -c serial1 stat list
stat groups:
    ble_att
    ble_gap
    ble_gattc
    ble_gatts
    ble_hs
    ble_l2cap
    ble_ll
    ble_ll_conn
    ble_phy
    ble_uart
    nffs_stats
    stat

List all Values in a Statistic Group

Download File
Copy Code 
$ newtmgr -c serial1 stat ble_phy
stat group: ble_phy
      8310 phy_isrs
         0 radio_state_errs
        15 rx_aborts
         0 rx_crc_err
         0 rx_hw_err
         0 rx_late
        15 rx_starts
         0 rx_valid
    265440 tx_bytes
         0 tx_fail
      8295 tx_good
         0 tx_hw_err
         0 tx_late
 newt Apache Mynewt Applications 

This guide was first published on Aug 18, 2017. It was last updated on Aug 18, 2017.

This page (newtmgr) was last updated on Aug 15, 2017.

Text editor powered by tinymce.