Difference between revisions of "PineModems"

From PINE64
Jump to navigation Jump to search
(Removed html tags, fixed tables)
 
(23 intermediate revisions by 7 users not shown)
Line 1: Line 1:
= Modems used in Pine64 boards and devices =
== PINE64 position on alternative firmware ==


PINE64 ships the PinePhone with a stock version of the Quectel EG25-G modem's firmware. Some administrative regions, in the EU and Asia in particular, require the entirety of the modem's firmware to be licensed. Therefore, the PinePhone cannot ship with an unlicensed firmware, and the PINE64 project cannot, officially encourage its userbase to use alternative modem firmware.   


== Quectel EG25-G Modem ==


=== Quectel EG25-G Modem ===
Quectel EG25-G is an LTE Cat 4 module optimized specially for M2M and IoT applications. It is used in the [[PinePhone]].


* Specifications: https://www.quectel.com/UploadFile/Product/Quectel_EG25-G_LTE_Specification_V1.1.pdf
* Specifications: [[File:Quectel_EG25-G_LTE_Standard_Specification_V1.3.pdf]]
* Hardware design: https://www.quectel.com/UploadImage/Downlad/Quectel_EG25-G_Hardware_Design_V1.2.pdf
* Hardware design: [[File:Quectel_EG25-G_Hardware_Design_V1.4.pdf]]
* AT Interface reference manual: https://www.quectel.com/UploadImage/Downlad/Quectel_EC25&EC21_AT_Commands_Manual_V1.3.pdf
* AT Interface reference manual:
* AT Interface file operations: https://www.quectel.com/UploadImage/Downlad/Quectel_EC2x&EG25-G&EG9x&EM05_FILE_AT_Commands_Manual_V1.0.pdf
** 1.3 for EC25: [[File:Quectel_EC25&EC21_AT_Commands_Manual_V1.3.pdf]]
** 2.0 for EC25 and EG25-G: [[File:Quectel_EC2x&EG9x&EG2x-G&EM05_Series_AT_Commands_Manual_V2.0.pdf]]
* AT Interface file operations: [[File:Quectel_EC2xEG25-GEG9xEM05_FILE_AT_Commands_Manual_V1.0.pdf]]
* GNSS Application note: [[File:Quectel_EC2x&EG9x&EG2x-G&EM05_Series_GNSS_Application_Note_V1.3.pdf]]


=== Specifications ===
=== Specifications ===
* Processor Family: Qualcomm MDM9607
* CPU: Qualcomm MDM9207
* Cores: 1 ACPU Core, Qualcomm Hexagon DSP
* Total RAM: 256Mb
* Total flash space: 256Mb
* Available RAM for the ACPU: 160Mb


{| class="wikitable"
| Processor Family
| Qualcomm MDM9607
|-
| CPU
| Qualcomm MDM9207
|-
| Cores
| 1 ACPU Core, Qualcomm Hexagon DSP
|-
| Total RAM
| 256Mb
|-
| Total flash space
| 256Mb
|-
| Available RAM for the ACPU
| 160Mb
|}


=== NAND Partition table layout ===
=== NAND Partition table layout ===


