Soracom Onyx LTE Dongle Setup Guide

Requirements

To get set up, you will need the following:


SIM Registration

If you have not already done so, take a moment to follow the instructions in the SIM Registration documentation and register your Soracom SIM card to your account.


Hardware Setup

  1. Carefully remove the Soracom SIM card from its packaging.

    Remove SIM

    The plan01s SIM is a 3-in-1 design that allows you to conveniently break out the SIM card into standard/mini (2FF), micro (3FF), and nano (4FF) form factors. As the Onyx LTE dongle uses the nano (4FF) size, take care to remove the nano SIM card size when removing it from its packaging.

  2. Slide the rear cover open in order to access the SIM slot.

    Open rear cover

  3. Insert the SIM card into the SIM slot, paying attention to the orientation notch.

    Insert SIM card

  4. Replace the rear cover.

Your Onyx LTE dongle is now ready for software configuration.


Linux Installation

The Onyx LTE dongle uses a Quectel EG25-G modem internally, which is natively supported in Linux kernel versions 2.6 and above, and therefore does not require any additional driver installation. However, you must configure an application to establish and manage the cellular connection.

While there are many applications that can do this, NetworkManager and WvDial are two of the most popular and reliable options. For most devices (such as Raspberry Pi, Nvidia Jetson, LattePanda, and others), we recommend using NetworkManager as it will take care of detecting and configuring the Onyx LTE dongle automatically and can be easily configured for a variety of use cases. However, if you prefer to use a more traditional PPP connection, or if NetworkManager is not available for your specific Linux distribution (such as embedded gateways or routers), you can use WvDial instead.

Using NetworkManager

Connection instability on Raspberry Pi OS

A bug exists in older versions of ModemManager (a component of NetworkManager used to detect and control modems) that mistakenly causes some Quectel modems, including the Quectel EG25-G found in the Onyx LTE dongle, to unnecessarily perform a full cellular network scan each time the Linux device is rebooted, when a modem is unplugged and reconnected, or when ModemManager itself is restarted, during which time the modem is unable to send or receive data.

Once the modem has finished the network scan, the device and modem will resume normal operation. However, if your Linux device is restarted frequently, or your application requires periodically disabling and re-enabling the modem or restarting ModemManager, the network scan caused by the bug may introduce unacceptable delays in establishing cellular connectivity.

To see if your device is affected, run the mmcli --version command and check if you have v1.14.0 or later. If you have an older version, you may need to update ModemManager.

In particular, Raspberry Pi OS (as recent as version 2021-05-07) has not updated its ModemManager package since v1.10.0. However, newer versions of ModemManager are available from the Debian backports repository. To manually install the latest version of ModemManager, first set up your modem using the Automated Installation or Manual Installation instructions below. Then run the following commands to add the Debian backports repository, update the package list, and install a newer version of ModemManager:

echo "deb http://deb.debian.org/debian buster-backports main" | sudo tee -a /etc/apt/sources.list
wget http://deb.debian.org/debian/pool/main/d/debian-archive-keyring/debian-archive-keyring_2021.1.1_all.deb
sudo dpkg -i debian-archive-keyring_2021.1.1_all.deb
sudo apt-get update
sudo apt-get install -t buster-backports modemmanager

Once installed, repeat the mmcli --version command to check that your ModemManager has been updated.

Automated Installation

For your convenience, we provide a simple shell script that automates the process of installing NetworkManager and configuring it for use with Soracom.

This script has been developed for use on Raspberry Pi. While it should work with other Debian-based Linux distributions, there may be some compatibility issues. If the script does not run properly, follow the Manual Installation instructions below instead.

  1. SSH into your device and download the setup script:

    sudo curl -O https://soracom-files.s3.amazonaws.com/connect/setup_eg25.sh
  2. Next, modify the file properties so that it can be executed:

    sudo chmod +x setup_eg25.sh
  3. Run the script and follow the prompts:

    sudo ./setup_eg25.sh

Once the script finishes installation, your device should automatically connect to a cellular network using the Onyx LTE dongle. You can then control the connection by using sudo nmcli con up soracom and sudo nmcli con down soracom commands.

Manual Installation

If you prefer to install NetworkManager separately (such as to integrate it into your own device provisioning script), you can follow these steps to install the Onyx LTE dongle and configure it. The following instructions assume you are using a Debian-based distribution, but can be adapted for other systems.

  1. Install NetworkManager:

    sudo apt-get install network-manager
  2. Insert your Onyx LTE dongle and confirm that it is detected by your device:

    lsusb
    >
    >Bus 001 Device 001: ID 2c7c:0125 Quectel Wireless Solutions Co., Ltd. EC25 LTE modem

    As the EG25-G module is part of Quectel's Ex25 modules, it will appear as "EC25".

  3. Confirm that ModemManager (a part of NetworkManager) has also detected your device:

    mmcli -L
    >
    >    /org/freedesktop/ModemManager1/Modem/0 [QUALCOMM INCORPORATED] QUECTEL Mobile Broadband Module
  4. Add the Soracom APN settings:

    sudo nmcli con add type gsm ifname "*" con-name soracom apn soracom.io user sora password sora

    After a few moments, NetworkManager should establish the cellular connection automatically. You can then control the cellular connection using sudo nmcli con up soracom and sudo nmcli con down soracom commands.

