macOS: enable CH341 LoRa-hardware path (fix serial truncation, document setup) (#10320)

* macOS: enable CH341 LoRa-hardware path — fix serial truncation, document setup

Verified on Apple Silicon with a CH341A USB-SPI bridge (VID 0x1A86,
PID 0x5512) wired to an SX1262 (Meshstick variant) that the existing
`pine64/libch341-spi-userspace` lib_dep works on macOS as-is — Apple's
bundled CH34x driver only matches the CH340 *UART* variant
(PID 0x7523), so the CH341A's interface 0 is left unclaimed and
libusb opens / configures / claims it directly via IOUSBHostInterface.
End-to-end test: meshtasticd boots, libusb claim succeeds, SX1262 init
returns 0, TCP API serves the meshtastic CLI's --info / --sendtext flow.

Two changes:

1. **`PortduinoGlue.cpp:497`**: pass `sizeof(serial)` (= 9) instead of
   the literal `8` to `Ch341Hal::getSerialString()`. The function in
   `USBHal.h:61-68` treats `len` as buffer size and reserves one slot
   for the null terminator (`bytesCopied = (len - 1) < 8 ? (len - 1) : 8`),
   so passing 8 produced a 7-char serial — which then broke the
   `strlen(serial) == 8` check at line 502, skipping the auto-MAC
   derivation from serial + product string. On Linux this was masked
   by the BlueZ HCI MAC fallback in `getMacAddr()` at lines 139-157,
   but on macOS that fallback is `__linux__`-guarded so the serial path
   is mandatory and the truncation left `mac_address` empty, causing
   the daemon to exit with `*** Blank MAC Address not allowed!`.

2. **`variants/native/portduino/platformio.ini`**: expand the
   `[env:native-macos]` comment block with a "Real LoRa hardware on
   macOS" section. Documents:
   - Why no upstream library change is needed (Apple kext targets
     CH340/UART, not CH341A/SPI; libusb's `#ifdef __linux__` skip is
     correct for macOS in this case).
   - How to point `meshtasticd` at an existing platform-agnostic
     `bin/config.d/lora-*.yaml` for CH341 hardware.
   - The auto-MAC-derivation contract (now working with this fix).
   - `ioreg` and `LIBUSB_DEBUG=4` diagnostic recipes for the failure
     mode where a third-party WCH `CH34xVCPDriver` *would* claim
     interface 0 (`kmutil unload -b <bundleID>` workaround).

No upstream library forks, no PR chain, no additional lib_deps —
the existing `pine64/libch341-spi-userspace` + libusb-1.0 stack does
the right thing on macOS already.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Apply suggestion from @Copilot

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

variants/native/portduino/platformio.ini

@@ -133,6 +133,39 @@ test_testing_command =
 ;     SOCK_NONBLOCK fallback, Common.h __APPLE__ guard, WiFiServer.cpp extern-C
 ;     fix, package.json URL refresh. Pulled by platform-native at its pinned commit.
 ; This env therefore only carries the firmware-side build flags and src filter.
+;
+; Real LoRa hardware on macOS:
+;   The same lib_dep `pine64/libch341-spi-userspace` used on Linux works on
+;   macOS as-is — its `libusb_detach_kernel_driver()` call is `__linux__`-
+;   guarded, but on macOS the kernel doesn't bind a driver to a CH341A SPI
+;   bridge (PID 0x5512; bDeviceClass=0xff vendor-specific) by default, so
+;   no detach is needed. Apple's bundled CH34x driver targets the CH340
+;   *UART* variant (PID 0x7523) — different product. libusb opens the device
+;   and claims interface 0 directly via IOUSBHostInterface.
+;
+;   To use, point `meshtasticd` at any of the existing `bin/config.d/lora-*.yaml`
+;   files that specify `spidev: ch341` — they're platform-agnostic. Example:
+;     pio run -e native-macos
+;     mkdir -p ~/.meshtasticd && cp bin/config-dist.yaml ~/.meshtasticd/config.yaml
+;     # Edit ~/.meshtasticd/config.yaml: ConfigDirectory: ./config.d/
+;     mkdir ~/.meshtasticd/config.d && cp bin/config.d/lora-meshstick-1262.yaml ~/.meshtasticd/config.d/
+;     cd ~/.meshtasticd && /path/to/firmware/.pio/build/native-macos/meshtasticd
+;
+;   The MAC address auto-derives from the CH341's USB serial + product string
+;   (PortduinoGlue.cpp ~497-518); on Linux a BlueZ HCI socket is the fallback
+;   when that path isn't taken, but BlueZ is `__linux__`-guarded so the
+;   serial-derivation path is mandatory on macOS. Override with
+;   `MACAddress: AA:BB:CC:DD:EE:FF` in config.yaml's `General:` section if
+;   the device's serial isn't 8 hex chars.
+;
+;   Diagnosing CH341 issues on macOS:
+;     ioreg -p IOUSB -l -w 0 | grep -B2 -A30 0x5512
+;       Children should be `IOUSBHostInterface`. If a vendor driver class
+;       (e.g. `com.wch.CH34xVCPDriver` from a third-party WCH installer)
+;       claims interface 0, libusb will fail with LIBUSB_ERROR_BUSY.
+;       Workaround: `sudo kmutil unload -b <bundleID>`.
+;     LIBUSB_DEBUG=4 .pio/build/native-macos/meshtasticd
+;       Verbose libusb trace — useful when claim_interface fails.
 ; ---------------------------------------------------------------------------
 [env:native-macos]
 extends = native_base