* MTD0: SBL (Secondary Bootloader), called from the BootROM. Used to start the TrustZone kernel and the Application Bootloader (LK). Also used to enter Quectel's recovery mode
{| class="wikitable"
* MTD1: mibib (Unknown, used by the DSP)
! Index
* MTD2: EFS2 (Unexplored, probably NVRAM data, Used by the DSP)
! Name
* MTD3: sys_rev: Unexplored
! Description
* MTD4: rawdata: This is where FOTA update data exists before being commited to system or recoveryfs partitions
|-
* MTD5: tz: TrustZone kernel
| MTD0
* MTD6: rpm: Resource / Power Manager
| <code>SBL</code>
* MTD7: cust_info: Unexplored
| Secondary Bootloader, called from the BootROM. Used to start the TrustZone kernel and the Application Bootloader (LK). Also used to enter Quectel's recovery mode
* MTD8: aboot: Application Bootloader. Uses LK (LittleKernel) as the bootloader. By default it allows flashing unsigned images but won't allow booting them, soft-bricking the modem until you enter EDL mode
|-
* MTD9:  boot: OpenEmbedded boot kernel + DTB
| MTD1
* MTD10: recovery: Recovery kernel (normally unused)
| <code>mibib</code>
* MTD11: modem: ADSP firmware blobs
| NAND Partition table
* MTD12: misc: Unexplored
|-
* MTD13: recoveryfs: Recovery filesystem image (FOTA updates)
| MTD2
* MTD14: usr_data: User data partition (/data when mounted by OpenEmbedded)
| <code>EFS2</code>
* MTD15: sec (Used to blow fuses in the mdm9207 from images generated by Qualcomm Sectools)
| IMEI and settings used by the ADSP are stored here
* MTD16: system (Linux OpenEmbedded root image, formatted in Ubifs filesystem)
|-
| MTD3
| <code>sys_rev</code>
| Unexplored
|-
| MTD4
| <code>rawdata</code>
| This is where FOTA update data exists before being commited to system or recoveryfs partitions
|-
| MTD5
| <code>tz</code>
| TrustZone kernel
|-
| MTD6
| <code>rpm</code>
| Resource / Power Manager
|-
| MTD7
| <code>cust_info</code>
| Unexplored
|-
| MTD8
| <code>aboot</code>
| Application Bootloader. Uses [https://github.com/littlekernel/lk LK] (LittleKernel, LK embedded kernel) as the bootloader. By default it allows flashing unsigned images but won't allow booting them, soft-bricking the modem until you enter EDL mode
|-
| MTD9
| <code>boot</code>
| [https://www.openembedded.org/wiki/Main_Page OpenEmbedded] boot kernel + DTB
|-
| MTD10
| <code>recovery</code>
| Recovery kernel (used for FOTA updates)
|-
| MTD11
| <code>modem</code>
| ADSP firmware blobs
|-
| MTD12
| <code>misc</code>
| Some settings are stored here, along with commands that need to be picked by LK on next boot (to reboot to fastboot or recovery mode)
|-
| MTD13
| <code>recoveryfs</code>
| Recovery filesystem image (FOTA updates)
|-
| MTD14
| <code>usr_data</code>
| User data partition (<code>/data</code> when mounted by OpenEmbedded)
|-
| MTD15
| <code>sec</code>
| Used to blow fuses in the mdm9207 from images generated by Qualcomm Sectools
|-
| MTD16
| <code>system</code>
| Linux OpenEmbedded root image, formatted in UBIFS (Unsorted Block Image File System, [https://en.wikipedia.org/wiki/UBIFS Wikipedia])
|}


=== Firmware Recovery ===
=== Firmware Recovery ===
The System partition is mounted as readonly mode, but the data partition is writable. It might be possible, if there's an unexpected reset or power is lost while running, that the data partition gets corrupt and thus unable to boot.
 
{{Warning|The following instructions are directed towards expert-level users and developers!}}
 
The System partition is mounted as read-only mode, but the data partition is writable. It might be possible, if there's an unexpected reset or power is lost while running, that the data partition gets corrupt and thus unable to boot.
 
[[File:Pinephone-EG25-Recovery.jpg|thumb|right|PinePhone USB_BOOT test points]]
[[File:Pinephone-EG25-Recovery.jpg|thumb|right|PinePhone USB_BOOT test points]]
The modem has 4 different boot modes:
The modem has 4 different boot modes:
* Normal boot
* Normal boot
Line 48: Line 127:
* Qualcomm EDL Mode
* Qualcomm EDL Mode


If the modem is unable to boot, depending on the type of crash, it might not show anywhere (USB device missing), it might malfunction (no radio but USB working), or it might enter EDL mode if the entire flash is corrupt
If the modem is unable to boot, depending on the type of crash, it might:
* not show anywhere (USB device missing)
* or malfunction (no radio but USB working)
* or enter EDL mode, if the entire flash is corrupt.


In any scenario, the modem can be triggered to enter EDL mode by shorting two test pins in the PinePhone Motherboard. Power off the phone, short the two test points and start it again while keeping the pads shorted at least until you hear the camera clicking twice (which is normally when the modem is powered)
'''Boot the device in EDL mode'''


To check if the device is booted in EDL mode, run <code>lsusb</code> (a part of the <code>usbutils</code> package) in a terminal and inspect the output. You should see the following device listed:


Download the Firmware Recovery Package and copy it to the Pinephone: https://github.com/Biktorgj/quectel_eg25_recovery/archive/master.zip
Bus 003 Device 003: ID 05c6:9008 Qualcomm, Inc. Gobi Wireless Modem (QDL mode)
To check if you're currently booted in EDL mode, run lsusb in a terminal and inspect the output.
You should see the following device listed: Bus 003 Device 003: ID 05c6:9008 Qualcomm, Inc. Gobi Wireless Modem (QDL mode)


Once in EDL mode, open a terminal and go to the root directory of the recovery package, and run:
In any scenario, the modem can be triggered to enter EDL mode by shorting two test pins on the PinePhone motherboard.


If you use an ARM64 distro (most likely) ./qfirehose_arm64 -f ./
# Power off the phone
# short the two test points
# boot the phone while keeping the test points shorted until fully booted up, at least until you hear the camera clicking twice (which is normally when the modem is powered).


If you use an ARMHF (32 bit) distro: ./qfirehose_armhf -f ./
'''Get the Firmware Recovery Package'''


After it finishes, it will reboot the modem and after about 30 seconds it will get back up and running
The Firmware Recovery Package is at: https://github.com/Biktorgj/quectel_eg25_recovery
 
Either clone its repo with git, or download its archive & unzip it.
 
As you should have no access to the Internet on PinePhone when its modem need a Recovery, you can fetch it on other devices and copy it to the Pinephone.
 
'''Execute the Quectel QFirehose utility'''
 
Once in EDL mode, open a terminal, navigate to the root directory of the recovery package, and run:
 
* If you use an ARM64 distribution (most likely): <code>sudo ./qfirehose -f ./</code> or <code>sudo ./qfirehose_arm64 -f ./</code>
* If you use an ARMHF (32 bit) distribution: <code>sudo ./qfirehose_armhf -f ./</code>
 
It will reboot the modem after finished. After about 30 seconds, it will get back up and running. To check the firmware version after that, use an AT command <code>AT+QGMR</code> like at [[PinePhone#Firmware_update]].


=== Bootloader unlocking ===
=== Bootloader unlocking ===
{{Warning|The following instructions are directed towards expert-level users and developers!}}
The Modem has a locked bootloader. It won't allow to boot unsigned Kernel images, but will allow to flash them, making it easy to brick the modem. To fix this, you can flash an unlocked bootloader, which will then allow you to do as you please with the hardware.
The Modem has a locked bootloader. It won't allow to boot unsigned Kernel images, but will allow to flash them, making it easy to brick the modem. To fix this, you can flash an unlocked bootloader, which will then allow you to do as you please with the hardware.


The source code for the Bootloader is here: https://github.com/Biktorgj/quectel_lk
Unlocked bootloader:
Prebuilt binary releases can be downloaded from here: https://github.com/Biktorgj/quectel_lk/releases
* Source code: https://github.com/Biktorgj/quectel_lk
* Prebuilt binary releases: https://github.com/Biktorgj/quectel_lk/releases
 
=== Custom Kernels and system images ===
 
{{Warning|The following instructions are directed towards expert-level users and developers!}}
 
Custom kernel builds and system images can be created for the modem, though they require a couple of things to be correctly built and be bootable.
 
* The source code release for the kernel provided by the manufacturer is incomplete and won't build
* Common Android tools like mkbootimg and dtbtool won't build a bootable image, even if the kernel is correctly compiled and all the DTBs attached.
* Further, there's no source for the OpenEmbedded parts, so building a new system image must be done from scratch, and retrieving the mandatory binary blobs to use the ADSP part of the modem.
 
There's a '''work in progress''' SDK to allow creating custom kernels and system images, which can be downloaded from the following repository: https://github.com/Biktorgj/pinephone_modem_sdk


See its readme for infomations and instructions. Once downloaded, you should run the <code>init.sh</code> script, which will create all the base directories and download all the different repositories required to build. After the initial setup is complete, run<code>make</code> without arguments to list the available options.


=== Custom Kernels and system images ===
=== Upgrade/switch firmware via fwupd ===
 
https://fwupd.org/ is an open-source tool for managing the installation of firmware on Linux systems.
 
fwupd >= 1.7.6 (with the ModemManager plugin) supports writing/upgrading the https://github.com/Biktorgj/pinephone_modem_sdk firmware on the Quectel EG25-G modem.
 
https://wiki.postmarketos.org/wiki/Fwupd discusses how to use fwupd to do this.
 
More context:
* https://dylanvanassche.be/blog/2022/pinephone-modem-upgrade/
* https://gitlab.com/postmarketOS/pmaports/-/merge_requests/2760
* https://gitlab.com/linux-mobile/tracker/-/issues/11
 
=== Modem management ===
 
To allow PinePhones to receive calls while the PinePhone is suspended, the modem should be kept running. ModemManager and a eg25-specific manager must be used for the eg25-manager to work correctly.
 
==== ModemManager ====
 
[https://www.freedesktop.org/wiki/Software/ModemManager/ ModemManager] "is a DBus-activated daemon which controls mobile broadband (2G/3G/4G) devices and connections". Distributions should enable the <code>--test-quick-suspend-resume</code> flag, per https://gitlab.com/linux-mobile/tracker/-/issues/12.
 
Context: https://gitlab.freedesktop.org/mobile-broadband/ModemManager/-/issues/321
 
==== eg25-specific manager ====
 
Some functionality is not built into ModemManager, and is instead managed via eg25-specific software. There are two variants of this, but only one should be used.
 
* [https://gitlab.com/mobian1/devices/eg25-manager eg25-manager] <b>recommended</b>, used in most distributions.
* [https://xnux.eu/devices/feature/modem-pp.html modem-power]
 
==== Testing ====
 
When a distribution makes a significant change to their modem management setup, they should consider testing the following:
 
* Modem is recognized by ModemManager on boot.
* Can make a call
* Can receive a call
* Can receive a call when asleep: <code>systemctl suspend</code>


Custom kernel builds and system images can be created for the modem, though they require a couple of things to be correctly built and be bootable. The source code release for the kernel provided by the manufacturer is incomplete and won't build, and common Android tools mkbootimg and dtbtool won't build a bootable image, even if the kernel is correctly compiled and all the DTB's attached. Further, there's no source for the OpenEmbedded parts, so building a new system image must be done from scratch, and retrieving the mandatory binary blobs to use the ADSP part of the modem.
== See also ==


There's a _Work in progress_ SDK to allow creating custom kernels and system images, which can be downloaded from the following repo: https://github.com/Biktorgj/pinephone_modem_sdk
* [https://dylanvanassche.be/blog/2021/pinephone-modem-myths/ "PinePhone modem myths" by Dylan Van Assche]


Once downloaded, you should run the 'init.sh' script, which will create all the base directories and download all the different repos required to build. After the initial setup is complete, run 'make' without arguments to list the available options
[[Category:PinePhone]]

Latest revision as of 13:35, 16 March 2023

PINE64 position on alternative firmware

PINE64 ships the PinePhone with a stock version of the Quectel EG25-G modem's firmware. Some administrative regions, in the EU and Asia in particular, require the entirety of the modem's firmware to be licensed. Therefore, the PinePhone cannot ship with an unlicensed firmware, and the PINE64 project cannot, officially encourage its userbase to use alternative modem firmware.

Quectel EG25-G Modem

Quectel EG25-G is an LTE Cat 4 module optimized specially for M2M and IoT applications. It is used in the PinePhone.

Specifications

Processor Family Qualcomm MDM9607
CPU Qualcomm MDM9207
Cores 1 ACPU Core, Qualcomm Hexagon DSP
Total RAM 256Mb
Total flash space 256Mb
Available RAM for the ACPU 160Mb

NAND Partition table layout

Index Name Description
MTD0 SBL Secondary Bootloader, called from the BootROM. Used to start the TrustZone kernel and the Application Bootloader (LK). Also used to enter Quectel's recovery mode
MTD1 mibib NAND Partition table
MTD2 EFS2 IMEI and settings used by the ADSP are stored here
MTD3 sys_rev Unexplored
MTD4 rawdata This is where FOTA update data exists before being commited to system or recoveryfs partitions
MTD5 tz TrustZone kernel
MTD6 rpm Resource / Power Manager
MTD7 cust_info Unexplored
MTD8 aboot Application Bootloader. Uses LK (LittleKernel, LK embedded kernel) as the bootloader. By default it allows flashing unsigned images but won't allow booting them, soft-bricking the modem until you enter EDL mode
MTD9 boot OpenEmbedded boot kernel + DTB
MTD10 recovery Recovery kernel (used for FOTA updates)
MTD11 modem ADSP firmware blobs
MTD12 misc Some settings are stored here, along with commands that need to be picked by LK on next boot (to reboot to fastboot or recovery mode)
MTD13 recoveryfs Recovery filesystem image (FOTA updates)
MTD14 usr_data User data partition (/data when mounted by OpenEmbedded)
MTD15 sec Used to blow fuses in the mdm9207 from images generated by Qualcomm Sectools
MTD16 system Linux OpenEmbedded root image, formatted in UBIFS (Unsorted Block Image File System, Wikipedia)

Firmware Recovery

Warning: The following instructions are directed towards expert-level users and developers!

The System partition is mounted as read-only mode, but the data partition is writable. It might be possible, if there's an unexpected reset or power is lost while running, that the data partition gets corrupt and thus unable to boot.

PinePhone USB_BOOT test points

The modem has 4 different boot modes:

  • Normal boot
  • Recovery mode (used by the modem usually to install a FOTA update)
  • Fastboot mode
  • Qualcomm EDL Mode

If the modem is unable to boot, depending on the type of crash, it might:

  • not show anywhere (USB device missing)
  • or malfunction (no radio but USB working)
  • or enter EDL mode, if the entire flash is corrupt.

Boot the device in EDL mode

To check if the device is booted in EDL mode, run lsusb (a part of the usbutils package) in a terminal and inspect the output. You should see the following device listed: 

Bus 003 Device 003: ID 05c6:9008 Qualcomm, Inc. Gobi Wireless Modem (QDL mode)

In any scenario, the modem can be triggered to enter EDL mode by shorting two test pins on the PinePhone motherboard.

  1. Power off the phone
  2. short the two test points
  3. boot the phone while keeping the test points shorted until fully booted up, at least until you hear the camera clicking twice (which is normally when the modem is powered).

Get the Firmware Recovery Package

The Firmware Recovery Package is at: https://github.com/Biktorgj/quectel_eg25_recovery

Either clone its repo with git, or download its archive & unzip it.

As you should have no access to the Internet on PinePhone when its modem need a Recovery, you can fetch it on other devices and copy it to the Pinephone.

Execute the Quectel QFirehose utility

Once in EDL mode, open a terminal, navigate to the root directory of the recovery package, and run:

  • If you use an ARM64 distribution (most likely): sudo ./qfirehose -f ./ or sudo ./qfirehose_arm64 -f ./
  • If you use an ARMHF (32 bit) distribution: sudo ./qfirehose_armhf -f ./

It will reboot the modem after finished. After about 30 seconds, it will get back up and running. To check the firmware version after that, use an AT command AT+QGMR like at PinePhone#Firmware_update.

Bootloader unlocking

Warning: The following instructions are directed towards expert-level users and developers!

The Modem has a locked bootloader. It won't allow to boot unsigned Kernel images, but will allow to flash them, making it easy to brick the modem. To fix this, you can flash an unlocked bootloader, which will then allow you to do as you please with the hardware.

Unlocked bootloader:

Custom Kernels and system images

Warning: The following instructions are directed towards expert-level users and developers!

Custom kernel builds and system images can be created for the modem, though they require a couple of things to be correctly built and be bootable.

  • The source code release for the kernel provided by the manufacturer is incomplete and won't build
  • Common Android tools like mkbootimg and dtbtool won't build a bootable image, even if the kernel is correctly compiled and all the DTBs attached.
  • Further, there's no source for the OpenEmbedded parts, so building a new system image must be done from scratch, and retrieving the mandatory binary blobs to use the ADSP part of the modem.

There's a work in progress SDK to allow creating custom kernels and system images, which can be downloaded from the following repository: https://github.com/Biktorgj/pinephone_modem_sdk

See its readme for infomations and instructions. Once downloaded, you should run the init.sh script, which will create all the base directories and download all the different repositories required to build. After the initial setup is complete, runmake without arguments to list the available options.

Upgrade/switch firmware via fwupd

https://fwupd.org/ is an open-source tool for managing the installation of firmware on Linux systems.

fwupd >= 1.7.6 (with the ModemManager plugin) supports writing/upgrading the https://github.com/Biktorgj/pinephone_modem_sdk firmware on the Quectel EG25-G modem.

https://wiki.postmarketos.org/wiki/Fwupd discusses how to use fwupd to do this.

More context:

Modem management

To allow PinePhones to receive calls while the PinePhone is suspended, the modem should be kept running. ModemManager and a eg25-specific manager must be used for the eg25-manager to work correctly.

ModemManager

ModemManager "is a DBus-activated daemon which controls mobile broadband (2G/3G/4G) devices and connections". Distributions should enable the --test-quick-suspend-resume flag, per https://gitlab.com/linux-mobile/tracker/-/issues/12.

Context: https://gitlab.freedesktop.org/mobile-broadband/ModemManager/-/issues/321

eg25-specific manager

Some functionality is not built into ModemManager, and is instead managed via eg25-specific software. There are two variants of this, but only one should be used.

Testing

When a distribution makes a significant change to their modem management setup, they should consider testing the following:

  • Modem is recognized by ModemManager on boot.
  • Can make a call
  • Can receive a call
  • Can receive a call when asleep: systemctl suspend

See also

Retrieved from "https://wiki.pine64.org/index.php?title=PineModems&oldid=18777"