Flash, reset and view

This is the first page in the section that needs hardware: a board with a SEGGER J-Link, which on many Ambiq EVBs is onboard rather than a separate probe. It also needs the J-Link Software and Documentation Pack, so if nsx doctor still reports the SEGGER checks as failures, fix that first.

The terminals below are illustrative examples, not captured hardware runs. Probe serial numbers are fictional; the flash example summarizes the sequence in brackets. Actual J-Link messages vary with the software version, board and build state.

1. Find the probe

nsx probes enumerates connected J-Link probes and prints their USB serial numbers. Here is an example with two probes connected:

Probe discovery · example

        $
        nsx probes
      
        
        SERIAL     PRODUCT   NICKNAME
      
        
        123456789  J-Link    -
      
        
        987654321  J-Link    -
      

$ nsx probes SERIAL PRODUCT NICKNAME 123456789 J-Link - 987654321 J-Link -

With a board attached it lists one line per probe. --json gives the same list in machine-readable form. If exactly one probe is connected you never need to name it; with more than one, pass --probe-serial <serial> to every command that touches hardware. The serial is printed here and on the probe label.

See nsx probes.

2. Flash

Flash sequence · illustrative summary

        $
        nsx flash --probe-serial 123456789
      
        
        [Configure the app and build the firmware]
      
        
        [Connect to the selected J-Link probe over SWD]
      
        
        [Program and verify the firmware image]
      
        
        [Reset the target and start the application]
      

$ nsx flash --probe-serial 123456789 [Configure the app and build the firmware] [Connect to the selected J-Link probe over SWD] [Program and verify the firmware image] [Reset the target and start the application]

nsx flash builds the app if the image is out of date, then drives JLinkExe over SWD using the command file NSX generated into build/<board>/jlink/. Expect the Ninja build lines you already saw from nsx build, if anything needed rebuilding, followed by J-Link’s own connect, program and verify output, and then a reset that starts the firmware.

nsx flash takes the same --board, --toolchain, --target, --jobs, --update and --frozen options as nsx build, plus --probe-serial.

–probe-serial always reconfigures

The probe serial is baked into the generated SEGGER command files, so passing --probe-serial forces a reconfigure. --frozen changes how the accompanying module sync behaves, not whether the reconfigure happens.

See nsx flash.

3. View

nsx view

nsx view opens JLinkSWOViewerCL against the board’s SEGGER device and streams ITM port 0. The app generated by nsx create-app prints one line per second from its main loop, so the viewer should settle into a repeating heartbeat:

nsx hello from generated app
nsx hello from generated app
nsx hello from generated app

Press Ctrl-C to stop.

The reset policy

Whether the viewer resets the target after it attaches depends on the SoC. NSX resets by default, except on the apollo3p, apollo4l, apollo4p and apollo510b SoCs, where a SEGGER reset can halt in the secure boot handoff and drop the viewer. On those boards NSX attaches without resetting and prints a line telling you so, which is why the working order there is nsx flash and then nsx view: the flash already started the app.

Three options override it:

• --reset-on-open forces the reset.
• --no-reset-on-open suppresses it.
• --reset-delay-ms changes how long NSX waits after the viewer attaches before resetting.

Recording instead of watching

• --duration SECONDS stops the viewer on a timer instead of running until interrupted.
• --capture FILE line-streams the output to a file as well as to your terminal.

Together they make a viewer run scriptable, which is what CI and benchmark harnesses use. Use --duration rather than wrapping the command in timeout. On Linux and macOS NSX also stops the viewer if it is sent SIGTERM, but --duration ends the capture cleanly.

See nsx view.

4. Reset on its own

nsx reset talks to the probe directly, so it takes the SEGGER device name rather than an app directory.

nsx reset --device AP510NFA-CBR

AP510NFA-CBR is the device the Apollo510 EVB resolves to. Other boards set their own; the value NSX uses for your board appears in the generated build/<board>/build.ninja as the -device argument.

--kind picks the reset primitive, debug or swpoi. --interface and --speed-khz set the debug interface and its speed, and --verify-reconnect reconnects afterwards and fails if the target did not come back.

See nsx reset.

When it does not work

• Nothing listed by nsx probes: check the USB cable and that the board is powered, then re-run nsx doctor to confirm the SEGGER runtime starts.
• Flash succeeds but the viewer shows nothing: on a secure-reset SoC the app may not have been started. Flash again, or pass --reset-on-open.
• More than one board on the desk: pass --probe-serial explicitly rather than letting NSX pick.

Next

Next steps points at the guides, the module catalog and the reference.