# The Same Dongle on a Mac: What to Do When the Platform Has No Drivers (5)

- URL: https://wuming.si/blog/4092/
- Author: Wuming
- Published: 2026-10-24
- Language: en
- Categories: Technology, English

> Previous: [USB Handsets, Browser Calls and an ESP32](https://wuming.si/blog/4091) | Next: [The iPhone Client](https://wuming.si/blog/4093) | 中文版：[插在 Mac 上](https://wuming.si/blog/4006)

The first four posts all ran on a Raspberry Pi. Linux is friendly to this kind of device: the serial ports have drivers, the network interface has a driver, sound goes through ALSA, and hotplug is handled by udev.

Plug the same dongle into a Mac and you get none of that.

The conclusion of the first post turns into a concrete problem here: the module's AT interface, network interface and diagnostic interface are all vendor-specific USB classes. macOS binds no driver to any of them, and there isn't so much as a trace of them under `/dev/cu.*`.

The only channel you can reach is ADB. Installing it is easy:

```sh
brew install android-platform-tools
adb devices -l
```

There are three ways to use it on a Mac, from shallow to deep:

| Mode | Who it's for | What you need |
|---|---|---|
| A. Internet only | Giving the Mac 4G on the road | Switch to ECM mode, install nothing |
| B. Run a server build | You want the same web console and eSIM management as on the Raspberry Pi | Build a macOS version |
| C. Native app | Making calls and sending texts directly on the Mac | An Xcode build, plus the voice driver |

## A. Internet only

```text
AT+QCFG="usbnet",1
AT+CFUN=1,1
```

After the module reboots, a new wired network interface shows up under "System Settings → Network". The module does DHCP and NAT itself, and the Mac gets a `192.168.225.x` address. No dialing; plug it in and you're online. Switch back with `usbnet,0`.

### It quietly takes over the Mac's IPv6

**Symptom**: Wi-Fi looks perfectly connected, but the browser's traffic is actually going over the SIM card.

**Cause**: The ECM interface brings along a carrier IPv6 prefix. If the Mac's current Wi-Fi has no IPv6 (plenty of home and office networks don't), that prefix becomes **the only IPv6 default route on the whole machine**. Every site that supports IPv6, which today means most of the major ones, goes out through the SIM card.

Nothing on screen tells you. On a roaming SIM, that is your bill.

**Fix**: The native app's default policy is "don't give the Mac the SIM's data". When it connects to a module that is in ECM mode, it switches it to QMI. Since macOS has no QMI driver, no network interface appears at all, so there is simply no route to take. The setting is stored in the module, so the reboot happens only once, and never during a call.

Switching manually on the network page updates this policy at the same time, so the next connection won't flip it back. There is also a guard against the loop of "switch didn't take → reconnect → switch again".

## B. The macOS build of the server

```sh
make build-mac
./dist/vohive_<ver>_darwin_arm64
```

This codebase had only ever been written for Linux, and four subsystems called Linux kernel interfaces directly. The porting rule: split each one at the narrowest seam, and leave the Linux side of the code untouched.

| Subsystem | What happens on macOS |
|---|---|
| Binding outbound connections to a specific interface | Linux has a dedicated socket option; the BSDs have a different one |
| Serial port parameter setup | Add a BSD path |
| Encrypted data plane for Wi-Fi calling | Left empty, so **there is no Wi-Fi calling on macOS** |
| Hotplug monitoring | Left empty; you have to rescan manually |
| Device-in-use detection | Returns "unknown" and takes the conservative branch |

One thing I hadn't anticipated before porting: **device discovery has to change too.** Linux relies on reading `/sys/bus/usb/devices` and looking for `ttyUSB*`. Neither exists on macOS, so the device list in the console was permanently empty.

The fix was to add an "adb transport": when the system paths don't exist, devices are discovered with `adb devices -l`; when a port name starts with `adb:`, the AT manager opens a virtual serial port backed by adb. The layers above (eSIM, SMS, device management) don't change at all.

Verified: it reads the IMEI, shows LTE registration and a −65 dBm signal, and the eSIM interface returns the card info and the enabled profile.

### A few macOS-specific traps

**A compressed binary won't launch.** A UPX-compressed Mach-O fails the code signature check, and the system flat out refuses to run it. The macOS build isn't compressed.

**Double-clicking it can't find the config file:**

```text
初始化配置管理器失败: open config/config.yaml: no such file or directory
```

(The message reads "failed to initialize config manager".) When launched from Finder or by absolute path, the working directory is your home directory or the root, not the directory the program lives in. Now, when it can't find the config, it falls back to the binary's own directory.

### Three details of the adb transport

**You can't select the device by serial number.** As the first post mentioned, the serial number is 256 bytes of `0xAA`, so `adb -s` is useless. The only option is the transport id, but that changes on every re-enumeration (after unplugging, after switching network modes). So the persistent identity is the USB path, and the current transport id is resolved from it each time it's used. Skip this and every mode switch fills the screen with "no device with this transport id".

