Turning a SIM Card into a Server: An SMS and eSIM Gateway on a Raspberry Pi (2)
Previous: What Is It, Really | Next: VoWiFi from Scratch | 中文版:树莓派上的短信与 eSIM 网关
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:
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:
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:
/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:
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:
# /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
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:
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:
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:
SUBSYSTEM=="tty", KERNELS=="1-1.1:1.2", SYMLINK+="modem-a-at"
SUBSYSTEM=="tty", KERNELS=="1-1.2:1.2", SYMLINK+="modem-b-at"
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:
# 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:
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:
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”):
下载 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.
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”
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
- What Is It, Really
- An SMS and eSIM Gateway on a Raspberry Pi
- VoWiFi from Scratch
- USB Handsets, Browser Calls and an ESP32
- On a Mac
- The iPhone Client
- An Android Tablet Drives It Directly
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.
Comments