diff --git a/docs/BUILD.md b/docs/BUILD.md index 4ecc90a7f22..85fe6ecc611 100644 --- a/docs/BUILD.md +++ b/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. diff --git a/docs/CONFIG.md b/docs/CONFIG.md index cb1a92d35fb..a6cb5e50c94 100644 --- a/docs/CONFIG.md +++ b/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, diff --git a/docs/DEVICE-CONNECTIVITY.md b/docs/DEVICE-CONNECTIVITY.md index 7a3ff6ab3f4..4cd19f4dab9 100644 --- a/docs/DEVICE-CONNECTIVITY.md +++ b/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/.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/.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 diff --git a/docs/ECO-METADATA.md b/docs/ECO-METADATA.md index 51da496b8cc..d56e19f884e 100644 --- a/docs/ECO-METADATA.md +++ b/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 diff --git a/docs/EDGEVIEW-CONTAINER-API.md b/docs/EDGEVIEW-CONTAINER-API.md index 32a01f1f534..802fe2dd10c 100644 --- a/docs/EDGEVIEW-CONTAINER-API.md +++ b/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). diff --git a/docs/HARDWARE-MODEL.md b/docs/HARDWARE-MODEL.md index 9bce0b3777f..0efe1d3c4d5 100644 --- a/docs/HARDWARE-MODEL.md +++ b/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 diff --git a/docs/WIRELESS.md b/docs/WIRELESS.md index a90ec48ddf3..2f31e1a9dda 100644 --- a/docs/WIRELESS.md +++ b/docs/WIRELESS.md @@ -1,162 +1,134 @@ # Support for wireless connectivity in EVE -Given that the biggest use case for EVE is in Edge Computing and IoT it is no surprise that wireless connectivity plays a major role in connecting edge applications. Currently EVE supports 2 kinds of wireless networking devices: WiFi cards and Cellular GSM Modems. When it comes to utilizing either of these EVE relies on its controller to supply two critical pieces of information: +Given that the biggest use case for EVE is in Edge Computing and IoT it is no surprise that wireless +connectivity plays a major role in connecting edge applications. Currently, EVE supports 2 kinds +of wireless networking devices: WiFi cards and Cellular Modems. When it comes to utilizing +either of these, EVE relies on its controller to supply two critical pieces of information: -* Name of the wireless network to be joined ([SSID](https://en.wikipedia.org/wiki/Service_set_(802.11_network)#SSID) for WiFi and [APN](https://en.wikipedia.org/wiki/Access_Point_Name) for Cellular). -* Pre-shared secret required to joining the network ([WPA/WPA2/WEP](https://en.wikipedia.org/wiki/Wi-Fi_Protected_Access) and [username/password](https://www.digi.com/resources/documentation/Digidocs/90001399-13/tasks/t-set-up-and-configure-mobile-connectivity.htm) for Cellular). +* Name of the wireless network to be joined ([SSID](https://en.wikipedia.org/wiki/Service_set_(802.11_network)#SSID) + for WiFi and [APN](https://en.wikipedia.org/wiki/Access_Point_Name) for Cellular). +* Pre-shared secret required for joining the network ([WPA/WPA2/WEP](https://en.wikipedia.org/wiki/Wi-Fi_Protected_Access) + for WiFi and username/password for Cellular network running [PAP](https://en.wikipedia.org/wiki/Password_Authentication_Protocol) + or [CHAP](https://en.wikipedia.org/wiki/Challenge-Handshake_Authentication_Protocol)). -This dependency on a controller creates a bit of a chicken-and-an-egg problem when the wireless connectivity itself happens to be the only means of reaching the controller. In those cases EVE uses pre-loaded controller configuration to bootstrap the entire process. +This dependency on a controller creates a bit of a chicken-and-an-egg problem when the wireless +connectivity itself happens to be the only means of reaching the controller. In those cases, +EVE uses pre-loaded controller configuration to bootstrap the entire process. -The rest of this document will be focused on details of wireless support in EVE. It must be noted that currently we're relying on a patchwork of different open source projects to do that, but we're also looking at things like [oFono](https://en.wikipedia.org/wiki/OFono) and [Android's RIL](https://en.wikipedia.org/wiki/Radio_Interface_Layer) for a more holistic support. +The rest of this document will be focused on details of wireless support in EVE. ## WiFi -In general, WiFi support in EVE is pretty straightforward and largely depends on enabling the required driver in the Linux kernel and finding an appropriate firmware binary blob to be loaded by the device driver. Please refer to our [new hardware bringup](HARDWARE-BRINGUP.md) document for more details on the former and make sure to checkout our [firmware package](../pkg/firmware) for the latter. +In general, WiFi support in EVE is pretty straightforward and largely depends on enabling +the required driver in the Linux kernel and finding an appropriate firmware binary blob +to be loaded by the device driver. Please refer to our [new hardware bringup](HARDWARE-BRINGUP.md) +document for more details on the former and make sure to checkout our [firmware package](../pkg/fw) +for the latter. + +EVE uses [wpa_suplicant](https://wiki.archlinux.org/title/wpa_supplicant) to perform WPA-PSK +or WPA-EAP authentication process when connecting to WiFi networks. This software is installed +into a standalone [wlan](../pkg/wlan) container and it expects configuration for every WiFi adapter +at the filepath `/run/wlan/wpa_supplicant.conf`. The responsibility of maintaining and updating +this configuration lies with the NIM microservice. + +## Cellular connectivity + +### Modems + +Compared to WiFi, cellular modems present a significant challenge. This is partially due to the fact +that radio regulations in different countries tend to be partially incompatible. These regulations +can vary widely in terms of frequency bands, power limits, emission standards, and licensing +requirements. In some cases, these regulations can even appear complex or convoluted. +All of these factors conspire to create a technology landscape where modem manufacturers are compelled +to produce highly capable and highly configurable units. These modems need to be adaptable to different +regulatory environments and network infrastructures. They often take on very different characteristics +when loaded with firmware and configured for use in specific regions. + +Given the complexity of the tasks that cellular modems are required to perform, it's no surprise that +they have evolved into self-contained computers with sophisticated internal states. This comparison +with remote computers or servers is particularly apt because of the way you interact with these +devices. Cellular modems often operate in a manner similar to remote cloud services, relying heavily +on APIs (Application Programming Interfaces) for communication and control. Instead of directly +interfacing with the host Linux kernel or operating system, you typically communicate with a cellular +modem using specialized protocols and APIs like AT commands, +[MBIM (Mobile Broadband Interface Model)](https://modemmanager.org/docs/libmbim/mbim-protocol/), +or [QMI (Qualcomm MSM Interface)](https://en.wikipedia.org/wiki/Qualcomm_MSM_Interface). +These APIs allow you to send and receive data, manage connections, and configure various modem +functions, offering a high level of control and customization. + +Currently, EVE stays away from managing modem's firmware and expects a modem unit to be fully +configured by a hardware manufacturer to (preferably) provide a QMI or MBIM interface. + +### wwan microservice + +All components responsible for managing cellular modem devices and connections (including 3G, 4G, and 5G) +are enclosed within a self-contained [wwan container](../pkg/wwan). In the initial stages of development, +we constructed a rather limited management agent using a shell script, which controlled modems +through CLI (Command Line Interface) tools provided by the [libqmi](https://www.freedesktop.org/wiki/Software/libqmi/) +and [limbim](https://www.freedesktop.org/wiki/Software/libmbim/) libraries. Several releases later, +[we made the strategic decision](https://wiki.lfedge.org/display/EVE/ModemManager+Evaluation) +to transition to the use of [ModemManager](https://modemmanager.org/), aligning with the approach +adopted by many standard Linux distributions. In doing so, we only had to implement a lightweight +agent in Go, called [mmagent](../pkg/wwan/mmagent), which serves as an intermediary, facilitating +translations between the EVE API and ModemManager API. + +For a comprehensive understanding of the wwan microservice's implementation details, we encourage +you to consult the documentation available at [wwan/README.md](../pkg/wwan/README.md). + +### Cellular configuration + +Cellular configuration for a given modem is defined within the `CellularConfig` proto message, +as specified in [netconfig.proto](https://github.com/lf-edge/eve-api/blob/main/proto/config/netconfig.proto). +To accommodate future multi-SIM capabilities, the formerly used singleton attribute `APN` has been +deprecated. Instead, the configuration now entails an array of `CellularAccessPoint` entries, +one for each SIM slot. Presently, it is typical to have only a single entry in this list submitted +by the controller. + +Beyond specifying the Access Point Name (APN), this versatile configuration allows for fine-tuning +access points, including options for PAP or CHAP-based username/password authentication, +toggling roaming on or off, designating preferred network operators, and establishing an order +of preference for Radio Access Technologies (RATs). This comprehensive API empowers users to tailor +cellular connectivity settings to suit various network scenarios and SIM card configurations. + +### Cellular info and metrics -## Cellular GSM Modems - -Compared to WiFi, cellular GSM modems present a major challenge. This is partially understandable, since radio regulations in different countries tend to be partially incompatible and at times [simply insane](https://www.afcea.org/content/disruptive-design-have-you-seen-flurry-acts-5g-security). All of this conspires to create a technology landscape where modem manufacturers are forced to produce highly capable and highly configurable units that take onto very different personalities when loaded with firmware and given their final configuration. - -Given the complexity of the task that a GSM modem has to perform, it is no wonder that they evolved to be self-contained computers with very sophisticated internal state. This comparison with remote computers/servers is especially apt, since the way you can interact with this device is very API-driven with pretty much zero offloading to the host Linux kernel. Just like you would talk to a remote cloud service using a REST API you would talk to a GSM Modem using: AT commands, MBIM or QMI API. - -Currently, EVE stays away from managing GSM modem's firmware and expects a modem unit to be fully configured by a hardware manufacturer to provide a [QMI interface](https://en.wikipedia.org/wiki/Qualcomm_MSM_Interface). - -### Enabling a new GSM modem (or debugging an existing one) - -As with any hardware, you will typically go through the following steps: - -1. making sure that the modem device is connected to the host edge node through one of the common buses (this doesn't guarantee that the host can communicate with the device, but at least you should see it registered on the bus) -2. making sure that the modem is configured in such a way that you can actually communicate with it -3. making sure that you can drive the modem and instruct it to connect to the wireless provider -4. making sure that a modem connected to the wireless provider can establish a data connection and reflect it back to the host as a network interface (typically `wwanX`) - -#### 1. Basic bus connectivity - -Almost all well known GSM modems get hooked to a USB bus (most of them communicate using USB2 but some try USB3 and then [trouble may ensue](https://forum.sierrawireless.com/t/mc7455-not-recognized-at-boot/9735) and you may need to [do soldering](https://forum.sierrawireless.com/t/effect-of-removing-usb-3-0-pins-of-mc7455/12702/2)). From there, a single device will expose different interfaces to accommodate various ways of interacting with it. These include: - -* traditional serial interface capable of accepting AT-commands (popular choices of drivers include [Qualcomm's qcserial](https://github.com/torvalds/linux/blob/master/drivers/usb/serial/qcserial.c) and [Sierra Wireless serial](https://github.com/torvalds/linux/blob/master/drivers/usb/serial/sierra.c)). This interface is NOT capable of directly transmitting Ethernet frames and requires an old-school PPP support -* traditional serial interface used for special purposes such as [GPS NMEA port](https://en.wikipedia.org/wiki/NMEA_0183) or [Diagnostic Monitoring](https://forum.sierrawireless.com/t/sierra-linux-qmi-dmcapture-sh-not-working/6373) -* One of the CDC (no, not [that CDC](https://www.cdc.gov/) - rather [communications device class](https://en.wikipedia.org/wiki/USB_communications_device_class)) interfaces capable of direct transport of Ethernet frames: - * [CDC MBIM](https://www.kernel.org/doc/Documentation/networking/cdc_mbim.txt) - * [CDC QMI](https://en.wikipedia.org/wiki/Qualcomm_MSM_Interface) - -To put it all together, a single GSM modem is likely to look something like this when inspected by the `lsusb -t` command: - -```console -/: Bus 01.Port 1: Dev 1, Class=root_hub, Driver=ehci-pci/2p, 480M - |__ Port 1: Dev 2, If 0, Class=Hub, Driver=hub/4p, 480M - |__ Port 2: Dev 3, If 0, Class=Hub, Driver=hub/4p, 480M - |__ Port 4: Dev 7, If 0, Class=Vendor Specific Class, Driver=qcserial, 480M - |__ Port 4: Dev 7, If 3, Class=Vendor Specific Class, Driver=qcserial, 480M - |__ Port 4: Dev 7, If 8, Class=Vendor Specific Class, Driver=qmi_wwan, 480M - |__ Port 4: Dev 7, If 2, Class=Vendor Specific Class, Driver=qcserial, 480M -``` - -#### 2. Communicating with the modem on various USB interfaces - -Our previous example had a modem that is Device 7 on Port 4 exposing 4 different interfaces: 3 serial ones and one QMI CDC. This magic number of 4 interfaces is interesting because most modems insist on mapping all of their different APIs to just 3 USB interface endpoints (this is really bizarre since its not like USB interface endpoints are a scarce commodity). This mapping is called a *usb composition* and it can be programmed by either issuing an appropriate AT command (typically `at!usbcomp=1,1,10d`) on a serial end point or by issuing a CDC/QMI command (if one of those interfaces is available). Sadly, there's no standard when it comes to AT commands (and worse yet whatever AT commands are available may not actually be able to program all of the usb compositions) and your best bet is something like (note that swi in --dms-swi stands for Sierra Wireless): - -```bash -$ qmicli --device-open-mbim -p -d /dev/cdc-wdm0 --dms-swi-get-usb-composition -[/dev/cdc-wdm0] Successfully retrieved USB compositions: - USB composition 6: DM, NMEA, AT, QMI - [*] USB composition 8: DM, NMEA, AT, MBIM - USB composition 9: MBIM -$ qmicli --device-open-mbim -p -d /dev/cdc-wdm0 --dms-swi-set-usb-composition=6 -``` - -If all else fails you may try [swi_setusbcomp script](https://github.com/mavstuff/swi_setusbcomp) to switch to a desired USB composition: - -```bash -$ swi_setusbcomp.pl --device=/dev/cdc-wdm0 - 6 => 'DM NMEA AT QMI', - 7 => 'DM NMEA AT RMNET1 RMNET2 RMNET3', - 8 => 'DM NMEA AT MBIM', - 9 => 'MBIM', - 10 => 'NMEA MBIM', -swi_setusbcomp.pl --device=/dev/cdc-wdm0 --usbcomp=6 -``` - -Regardless of how you arrive at the desired USB composition, make sure to reboot and watch out for the following device and device drivers: - -* `/dev/ttyUSB2` and qcserial driver serving as serial AT command capable endpoint -* `/dev/ttyUSBX` and qcserial and option (yes somebody had enough sense of humor to call a driver option) -* `/dev/cdc-wdm0` and either qmi_wwan or cdc_mbim drivers for QMI and MBIM endpoints - -Even though MBIM is more of a standard EVE prefers QMI over it simply because QMI uses a more reliable NCM protocol underneath (after all MBIM is just the NCM protocol + a signaling channel and QMI is just the ECM protocol + a signaling channel). ECM is the Ethernet Control Model and NCM is the Network Control Model. ECM is an earlier standard and has some issues with latency while NCM resolves those issues and is designed for high speed operation. You can read more [here](https://en.wikipedia.org/wiki/Ethernet_over_USB#Protocols). - -#### 3. Connecting to the wireless provider - -While GSM modems may connect to any compatible wireless provider (roaming), depending on the SIM settings the state machine may only allow a very restricted kind of roaming (emergency calls only). It is tempting to think that open source software can drive much of this state machine, but in reality, we can rely on a modem+SIM doing the right thing and connecting to the given provider at a basic level. Once that happens we have a bit of control in driving the rest of the state machine that can give us a data connection. - -All the configuration that makes your modem connect to a desired wireless provider resides in SIM and modem's NVRAM. Both of these settings are expected to be done once before the hardware unit ships and EVE stays away from fiddling with these. Still, sometimes it is important to troubleshoot basic (non-data) wireless connectivity issues and most of the time you would use AT commands for that. - -When it comes to controlling GSM modems via AT commands, there's not much of a standard. Different vendors use different commands and worse yet the state machines of how modems operate tend to be very different. Some vendors (e.g. Sierra Wireless) [publish](https://source.sierrawireless.com/resources/airprime/minicard/74xx/4117727-airprime-em74xx-mc74xx-at-command-reference/#sthash.fPZTyQtd.dpbs) reasonably detailed references, but even those don't really contain enough details. Various [forums](https://ltehacks.com/viewtopic.php?t=33) tend to be a good source of information for what may work. In addition to that, here's a minimum set of AT commands to keep in mind when debugging GSM modem issues (they are roughly in order you'd use them): - -* `AT!RESET` and `AT+CFUN=0` followed by `AT+CFUN=1,1` for resetting the modem -* `AT!ENTERCND="A710"` enter super user mode -* `AT+CPIN?` for working with SIM (make sure SIM is ready to use) -* `AT+CREG?` for figuring out network registration (make sure you are registered in the home network) -* `AT+COPS=?` for showing available networks and `AT+COPS=0` for triggering the network registration or `AT+COPS=1,2,"xxxxx",7` to manually connect to a given provider -* `AT+CSQ` (and especially `+WIND:`) for finding out signal quality and the connections -* `AT+CGATT=1` for attaching to the service -* `AT+CGDCONT?` and `AT+CGDCONT=1,"IP","apn.tmobile.com"` for defining Packet Data Protocol (PDP) context -* `AT+CGACT=1,1` for activating one of the PDP contexts -* `AT+CGPADDR=1` for requesting an IP address assigned by the context -* `AT!USBCOMP=1,1,10d` for changing USB composition -* `ATI` for general information and `AT!entercnd="A710"` (for Sierra Wireless) to enter extended command set -* `$GPS_START` to start receiving GPS data on a lot of Qualcomm modems - -For example, the following may be a reasonable session to initialize your modem using AT commands: - -```bash -picocom -b 115200 /dev/ttyUSB2 - -ati -at!entercnd="A710" -at+cpin? - READY -at!custom="IPV6ENABLE",1 -at+cgdcont=1,"ipv4v6","vzwinternet" -at!selrat=06 -at!usbcomp = 1,1,1009 -at!reset -``` - -#### 4. Establishing a data connection - -Once your modem reliably connects to your desired wireless provider, the final step is making sure that you can request a data connection. Data connection is layered on top of the basic GSM connectivity and requires you knowing a recommended APN and credentials that are needed to connect to it (both can be set dynamically by EVE's controller). Managing that data connection is the job of EVE's [wwan](../pkg/wwan) package and that is all that it does (e.g. it does NOT manage firmware or basic GSM connectivity). `wwan` package uses `uqmi` utility to talk to the QMI-enabled USB endpoint (typically `/dev/cdc-wdmX`) and goes through the following stages: - -```bash -# wait for modem to register with the network -uqmi --get-serving-system -# start data connection -uqmi --start-network --apn YOUR_APN --keep-client-id wds -# wait for data connection to be established -uqmi --get-data-status -# wait for IP setting (addr, DNS, etc.) to be available -uqmi --get-current-settings -``` - -In general, a single GSM modem can actually multiplex between different data networks (and thus provide multiple network interfaces) this is very rarely done in practice (and EVE certainly doesn't support it) but you need to keep in mind that each of these networks is distinguished by a separate Packet Data Handle (PDH) value. For example, your `uqmi --start-network ...` command will return a unique PDH handle back to you and if you ever want to reference that particular data connection you'll have to either use that value or use a catchall one `0xFFFFFFFF`. - -Another concept that you will encounter when looking at QMI/MBIM protocols is that of a Client ID (CID). Think of it as an HTTP token in REST APIs -- something that uniquely identifies a stateful connection with a given client. If you're issuing a series of QMI/MBIM commands as a transaction you want to keep client ID the same for all of them. Take a look at how [this script](https://github.com/freedesktop/libqmi/blob/master/utils/qmi-network.in) handles both PDH and CID. - -This idea of an token guaranteeing an active connection is actually a pretty important one. For example, another popular script for attaching to data connection in [MBIM mode](https://github.com/freedesktop/libmbim/blob/master/utils/mbim-network.in) goes out of its way to keep a single active connection between different invocations of the `mbimcli` utility (look for how it uses `--no-open` and `--no-close` options and caches transactions IDs so that the next call to `mbimcli` can pick it up and use it as an argument for `--no-open`) - -### Frequencies and antennas - -At some point you will have to care about frequencies and antennas. Most Sierra Wireless modems support all frequencies and both FDD-LTE and TDD-LTE (which are just two different ways of splitting upstream and downstream bandwidth). You can check on cellmapper.net which channels are supported by the cell towers near you and look up the corresponding frequencies [here](https://www.wiserepeater.com/4g-lte-bands-and-frequencies-tdd-fdd-lte). You can then either get a wideband antenna that covers all of the frequencies supported by your modem and the cell tower, or you can pick one or two frequencies and get an antenna for just those frequencies. Usually wideband antennas that support multiple frequencies don't have as much gain. You might want to try forcing your modem to use each of the frequencies in turn and check the bandwidth during peak times before you decide on the best antenna. +The list of all cellular modems visible to the host (incl. the unused ones, without network config attached), +is published in `ZInfoDevice.cell_radios`. The `name` of each modem is simply a string that EVE guarantees +to be unique among all the modems in the list (for example IMEI if available). Information provided for each +modem may include IMEI (a globally unique modem ID), hardware model, firmware version, operating state +([radio silence](#radio-silence) is one of the states) and the protocol used for management (QMI or MBIM). -For the MC7455 you will probably need pigtails (antenna adaptors) from u.fl to either SMA or N-type connectors depending on your antenna. Other modems like the EM7565 use MHF4 connectors instead of u.fl. Remember that the longer the cable from your modem to the antenna, the more signal you will loose. +The list of all SIM cards inserted into cellular modems is published in `ZInfoDevice.sims`. The `name` of each +SIM card is simply a string that EVE guarantees to be unique among all the SIM cards in the list (for example +ICCID if available). Information provided for each SIM card may include ICCID (a globally unique SIM ID), +IMSI (a mobile subscriber identity) and a reference to the name of the modem to which it is inserted. +SIM card state is a string instead of enum because the set of possible values differs between QMI and MBIM. +But some SIM states are common: -### Firmware +* `absent`: SIM card is not present in the SIM slot. +* `present`: SIM card is present in the SIM slot (and there is no issue detected). +* `inactive` : SIM slot is not activated (SIM card presence may be unknown). +* `error`: SIM slot/card is in failed state. -The fact that EVE itself stays out of Firmware upgrade business means that you may get into it. [Bootable ISO from Daniel E Wood](https://github.com/danielewood/sierra-wireless-modems) is probably the best option at this point. +Every device port associated with a cellular modem has `wireless_status` defined. +It contains references to the names of the modem and the SIM card(s) being used, information +about the currently used network provider (identified by PLMN code), and potentially, +error messages if EVE failed to apply the last configuration for this port or if connectivity +testing is failing. -### Open Source projects with focus on GSM modem support +It is also possible to request information about all visible providers by enabling +the [configuration property](CONFIG-PROPERTIES.md) `wwan.query.visible.providers`. +By default, this feature is disabled because the operation to scan visible cellular providers +is quite expensive and takes around 2 minutes to complete, during which the modem is practically +unmanageable. Therefore, even if enabled, the period for re-scanning visible providers +is quite long: 1 hour. For the user, it makes sense to enable scanning only temporarily, +for example, when troubleshooting a modem that is failing to register on the network. -Aside from vendor and system integrator's forums, a lot of great information and software is available at [ROOter Of Modems and Men](https://www.ofmodemsandmen.com/) and [Daniel Wood's GitHub](https://github.com/danielewood/sierra-wireless-modems). +EVE also collects metrics from cellular modems (i.e. stats recorded by modems themselves, not from the Linux +network stack). These are published in `deviceMetric.cellular`. Included are packet and byte RX/TX +counters, drop/error counters and information about the signal strength: RSSI, RSRQ, RSRP, SNR. +Note that with MBIM control protocol, only RSSI is available. The maximum value of int32 (`0x7FFFFFFF`) +represents unspecified/unavailable metric (zero is a valid value). ## Radio Silence @@ -186,12 +158,13 @@ that the radio silence mode is switched ON and OFF locally and not managed remot With these requirements in mind, EVE was designed to use the [Local profile server](https://github.com/lf-edge/eve-api/tree/main/PROFILE.md) (a designated application overriding controller for a small subset of the config) with a separate -[Radio endpoint](https://github.com/lf-edge/eve-api/tree/main/PROFILE.md#Radio), to periodically obtain the required state of the radio -silence mode and to publish the actual state. Intentionally, it is not possible to enabled or disable -radio silence remotely through the controller. Still, the controller is at least used to deploy -the application, mark it as a Local profile server and to specify string token that the application -will have to present to EVE with each request to authenticate itself. This is submitted to the edge -node using the `local_profile_server` and `profile_server_token` fields from `EdgeDevConfig`. +[Radio endpoint](https://github.com/lf-edge/eve-api/tree/main/PROFILE.md#Radio), to periodically +obtain the required state of the radio silence mode and to publish the actual state. Intentionally, +it is not possible to enable or disable radio silence remotely through the controller. Still, +the controller is at least used to deploy the application, mark it as a Local profile server +and to specify string token that the application will have to present to EVE with each request +to authenticate itself. This is submitted to the edge node using the `local_profile_server` and +`profile_server_token` fields from `EdgeDevConfig`. #### Radio endpoint semantic @@ -205,20 +178,21 @@ state, EVE will start periodically making a POST request to the [Radio endpoint] If this (optional) endpoint is not implemented, the default policy for radio transmission will remain in effect. If the endpoint is available, EVE will provide an update of the current state of wireless devices in the POST request body, formatted and marshalled using -the [RadioStatus](./proto/profile/local_profile.proto) proto message. This includes the state -of the radio silence mode, information about cellular modem(s) and SIM card(s), signal strength -metrics and packets counters as recorded by modem(s). Note that currently the state information -is limited to cellular connectivity and does not cover WiFi network adapters. +the [RadioStatus](https://github.com/lf-edge/eve-api/blob/main/proto/profile/local_profile.proto) +proto message. This includes the state of the radio silence mode, information about cellular modem(s) +and SIM card(s), signal strength metrics and packets counters as recorded by modem(s). +Note that currently the state information is limited to cellular connectivity and does not cover +WiFi network adapters. If a response from the application contains no content (response code 204), EVE assumes that the intended radio silence state has not changed (initial intended state is a disabled radio silence). Application response with non-empty content (response code 200) is unmarshalled into -[RadioConfig](https://github.com/lf-edge/eve-api/tree/main/proto/profile/local_profile.proto) protobuf message. If the unmarshalling -succeeded and the token matches the expected value configured through the controller, -EVE will accept the new radio configuration. Currently, apart from the token, RadioConfig -contains only a single boolean field which determines if the radio silence should be imposed -or lifted. +[RadioConfig](https://github.com/lf-edge/eve-api/tree/main/proto/profile/local_profile.proto) +protobuf message. If the unmarshalling succeeded and the token matches the expected value +configured through the controller, EVE will accept the new radio configuration. Currently, +apart from the token, RadioConfig contains only a single boolean field which determines +if the radio silence should be imposed or lifted. Whenever the newly received intended state of the radio silence mode differs from the currently applied state, EVE will trigger an operation of switching radio transmission @@ -298,10 +272,9 @@ should be aware of, especially if used for safety-critical use-cases. Run `rfkill` command from the debug console and look for a table entry with `wlan` TYPE. For some devices it may be necessary to enable certain `*_RFKILL=y` kernel parameters to build their drivers (e.g. `CONFIG_ATH9K_RFKILL=y`). -* For cellular modems we use QMI and MBIM protocols for management. Both of these protocols - provide APIs to enable/disable radio transmission. However, cellular modems that do not - support any of these protocols (and likely only AT commands), cannot be managed by EVE - and the radio transmission will remain in the modem's default state (which usually is ON). +* Cellular modem must be [supported by ModemManager](https://www.freedesktop.org/wiki/Software/ModemManager/SupportedDevices/), + otherwise it will not be recognized and the radio transmission will remain in the modem's + default state (which usually is ON). * Radio silence only applies to wireless network adapters which are visible to EVE (host OS). Adapters directly assigned to applications are not covered. It is up to those applications to manage the state of radio transmission. @@ -327,48 +300,3 @@ should be aware of, especially if used for safety-critical use-cases. do support persistence. * The last limitation (not really a risk) is that by design the local profile override and the radio silence mode both have to be managed by the same application. - -## Cellular info and metrics - -The list of all cellular modems visible to the host (incl. the unused ones, without network config attached), -is published in `ZInfoDevice.cell_radios`. The `name` of each modem is simply a string that EVE guarantees -to be unique among all the modems in the list (for example IMEI if available). Information provided for each -modem may include IMEI (a globally unique modem ID), hardware model, firmware version, operating state -(radio silence is one of the states) and the protocol used for management (QMI or MBIM). - -The list of all SIM cards inserted into cellular modems is published in `ZInfoDevice.sims`. The `name` of each -SIM card is simply a string that EVE guarantees to be unique among all the SIM cards in the list (for example -ICCID if available). Information provided for each SIM card may include ICCID (a globally unique SIM ID), -IMSI (a mobile subscriber identity) and a reference to the name of the modem to which it is inserted. -SIM card state is also defined but currently not provided. - -Every device port associated with a cellular modem has `wireless_status` defined. -It contains references to the names of the modem and the SIM card(s) being used, information -about the currently used network provider (identified by PLMN code), and potentially, -error messages if EVE failed to apply the last configuration for this port or if connectivity -testing is failing. - -It is also possible to request information about all visible providers by enabling -the [configuration property](CONFIG-PROPERTIES.md) `wwan.query.visible.providers`. -By default, this feature is disabled because the operation to scan visible cellular providers -is quite expensive and takes around 2 minutes to complete, during which the modem is practically -unmanageable. Therefore, even if enabled, the period for re-scanning visible providers -is quite long: 1 hour. For the user, it makes sense to enable scanning only temporarily, -for example, when troubleshooting a modem that is failing to register on the network. - -EVE also collects metrics from cellular modems (i.e. stats recorded by modems themselves, not from the Linux -network stack). These are published in `deviceMetric.cellular`. Included are packet and byte RX/TX -counters, drop/error counters and information about the signal strength: RSSI, RSRQ, RSRP, SNR. -Note that with MBIM control protocol, only RSSI is available. The maximum value of int32 (`0x7FFFFFFF`) -represents unspecified/unavailable metric (zero is a valid value). - -## References - -* [Sierra Wireless MC7455 stuck in MBIM-only USB composition](https://forum.sierrawireless.com/t/mc7455-stuck-in-mbim-only-usb-composition/8499) -* [AirPrime EM74xx-MC74xx AT Command Reference](https://source.sierrawireless.com/resources/airprime/minicard/74xx/4117727-airprime-em74xx-mc74xx-at-command-reference/#sthash.fPZTyQtd.dpbs) -* [Network Registration Issues](https://forum.sierrawireless.com/t/problem-about-network-registration/4333) -* [Sierra Wireless MC7455 | EM7455 -- AT! Command Guide](https://ltehacks.com/viewtopic.php?t=33) -* [Minicard GPS operation](https://forum.sierrawireless.com/uploads/short-url/2qSQfE8H2hxdS1kS3mdYtSWGtpr.pdf) -* [Gateworks LTE Guide](http://trac.gateworks.com/wiki/wireless/modem) -* [Embedded Pi documentation](http://www.embeddedpi.com/documentation/3g-4g-modems) -* [How to use 4G LTE modems like the MC7455 on both Debian/Ubuntu and OpenWRT using MBIM](https://gist.github.com/Juul/e42c5b6ec71ce11923526b36d3f1cb2c) diff --git a/pkg/pillar/docs/nim.md b/pkg/pillar/docs/nim.md index 7780992105c..7df1b6ca393 100644 --- a/pkg/pillar/docs/nim.md +++ b/pkg/pillar/docs/nim.md @@ -35,6 +35,9 @@ to move to the most recent, aka the highest-priority configuration. * zedagent status * an instance of `ZedAgentStatus` received from zedagent * used to determine the intended state of the [Radio-Silence mode](./radio-silence.md) +* status of cellular connectivity + * an instance of the `WwanStatus` struct received from `mmagent` (wwan microservice) + * used to update `NetworkPortStatus` of cellular ports **NIM publishes**: @@ -45,8 +48,9 @@ to move to the most recent, aka the highest-priority configuration. * ordered by priority, the highest priority is at index 0 * contains index pointing to the currently used config * persisted publication - NIM is able to read it back and reapply after a reboot -* WWAN metrics - * received from wwan microservice and just forwarded further via pubsub +* configuration for cellular modems + * an instance of the `WwanConfig` struct + * consumed by `mmagent` from the wwan microservice ## Components diff --git a/pkg/pillar/docs/pics/nim.png b/pkg/pillar/docs/pics/nim.png index 9911ddd906e..e0aa51c068e 100644 Binary files a/pkg/pillar/docs/pics/nim.png and b/pkg/pillar/docs/pics/nim.png differ diff --git a/pkg/pillar/docs/pics/nim.xml b/pkg/pillar/docs/pics/nim.xml index 8d21fe7fc8b..cb2009830b7 100644 --- a/pkg/pillar/docs/pics/nim.xml +++ b/pkg/pillar/docs/pics/nim.xml @@ -1,2 +1,137 @@ -7VxNd5s6EP01XqYHEGCzTOw07WnSkxe3p+3byaAYNRhRkBP7/fongcSnYhMHYztpFgkaJAH3jkZXI8gAjBerqxhG/g3xUDAwNG81AJOBYeimo7M/3LLOLI6jZYZ5jD1RqTBM8X9IGGW1JfZQUqlICQkojqpGl4QhcmnFBuOYPFWr3ZOgetUIzlHDMHVh0LT+wB71M+vI0gr7J4TnvryyrokzCygrC0PiQ488lUzgcgDGMSE0O1qsxijg4ElcsnYfnzmb31iMQtqmwfQh8a8vzOsvq8kliL5M/vy5AWeil0cYLMUDi5ula4lATJahh3gn2gBcPPmYomkEXX72iXHObD5dBKyks0MPJn5alxdE3yimaPXsTes5FMyHEFkgGq9ZlVXVDYT3mBLMp4ILU3Lhl3kwhREK/ud51wVE7ECgpEbs0+Ps8TcmcPxd+8e7uXMvVnR2Zgz3D1kDHwWKz0JmOtsx051eMbMbCCGPjTJRJDH1yZyEMLgsrBdVDIs614REAqzfiNK1CBlwSUkVV7TC9Cdv/sESpV+iM348WZULa1kI2eOWGvHiL9kfLxTN0pJs9yxtCVnGLtoAjYxpMJ4juqEeyOpx3DY6QYwCSPFjNXp1TujwL6GvJdQ6KkJ1cDyM6jsxqh2cUeeoGFVMS30yWh6hObtbGTVeRGnCKKHnXOQxQ0hCJG0fMceqJ9qlRDkS3puK7uvnm9cplHsG55gEJE7bAtdF1v19inVMHlDpDLCBAzx+RmrdjRS01zTAqGoa3VZoGkOhaey9ycDtKhCFnnRON4BJgt26zxbmEtpVanaZ9F7t81tduQS7Sn1LW2uPF1e4JZjdccH6qMq6UyMzexzRqLzy2dJP3SmyId7oJ/WL/KF3dxXQcJV/kcfWjeJqXQ1LlP5sHJYdjMR85XCwkWc24JyQBcThYh6fIJ4AHBpPq4Hnt2hxmmCaw0ODOWqAebucTZezBpjsiWgVsSoyQs6UYRQmGOB5yCcPhhNi9guOD3ZhcC5OLLDnpWpORVGVxC4cuBZcdb3Jga2gAOyLAt1szsT9CV990F747j5Pd77UUE+cllbj1nA+OOWfXudR/cBZh+ExL1IFFdtXK0bXrvO6weocltM3QWlb1d5T4kE/KKUviL/7zR+0pu+48gdOU15H7g0M2YKlW0nYIo3QhTypZQ6AQp70KxHlDZQzNIg+kfjhhoSYko6Ft+5ZaKhC2bGHANodoVzbcjIPDbJxMiKwmFcqs0oxybRJftbySyJ+ZZscXi3CMUs3+VHt6Ocn5Za3dVjFYexfcrSZ15TJycI1ir3oGms7+ooima4kB3SxjmEPBtelChFfkSTPL3OAVQ1f1qj2JkWtvjHaWJ8dZHew6+pHicyB99B3XPwwfV9y3DPtgwbAFu9NS7coxgwxnt84dZc2D+HSpv4ylzbt4V5deiOEVa15h1wSujjoWG72JISMY1NCcsFfAnmcvSuHHzFdf0MJPUmkLcM6NqSbmfTb5SzAic+Mk6/TgTHmB7f8N7M2d3/eTE7YqkWf/B3IMjeg16Sw3eBmYNgBh9vDj+xwzg/PPS+lJ+UJBelxVoldtFRP0fR75EGKzs9f2OBqfPvCFnfQw2TKwmPIKBSVZnG9Wb2zt+pphlnzNFUUMBWeZu3N05pbQDzGlmPu26XDrCljMLQadPS6GWQ0ky25vpDB+K2SUV+m5Dt15bGhqdiw9sVG81UIRZy7QjRlhAU7rq8J+zVb4sBrHSivYULvUMLWO5Li9xUU87ej5LadpbecfvdGfFMa/YDU9SW/y3Rq4yWf/3aXcfr4uRe8Wabq7+oDcOgh2kooSfIy3pLWIzMlO0bpyj0DCt8z9Ckm4YCHahsuOM7hLInSDrR3N3Rrega0XdXszyGaekZBrDRhaRBbGmeMaveBkxUhl3NdIhRvE63br3KHooARAmfBZi289VJH6U9dfxlUzwmpVmUqrdyFOlOmxpqpiTakczmNw/kZuwefeH99qyvfetWHepZuHZlzNbXmnjKLE3A5ulTmu0ZDx3RANwAbtcyi3We+6/nEdjV7i6L0M+AThNfUrCODV/WdaSNqlRazLePcuK6tC9mVVj3Li6IH7TOLNil7eZOTzjopvk15lefUJLytKRxn1GfgayXY5Jf6uTu0dB8Yehtc4l06gGn25wGsWPzHgGwfrvi/C+Dyfw== \ No newline at end of file + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/pkg/pillar/docs/radio-silence.md b/pkg/pillar/docs/radio-silence.md index 61cc7eca4be..4ff2326aea3 100644 --- a/pkg/pillar/docs/radio-silence.md +++ b/pkg/pillar/docs/radio-silence.md @@ -11,8 +11,9 @@ Radio silence implementation is split between 3 EVE microservices: In the request body, it publishes the current state of all used wireless devices, which it obtains from the `DeviceNetworkStatus` (`DNS` for short; the message is received from NIM). Radio silence status in encapsulated by `RadioSilence` structure, embedded into `DNS`. It contains a `ChangeInProgress` - boolean, which NIM uses to inform that an operation of switching radio silence ON/OFF is still in progress - and that zedagent should therefore pause Radio endpoint POST requests until it finalizes. + boolean, which NIM (specifically DPCManager component) uses to inform that an operation of switching + radio silence ON/OFF is still in progress and that zedagent should therefore pause Radio endpoint + POST requests until it finalizes. Whenever the Local profile server responds with a radio silence configuration that differs from the current state, zedagent will record the new intended radio state into `RadioSilence` structure @@ -30,34 +31,52 @@ Radio silence implementation is split between 3 EVE microservices: `ChangeRequestedAt` from `ZedAgentStatus.RadioSilence` to `DeviceNetworkStatus.RadioSilence`, sets `ChangeInProgress` to `true` and starts switching radios of wireless devices ON/OFF. For WiFi adapters, this is done by directly [calling the rfkill command](../devicenetwork/wlan.go). - For cellular modems, NIM updates the configuration file `/run/wwan/config.json`, which is picked up - by the `wwan` microservice, and waits for the status update published in `/run/wwan/status.json` (see below). + For cellular modems, NIM updates and publishes new `WwanConfig` via pubsub, which is received + by `mmagent` of the `wwan` microservice. NIM then waits for the status update from `wwan` + published through pubsub topic `WwanStatus`. To avoid NIM processing obsolete `WwanStatus`, + corresponding to an older `WwanConfig` and thus not reflecting the latest radio config, a timestamp + is appended to `WwanConfig` by NIM (as max of `ChangeRequestedAt` from `ZedAgentStatus.RadioSilence` + and `TimePriority` of the latest DPC), which is copied to `WwanStatus` by `mmagent` only once this + config has been fully applied. Using this mechanism, NIM is able to ignore obsolete wwan status + updates. + Once NIM is done with all radio devices, it updates `RadioSilence` of `DeviceNetworkStatus` and sets `ChangeInProgress` to false and `Imposed` (boolean) to reflect the actual radio silence state - (could be different from the intended state if operation failed). If the operation fails, it also shares - all error messages with zedagent, to be published up to the Local profile server. - -* `wwan`: Microservice implemented as a [shell script](../../wwan/usr/bin/wwan-init.sh), which manages - cellular modems, including the state of radio transmission. It receives the intended configuration - from NIM through the file `/run/wwan/config.json`. A boolean field `radio-silence` is used to order - the microservice to either enable or disable radio transmission on all cellular modems visible to the host. - For QMI-controlled modems, it calls `uqmi -d --set-device-operating-mode `. - For MBIM-controlled modems, it calls `mbimcli -d --set-radio-state `. - State updates (including the actual state of radio transmission) is published as `/run/wwan/status.json`. - It includes a SHA256 hash of the last applied configuration. It is used by NIM to wait for a config - update to be fully applied, without any operations still ongoing, and to process and publish status update - which corresponds to the new config. + (could be different from the intended state if operation failed for any of the wireless devices). + If the operation fails, it also shares all error messages with zedagent, to be published up + to the Local profile server. + +* `wwan`: Microservice running [ModemManager](https://modemmanager.org/), controlling WWAN (2G/3G/4G/5G) + devices and connections, and [mmagent](../../wwan/mmagent), a Go program build on top of the pillar + infrastructure (pubsub, agentbase, logging, etc.), acting as a translation layer between declarative + EVE cellular API and imperative ModemManager API. More information about this microservice + can be found in [WIRELESS.md](../../../docs/WIRELESS.md). What is important here, is that the input + (i.e. wwan config) is received by mmagent from NIM via pubsub as `WwanConfig`. A boolean field + `RadioSilence` is used to order the microservice to either enable or disable radio transmission + on all cellular modems visible to the host. mmagent uses [SetPowerState][set-power-state] method + of the [DBus][dbus]-based [ModemManager API][mm-api]. It sets `MM_MODEM_POWER_STATE_LOW` for + a given modem if radio silence is enabled or if the modem is not managed, i.e. it is not configured + by the controller. Otherwise, `MM_MODEM_POWER_STATE_ON` is set to enable radio transmission functions. + State updates (including the actual state of radio transmission) are published as `WwanStatus`. + Included is timestamp of the last applied configuration. As already described above, it is used + by NIM to wait for a config update to be fully applied, without any operations still ongoing, + and to process and publish status update which corresponds to the new config. To summarize, the indented radio configuration flow is: ```text -Local profile server --POST-response--> zedagent --ZedAgentStatus--> NIM --/run/wwan/config.json--> wwan +Local profile server --POST-response--> zedagent --ZedAgentStatus--> NIM --WwanConfig--> wwan (mmagent --SetPowerState--> ModemManager) --> rfkill ((un)block wlan) ``` And the status update flow is: ```text -wwan --/run/wwan/status.json--> NIM --DeviceNetworkStatus--> zedagent --POST-request--> Local profile server - rfkill exit status --> +wwan (ModemManager --(Get)PowerState--> mmagent) --WwanStatus--> NIM --DeviceNetworkStatus--> zedagent --POST-request--> Local profile server + rfkill exit status --> ``` + + +[dbus]: https://www.freedesktop.org/wiki/Software/dbus/ +[set-power-state]: https://www.freedesktop.org/software/ModemManager/api/latest/gdbus-org.freedesktop.ModemManager1.Modem.html#gdbus-method-org-freedesktop-ModemManager1-Modem.SetPowerState +[mm-api]: https://www.freedesktop.org/software/ModemManager/api/latest/ref-dbus.html \ No newline at end of file diff --git a/pkg/wwan/README.md b/pkg/wwan/README.md new file mode 100644 index 00000000000..e08db7e4f4c --- /dev/null +++ b/pkg/wwan/README.md @@ -0,0 +1,918 @@ +# WWAN microservice + +## Overview + +WWAN microservice is responsible for the management of cellular modem devices and connections (3G/4G/5G). +On the northbound API side it receives configuration from NIM and publishes the cellular status +and metrics to zedagent and other microservices using pubsub. +On the southbound API side it controls modems (connect, disconnect, enable radio, etc.), obtains +their attributes (modem IMEI, SIM card ICCID, etc.), monitors their state (modem operational state, +power state, SIM card state, etc.) and periodically retrieves metrics (packet and byte counters). + +It is build as a single container named `wwan` (i.e. can be entered with `eve enter wwan` from console +or SSH connection), running multiple processes. Instead of developing modem management agent from +scratch, EVE uses [ModemManager](https://modemmanager.org/), just like many other standard Linux +distributions. This daemon does most of the heavy lifting in controlling modems. In cooperation with +[udev](https://wiki.archlinux.org/title/udev) it recognizes all available cellular modems, finds +the right protocol to talk to them (preferably QMI or the standardized MBIM), retrieves their state +and subscribes for updates, and finally performs operations like Connect, Disconnect, SetPowerState, +etc., as requested via [DBus](https://www.freedesktop.org/wiki/Software/dbus/) by a higher-level agent. +In standard Linux distributions this is NetworkManager. However, EVE is quite different and NetworkManager +does not fit into the architecture. Instead, we implemented our own agent controlling ModemManager, +called `mmagent`, tailor-made for the specific requirements and characteristics of EVE OS. + +In this document, we describe components of the wwan microservice in detail from the developer perspective. +For a more broad understanding of cellular connectivity in EVE, its use-cases, challenges and high-level +design decisions that were made (such as to use ModemManager), please refer to [WIRELESS.md](../../docs/WIRELESS.md). + +## ModemManager + +ModemManager (sometimes abbreviated to MM in this document) is a system daemon which controls +WWAN (2G/3G/4G/5G) devices and connections. Alongside NetworkManager, ModemManager is the default mobile +broadband management system in most standard GNU/Linux distributions (Debian, Fedora, Ubuntu, +Arch Linux…), and is also available in custom systems built with e.g. buildroot, yocto/openembedded +or ptxdist. ModemManager may also be used in routers running openwrt. + +MM provides a standardized and consistent interface for interacting with different types of modems, +such as USB dongles, embedded cellular modules or RS232 modems, enabling seamless integration of these +devices into the Linux ecosystem. MM uses plugin architecture, where each plugin is a dynamically +loaded library implementing a MMPlugin interface for a class of modems. For example, there is +`libmm-plugin-sierra.so` implementing support for modems from Sierra Wireless. As of this writing, +there are 48 plugins in total, covering all relevant modem manufacturers out there. + +ModemManager is an actively developed project with contributions from a diverse group of developers +and maintainers, the main one being [Aleksander Morgado](https://aleksander.es/). +The project is hosted on [freedesktop.org](https://www.freedesktop.org/wiki/) and licensed under +GNU LGPLv2.1. It is written in C, using [glib](https://docs.gtk.org/glib/) and [gio](https://docs.gtk.org/gio/). + +Here are some useful links related to ModemManager: + +* [Official Website](https://www.freedesktop.org/wiki/Software/ModemManager/) with detailed information + about ModemManager, its features, and its usage. +* [Repository](https://gitlab.freedesktop.org/mobile-broadband/ModemManager) with the source code + and issue tracking. +* [Comprehensive documentation](https://www.freedesktop.org/software/ModemManager/api/latest/) + also describes [ModemManager API](https://www.freedesktop.org/software/ModemManager/api/latest/ref-dbus.html) +* [Mailing List](https://lists.freedesktop.org/archives/modemmanager-devel/) allows to stay updated + with the latest developments and discussions about ModemManager. + +### ModemManager interfaces + +Important from the EVE development perspective, is to understand how ModemManager interacts with +the operating system. MM and its dependencies are typically started by [systemd](https://systemd.io/). +However, this is optional and MM can be built without systemd support. MM uses +[libqmi](https://www.freedesktop.org/wiki/Software/libqmi/), [libmbim](https://www.freedesktop.org/wiki/Software/libmbim/) +and sometimes [AT commands](https://en.wikipedia.org/wiki/Hayes_AT_command_set) +to control modems. These libraries are developed under the same project umbrella as MM and by the same +contributors. ModemManager also depends on [udev](https://wiki.archlinux.org/title/udev) to discover +modems and to detect hardware changes (modem (dis)connected from USB port etc.). + +ModemManager is controlled using APIs exposed via [DBus](https://www.freedesktop.org/wiki/Software/dbus/). +These APIs are imperative in nature, meaning that for a declaratively defined config, there must be an agent +translating the config into the corresponding sequence of MM API calls with the right arguments. +These APIs allow getting state data, metrics, calling methods and watching for notifications +(aka signals in the DBus terminology). There is a detailed documentation for +[MM application interface](https://www.freedesktop.org/software/ModemManager/api/latest/ref-dbus.html), +describing all DBus interfaces, objects, signals, properties and methods provided by MM. DBus daemon +is therefore a mandatory dependency of MM. Also used is [Polkit](https://wiki.archlinux.org/title/Polkit) +to define and handle policy restricting access to these DBus APIs, but this is optional. +Access can be allowed for any DBus client (that is able to access DBus UNIX socket) and Polkit +does not have to be installed. + +MM on its own does not do much, just discovers modems and allows to print some details about them +using a CLI tool [mmcli](https://www.freedesktop.org/software/ModemManager/man/1.0.0/mmcli.8.html). +In standard Linux distributions, it is up to NetworkManager daemon to: + +* tell ModemManager what it should do, e.g. connect modem at `` with parameters `` +* obtain IP settings (IP address, gateway IP, DNS servers) and apply them in the network stack + (i.e. this is done by NetworkManager, not MM, which as a result does not depend on the Linux network stack) +* obtain modem state data to then display via UI and nmcli (NetworkManager CLI tool) +* trigger reconnect (if enabled by user) when MM sends notification about a modem losing connection + +## mmagent + +[mmagent](mmagent) is an EVE microservice, leveraging [agentbase](../pillar/agentbase), +[logging system](../pillar/agentlog), [pubsub](../pillar/pubsub), [types](../pillar/types) +and other common packages from pillar. It has similar set of responsibilities as NetworkManager +in standard Linux distributions: + +* Translate declarative configuration of EVE API to imperative DBus calls of MM API. +* Configure wwanX interfaces in the Linux network stack with IP settings obtained from MM (which + receives them from the network provider) +* Try to reconnect modem when it loses connection +* Publish state data, metrics, location info + +The source code of mmagent written in Go is available under the directory [mmagent](mmagent). +The implementation is split into two parts: + +* [mmdbus/Client](mmagent/mmdbus/client.go) abstracts the interaction with ModemManager done over + DBus-based API into a single client object, providing methods to get info about all of available + modems, watch for changes (modem added/deleted, state changed) and to execute operations, + such as Connect, Disconnect, EnableRadio, DisableRadio, etc. +* [MMAgent](mmagent/agent.go) tries to keep the state of cellular modems (aka the actual state) + in-sync with the config received from the controller (aka the desired state). First, it must + translate declarative configuration (received as `WwanConfig`, see the next section) into imperative + calls of mmdbus/Client methods. Next, it must react to state changes notified by modems. For example, + on an event of modem loosing connectivity, the agent requests reconnect. MMAgent also periodically + probes the connectivity by attempting to talk to a remote endpoint over the cellular connection + and triggers reconnect if there are any issues. Finally, it must collect and publish state data, + metrics and potentially also location info to zedagent and other microservices. + +### Input/Output + +**mmagent consumes**: + +* configuration for cellular ports: + * an instance of the `WwanConfig` struct + * contains configuration for every cellular modem, except those which are disabled or directly + assigned to applications +* global configuration properties + * an instance of `ConfigItemValueMap` struct received from zedagent + * option `wwan.query.visible.providers` decides if `mmagent` should scan visible providers + (once per hour for every modem) and publish results alongside `WwanStatus` (costly operation, + by default disabled) + * options `timer.location.cloud.interval` and `timer.location.app.interval` indirectly decide + how frequently should `mmagent` get location update from a modem (with GNSS receiver) + and publish it as `WwanLocationInfo` (see below) +* controller and edge node certificates + * needed to decrypt user password encrypted using [EVE’s object-level encryption method](../../docs/OBJECT-LEVEL-ENCRYPTION.md) + +**mmagent publishes**: + +* state data for all modems: + * an instance of `WwanStatus` + * this includes modem information/status, SIM info/status, network provider info, etc. +* metrics for all connected modems: + * an instance of `WwanMetrics` + * includes packet and byte counters (actually, only byte counters are exposed by MM) +* location coordinates obtained from GNSS receiver of one of the modems + * an instance of `WwanLocationInfo` + * longitude + latitude + altitude + timestamp from the GNSS receiver + * only if location tracking is enabled and location info is available (good enough signal) + +Subscribers of these publications are: + +* zedagent: to forward status, location and metrics to LPS, LOC and controller +* NIM: to build DeviceNetworkStatus +* zedrouter: to publish status and location to apps via metadata HTTP server + +## Limitations + +There are few things not exposed by ModemManager API. For example, packet and drop counters +are not available and only byte counters can be retrieved. Also, it is not possible to differentiate +between inactive SIM slot with SIM card inserted and inactive SIM slot without SIM card. +With `qmicli --uim-get-slot-status` / `mbimcli --ms-query-slot-info-status` we can tell these +states apart, so it is not a limitation of QMI/MBIM or libqmi/libmbim. +Next, for a visible network provider (which is scanned and published if `wwan.query.visible.providers` +is enabled), we cannot tell if roaming is required (we publish that as a boolean flag). +Again, this is available with QMI/MBIM. +Neither of these are particularly important features and these gaps could be filled in with +our future contributions to ModemManager. + +In terms of our `mmagent` implementation, the only notable limitation is that between +[Static, DHCP and PPP bearer IP methods](https://www.freedesktop.org/software/ModemManager/api/latest/ModemManager-Flags-and-Enumerations.html#MMBearerIpMethod), +only Static is supported. With modern modems implementing QMI/MBIM protocols, the PPP method, +which merely emulates a legacy analog modem, is no longer recommended and rarely used these +days due to its performance and other limitations. It is therefore up to our consideration +if supporting PPP for cellular connectivity in EVE is worth the extra effort and additional +dependencies (pppd or some implementation in Golang). And as for DHCP, we haven’t yet received +any request from EVE users to support DHCP client running on the wwan interface. It seems, +that at least the modems supported and verified on EVE always pass full IP configuration +to the host, thus it is not necessary to run a DHCP client on the host. However, since we already +support DHCP for ethernet interfaces, this could be implemented with little effort and no extra +dependencies (NIM would be told by the wwan microservice to start dhcpcd for wwan* interface as well). + +## Architecture + +Cellular connectivity in EVE involves multiple components operating across different layers +in both user-space and kernel-space. It begins with a physical cellular modem connected via a USB +interface, exchanging control messages with the host over a CDC-WMC channel, operated on the host +side by the cdc-wdm driver. Kernel modules like qmi_wwan and cdc_mbim use this channel to facilitate +communication between the user-space of the host and the cellular modem in the language of QMI/MBIM +protocols, while user-space libraries libqmi and libmbim provide high-level client-facing C-bindings +for these protocols. +The ModemManager user-space daemon serves as a central manager, handling modem initialization, +network registration, and data connection management, ensuring a standardized and unified interface +for cellular modem communication on Linux systems. It uses libqmi and libmbim libraries and in some +cases also AT command set to interact with and manage modems. +On top of that, our `mmagent` acts as an adapter between the declarative EVE API and +the imperative ModemManager API, plus it manages the IP settings of the wwan network interfaces +in the Linux network stack. +Moreover, there are some additional tools installed in the wwan container, such as mmcli, qmicli, +mbimcli, which are provided solely for the troubleshooting purposes. +Diagram belows depicts hierarchy and placements of all components and how they interact with each other: + +![wwan components](./pics/wwan.png) + +Further information on the topic of cellular connectivity in Linux (not including EVE-specific components): + +* [This document](https://aleksander.es/data/Qualcomm%20Gobi%20devices%20on%20Linux.pdf) describes + principles of the QMI protocol, compares two alternative `qmi_wwan` and `GobiNet` drivers used + in Linux to interact with QMI-enabled modems, and explains why `qmi_wwan` is preferred and used + by ModemManager (in summary: with `qmi_wwan` + `libqmi`, the complexity is moved from the kernel + space and into the user space). + Document also mentions why it is no longer needed to setup a PPP session over a serial port + for a cellular connection data-plane. Instead, packets can be sent and received over an ECM/NCM-like + USB interface exposed by the device for better performance and lower overhead. +* [This presentation](https://aleksander.es/data/20210421%20-%20Introduction%20to%20ModemManager.pdf) + introduces ModemManager and depicts how all components involved in cellular connectivity of both + the user-space and the kernel-space fit together. +* [Documentation for cdc_mbim driver](https://docs.kernel.org/networking/cdc_mbim.html) explains + interaction between the cdc_mbim and cdc_wdm drivers. +* [This video presentation](https://www.youtube.com/watch?v=NPeMqK_vFFc) provides a brief overview of + all major components and protocols involved in the cellular modem support in Linux, along with their + evolution. This presentation also touches on the topic of modern high-speed 5G modems connected + over the PCI bus instead of the USB bus for even better performance. In this case, data are transmitted + between the host and the modem using the [MHI protocol](https://docs.kernel.org/mhi/mhi.html). + Control-plane still relies on QMI/MBIM protocols, running on top of MHI, meaning that there is + very little change from the user-space perspective. However, it is important to note that testing + of 5G modems connected via PCI on EVE is still TBD. + +## Troubleshooting + +### PubSub + +Provided that an SSH or a console access to a device is available, it is possible +to print the currently submitted config from NIM to wwan with: +`cat /run/nim/WwanConfig/global.json | jq` + +Similarly, state data published by the wwan microservice can be printed with: +`cat /run/wwan/WwanStatus/global.json | jq` + +To read metrics: +`cat /run/wwan/WwanMetrics/global.json | jq` + +And finally, provided that location tracking is enabled and location information is available +(good enough signal), print the last published location info with: +`cat /run/wwan/WwanLocationInfo/global.json | jq` + +In all cases, it is preferable to run these commands from the pillar container (enter with `eve enter`), +where the `jq` tool is already available (not necessary but makes output much easier to read). + +### mmcli + +ModemManager is installed into the wwan container together with its own CLI tool +[mmcli](https://www.freedesktop.org/software/ModemManager/man/1.0.0/mmcli.8.html). +This tool is included purely for debugging/troubleshooting purposes and is not used by EVE to manage +modems in any way. + +To use it, first enter the wwan container: `eve enter wwan`. + +List all modems recognized by ModemManager with: `mmcli -L`, e.g.: + +```console +$ mmcli -L +/org/freedesktop/ModemManager1/Modem/0 [QUALCOMM INCORPORATED] QUECTEL Mobile Broadband Module +/org/freedesktop/ModemManager1/Modem/2 [Sierra Wireless, Incorporated] Sierra Wireless EM7565 Qualcomm® Snapdragon™ X16 LTE-A +``` + +Notice that every modem is referenced by filesystem-like path, ending with integer number, aka modem index. +Using this index, you can get detailed info for a modem with: `mmcli -m `, e.g.: + +```console +$ mmcli -m 2 + ---------------------------------- + General | path: /org/freedesktop/ModemManager1/Modem/2 + | device id: ffc9b1b812c716917655b1b67c3decda1caa33e1 + ---------------------------------- + Hardware | manufacturer: Sierra Wireless, Incorporated + | model: Sierra Wireless EM7565 Qualcomm® Snapdragon™ X16 LTE-A + | firmware revision: SWI9X50C_01.08.04.00 + | carrier config: default + | h/w revision: EM7565 + | supported: gsm-umts, lte + | current: gsm-umts, lte + | equipment id: 353533102301374 + ---------------------------------- + System | device: /sys/devices/platform/scb/fd500000.pcie/pci0000:00/0000:00:00.0/0000:01:00.0/usb1/1-1/1-1.3 + | drivers: cdc_mbim, qcserial + | plugin: sierra + | primary port: cdc-wdm0 + | ports: cdc-wdm0 (mbim), ttyUSB0 (gps), wwan0 (net) + ---------------------------------- + Status | lock: sim-pin2 + | unlock retries: sim-pin2 (3) + | state: connected + | power state: on + | access tech: lte + | signal quality: 19% (recent) + ---------------------------------- + Modes | supported: allowed: 3g; preferred: none + | allowed: 4g; preferred: none + | allowed: 3g, 4g; preferred: 4g + | allowed: 3g, 4g; preferred: 3g + | current: allowed: 4g; preferred: none + ---------------------------------- + Bands | supported: utran-1, utran-4, utran-6, utran-5, utran-8, utran-9, + | utran-2, eutran-1, eutran-2, eutran-3, eutran-4, eutran-5, eutran-7, + | eutran-8, eutran-9, eutran-12, eutran-13, eutran-18, eutran-19, + | eutran-20, eutran-26, eutran-28, eutran-29, eutran-30, eutran-32, + | eutran-41, eutran-42, eutran-43, eutran-46, eutran-48, eutran-66, + | utran-19 + | current: utran-1, utran-4, utran-6, utran-5, utran-8, utran-9, + | utran-2, eutran-1, eutran-2, eutran-3, eutran-4, eutran-5, eutran-7, + | eutran-8, eutran-9, eutran-12, eutran-13, eutran-18, eutran-19, + | eutran-20, eutran-26, eutran-28, eutran-29, eutran-30, eutran-32, + | eutran-41, eutran-42, eutran-43, eutran-46, eutran-48, eutran-66, + | utran-19 + ---------------------------------- + IP | supported: ipv4, ipv6, ipv4v6 + ---------------------------------- + 3GPP | imei: 353533102301374 + | enabled locks: fixed-dialing + | operator id: 23106 + | operator name: Tesco - SK + | registration: home + | packet service state: attached + ---------------------------------- + 3GPP EPS | initial bearer path: /org/freedesktop/ModemManager1/Bearer/2 + | initial bearer apn: o2internet + | initial bearer ip type: ipv4 + ---------------------------------- + SIM | primary sim path: /org/freedesktop/ModemManager1/SIM/1 + | sim slot paths: slot 1: none + | slot 2: /org/freedesktop/ModemManager1/SIM/1 (active) + ---------------------------------- + Bearer | paths: /org/freedesktop/ModemManager1/Bearer/3 +``` + +Notice, that for every SIM slot there is also path identifier ending with index number: + +```console + SIM | primary sim path: /org/freedesktop/ModemManager1/SIM/1 + | sim slot paths: slot 1: none + | slot 2: /org/freedesktop/ModemManager1/SIM/1 (active) +``` + +Beware that while full path is a unique object identifier, every object type (modem, SIM, bearer) +has its own index pool. +In this case, the primary SIM slot has index 1. We can get more info about a SIM slot and the SIM +card it contains with `mmcli -i `, e.g.: + +```console +$ mmcli -i 1 + ------------------------------- + General | path: /org/freedesktop/ModemManager1/SIM/1 + ------------------------------- + Properties | active: yes + | imsi: 231063511665993 + | iccid: 8942104393400779111 + | operator id: 23106 + | operator name: Tesco - SK + | gid1: FFFFFFFFFFFFFFFFFFFF + | gid2: FFFFFFFFFFFFFFFFFFFF +``` + +In order to debug the data connection, aka Bearer service (see bottom of modem details), +use: `mmcli -b `, e.g.: + +```console +$ mmcli -b +mmcli -b 3 + ------------------------------------ + General | path: /org/freedesktop/ModemManager1/Bearer/3 + | type: default + ------------------------------------ + Status | connected: yes + | suspended: no + | multiplexed: no + | interface: wwan0 + | ip timeout: 20 + ------------------------------------ + Properties | apn: o2internet + | roaming: allowed + | ip type: ipv4 + ------------------------------------ + IPv4 configuration | method: static + | address: 10.133.54.34 + | prefix: 30 + | gateway: 10.133.54.33 + | dns: 37.152.96.1, 31.3.32.1 + | mtu: 1500 + ------------------------------------ + Statistics | start date: 2023-10-06T08:16:21Z + | duration: 600 + | uplink-speed: 600000000 + | downlink-speed: 600000000 + | bytes rx: 81514 + | bytes tx: 10878 + | attempts: 1 + | total-duration: 600 + | total-bytes rx: 81514 + | total-bytes tx: 10878 +``` + +`mmcli` has many options that allow to query various additional information. +To learn more about them, run `mmcli --help`. + +For example, to get the status of location tracking, run: + +```console +$ mmcli -m 2 --location-status + -------------------------------- + Location | capabilities: 3gpp-lac-ci, gps-raw, gps-nmea, agps-msa, agps-msb + | enabled: gps-raw + | signals: yes + -------------------------------- + GPS | refresh rate: 10 seconds + | supported assistance: xtra + | assistance servers: https://xtrapath2.izatcloud.net/xtra3grcej.bin + | https://xtrapath3.izatcloud.net/xtra3grcej.bin + | https://xtrapath1.izatcloud.net/xtra3grcej.bin +``` + +When enabled for a given modem, attribute `enabled` is set to `gps-raw` and `signals` to `yes`. + +We can check if modem is able to get location information (if signal is good enough): + +```console +$ mmcli -m 2 --location-get + ---------------- + GPS | utc: 085945.00 + | longitude: 19.116371 + | latitude: 48.726629 + | altitude: 426.400000 +``` + +If it cannot determine the location, output will be empty. + +### Logs + +`mmagent` uses logger with source set to "wwan". +if connected to a device over SSH or console, these logs can be grep-ed (and potentially followed) with: + +```console +logread | grep '"source":"wwan"' +``` + +The content of these logs is generally self-explanatory. Here are some examples and brief descriptions +of some log messages reflecting important events that you may see in the log file: + +* When a new modem is found (initially or in run-time): + ```text + 2023-10-06T08:16:19.197079481Z;wwan.out;{"file":"/mmagent/agent.go:666","func":"main.(*MMAgent).processModemNotif","level":"info","msg":"New modem was added at path /org/freedesktop/ModemManager1/Modem/2, physical addresses: {Interface:wwan0 USB:1:1.3 PCI:0000:01:00.0 Dev:/dev/cdc-wdm0}","pid":28,"source":"wwan"} + 2023-10-06T08:16:19.197267665Z;wwan.out;{"file":"/mmagent/agent.go:753","func":"main.(*MMAgent).findConfigForNewModem","level":"info","msg":"Associated modem at path /org/freedesktop/ModemManager1/Modem/2 with logical label modem1","pid":28,"source":"wwan"} + ``` +* The process of establishing a connection: + ```text + 2023-10-06T08:16:19.198739081Z;wwan.out;{"file":"/mmagent/agent.go:948","func":"main.(*MMAgent).logReconcileOp","level":"info","msg":"Succeeded to remove (obsolete) IP settings for modem modem1 (/org/freedesktop/ModemManager1/Modem/2) (run due to: modem not connected)","pid":28,"source":"wwan"} + 2023-10-06T08:16:21.05135799Z;wwan.out;{"file":"/mmagent/agent.go:948","func":"main.(*MMAgent).logReconcileOp","level":"info","msg":"Succeeded to establish connection for modem modem1 (/org/freedesktop/ModemManager1/Modem/2) (run due to: modem not connected)","pid":28,"source":"wwan"} + ``` +* When location tracking is started: + ```text + 2023-10-06T08:16:26.495981911Z;wwan.out;{"file":"/mmagent/agent.go:948","func":"main.(*MMAgent).logReconcileOp","level":"info","msg":"Succeeded to start location tracking for modem modem1 (/org/freedesktop/ModemManager1/Modem/2)","pid":28,"source":"wwan"} + ``` +* When connection attempt fails (in this case the SIM card is missing): + ```text + 2023-10-06T08:17:16.387946182Z;wwan.out;{"file":"/mmagent/agent.go:950","func":"main.(*MMAgent).logReconcileOp","level":"error","msg":"Failed to establish connection for modem modem2 (/org/freedesktop/ModemManager1/Modem/0) (run due to: modem not connected): SIM card is absent","pid":28,"source":"wwan"} + 2023-10-06T08:17:16.38800457Z;wwan.out;{"file":"/mmagent/agent.go:886","func":"main.(*MMAgent).reconcileModem","level":"warning","msg":"SIM card is absent","pid":28,"source":"wwan","time":"2023-10-06T08:17:16.387903682Z"} + ``` +* If you see that reconciliation was suspended for a modem, this is because some config change + was made and `mmagent` wants to give the modem some time (30 seconds) to apply the change: + ```text + 2023-10-06T08:16:26.496260891Z;wwan.out;{"file":"/mmagent/agent.go:928","func":"main.(*MMAgent).suspendReconcile","level":"info","msg":"Suspended reconciliation for modem modem1 (/org/freedesktop/ModemManager1/Modem/2) until 2023-10-06 08:16:56.495884523 +0000 UTC m=+402.493881974","pid":28,"source":"wwan"} + ``` +* If data connection is actually broken (packets not getting through) despite modem claiming + that it is OK, `mmagent` will eventually notice it (probing run every 5 minutes) and restart it: + ```text + 2023-10-06T09:11:41.295122113Z;wwan.out;{"file":"/mmagent/agent.go:1005","func":"main.(*MMAgent).probeConnectivity","level":"warning","msg":"Connectivity probing failed for modem modem1: read udp 10.133.182.81:36633-\u003e37.152.96.1:53: i/o timeout; read udp 10.133.182.81:53986-\u003e31.3.32.1:53: i/o timeout; no ping response received from 8.8.8.8","pid":28,"source":"wwan"} + 2023-10-06T09:11:41.547290979Z;wwan.out;{"file":"/mmagent/agent.go:948","func":"main.(*MMAgent).logReconcileOp","level":"info","msg":"Succeeded to remove (obsolete) IP settings for modem modem1 (/org/freedesktop/ModemManager1/Modem/2) (run due to: modem not connected)","pid":28,"source":"wwan"} + 2023-10-06T09:11:46.386529591Z;wwan.out;{"file":"/mmagent/agent.go:948","func":"main.(*MMAgent).logReconcileOp","level":"info","msg":"Succeeded to establish connection for modem modem1 (/org/freedesktop/ModemManager1/Modem/2) (run due to: modem not connected)","pid":28,"source":"wwan"} + 2023-10-06T09:11:46.563987646Z;wwan.out;{"file":"/mmagent/agent.go:948","func":"main.(*MMAgent).logReconcileOp","level":"info","msg":"Tried to fix connectivity for modem modem1: ","pid":28,"source":"wwan"} + 2023-10-06T09:11:46.868374255Z;wwan.out;{"file":"/mmagent/agent.go:948","func":"main.(*MMAgent).logReconcileOp","level":"info","msg":"Succeeded to start location tracking for modem modem1 (/org/freedesktop/ModemManager1/Modem/2)","pid":28,"source":"wwan"} + ``` +* When modem is unplugged from device (if it is USB dongle): + ```text + 2023-10-06T09:11:26.011452905Z;wwan.out;{"file":"/mmagent/agent.go:708","func":"main.(*MMAgent).processModemNotif","level":"info","msg":"Modem at path /org/freedesktop/ModemManager1/Modem/0 was removed","pid":28,"source":"wwan"} + ``` + +If these logs are not enough to determine the root cause of an issue, it is possible to increase +the log level of the wwan microservice to `debug` for more detailed logging. This is done by setting +[config property](../../docs/CONFIG-PROPERTIES.md) `agent.wwan.debug.loglevel` to value `debug`. +This will also enable (very!) verbose logging for ModemManager. You will be able to see traces +of all QMI/MBIM messages exchanged between ModemManager and cellular modems. +This is an example of a single QMI indication received by ModemManager: + +```text +2023-10-09T11:48:11.018473289Z;wwan;[22]: [1696852091.018185] [/dev/cdc-wdm0] received generic indication (translated)... +2023-10-09T11:48:11.018547011Z;wwan;<<<<<< QMUX: +2023-10-09T11:48:11.018549751Z;wwan;<<<<<< length = 85 +2023-10-09T11:48:11.018588436Z;wwan;<<<<<< flags = 0x80 +2023-10-09T11:48:11.018590695Z;wwan;<<<<<< service = "loc" +2023-10-09T11:48:11.018628491Z;wwan;<<<<<< client = 1 +2023-10-09T11:48:11.018630565Z;wwan;<<<<<< QMI: +2023-10-09T11:48:11.018668509Z;wwan;<<<<<< flags = "indication" +2023-10-09T11:48:11.018670602Z;wwan;<<<<<< transaction = 63939 +2023-10-09T11:48:11.018708361Z;wwan;<<<<<< tlv_length = 73 +2023-10-09T11:48:11.018710398Z;wwan;<<<<<< message = "NMEA" (0x0026) +2023-10-09T11:48:11.018763453Z;wwan;<<<<<< TLV: +2023-10-09T11:48:11.018765582Z;wwan;<<<<<< type = "NMEA String" (0x01) +2023-10-09T11:48:11.018804656Z;wwan;<<<<<< length = 70 +2023-10-09T11:48:11.018807193Z;wwan;<<<<<< value = 24:47:50:47:53:56:2C:33:2C:31:2C:31:32:2C:30:37:2C:36:32:2C:31:38:34:2C:32:31:2C:31:31:2C:33:38:2C:32:37:35:2C:31:38:2C:33:30:2C:33:33:2C:32:30:36:2C:32:35:2C:30:33:2C:30:32:2C:31:33:33:2C:2C:31:2A:36:41:0D:0A +2023-10-09T11:48:11.018848415Z;wwan;<<<<<< translated = $GPGSV,3,1,12,07,62,184,21,11,38,275,18,30,33,206,25,03,02,133,,1*6A +``` + +Please use this carefully and only temporarily. The rate of new logs produced will likely outmatch +the rate at which device is able to publish them. + +### QMI/MBIM CLI tools + +The wwan container is shipped with CLI tools from libqmi and libmbim: `qmicli` and `mbimcli`, respectively. +This enables you to go one layer deeper than ModemManager in the [architecture](#architecture) +and communicate with a modem in a more direct manner using the QMI/MBIM protocols. + +To use these commands, connect to a device over SSH or a console and type: + +```console +eve enter wwan +# For QMI device: +qmicli -p -d /dev/ +# For MBIM device: +mbimcli -p -d /dev/ +``` + +For example, to get the IP settings of the currently established data connection: + +```console +qmicli -p -d /dev/cdc-wdm0 --wds-get-current-settings +[/dev/cdc-wdm0] Current settings retrieved: + IP Family: IPv4 + IPv4 address: 10.65.17.48 + IPv4 subnet mask: 255.255.255.224 +IPv4 gateway address: 10.65.17.49 + IPv4 primary DNS: 31.3.32.1 + IPv4 secondary DNS: 37.152.96.1 + MTU: 1500 + Domains: none +``` + +```console +mbimcli -p -d /dev/cdc-wdm0 --query-ip-configuration + +[/dev/cdc-wdm0] IPv4 configuration available: 'address, gateway, dns, mtu' + IP [0]: '10.65.17.48/27' + Gateway: '10.65.17.49' + DNS [0]: '31.3.32.1' + DNS [1]: '37.152.96.1' + MTU: '1500' + +[/dev/cdc-wdm0] IPv6 configuration available: 'none' +``` + +With these CLI tools, it is also possible to execute various actions and change the modem's state +(connect, disconnect, enable, or disable radio, etc.). However, please note that if ModemManager +is running, it will detect and report any changes to mmagent, which, in turn, can instruct +ModemManager to reverse the manually made changes, potentially interfering with your troubleshooting +session. + +Run `qmicli/mbimcli` with `--help-all` to learn about all the options available. + +### AT interface + +All the configuration that makes your modem connect to a desired wireless provider resides +in SIM and modem's NVRAM. Both of these settings are expected to be done once before the hardware +unit ships and EVE stays away from fiddling with these. Still, sometimes it is important +to troubleshoot basic (non-data) wireless connectivity issues and most of the time you would +use AT commands for that. + +When it comes to controlling cellular modems via AT commands, there's not much of a standard. +Different vendors use different commands and worse yet the state machines of how modems +operate tend to be very different. Some vendors (e.g. Sierra Wireless) +[publish](https://source.sierrawireless.com/resources) reasonably detailed references, but even +those don't really contain enough details. Various [forums](https://wirelessjoint.com/) +tend to be a good source of information for what may work. In addition to that, here's a minimum +set of AT commands to keep in mind when debugging cellular modem issues (they are roughly +in order you'd use them): + +* `AT!RESET` and `AT+CFUN=0` followed by `AT+CFUN=1,1` for resetting the modem +* `AT!ENTERCND="A710"` enter super user mode +* `AT+CPIN?` for working with SIM (make sure SIM is ready to use) +* `AT+CREG?` for figuring out network registration (make sure you are registered in the home network) +* `AT+COPS=?` for showing available networks and `AT+COPS=0` for triggering the network registration + or `AT+COPS=1,2,"xxxxx",7` to manually connect to a given provider +* `AT+CSQ` (and especially `+WIND:`) for finding out signal quality and the connections +* `AT+CGATT=1` for attaching to the service +* `AT+CGDCONT?` and `AT+CGDCONT=1,"IP","apn.tmobile.com"` for defining Packet Data Protocol (PDP) context +* `AT+CGACT=1,1` for activating one of the PDP contexts +* `AT+CGPADDR=1` for requesting an IP address assigned by the context +* `AT!USBCOMP=1,1,10d` for changing USB composition +* `ATI` for general information and `AT!entercnd="A710"` (for Sierra Wireless) to enter extended command set +* `$GPS_START` to start receiving GPS data on a lot of Qualcomm modems + +For example, the following may be a reasonable session to initialize your modem using AT commands: + +```console +eve enter wwan +picocom -b 115200 /dev/ttyUSB2 + +ati +at!entercnd="A710" +at+cpin? + READY +at!custom="IPV6ENABLE",1 +at+cgdcont=1,"ipv4v6","vzwinternet" +at!selrat=06 +at!usbcomp = 1,1,1009 +at!reset +# Press CTRL-A, then CTRL-X to exit +``` + +## Enabling a new cellular modem + +Go through the following steps (more detailed description below): + +1. Check that modem is supported by ModemManager. +2. Make sure that the modem device is connected to the host edge node through one of the common buses. + This doesn't guarantee that the host can communicate with the device, but at least you should see it + registered on the bus. +3. Make sure that the modem is configured in such a way that you (and more importantly ModemManager) + can actually communicate with it. +4. Check that ModemManager recognized the modem. +5. Check that ModemManager is able to establish a data connection. + +### 1. ModemManager support + +Check the up-to-date list of modems supported by ModemManager [here](https://www.freedesktop.org/wiki/Software/ModemManager/SupportedDevices/). + +### 2. Basic bus connectivity + +Almost all well known cellular modems get hooked to a USB bus (most of them communicate using USB2 +but some try USB3 and then [trouble may ensue](https://forum.sierrawireless.com/t/mc7455-not-recognized-at-boot/9735) +and you may need to [do soldering](https://forum.sierrawireless.com/t/effect-of-removing-usb-3-0-pins-of-mc7455/12702/2). +From there, a single device will expose different interfaces to accommodate various ways of interacting +with it. These include: + +* Traditional serial interface capable of accepting AT-commands. + Popular choices of drivers include [Qualcomm's qcserial](https://github.com/torvalds/linux/blob/master/drivers/usb/serial/qcserial.c) + and [Sierra Wireless serial](https://github.com/torvalds/linux/blob/master/drivers/usb/serial/sierra.c). + This interface is NOT capable of directly transmitting Ethernet frames and requires an old-school + PPP support. +* Traditional serial interface used for special purposes such as [GPS NMEA port](https://en.wikipedia.org/wiki/NMEA_0183) + or [Diagnostic Monitoring](https://forum.sierrawireless.com/t/sierra-linux-qmi-dmcapture-sh-not-working/6373) +* One of the [CDC](https://en.wikipedia.org/wiki/USB_communications_device_class) interfaces capable + of direct transport of Ethernet frames: + * [CDC MBIM](https://www.kernel.org/doc/Documentation/networking/cdc_mbim.txt) + * [CDC QMI](https://en.wikipedia.org/wiki/Qualcomm_MSM_Interface) + +To put it all together, a single cellular modem is likely to look something like this when inspected +by the `lsusb -t` command: + +```console +/: Bus 01.Port 1: Dev 1, Class=root_hub, Driver=ehci-pci/2p, 480M + |__ Port 1: Dev 2, If 0, Class=Hub, Driver=hub/4p, 480M + |__ Port 2: Dev 3, If 0, Class=Hub, Driver=hub/4p, 480M + |__ Port 4: Dev 7, If 0, Class=Vendor Specific Class, Driver=qcserial, 480M + |__ Port 4: Dev 7, If 3, Class=Vendor Specific Class, Driver=qcserial, 480M + |__ Port 4: Dev 7, If 8, Class=Vendor Specific Class, Driver=qmi_wwan, 480M + |__ Port 4: Dev 7, If 2, Class=Vendor Specific Class, Driver=qcserial, 480M +``` + +### 3. Communicating with the modem on various USB interfaces + +Our previous example had a modem that is Device 7 on Port 4 exposing 4 different interfaces: 3 serial +ones and one QMI CDC. This magic number of 4 interfaces is interesting because most modems insist +on mapping all of their different APIs to just 3 USB interface endpoints (this is really bizarre since +its not like USB interface endpoints are a scarce commodity). This mapping is called a *usb composition* +and it can be programmed by either issuing an appropriate AT command (typically `at!usbcomp=1,1,10d`) +on a serial end point or by issuing a CDC/QMI command (if one of those interfaces is available). +Sadly, there's no standard when it comes to AT commands (and worse yet whatever AT commands +are available may not actually be able to program all of the usb compositions) and your best bet +is something like (note that swi in --dms-swi stands for Sierra Wireless): + +```console +$ qmicli --device-open-mbim -p -d /dev/cdc-wdm0 --dms-swi-get-usb-composition +[/dev/cdc-wdm0] Successfully retrieved USB compositions: + USB composition 6: DM, NMEA, AT, QMI + [*] USB composition 8: DM, NMEA, AT, MBIM + USB composition 9: MBIM +$ qmicli --device-open-mbim -p -d /dev/cdc-wdm0 --dms-swi-set-usb-composition=6 +``` + +Alternatively, you may try to use an AT command to change USB composition. What AT command to use +depends on the manufacturer and possibly also on the particular model of the modem. +For example, for SierraWireless you would use `USBCOMP` from the super user mode: + +```console +eve enter wwan +picocom -b 115200 /dev/ttyUSB2 +AT!ENTERCND="A710" +AT!USBCOMP=? +!USBCOMP: +AT!USBCOMP=,, + - configuration index to which the composition applies, s1 + + - 1:MBIM USBIF, 2:PCIE USBIF, 3:Legacy-Generic, 4:RNDIS + + - DIAG - 0x00000001, + NMEA - 0x00000004, + MODEM - 0x00000008, + RMNET0 - 0x00000100, + MBIM - 0x00001000, +``` + +If all else fails, you may try [swi_setusbcomp script](https://github.com/mavstuff/swi_setusbcomp) +to switch to a desired USB composition: + +```console +$ swi_setusbcomp.pl --device=/dev/cdc-wdm0 + 6 => 'DM NMEA AT QMI', + 7 => 'DM NMEA AT RMNET1 RMNET2 RMNET3', + 8 => 'DM NMEA AT MBIM', + 9 => 'MBIM', + 10 => 'NMEA MBIM', +swi_setusbcomp.pl --device=/dev/cdc-wdm0 --usbcomp=6 +``` + +Regardless of how you arrive at the desired USB composition, make sure to reboot and watch out for +the following devices and device drivers: + +* `/dev/ttyUSB` with qcserial or "option" driver serving as serial AT command capable endpoint +* `/dev/cdc-wdm` with either qmi_wwan or cdc_mbim driver for QMI or MBIM endpoint + +### 4. Detecting modem with ModemManager + +ModemManager normally listens, probes and detects cellular devices automatically when operating +correctly but a forced scan can be triggered with command: + +```console +eve enter wwan +mmcli --scan-modems +successfully requested to scan devices +``` + +To list detected cellular devices, use the command: + +```console +mmcli --list-modems + /org/freedesktop/ModemManager1/Modem/0 [Sierra Wireless, Incorporated] MC7455 +``` + +If ModemManager failed to recognize your modem, you can [enable debug logging](#logs) and reboot, +then investigate logged ModemManager output using `logger`. However, a much quicker solution is to +simply kill ModemManager running inside the wwan container and start a new instance with output +redirected to a file for further analysis: + +```console +eve enter debug +pkill ModemManager +ModemManager --debug 2>&1 | tee mm.stdout +``` + +Wait few seconds, then analyze the output collected in `mm.stdout`. Look for any messages related +to your modem that could give hints as to why ModemManager failed to recognize and initialize the modem. + +### 5. Establishing data connection with ModemManager + +Before trying to establish data connection, check with `mmcli` that your modem is not in some error state. +For example, here we see a modem with missing (or maybe not recognized) SIM card: + +```console +mmcli -m 0 +... + ----------------------------- + Status | state: failed + | failed reason: sim-missing + | power state: on + ----------------------------- +... +``` + +Also, make sure that `state` is not `locked`, which would suggest that your SIM card requires PIN +code, which is not supported by EVE. + +```console +mmcli -m 0 +... + Status | lock: sim-pin + | unlock retries: sim-pin (3), sim-puk (10), sim-pin2 (3), sim-puk2 (10) + | state: locked + | power state: on + | signal quality: 0% (cached) +... +``` + +If the modem is `disabled`, run `mmcli -m= --enable`. + +Desired modem state before connecting is `registered` or at least `searching`. + +Then try to establish data connection using an appropriate APN: + +```console +mmcli -m --simple-connect='apn=,ip-type=' +``` + +Where `` should be either `ipv4` or `ipv4v6` (try both to find which one works with your +provider). mmagent would do the same. +For example: + +```console +mmcli -m 0 --simple-connect='apn=internet,ip-type=ipv4' +successfully connected the modem +``` + +If we check modem status again, we can see that a bearer has been established. + +```console +mmcli -m 0 +... + ---------------------------------- + Bearer | paths: /org/freedesktop/ModemManager1/Bearer/5 +... +``` + +Next we obtain IP configuration assigned to the bearer: + +```console +mmcli -b 5 + ------------------------------------ + General | path: /org/freedesktop/ModemManager1/Bearer/5 + | type: default + ------------------------------------ + Status | connected: yes + | suspended: no + | multiplexed: no + | interface: wwan0 + | ip timeout: 20 + ------------------------------------ + Properties | apn: internet + | roaming: allowed + | ip type: ipv4 + ------------------------------------ + IPv4 configuration | method: static + | address: 10.49.140.93 + | prefix: 30 + | gateway: 10.49.140.94 + | dns: 213.151.233.252, 213.151.233.249 + | mtu: 1500 + ------------------------------------ + Statistics | duration: 60 + | attempts: 1 + | total-duration: 60 +``` + +From here we can see the IP details we have been assigned by the cellular network and the network +interface corresponding to the modem (`wwan0`). +ModemManager does not assign IPv4 address details to the network interface in Linux by itself. +When ModemManager is used in conjunction with NetworkManager and the cellular connection is managed +by it, then the IPv4 address details will be collected by NetworkManager through ModemManager +and automatically assigned to the network interface when connection is established. +In EVE, it is the responsibility of mmagent to manage the IP configuration of the network interface. + +When testing a new modem on EVE manually, the IP and routing configuration needs to be applied +using the ip command. Taking the IP config from the above as an example, we would run: + +```console +# Enable network interface in Linux. +ip link set wwan0 up + +# Set the IPv4 address acquired from the bearer information above. +ip addr add 10.49.140.93/30 dev wwan0 + +# Disable ARP. +ip link set dev wwan0 arp off + +# Set MTU value acquired from network. +ip link set dev wwan0 mtu 1500 + +# Add a default route for the cellular network device pointing to the received gateway IP. +ip route add default via 10.49.140.94 dev wwan0 metric 1000 + +# Add the DNS servers reported by cellular network: +echo 'nameserver 213.151.233.252' >> /etc/resolv.conf +echo 'nameserver 213.151.233.249' >> /etc/resolv.conf +``` + +We should now have a network interface passing data successfully, we can try it out by doing ping requests: +```console +ping -4 -c 4 -I wwan0 8.8.8.8 +PING 8.8.8.8 (8.8.8.8) from 10.49.140.93 wwan0: 56(84) bytes of data. +64 bytes from 8.8.8.8: icmp_seq=1 ttl=117 time=123 ms +64 bytes from 8.8.8.8: icmp_seq=2 ttl=117 time=46.2 ms +64 bytes from 8.8.8.8: icmp_seq=3 ttl=117 time=51.4 ms +64 bytes from 8.8.8.8: icmp_seq=4 ttl=117 time=44.2 ms + +--- 8.8.8.8 ping statistics --- +4 packets transmitted, 4 received, 0% packet loss, time 3005ms +rtt min/avg/max/mdev = 44.159/66.162/122.881/32.853 ms +``` + +Now you have verified that your modem is compatible with EVE OS and you can try to configure +cellular connection properly from the controller. + +## Frequencies and antennas + +At some point you will have to care about frequencies and antennas. Most Sierra Wireless modems +support all frequencies and both FDD-LTE and TDD-LTE (which are just two different ways of splitting +upstream and downstream bandwidth). You can check on [cellmapper.net](https://www.cellmapper.net) +which channels are supported by the cell towers near you and look up the corresponding frequencies +[here](https://en.wikipedia.org/wiki/Cellular_frequencies). +You can then either get a wideband antenna that covers all the frequencies supported +by your modem and the cell tower, or you can pick one or two frequencies and get an antenna +for just those frequencies. Usually wideband antennas that support multiple frequencies +don't have as much gain. You might want to try forcing your modem to use each of the frequencies +in turn and check the bandwidth during peak times before you decide on the best antenna. + +For the MC7455 you will probably need pigtails (antenna adaptors) from u.fl to either SMA or N-type +connectors depending on your antenna. Other modems like the EM7565 use MHF4 connectors +instead of u.fl. Remember that the longer the cable from your modem to the antenna, the more signal +you will lose. diff --git a/pkg/wwan/pics/wwan.png b/pkg/wwan/pics/wwan.png new file mode 100644 index 00000000000..298b54bd4a1 Binary files /dev/null and b/pkg/wwan/pics/wwan.png differ diff --git a/pkg/wwan/pics/wwan.xml b/pkg/wwan/pics/wwan.xml new file mode 100644 index 00000000000..0b2a4836e6d --- /dev/null +++ b/pkg/wwan/pics/wwan.xml @@ -0,0 +1,164 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +