infix/doc/modem.md

Cellular Modem (WWAN)

Infix supports cellular modem connectivity via modems that expose a QMI or MBIM control interface over USB. Form factor does not matter: USB dongles, mPCIe cards, and M.2 Key-B modules all work as long as the modem chipset uses USB on the connector (the typical case for 4G/LTE modems). See Supported Modems below for the exceptions.

Setup involves three configuration items:

• A modem0 hardware component for the physical modem
• A sim0 hardware component for the SIM card slot
• A wwan0 network interface that references both and carries the bearer (APN) configuration

Architecture

Infix uses a three-layer architecture for cellular modem support:

1. Modem hardware component (modem0): the physical modem

   • Configured via ietf-hardware with class infix-hardware:modem
   • admin-state controls whether ModemManager and modemd are active
   • Holds physical-layer config: allowed bands, preferred mode, location
   • Auto-discovered into factory-default config when the modem is present at first boot

2. SIM hardware component (sim0): the SIM card slot

   • Configured via ietf-hardware with class infix-hardware:sim
   • Holds PIN/PUK credentials and carrier profile
   • Auto-discovered into factory-default config alongside the modem

3. Network interface (wwan0): data bearer to the cellular network

   • Configured via ietf-interfaces with type infix-if-type:modem
   • References a modem component and a SIM component
   • Holds bearer config: APN, IP type, roaming, route preference, authentication
   • Always added by the user, never auto-created

Naming Conventions

Name Pattern	Type	Description
modemN	Modem hardware	Hardware component for the physical modem
simN	SIM hardware	Hardware component for the SIM card slot
wwanN	Modem interface	Network interface for cellular data

Where N is a number (0, 1, 2, ...).

Tip

Using these naming conventions simplifies configuration since type and class are automatically inferred. Creating a hardware component named modem0 automatically sets its class to infix-hardware:modem, and creating an interface named wwan0 automatically sets its type to infix-if-type:modem.

Note: This inference only works via the CLI. When configuring over NETCONF or RESTCONF the class and type must be set explicitly.

Multi-Bearer (Multiple APNs)

Multiple wwan interfaces can reference the same modem component, each with a different APN. Same idea as multi-SSID on a WiFi radio: one hardware modem, several independent data connections.

Configure wwan0 and wwan1 both pointing to modem0:

edit interface wwan0 wwan
set modem modem0
set bearer apn internet

edit interface wwan1 wwan
set modem modem0
set bearer apn corporate.vpn.apn

Current Limitations

• The modem must be present at boot. Hot-plug is not supported.
• If the modem is absent at boot, and no probe-timeout is set, a dummy wwan0 placeholder is created immediately so IP configuration can proceed. A reboot is required once the hardware is inserted.

Supported Modems

Modems exposing a CDC-WDM control interface over USB are supported, regardless of physical form factor. Two protocols are handled by ModemManager:

• MBIM: Mobile Broadband Interface Model (e.g. Sierra Wireless, Quectel EM06/EM12)
• QMI: Qualcomm MSM Interface (e.g. Sierra Wireless EM7xxx, Quectel EM/RMxxx)

Most 4G/LTE modules (USB dongles, mPCIe cards, M.2 Key-B) use USB on the connector even when the slot also carries PCIe lanes. From Infix's view they are all USB modems. PCIe-only modems (some 5G NR modules) are not supported, since the modemd / ModemManager pipeline assumes a USB-attached control interface.

Step-by-step Setup

1. Hardware Detection

At first boot, USB modems detected by the kernel are written to /run/system.json and added as hardware components in the factory-default configuration. Verify the modem appears:

admin@example:/> show modem
──────────────────────────────────────────────────────────────
Cellular Modems
NAME    MANUFACTURER  MODEL   STATE       NETWORK  SIGNAL
modem0  Quectel       EM06-E  registered  lte      good
──────────────────────────────────────────────────────────────
SIM Cards
NAME  SLOT  STATE     OPERATOR
sim0  1     unlocked  Tele2

The STATE, SIM STATE, and SIGNAL columns are color-coded so the healthy / attention / problem cases are visible at a glance: green for registered, connected, unlocked, excellent, good; yellow for transient or attention states like enabling, pin-required, poor; red for failed, not-inserted, bad.

If modem0 does not appear:

• Verify the kernel sees the modem (dmesg | grep -i mbim or dmesg | grep -i qmi). Without a kernel driver no further setup is possible.
• On boards with a custom factory configuration, or after replacing hardware on a running system, the components may need to be added manually. See Step 2.

2. Hardware Components

If show modem already lists modem0 and sim0, the components were auto-discovered into the factory-default configuration and you can skip ahead to Step 3.

Otherwise, add them manually. The class is inferred from the component name (modemN → infix-hardware:modem, simN → infix-hardware:sim). The admin-state must be set explicitly. There is no implicit default, and without unlocked confd will not start ModemManager or modemd:

