PART I / ENGINEERING JOURNAL
01 / Cause
The RAK4631WisBlock Core module combining a Nordic nRF52840 microcontroller and an SX1262 LoRa radio.Crux usage: The module used as a MeshCore USB Companion in the Atlas Bridge recovery campaign.Open full definition is a useful platform for work that combines an nRF52840Nordic Semiconductor ARM Cortex-M4F microcontroller and wireless system-on-chip.Crux usage: Processing device inside the RAK4631, accessed during recovery using SWD.Open full definition microcontroller, an SX1262Semtech LoRa transceiver IC for sub-GHz radio communications.Crux usage: Provides the RAK4631’s LoRa radio path in CRUX MeshCore nodes.Open full definition LoRa radio and a compact WisBlock mechanical architecture. It became central to Atlas BridgeThe indoor bridge unit linking field communications and local sensors to the Crux Atlas system.Crux usage: The Atlas Bridge receives MeshCore traffic, supports local diagnostics and Daymark events, and sends authoritative data to Atlas over its permanent server connection.Open full definition, the hardware interface between a host computer and the CRUX MeshCoreAn open-source, off-grid mesh communications system that uses LoRa-capable nodes to relay messages across a network.Crux usage: Crux uses MeshCore as a resilient public and fallback communications layer for field nodes, mobile diagnostics, and selected sensor or Daymark events. Private Crux operational data remains separately governed.Open full definition communications network.
During development, we relied on a popular mainstream AI assistant to accelerate decisions about firmware, bootloaders and serial communications. That approach was consistent with the CRUX ambition to leverage practical tools, but it exposed a weakness in our process. We executed suggested commands before we had established, independently, which firmware environment was installed on each module and what those commands would change.
The assistant could reason from documentation and the information we supplied. Without instrument output or direct physical access, it could not inspect the module, its flash contents, its power condition or its prior programming history. Some advice was delivered with more certainty than the available evidence justified. We treated plausible software instructions as if they described the actual state of hardware on the bench.
The result was a loss of our operational baseline. One module became inaccessible through its normal USB route. Others remained functional but were not running the environment required for our next stage. We initially approached these states as variations of one flashing problem, even though they required different diagnoses.
The central issue was human accountability within AI-assisted engineering. The assistant contributed guidance that needed more verification; we supplied incomplete evidence and accepted actions without enough cross-checking. The recovery therefore involved more than repairing firmware. It required restoring our understanding of the hardware we were operating.
02 / Operating Software
The RAK4631 hardware can operate within different software ecosystems. Our modules included RUI3RAKwireless Unified Interface V3, a firmware/API environment for supported RAK modules.Crux usage: An original firmware environment encountered in the RAK4631 fleet before migration to MeshCore.Open full definition-based configurations, while the target MeshCore USB CompanionA MeshCore firmware role that exposes the MeshCore companion protocol to a USB-connected host.Crux usage: Chosen as the standard application role for the RAK4631 fleet and Atlas Bridge host integration.Open full definition deployment required a different, compatible nRF52 BootloaderFirmware supporting startup and, depending on design, a supported method for updating device application software.Crux usage: The recovery campaign restored a compatible UF2 bootloader environment before applying the MeshCore USB Companion firmware.Open full definition and application arrangement.
A responsive serial interface is not proof that the installed environment can accept an unrelated DFUDevice Firmware Update: a method for transferring firmware to a device through a compatible update mechanism.Crux usage: After SWD bootloader restoration, the MeshCore USB Companion application was delivered using serial DFU.Open full definition package. Equally, loss of normal USB communication is not proof of electrical damage to the nRF52840.
These distinctions were easy to miss while we were focused on higher-level behaviour: LoRa transmissions, host commands and the immediate objective of getting AtlasCrux’s governed operational intelligence system for interpreting system state, coordinating workflows, and presenting actions or decisions.Crux usage: Atlas connects engineering records, sensor data, communications, automation, evidence, and publishing. Material changes remain subject to validation rules and human approval.Open full definition Bridge communicating. We needed to separate the physical processor, debug transport, bootloader / supporting stack, application image, and host protocol into independently testable layers.
03 / Three operational scenarios
Scenario A — The nonresponsive module
One device no longer provided a useful normal USB interface. It was labelled as potentially bricked during troubleshooting. The observation was legitimate; the implied conclusion of irreparable hardware damage was not established. SWDSerial Wire Debug, an ARM debugging and programming interface using SWDIO, SWCLK and a common electrical reference.Crux usage: Provides a lower-level diagnostic path to the RAK4631 processor when ordinary USB access is unavailable.Open full definition access through the RAKDAP1USB-connected programmer/debugger providing CMSIS-DAP access to ARM SWD targets.Crux usage: Used with the workbench workstation to inspect and recover nRF52840 targets independently of their application or USB bootloader.Open full definition offered a way to test the processor independently of the failing application/bootloader path.
.jpeg)
Scenario B — The functioning RUI3 module
Other modules answered their existing commands, including a recorded RUI3 v4.2.4 state. They were not dead. They required migration, not a blanket description of recovery from hardware failure. The question was whether we could safely establish the intended bootloader and MeshCore firmware environment.
Scenario C — The fresh factory-state control
A newly supplied module, recorded as RAK4631_FCT_001, provided a factory-state starting reference. It was not a defective board to be resurrected. Nevertheless, the dated workbench logs show that it was subsequently mass-erased, flashed and migrated to MeshCore USB Companion. It therefore should not be described as left untouched at the end of the session.
The fleet objective
The October 10 workbench logs document five complete mass-erase → combined-bootloader flash → USB DFU sequences, followed by five successful MeshCore CLI identification checks. These comprise four recovery/migration targets, including Atlas Bridge, and one factory-state starting reference that was also migrated. The logs establish the successful migration outcomes; they do not independently prove the precise pre-failure cause of each previously used module.
04 / Earlier approaches: what we tried and why they were insufficient
Earlier approaches included ordinary USB/serial interaction with RUI3, attempting bootloader or DFU entry over USB, and successive candidate flashing/update routes. The Saturday session documents the eventual shift to direct SWD. The exact chronology, each failed command and the state of each module still require reconciliation against the original workbench transcripts.
Our initial approach was too dependent on the next command or binary. When a command produced a disappointing result, the temptation was to try another flash utility, alternative firmware package or USB update path.
This was a risk in our specific AI-assisted troubleshooting process, rather than evidence that every AI assistant follows the same pattern: a language model can suggest successive software interventions without having direct evidence that the underlying bootloader, memory layout and physical target match those interventions. On this occasion, the recommendations and our execution of them amplified uncertainty rather than reducing it.
The key gap was the transition between the RUI3 firmware ecosystem and the bootloader / SoftDeviceNordic’s precompiled Bluetooth protocol stack used with compatible nRF52 applications and bootloader configurations.Crux usage: The recovered RAK4631 baseline used the S140 SoftDevice 6.1.1 bundled with the approved bootloader artifact.Open full definition arrangement used for the intended MeshCore firmware. A procedure that belongs to one ecosystem must not be assumed to belong to the other. Repeating a higher-level updater cannot fix a lower-level incompatibility unless the updater explicitly supports that migration.
We changed approach when we stopped asking what should we flash next? and started asking what state can we actually prove the processor is in?
That shifted the work from ad hoc software iteration to layered diagnosis: power, physical SWD connection, target detection, firmware artifacts, application deployment and acceptance tests.
05 / Root cause and engineering accountability
Observed: modules had diverged into distinct operational states, including one without useful normal USB access.
Supported mechanism: a migration between different firmware/update environments created compatibility constraints that our early procedure had not accounted for.
Contributing process failure: AI-generated guidance was acted on without a controlled inventory of firmware states, independent source verification and reversible checkpoints.
The newly available session logs confirm the recovery and migration operations, but they primarily capture successful corrective work. They do not preserve a complete chronology of earlier failed attempts or prove which specific command left a particular board inaccessible. The firmware-environment mismatch remains a strongly supported engineering explanation, not a chip-level forensic determination for every module. Nor do these results imply that the RAK4631 hardware itself was unreliable.
The lesson is not to avoid AI. It is to place AI-generated actions inside an engineering verification process. A model can help interpret documentation and develop tools, but the engineer must establish the actual state of the physical system and approve the operation to be performed.
What follows is the controlled procedure we developed to restore access to the nRF52840 through SWD, rebuild the required software environment and verify the resulting USB Companion operation.
PART II / PRACTICAL RECOVERY FIELD GUIDE
Verification status: October 10 workbench logs now independently document all five erase, bootloader-flash, USB DFU and post-flash MeshCore CLI acceptance stages. Representative commands remain reconstructed wherever the saved log omitted line continuations. Validate tool versions, firmware files and hashes, physical contacts and target identity before executing any command. Destructive operations are never the first diagnostic step.
06 / What the RAKDAP1 changes
The RAKDAP1 provides direct SWD connectivity to the nRF52840, independent of normal USB application behaviour. For this recovery setup, the SWD contacts were made at the RAK4631, while the RAK19007RAKwireless WisBlock baseboard providing mechanical module connection, power/USB and access to core and expansion signals.Crux usage: The RAK4631 was seated on a RAK19007 and the target powered through its USB-C port during SWD programming.Open full definition provided target power via its USB-C connector. The original workbench setup used a temporary, solderless contact method.
The four documented connections were:
| Target signal | RAKDAP1 header | Function |
|---|---|---|
| SWCLK | TCK / CK | Debug clock |
| SWDIO | TMS / IO | Debug data |
| GND | GND | Common ground reference |
| 3V3 | 3V3 | Target-voltage reference, subject to debugger configuration |
The RAKDAP1 5V header was deliberately not connected. RESET was not part of the recorded four-wire path. Do not energize the target using two independent, conflicting supply arrangements. Verify all connections against the actual silkscreen before applying power.
Five original Rhino Make2D studies form the hardware reference set. Select a drawing to open the complete interactive inspection viewer with all 24 saved callouts, alternative projections where available, and the four-wire SWD mapping. The drawings are spatial references; verify electrical connections against the physical hardware and official documentation before energizing the target.
Select a figure to inspect its callouts. Technical card positions are awaiting final physical/electrical sign-off; the recovery commands remain subject to final workbench artifact and electrical sign-off.
07 / Workbench preparation
- Identify and label the specific module and its current known state.
- Fit the RAK4631 to its RAK19007 base while unpowered.
- Establish stable, strain-relieved SWD contacts.
- Connect the RAKDAP1 to the workstation.
- Attach the target USB-C cable to the baseboard, then connect its other end to the host using the documented session power-up order.
- Verify target power, shared ground and debugger enumeration before any write or erase action.
A known-good regional antenna should be attached for later radio validation, but SWD interrogation is a separate operation from radio transmit testing.
08 / Diagnose before erasing
The workbench README records a conservative 100 kHz SWD clock for the solderless contacts. Its recorded ARM debug-port IDCODEIdentification value read from an ARM debug port during low-level target communication.Crux usage: The value 0x2BA01477 was recorded during successful workbench SWD connections.Open full definition was 0x2BA01477, the ARM debug-port IDCODE. This confirms debug-port response, not a unique processor identity or the correctness of installed firmware.
At this point, choose a path:
- SWD unavailable: stop; recheck power, contacts, signal mapping, target selection and programmer status.
- SWD works, USB fails: investigate firmware, bootloader and protection state; use destructive recovery only when justified.
- Normal RUI3 works: this is primarily a migration decision; do not present it as a repair of electrically failed hardware.
- Factory state works: preserve it as the diagnostic control and record its initial version before migration.
09 / Recover the required environment
For targets that require a full reset of flash configuration, an authorized chip erase may be necessary. Such an erase destroys installed software, configuration, identities and secrets; it may also affect recoverability if required artifacts have not been retained.
The October 10 logs record a completed python -m pyocd erase operation and successful programming of the combined wiscore_rak4631_board_bootloader-0.4.4_s140_6.1.1.hex artifact for each of the five targets. The next stage used adafruit-nrfutil USB serial DFU with the specific RAK_4631_companion_radio_usb-v1.17.1-d929643.zip package. The exact pyOCDOpen-source host-side tools for debugging and programming supported ARM microcontrollers.Crux usage: Used for nRF52840 SWD diagnostics and recovery through the RAKDAP1.Open full definition option lists are not completely visible in the saved PowerShell transcript excerpts; see the appendix for this limitation.
Do not run an erase merely because one USB flash command failed. The recoverability of useful information and the exact requirements of the target board must be considered first.
10 / Install and verify MeshCore
All five post-flash CLI outputs report v1.17.1-d929643 running as MeshCore USB Companion. The associated CLI reads report 869.618 MHz, 62.5 kHz bandwidth and spreading factor 8. CLI connectivity and configured radio parameters are verified; these logs do not record a full five-device RF transmit/receive acceptance campaign. After DFU, discover the application COM port again: the port changed after each recorded flash (for example, Atlas Bridge COM12 → COM13).
Acceptance should be layered:
- Debugger: SWD is accessible where needed and the target can be identified.
- Bootloader: intended update mode is present after reset.
- Application: firmware installed via its correct update mechanism.
- USB companion protocol: host can connect and retrieve firmware/device details.
- RF/network: radio transmit, receive, channel and reboot tests pass separately.
- Operational assignment: device ID, role, history and final version are recorded.
Our historic USB Companion verification is not, by itself, a claim that every device had completed every network and host-service acceptance check.
11 / Lessons from the recovery campaign
We restored working hardware, but the more durable result was procedural. Firmware environments became explicit. Board state became recorded evidence rather than an assumption. SWD access was treated as a diagnostic tool, and an available factory-state control prevented the whole stock from becoming an uncontrolled experiment.
The same discipline should apply to future CRUX hardware: identify, preserve, verify, change and validate. AI remains a useful assistant in the workflow; human accountability remains the operating principle.
TECHNICAL APPENDIX — VERIFIED WORKBENCH LOGS
Evidence level: Records supplied from the 10 October 2026 recovery workbench workstation. The archive contains five mass-erase logs, five bootloader-flash logs, five MeshCore USB DFU logs, five commissioned CLI records (with an additional Atlas pre-rename baseline), a bootstrap record and the workstation inventory. The logs confirm operation outcomes, but some full PowerShell command-line arguments are truncated by line continuation in the captures.
A.1 — Recorded tools and target
The workbench used a NanoDAP v2.3/CMSIS-DAPA standard protocol enabling host debugging software to communicate with supported ARM debug probes.Crux usage: The RAKDAP1 presents a CMSIS-DAP interface for host tools such as pyOCD.Open full definition compatible probe on an nRF52840 RAK4631 target. The README records ARM SWD IDCODE 0x2BA01477 at 100 kHz; it also identifies a 1 MiB reference flash capture from a working module. The tool inventory found Python 3.14 and PowerShell 7.6.6; pyocd and adafruit-nrfutil were not standalone executables in PATH at the inventory snapshot. The device logs show python -m pyocd and a resolved adafruit-nrfutil.exe invocation.
A.2 — Firmware artifacts and recorded SHA-256
| Artifact | Recorded SHA-256 |
|---|---|
wiscore_rak4631_board_bootloader-0.4.4_s140_6.1.1.hexCombined bootloader / S140 image; SHA recorded in the Atlas preflash evidence | 6D2FA3D113F691C147C4694D29D368B46FED2D9E6FDAF2BF102BCD05ACDC2B15 |
RAK_4631_companion_radio_usb-v1.17.1-d929643.zipMeshCore USB Companion release artifact; SHA recorded at download | 9F1CFB62A7FAAB4367E0138D25541A8253618792091C871DFC991C7E62B239F9 |
Integrity limitation: these SHA-256 values are recorded in the supplied workstation evidence. The actual firmware binary files were not uploaded in this batch, so the hashes have not been independently recomputed here. Before any future recovery, compare local files against the recorded values and an authoritative upstream source.
A.3 — Documented execution sequence
- Identify the selected target and confirm stable powered SWD access. The reference-stage workbench instructions explicitly prohibited automatic unlocking or erase of the then-working reference module.
- With the correct target intentionally selected and appropriate backups secured, execute an authorised full erase if required. Each of the five supplied device-specific logs reports
Mass erase complete. - Program the combined bootloader/S140 hex image by SWD. All five flash logs report
Erased 193536 bytes (48 sectors), programmed 193536 bytes (48 pages). - Enter the supported bootloader DFU mode and send the MeshCore USB Companion ZIP using
adafruit-nrfutil. All five DFU logs end withDevice programmed.Their application payload is reported as 486160 bytes. - Reconnect on the newly enumerated application COM port; use the MeshCore CLI
infosaction to confirm firmware version, device identity and configured radio values.
PowerShell interpretation: the captured output contains NativeCommandError/RemoteException wrappers around some stderr status messages from command-line tools. Do not equate these wrapper strings with failure when the same record later reports completed erase, programming or DFU; conversely, confirm exit status when repeating the procedure rather than assuming every stderr line is harmless.
A.4 — Five-device result ledger
| Log label | Commissioned identity | DFU → CLI COM | Result |
|---|---|---|---|
| ATLAS_BRIDGE | CRUX-ATLAS-BRIDGE | COM12 → COM13 | USB Companion v1.17.1-d929643 |
| RCV_001 | CM-MOB-LGO-001 | COM14 → COM15 | USB Companion v1.17.1-d929643 |
| RCV_002 | CM-DEV-002 | COM16 → COM17 | USB Companion v1.17.1-d929643 |
| RCV_003 | CM-DEV-003 | COM18 → COM19 | USB Companion v1.17.1-d929643 |
| FCT_001 (factory-state starting reference) | CM-DEV-004 | COM21 → COM22 | USB Companion v1.17.1-d929643 |
These five successful software commissioning checks do not prove that five defective boards were repaired, that all five underwent identical failure states or that all five passed full RF acceptance. The factory-state reference was also intentionally mass-erased and migrated.
A.5 — Representative terminal form (not verbatim recorded commands)
Because some multi-line invocations are not preserved in full, the commands below are reference syntax only—not an unqualified copy/paste recovery script. Confirm target identity, local tool versions, connected probe, Vref conditions, file hashes and backup requirements before execution.
# Non-destructive connection check (reference syntax)
python -m pyocd commander -t nrf52840 -f 100k -O auto_unlock=false
# DESTRUCTIVE EXAMPLE — NEVER use on a device until approved for erase
python -m pyocd erase -t nrf52840 --chip -f 100k
# Flash the exact preverified combined image through SWD
python -m pyocd flash -t nrf52840 ".\wiscore_rak4631_board_bootloader-0.4.4_s140_6.1.1.hex" -f 100k
# Send the USB Companion DFU package to the actual discovered bootloader port
adafruit-nrfutil dfu serial -pkg ".\RAK_4631_companion_radio_usb-v1.17.1-d929643.zip" -p COM12 -b 115200
# Re-identify the application COM port after DFU; example Atlas Bridge result
meshcli -s COM13 -b 115200 infosSafety: the historic COM examples are not portable. USB port numbering changes by workstation and device state. Mass erase is permanent; never use it as a routine discovery command.
A.6 — Limits and pending verification
- The source archive does not contain a complete transcript of earlier unsuccessful troubleshooting commands or independent forensic proofs of each device's prior failure cause.
- The binary firmware files themselves and a completed UICR backup are not among this upload batch.
- Physical four-wire SWD pin placement and probe Vref semantics still require final hardware sign-off before publishing this as a universal wiring procedure.
- The October 10 outputs demonstrate successful application/USB-protocol commissioning, not an exhaustive radio-network, reboot-persistence or Atlas host-service test.
References and traceability
- RAKwireless: RAKDAP1 Flash and Debug Tool — DAPLink / CMSIS-DAP debugger documentation.
- RAKwireless: RAK4631 product specifications — nRF52840, SX1262, regional hardware and antenna references.
- Zephyr: RAK4631 board description — debug and programming support background.
- MeshCore: Official firmware documentation — supported devices and nRF DFU workflow; these are generic upstream instructions, not substitutes for our specific validated October 10 commands.
- CRUX: October 10 bench-session notes, original user photos,
Article Feedback.txtand Rhino Make2D masters. recovery workbench archive now supplied: five device-specific erase/flash/DFU/commissioning sequences,bootstrap-20261010-113608.log,README.md,downloaded-assets.csvand tool inventory. The actual firmware binaries, missing earlier failed-attempt records and physical wiring sign-off remain outstanding.
Editorial note: This article intentionally avoids implying that five defective boards were repaired. Our recorded result was five programmed and commissioned devices: four recovery/migration targets and a fifth factory-state starting reference that was also migrated.