This repository provides ready-to-use ESPHome packages for popular ESP32 development boards with integrated cellular modems. These packages simplify the configuration of cellular connectivity by automatically configuring the modem hardware with the appropriate pins and settings.

These packages are designed to work with the ESPHome modem component, which provides cellular TCP/IP connectivity for ESP32-based devices over 4G/LTE networks.

Related ESPHome Pull Requests:

• #6721 - [modem] pppos tcp/ip for UART modem (esp32)
• #7147 - [wifi, ethernet] Allow Wifi AP to reuse existing network interface (ethernet or modem) for NAT

Documentation: ESPHome Modem Component

⚠️ These configuration packages do not include complete network setup.

When using a cellular modem, your device receives a private IP address from the mobile carrier, making it unreachable from the internet. This prevents direct connections for OTA updates via the API component.

You must configure one of the following solutions:

Option 1: MQTT (Recommended)

• Configure an MQTT broker that is accessible from the internet (without firewall restrictions)
• For OTA updates with MQTT, use the HTTP Request OTA platform
• Documentation: ESPHome OTA HTTP Request

Option 2: WireGuard + API (Less Recommended)

• Set up a WireGuard VPN tunnel to create a private network connection
• Use the standard ESPHome API for communication and OTA updates
• Documentation: ESPHome WireGuard

⚠️ GPS/GNSS support with cellular modems is more complex than standalone GPS modules.

When a modem sits between the ESP32 and the GNSS receiver, the direct UART access to NMEA sentences (as used by the standard ESPHome GPS component) is not available. The modem firmware controls GNSS access, creating several challenges:

Implementation Challenges:

• The GNSS UART is hidden behind the modem's AT command interface
• NMEA sentences must be retrieved either:
  • Via Unsolicited Result Codes (URC) - when supported, the modem forwards NMEA frames automatically (best method)
  • By parsing proprietary formats like AT+CGNSSINFO responses, which vary between modem models and firmware versions
• Non-standard formats require complex parsing and conversion to NMEA format
• GNSS support and data format can change between firmware versions of the same modem model

Simcom Firmware Variants:

• Some Simcom firmware versions are "lightened" and lack GNSS support entirely, even when the hardware connector is present
• To verify GNSS support: Use the ATI command and check if the firmware version ends with _F (for "Full")
  • Example: SIM7600M22_V2.0_210630_F → GNSS supported ✅
  • Example: SIM7600M22_V2.0_210630 → GNSS not supported ❌

Recommendation: When possible, choose boards with modems that support native NMEA forwarding via URC (like the LilyGo T-SIM7600).

To use these packages in your ESPHome configuration, create a YAML file based on the generic example below. You'll need to:

1. Choose the appropriate package for your board (uncomment one line)
2. Set your APN and PIN code
3. Adjust GPIO pins if they're not defined in the package

Generic Example: examples/test_modem.yaml

modem_package: url: https://github.com/oarcher/piotech files: # include only one model! - packages/lilygo_tsim7080.yaml # https://github.com/Xinyuan-LilyGO/LilyGo-T-SIM7080G # - packages/lilygo_tsim7600.yaml # https://lilygo.cc/en-us/products/t-sim7600 # - packages/Makerfabs_ESP32-S3-4G-LTE-CAT1-SIM7670.yaml # - packages/waveshare_ESP32-S3-A7670E-4G.yaml # https://docs.waveshare.com/ESP32-S3-A7670E-4G # - packages/and_A7670.yaml # - packages/ICGOICIC_A7670X.yaml - packages/modem_external.yaml # for automatic external components (while PR not merged) - packages/modem_wifi_ap.yaml # for testing wifi AP refresh: 10s # optional modem: # set your apn apn: "orange" # set your pin code (or keep commented if no pin) # pin_code: "0000" # if not defined in the modem package, you should set rx/tx # rx_pin: GPIOXX # connected to TX or the modem side # tx_pin: GPIOXX # connected to RX or the modem side

Important: Copy and modify this example for your specific board and configuration needs.

Legend:

• ✅ = Fully supported
• ⚠️ = Partially supported or requires workarounds
• ❌ = Not supported or not working

⚠️ Special Warning: The LilyGo T-SIM7080 board requires a non-official external component for power management (AXP2101). This is not ideal for production use.

Product Page: LilyGo T-SIM7600

Features:

• Modem: SIM7600 (4G Cat-1)
• GPS/GNSS: ✅ Excellent support via modem Unsolicited Result Codes (URC)
• Power Control: GPIO4 (inverted)
• Status Pin: GPIO34
• Flight Mode: GPIO25 (inverted)
• Status LED: GPIO12