**Reads and writes must be separate.** One long-running reader process receives; writes are one-shot invocations. You can't use an interactive shell, because it allocates a pseudo-terminal and rewrites bytes. Nor can you start a second reader: two readers each take half of the replies, which looks exactly like the command got no response.

**Loosen the probe timeout.** The caller originally allowed about 1.2 seconds, estimated for serial port speeds. But every adb write is a process launch, and attaching the reader takes time too. A timeout cascades: probe times out → IMEI is treated as unverified → device is discarded → the console shows nothing. The timeout floor for adb ports is now 6 seconds.

(A test caught a lazy fix here: "on timeout, reuse the IMEI from the discovery phase". It was right to: only an IMEI given by a verified AT port can be trusted.)

### Every service restart leaves another ghost in the module

**Symptom**: After a few service restarts, device discovery fails with "no matching hardware" and nothing will bring it back.

**Cause**: Killing the local adb client does **not** kill the reader process inside the module. adbd keeps that shell alive. So the next reader only gets half the replies, which looks as if the module has stopped responding.

**Fix**: Clean up leftover readers when opening the port. There are two counterintuitive details here.

The cleanup script's command line contains the path it is searching for, so it matches itself. It has to skip itself using its own marker, or the first thing it does is kill the very shell running the cleanup.

More importantly, **only clean up the first time this process opens the node**. My first version cleaned up on every open, and then the probe during a device rescan would kill **a healthy module's** reader: exactly the failure this fix was meant to prevent, produced by the fix itself.

### Web calls fail on the Mac

The error is "cellular audio device unavailable". The cause: the cellular voice session had Linux hardcoded in two places. It looked for the USB sound card in `/proc/asound`, and moved data with ALSA's command-line tools.

The platform-specific parts now live in separate files. On macOS it looks for the module's two CoreAudio devices and uses sox to convert to 8 kHz mono.

There's also an ordering problem: **the module's USB audio function doesn't exist at all until the voice route has been set up.** So the host-side audio devices must be resolved after the route is up, or the first call after a module reboot is guaranteed to fail.

## C. The native app

No gateway needed: the app drives the module directly over ADB. Calls, texts, switching network modes, multiple modules, headset selection, mute.

```sh
cd mac/VoHiveMac
xcodegen generate
xcodebuild -scheme VoHiveMac -allowProvisioningUpdates build
```

The voice driver lives in the Application Support directory, and the app sets up the route automatically before every call.

The AT layer has two design decisions:

**Reading must be continuous.** Notifications for incoming calls and new texts arrive unsolicited, and polling will miss incoming calls. One long-lived reader process feeds the parser, and writes are separate short invocations.

**Only one command in flight at a time.** The AT protocol has no request IDs; replies are matched to requests by order. An actor guarantees this. Unsolicited notifications that land in the middle of another command's reply are handed to the call-state logic.

SMS uses text mode, and anything outside the GSM character set (all Chinese) switches to UCS2 encoding. **There's a trap in decoding**: a phone number is itself a valid hex string. So the UCS2 check must be "length is a multiple of 4 **and** contains letters", otherwise `13800138000` gets displayed as a string of Chinese characters. There's a test for this.

### Connected, but no carrier, number or signal

**Cause**: The timeout logic targeted the wrong object. It failed the request **currently in flight**, not the request that had started the timer.

Concretely: the first status query had long since returned successfully, but its 5-second timer fired afterwards and killed a different request that was in progress at that moment; that request's timer then killed the next one... Of six quick queries, only the first survived.

**Fix**: Each request carries its own identity, and a timer can only fail its own request. The regression test replays this exact sequence.

### Call connects, but no sound at all

**Evidence**: Everything on the module side was right: the sound card loaded, audio enabled, both internal channels running. But the two streams in the USB direction looked like this:

```text
pcm5p PREPARED    uplink, nobody feeding it data
pcm6c PREPARED    downlink, nobody reading data
```

"Prepared", but no data flowing. The problem was on the host side.

**Cause**: On macOS, an `AVAudioEngine`'s input and output **must be the same device**. Here each engine had been given two different devices (Mac mic in, module out; module in, Mac speaker out). It doesn't throw an error; it just silently doesn't work.

**Fix**: For each direction, create a private **Aggregate Device** that pairs the needed input and output, and run the engine on the aggregate device. Private means it doesn't appear in the system sound settings and dies with the process.

Another silent failure: the property that sets the current device is element 0 in global scope for both input and output. Writing element 1 for input doesn't error; it just quietly stays on the default device.

### The other side can't hear me, and there's no error

**Cause**: Without microphone permission, capture runs as usual but outputs pure silence. It shows up as one-way audio, not as a permission error.

The system privacy log told the whole story: the app's identifier was "identifier for invalid code". Because the app wasn't signed, it had no stable identity, so microphone authorization could neither be meaningfully requested nor saved.

