Documentation for the ModemManager-based wwan microservice

Completely rewritten documentation for the topic of cellular
connectivity on EVE, reflecting the major rework of the wwan microservice
and the transition from the shell script to using ModemManager.

Signed-off-by: Milan Lenco <milan@zededa.com>

Author: milan-zededa

docs/BUILD.md

@@ -399,7 +399,7 @@ The following custom packages are used:
 * `onboot` packages:
   * `lfedge/eve-rngd` - custom `lfedge/eve-rngd` package, rather than the standard linuxkit one. This micro-fork accommodates the [following hack](https://github.com/lf-edge/eve/blob/master/pkg/rngd/cmd/rngd/rng_linux_arm64.go) which provides some semblance of seeding randomness on ARM. Without this HiKey board won't boot.
 * `services` packages:
-  * `lfedge/eve-wwan` - WWAN drivers and software. LTE/3G/2G. Mostly experimental.
+  * `lfedge/eve-wwan` - WWAN drivers and software. 5G/LTE/3G/2G. See [wwan/README.md](../pkg/wwan/README.md) for detailed documentation.
   * `lfedge/eve-wlan` - WLAN drivers and software. Currently a glorified wrapper around wpa_supplicant.
   * `lfedge/eve-guacd` - [Apache Guacamole service](http://guacamole.apache.org/) that provides console and VDI services to running VMs and containers.
   * `lfedge/eve-zedctr` - a "catch-all" package for EVE tools; see below.

docs/CONFIG.md

@@ -184,7 +184,8 @@ An example file with eth0 being static and eth1 using dhcp is:
 }
 ```
 
-To specify that wwan0 should be secondary (only used if eth0 can not be used to reach the controller), and eth1 only be if neither eth0 nor wwan0 works, one would set non-zero costs. For example,
+To specify that a cellular modem should be secondary (only used if eth0 can not be used to reach the controller),
+and eth1 only be used if neither eth0 nor the modem works, one would set non-zero costs. For example,
 
 ```json
 {
@@ -201,10 +202,23 @@ To specify that wwan0 should be secondary (only used if eth0 can not be used to
         {
             "Dhcp": 4,
             "Cost": 1,
-            "IfName": "wwan0",
+            "USBAddr": "1:1.4",
+            "PCIAddr": "0000:01:00.0",
             "IsMgmt": true,
-            "Name": "Management1"
-        }
+            "Name": "Management1",
+            "WirelessCfg": {
+                "WType": 1,
+                "CellularV2": {
+                    "AccessPoints": [
+                        {
+                            "SIMSlot": 0,
+                            "Activated": true,
+                            "APN": "internet"
+                        }
+                    ]
+                }
+            }
+        },
         {
             "Dhcp": 4,
             "Cost": 2,

docs/DEVICE-CONNECTIVITY.md

@@ -33,7 +33,7 @@ When EVE is installed using a generic EVE installer without device bootstrap con
 
 - DHCP is enabled on one of the Ethernet ports
 - WiFi is not assumed (since WiFi needs credentials)
-- If cellular connectivity is assumed, the default APN (`internet`) will work to connect to the network
+- Cellular connectivity is not assumed (without cellular config every discovered modem will have RF function disabled)
 - No enterprise proxy configuration is required to be able to connect to the controller.
 
 If any of those assumptions is not satisfied, then it is necessary to either install EVE using a single-use EVE installer, shipped with the initial "bootstrap" configuration prepared for the target device (the preferred method) or to use one of the legacy mechanisms for off-line configuration management.
@@ -65,7 +65,7 @@ At least one port must be set to be a management port, and that port needs to re
 
 ### Last resort
 
-If `network.fallback.any.eth` [configuration property](CONFIG-PROPERTIES.md) is set to `enabled` (by default it is disabled), then there is an additional lowest priority item in the list of DevicePortConfigs, called "Last resort" DPC (pubsub key `lastresort`), based on finding all of the Ethernet and Ethernet-like interfaces (an example of the latter is WiFi and cellular modems) which are not used exclusively by applications. The last resort configuration assumes DHCP and no enterprise proxies.
+If `network.fallback.any.eth` [configuration property](CONFIG-PROPERTIES.md) is set to `enabled` (by default it is disabled), then there is an additional lowest priority item in the list of DevicePortConfigs, called "Last resort" DPC (pubsub key `lastresort`), based on finding all Ethernet interfaces (i.e. excluding wireless connectivity options) which are not used exclusively by applications. The last resort configuration assumes DHCP and no enterprise proxies.
 
 However, independent of the above property setting, if the device has no source of network configuration available (no bootstrap, override or persisted config), then EVE will use the Last resort *forcefully*. This, for example, happens when device boots for the very first time, without [bootstrap config](#bootstrap-configuration) or the (legacy) network config override being provided. In that case, device may remain stuck with no connectivity indefinitely (unless the user plugs in a USB stick with a network config later), therefore EVE will try to use Last resort to see if it can provide connectivity with the controller. Once device obtains a proper network config (from the controller or a USB stick), EVE will stop using Last resort forcefully and will keep this network config inside `DevicePortConfigList` only if and as long as it is enabled explicitly by the config (`network.fallback.any.eth` is `enabled`).
 
@@ -189,7 +189,7 @@ with `eve verbose off`.
 ### Connectivity-Related Logs
 
 The progression and outcome of [network configuration testing](#testing) is logged with messages
-prefixed with `DPC verify:` (not that DPC is abbreviation for `DevicePortConfig`, which is a Go
+prefixed with `DPC verify:` (note that DPC is abbreviation for `DevicePortConfig`, which is a Go
 structure holding configuration for all management and app-shared interfaces). These messages
 can explain why a particular device is not using the latest configuration but instead has fallen
 back to a previous one. These logs are quite concise yet pack enough information to tell when
@@ -271,19 +271,20 @@ troubleshooting:
  Once device is onboarded, `DeviceUUID` field will be non-empty and contain the assigned
  device UUID (also printed to `/persist/status/uuid`).
 
-Finally, the [wwan microservice](../pkg/wwan), managing the [cellular connectivity](./WIRELESS.md),
-is a shell script outside of the pillar container, not using pubsub for IPC. Instead, it exchanges
-wwan config, status and metrics with NIM simply by reading/writing files located under `/run/wwan`
-directory:
+For WWAN connectivity info, refer to these pubsub topics:
 
-- `config.json` is published by NIM and may contain configuration for a cellular modem.
+- `/run/nim/WwanConfig/global.json` is published by NIM and contains configuration for cellular modems.
+- `/run/wwan/WwanStatus/global.json` is published by wwan microservice to inform zedagent, NIM
+  and some other microservices about the current cellular connectivity status.
+- `/run/wwan/WwanMetrics/global.json` is published by wwan microservice and contains packet/byte
+  counters reported by cellular modems (i.e. not from the Linux network stack)
 
-- `status.json` and `metrics.json` are published by wwan microservice to inform NIM about the current
- cellular connectivity status and to publish packet/byte counters, respectively.
-
-- `resolv.conf/<interface-name>.dhcp` contains the list of nameservers that should be used with
- a given wwan interface (published by wwan to NIM and further via `DeviceNetworkStatus` to other
- microservices, like downloader)
+Separately to pubsub topics, file `/run/wwan/resolv.conf/<interface-name>.dhcp` is updated
+by the wwan microservice and contain the list of nameservers that should be used with the given
+wwan interface. This is similar to how dhcpcd reports DNS servers for ethernet interfaces
+(for both DHCP and static IP config). In NIM, where this info is processed and further published
+via `DeviceNetworkStatus` pubsub topic, we can therefore process nameservers for ethernet
+and wwan interfaces in a very similar way and reuse some code.
 
 ### Netdump and Nettrace
 
@@ -340,7 +341,7 @@ topic name with a publication timestamp plus the `.tgz` extension, for example:
 `downloader-fail-2023-01-03T14-25-04.tgz`, `nim-ok-2023-01-03T13-30-36`, etc.
 
 Not all microservices that communicate over the network are traced and contribute with netdumps.
-Currently traced HTTP requests are:
+Currently, traced HTTP requests are:
 
 - `/ping` request done by NIM to verify connectivity for the *latest* DPC (testing of older DPCs
  is never traced). Packet capture is also enabled and the obtained pcap files are included in

docs/ECO-METADATA.md

@@ -61,10 +61,10 @@ Standalone GPS receivers are currently not supported.
 
 However, by default EVE does not use the location service of the LTE modem and the location
 information is therefore not available.
-To enable location reporting for the device, the `wwan*` adapter (corresponding to the LTE modem)
-must be **configured as port shared between applications and/or for device management** with
-**location tracking** enabled. When the modem is disabled or directly assigned to an application,
-EVE is not able to access the location service and obtain location information.
+To enable location reporting for the device, the cellular modem adapter must be **configured as port
+shared between applications and/or for device management** with **location tracking** enabled.
+When the modem is disabled or directly assigned to an application, EVE is not able to access
+the location service and obtain location information.
 In EVE API this is done by setting the field `NetworkConfig.wireless.cellularCfg.location_tracking`
 to `true`. For more details refer to [netconfig.proto](https://github.com/lf-edge/eve-api/tree/main/proto/config/netconfig.proto).
 
@@ -112,6 +112,8 @@ Uncertainty and reliability fields describe how accurate the provided location i
 with single-precision floating-point values. Negative values are not valid and represent
 unavailable uncertainty.
 Reliability is one of: `not-set` (unavailable), `very-low`, `low`, `medium` and `high`.
+Note that Uncertainty and Reliability are no longer available in newer EVE versions
+(returned are zero values).
 
 The frequency at which EVE updates location information is configurable using the option
 [timer.location.app.interval](../docs/CONFIG-PROPERTIES.md). By default, the interval is 20
@@ -206,7 +208,7 @@ curl 169.254.169.254/eve/v1/wwan/status.json 2>/dev/null | jq
 ```
 
 The underlying structure, used by EVE to store the information and output it as JSON,
-is named `WwanStatus` and can be found in [zedroutertypes.go](../pkg/pillar/types/zedroutertypes.go).
+is named `WwanStatus` and can be found in [wwan.go](../pkg/pillar/types/wwan.go).
 
 The endpoint returns a list of entries, one for every cellular modem, with the modem's
 logical label (from the device model) used as a reference. The physical connection between
@@ -275,7 +277,7 @@ curl 169.254.169.254/eve/v1/wwan/metrics.json 2>/dev/null | jq
 ```
 
 The underlying structure, used by EVE to store the information and output it as JSON,
-is named `WwanMetrics` and can be found in [zedroutertypes.go](../pkg/pillar/types/zedroutertypes.go).
+is named `WwanMetrics` and can be found in [wwan.go](../pkg/pillar/types/wwan.go).
 
 The endpoint returns a list of entries, one for every cellular modem, with the modem's
 logical label (from the device model) used as a reference. Just like in the

docs/EDGEVIEW-CONTAINER-API.md

@@ -1,10 +1,10 @@
 # Edge-View Container and APIs
 
-EVE provides the Edge-View mainly for device and application troubleshooting tasks. It is a system-level container similar to `newlogd`, `wwan`, etc.
+EVE provides the Edge-View mainly for device and application troubleshooting tasks. It is a system-level container similar to `newlogd`, `wlan`, etc.
 
 Edge-View as a service on EVE, it needs to receive/update user configurations from the controller; and it needs to send/update Edge-View running status to the controller.
 
-The software integration level of Edge-View is somewhere between the services like `newlogd` and `wwan`. `newlogd` is an integral part of the EVE, while `wwan` is a generic Linux service without any specific EVE related changes. The Edge-View container runs on the EVE device and has many tasks designed specifically for EVE device and application usage, but it can also run as a normal Linux docker container on any host; the same container is used for Edge-View client runs on the user's laptop. Thus design of Edge-View container tries to minimize the interaction with the rest of the EVE system while still being configured from the controller and sending status to the controller.
+The software integration level of Edge-View is somewhere between the services like `newlogd` and `wlan`. `newlogd` is an integral part of the EVE, while `wlan` is a generic Linux service without any specific EVE related changes. The Edge-View container runs on the EVE device and has many tasks designed specifically for EVE device and application usage, but it can also run as a normal Linux docker container on any host; the same container is used for Edge-View client runs on the user's laptop. Thus design of Edge-View container tries to minimize the interaction with the rest of the EVE system while still being configured from the controller and sending status to the controller.
 
 This Wiki page describes the provisioning, security and status update for Edge-View in [Edge-View Doc](https://wiki.lfedge.org/display/EVE/Edge-View).
 

docs/HARDWARE-MODEL.md

@@ -61,7 +61,7 @@ Starting from the generated model file and add or adjust:
 - Optionally, if the intended application pre-determined and e.g., eth1 will be connected to the shopfloor network, you can set the logicallabel field to "shopfloor". That makes it more clear in the UI the intended use of that port.
 - If the model file shows multiple USB controllers, then plug in e.g., a USB stick in each physical USB port and use ```lsusb``` and ```lspci``` to tell which controller to which port is connected.
 - If the device has multiple physical USB ports, please add a entry for each one of them in the json file (on the correct USB controller if there are multiple)
-- If you device has a cellular modem verify that there is one or two wwan interfaces in the generated file, and if not add one. If it is connected via a USB controller (```lsusb``` will tell you that) it needs to be in the same assignment group as the USB controller.
+- If your device has a cellular modem, verify that the PCI and USB addresses recognized by spec.sh are actually correct. The script will make sure that modem connected over USB bus will be in the same assignment group as the USB controller itself.
 - If some controllers have an empty assignment group there might be an issue with an unknown controller/function. The ```-v``` option to the script can be used to get more information about such unknown controllers/functions.
 
 #### Check for unknown controllers/functions