Add SIM868 cellular fallback for tracking uploads (untested, no SIM card)
modules/app_cellular.py: uses the SIM868's built-in AT-command HTTP(S) client (AT+HTTPINIT/HTTPPARA/HTTPACTION/HTTPREAD) instead of a real ppp0 interface, since the module's GNSS (polled continuously by app_gps.py) and its GSM/GPRS radio share the same physical UART (/dev/serial0) - a pppd/chat dial-up would take over that port entirely and starve GNSS polling. Staying in AT-command mode lets cellular HTTP calls interleave safely through the same serial lock. Only carries small JSON tracking batches, never dashcam video - cellular is far too slow/limited for that, and the modem's HTTP AT interface has too small an internal buffer anyway. Dashcam uploads remain WiFi/Ethernet-only, unchanged. modules/app_upload.py: tracking-batch upload always tries WiFi/ Ethernet first; only on a connection-level failure (not an HTTP error status, which means the server was reached) does it retry over cellular. Exposes last_network_path/cellular_fallback_configured in /api/upload/status; UI shows which path the last batch used. Feature-flagged off by default via new YARIS_CELLULAR_ENABLED/ YARIS_CELLULAR_APN/_APN_USER/_APN_PASS keys in db/upload_creds.env (all blank by default) - has zero effect on the existing WiFi upload path unless explicitly configured. Regression-tested against the real deployed server that normal WiFi uploads are unaffected while cellular stays unconfigured. *** UNTESTED against real cellular hardware - no SIM card was *** available. See docstrings in app_cellular.py and PLAN.md for *** exactly what needs validation once a SIM card is available. Co-authored-by: Copilot <[email protected]>
This commit is contained in:
Mathieu Moran
@@ -0,0 +1,194 @@
|
||||
"""SIM868 GSM/GPRS cellular fallback for uploading trip/GPS tracking batches
|
||||
when there is no WiFi/Ethernet path to the remote server.
|
||||
|
||||
*** UNTESTED - no SIM card was available to validate this against a real
|
||||
*** cellular network. Written defensively (every AT exchange is wrapped so a
|
||||
*** failure just raises CellularError, never crashes the app) but the exact
|
||||
*** AT command dialect/timing may need small tweaks once a SIM is inserted
|
||||
*** and this can actually be exercised. See "Verifying on real hardware"
|
||||
*** below and the Phase 9 notes in PLAN.md.
|
||||
|
||||
Why AT-command HTTP instead of a real ppp0 network interface: the SIM868's
|
||||
GNSS (used by modules/app_gps.py) and its GSM/GPRS radio are both driven over
|
||||
the *same* physical UART (/dev/serial0). A classic pppd/chat dial-up would put
|
||||
that UART into raw PPP framing for as long as the link is up, which would
|
||||
starve/conflict with the GNSS AT+CGNSINF polling already running continuously
|
||||
in app_gps.py. SIMCOM modules instead expose a built-in "HTTP(S) Application"
|
||||
AT command set (AT+HTTPINIT / AT+HTTPPARA / AT+HTTPACTION / AT+HTTPREAD) that
|
||||
stays in normal AT command mode the whole time, so it can safely interleave
|
||||
with GNSS polling through the same serial lock (modules.app_gps._serial_lock) -
|
||||
each exchange just briefly delays the next GPS poll, it never takes over the
|
||||
port.
|
||||
|
||||
This only carries small JSON tracking-batch payloads - dashcam video uploads
|
||||
remain WiFi/Ethernet-only (see modules/app_upload.py), both because cellular
|
||||
data is far too slow/limited for video files and because the modem's HTTP
|
||||
AT interface has a small internal buffer unsuited to multi-MB bodies.
|
||||
"""
|
||||
import os
|
||||
import time
|
||||
|
||||
from modules import app_gps
|
||||
|
||||
APN = os.getenv("YARIS_CELLULAR_APN", "")
|
||||
APN_USER = os.getenv("YARIS_CELLULAR_APN_USER", "")
|
||||
APN_PASS = os.getenv("YARIS_CELLULAR_APN_PASS", "")
|
||||
ENABLED = os.getenv("YARIS_CELLULAR_ENABLED", "") == "1"
|
||||
|
||||
GPRS_BRINGUP_TIMEOUT = 30 # seconds to wait for AT+CIICR / AT+CIFSR
|
||||
HTTP_ACTION_TIMEOUT = 60 # seconds to wait for the +HTTPACTION URC (2G/3G can be slow)
|
||||
|
||||
_gprs_context_up = False
|
||||
|
||||
|
||||
class CellularError(Exception):
|
||||
"""Raised for any cellular-modem/AT-command failure - always caught by
|
||||
the caller (modules/app_upload.py), never allowed to crash the app."""
|
||||
|
||||
|
||||
def is_configured():
|
||||
"""True once the user has filled in an APN and flipped the enabled flag
|
||||
in db/upload_creds.env. Off by default - nothing cellular-related runs
|
||||
unless explicitly opted into."""
|
||||
return ENABLED and bool(APN)
|
||||
|
||||
|
||||
def _read_until(ser, terminators, timeout):
|
||||
"""Read from the modem until one of the given substrings shows up in the
|
||||
accumulated buffer, or timeout. Returns the buffer (decoded, best-effort)."""
|
||||
deadline = time.time() + timeout
|
||||
buf = ""
|
||||
while time.time() < deadline:
|
||||
chunk = ser.read(1024)
|
||||
if chunk:
|
||||
buf += chunk.decode(errors="replace")
|
||||
if any(t in buf for t in terminators):
|
||||
return buf
|
||||
else:
|
||||
time.sleep(0.1)
|
||||
return buf
|
||||
|
||||
|
||||
def _at(ser, cmd, terminators=("OK", "ERROR"), timeout=5):
|
||||
"""Send one AT command and wait for a terminator. Raises CellularError
|
||||
if the modem responds with ERROR or nothing recognizable within timeout."""
|
||||
ser.reset_input_buffer()
|
||||
ser.write((cmd + "\r\n").encode())
|
||||
resp = _read_until(ser, terminators, timeout)
|
||||
if "ERROR" in resp and "OK" not in resp:
|
||||
raise CellularError(f"{cmd!r} -> {resp!r}")
|
||||
if not any(t in resp for t in terminators):
|
||||
raise CellularError(f"{cmd!r} timed out, got {resp!r}")
|
||||
return resp
|
||||
|
||||
|
||||
def _ensure_gprs_context():
|
||||
"""Bring up the GPRS data context (APN attach) if not already up.
|
||||
|
||||
Reuses app_gps's serial connection/lock - see module docstring for why.
|
||||
"""
|
||||
global _gprs_context_up
|
||||
|
||||
with app_gps._serial_lock:
|
||||
ser = app_gps._get_serial()
|
||||
|
||||
if _gprs_context_up:
|
||||
# Cheap check that the context is still alive before trusting it.
|
||||
try:
|
||||
resp = _at(ser, "AT+CIFSR", terminators=("\r\n",), timeout=5)
|
||||
if "." in resp and "ERROR" not in resp:
|
||||
return
|
||||
except CellularError:
|
||||
pass
|
||||
_gprs_context_up = False
|
||||
|
||||
_at(ser, "AT+CGATT=1", timeout=10)
|
||||
|
||||
apn_cmd = f'AT+CSTT="{APN}","{APN_USER}","{APN_PASS}"'
|
||||
_at(ser, apn_cmd, timeout=10)
|
||||
|
||||
_at(ser, "AT+CIICR", timeout=GPRS_BRINGUP_TIMEOUT)
|
||||
|
||||
resp = _at(ser, "AT+CIFSR", terminators=("\r\n",), timeout=10)
|
||||
if "ERROR" in resp or "." not in resp:
|
||||
raise CellularError(f"AT+CIFSR did not return an IP: {resp!r}")
|
||||
|
||||
_gprs_context_up = True
|
||||
|
||||
|
||||
def http_post_json(url, body_bytes, extra_headers, timeout=HTTP_ACTION_TIMEOUT):
|
||||
"""POST a small JSON body to `url` via the modem's built-in HTTP client.
|
||||
|
||||
Returns (status_code, response_body_bytes). Raises CellularError on any
|
||||
failure (modem not responding, no network attach, HTTP-layer failure,
|
||||
etc.) - callers should catch this broadly and treat it the same as a
|
||||
network-unreachable condition.
|
||||
"""
|
||||
if not is_configured():
|
||||
raise CellularError("cellular fallback not configured (APN/enabled flag not set)")
|
||||
|
||||
_ensure_gprs_context()
|
||||
|
||||
with app_gps._serial_lock:
|
||||
ser = app_gps._get_serial()
|
||||
try:
|
||||
_at(ser, "AT+HTTPTERM", timeout=3)
|
||||
except CellularError:
|
||||
pass # fine if nothing was initialized yet
|
||||
|
||||
_at(ser, "AT+HTTPINIT", timeout=5)
|
||||
try:
|
||||
_at(ser, 'AT+HTTPPARA="CID",1', timeout=5)
|
||||
_at(ser, f'AT+HTTPPARA="URL","{url}"', timeout=5)
|
||||
if url.lower().startswith("https"):
|
||||
try:
|
||||
_at(ser, "AT+HTTPSSL=1", timeout=5)
|
||||
except CellularError:
|
||||
# Older SIMCOM firmware/certificate stores sometimes
|
||||
# don't support this - surfacing as a clear error is more
|
||||
# useful than silently falling back to plain HTTP against
|
||||
# an HTTPS-only endpoint.
|
||||
raise CellularError(
|
||||
"modem does not support AT+HTTPSSL - HTTPS upload via "
|
||||
"cellular is unavailable on this firmware. Consider a "
|
||||
"plain-HTTP router port-forward path for cellular use."
|
||||
)
|
||||
_at(ser, 'AT+HTTPPARA="CONTENT","application/json"', timeout=5)
|
||||
|
||||
header_lines = "".join(f"{k}: {v}\r\n" for k, v in extra_headers.items())
|
||||
_at(ser, f'AT+HTTPPARA="USERDATA","{header_lines}"', timeout=5)
|
||||
|
||||
_at(
|
||||
ser,
|
||||
f"AT+HTTPDATA={len(body_bytes)},{int(timeout * 1000)}",
|
||||
terminators=("DOWNLOAD", "ERROR"),
|
||||
timeout=5,
|
||||
)
|
||||
ser.write(body_bytes)
|
||||
_read_until(ser, ("OK", "ERROR"), timeout=10)
|
||||
|
||||
action_resp = _at(
|
||||
ser,
|
||||
"AT+HTTPACTION=1",
|
||||
terminators=("+HTTPACTION:",),
|
||||
timeout=timeout,
|
||||
)
|
||||
|
||||
status_code = 0
|
||||
for line in action_resp.splitlines():
|
||||
if "+HTTPACTION:" in line:
|
||||
# +HTTPACTION: <method>,<status_code>,<data_len>
|
||||
parts = line.split(":", 1)[1].strip().split(",")
|
||||
if len(parts) >= 2:
|
||||
status_code = int(parts[1])
|
||||
break
|
||||
|
||||
read_resp = _at(ser, "AT+HTTPREAD", terminators=("OK", "ERROR"), timeout=15)
|
||||
body = read_resp.encode(errors="replace")
|
||||
|
||||
return status_code, body
|
||||
finally:
|
||||
try:
|
||||
_at(ser, "AT+HTTPTERM", timeout=5)
|
||||
except CellularError:
|
||||
pass
|
||||
Reference in New Issue
Block a user