Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents

Design

If nodes support cellular uplink connectivityNodes with cellular capability, OpenSync allows using the LTE connection as a failover backup mechanism in cases of WAN link outages (L2 or L3).

LTE Manager

OpenSync LTE Manager (LTEM) will initialize or configure the LTE modem, data call creation and monitoring the health of the LTE interface. It is also responsible for switching traffic from WAN to LTE when detecting an outage. LTEM also monitors WAN and switches back when the WAN interface is back up. LTEM needs to be flexible enough to allow all or some devices to use LTE as configured.

General use cases are:

...

All devices use the LTE interface when there is a WAN outage. The scenarios vary from a link down state on the WAN interface to all/some L2/L3 traffic is dropped upstream in the network.

...

Some devices are allowed to use the LTE interface and some are excluded when the WAN link goes down.

  • Some devices may be considered 'essential' and they must always have connectivity.

  • Other devices are not considered 'essential' and the loss of connectivity does not have adverse affects. 

Some devices always use the LTE interface.

...

There could be circumstances where a device would need uninterrupted connectivity.

...

:

  • Monitoring WAN interface health to detect L2 and L3 WAN failures

  • Report WAN outages via MQTT

  • Force LTE use when configured

  • Gathering and reporting LTE modem statistics (cell network state, signal strength, etc)

Panel
panelIconIdatlassian-info
panelIcon:info:
bgColor#EAE6FF

With OpenSync 3.4, support for LTE Primary or LTE Only is not available, but is planned for future releases.

Implementation

LTEM needs to be enabled by kconfig option (MANAGER_LTEM) as part of OpenSync building process since is disabled by default. It will register to OVSDB and brigng up the LTE interface based on OVSDB entry in Wifi_Inet_Config. LTEM will add the LTE interface to the Connection_Manager_Uplink table and set has_l2 and has_l3 to true, if the LTE interface has successfully connected to the LTE network. The LTEM will monitor the LTE link for L2 and L3 state and update the Connection_Manager_Uplink table as needed.

Connection Manager (CM) will be responsible for detecting L3 outages on the WAN/uplink interface(s). The LTE manager will report the switchover to the cloud via MQTT the WAN interface loses L2 or L3. In the background, CM will periodically check reachability over the WAN interface. If the WAN interface (like ethernet backhaul) is back 'up', CM will update the Wifi_Route_Config table. This will trigger LTEM to report this to the cloud via MQTT.

Panel
panelIconIdatlassian-info
panelIcon:info:
bgColor#EAE6FF

With OpenSync 3.4, support for LTE Primary or LTE Only is not available, but is planned for future releases.

LTEM is also responsible for creating and maintaining the routing tables associated with the WAN and LTE interfaces. All (or some) packets are marked to use either WAN or LTE routing table during a WAN outage.

LTE Modem Control

Using the AT commands, information items such as connect, disconnect, query connected network name, query signal strength, query EID of SIM/eSIM, and similar can be extracted. 

Implementation

LTEM adds the LTE interface to the Connection_Manager_Uplink table, and sets has_l2 and has_l3 to true if the LTE interface has successfully connected to the LTE network. LTEM monitors the LTE link for L2 and L3 state, and updates the Connection_Manager_Uplink table as needed.

A new 'reachability' timer has been added to the Connectivity Manager (CM2) config. CM2 is responsible for detecting outages on the WAN/uplink interface(s) and for updating the is_used value for the LTE interface in case of a WAN link reachability failure.

LTEM executes the switchover to LTE when the is_used field for LTE is set to true. Once the switchover is triggered, LTEM updates the IP rules to direct traffic to the LTE interface. In the background, CM2 periodically checks for reachability over the WAN interface. If the WAN interface is back up, CM2 sets the is_used field for LTE to false. This triggers LTEM to update the IP rules to direct the traffic back to the WAN interface.

Init is the procedure that occurs when the device loses the wired uplink. These steps are triggered:

  1. OVSDB registration

  2. LTE interface bringup

  3. DHCP for LTE

  4. Route table creation for forwarding over LTE

Reenabling the Wired Uplink – Failover

Failover is the procedure that occurs when the device regains access via the wired uplink. These steps are triggered:

  1. OVSDB notification

  2. Client route updates

  3. NAT (V4 only)

  4. Switching back to WAN

Northbound API

OVSDB Schema: Lte_Config Table

Code Block
$ ovsh s Lte_Config
------------------------------------
_uuid                 | d6ae~8b1f  |
_version              | 0299~ca76  |
active_simcard_slot   | 0          |
apn                   | data641003 |
enable_persist        | false      |
esim_activation_code  | ["set",[]] |
esim_download_start   | false      |
esim_profile_activate | false      |
force_use_lte         | false      |
if_name               | wwan0      |
ipv4_enable           | true       |
ipv6_enable           | true       |
lte_bands_enable      | ["set",[]] |
lte_failover_enable   | true       |
manager_enable        | true       |
modem_enable          | true       |
os_persist            | false      |
pdp_context_id        | ["set",[]] |
report_interval       | 60         |
------------------------------------

