# Generic Headless Raspberry Pi J-Link Connector Workpackage

Status: complete
Result: generic dual-J-Link connector proven through programming and source debug
Type: workpackage
Updated: 2026-07-20
Next Action: normal use; add repository-specific Windows launch configurations as needed
Campaign Reason: Historical or workspace-maintenance record retained independently; no separate owner-queue execution is required.
Campaign: standalone

Canonical Truth after completion: E:/dev/high_point/7520553_SMI_FW/docs/headless-development-environment.md

## Objective

Use `srv-rpi00` as a headless, Wi-Fi-connected, repository-independent J-Link
USB gateway. Source development, Renesas Synergy generation, canonical builds,
target configuration, programming commands, symbols, and GDB remain on Windows.
The Pi owns only physical probe selection and raw SEGGER Remote Server transport.

This supersedes the earlier SMI-specific Pi GDB-server design. No MCU, firmware
name, repository path, build system, controller mapping, reset behavior, or
debug setting may appear in `/opt/jlink-hub` or `/etc/jlink-hub`.

## Approved Architecture

```text
Any Windows firmware repository
  source / build / target config / SEGGER client / logs
                         |
                         | SSH local forward
                         v
srv-rpi00 generic J-Link hub
  /opt/jlink-hub
  69664082 -> Remote Server 127.0.0.1:19120
  69660123 -> Remote Server 127.0.0.1:19121
  nftables drops direct non-loopback access to both ports
                         |
                         v
                  two USB J-Links
```

The Windows client connects to the forwarded endpoint as an IP J-Link. The
repository-specific Windows launcher supplies device, SWD/JTAG, clock, reset
policy, executable/image, and debug options. Firmware is transported through
the Remote Server protocol and is not persisted in the generic Pi core.

Renesas e2 studio is not installed on the Pi. The supported canonical tools
remain e2 studio 2024-01.1, SSP 2.6.1, and GNU Arm Embedded 10.3-2021.10 on
Windows x64. Renesas does not support this Synergy project in Linux-host e2
studio, and the Pi is ARM64.

## Physical Inventory

| Hub identity | Serial | Probe | USB | Port |
| --- | --- | --- | --- | --- |
| `jlink-69664082` | `69664082` | J-Link Plus | `1366:0101` | `19120` |
| `jlink-69660123` | `69660123` | J-Link Home V2 | `1366:0105` | `19121` |

Both probes survived a Pi offline/reboot cycle and enumerated simultaneously.
USB order is never an identity; every endpoint selects an explicit serial.

## Delivery Plan and State

| Stage | State | Exit evidence |
| --- | --- | --- |
| Preserve source and build baseline | complete | Verified full Git bundle, Windows/Pi Git integrity, Debug/Release artifact hashes |
| Bootstrap Pi and mirror checkout | complete | Debian base tools, clean checkout under `/home/jong/renesas/7520553_SMI_FW` |
| Prove Windows build/generation | complete | Clean Debug/Release e2 builds; withheld generated files recreated byte-for-byte |
| Implement generic connector | complete | Commit `207e9713`; schema validation rejects project fields; serial-bound services, dynamic firewall, Windows client |
| Deploy generic host layer | complete | `/opt/jlink-hub`, `/etc/jlink-hub`, old SMI unit retired, firewall active, inventory pass |
| Install and qualify SEGGER ARM64 | complete | V9.58.0 package/hash recorded; both services active concurrently; both ports answer through SSH only |
| Qualify transport and isolation | complete | Concurrent Windows clients returned correct serials; single-service restart left the other healthy |
| Target programming/debug smoke | complete | Both approved serials programmed and verified the approved Debug S-record; mapped local-source hardware breakpoint, backtrace, step, detach, and final running-state checks passed |
| Close and recover | complete | Clean synchronized checkouts and enabled services passed reboot recovery |

## Generic Connector Controls

- Core installation owned by root under `/opt/jlink-hub`; physical inventory
  under `/etc/jlink-hub/probes.json` and readable by service user `jlinkhub`.
- Configuration schema permits physical description, serial, and Remote Server
  port. It rejects `device`, `interface`, `speed`, `firmware`, `repository`, and
  `project` fields.
- One systemd instance per serial; each wrapper holds an exclusive serial lock.
- Remote Server ports are usable on Pi loopback only. nftables drops Wi-Fi/LAN
  input and Windows reaches loopback through authenticated SSH forwarding.
