General LTE settings and functions [Unipi technology Knowledge Base]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
/* řešeno v tiketech:
  * https://tickets.unipi.technology/agent/unipi/tech-support/tickets/details/10041000007339222 (#3239)
  * https://tickets.unipi.technology/agent/unipi/tech-support/tickets/details/10041000007335292 (#3240)
*/
====== General LTE settings and functions ======

<WRAP group center round box 95%>
{{ :files:img_warning-line_b.png?nolink |}}
<WRAP half column 13%>
{{ :en:hw:08_safety-instructions_pseudo-ISO-7010-info.png?nolink |(i)}}
</WRAP>
<WRAP half column 83%>
Looking for a guide how to get started with LTE on **Mervis IDE**? Please see [[en:sw:01-mervis:lte-configuration-hidden|this tutorial]], otherwise continue here.
</WRAP>
</WRAP>

This manual refers to the LTE series of Patron and Edge units - currently [[https://www.unipi.technology/unipi-patron-s167-lte-p383?categoryId=45|S167]], [[https://www.unipi.technology/unipi-patron-m267-lte-p386?categoryId=46|M267]], [[https://www.unipi.technology/unipi-patron-m567-lte-p388?categoryId=46|M567]], [[https://www.unipi.technology/unipi-edge-e410-2-gb-ram-16-gb-emmc-lte-cat-1-wifi-p743|E410]]*, E412* and [[https://www.unipi.technology/unipi-edge-e413-4-gb-ram-32-gb-emmc-lte-cat-1-wifi-p751|E413]]*.

<WRAP group center round box 95%>
{{ :files:img_warning-line_b.png?nolink |}}
<WRAP half column 13%>
{{ :en:hw:08_safety-instructions_pseudo-ISO-7010-info.png?nolink |(!)}}
</WRAP>
<WRAP half column 83%>
**Note:** \\
*LTE is optional.
</WRAP>
</WRAP>

===== Quick-start guide =====

  - Insert a micro-sim supporting LTE data into the slot
  - Connect to the unit [[en:files:software:tools:putty-hidden?tns|via SSH]] 
  - Check the status of the unipi-lte service using the command: <code>systemctl status unipi-lte</code><code>* unipi-lte.service - LED indication of embedded GSM/3G/LTE module status
    Loaded: loaded (/lib/systemd/system/unipi-lte.service; enabled; vendor preset: enabled)
    Active: active (running) since Thu 2023-07-20 07:57:07 UTC; 9min ago
  Main PID: 393 (python3)
    Tasks: 1 (limit: 796)
    Memory: 16.6M
    CGroup: /system.slice/unipi-lte.service
            `-393 python3 /opt/unipi/tools/unipi-lte.py
</code> <WRAP group center round box 95%>{{ :files:img_warning-line_b.png?nolink |}}<WRAP half column 13%>{{ :en:hw:08_safety-instructions_pseudo-ISO-7010-info.png?nolink |(i)}}</WRAP><WRAP half column 83%>**Note:** \\ If the operator uses the APN value ''internet'' and the SIM card is not protected by a PIN, there is no need to set anything and you can skip following steps.</WRAP></WRAP>
  - Start editing the **lte.conf** file, e.g. with MidnightCommander: <code>sudo mc -e /etc/unipi/lte.conf</code>
  - If the SIM card is PIN protected, set the correct PIN and uncomment the line: <code>pin: 1234 </code>
  - **The APN setting is mandatory** (if this line is missing or commented out, the LTE service is disabled). The correct value is determined by the operator, the default value is ''internet'': <code>apn: "internet" </code> <WRAP group center round box 95%>{{ :files:img_warning-line_b.png?nolink |}}<WRAP half column 13%>{{ :en:hw:08_safety-instructions_pseudo-ISO-7010-info.png?nolink |(i)}}</WRAP><WRAP half column 83%>**Note:** \\ In older lte.conf versions parameter **connection_type** was included in **apn**. If you are using older version without **connection_type** parameter, it is necessary to set the **apn** parameter in the following format: ''apn: "IPV4V6","internet" ''</WRAP></WRAP>
  - Save and exit editing the file and restart the unipi-lte service with the command: <code>sudo systemctl restart unipi-lte</code>


/* <WRAP group center round box 95%>{{ :files:img_warning-line_b.png?nolink |}}<WRAP half column 13%>{{ :en:hw:08_safety-instructions_pseudo-ISO-7010-info.png?nolink |(i)}}</WRAP><WRAP half column 83%>**Note:** \\ If you are using most recent OS images from this website, there is no need to install anything and you can skip steps 3 & 4. If you are using older OS, it is still recommended to at least update the packages.</WRAP></WRAP>
 - Install the **unipi-lte** package:<code>sudo su
apt-get update
apt-get install unipi-lte
systemctl enable unipi-lte 
reboot</code>
*/
----

<WRAP group center round box 95%>
{{ :files:img_warning-line_b.png?nolink |}}
<WRAP half column 13%>
{{ :en:hw:08_safety-instructions_pseudo-ISO-7010-info.png?nolink |(i)}}
</WRAP>
<WRAP half column 83%>
**Note:** \\
Be patient, registration to the mobile network can take several minutes. When registered, NET LED lights up.
</WRAP>
</WRAP>

----

  - During normal operation, "Mobile network" LED indicators SIM, NET, INT should be ON while blinking SIG indicates signal strength. [[#overview_of_the_functions_and_states_of_the_indication_leds|See LED Indicators table]].
  - In case of any problem, we recommend that you check the unipi-lte service log file. The log is described in detail in chapter [[#log_file|Log File]].


===== Overview of the functions and states of the indication LEDs =====
{{page>en:hw:lte_led_description-hidden}}

/* DELETEME
^ LED      ^ OFF       ^ ON          ^ Flashing ^
| SIM    | LTE service (daemon) is not active \\ (disabled or not installed)    | SIM is OK        | Slow - No sim inserted (or SIM corrupted) \\ Fast - wrong PIN |
| NET    | Not registered to LTE network   | Registered to network            | —  |
| SIG    | No signal     | Excellent signal        | Signal quality - faster ∼ better |
| INT    | No WAN access     | Unit online, backup active \\ (or single interface only)   | Slow - connected via the primary WAN interface, backup inactive \\ Fast - connected via backup WAN interface |


<WRAP group center round box 95%>
{{ :files:img_warning-line_b.png?nolink |}}
<WRAP half column 13%>
{{ :en:hw:08_safety-instructions_pseudo-ISO-7010-info.png?nolink |(i)}}
</WRAP>
<WRAP half column 83%>
**Note:** \\
All LEDs flashing — LTE module is restarting.
</WRAP>
</WRAP>
*/

/* NEMĚNIT NÁZEV, JE POUŽITO JAKO KOTVA na Eshpou */
===== Updating LTE service =====

/* DELETEME
<WRAP group center round box 95%>
{{ :files:img_warning-line_b.png?nolink |}}
<WRAP half column 13%>
{{ :en:hw:09_safety-instructions_pseudo-ISO-7010-attention.png?nolink |(!)}}
</WRAP>
<WRAP half column 83%>
**Attention:** \\
The updated LTE packages are available only for Debian 12!
</WRAP>
</WRAP>

All available OS images in stable versions (at least Mervis OS version 2.6.5.38 or Base/Node-RED OS version 12.20250617.0) on this site already contain all necessary LTE packages.
If you are flashing OS images to Patron FID 2.0 from backup created on FID 1.x, it is necessary to update the LTE packages on the backup first. The packages can be updated as follows:
*/

Service and related packages can be updated by:
  - Connect to the unit [[en:files:software:tools:putty-hidden?tns|via SSH]] 
  - Obtain a refreshed list of available packages: <code>sudo apt update</code>
  - The LTE service can be installed or updated with: <code>sudo apt install unipi-kernel unipi-os-configurator unipi-os-configurator-data unipi-lte</code>


<WRAP group center round box 95%>
{{ :files:img_warning-line_b.png?nolink |}}
<WRAP half column 13%>
{{ :en:hw:08_safety-instructions_pseudo-ISO-7010-info.png?nolink |(!)}}
</WRAP>
<WRAP half column 83%>
**Note:** \\
To flash an old OS image or backup of OS to Patron unit with LTE in revision FID 2.0+, it is necessary that it includes LTE package in version 0.64 or newer and it's dependencies in compatible versions.
We recommend to update the packages on Patron in revision FID 1.x and then create a backup of OS with updated packages, which can be flashed on the newer Patron units. \\
Package version can be displayed with:
<code>dpkg -s unipi-lte | grep Version</code>
/* zjištění verze OS: cat /usr/share/unipi-info/unipi_image_version */
</WRAP>
</WRAP>

===== Useful hints =====

  * for optimal signal strength **it is necessary to use an external antenna** installed in an open area (eg. outside any enclosures). For some Unipi units external antenna is included in the package /* of each LTE controller */ - during the purchase, you can choose between the default antenna with magnetic mount or a larger one with on-wall mount. Both antennas can be also [[https://www.unipi.technology/others-c42|purchased separately]].
  * By default, Ethernet is set as the primary network interface and LTE as the backup interface. Changing the primary interface is possible in the [[#ping|configuration file in the PING]] section.
  * WAN connection availability is determined by ping to 8.8.8.8. The IP address and ping interval can be set in the [[#ping|configuration file in the PING]] section.


===== Detailed information =====

==== Configuration File ====

The **lte.conf** configuration file is available in the **/etc/unipi/** directory. Editing the file is possible e.g. with MidnightCommander: <code>mc -e /etc/unipi/lte.conf</code>

This file is divided into three sections, some settings ([[#autokeepon_feature|auto_keepon]], [[#autoswitch_feature|autoswitch]], [[#log_file|Log File]]) are described in detail in separate chapters.


=== MAIN ===

<WRAP group center round box 95%>{{ :files:img_warning-line_b.png?nolink |}}<WRAP half column 13%>{{ :en:hw:08_safety-instructions_pseudo-ISO-7010-info.png?nolink |(i)}}</WRAP><WRAP half column 83%>**Note:** \\ In older lte.conf versions parameter **connection_type** was included in **apn**. If you are using older version without **connection_type** parameter, it is necessary to set the **apn** parameter in the following format: ''apn: "IPV4V6","internet" ''</WRAP></WRAP>

/*
<code>
pin: 1234 
apn: "internet"
connection_type: IPV4V6
auth_method: 0 
auth_user: 
auth_pass: 
usbmode: 2 
oneshot: false 
reg_timeout: 120 
suspend_timeout: 43200
report_period: 86400
auto_keepon: true
</code>
*/

  * **pin**: if the SIM is protected by PIN code it is necessary to enter it here, if the SIM is not protected by PIN code just comment the line (with semicolon ";")
  * **apn**: Access Point Name **;** the default value is the ''internet'', this value can be different and is determined by the operator
  * **connection_type**: protocol type **;** specifies the type of data protocol, possible values are IP, IPV4V6 or IPV6
  * **auth_user**: user name ; if authentication is required
  * **auth_pass**: user password ; if authentication is required
  * **oneshot**: performs only the initialization and then exits 
  * **reg_timeout**: the time in seconds that the modem attempts to register with the operator's network
  * **suspend_timeout**: delay between modem re-initializations, if an error occurs (default: 34200 seconds, i.e. 12 hours)
  * **report_period**: frequency with which the periodic report is written to the log (default: 86400 seconds, i.e. 24 hours)
  * **auto_keepon**: if an accidental disconnection occurs and is set to true, the connection is automatically restored ; this parameter is detailed in the [[#autokeepon_feature|auto_keepon]] chapter

The **auth_method** and **usbmode** parameters are not used and are present only for backward compatibility.


=== LOG ===

Logs are stored in the log file for debugging and possible troubleshooting. For a detailed description of the log file, see the [[#log_file|Log File]] chapter.

/*
<code>
path: /var/log/unipilte.log
severity: info
logfile_size: 131072
</code>
*/

  * **path**: location of the log file **;** if not defined, messages will be written to the syslog
  * **severity**: severity of the message to be logged
  * **logfile_size**: log file size


=== PING ===

/*
<code>
active: True
primary_iface: eth0 
fail_threshold: 3 
ip_eth: 8.8.8.8
ip_lte: 8.8.8.8 
period: 4
timeout: 2 
packetsize: 2 
autoswitch: true
</code>
*/

  * **active**: enable periodic ping retries to the configured addresses 
  * **primary_iface**: primary network interface
  * **fail_threshold**: the number of times a connection is attempted before the device switches to the backup network interface
  * **ip_eth**: the address that the daemon is trying to ping over the ethernet network interface (**eth0**)
  * **ip_lte**: the address that the daemon is trying to ping over the **lte** network interface (**wwan0**)
  * **period**: time between contact attempts, 0 → 10s, 1 → 20s, 3 → 40s, etc. ; in 10s increments
  * **timeout**: time to wait for a response in seconds
  * **packetsize**: size of the ping sent in packets
  * **autoswitch**: enable/disable the autoswitch feature, set **true** to enable, **false** to disable, see [[#autoswitch_feature|Autoswitch feature]] for details


==== Autoswitch feature ====

When Autoswitch feature is enabled (default state), service **unipi-lte** automatically selects the default network gateway based on WAN availability on the primary/backup network interface. By default, the primary network interface is fixed Ethernet (eth0) and the LTE interface is the backup connection. The Linux routing table must always contain the default routing for both interfaces. If there is a need to switch between the primary and backup interfaces, the unipi-lte service will automatically increase/decrease the LTE interface metric. 

/*
In order to switch between the primary and backup interfaces, it is necessary that **the metric values of all network interfaces are non-zero positive values**. \\
*/

  * __IP address from the DHCP server:__ There is no need to set anything, as the (non-zero) metric is set by the DHCP client.

  * __Static IP address:__ You must always set a non-zero metric value manually, as the default static routing is set to ''metric 0''. The static configuration can be configured via [[https://wiki.debian.org/SystemdNetworkd|systemd-networkd]]. 

The **Autoswitch** feature can be disabled in the [[#ping|configuration file in the PING]] section of the unipi-lte service. Feature is turned on/off by setting the values **true/false**.


==== Autokeepon feature ====

The auto_keepon feature is also available, which automatically enables the LTE network interface when it is accidentally disabled (e.g. by an ifdown command). In this case, the feature re-enables the interface (ifup) and updates the routing table entries. The feature is enabled by default and can be disabled in the [[#main|configuration file in the MAIN]] section.


==== Log File ====

The log file is invaluable for debugging. By default, all relevant logs from unipi-lte are stored in syslog. /* ''/var/log/unipilte.log''. */ The location and severity of the logs can be set in the [[#log|configuration file in the LOG]] section.

<html><span class="kbBlueText">Example of log file</span></html>

<code>
2023-07-25 08:33:00,047 - INFO - unipi-lte version 0.36 from 2023-03-14 10:19:01 - Logging started..
2023-07-25 08:33:00,052 - INFO - Running on Patron series, model: S167
2023-07-25 08:33:01,067 - INFO - Created/corrected wwan0 iface file
2023-07-25 08:33:02,143 - ERROR - Incorrect or undefined password (PIN). Going to sleep...
2023-07-25 08:33:02,144 - WARNING - Daemon halted forever...must be restarted manually 3
2023-07-25 08:36:06,945 - INFO - Exiting after received signal 15
2023-07-25 08:36:18,065 - INFO - unipi-lte version 0.36 from 2023-03-14 10:19:01 - Logging started..
2023-07-25 08:36:18,071 - INFO - Running on Patron series, model: S167
2023-07-25 08:36:19,084 - INFO - Created/corrected wwan0 iface file
2023-07-25 08:36:20,597 - INFO - Pin resolved
2023-07-25 08:36:36,942 - INFO - Modem init complete
2023-07-25 08:36:37,546 - INFO - Registered to: O2.CZ Network type: 7 RSSI: 31 Sigqual: 99
2023-07-25 08:36:40,562 - INFO - WAN IP ADDRESS: 100.71.129.7 INTERFACE IP ADDRESS: 100.71.129.7
2023-07-26 08:36:18,370 - INFO - RSSI: (MIN 21, MAX 31, AVG 25), SIGQUAL: 99, NET-TYPES: ['7'], USED_MODES: {6} PING_COUNT: 1727 PING_SUCCESS_RATIO: 99.94
2023-07-26 21:55:06,956 - INFO - Ping failure threshold reached 3 on main eth0.Switching to backup wwan0...
2023-07-26 22:06:48,490 - WARNING - Routing table metric mismatch A (changed by other application?), re-setting... 203 202
2023-07-26 22:21:49,183 - WARNING - Routing table metric mismatch A (changed by other application?), re-setting... 203 202
2023-07-26 22:36:47,974 - WARNING - Routing table metric mismatch A (changed by other application?), re-setting... 203 202
2023-07-26 22:47:38,255 - INFO - Main interface eth0 becomes available, switching to it
2023-07-27 08:36:25,783 - INFO - RSSI: (MIN 17, MAX 31, AVG 23), SIGQUAL: 99, NET-TYPES: ['7'], USED_MODES: {4, 6} PING_COUNT: 1727 PING_SUCCESS_RATIO: 99.36
2023-07-28 08:36:33,574 - INFO - RSSI: (MIN 18, MAX 31, AVG 24), SIGQUAL: 99, NET-TYPES: ['7'], USED_MODES: {6} PING_COUNT: 1726 PING_SUCCESS_RATIO: 99.94
2023-07-29 08:36:41,673 - INFO - RSSI: (MIN 21, MAX 31, AVG 24), SIGQUAL: 99, NET-TYPES: ['7'], USED_MODES: {6} PING_COUNT: 1727 PING_SUCCESS_RATIO: 100.00
2023-07-30 08:36:49,334 - INFO - RSSI: (MIN 21, MAX 31, AVG 24), SIGQUAL: 99, NET-TYPES: ['7'], USED_MODES: {6} PING_COUNT: 1727 PING_SUCCESS_RATIO: 99.94
2023-07-31 08:36:57,165 - INFO - RSSI: (MIN 17, MAX 31, AVG 24), SIGQUAL: 99, NET-TYPES: ['7'], USED_MODES: {6} PING_COUNT: 1727 PING_SUCCESS_RATIO: 99.83
</code>

----

  * **2023-07-25 08:33:00**: Initialization and start of connection
  * **2023-07-25 08:33:02**: Error caused by wrong PIN
  * **2023-07-25 08:36:20**: Correct PIN code entered
  * **2023-07-25 08:36:40**: Connection to LTE network successfully established
  * **2023-07-25 21:55:06**: eth0 network failure, Unipi device switching to backup LTE connection
  * **2023-07-25 22:47:38**: eth0 network available again
  * **2023-07-2x 08:36:xx**: Periodic report, the frequency of the report can be set with the **report_period** parameter in the [[#main|configuration file in the MAIN]] section.


===== Advanced options =====

==== Disabling/Enabling NAT for LTE modem ====
/* DELETEME
<WRAP group center round box 95%>
{{ :files:img_warning-line_b.png?nolink |}}
<WRAP half column 13%>
{{ :en:hw:09_safety-instructions_pseudo-ISO-7010-attention.png?nolink |(!)}}
</WRAP>
<WRAP half column 83%>
**Attention:** \\
In Patron FID 1.x, the AT command for disabling NAT is as follows: \\
To disable NAT: AT+QCFG="nat",1\\ 
To enable NAT: AT+QCFG="nat",0
</WRAP>
</WRAP>
*/
By default, NAT is enabled. To turn it off/on, you need to send a specific AT command to the modem via the virtual serial line:

  - communication is possible via the virtual serial line ** /run/unipi-plc/by-sys/lte.1/tty_at1 ** (e.g. by the minicom): <code>minicom -D /run/unipi-plc/by-sys/lte.1/tty_at1</code> 
  - then you need to send the string, depending on the modem variant (see AT commands of the relevant Unipi unit):
    - for the modems - **EG912Y-EU**, **EC200U-EUAB** and **EC200U-EUAP**: <code>AT+QCFG="nat",X</code> <WRAP group center round box 95%>{{ :files:img_warning-line_b.png?nolink |}}<WRAP half column 13%>{{ :en:hw:08_safety-instructions_pseudo-ISO-7010-info.png?nolink |(!)}}</WRAP><WRAP half column 83%>**Note:** \\ To disable NAT it is necessary to set parameter **1** instead of **X**, or parameter **0** to enable it.</WRAP></WRAP>
    - for the modems - **EG915U-EU** and **EC200A-EUAH**: <code>AT+QCFG="nat/cid",0xYY </code> <WRAP group center round box 95%>{{ :files:img_warning-line_b.png?nolink |}}<WRAP half column 13%>{{ :en:hw:08_safety-instructions_pseudo-ISO-7010-info.png?nolink |(!)}}</WRAP><WRAP half column 83%>**Note:** \\ To disable NAT it is necessary to set parameter **00** instead of **YY**, or parameter **7F** to enable it.</WRAP></WRAP>

/* DELETEME
  - communication is possible via the virtual serial line ** /run/unipi-plc/by-sys/lte.1/tty_at1** (e.g. by the minicom): <code>minicom -D /run/unipi-plc/by-sys/lte.1/tty_at1</code>
  - then you need to send the string: <code>AT+QCFG="nat/cid",0xYYX</code> 

<WRAP group center round box 95%>
{{ :files:img_warning-line_b.png?nolink |}}
<WRAP half column 13%>
{{ :en:hw:08_safety-instructions_pseudo-ISO-7010-info.png?nolink |(i)}}
</WRAP>
<WRAP half column 83%>
**Note:** \\
To disable NAT it is necessary to set parameter **00** instead of **YY**, or parameter **7F** to enable it.
</WRAP>
</WRAP>
*/

After sending the command and exiting the minicom program, it is **necessary to restart the modem** for the settings to take effect. Restart is possible e.g. by unplugging/plugging the power supply of the controller /*, or by restarting the **unipi-lte** service*/.

----

**Note:** The string (AT command) must be entered in the exact format, including case sensitivity. A proven method is, for example, to copy the entire AT command string and then paste it into the terminal window running minicom.

**Note on minicom:** To exit the minicom, press the CTRL+A key combination, followed by the Q key, which brings up a dialog where you still need to confirm the exit.

==== I want PPP instead of unipi-lte ====
If you are using PPP for your application and therefore do not want a unipi-lte solution, we also recommend that you disable unipi-lte and remove the network interface definition. 

  - Permanently disable the unipi-lte service by: <code>
sudo systemctl stop unipi-lte
sudo systemctl disable unipi-lte
</code>
  - Delete the LTE interface in **/etc/systemd/network/** and restart the systemd-networkd service.

===== Configuration of GNSS =====
<WRAP group center round box 95%>
{{ :files:img_warning-line_b.png?nolink |}}
<WRAP half column 13%>
{{ :en:hw:09_safety-instructions_pseudo-ISO-7010-attention.png?nolink |(!)}}
</WRAP>
<WRAP half column 83%>
**Attention:** \\
This section refers only to Unipi units equipped with GNSS capable modem. 
/* Compatible modems: EG200U-EUAP */
/* See [[..:#part_number_description|overview]] for more details. */
</WRAP>
</WRAP>

All GNSS AT commands and mapping of GNSS virtual serial line can be found in port mapping of the relevant Unipi unit.
The antenna for the GNSS must be connected to the LTE DIV connector.

Configuration of GNSS can be done via virtual serial line **tty_at1** similar to [[#disabling_enabling_nat_for_lte_modem| NAT configuration]]. Only difference is used AT commands:
  * Set active antenna mode: <code>AT+QGPSPOWER=1</code>
  * Set passive antenna mode: <code>AT+QGPSPOWER=0</code>
  * Configure GNSS <code>AT+QGPSCFG="setting",value</code> for available settings see {{en:hw:004-edge:ec200-gnss-manual.pdf|AT commands documentation}}.
  * Turning on GNSS: <code>AT+QGPS=1</code>
  * Turning off GNSS: <code>AT+QGPSEND=1</code>
  * Read positional data: <code>AT+QGPSLOC=2</code> <WRAP group center round box 95%>
{{ :files:img_warning-line_b.png?nolink |}}
<WRAP half column 13%>
{{ :en:hw:08_safety-instructions_pseudo-ISO-7010-info.png?nolink |(!)}}
</WRAP>
<WRAP half column 83%>
**Note:** \\
 Before reading the position for the first time after enabling the GNSS it is necessary to wait for position solution fix. That process of GNSS module can take up to 20 minutes and until its not finished the command will return error code 516.
</WRAP>
</WRAP>