gsm-sms

Async Python library that exclusively owns a GSM modem serial port. It serializes AT commands, decodes text/PDU and multipart SMS, emits typed events, and deletes incoming messages only after ack_incoming().

from gsm_sms.core.events import IncomingSmsEvent
from gsm_sms.core.modem import GsmSms

modem = GsmSms(port="/dev/ttyUSB0")
await modem.start()

async for event in modem.events():
    if isinstance(event, IncomingSmsEvent):
        await deliver(event.message)
        await modem.ack_incoming(event.message.id)

Install the library with pip install gsm-sms. Applications that talk to a gateway instead of opening the modem use pip install "gsm-sms[client]" and gsm_sms.client.GatewayClient.

Gateway with Docker Compose

The gateway is a separate, Docker-only REST/SSE service. It persists events and send operations in SQLite, supports resumable SSE cursors, and must remain the only process using the modem.

services:
  gateway:
    image: ghcr.io/jag-k/gsm-sms-gateway:latest
    restart: unless-stopped
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0
    environment:
      MODEM__SERIAL_PORT: /dev/ttyUSB0
      MODEM__BAUD_RATE: "115200"
      MODEM__SMS_STORAGE: SM
      JOURNAL__DATABASE_PATH: /data/gateway.sqlite3
    volumes:
      - ./data:/data
    ports:
      - 127.0.0.1:8000:8000
    networks:
      - gsm-sms

networks:
  gsm-sms:
    name: gsm-sms-network

docker compose up -d
curl http://127.0.0.1:8000/v1/health

For all environment variables, see docs/gateway/Configuration.md. The published Python package intentionally excludes FastAPI, Docker, Telegram, and Matrix.