macOS: enable CH341 LoRa-hardware path (fix serial truncation, document setup)#10320
Merged
Conversation
…ent 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>
Contributor
There was a problem hiding this comment.
Pull request overview
Enables/clarifies running Portduino (native-macos) against real LoRa hardware via a CH341 USB-SPI bridge on macOS by fixing CH341 serial-string truncation (which prevented MAC derivation) and documenting the setup/diagnostics path in the Portduino PlatformIO environment.
Changes:
- Fix CH341 serial retrieval by passing the full buffer size to
Ch341Hal::getSerialString()so 8-char serials are not truncated. - Document macOS CH341 real-hardware usage and troubleshooting steps in the
native-macosPlatformIO environment comments.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| variants/native/portduino/platformio.ini | Adds macOS-specific documentation for CH341 real LoRa hardware usage and debugging. |
| src/platform/portduino/PortduinoGlue.cpp | Fixes serial-string truncation impacting CH341-based MAC auto-derivation on macOS. |
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
thebentern
added a commit
that referenced
this pull request
Apr 28, 2026
…nt 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>
mariotti
pushed a commit
to mariotti/firmware
that referenced
this pull request
May 6, 2026
…nt setup) (meshtastic#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>
Evil8it
pushed a commit
to Evil8it/ME4TACTNK
that referenced
this pull request
Jun 10, 2026
…nt setup) (meshtastic#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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Verified on Apple Silicon with a CH341A USB-SPI bridge (VID
0x1A86, PID0x5512) wired to an SX1262 Meshstick that the existingpine64/libch341-spi-userspacelib_dep works on macOS as-is — Apple's bundled CH34x driver only matches the CH340 UART variant (PID0x7523), so the CH341A's interface 0 is left unclaimed and libusb opens / configures / claims it directly viaIOUSBHostInterface.End-to-end verification on
darwin/arm64:meshtastic --host localhost --inforeturns full node info;--sendtextround-trips throughServerAPI→ PacketHistory; runtime--set lora.region USreconfigures the SX1262 over SPI and the radio reflects its state back via[Router] Received routing from=….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.Changes
1.
src/platform/portduino/PortduinoGlue.cpp:497— fix serial truncationPass
sizeof(serial)(= 9) instead of the literal8toCh341Hal::getSerialString(). The function inUSBHal.h:61-68treatslenas buffer size and reserves one slot for the null terminator:So calling with
len=8produced a 7-char serial ("1000000"instead of"10000002"), which then failed thestrlen(serial) == 8check at line 502 and skipped the auto-MAC derivation from serial + product string.On Linux this was masked by the BlueZ HCI MAC fallback in
getMacAddr()(PortduinoGlue.cpp:139-157) — that path runs whenmac_addressis empty. On macOS the BlueZ path is__linux__-guarded, so the serial-derivation path is the only MAC source for CH341 boards without an explicitMACAddress:inconfig.yaml. Truncation leftmac_addressempty and the daemon exited with*** Blank MAC Address not allowed!.2.
variants/native/portduino/platformio.ini— document macOS hardware supportExpanded the
[env:native-macos]header comment with a "Real LoRa hardware on macOS" section. Covers:#ifdef __linux__skip inlibpinedio-usb.cis correct for macOS in this case).meshtasticdat an existing platform-agnosticbin/config.d/lora-*.yamlfor CH341 hardware.CH34xVCPDriverwould claim interface 0 (ioreg -p IOUSB -l -w 0 | grep -B2 -A30 0x5512,LIBUSB_DEBUG=4 meshtasticd,sudo kmutil unload -b <bundleID>).Test plan
pio run -e native-macosbuilds clean on Apple Silicon (arm64)bytesCopied = (len - 1) < 8 ? (len - 1) : 8withlen=9still givesbytesCopied=8, identical behavior to the previous code path withlen=8and the intendedbytesCopiedsemantics. Linux CI's BlueZ fallback was the actual MAC source so neither path observed the truncation in the field.bin/config.d/lora-meshstick-1262.yaml, derives MAC, initializes SX1262meshtastic --infoand--sendtextround-trips through ServerAPI + PacketHistory--set lora.region USreconfigures SX1262 and a second--sendtextis accepted (nolora tx disabledwarning)🤖 Generated with Claude Code