...
| No Format |
|---|
message RadioStatus {
// true if enabled AND successfully applied
bool airplane_mode = 1;
// for every LTE network
repeated CellularStatus cellular_status = 1;
// later we can add status for every WiFi network
}
message CellularStatus {
// logicallabel of the physical device
string networkUUIDdeviceName = 1;
CellularModem modem = 2;
OperatingState operatingState = 3;
string controlProtocol = 4; // "qmi" or "mbim"
string imei = 5;
CellularProvider provider = 6;
CellularVisibleProvider visibleProviders = 7;
// if the last configuration change failed, error message is reported here
string configError = 10;
// wwan servise periodically pings configured IP address.
// If the last probing failed, stderr of the probing method is published here.
string probeError = 11;
}
message CellularModem {
string model = 1;
string revision = 2;
}
enum CellularOperatingState {
OPERATING_STATE_UNSPECIFIED = 0;
OPERATING_STATE_ONLINE = 1;
OPERATING_STATE_RADIO_OFF = 2; (AKA airplane mode)
OPERATING_STATE_OFFLINE = 3;
...
}
|
The Local profile server application may either reply with status 204 (No content), acknowledging the received state data update but not requiring any configuration changes, or return 200 (OK) and append response body with the intended radio state encoded using this proto message:
| No Format |
|---|
message RadioConfig {
bool airplaneMode = 1;
string serverToken = 2;
} |
message CellularProvider {
string plmn = 1;
string description = 2;
bool registered = 3;
bool roaming = 4;
}
message CellularVisibleProvider {
string plmn = 1;
string description = 2;
string status = 3;
}
|
The Local profile server application may either reply with status 204 (No content), acknowledging the received state data update but not requiring any configuration changes, or return 200 (OK) and append response body with the intended radio state encoded using this proto message:
| No Format |
|---|
message RadioConfig {
bool airplaneMode = 1;
string serverToken = 2;
} |
If the actual state and the returned intended state differ, EVE will trigger the operation of applying the intended state (eIf the actual state and the returned intended state differ, EVE will trigger the operation of applying the intended state (e.g. disabling the radio). The outcome of this operation (i.e. the new state, with potential error message if the change failed) will be published by the next POST call. If the actual and the intended state are the same, EVE will not perform any airplane-mode changes at least until the next POST call.
...
EVE API - device info (i.e. API between EVE and the controller)
| No Format |
|---|
message ZInfoNetworkDevicePort { ... WirelessStatus wirelessStatus = XY; } message WirelessStatus { // either LTE or WiFi (or not wireless) WirelessType type = 1; // for LTE; see CellularStatus defined above repeated CellularStatus cellularStatus = 5; // later we may add status for WiFi } |
EVE API - device metrics (requested by the same customer)
| No Format |
|---|
message NetworkMetricdeviceMetric { ... repeated CellularMetric cellularMetric = XY; } message CellularMetric { CellularSignalStrength// signalStrengthlogicallabel = 1of the physical device string deviceName = 1; CellularSignalStrength signalStrength = 2; CellularPacketStats packetStats = 23; } // Value of 0xFFFF means that the particular metric is not available. message CellularSignalStrength { int32 rssi = 1; int32 rsrq = 2; int32 rsrp = 3; int32 snr = 4; } // Collected by the modem itself and can be obtained using // e.g. "qmicli -d /dev/cdc-wdm0 --wds-get-packet-statistics" message CellularPacketStats { // NetworkStats are already defined in EVE API NetworkStats rx = 1; NetworkStats tx = 2; } |
Interface between wwan service and zedbox
A new /run/wwan/<network-uuid>/config.json will be added for each LTE network to submit LTE configuration from nim to wwan service, including the required airplane mode state, e.g.:
| No Format |
|---|
{
"physical“airplane-addrsmode”: {
# nim will specify one/some of “off”, # "on" or "off"
"modems": [
{
"device-name": "lte-modem1", # logicallabel of the physical device
"physical-addrs: {
# nim will specify one/some of these. With multiple LTE modems the USB address is the most unambiguous and reliable.
“interface”: “wwan0”,
“usb”: “1:2.3”, # <bus>:[port]
"pci": "0000:11:00.0",
},
“apns”: [“internet”],
“airplane-mode”: “off”,
“probe-ip”: “8.8.8.8”
},
]
} |
Note: interface/usb/pci will be obtained by nim from AssignableAdapters based on the PhyLabel of NetworkPortConfig.
Next a new /run/wwan/<network-uuid>/status.json with modem state data will be published for each LTE network by wwan service for zedagent nim to read. Status file will contain MD5 checksum of the last applied revision of config.json. With this, EVE will know when there are no more pending configuration changes, so that it is ready to publish radio state up to the application.
| No Format |
|---|
{
// MD5 checksum of config.json (without trailing white-space) applied at the time of publishing this info
"config-checksum": "d7548db5594b064f2c9ec0599e84523e",
"modems": [
{
"device-name": "lte-modem1", # can be empty for modems not configured from the controller
"physical-addrs: {
# all addresses will be filled by wwan service
“interface”: “wwan0”,
“usb”: “1:2.3”, # <bus>:[port]
"pci": "0000:11:00.0",
},
"control-protocol": "qmi" | "mbim",
"operating-mode": "offline" | "online" | "radio-off" | "unrecognized",
"imei": “310170845466094”,
"modem": {
"model": "QUECTEL Mobile Broadband Module",
"revision": "EC21ECGAR06A04M1G",
},
"config-error": "",
"probe-error": "Failed to ping 8.8.8.8 (2 packets transmitted, 0 received, 100% packet loss, time 1029ms)",
"provider" {
"plmn": "310-410",
"description": "AT&T",
"registered": true,
"roaming": false
},
"visible-providers": [
{
"plmn": "310-410",
"description": "AT&T",
"status": "home, preferred, visible, registered"
},
{
"plmn": "310-120",
"description": "AT&T",
"status": "visible"
}
]
}
]
} |
Lastly, wwan service will also periodically publish /run/wwan/metrics.json with cellular metrics:
| No Format |
|---|
{ "modems": [ { "device-name": "lte-modem1", # can be empty for modems not configured from the controller "physical-addrs: { # all addresses will be filled by wwan service “interface”: “wwan0”, “usb”: “1:2.3”, # <bus>:[port] "pci": "0000:11:00.0" }, "packet-stats": { "rx": { "bytes": 456456, "packets": 1234, "drops": 0 }, "tx": { "bytes": 23485, "packets": 758, "drops": 12 } }, "signal-info": { "rssi": -42 "rsrq": -11, "rsrp": -98, "snr": 56 } } ] "interface": "wwan0", "protocol": "qmi" | "mbim", "operating-mode": "online" | "radio-off" | etc. "imei": “310170845466094”, "modem-model": "QUECTEL Mobile Broadband Module", "modem-revision": "EC21ECGAR06A04M1G", "config-error": "", "probe-error": "Failed to ping 8.8.8.8 (2 packets transmitted, 0 received, 100% packet loss, time 1029ms)", // MD5 checksum of config.json (without trailing white-space) applied at the time of publishing this info "config-checksum": "d7548db5594b064f2c9ec0599e84523e" } |
Application Behavior
Application acting as a Local Profile Server for the airplane-mode is expected to behave as follows:
...
Inside the zedbox process the handling of the airplane mode will be split between zedagent and nim microservices. Communication between the Local profile server and EVE is already being done by zedagent. Periodically, it obtains the latest profile configuration, stores it into a file for persistence and publishes it inside ZedagentStatus. For the airplane feature we will mostly reuse the same code and add AirplaneMode (the intended state) into the structure:
| No Format |
|---|
type ZedAgentStatus struct { ... AirplaneMode AirplaneMode } AirplaneMode struct { Enabledtype ZedAgentStatus struct { ... AirplaneMode AirplaneMode } AirplaneMode struct { Enabled bool // from application PermanentlyEnabled bool // from grub (radio cannot be ever turned ON, not even by the local profile server) InProgress bool // from application InProgress bool // from NIM RequestedAt time.Time // recorded by zedagent after POST call } |
nim will subscribe for zedagent status updates. If AirplaneMode.Enabled has changed, nim will trigger the operations of switching all radios ON/OFF. This actually means to publish the new configuration into wwan (and later also wlan/rfkill) service and (asynchronously) wait for updated state data (acknowledging the latest config using a checksum). Once wwan service responds, nim will publish the new state back into zedagent using DeviceNetworkStatus, which will be also extended with the same AirplaneMode structure (.RequestedAt copied from ZedAgentStatus; .Enabled and .InProgress updated by nim). Inside, the per-port NetworkPortStatus will contain WirelessStatus. zedagent will make another POST call to /api/v1/radio only after it has received DeviceNetworkStatus with AirplaneMode of the same timestamp and with InProgress being false.
...
The shell script of the wwan service will undergo few implementation changes. Firstly, it will stop using hard-coded configuration values and instead will wait for and read /run/wwan/<network-uuid>/config.json (written by nim for each LTE network). It will then keep monitoring config.json files file and will apply any changes, including the airplane-mode on/off switch.
...
| No Format |
|---|
wwan main:
repeat indefinitely:
for every LTE network:
if /run/wwan/<network-uuid>/config.json changed/appeared:
detect protocol (QMI or MBIM)
reset modem (i.e. disconnect)
(re)load config
set operating mode (online or low-power)
if not in the airplane mode (operating mode is "online") and connectivity check failed:
reset modem if connected
wait for device registration on the network
start network(s) (take APN(s) from config.json)
wait for data connectivity and IP address
configure interface and resolv.conf
publish state data and metrics under /run/wwan/<network-uuid>/ (power state, signal strength, IPmodem configurationinfo, etc.)
sleep 5mins, break from sleep if any /run/wwan/<network-uuid>/config.json changes/(dis)appears |
...