# Software Setup

Configure Linux networking for the Soracom Onyx modem.

The Soracom Onyx LTE™ USB Modem uses a Quectel EG25-G modem internally, which is natively supported in Linux kernel versions 2.6 and above. Due to this, no additional driver installation is required; however, you must configure an application to establish and manage the cellular connection.

While many applications 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 modem automatically and can be easily configured for a variety of use cases. If you prefer to use a more traditional PPP connection or if NetworkManager is not available for your specific Linux distribution (such as with embedded gateways or routers), you can use WvDial instead.

## Using NetworkManager

When using NetworkManager, the Onyx modem is fully managed, enabling automatic internet connections without manual dialing. It's widely used across Linux distributions for handling network configurations, including mobile broadband.

> [!NOTE]
>
> Note that the `setup_eg25.sh` script automatically enables and starts NetworkManager when executed. This behavior is intended to address the configuration of Raspberry Pi OS (Bullseye), where NetworkManager is pre-installed but disabled by default.
>
> If you are running this script on a device with Bullseye installed, you may notice changes in the behavior of your network adapters after the script is executed.
>
> For newer versions of Raspberry Pi OS released after Bullseye, NetworkManager is pre-installed and enabled by default.

**Automated Installation**

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

> [!WARNING]
>
> This script has been developed and tested for use on a 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, consider reviewing the logs below for warnings or errors:
>
> - `/var/log/soracom_setup.log`
> - `/var/log/soracom_status.log`
>
> If you continue to experience issues with the automated script, we recommend following the **Manual Installation** instructions included below instead.

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

   ```bash
   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:

   ```bash
   sudo chmod +x setup_eg25.sh
   ```

3. Run the script and follow the prompts:

   ```bash
   sudo ./setup_eg25.sh
   ```

> [!WARNING]
>
> For headless setups or automated provisioning, you can run the script with the `-H` flag to skip interactive prompts:
>
> ```bash
> sudo ./setup_eg25.sh -H
> ```
>
> This allows the script to set up the network configuration without needing to insert the Soracom Onyx LTE USB Modem during the setup process, making it suitable for automated deployments.

Once the script finishes installing, your device should automatically connect to an available cellular network using the Onyx modem. 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, for example, to integrate it into your device provisioning script, you can follow these steps to install NetworkManager and configure it with the Onyx modem. The following instructions assume you are using a Debian-based distribution, but can be adapted for other systems.

1. Install NetworkManager:

   ```bash
   sudo apt-get install network-manager
   ```

2. Insert your Onyx modem and confirm that it is detected by your device:

   ```bash
   lsusb

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

> [!WARNING]
>
> 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:

   ```bash
   mmcli -L

   /org/freedesktop/ModemManager1/Modem/0 [QUALCOMM INCORPORATED] QUECTEL Mobile Broadband Module
   ```

4. Add the Soracom APN settings:

   ```bash
   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:

5. If you want network traffic for Soracom services (such as Beam, Funnel, Funk, and Harvest Data/Files) to use the Onyx modem but all other traffic on WiFi or ethernet connection, create a custom route:

   ```bash
   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 modem instead, modify the connection metric directly:

   ```bash
   sudo nmcli con modify soracom ipv4.route-metric 0
   ```

> [!NOTE]
>
> If you configure your device to use the Onyx modem's network interface by default, 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 modem'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 make additional configuration changes to other parts of your Linux system as 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:

   ```bash
   sudo apt-get install wvdial
   ```

2. Edit the default WvDial configuration file:

   ```bash
   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
   ```

> [!WARNING]
>
> By default, the Onyx modem'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 modem and confirm that it is detected by your device:

   ```bash
   lsusb

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

> [!WARNING]
>
> 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:

   ```bash
   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 Fri Mar 1 13:48:20 2024
   --> 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.

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

   ```bash
   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 modem.

> [!NOTE]
>
> 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 carrying out 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:

   ```bash
   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 modem'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 inconsistency, you can use the Udev system within Linux to check if a USB serial device matches the Onyx modem, 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:

   ```bash
   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:

   ```bash
   sudo udevadm control --reload-rules
   ```

3. Modify your `/etc/wvdial.conf` file to use the symlink path instead:

   ```bash
   sudo nano /etc/wvdial.conf

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

With this rule configured when 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:

- Add a symlink `/dev/modem` which points to the detected port
- Run `ifup wwan0` as a service

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