...
Firstly, for safety reasons it is essential that the airplane mode radio-silence functionality is managed locally. Regardless of the controller connectivity status, the operator working on the location should be able to enable/disable the airplane mode radios as needed.
We can assume that a keyboard, mouse and a monitor will be attached to the device. The operator should be able to change and view the airplane mode radio status using these peripherals. It is not required to add any additional hardware like a physical toggle button or an LED. The airplane mode radio status could be therefore managed via an application deployed on the device.
...
Firstly, given that the feature should be managed locally, we propose to leverage a recently added Local Profile server. The idea was to essentially allow a locally deployed application to act as a local controller and override a (very small) subset of the device configuration received from the controller. Currently, only the “profile” field can be overridden, hence the name. However, the feature was designed knowing that it could be extended in the future with more device configuration options that need local override. The API of the Local Profile server defines endpoint /api/v1/local_profile
from which EVE should periodically obtain a profile name and use it instead of the default profile selected by the controller. The endpoint content is a protobuf-serialized message, which makes it easily extensible and allows to add more fields for the local override. However, for radio management we will define a separate POST endpoint, making it easier to remove/disable or to split from local profile server into a separate application if needed. For API details see “EVE API Additions” below
...
- The application to act as a Local Profile Server is selected via the controller
- Local profile server has to authenticate itself to EVE OS using a token
- Configuration from Local Profile server overrides the configuration from the controller (even when the Local server is not currently running/accessible/responsive). In this case, the radio silence is not actually configurable by the controller. The behavior is to act as if the feature was disabled (i.e. radio silence is disabledradios are enabled) by the controller. This means that only Local profile server can enable it and by default (i.e without local profile server app being deployed) the feature is disabled (i.e. radio is on).and radios are turned ON.
- The configuration from the Local Profile Server is preserved between system reboots using the
/persist
partition
The requested radio silence state would be periodically obtained by zedagent
from the Local Profile server. The handler of this configuration option would be the wwan
service. The file-based communication between the zedagent
/nim
and wwan
service will be used to exchange the intended/actual radio silence state. This is described in more details below under “EVE API Additions”.
...
No Format |
---|
message RadioStatus { // true if enabled AND successfully applied bool radioSilenceradio_silence = 1; // If the last radio configuration change failed, error message is reported here. // Please note that there is also a per-modem configuration error reported under CellularStatus. string config_error = 2; // for every LTE network repeated CellularStatus cellular_status = 3; // later we can add status for every WiFi network } message CellularStatus { // Logical label assigned to the physical cellular modem. string logicallabel = 1; org.lfedge.eve.common.ZCellularModuleInfo module = 2; repeated org.lfedge.eve.common.ZSimcardInfo simCardssim_cards = 3; repeated org.lfedge.eve.common.ZCellularProvider providers = 4; string configErrorconfig_error = 10; string probeErrorprobe_error = 11; } |
Where ZCellularModuleInfo
, ZSimcardInfo
and ZCellularProvider
are defined in api/proto/info/info.proto
as follows:
No Format |
---|
enum ZSimcardState { Z_SIMCARD_STATE_INVALID = 0; Z_SIMCARD_STATE_ASSIGNED = 1; Z_SIMCARD_STATE_PROVISIONED = 2; Z_SIMCARD_STATE_ACTIVE = 3; Z_SIMCARD_STATE_SUSPENDED = 4; Z_SIMCARD_STATE_CANCELLED = 5; } message ZSimcardInfo { // Name is a SIM card identifier. For example ICCID if available. // Guaranteed to be unique only in the scope of the edge node. string name = 1; // Reference to ZCellularModuleInfo.name string cellularModuleNamecell_module_name = 2; string imsi = 3; string iccid = 4; ZSimcardState state = 5; } message ZCellularModuleInfo { // Name is a module identifier. For example IMEI if available. // Guaranteed to be unique only in the scope of the edge node. string name = 1; string imei = 2; string firmwareVersionfirmware_version = 3; string model = 4; ZCellularOperatingState operatingStateoperating_state = 5; ZCellularControlProtocol controlProtocolcontrol_protocol = 6; } enum ZCellularOperatingState { OPERATING_STATE_UNSPECIFIED = 0; OPERATING_STATE_OFFLINE = 1; OPERATING_STATE_RADIO_OFF = 2; // AKA radio silence OPERATING_STATE_ONLINE = 3; OPERATING_STATE_ONLINE_AND_CONNECTED = 4; OPERATING_STATE_UNRECOGNIZED = 5; } enum ZCellularControlProtocol { CONTROL_PROTOCOL_UNSPECIFIED = 0; CONTROL_PROTOCOL_QMI = 1; CONTROL_PROTOCOL_MBIM = 2; } message ZCellularProvider { // Public land mobile network code. string plmn = 1; string description = 2; // True if this is the provider currently being used. bool currentServingcurrent_serving = 3; bool roaming = 4; } |
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 { string serverTokenserver_token = 1; bool radioSilenceradio_silence = 2; } |
If 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 radio state changes at least until the next POST call.
...
No Format |
---|
message DevicePort { ... WirelessStatus wirelessStatus = XY; } message WirelessStatus { // either LTE or WiFi (or not wireless) WirelessType type = 1; // for LTE: repeated CellularStatus cellularStatuscellular_status = 5; // later we may add status for WiFi } message ZCellularStatus { // Name reference (ZCellularModuleInfo.name) to the corresponding cellular module // from the list ZInfoDevice.cellularModules string cellularModulecellular_module = 1; // Each item is a name reference (ZSimcardInfo.name) to a SIM card from the list ZInfoDevice.simCards // Ordered by slot numbers. repeated string simCardssim_cards = 2; // List of available cellular service providers. repeated org.lfedge.eve.common.ZCellularProvider providers = 3; // If EVE failed to configure the cellular connection, the error is published here. string configErrorconfig_error = 10; // if the connectivity probing is failing, error is reported here // (see CellularConnectivityProbe). string probeErrorprobe_error = 11; } |
EVE API - device metrics (requested by the same customer)
No Format |
---|
message deviceMetric { ... repeated CellularMetric cellularMetriccellular_metric = XY; } message CellularMetric { // logicallabel of the physical device string logicallabel = 1; CellularSignalStrength signalStrengthsignal_strength = 2; CellularPacketStats packetStatspacket_stats = 3; } // 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; } |
...
Inside the zedbox
process the handling of the radio silence 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 radio-silence feature we will mostly reuse the same code and add AirplaneMode
add RadioSilence
(the intended state) into the structure:
...
nim
will subscribe for zedagent
status updates. If RadioSilence.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 RadioSilence
structure (.
ChangeRequestedAt
copied from ZedAgentStatus
; .
Enabled
and .
ChangeInProgress
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 RadioSilence of the same timestamp and with Change
InProgress
being false.
At the same time nim
will take into account the radio state during network connectivity testing. If the radio silence is ON (or a change is in progress), DPC (device port configuration) verification will be skipped. The state of enabled radio silence will be indicated by both diag
and ledmanager
microservice microservices. We could also introduce a distinct blinking count for the case of lost controller connectivity due to disabled radio(s) - e.g. 5 blinks.
...