OVSDB Schema: Lte_State Table

Code Block
$ ovsh s Lte_State
-----------------------------------------------------
_uuid                     | ac94~71f3               |
_version                  | 8fb0~8982               |
active_simcard_slot       | 0                       |
apn                       | data641003              |
enable_persist            | false                   |
esim_activation_code      | ["set",[]]              |
esim_active_profile       | ["set",[]]              |
esim_download_complete    | false                   |
esim_download_in_progress | false                   |
esim_download_start       | false                   |
esim_profile_activate     | false                   |
force_use_lte             | false                   |
iccid                     | xxxxxxx3278753831737    |
if_name                   | wwan0                   |
imei                      | xxxxxx040285999         |
imsi                      | xxxxxx875383173         |
ipv4_enable               | true                    |
ipv6_enable               | true                    |
lte_bands_enable          |                         |
lte_failover_enable       | true                    |
lte_net_mode              | lte                     |
lte_net_state             | registered_home_network |
manager_enable            | true                    |
mcc                       | 310                     |
mnc                       | 410                     |
modem_enable              | true                    |
modem_firmware_version    | ["set",[]]              |
modem_present             | true                    |
pdp_context_id            | ["set",[]]              |
report_interval           | 60                      |
service_provider_name     | "ISP Name"              |
sim_status                | Inserted                |
tac                       | 8                       |
-----------------------------------------------------

MQTT

Protobuf definition:

Code Block
syntax = "proto3";

package interfaces.lte_info;

// LTE common fields
message LteCommonHeader {
  uint32 request_id = 1;
  string if_name = 2; // wwan0
  string node_id = 3;
  string location_id = 4;
  string imei = 5;
  string imsi = 6;
  string iccid = 7;
  uint64 reported_at = 8; // Unix time in seconds
}

// Network Registration Status
enum LteNetRegStatus {
  LTE_NET_REG_STAT_UNSPECIFIED = 0;
  LTE_NET_REG_STAT_NOTREG = 1; // Not registered. ME is not currently searching a new operator to register to
  LTE_NET_REG_STAT_REG = 2; // Registered, home network
  LTE_NET_REG_STAT_SEARCH = 3; // Not registered, but ME is currently searching a new operator to register to
  LTE_NET_REG_STAT_DENIED = 4; // Registration denied
  LTE_NET_REG_STAT_UNKNOWN = 5; // Unknown
  LTE_NET_REG_STAT_ROAMING = 6; // Registered, roaming
}

// SIM type (eSIM, physical SIM)
enum LteSimType {
  LTE_SIM_TYPE_UNSPECIFIED = 0; // No SIM present
  LTE_SIM_TYPE_ESIM = 1;
  LTE_SIM_TYPE_PSIM = 2; // Physical SIM card
}

// SIM Status (Inserted, Removed, Unknown)
enum LteSimStatus {
  LTE_SIM_STATUS_UNSPECIFIED = 0;
  LTE_SIM_STATUS_INSERTED = 1;
  LTE_SIM_STATUS_REMOVED = 2;
  LTE_SIM_STATUS_BAD = 3;
}

message LteNetInfo {
  LteNetRegStatus net_status = 1;
  uint32 mcc = 2;
  uint32 mnc = 3;
  uint32 tac = 4;
  string service_provider = 5;
  LteSimType sim_type = 6;
  LteSimStatus sim_status = 7;
  uint32 active_sim_slot = 8;
  int32 rssi = 9;
  int32 ber = 10;
}

// LTE data usage
message LteDataUsage {
  uint64 rx_bytes = 1;
  uint64 tx_bytes = 2;
  uint64 failover_start = 3; // Unix time in seconds
  uint64 failover_end = 4; // Unix time in seconds
  uint32 failover_count = 5;
}

// Serving Cell State
enum LteServingCellState {
  LTE_SERVING_CELL_UNSPECIFIED = 0;
  LTE_SERVING_CELL_SEARCH = 1; // UE is searching but could not (yet) find a suitable 3G/4G cell.
  LTE_SERVING_CELL_LIMSERV = 2; // UE is camping on a cell but has not registered on the network.
  LTE_SERVING_CELL_NOCONN = 3; // UE is camping on a cell and has registered on the network, and it is in idle mode.
  LTE_SERVING_CELL_CONNECT = 4; // UE is camping on a cell and has registered on the network, and a call is in progress.
}