admin@example:/> configure
admin@example:/config/> edit hardware component modem0
admin@example:/config/hardware/component/modem0/> set state admin-state unlocked
admin@example:/config/hardware/component/modem0/> end
admin@example:/config/hardware/> edit component sim0
admin@example:/config/hardware/component/sim0/> set state admin-state unlocked
admin@example:/config/hardware/component/sim0/> leave
admin@example:/>

To take the modem offline cleanly without removing the configuration, set admin-state locked. All related services are stopped and the bearer is torn down before the modem goes offline:

admin@example:/config/> edit hardware component modem0
admin@example:/config/hardware/component/modem0/> set state admin-state locked
admin@example:/config/hardware/component/modem0/> leave

Slow USB Modems

USB modems can be slow to enumerate at boot. The kernel wwan interface may not appear until several seconds after confd starts applying configuration. The probe-timeout leaf inside the modem hardware configuration container controls how long confd waits. It defaults to 30 seconds when the container is present.

To enable the timeout, create the modem configuration container (this also lets you configure bands, preferred mode, etc.):

admin@example:/config/> edit hardware component modem0 modem
admin@example:/config/hardware/component/modem0/modem/> leave

With probe-timeout at its default of 30, confd waits up to 30 seconds for the wwan interface to appear before proceeding. For most modems it is ready in 2-5 seconds. If the modem has not appeared within the timeout, a dummy placeholder interface is created and a reboot is required for the real interface to take over. Set probe-timeout 0 to disable waiting entirely.

Note

Some Quectel modules (e.g. EM05) re-enumerate the USB device several times during a cold-boot firmware-init sequence that takes around 50 to 60 seconds. Bump probe-timeout to 90 for those, otherwise the dummy placeholder fires before the modem settles and the real interface ends up with a different name (wwan1 instead of wwan0).

3. Configure the Bearer (APN)

Bearer configuration lives on the wwan0 interface. Reference the modem hardware component and set the APN:

admin@example:/> configure
admin@example:/config/> edit interface wwan0
admin@example:/config/interface/wwan0/> set wwan modem modem0
admin@example:/config/interface/wwan0/> set wwan sim sim0
admin@example:/config/interface/wwan0/> set wwan bearer apn internet
admin@example:/config/interface/wwan0/> leave

The modem will connect automatically once the bearer is configured and the hardware is unlocked.

Key bearer parameters:

• apn: Access Point Name, required, provided by your operator (e.g. internet, data.vodafone.com, web.tele2.se)
• route-preference: Administrative distance for the default route (default: 200). Higher value = lower priority. The default of 200 places cellular behind wired Ethernet (distance 5) and WiFi, so cellular acts as a failover when the wired link is up
• roaming: Allow data when roaming on a foreign network (default: false)
• ip-type: ipv4, ipv6, or ipv4v6 dual-stack (default: ipv4v6)

4. Configure Authentication

Most consumer APNs connect without credentials. If your operator requires authentication, first store the password in the keystore, then reference it from the bearer.

Create the keystore entry for the APN password:

admin@example:/> configure
admin@example:/config/> edit keystore symmetric-key apn-pass
admin@example:/config/keystore/…/apn-pass/> set key-format passphrase-key-format
admin@example:/config/keystore/…/apn-pass/> change cleartext-symmetric-key
Passphrase: ************
Retype passphrase: ************
admin@example:/config/keystore/…/apn-pass/> leave

Then point the bearer's authentication at it:

admin@example:/> configure
admin@example:/config/> edit interface wwan0 wwan bearer
admin@example:/config/interface/wwan0/wwan/bearer/> set authentication username myuser
admin@example:/config/interface/wwan0/wwan/bearer/> set authentication password apn-pass
admin@example:/config/interface/wwan0/wwan/bearer/> leave

Setting any leaf inside authentication creates the container, which enables authentication. The password leaf is a reference to a symmetric key in the keystore, not the plaintext password itself.

The authentication protocol defaults to chap. To use PAP instead:

admin@example:/config/interface/wwan0/wwan/bearer/> set authentication type pap

5. Configure SIM PIN

If the SIM requires a PIN to unlock, configure it on the SIM hardware component:

admin@example:/config/> edit hardware component sim0
admin@example:/config/hardware/component/sim0/> set sim pin 1234
admin@example:/config/hardware/component/sim0/> leave

6. Verify Connectivity

Once connected, the wwan0 interface receives an IP address from the carrier and modemd installs the default route:

admin@example:/> show interface wwan0
name                : wwan0
type                : modem
index               : 5
mtu                 : 1500
operational status  : up
ip forwarding       : enabled
physical address    : 12:34:56:78:9a:bc
ipv4 addresses      : 10.142.87.33/30 (wwan)
ipv6 addresses      : 2001:db8:1:2::1/64 (wwan)
in-octets           : 84213
out-octets          : 31456

