.. _cellular-connection:

Setting up a Cellular Connection
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Prerequisites
""""""""""""""""""""

* Network configuration from your operator (APN, SIM PIN, credentials).
* Administrative privileges on the gateway.
* Console access to the gateway (monitor/keyboard/mouse, SSH, or serial).
* Connected cellular antennas.

Steps
""""""""""

1. Log in as root:

   .. code:: console

       $ sudo su

2. Identify the modem interface (e.g., ``cdc-wdm0`` for RM500Q):

   .. code:: console

       $ mmcli -L
       /org/freedesktop/ModemManager1/Modem/0 [Quectel] RM500Q-GL

3. Create a NetworkManager connection (replace ``my_cell_conn`` and ``cdc-wdm0`` as needed):

   .. code:: console

       $ nmcli con add type gsm con-name my_cell_conn ifname cdc-wdm0

4. Configure APN (if required):

   .. code:: console

       $ nmcli con modify my_cell_conn gsm.apn xxxx


5. Configure SIM PIN (if required):

   .. code:: console

       $ nmcli con modify my_cell_conn gsm.pin xxxx

6. Configure username (if required):

   .. code:: console

       $ nmcli con modify my_cell_conn gsm.username xxxx

7. Configure password (if required):

   .. code:: console

       $ nmcli con modify my_cell_conn gsm.password xxxx

8. Set route metric (optional):

   .. code:: console

       $ nmcli con modify my_cell_conn ipv4.route-metric 1

9. Enable NetworkManager and ModemManager on boot:

   .. code:: console

       $ systemctl enable NetworkManager && systemctl enable ModemManager

10. Reboot:

    .. code:: console

       $ reboot

11. Verify the connection:

    .. code:: console

       $ nmcli dev status


Troubleshooting
""""""""""""""""""""

If connectivity issues persist despite correct APN and SIM PIN:

1. Log in as root:

   .. code:: console

       $ sudo su

2. Stop NetworkManager and ModemManager:

   .. code:: console

       $ systemctl stop NetworkManager && systemctl stop ModemManager

3. Identify the modem interface (e.g., ``wwan0`` for RM500Q):

   .. code:: console

       $ mmcli -L   
       /org/freedesktop/ModemManager1/Modem/0 [Quectel] RM500Q-GL

4. Obtain and prepare the ``ivecm`` tool (contact us for details):

   .. code:: console

       $ cd ~ && chmod +x ivecm

5. Attempt connection using ``ivecm`` (replace placeholders):

   .. code:: console

       $ ./ivecm -s <apn> -p <simpin> -i wwan0

6. If successful, configure with ``nmcli`` and reboot:

   .. code:: console

       $ reboot

7. Verify connection:

   .. code:: console

       $ nmcli dev status

8. Check modem status (replace identifier):

   .. code:: console

       $ mmcli -m 0

9. If issues persist, try upgrading the modem firmware or contact us.



Advanced
""""""""""

To connect without rebooting

.. code:: console

    $ nmcli dev connect cdc-wdm0

For advanced NetworkManager usage, see the `Arch Linux <https://wiki.archlinux.org/title/NetworkManager>`_ and `Debian <https://wiki.debian.org/NetworkManager>`_ documentation.


For detailed modem operations, use ModemManager

1. Find the modem identifier

   .. code:: console

       $ mmcli ls

2. Request modem information
   
   .. code:: console

       $ mmcli -m 0

Use ``mmcli --help`` for more details. ``qmicli`` is available for low-level QMI communication. Stop ModemManager (``systemctl stop ModemManager``) before using ``qmicli``.


For AT command communication:

1. Find the modem identifier (see above).

2. Request modem information (see above).

3. *(Optional)* Disable ModemManager temporarily (``systemctl disable ModemManager``) and reboot. Re-enable later (``systemctl enable ModemManager && systemctl start ModemManager``).

4. Establish a serial connection (replace ``/dev/ttyX``)

.. code:: console
    
    $ picocom -b 115200 /dev/ttyX



Additional Resources
""""""""""""""""""""""""""""""

* `NetworkManager Arch documentation <https://wiki.archlinux.org/title/NetworkManager>`_
* `NetworkManager Debian documentation <https://wiki.debian.org/NetworkManager>`_
* `Toradex ModemManager documentation <https://developer.toradex.com/software/connectivity/modem-support/>`_
* `mmcli Linux man page <https://www.systutorials.com/docs/linux/man/8-mmcli/>`_
* `libqmi basic tutorial <https://docs.sixfab.com/page/setting-up-a-data-connection-over-qmi-interface-using-libqmi>`_