**Fix**: Sign with your developer team (**don't build with code signing disabled**); request permission at launch rather than waiting until the call connects; show the permission status on the settings page and the call page. A development signature expires after about a week; just rebuild when it does.

### After using the app, the Mac's own speakers broke

This is the most absurd one in the whole post.

**Symptom**: Sound from other apps starts stuttering and distorting, and stays that way until you reboot.

**Evidence**: The system audio service logged 671 IO errors naming this app, flagged "security violation" and "overload", on the built-in speakers, with clients at both 48000 Hz and 8000 Hz present at the same time.

**Cause**: The uplink aggregate device made the module's 8 kHz output its main device, which is to say its **clock source**, and then added the Mac's microphone to it. But the Mac's speakers, microphone and codec all share **one clock domain and one hardware engine**. So the whole machine's built-in audio engine got dragged onto an external 8 kHz crystal.

And since the app didn't destroy the aggregate device on exit, that state persisted.

**Fix**: Both aggregate devices use **the Mac's own device as the clock source**, with drift compensation enabled on the other sub-devices. That is the correct way to reconcile two different crystals. On exit the aggregate devices are destroyed synchronously, and on launch any left over from a crash are swept up.

**If you've already been hit**, no reboot needed:

```sh
sudo killall coreaudiod
```

To dig up the evidence, use `log show --start <time> --predicate 'process == "coreaudiod"'`.

### After stopping the app in the debugger, the next run can't see calls

**Cause**: The reader process is a child of the app, and on macOS a child process outlives its parent. The debugger's "stop" is a forced kill, so the cleanup code never gets a chance to run; the reader is adopted by the system and keeps reading.

The next run opens another reader, and the two readers split the replies: the reply to the call-status query lands in the pipe left behind by the previous run, so the call never reaches "connected" and the audio bridge never starts.

At one point I found a process that had started at 4:24 AM and was still reading at 5:46.

**Fix**: Record each reader's process ID outside the actor (a termination callback can't wait on async work), kill them on exit, and sweep them up on launch.

**By the same logic, never run another AT script in a terminal while the app is connected to the module.** Both sides are reading the same device and will steal each other's bytes.

### Mute must not stop the stream

While muted, the uplink engine has to keep running, just feeding silence. Stopping the engine interrupts the module's uplink stream, and some networks treat a stalled uplink as a dropped call.

A clear "Muted" indicator on the call screen is also necessary: **a forgotten mute looks exactly like the one-way-audio bug you just fixed.**

### Other bits

- **Multiple modules**: Each module has its own AT port, its own voice route (the driver is loaded in each module), and its own SMS history. An incoming call on any of them takes over the window. Modules remember their names by USB path, as long as they stay in the same port.
- **Headset selection**: Remembered by UID, because CoreAudio device IDs change on every boot or replug. The module's own two audio interfaces don't appear in the list: selecting them would route the call back into the call itself.
- **Two-way level meters**: With only a downlink meter, "the mic isn't getting into the call" and "the module isn't sending sound out" look exactly the same. One more meter, half the guessing.

### A side experiment: a phone bot

The app also has an experimental page: dial, then listen, think, answer. Speech recognition is SenseVoice, synthesis is Kokoro, and the LLM is qwen3:30b-a3b on Ollama on the LAN (0.2 to 0.4 seconds to first token). Call content never leaves the LAN.

There's an unexpected bonus: because the module splits the far end and the near end into two separate devices, the audio the bot hears naturally contains none of its own voice. Barge-in (making it shut up when you talk) is just an energy threshold, with no echo cancellation involved at all.

This part has enough traps of its own to deserve a separate post: the audio engine's various silent failures on 8 kHz devices, voice activity detection eating the first word, discontinuities introduced by chunk-by-chunk resampling. I won't go into them here.

## Platform differences at a glance

| What Linux has | The Mac substitute |
|---|---|
| Serial ports | adb into the module, via its internal device nodes |
| sysfs / udev | `adb devices -l` plus the USB path |
| ALSA | CoreAudio aggregate devices |
| Wi-Fi calling data plane | None; it stays on the Raspberry Pi |
| No signing required | Signing required, or no microphone |

The next post goes back to the Raspberry Pi gateway and builds an iPhone client for it, so that every SIM card plugged into the gateway becomes a line on your phone.

## The series

1. [What Is It, Really](https://wuming.si/blog/4088)
2. [An SMS and eSIM Gateway on a Raspberry Pi](https://wuming.si/blog/4089)
3. [VoWiFi from Scratch](https://wuming.si/blog/4090)
4. [USB Handsets, Browser Calls and an ESP32](https://wuming.si/blog/4091)
5. [On a Mac](https://wuming.si/blog/4092)
6. [The iPhone Client](https://wuming.si/blog/4093)
7. [An Android Tablet Drives It Directly](https://wuming.si/blog/4094)

---

*This series is a personal record of learning and technical research. The module's voice driver is a GPL derivative; it is not distributed with the project, and you need to supply it yourself.*
