nrfjprog, pynrfjprog - Intro, Mac OS X & Linux now supported, New Feature

#Highlights

  • New release of nrfjprog, pynrfjprog, mergehex available at: http://www.nordicsemi.com/eng/Products/Bluetooth-Smart-Bluetooth-low-energy/nRF52832. Windows, OS X and Linux now supported.
  • New feature in pynrfjprog enables multiple devices to be controlled and selectively programmed.

Do you want a more efficient way to program your devices than nRFgo Studio? Are you an OS X or Linux user who has struggled setting up a toolchain for nRF5x devices? Maybe you are using JLink.exe or an open source tool to program your devices or maybe you even wrote your own? If this is you READ THIS POST!

If you have already been using nrfjprog, pynrfjprog, mergehex you may want to skip to the 'Multi API' section of this post. This introduces the new feature in pynrfjprog that enables multiple devices to be controlled and selectively programmed from python (great for automated testing, scripting, workflow, etc...).

#Motivation As developers our goal is to ship a great product. We have time constraints and deadlines to meet and to efficiently build our product we need to have a good workflow in place. It is key to be able to compile, run and debug applications quickly. It is proven a shorter compile & run/debug cycle leads to cleaner, less buggy code. And added efficiency here WILL ultimately lead to a better product and make you a happier developer. If it takes you over 30 seconds to build and run/debug your applications (including erasing the chip, programming soft-device & or bootloader along with your application) then you are not operating at full efficiency. From blinky to production you will do this thousands of times - take a few minutes to get this right!

#What does an ideal toolchain for nRF5x devices look like currently?

  • Selecting the ideal compiler/IDE for your product. This takes price, code performance, code size, developer friendliness, platforms supported etc... into consideration. See https://devzone.nordicsemi.com/blogs/835/comparing-compilersides-for-development-with-nrf5x/.
  • Programming (erasing, flashing, reading/writing memory, protecting chip, etc...) your device. When using an IDE you should be doing this directly from the IDE (if you don't already know how to do this for your IDE ask in the comments and I'll answer). When using a Make you should have a make flash option that erases, flashes softdevice and flashes application (use nrfjprog for this). See https://github.com/andenore/NordicSnippets/blob/master/common/gcc/Makefile for an example of this.
  • Modern debugging techniques. Average developer spends 21% of time debugging. Be efficient here! Lots to be said on this but an example of a modern debugging technique that is great for Nordic devices is https://devzone.nordicsemi.com/blogs/829/segger-embedded-studio-part-2-monitor-mode-debuggi/. Also use RTT instead of UART https://devzone.nordicsemi.com/tutorials/6/ (trust me it is WAY better and easier).
  • Automated testing. Depending on your current workflow pynrfjprog may be very useful for you. (i.e. you are testing a mesh network and need to program many devices).
  • Programming custom hardware. Ideally have a 6 pin or 10 pin header for one of these SEGGER needle adapters https://www.segger.com/jlink-adapters.html. Then just plug the SEGGER needle adapter into the 'Debug Out' port on your nRF5x development kit, connect the dev kit to your computer, and debug just like you always have!

#5 minute nrfjprog quick start nrfjprog is a command line utility that allows you to erase, flash, unlock, read/write memory etc... from the command line.

  • Download & Install nRF5x-Command-Line-Tools for your operating system http://www.nordicsemi.com/eng/Products/Bluetooth-Smart-Bluetooth-low-energy/nRF52832.

EDIT (nikolaus's comment): I've added nrfjprog (and mergehex) to Homebrew Cask, meaning they can be installed on OS X using:

brew cask install nrf5x-command-line-tools

This will automatically handle putting them in the right place, so they'll be in your PATH and immediately usable. Thanks!

  • Run 'nrfjprog' from the command line. The man page will be displayed (if its not you didn't properly add nrfjprog to your system path, but this is done by the installer in windows). Skim over this to see everything nrfjprog can do.

Note: nrfjprog and pynrfjprog relies on SEGGER's JLinkARM.dll. This means it will only work with a debugger running SEGGER firmware (all our development kits come shipped with SEGGER software so this works by default).

mergehex.exe is in the same folder as nrfjprog.exe so just run mergehex from the command line and read the man page and you will understand how to use it.

The most common nrfjprog commands: image description

#5 minute pynrfjprog quick start pynrfjprog has the same functionality of nrfjprog and more in Python! You may want to use shell scripting with nrfjprog to do many things in one command but pynrfjprog gives you finer control of the nRF5x device and gives you options like using Python's Unit Testing Framework and many of the benefits that come along with Python.

  1. Run 'pip install pynrfjprog' from the command line.
  2. Go to your equivalent: 'C:\Python27\Lib\site-packages\pynrfjprog\examples' and look at a few of the examples or even run them.
  3. You will see this in the examples above 'from pynrfjprog import API, Hex' is how you import this module.

Example of pynrfjprog in use: image description

And most of the functions available from API.py (Just open 'C:\Python27\Lib\site-packages\pynrfjprog\API.py': image description

#pynrfjprog new feature: Multi API Just a quick demo of the new feature. Very similar to what you are used to with pynrfjprog - just unlocks new possibilities. image description

Limitations:

  • Linux & OS X: Multi API class cannot be instantiated if an API class has already been instantiated and opened.
  • Windows: Scripts containing instances of Multi API must perform their activity inside if name == 'main':

#Where to go from here What tools do you use? Do you use JLink.exe? Why do you use this instead of nrfjprog? What will you use these tools for? Any suggestions? What do you want to see, what isn't necessary? Official documentation on these tools is currently being edited and will be on the infocenter soon. What other documentation do you need, examples? Do you flash your softdevice/application directly from the IDE? Why not? How is your workflow efficient? done

EDIT: Do you want our tools to be open source? How would this help you?

Anonymous
  • I had to use this to install via Homebrew:

    brew tap caskroom/drivers
    brew cask install nordic-nrf5x-command-line-tools
    
  • @Lee Daniel Crocker

    nrfjprog does not enable pinreset by itself, and I am certain of that since I am the programmer. But I can think of two ways it happens:

    1. You build your project with the macro CONFIG_GPIO_AS_PINRESET defined. If that is the case, on the first run of the SW the SystemInit() function in system_nrf52.c (or system_nrf52840.c) file will write those values.
    2. Your code in some way defines a const variable placed at 0x10001200 with the value. You can open yourself the hex file and take alook at the end of the code.

    If those are not the case, please tell and I can take a look at it.

  • BUG REPORT:

    nrfjprog version: 9.3.1 JLinkARM.dll version: 6.12g

    I haven't figured out the exact way to trigger this yet, but about half the time when programming either the softdevice or bootloader from hex file, nrfjprog pre-emptively enables pinreset without being asked to in any way (no command line, and nothing in either hex file). It's quite clear--I read address 0x10001200 before the --program statement with 0xFFFFFFFF, and afterward it contains 0x00000015.

    I have had to eliminate the use of nrfjprog from my Makefiles and use Segger's JLink scripts to program my device to work around this bug. But nrfjprog is handy, and I would use it if it were fixed.

  • The problem is that the debug port is not abkle in nRF51 to get out of debug interface mode, so some regulators and oscillators are kept on. A pin reset will stop those current drains. Perform a pin reset and measure again.

    Note that this is only valid in nRF51 devices.