By default, NetworkManager will treat cellular connections with lower priority and continue to route network traffic using WiFi, ethernet, or other network interfaces. To change this behavior, you can modify the soracom connection to create custom routes or change the interface metric:

  1. If you want network traffic for Soracom services (such as Beam, Funnel, Funk, or Harvest) to use the Onyx LTE dongle but all other traffic to use your WiFi or ethernet connection, create a custom route:

    sudo nmcli con modify soracom +ipv4.routes "100.127.0.0/16 0.0.0.0 0, 54.250.252.67/32 0.0.0.0 0, 54.250.252.99/32 0.0.0.0 0"

    If you prefer to route all traffic using the Onyx LTE dongle instead, modify the connection metric directly:

    sudo nmcli con modify soracom ipv4.route-metric 0

    If you configure your device to use the Onyx LTE dongle network interface by default, please note that all traffic will use the cellular connection even if WiFi, ethernet, or other network connections are available. Take care to disable the cellular connection using sudo nmcli con down soracom when installing additional software, performing upgrades, or other high-bandwidth actions.

Using WvDial

When using WvDial, the Onyx LTE dongle's USB serial port will be used to dial the modem, and the resulting connection will be made available as a ppp0 network interface. As the default PPP configuration will not change any routing behavior, you may need to perform additional configuration to other parts of your Linux system described below. The following instructions assume you are using a Debian-based distribution, but can be adapted for other systems.

Manual Installation

  1. Install WvDial:

    sudo apt-get install wvdial
  2. Edit the default WvDial configuration file:

    sudo nano /etc/wvdial.conf
    [Dialer Defaults]
    Modem = /dev/ttyUSB2
    Baud = 460800
    Init1 = AT+CFUN=1
    Init2 = ATZ
    Init3 = AT+CGDCONT=1,"IP","soracom.io"
    Phone = *99***1#
    Dial Command = ATD
    Username = sora
    Password = sora
    Auto DNS = 1
    Check Def Route = 1
    Carrier Check = 0
    Stupid Mode = 1
    Dial Attempts = 3
    ISDN = 0

    By default, the Onyx LTE dongle's USB serial port will be available at /dev/ttyUSB2. If you are connecting other USB serial devices at the same time, this port may change, and you may need to modify this according to the Setting the Modem Port instructions below.

  3. Insert your Onyx LTE dongle and confirm that it is detected by your device:

    lsusb
    >
    >Bus 001 Device 001: ID 2c7c:0125 Quectel Wireless Solutions Co., Ltd. EC25 LTE modem

    As the EG25-G module is part of Quectel's Ex25 modules, it will appear as "EC25".

  4. Run WvDial to verify the connection. If connected, you should see output similar to the following:

    sudo wvdial
    >
    >--> WvDial: Internet dialer version 1.61
    >--> Initializing modem.
    >--> Sending: AT+CFUN=1
    >AT+CFUN=1
    >OK
    >--> Sending: ATZ
    >ATZ
    >OK
    >--> Sending: AT+CGDCONT=1,"IP","soracom.io"
    >AT+CGDCONT=1,"IP","soracom.io"
    >OK
    >--> Modem initialized.
    >--> Sending: ATD*99***1#
    >--> Waiting for carrier.
    >ATD*99***1#
    >CONNECT 150000000
    >--> Carrier detected.  Starting PPP immediately.
    >--> Starting pppd at Wed Jun 17 13:48:20 2020
    >--> Pid of pppd: 123
    >--> Using interface ppp0
    >--> local  IP address 10.123.45.67
    >--> remote IP address 10.64.64.64
    >--> primary   DNS address 100.127.0.53
    >--> secondary DNS address 100.127.1.53

While WvDial is running, you can verify that a ppp0 network interface is now available using the ifconfig command in a separate terminal window.

Routing Traffic

Although WvDial will set up the ppp0 network interface, by default it will not modify any network routing rules. As a result, all network traffic will continue to use WiFi, ethernet, or other network connections. To send data using the cellular connection, you must modify the routes.

  1. To change the routing rules, edit the /etc/ppp/peers/wvdial file to add the following option:

    sudo nano /etc/ppp/peers/wvdial
    replacedefaultroute

