newtmgr
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:
- OS X Installation: https://mynewt.apache.org/latest/newt/install/newt_mac.html
- Linux Installation: https://mynewt.apache.org/latest/newt/install/newt_linux.html
- Windows Installation: https://mynewt.apache.org/latest/newt/install/newt_windows.html
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:
$ newtmgr conn add serial1 type=serial connstring=/dev/tty.SLAB_USBtoUART
Or, on windows:
$ newtmgr conn add serial1 type=serial connstring=COM14
$ 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:
$ newtmgr -c serial1 image list
Images:
slot=0
version: 0.1.0
bootable: true
flags: active confirmed
hash: be52a255c25546dacc497d62faea910459903a1c1916ce831697d40fc2c20689
Split status: N/A (0)
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:
$ 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):
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:
$ 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:
$ newt create-image bleuart 0.2.0 App image succesfully generated: [PATH]/bin/targets/bleuart/app/apps/bleuart/bleuart.img
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:
$ 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:
$ 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)
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:
$ 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)
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:
$ newtmgr -c serial1 reset Done
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':
$ 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:
$ newtmgr -c serial1 image confirm
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:
$ 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)
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
$ 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
$ 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
Page last edited March 08, 2024
Text editor powered by tinymce.
