# Turning a SIM Card into a Server: An SMS and eSIM Gateway on a Raspberry Pi (2)

- URL: https://wuming.si/blog/4089/
- Author: Wuming
- Published: 2026-10-18
- Language: en
- Categories: Raspberry Pi, Technology, English

> Previous: [What Is It, Really](https://wuming.si/blog/4088) | Next: [VoWiFi from Scratch](https://wuming.si/blog/4090) | 中文版：[树莓派上的短信与 eSIM 网关](https://wuming.si/blog/4003)

The previous post worked out what that 4G dongle actually is: an LTE module running Linux that can make calls, send texts and manage eSIMs. This post puts it to work.

The goal is an always-on Raspberry Pi with one or two modules plugged in, providing:

- a web console showing module status, signal and SIM card details;
- sending and receiving SMS with conversation history, with important messages forwarded automatically to Telegram, email or wherever else;
- downloading, enabling, disabling and deleting eSIM profiles;
- sharing the 4G connection with the LAN as a proxy.

One very practical use: a number you rarely use but can't let lapse (bank verification codes, a foreign number, a backup SIM) no longer has to occupy a phone's SIM slot. Drop it into this Pi, have texts pushed to your phone automatically, and still make calls with it when you need to.

Calling and Wi-Fi calling are bigger topics, saved for parts 3 and 4.

## Why not write it from scratch

At first I really did write my own Go daemon. Somewhere along the way I realized that on Linux, the system already does most of the dirty work for you: serial drivers, network drivers, firewall forwarding are all there. What's left to write is device management, SMS decoding, the eSIM flow, notification pushing and a web console, and a project called VoHive already does all of that quite thoroughly: Go backend, Vue frontend, eSIM built on euicc-go.

So I changed approach: use VoHive's backend as the foundation, and port over, one by one, the things I had already verified on real hardware (calling, a pile of Wi-Fi calling fixes, USB handset support).

The decision itself was fine, but it planted a landmine worth mentioning up front: **what gets lost most easily in a migration is exactly those few lines of fixes that no test covers.** Later, incoming Wi-Fi calls once again all went straight to voicemail, and outgoing calls once again did nothing. Both traced back to the same cause: a one-line fix in the old code that never made it across. Part 3 goes into these two rounds of redone work in detail.

## Hardware

| Item | Configuration |
|---|---|
| Host | Raspberry Pi 4 Model B, Debian 13 (arm64) |
| Modules | Two QDC507s on the same USB hub (one foreign SIM, one Chinese SIM) |
| Power | Must be sufficient |

That last row is not a formality. The Pi 4's USB ports are linked: **cut power to one port and all of them go down together**. This comes up again later with the USB handset hangs: many routine "just reset the device" operations on a Pi 4 will reset the modules along with it.

## Building and deploying

It's pure Go with no cgo, so it cross-compiles on a Mac or Linux dev machine:

```sh
make build-arm64
```

**First pitfall: without UPX installed, `make` fails outright.** UPX is a tool that compresses executables, and the Makefile treats it as mandatory. If you don't want to install it, just run the go build steps on their own:

```sh
npm ci --prefix web && npm run build --prefix web
rm -rf internal/web/dist && cp -R web/dist internal/web/dist
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -trimpath -tags "with_utls nomsgpack" \
  -ldflags "-s -w" -o dist/vohive_linux_arm64 ./cmd/vohive
```

Incidentally, `go build ./cmd/vohive` without `-o` leaves an 87 MB binary in the repo root, which is easy to commit by accident.

The deployment directory looks like this; config, data and logs are all relative to where the binary lives:

```text
/opt/vohive-call/
├── vohive                 # the binary
├── config/config.yaml
├── data/                  # database, certificates, recordings
├── logs/app.log
├── qdc507-route           # voice routing script (part 4)
└── qdc507/                # module voice driver (bring your own, part 4)
```

Minimal config:

```yaml
server:
  port: 7575
  debug: false          # set to true when debugging eSIM issues; needs a restart to take effect
web:
  username: admin
  password: change-me
devices:
  - id: us
    name: Primary
    modem_imei: "86xxxxxxxxxxxxx"
    device_backend: at
```

Add a systemd service so it starts at boot:

```ini
# /etc/systemd/system/vohive-call.service
[Unit]
Description=VoHive gateway
After=network-online.target

[Service]
WorkingDirectory=/opt/vohive-call
ExecStart=/opt/vohive-call/vohive
Restart=on-failure

[Install]
WantedBy=multi-user.target
```

```sh
sudo systemctl daemon-reload
sudo systemctl enable --now vohive-call
tail -f /opt/vohive-call/logs/app.log
```

From then on, updating means overwriting the binary and restarting the service.

## udev rules: skip them now and something will break later

udev is Linux's mechanism for managing device nodes: it can give devices fixed names, set permissions and tag them. Two things here are mandatory.

### Keep ModemManager away from the module

ModemManager is the system service that manages cellular devices on desktop Linux. It works by writing AT commands to the serial port to probe what the device can do. The problem is that its commands interleave with yours, so the replies get misaligned: you send `AT+CSQ` to ask for signal strength and get the reply to its command instead.

This kind of failure looks exactly like a firmware bug and can eat a lot of debugging time.

Don't stop ModemManager outright (other devices on the machine may still need it); just tag the module so it gets ignored:

```udev
SUBSYSTEM=="usb", ATTRS{idVendor}=="2c7c", ATTRS{idProduct}=="0125", ENV{ID_MM_DEVICE_IGNORE}="1"
SUBSYSTEM=="tty", ATTRS{idVendor}=="2c7c", ATTRS{idProduct}=="0125", ENV{ID_MM_DEVICE_IGNORE}="1"
SUBSYSTEM=="net", ATTRS{idVendor}=="2c7c", ATTRS{idProduct}=="0125", ENV{ID_MM_DEVICE_IGNORE}="1"
```

### Give each module a fixed name

**Symptom**: both lines went offline at the same time and stayed down for days, with the log endlessly repeating `ATE0: command timed out`.

**Cause**: the two modules' `ttyUSB` numbers had swapped as whole blocks. The first went from `ttyUSB2` to `ttyUSB3`, the second from `ttyUSB6` to `ttyUSB5`. The program kept sending commands to the old numbers, and those positions were now the *other* module's diagnostic port, which of course doesn't answer AT commands.

**Why the usual fix doesn't work**: the two modules have identical vendor IDs, product IDs and serial numbers (the serial number is those 256 `0xAA` bytes from the previous post). The only thing that tells them apart is which physical port they're plugged into.

The rule you'll find all over the internet **simply does not work**:

```udev
SUBSYSTEM=="tty", ATTRS{bInterfaceNumber}=="02", ATTRS{idVendor}=="2c7c", ...
```

That's because udev requires all `ATTRS` matches in one rule to hit **the same parent device**, and `bInterfaceNumber` and `idVendor` live at different levels of the device tree, so they can never match together. It's a very common misconception: the copied rule throws no error, it just quietly never matches.

The right way is to match the interface's device name directly, in the form `hub-port:config.interface`:

```udev
SUBSYSTEM=="tty", KERNELS=="1-1.1:1.2", SYMLINK+="modem-a-at"
SUBSYSTEM=="tty", KERNELS=="1-1.2:1.2", SYMLINK+="modem-b-at"
```

```sh
sudo udevadm control --reload && sudo udevadm trigger
ls -l /dev/modem-a-at /dev/modem-b-at
```

From then on, use these two symlinks everywhere. **Never write `/dev/ttyUSB2` in a config.**

## The web console and certificates

The console lives at `https://<Pi's IP>:7575` and uses a self-signed certificate by default.

**Pitfall**: the browser shows a security warning, you click "proceed anyway", the page loads, but some features still don't work, and the server log keeps printing `tls: unknown certificate`.

The reason is that "proceed anyway" only applies to the current page. WebSocket connections the page opens afterwards (needed for browser calling) are still rejected.

The real fix is to add the certificate to the system trust store and then **fully quit the browser** and reopen it:

```sh
# macOS
security add-trusted-cert -d -r trustRoot \
  -k "$HOME/Library/Keychains/login.keychain-db" server.crt
```

This one will show up again: browser calling in part 4 and the iPhone app in part 6 both tripped over the exact same thing.

## SMS

VoHive already handles SMS encoding and decoding (the PDU format, UCS2 encoding for Chinese). Received messages are stored, shown grouped by conversation and pushed out according to rules.

None of the problems I actually hit were in the encoding or decoding. They were all cases of **the message never reaching the program at all**.

### SIM storage full, texts silently rejected for two weeks

**Symptom**: from a certain day on, not a single text arrived. No error, no alert, the program's log looked perfectly normal.

A quick check:

```text
AT+CPMS?
+CPMS: "ME",23,23,"ME",23,23,"ME",23,23
AT+CNMI?
+CNMI: 2,1,0,0,0
```

The first line means: storage capacity 23 messages, 23 used, full.

**Cause**: the second parameter of `+CNMI` is 1, meaning "store the new message first, then report a notification". With storage full, delivery is rejected at the SMS layer, and the network retries for a while before giving up.

Meanwhile the program only reads a message (and deletes it after reading) when it receives a notification. Messages that arrived while the program wasn't running, or that were left over from before a SIM swap, are never read and therefore never deleted. All 23 of them were marketing texts received by the previous SIM.

What makes this pitfall so nasty: **the backlog left by one SIM stops every SIM inserted afterwards from receiving texts.**

**Fix**: add a periodic sweep. `AT+CPMS?` to check occupancy, `AT+CMGL=4` to read everything in storage, run each message through the same decode-and-callback path as live messages, then `AT+CMGD` to delete them one by one. When storage is empty it costs a single command, so it's safe to run often.

### The sweep looked like it worked, but only by coincidence

**Symptom**: the sweep was hooked to the "SIM ready" event, and new texts did start coming in. But a closer look showed the new-message notification path had never actually fired once.

**Cause**: the same pitfall from the previous post. The URC port is `usbat`, so a program reading `/dev/smd7` over ADB never receives notifications. The `+CPIN` and `+CSQ` lines in the log that looked like notifications were actually replies to polling commands misread as unsolicited reports, and they happened to trigger the sweep.

One bug covering for another, and the whole thing looked like it worked.

**Fix**: the inbox now has its own independent 20-second polling timer and no longer depends on any event. On top of that, initialization checks the URC port and changes it to `"all"` if it isn't already (reading first, then writing, to avoid writing a non-volatile parameter on every start). Modules that can receive notifications get texts immediately; the ones that can't get them at most 20 seconds late.

While verifying this, I watched a verification code that the carrier had been retrying for hours finally land in the database.

### Two conversations for the same number

`138xxxxxxxx` and `+86138xxxxxxxx` were treated as two different people. The fix is to fold the country-code prefix consistently, while leaving short numbers (carrier service numbers) and foreign numbers as they are.

## eSIM

An eSIM is not a special kind of card, but **a card that can hold profiles**. The QR code or activation code your carrier gives you essentially tells the card to download a profile from a certain server. That flow is called SGP.22, a GSMA standard.

Here, the whole flow runs over AT command logical channels, with no dedicated driver required:

```text
AT+CCHO="A0000005591010FFFFFFFF8900000100"   -> +CCHO: 1          # open the card's management application
AT+CGLA=1,22,"81E2910006BF3E035C015A"        -> +CGLA: 4,"6115"   # ask for the EID (the card's unique ID)
AT+CGLA=1,10,"81C0000015"                    -> BF3E125A10<EID>9000
AT+CCHC=1                                    -> OK
```

The console shows the card's manufacturer, firmware, certificates and installed profiles. You can download new ones with an activation code, and enable, disable, rename or delete them.

### Three quirks of `AT+CGLA`

Get any one of these wrong and you get a flat error, with an error message that tells you nothing about why:

| Quirk | Behavior |
|---|---|
| The hex argument **must be quoted** | Without quotes it's just `ERROR` |
| The length is the **number of hex characters**, not bytes | 5 bytes of data means a length of 10 |
| Fetching data on logical channel 1 needs a `0x81` class byte | Writing `0x01` per the ISO standard returns `6F00` |

On top of that, these commands first reply with `61XX`, meaning "XX bytes of data are waiting", and you have to send another fetch command to actually get it.

An ordinary SIM card (not an eUICC) has no management application, so `AT+CCHO` simply returns `ERROR`. That's normal; nothing is broken.

### Every download died on the same line

**Symptom** (the Chinese prefix reads "failed to download eSIM profile"):

```text
下载 eSIM profile 失败 ... err="tag encoding with less than one byte\nEOF"
```

Translated, that line only says "the parser got 0 bytes". It says nothing at all about why it got 0 bytes.

**How I tracked it down**: turn on `server.debug` and restart, and the library logs every round trip with the card plus the full requests and responses to the carrier's server. I also added one more log line per card command round trip, recording only the command header, length and status word.

The key point: **only the per-block status words reveal which block it gave up on.** The upper layer only sees the reassembled full response, and that response was empty.

```text
81E21100 9000   81E21101 9000   ...   81E21106 9000     <- always "continue", never "last"
```

**Cause**: this particular payload happened to be exactly 840 bytes. The library splits it into 120-byte blocks, giving exactly 7 blocks. But it decides "which block is the last one" with `length / 120`: 840 divided by 120 is 7, while the block indices only go up to 6. So every block was marked "more to come", the card kept replying "OK, continue", waiting for a next block that would never arrive. The upper layer read an empty response.

An off-by-one error sitting exactly on a divisibility boundary. When the data length isn't a multiple of 120, everything works.

**Fix**: upstream had already fixed it (`blockCount = 1 + (len-1)/mss`); just upgrade the dependency. After that, the 7th block finally carried the "last" flag, and the flow reached the carrier's server for the first time.

### Once fixed, the server said "no"

```text
8.1.1 / 3.8  EID does not match the expected value, or there is no pending RSP Session for this eUICC.
```

This time it was a genuine rejection: that activation code had already been used on a phone.

Activation codes are usually single-use, and some are also bound to a card's EID. For testing, have an unused code ready, or use a different card.

The good news: **a real business rejection is worth far more than a parse error.** It means the dozens of steps before it were all correct.

## Sharing 4G with the LAN

Each module can run its own proxy instance, with outbound traffic strictly bound to that module's network interface, so nothing leaks across.

**Before sharing, check whether the SIM is roaming.** One of the test SIMs was registered as roaming (`AT+CEREG?` returned `0,5`, where 5 means registered, roaming). In that state, a single command that brings up a data connection, or a single DHCP exchange, can rack up expensive data charges.

That SIM ended up being used only for Wi-Fi calling (next post), and its cellular radio could even stay in airplane mode the whole time.

## A few small pitfalls

| Symptom | Cause | Fix |
|---|---|---|
| Starting from outside the install directory fails with `open config/config.yaml: no such file or directory` | The config path is relative to the working directory | If it isn't found in the working directory, fall back to the binary's directory |
| `unable to open database file: out of memory (14)` | The `data/` directory doesn't exist. The error message is completely misleading | Create the directory before opening the database |
| AT port busy while debugging | The service is running and holds it exclusively | Stop the service once when you start debugging and start it again when done; don't restart it at every step |
| A reader process left behind on the module, after which programs "get no replies" | Killing the local adb client does **not** kill the reader process on the module | Clean up leftovers the first time the device node is opened (details in part 5) |

## What we have now

A plugged-in, always-on Raspberry Pi managing two SIM cards: receiving and sending texts, downloading eSIMs, sharing 4G. Texts get pushed to my phone, and the whole thing doesn't take up a single phone SIM slot.

The next post is the toughest in the whole series: no cellular signal at all, with the SIM card reaching the carrier's core network over Wi-Fi, and still making calls and receiving texts.

## The full 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 record of personal learning and technical research. Please comply with local laws and regulations and your carrier's terms of service.*