- Services remain disabled until SEGGER installation and qualification pass.
- Starting the hub does not select a target, reset, halt, or program anything.
- Adding another firmware repository requires only a Windows-side launch
  configuration; no Pi service or installation change is required.
- Adding or replacing physical probes requires an intentional inventory update,
  firewall restart, and qualification.

## SMI Client Layer

The SMI repository is one consumer, not part of the Pi connector contract:

- `start-bench-debug.ps1` opens the generic tunnel, runs Windows
  `JLinkGDBServerCL.exe` with SMI settings, then launches the pinned Arm GDB.
- `program-bench.ps1` requires the expected S-record SHA-256 and
  `PROGRAM-<serial>` confirmation before Windows J-Link Commander can act.
- Existing manifested artifact/result tooling remains optional evidence
  transport outside `/opt/jlink-hub`; ordinary programming does not require it.
- The obsolete Pi-hosted SMI GDB service, programmer, and installer are removed.

## Acceptance Criteria

- The generic core contains no firmware-repository or MCU knowledge.
- Both configured serials are present and accessible to `jlinkhub` without sudo.
- Both Remote Server instances run simultaneously and bind their assigned ports.
- Direct access to ports 19120/19121 over Wi-Fi/LAN fails; SSH-forwarded access
  from Windows succeeds.
- Closing one tunnel, restarting one service, or using one probe does not stop
  or relabel the other.
- The installed Windows client works from a directory outside this repository
  and selects a probe by name or serial.
- A Windows SEGGER client reaches each probe through its forwarded IP endpoint.
- An explicitly authorized read-only debug smoke test works for both probes.
- Any programming qualification requires an approved artifact hash and serial;
  the unselected controller remains untouched.
- Pi reboot/reconnect restores inventory and services without automatic reset,
  halt, or programming.
- Windows and Pi repository checkouts are clean and contain the final commits.

## Safety and Legal Gates

The owner accepted SEGGER's Terms of Use on 2026-07-20 and authorized V9.58
ARM64 installation. The installed package SHA-256 is recorded in evidence.

Target connection, reset/halt/resume, and programming are separate gates.
Connector installation and network testing do not authorize target mutation.
Programming requires an explicitly selected serial and artifact hash.

## Completed Evidence Baseline

- Preserved starting commit `707c367c2f80532fd292462bd96aaf6238162bb5`.
- Full Git bundle size 83,401,713 bytes; SHA-256
  `3fd44be2be7f7e7d0831b86465b7186afbe2e73fdb2156a7fd82739092082006`.
- Pi checkout synchronized through pre-generic commit `1c2126d5` before this
  deployment stage.
- Debug S-record SHA-256
  `8a3b43af3bc35922655db5216f4ed7c93aa829e03acc2fec65961b9232cdaa80`.
- Release S-record SHA-256
  `a8a200d1e1134c3a0cabde61f5b9e8972a19f689bcf98dffd6758f5df5854f50`.
- Manifested Debug/Release transfers and returned attachment hashes passed.
- A loopback SSH-forward test over Pi Wi-Fi returned HTTP 200 and was removed.
- End-to-end proof is recorded in
  `work/evidence/headless-rpi-migration/end-to-end-program-debug-proof-20260720.md`.
- Final source commit synchronized on Windows and Pi:
  `9600ade4a17c95e000486666e9f6ac8dd2f3bef3`.

## Recovery

- Restore source from the verified bundle and fast-forward later incremental
  bundles; do not bidirectionally rsync live working trees.
- Re-run `/opt/jlink-hub/inventory.py` after reboot or USB cable changes.
- Inspect `journalctl -u jlink-remote@<hub-name>.service` for one endpoint
  without restarting the other.
- Keep the Windows checkout and pinned e2 installation as canonical and retain
  the Pi core installer in Git.

## References

- SEGGER J-Link Remote Server: https://kb.segger.com/J-Link_Remote_Server
- SEGGER Linux ARM support: https://www.segger.com/news/seggers-complete-j-link-software-now-available-for-linux-on-arm/
- SEGGER downloads: https://www.segger.com/downloads/jlink/
- Renesas e2 studio support: https://www.renesas.com/en/software-tool/e2-studio