// cell mode
enum LteCellMode {
  LTE_CELL_MODE_UNSPECIFIED = 0;
  LTE_CELL_MODE_LTE = 1;
  LTE_CELL_MODE_WCDMA = 2;
}

// is_tdd
enum LteFddTddMode {
  LTE_MODE_UNSPECIFIED = 0;
  LTE_MODE_FDD = 1;
  LTE_MODE_TDD = 2;
}

// Uplink/Downlink Bandwidth in MHz
enum LteBandwidth {
  LTE_BANDWIDTH_UNSPECIFIED = 0;
  LTE_BANDWIDTH_1P4_MHZ = 1;
  LTE_BANDWIDTH_3_MHZ = 2;
  LTE_BANDWIDTH_5_MHZ = 3;
  LTE_BANDWIDTH_10_MHZ = 4;
  LTE_BANDWIDTH_15_MHZ = 5;
  LTE_BANDWIDTH_20_MHZ = 6;
}

message LteNetServingCellInfo {
  LteServingCellState state = 1;
  LteCellMode mode = 2;
  LteFddTddMode fdd_tdd_mode = 3;
  uint32 cellid = 4; // Hexadecimal format. Cell ID. The parameter determines the 16-bit (GSM) or 28-bit (UMTS) cell ID. Range: 0-0xFFFFFFF.
  uint32 pcid = 5; // Physical cell ID
  uint32 uarfcn = 6; // Number format. The parameter determines the UTRA-ARFCN of the cell that was scanned
  uint32 earfcn = 7; // Number format. The parameter determines the E-UTRA-ARFCN of the cell that was scanned
  uint32 freq_band = 8; // E-UTRA frequency band (see 3GPP 36.101)
  LteBandwidth ul_bandwidth = 9;
  LteBandwidth dl_bandwidth = 10;
  uint32 tac = 11; // Tracking Area Code (see 3GPP 23.003 Section 19.4.2.3)
  int32 rsrp = 12; // Reference Signal Received Power (see 3GPP 36.214 Section 5.1.1)
  int32 rsrq = 13; // Reference Signal Received Quality (see 3GPP 36.214 Section 5.1.2)
  int32 rssi = 14; // The parameter shows the Received Signal Strength Indication
  uint32 sinr = 15; // Logarithmic value of SINR, Values are in 1/5th of a dB. Range: 0-250 which translates to -20dB - +30dB
  uint32 srxlev = 16; // Select receive level value for base station in dB (see 3GPP25.304).
}

// NeighborCell freq mode
enum LteNeighborFreqMode {
  LTE_FREQ_MODE_UNSPECIFIED = 0;
  LTE_FREQ_MODE_INTRA = 1;
  LTE_FREQ_MODE_INTER = 2;
  LTE_FREQ_MODE_WCDMA = 3;
  LTE_FREQ_MODE_WCDMA_LTE = 4;
}

// Set
enum LteNeighborCellSet {
  LTE_NEIGHBOR_CELL_SET_UNSPECIFIED = 0;
  LTE_NEIGHBOR_CELL_SET_ACTIVE_SET = 1;
  LTE_NEIGHBOR_CELL_SET_SYNC_NEIGHBOR = 2;
  LTE_NEIGHBOR_CELL_SET_ASYNC_NEIGHBOR = 3;
}

message LteNetNeighborCellInfo {
  LteCellMode mode = 1;
  LteNeighborFreqMode freq_mode = 2;
  uint32 earfcn = 3;
  uint32 uarfcn = 4;
  uint32 pcid = 5;
  int32 rsrq = 6;
  int32 rsrp = 7;
  int32 rssi = 8;
  uint32 sinr = 9;
  uint32 srxlev = 10;
  uint32 cell_resel_priority = 11; // Cell reselection priority. Range: 0-7
  uint32 s_non_intra_search = 12; // Threshold to control non-intra frequency searches.
  uint32 thresh_serving_low = 13; //Specifies the suitable receive level threshold (in dB) used by the UE on the serving cell when reselecting towards a lower priority RAT/frequency.
  uint32 s_intra_search = 14; // Cell selection parameter for the intra frequency cell.
  uint32 thresh_x_low = 15; // The suitable receive level value of an evaluated lower priority cell must be greater than this value.
  uint32 thresh_x_high = 16; // The suitable receive level value of an evaluated higher priority cell must be greater than this value.
  uint32 psc = 17; //The parameter determines the primary scrambling code of the cell that was scanned
  int32 rscp = 18; // The parameter determines the Received Signal Code Power level of the cell that was scanned
  int32 ecno = 19; // Carrier to noise ratio in dB = measured Ec/Io value in dB.
  LteNeighborCellSet cell_set = 20; // 3G neighbour cell set
  int32 rank = 21; // Rank of this cell as neighbour for inter-RAT cell reselection
  uint32 cellid = 22; // Hexadecimal format. Cell ID. The parameter determines the 16-bit (GSM) or 28-bit (UMTS) cell ID. Range: 0-0xFFFFFFF.
  int32 inter_freq_srxlev = 23; // Suitable receive level for inter frequency cell
}