With this option, WvDial will replace the default network route (WiFi, ethernet, or other network interface) with the ppp0 interface whenever it is connected. Now when you run sudo wvdial, all network traffic will use the Onyx LTE dongle.

By enabling the replacedefaultroute option, all traffic will use the cellular connection even if WiFi, ethernet, or other network connections are available. Take care to stop WvDial and disable the cellular connection when installing additional software, performing upgrades, or other high-bandwidth actions.

Adding WvDial to ifupdown

As manually running WvDial to start the connection is inconvenient, you can add a network interface definition to the ifupdown system (a standard part of most Linux distributions) to specify that wvdial should be used to configure the interface.

  1. Edit the /etc/network/interfaces file to add the following definition:

    sudo nano /etc/network/interfaces
    allow-hotplug wwan0
    iface wwan0 inet wvdial

This will add a wwan0 interface which will be used to run WvDial in the background, which in turn will create the ppp0 interface when connected. You can then manage the cellular connection using sudo ifup wwan0 and sudo ifdown wwan0 commands.

Setting the Modem Port

By default, the Onyx LTE dongle's USB serial port will be available at /dev/ttyUSB2. However, if you are attaching other USB serial devices, this number may be different, and may also change each time your device is restarted.

To work around this inconsitency, you can use the Udev system within Linux to check if a USB serial device matches the Onyx LTE dongle, and then create a symlink that will always point to the correct port.

  1. Create a new file in the /etc/udev/rules.d/ directory (such as 30-eg25.rules) and add the following rule to the file:

    sudo nano /etc/udev/rules.d/30-eg25.rules
    KERNEL=="ttyUSB*", ATTRS{../idVendor}=="2c7c", ATTRS{../idProduct}=="0125", ATTRS{bNumEndpoints}=="03", ATTRS{bInterfaceNumber}=="02", SYMLINK+="modem", ENV{SYSTEMD_WANTS}="ifup@wwan0.service"
  2. Reload the rules:

    sudo udevadm control --reload-rules
  3. Modify your /etc/wvdial.conf file to use the symlink path instead:

    [Dialer Defaults]
    Modem = /dev/modem
    ...

With this rule configured, whenever a USB device is attached, Udev will check if it matches specific parameters (vendor ID, product ID, and specific port number), then it will perform two actions:

Now whenever you restart your device or plug in other USB devices, the Onyx LTE dongle USB serial interface will always be accessible at /dev/modem, which will allow WvDial to use the correct interface to establish a network connection.


Windows Installation

The Onyx LTE dongle uses a Quectel EG25-G modem internally, which requires installation of the appropriate Quectel drivers as well as cellular network configuration within Windows.

By default, Windows will prioritize ethernet or WiFi connections over cellular connections. In order to send/receive data using the Onyx LTE dongle, you must disconnect or disable any other Internet-connected network interface. Unfortunately, Windows does not provide any built-in method to separate network traffic such that certain traffic uses the cellular connection while other traffic uses ethernet or WiFi interfaces.

  1. Download the Onyx Windows device drivers from the Downloads section.

  2. Extract the zip file, run the installation program, and follow the installation prompts.

    Windows driver installation

  3. Insert your Onyx LTE dongle. You can optionally check that your computer has correctly detected the dongle by right clicking the Start menu, selecting Device Manager, and verifying that Quectel USB Modem appears in the list of devices underneath Modems:

    Windows device manager

  4. Next, click the Start menu, open Settings, then select Network & Internet:

    Windows settings

  5. Click the Cellular network settings tab. The Onyx LTE dongle cellular connection should appear. Change the Data roaming options setting to Roam.

    Cellular settings

    By default, the Let Windows keep my connected option will be enabled, and Windows will automatically connect to a cellular network every time your device is started. You can disable this option if you prefer to manually connect each time.

In newer versions of Windows 10, Windows will automatically detect the correct APN settings so no further setup is required. You should see that your cellular connection is Connected, roaming.

If your Onyx LTE dongle is not connected, you may need to manually configure the APN settings below:

  1. Click the Advanced options link underneath the cellular connection.

    Cellular settings

  2. Scroll to the APN settings section and click the Add an APN button.

    Add an APN

  3. Enter the following APN settings:

    APN settings

    • Profile name - A friendly name to identify the connection, such as Soracom
    • APN - soracom.io
    • User name - sora
    • Password - sora
    • Type of sign-in info - PAP or CHAP
    • IP type - IPv4
    • APN type - Internet

    Then click the Save button.

Now Windows should be able to connect to a cellular network using the Onyx LTE dongle.


Additional Resources

AT Commands

The Onyx LTE dongle provides additional functionality, such as advanced network configuration and built-in application functionality which lets you utilize various protocols (such as TCP, HTTP, MQTT, and more) by simply sending AT commands directly to the modem.

For more information, refer to the AT Command Manual and Application manuals on the Device Drivers page.