📝 20 Feb 2023
PinePhone talks to LTE Modem over USB
Over the past 17 articles we talked about porting to Pine64 PinePhone a Real-Time Operating System: Apache NuttX RTOS.
Today NuttX can run Touchscreen Apps on PinePhone… But it ain’t done yet till we can make Phone Calls and send Text Messages!
In this article we’ll dive into PinePhone’s USB Controller…
Why PinePhone needs USB for Voice Calls and SMS
What’s inside PinePhone’s Allwinner A64 USB Controller
Which is actually a Mentor Graphics Inventra USB Controller
We’ll study the FreeBSD Driver for the USB Controller
And how we might port the USB Driver to NuttX RTOS
By comparing with the STM32 USB Driver for NuttX
Our journey down the PinePhone USB Rabbit Hole begins with a curious comment…
Quectel EG25-G LTE Modem inside PinePhone
Now that NuttX can run Touchscreen Apps on PinePhone… What next?
We might turn PinePhone on NuttX into a Feature Phone, thanks to an inspiring comment on YouTube…
“I’d like to use or build a ‘feature-phone’-style UI for the PinePhone someday”
“Is there USB support (In NuttX, and your port)? I think that would be the first step in getting the modem to work”
Excellent Idea! We’ll turn NuttX on PinePhone into a Feature Phone…
Just Voice Calls and SMS, using PinePhone’s LTE Modem.
(LTE Modem is the hardware inside PinePhone that handles 4G Voice Calls, SMS and Mobile Data)
Why is this useful?
Maybe we can pop a microSD Card (and SIM) into any PinePhone…
And turn it instantly into an Emergency Phone with NuttX?
What if there’s no LTE Network Coverage? Like in a Natural Disaster?
The Long-Range, Low-Power LoRa Network might be good for search and rescue communications.
We could attach the PineDio LoRa Add-On Case to turn PinePhone into a LoRa Communicator.
Will PinePhone on NuttX become a fully-functional smartphone?
Maybe someday? We’re still lacking plenty of drivers: WiFi, Bluetooth LE, GPS, Audio, …
Probably better to start as a Feature Phone (or LoRa Communicator) and build up.
Let’s talk about PinePhone’s LTE Modem…
What’s this LTE Modem?
Check out the article…
Inside PinePhone is the Quectel EG25-G LTE Modem for 4G Voice Calls, SMS, Mobile Data and GPS (pic above)…
To control the LTE Modem, we send AT Commands…
So to dial the number 1711, we send this AT Command…
ATD1711;
(EG25-G runs on Qualcomm MDM 9607 with a Cortex-A7 CPU inside)
How to send the AT Commands to LTE Modem?
The LTE Modem accepts AT Commands in two ways (pic below)…
Via the UART Port (Serial)
Which is Slower: Up to 921.6 kbps
Via the USB Port (USB Serial)
Which is Faster: Up to 480 Mbps
So if we’re sending and receiving lots of 4G Mobile Data, USB is the better way.
(UART Interface is probably sufficient for a Feature Phone)
Quectel EG25-G LTE Modem in PinePhone Schematic (Page 15)
How is the LTE Modem connected to PinePhone?
Check out the article…
According to the PinePhone Schematic (Page 15), the Quectel EG25-G LTE Modem connects to the Allwinner A64 SoC on the USB Pins…
USB1-DP
USB1-DM
Which is Port USB1 of the Allwinner A64 SoC. (Pic above)
(LTE Modem Audio goes to Port PCM0)
Only 2 pins?
That’s because USB 2.0 runs on 2 data wires and 2 power wires…
Data+ (USB1-DP)
Data- (USB1-DM)
5V and GND
(Due to Differential Signalling)
What about USB0-DP and USB0-DM?
Port USB0 of the Allwinner A64 SoC is exposed as the External USB Port on PinePhone.
(Port USB0 supports USB OTG, Port USB1 doesn’t)
Beware! The USB Port Names look confusing in the Allwinner A64 User Manual…
| USB Port | Alternate Name | Base Address |
|---|---|---|
| Port USB0 | USB-OTG-EHCI / OHCI | 0x01C1 A000 (USB_HCI0) |
| Port USB1 | USB-EHCI0 / OHCI0 | 0x01C1 B000 (USB_HCI1) |
We’ll talk only about Port USB1 (Non-OTG), since it’s connected to the LTE Modem.
So PinePhone talks to the LTE Modem on USB Serial?
Correct! Here are the USB Endpoints exposed by the LTE Modem (which we’ll decipher later)…
$ sudo lsusb -v
Bus 002 Device 002: ID 2c7c:0125 Quectel Wireless Solutions Co., Ltd. EC25 LTE modem
Device Descriptor:
idVendor 0x2c7c Quectel Wireless Solutions Co., Ltd.
idProduct 0x0125 EC25 LTE modem
iManufacturer 1 Quectel
iProduct 2 EG25-G
Configuration Descriptor:
bNumInterfaces 5
Interface Descriptor:
bInterfaceNumber 0
bEndpointAddress 0x81 EP 1 IN
bEndpointAddress 0x01 EP 1 OUT
Interface Descriptor:
bInterfaceNumber 1
bEndpointAddress 0x83 EP 3 IN
bEndpointAddress 0x82 EP 2 IN
bEndpointAddress 0x02 EP 2 OUT
Interface Descriptor:
bInterfaceNumber 2
bEndpointAddress 0x85 EP 5 IN
bEndpointAddress 0x84 EP 4 IN
bEndpointAddress 0x03 EP 3 OUT
Interface Descriptor:
bInterfaceNumber 3
bEndpointAddress 0x87 EP 7 IN
bEndpointAddress 0x86 EP 6 IN
bEndpointAddress 0x04 EP 4 OUT
Interface Descriptor:
bInterfaceNumber 4
bEndpointAddress 0x89 EP 9 IN
bEndpointAddress 0x88 EP 8 IN
bEndpointAddress 0x05 EP 5 OUT
But first we need to build the PinePhone USB Driver for NuttX…
Sorry Elmo… Allwinner A64’s USB Controller isn’t documented
To turn PinePhone into a Feature Phone (Voice Calls and SMS only)…
What NuttX Drivers would we need?
We need a NuttX Driver for the PinePhone’s Quectel LTE Modem… Which talks over USB Serial.
Thus we also need a NuttX Driver for PinePhone’s Allwinner A64 USB Controller.
So we check the USB Controller docs?
Allwinner A64’s USB Controller is officially documented in…
See Section 7.5 “USB” (Page 583)
Which doesn’t say much about the USB Controller!
Allwinner A64’s Official Docs are horrigibly lacking…
But thanks to the Sunxi Community we have a valuable tip on the USB Controller…
“All Allwinner A-series SoCs come with one USB OTG controller”
“The controller has been identified as a Mentor Graphics Inventra HDRC (High-speed Dual Role Controller), which is supported by the musb driver”
“However, the register addresses are scrambled”
Aha! Allwinner A64’s USB Controller is actually a Mentor Graphics USB Controller!
USB Registers are scrambled? Like eggs?
Actually it means that Allwinner A64’s USB Registers are located in different addresses from the Mentor Graphics ones.
(Everything else works exactly the same way)
The Sunxi Community has helpfully documented the Scrambled USB Registers…
What’s a USB OTG Controller?
OTG refers to USB On-The-Go, which supports both USB Host Mode and USB Device Mode.
(Also known as “Dual-Role”)
Let’s find a Reference Driver for the Mentor Graphics USB Controller…
USB Controller in PinePhone Device Tree
UPDATE: There’s an easier way to build the PinePhone USB Driver…
How to find a driver for Allwinner A64’s USB Controller?
PinePhone’s Device Tree describes the Hardware Configuration of PinePhone…
According to the Device Tree, PinePhone’s USB Drivers are listed as (pic above)…
usb@1c19000 {
compatible = "allwinner,sun8i-a33-musb";
...
phy@1c19400 {
compatible = "allwinner,sun50i-a64-usb-phy";
What are MUSB and USB PHY?
MUSB refers to the Mentor Graphics USB Controller
USB PHY refers to the Physical Layer (physical wires) that carries the USB signals
Thus we search for these USB Driver Names on GitHub Code Search…
allwinner,sun8i-a33-musb
allwinner,sun50i-a64-usb-phy
Which uncovers the Allwinner A64 USB Driver that we seek (for FreeBSD, NetBSD and Linux)…
We found a Reference Driver for Allwinner A64 USB Controller?
Yep! Earlier we discovered the name of the Allwinner A64 USB Driver: “allwinner,sun8i-a33-musb”
GitHub Code Search says that the Allwinner A64 USB Driver for FreeBSD is…
MUSB refers to the Mentor Graphics USB Controller.
OTG refers to USB On-The-Go, which supports both USB Host Mode and USB Device Mode.
(We’ll stick to USB Host Mode for today)
But where’s the actual code for the USB Driver?
The Mentor Graphics USB Driver is implemented here…
Why two files: musb_otg.c and musb_otg_allwinner.c?
Remember that the Allwinner A64 USB Controller is identical to the Mentor Graphics one… Except that the USB Registers are scrambled?
That’s why we need musb_otg_allwinner.c to unscramble the USB Registers, specifically for Allwinner A64.
What about the USB Physical Layer for FreeBSD?
The USB Physical Layer for Allwinner A64 is implemented here…
This driver controls the Physical Layer (physical wires) that carries the USB signals.
(But we won’t touch it today)
OK we’ve seen the FreeBSD Drivers… What about other operating systems?
GitHub Code Search also uncovers the NetBSD Drivers for Allwinner A64 USB…
But today we’ll study the FreeBSD Driver because it’s easier to read.
Transmit Control Data as Host in Mentor Graphics USB Controller (Page 126)
Do we copy the FreeBSD Driver into NuttX?
Sorry that sounds mighty irresponsible… If we don’t understand the code! (Just like ChatGPT)
Remember that the Allwinner A64 USB Controller is based on the design by Mentor Graphics…
Hence to understand the driver internals, we shall match the FreeBSD Driver Code with the Mentor Graphics Doc.
Where do we start?
The Mentor Graphics Doc describes Transmitting Control Data (as a Host)…
See Section 21.2.3 “Control Transactions as a Host - Out Data Phase as a Host”. (Page 126, pic above)
(USB Out Transaction is explained here)
This seems to match the FreeBSD Driver Code for musbotg_host_ctrl_data_tx in musb_otg.c…
To figure out how it works, we compare the code with the doc side-by-side…
Matching the FreeBSD Driver Code with the Mentor Graphics Doc will be an interesting educational exercise…
Which we’ll cover in the next article!
UPDATE: There’s an easier way to build the PinePhone USB Driver…
We found the FreeBSD Driver for Allwinner A64 USB…
How will we adapt it for NuttX RTOS?
First we understand how USB Drivers work in NuttX…
The NuttX doc describes the Detection and Enumeration of USB Devices…
Each USB Host Device Controller supports two methods that are used to detect and enumeration newly connected devices…
wait: Wait for a device to be connected or disconnected
enumerate: Enumerate the device connected to a root hub port
Then the NuttX doc explains the USB Enumeration Process…
As part of this enumeration process, the driver will
(1) Get the Device’s Configuration Descriptor
(2) Extract the Class ID info from the Configuration Descriptor
…
So our PinePhone USB Driver needs to implement this USB Enumeration?
Yep! To prepare for our upcoming implementation of the PinePhone USB Driver, let’s look at the NuttX Driver for STM32 USB Controller…
UPDATE: There’s an easier way to build the PinePhone USB Driver…
We’re about to implement our NuttX Driver for PinePhone USB…
Can we learn something from the NuttX Driver for STM32 USB?
Let’s find out! The NuttX USB Driver for STM32 is implemented at…
We see these in the NuttX Filenames…
OTG refers to USB On-The-Go, which supports both USB Host Mode and USB Device Mode
FS refers to USB Full Speed Mode at 12 Mbps
HS refers to USB High Speed Mode at 480 Mbps
How does the STM32 Driver enumerate USB Devices?
That’s done in stm32_enumerate…
Which calls stm32_rh_enumerate
(To enumerate the USB Root Hub)
Which calls usbhost_enumerate
(Platform-independent USB Enumeration for NuttX)
Which calls DRVR_CTRLOUT
(To send a USB Control Out Request)
Which calls stm32_ctrlout
(To send a USB Control Out Request on STM32)
stm32_ctrlout in NuttX looks similar to musbotg_host_ctrl_data_tx in FreeBSD that we saw earlier…
Aha! We found the Rosetta Stone that matches…
Allwinner A64 USB Driver in FreeBSD, with the…
STM32 USB Driver in NuttX RTOS!
(Pic below)
This will be super helpful as we port the Allwinner A64 USB Driver to NuttX.
stm32_ctrlout in NuttX looks similar to musbotg_host_ctrl_data_tx in FreeBSD
Porting the PinePhone USB Driver to NuttX will be a super long journey… The FreeBSD driver has 4,000 lines of code 😲
UPDATE: There’s an easier way to build the PinePhone USB Driver…
But stay tuned for updates! Meanwhile please check out the other articles on NuttX for PinePhone…
Many Thanks to my GitHub Sponsors for supporting my work! This article wouldn’t have been possible without your support.
Got a question, comment or suggestion? Create an Issue or submit a Pull Request here…
USB Controller Block Diagram in Allwinner A64 User Manual (Page 583)
Read the article…
Lwazi Dube noted that USB Enhanced Host Controller Interface 1.0 (EHCI) is implemented for the Allwinner A64 USB Controller. (Pic above)
Thus we have an easier way to build the NuttX USB Driver for PinePhone!
Let’s find out why…
(PinePhone’s LTE Modem is connected to Port USB1, which is HCI0 in the lower half of the pic)
What’s EHCI?
According to the EHCI Spec…
“The Enhanced Host Controller Interface (EHCI) specification describes the Register-Level Interface for a Host Controller for the Universal Serial Bus (USB) Revision 2.0”
“The specification includes a description of the Hardware and Software Interface between System Software and the Host Controller Hardware”
Which means we can build the NuttX USB Driver for PinePhone… By simply talking to the (Memory-Mapped) EHCI Registers on Allwinner A64’s USB Controller!
What are the EHCI Registers?
The Standard EHCI Registers are documented here…
(Version 1.1 Addendum isn’t relevant because Allwinner A64 only implements Version 1.0 of the spec)
Allwinner A64 implements the EHCI Registers for Port USB1 at Base Address 0x01C1 B000 (USB_HCI1, pic below)
Refer to the Allwinner A64 User Manual…
Section 7.5.3.3: USB Host Register List (Page 585, pic below)
Section 7.5.3.4: EHCI Register Description (Page 587)
Section 7.5.3.5: OHCI Register Description (Page 601)
Section 7.5.3.6: HCI Interface Control and Status Register Description (Page 619)
Section 7.5.3.7: USB Host Clock Requirement (Page 620)
PinePhone’s LTE Modem is connected on EHCI?
Yep we confirmed it with lsusb…
$ lsusb -t -v
/: Bus 04.Port 1: Dev 1, Class=root_hub, Driver=ohci-platform/1p, 12M
ID 1d6b:0001 Linux Foundation 1.1 root hub
/: Bus 03.Port 1: Dev 1, Class=root_hub, Driver=ehci-platform/1p, 480M
ID 1d6b:0002 Linux Foundation 2.0 root hub
/: Bus 02.Port 1: Dev 1, Class=root_hub, Driver=ohci-platform/1p, 12M
ID 1d6b:0001 Linux Foundation 1.1 root hub
/: Bus 01.Port 1: Dev 1, Class=root_hub, Driver=ehci-platform/1p, 480M
ID 1d6b:0002 Linux Foundation 2.0 root hub
|__ Port 1: Dev 2, If 0, Class=Vendor Specific Class, Driver=option, 480M
ID 2c7c:0125 Quectel Wireless Solutions Co., Ltd. EC25 LTE modem
|__ Port 1: Dev 2, If 1, Class=Vendor Specific Class, Driver=option, 480M
ID 2c7c:0125 Quectel Wireless Solutions Co., Ltd. EC25 LTE modem
|__ Port 1: Dev 2, If 2, Class=Vendor Specific Class, Driver=option, 480M
ID 2c7c:0125 Quectel Wireless Solutions Co., Ltd. EC25 LTE modem
|__ Port 1: Dev 2, If 3, Class=Vendor Specific Class, Driver=option, 480M
ID 2c7c:0125 Quectel Wireless Solutions Co., Ltd. EC25 LTE modem
|__ Port 1: Dev 2, If 4, Class=Vendor Specific Class, Driver=qmi_wwan, 480M
ID 2c7c:0125 Quectel Wireless Solutions Co., Ltd. EC25 LTE modem
EHCI also appears in the PinePhone Device Tree: sun50i-a64-pinephone-1.2.dts
usb@1c1a000 {
compatible = "allwinner,sun50i-a64-ehci\0generic-ehci";
reg = <0x1c1a000 0x100>;
interrupts = <0x00 0x48 0x04>;
clocks = <0x02 0x2c 0x02 0x2a 0x02 0x5b>;
resets = <0x02 0x15 0x02 0x13>;
status = "okay";
};
usb@1c1a400 {
compatible = "allwinner,sun50i-a64-ohci\0generic-ohci";
reg = <0x1c1a400 0x100>;
interrupts = <0x00 0x49 0x04>;
clocks = <0x02 0x2c 0x02 0x5b>;
resets = <0x02 0x15>;
status = "okay";
};
usb@1c1b000 {
compatible = "allwinner,sun50i-a64-ehci\0generic-ehci";
reg = <0x1c1b000 0x100>;
interrupts = <0x00 0x4a 0x04>;
clocks = <0x02 0x2d 0x02 0x2b 0x02 0x5d>;
resets = <0x02 0x16 0x02 0x14>;
phys = <0x31 0x01>;
phy-names = "usb";
status = "okay";
};
usb@1c1b400 {
compatible = "allwinner,sun50i-a64-ohci\0generic-ohci";
reg = <0x1c1b400 0x100>;
interrupts = <0x00 0x4b 0x04>;
clocks = <0x02 0x2d 0x02 0x5d>;
resets = <0x02 0x16>;
phys = <0x31 0x01>;
phy-names = "usb";
status = "okay";
};
Which says that PinePhone uses the Generic Platform EHCI Driver.
There’s another EHCI Port at 0x01C1 A000?
Yep there are two USB Ports in Allwinner A64: USB0 and USB1.
Port USB0 Base Address isn’t documented, but it appears in the Memory Mapping (Page 73) of the Allwinner A64 User Manual…
| USB Port | Alternate Name | Base Address |
|---|---|---|
| Port USB0 | USB-OTG-EHCI / OHCI | 0x01C1 A000 (USB_HCI0) |
| Port USB1 | USB-EHCI0 / OHCI0 | 0x01C1 B000 (USB_HCI1) |
We’ll talk only about Port USB1 (Non-OTG), since it’s connected to the LTE Modem.
How will we build the EHCI Driver for PinePhone?
Lwazi found these EHCI Drivers in NuttX…
(This is the newest driver)
Microchip SAMA5 USB: sam_ehci.c
(This is the oldest driver)
(The 4 files look similar… We might need to refactor them someday)
I’ll port the i.MX RT EHCI Driver to PinePhone and Allwinner A64, since it’s the newest one.
Check the updates here…
What about the LTE Modem Driver for NuttX?
This NuttX Driver for Quectel EC20 LTE Modem might be helpful…
Stay tuned for updates!
Pine64 PineDio LoRa Gateway (left) with PineDio LoRa Add-On Case (right)
Earlier we talked about turning PinePhone on NuttX into a Feature Phone for Emergency Use…
What if there’s no LTE Network Coverage? Like in a Natural Disaster?
The Long-Range, Low-Power LoRa Network might be good for search and rescue communications.
(Short Text Messages only plus GPS Geolocation, non-guaranteed message delivery)
To turn PinePhone into a LoRa Communicator, just attach the LoRa Add-On Case to PinePhone (pic above)…
Pine64 PineDio LoRa Add-On Case
(Still in stock!)
We might use JF’s LoRa Driver (which handles the I2C-to-SPI Bridge)…
Or the LoRa Driver that we’ve ported to NuttX…
Or maybe Meshtastic, since it has a complete LoRa Mesh Messaging App…
Meshtastic was built with Arduino (C++). To compile it on NuttX we could use the Portduino Library…