enum LtePcellState {
    LTE_NO_SERVING = 0;
    LTE_REGISTERED = 1;
}

enum LteScellState {
    LTE_DECONFIGURED = 0;
    LTE_CONFIGURED_DEACTIVATED = 1;
    LTE_CONFIGURERD_ACTIVATED = 2;
}

enum LteCarrierComponent {
    LTE_CC_UNAVAILABLE = 0;
    LTE_PCC = 1;
    LTE_SCC = 2;
}

message LteNetCarrierAggInfo {
    LteCarrierComponent lte_carrier_component = 1;
    uint32 freq = 2;
    LteBandwidth bandwidth = 3;
    LtePcellState pcell_state = 4;
    LteScellState scell_state = 5;
    uint32 pcid = 6;
    int32 rsrp = 7;
    int32 rsrq = 8;
    int32 rssi = 9;
    int32 sinr = 10;
}

message LtePDPContextInfo {
    uint32 cid = 1;
    uint32 bearer_id = 2;
    string apn = 3;
    string local_addr = 4;
    string subnetmask = 5;
    string gw_addr = 6;
    string dns_prim_addr = 7;
    string dns_sec_addr = 8;
    string p_cscf_prim_addr = 9;
    string p_cscf_sec_addr = 10;
    uint32 im_cn_signalling_flag = 11;
    uint32 lipaindication = 12;
}

// LTE info
message LteInfoReport {

  LteCommonHeader header = 1;

  // LTE info
  LteNetInfo lte_net_info = 2;

  // Data usage
  LteDataUsage lte_data_usage = 3;

  // Serving cell info
  LteNetServingCellInfo lte_srv_cell = 4;

  // Neighbor cell info
  repeated LteNetNeighborCellInfo lte_neigh_cell_info = 5;

  // Carrier aggregation
  LteNetCarrierAggInfo lte_primary_carrier_agg_info = 6;
  LteNetCarrierAggInfo lte_secondary_carrier_agg_info = 7;

  // PDP context info
  LtePDPContextInfo lte_pdp_context = 8;
Info

The feature was stabilized using the Quectel module.The feature was stabilized using the Quectel module.

Northbound API

OVSDB Schema: Lte_Config Table

Code Block
root@opensync:~# ovsh s Lte_Config
------------------------------------
_uuid                 | d6ae~8b1f  |
_version              | 0299~ca76  |
active_simcard_slot   | 0          |
apn                   | data641333 |
enable_persist        | false      |
esim_activation_code  | ["set",[]] |
esim_download_start   | false      |
esim_profile_activate | false      |
force_use_lte         | false      |
if_name               | wwan0      |
ipv4_enable           | true       |
ipv6_enable           | true       |
lte_bands_enable      | ["set",[]] |
lte_failover_enable   | true       |
manager_enable        | true       |
modem_enable          | true       |
os_persist            | false      |
pdp_context_id        | ["set",[]] |
report_interval       | 60         |
------------------------------------

OVSDB Schema: Lte_State Table

Code Block
root@opensync:~# ovsh s Lte_State
-----------------------------------------------------
_uuid                     | ac94~71f3               |
_version                  | 8fb0~8982               |
active_simcard_slot       | 0                       |
apn                       | data641333              |
enable_persist            | false                   |
esim_activation_code      | ["set",[]]              |
esim_active_profile       | ["set",[]]              |
esim_download_complete    | false                   |
esim_download_in_progress | false                   |
esim_download_start       | false                   |
esim_profile_activate     | false                   |
force_use_lte             | false                   |
iccid                     | 89011703278753831333    |
if_name                   | wwan0                   |
imei                      | 861364040285993         |
imsi                      | 310170875383333         |
ipv4_enable               | true                    |
ipv6_enable               | true                    |
lte_bands_enable          |                         |
lte_failover_enable       | true                    |
lte_net_mode              | lte                     |
lte_net_state             | registered_home_network |
manager_enable            | true                    |
mcc                       | 310                     |
mnc                       | 410                     |
modem_enable              | true                    |
modem_firmware_version    | ["set",[]]              |
modem_present             | true                    |
pdp_context_id            | ["set",[]]              |
report_interval           | 60                      |
service_provider_name     | "AT&T"                  |
sim_status                | Inserted                |
tac                       | 8                       |
-----------------------------------------------------

MQTT

Protobuf definition: src/lib/protobuf/lte_info.proto

OSN LTE Southbound API - OSN LTE

...