SolarOS 4.13.4 manual · service

Cellular modem

SolarOS exposes cellular configuration through a common modem service. Each hardware driver translates the common profile into its own command set. The Waveshare ESP32-S3-SIM7670G-4G V2.0 registers its SIM7670 as modem0 on modem-uart. The UART starts at the module's 115200-baud boot rate, then the driver defaults to auto, which temporarily raises both ends to the SIM7670 maximum of 460800 baud. It verifies the selected rate after every power-on or reset and falls back to the boot rate if negotiation fails; the module's persistent IPREX setting is not changed. Show or persist another supported rate while packet data is disconnected:

modem baud modem0
modem baud modem0 230400
modem baud modem0 auto

Baud selection is an optional capability of the common modem service. USB and other non-serial modem transports do not expose it.

Open the modem TUI to inspect status, control power/data, and edit the saved profile and optional baud setting. Use the textual commands when scripting or diagnosing:

modem
modem list
modem status

Use Tab to switch between Status and Settings. The arrow keys select settings and change enumerated values; Enter edits text or runs the selected action. Profile fields remain a draft until save profile is selected. Password values are represented only as set or none, and password input is masked.

If the driver has a hardware power or reset binding, control it without using module-specific AT commands:

modem power off modem0
modem power on modem0
modem reset modem0

modem list reports whether power and reset control are available. On the Waveshare V2.0 board, set CAM OFF, HUB ON, 4G OFF, and USB OFF. SolarOS owns the active-high GPIO21 modem rail when the 4G switch is OFF. The module RESET pin is not routed to the ESP32, so modem reset performs a full rail power cycle. An expansion attachment can instead provide both a power line and a dedicated active-low reset line.

Create and save a packet-data profile without entering AT commands:

modem profile set modem0 --apn internet --ip ipv4v6 --auth none
modem profile show modem0

Use --dns <ipv4> when the SIM or APN requires a specific resolver. Omit it, or use --dns auto, to accept the DNS server negotiated by PPP. For example:

modem profile set modem0 --apn internet --dns 8.8.8.8 --ip ipv4v6 --auth none

The profile stores the APN, optional IPv4 DNS override, IP family, authentication mode, and optional username/password in NVS. profile show never prints the password. PAP and CHAP require both --user and --password; none and auto reject explicit credentials. auto asks the backend to use its default authentication policy. The SIM7670 backend currently resolves auto to no authentication.

Bring the saved cellular connection up or down:

modem connect modem0
modem status modem0
modem disconnect modem0

modem connect reapplies the saved profile, attaches packet service, dials the SIM7670 data connection, and waits for its PPP interface to obtain an IPv4 address. The cellular interface becomes the preferred route for new SolarOS traffic while it is connected. modem status reports network=up and prints the interface, IPv4 address, gateway, and DNS server. The Waveshare target accepts an ipv4v6 modem profile but currently brings up IPv4 over PPP.

The SIM7670 UART is exclusive. While PPP is connected, SolarOS uses that UART for network frames, so raw modem at commands, SIM unlock, profile changes, and GNSS operations return ESP_ERR_INVALID_STATE. modem status remains available using the registration and signal values cached immediately before dialing. Run modem disconnect to stop PPP and return the UART to AT/GNSS operation. Concurrent PPP and AT/GNSS access would require a later CMUX stage.

Remove both the stored profile and the modem-side context configuration:

modem profile clear modem0

If a SIM is waiting for its PIN, unlock it separately:

modem sim unlock 1234 modem0

The PIN is sent to the modem but is not stored by SolarOS. Shell commands can remain in terminal history, so clear sensitive command history after entering a PIN or APN password.

Raw AT access remains available for diagnostics. Quote the command as one shell argument; the optional device name and timeout follow it:

modem at "AT+CGMM"
modem at "AT+COPS?" modem0 10000

The command accepts only text that starts with AT and rejects embedded CR or LF characters. It prints the modem response, including an ERROR, before it prints the SolarOS error name.

The modem also registers a GNSS receiver with the common service. Turn it on before requesting a fix:

gnss power on modem0
gnss fix modem0 5000
gnss power off modem0

gnss status [name] reports the selected logical receiver's power, fix, fix type, and satellite state. gnss fix reports latitude, longitude, altitude, and UTC when the receiver has a valid fix. The SIM7670 backend uses AT+CGNSSINFO, including its fix mode and satellite count. Some SIM7670 firmware omits the satellite fields until it has a fix; SolarOS reports that state as satellites=unknown, not as a measured count of zero.

Because this SIM7670 contains both functions, gnss power on enables the shared modem rail before it starts the GNSS engine, and gnss power off shuts that rail down, disconnecting an active cellular/PPP session first. Modem power-off or reset also marks the co-located GNSS receiver off. Turning modem power back on does not start the GNSS engine; use gnss power on again. This relationship belongs to the combined SIM7670 driver only. A separately registered modem and GNSS receiver have independent power state and controls.

The modem profile API and PPP network service are shared. The PPP service owns network negotiation, authentication, DNS, routing, and interface state over a generic byte-stream transport. The SIM7670 adapter supplies UART reads and writes plus its modem-specific packet attach, dial, escape, and hang-up steps. Other PPP users can supply another pull-based byte stream or feed received frames from a push-based transport without depending on the modem service.

Quick reference

modem list shows registered devices, concrete drivers, and power, reset, and baud capabilities. modem status [name] reads power, SIM, LTE registration, signal, packet-context, and IP-interface state. modem power on|off [name] controls an optional hardware rail and modem reset [name] uses the driver's reset method. modem baud [name] [auto|rate] manages an optional serial transport rate. modem profile set|show|clear manages persistent cellular settings. modem connect|disconnect brings the PPP network interface up or down. modem sim unlock enters a SIM PIN. modem at remains an advanced diagnostic escape hatch. Use gnss status [name], gnss power on [name], gnss fix [name] [timeout-ms], and gnss power off [name] for the integrated SIM7670 GNSS receiver.