Check the full modem state including signal quality and registration:

admin@example:/> show modem modem0
MODEM: modem0                                                 
──────────────────────────────────────────────────────────────
Hardware Information
  Manufacturer        : Quectel
  Model               : EM06-E
  Firmware Version    : EM06ELAR04A07M4G
  Serial Number       : 352753090141905
  IMSI                : 240021234567890
  ICCID               : 8946020000001234567
──────────────────────────────────────────────────────────────
Status
  State               : connected
  Power State         : on
  Signal              : Quality: 72% good  RSSI: -59 dBm  RSRP: -95 dBm  RSRQ: -11.0 dB
──────────────────────────────────────────────────────────────
Cellular
  Registration        : home
  Service State       : attached
  Operator            : Tele2
  Operator ID         : 23002
  Network Type        : lte
──────────────────────────────────────────────────────────────
SIM Card
  Name                : sim0
  Slot                : 1
  Lock State          : unlocked
  Operator            : Tele2

When the modem is in trouble, the same view shows why. A State: failed line is followed by Failed Reason (e.g. sim-missing), and the SIM Card section's Lock State reads not-inserted or pin-required to match.

Cellular Failover

The default route-preference (200) is deliberately higher than the distances used by wired Ethernet (udhcpc default: 5) and WiFi. When a wired link is up it takes precedence automatically; cellular becomes the active path only if higher-priority routes are withdrawn.

A default route via the bearer is always installed when the bearer connects. To adjust the failover priority between two cellular modems, or to prefer cellular over WiFi, set route-preference explicitly:

admin@example:/config/> edit interface wwan0 wwan bearer
admin@example:/config/interface/wwan0/wwan/bearer/> set route-preference 100
admin@example:/config/interface/wwan0/wwan/bearer/> leave

Lower route-preference = higher priority.

Roaming

Data roaming is disabled by default. To allow the modem to connect when on a foreign (roaming) network:

admin@example:/config/> edit interface wwan0 wwan bearer
admin@example:/config/interface/wwan0/wwan/bearer/> set roaming true
admin@example:/config/interface/wwan0/wwan/bearer/> leave

Important

Enabling roaming may incur significant charges depending on your mobile subscription. Check with your operator before enabling.

Management Commands

Restart Bearer

Disconnect and reconnect all bearers without resetting the modem hardware. Use this after changing APN or authentication settings:

admin@example:/> modem restart modem0

Reset Modem

Factory-reset the modem firmware. This clears all modem-internal settings and takes longer than a restart. Only use it if the modem is in a bad state that a bearer restart cannot fix:

admin@example:/> modem reset modem0

Note

Not all modules accept --reset from ModemManager. Quectel EM05, for example, rejects both --reset and --factory-reset. The only way to recover from a hung firmware on these is a physical power cycle. When the modem reports the rejection, modemd logs it once and stops retrying.

Send SMS

Send an SMS message via the signalling plane. No active data bearer is required; the modem only needs to be registered on the network:

admin@example:/> modem sms modem0 +46701234567 "Hello from Infix"

Note

Some SIM cards have Fixed Dialing Number (FDN) enabled, which restricts outgoing SMS and calls to a pre-configured whitelist. If modem sms fails, check whether FDN is active with mmcli -m 0 and look for enabled locks: fixed-dialing in the output.

Troubleshooting

Modem not detected (show modem shows no modem entry)

• Verify the modem is connected and recognized by the kernel: check dmesg for cdc_mbim or qmi_wwan driver messages
• Confirm /sys/class/usbmisc/ contains a cdc-wdm* entry
• The modem must be present at boot; hotplug after boot is not supported

wwan0 shows as down or has no IP address

• Check show modem modem0. The State should show registered or connected, not failed
• If the State is failed, look at the Failed Reason line that immediately follows:
  • sim-missing: the SIM Card section will also show Lock State: not-inserted. Power off the device, insert the SIM, power back on. A warm reboot is not enough; on most M.2 slots the SIM tray stays powered through reboot, so the modem keeps the original not-inserted reading
  • unlock-required: the SIM Card section will show Lock State: pin-required. Configure the PIN with set hardware component sim0 sim pin <code>
  • sim-wrong / sim-error: the SIM is not compatible or is damaged. Try a different SIM
• Verify the APN is correct for your operator
• Check system logs with show log for modemd or ModemManager messages

wwan0 interface is a dummy (no data flows, no carrier address)

• The modem was not enumerated by the kernel before confd applied config
• Create the modem hardware configuration container (see Step 2), which enables the default 30-second probe-timeout so confd waits for the wwan interface before falling back to a dummy placeholder

High latency or poor signal

• Use show modem modem0 to check signal quality and RSRP
• Signal below -110 dBm RSRP typically indicates poor coverage
• Consider repositioning the antenna or the device