Pin Configuration:

GPS/GNSS Support:

The SIM7600 modem provides native GPS support through NMEA sentences delivered via Unsolicited Result Codes. The package automatically:

1. Powers on GPS with AT+CGPS=1
2. Configures NMEA output (AT+CGPSINFOCFG=10,3) for GPGGA and GPRMC sentences every 10 seconds
3. Forwards NMEA data to the ESPHome GPS component

Package: packages/lilygo_tsim7600.yaml

Product Page: Makerfabs ESP32-S3 4G LTE SIM7670

Features:

• ESP32 Variant: ESP32-S3
• Modem: SIM7670 (4G Cat-1)
• GPS/GNSS: ⚠️ Requires manual conversion from AT+CGNSSINFO to NMEA with format workaround
• Power Pin: GPIO4 (inverted)
• Status Pin: Not available
• Flight Mode: GPIO5 switch available
• Hardware Flow Control: ❌ Not available

Pin Configuration:

GPS/GNSS Support:

The SIM7670 on this board does not provide native NMEA output. Like the AND SIM7670, it requires parsing AT+CGNSSINFO responses and converting to NMEA format.

⚠️ Critical Issue: Dynamic CGNSSINFO Format Changes!

The AT+CGNSSINFO response format on this board is unstable and changes dynamically:

• Sometimes returns 17 fields (missing the last sat_used field)
• Sometimes returns 18 fields (complete format)
• The format can change between queries on the same device
• The package includes a workaround that detects 17-field responses and adds an empty field

From the package code:

if (p.size() == 17) { // on waveshare 7670 last field is sometime missing ESP_LOGW("NMEA", "Added missing 'sat_used' field"); p.push_back(""); }

This instability makes GNSS support fragile and unreliable. The same issue may occur on other SIM7670-based boards.

Package: packages/Makerfabs_ESP32-S3-4G-LTE-CAT1-SIM7670.yaml

Product Link: AliExpress - AND SIM7670

Features:

• Modem: SIM7670 (4G Cat-1)
• GPS/GNSS: ⚠️ Requires manual conversion from AT+CGNSSINFO to NMEA
• Power Pin: ⚠️ K pin - connection status unclear
• Status Pin: ⚠️ S pin - connection status unclear
• Hardware Flow Control: ✅ Unpopulated G/T/R pins available

Pin Configuration:

Power Requirements:

⚠️ External 5V power required! The ESP32 may not provide sufficient power to the modem. Connect:

• External 5V to modem V pin (or via USB)
• ESP32 GND to modem GND pin
• ESP32 3.3V to modem Vdd pin

LED Indicators:

GPS/GNSS Support:

The SIM7670 on this board does not provide native NMEA output. The package includes a complex lambda function that:

1. Queries modem position with AT+CGNSSINFO
2. Parses the CSV response
3. Converts decimal degrees to NMEA format
4. Generates GPGGA and GPRMC sentences with checksums
5. Feeds synthetic NMEA data to the GPS component

This runs every 20 seconds via an interval component.

⚠️ Note: Users report that pins S (status) and K (power) may not be properly connected on this board. Please report if you successfully use them!

Package: packages/and_A7670.yaml

Product Page: Waveshare ESP32-S3-A7670E-4G

Features:

• ESP32 Variant: ESP32-S3
• Modem: SIM7670E (4G Cat-1)
• GPS/GNSS: ❌ Non-functional due to firmware bug with SIM card
• Power Pin: Not available
• Status Pin: Not available
• Hardware UART: UART1 (TX: GPIO18, RX: GPIO17)

Pin Configuration:

Known Issues:

❌ GPS/GNSS Firmware Bug: The A7670E modem firmware on this board has a critical bug that breaks all GPS-related AT commands when a SIM card is inserted.

Symptom:

# With SIM card inserted: AT+CGNSSPWR=1 OK +CGNSSPWR: READY! AT+CGNSSPROD AT+CGNSSPROD ,, # Empty response # Without SIM card: AT+CGNSSPROD AT+CGNSSPROD PRODUCT: UNICORECOMM,UC6228CI,R3.4.21.0Build16211 # Normal response 

All GPS commands (AT+CGNSSPWR, AT+CGNSSINFO, AT+CGNSSPROD, etc.) return empty tokens when a SIM card is present.

USB Interface:

The board exposes USB D+/D- pins connected to the modem, which could potentially be used for NMEA sentence retrieval. However, ESPHome does not yet have a USB host component to interface with this.

AT Command Manual: A7670E AT Command Manual

Package: packages/waveshare_ESP32-S3-A7670E-4G.yaml

Product Link: AliExpress - ICGOICIC A7670X

Features:

• Modem: SIM7670 (4G Cat-1)
• GPS/GNSS: ❌ Not available (firmware doesn't end with _F)
• Power Pin: ⚠️ K pin - connection status unclear
• Status Pin: ⚠️ S pin - connection status unclear
• Hardware Flow Control: ❌ Not available

Pin Configuration:

Power Requirements:

✅ Can be powered by ESP32! Unlike the AND SIM7670 board, this board includes a capacitor and has no GNSS module, allowing it to be powered directly from the ESP32:

• ESP32 GND to modem GND pin
• ESP32 3.3V to modem Vdd pin

Alternatively, you can use external 5V power:

• External 5V to modem V pin (or via USB)
• ESP32 GND to modem GND pin
• ESP32 3.3V to modem Vdd pin

LED Indicators:

GPS/GNSS Support:

❌ Not available. This board uses a non-full firmware version (doesn't end with _F). Check with the ATI command to verify your firmware version.

⚠️ Note: If you have tested this board with a "Full" firmware version that supports GNSS, please report your findings so this documentation can be updated!

⚠️ Note: Users report that pins S (status) and K (power) may not be properly connected on this board. Please report if you successfully use them!

Package: packages/ICGOICIC_A7670X.yaml

⚠️ WARNING: This board requires an unofficial external component and is NOT recommended for production use!

Product Page: LilyGo T-SIM7080G GitHub

Features:

• ESP32 Variant: ESP32-S3
• Modem: SIM7080 (NB-IoT/Cat-M, not 4G Cat-1)
• GPS/GNSS: ❌ Cannot be used when modem is connected (manufacturer hardware limitation)
• Power Management: ⚠️ AXP2101 PMU - requires unofficial external component
• Power Pin: GPIO41 (inverted)
• Status Pin: Not available

Pin Configuration:

Critical Limitation: Power Management

🛑 This board uses an AXP2101 Power Management Unit (PMU) which does NOT have an official ESPHome component.

The package includes a workaround using an unofficial external component:

• External component: Quick and dirty implementation
• Repository: https://github.com/oarcher/piotech/components/axp2101)
• Limitations:
  • Not officially supported or maintained
  • Power OFF functionality is not implemented
  • May break with ESPHome updates
  • Not suitable for production deployments

Why This is Problematic:

1. No official ESPHome support for AXP2101
2. Unofficial component quality and maintenance cannot be guaranteed
3. Power management is critical for stable operation
4. Future ESPHome updates may break compatibility

GPS/GNSS Limitation:

❌ GPS/GNSS cannot be used when the modem is connected. This is a manufacturer hardware design limitation, not a software issue.

Modem Model:

The SIM7080 is a NB-IoT/Cat-M modem, not a 4G Cat-1 modem like the other boards. It's designed for low-power IoT applications with different network coverage and capabilities.

Package: packages/lilygo_tsim7080.yaml

For faster data transfer or to resolve issues with large transfers, enable CONFIG_UART_ISR_IN_IRAM:

esp32: framework: type: esp-idf sdkconfig_options: CONFIG_UART_ISR_IN_IRAM: y CONFIG_ESP_TASK_WDT_TIMEOUT_S: "60"

⚠️ Warning: This conflicts with the UART component and may cause crashes if you're using multiple UARTs.

If you encounter "CMUX: Failed to defragment longer payload" warnings:

esp32: framework: type: esp-idf sdkconfig_options: CONFIG_ESP_MODEM_CMUX_DEFRAGMENT_PAYLOAD: n CONFIG_ESP_MODEM_USE_INFLATABLE_BUFFER_IF_NEEDED: y CONFIG_ESP_MODEM_CMUX_USE_SHORT_PAYLOADS_ONLY: n

• Modem Component
• GPS Component
• MQTT
• Wireguard

• SIM7600 AT Command Manual
• SIM7600 Hardware Design
• A7670E AT Command Manual

• esp_modem Library

Contributions are welcome! If you have:

• Successfully used pins that are marked as unclear
• Found workarounds for known issues
• Support for additional boards
• Improvements to existing packages

Get in touch:

• Open an issue or pull request on GitHub
• Join the discussion on Discord: ESPHome Modem Discussion