Skip to content
alekajiya
Open menu
All projects

Własna bramka SMS: modem GSM, dwie karty i API dla wielu systemów

4 min readProgramowanie

Moje systemy wysyłają SMS-y o przerwanych transmisjach, awariach tablic i zmianach w kopiach zapasowych. Zamiast płacić za komercyjną bramkę, zbudowałem własną: modem Quectel M95, dwie karty SIM, API w Pythonie, podpisane webhooki, raporty doręczenia i panel z logowaniem dwuetapowym.

Technologies

  • Python
  • FastAPI
  • pyserial
  • Quectel M95
  • SQLite
  • Redis
  • Jinja2
  • Docker

Kilka moich systemów musi czasem kogoś szybko zaalarmować. Transmisje ChurchStream informują o przerwanym streamie, tablice informacyjne i kiosk zgłaszają awarie, a nocne kopie zapasowe wykrywają zmiany w kodzie stron.

E-mail łatwo przeoczyć, a komercyjne bramki SMS liczą za każdą wiadomość. Dlatego zbudowałem własną bramkę: mały modem GSM w homelabie i usługę, która udostępnia go innym systemom przez API.

Pulpit bramki SMS: pasek stanu z modemem, siecią, sygnałem 70 procent i aktywną kartą SIM1, kafelki z liczbą wysłanych i odebranych wiadomości, wykres z ostatnich 24 godzin i lista ostatnich wiadomości z rozmytymi numerami(enlarge)
Pulpit bramki: stan modemu, ruch z dziś i ostatnie wiadomości

Sprzęt: modem za kilkadziesiąt złotych

Sercem bramki jest płytka a-GSM II Shield z modemem Quectel M95. Ma dwa gniazda kart SIM, a z serwerem łączy się przez USB. Obie karty są w sieci Play: jedna dla moich systemów, druga dla aplikacji instytucji.

Modem rozmawia komendami AT przez port szeregowy. Usługa pilnuje, czy modem odpowiada, czy jest zarejestrowany w sieci i jaki ma sygnał. Publiczny stan, bez klucza, odświeża się co 30 sekund i służy do monitoringu.

Wersja 1.0: prosta usługa w Pythonie

Pierwsza wersja powstała w marcu 2026 roku. Robiła to, czego potrzebowały moje skrypty:

  • wysyłka pojedynczych SMS-ów i wysyłka masowa przez kolejkę w Redis,
  • historia wiadomości w bazie, z filtrami po numerze, dacie i kierunku,
  • przełączanie kart SIM i odbiór wiadomości z nieaktywnej karty co 5 minut,
  • limit zapytań na adres IP,
  • zgodność z API komercyjnej bramki SMSEagle, więc gotowe integracje działały bez zmian.

Wersja 2.0: wielu klientów na jednej bramce

Z bramki zaczęły korzystać kolejne aplikacje, w tym panel SMS dla ludzi. Jeden wspólny klucz API przestał wystarczać, więc w listopadzie przebudowałem bramkę. Klient to teraz aplikacja albo grupa integracji. Każdy ma:

  • przypisaną kartę SIM, z której wysyła i na którą dostaje odpowiedzi,
  • własne klucze API z uprawnieniami do wysyłki, odczytu, stanu i kart SIM,
  • opcjonalny dobowy limit wiadomości,
  • własny adres webhooka na zdarzenia.

Klucz jest pokazywany tylko raz, przy tworzeniu. W bazie zostaje jego skrót SHA-256. Stary klucz z pliku konfiguracyjnego należy do klienta „Integracje dotychczasowe”, więc nic, co już działało, nie wymagało zmian.

Lista Klienci i klucze: trzy aktywne wpisy z przypisaną kartą SIM, adresem webhooka, liczbą kluczy i ruchem z 7 dni, nazwa jednego klienta i adresy rozmyte(enlarge)
Klienci bramki z kartą SIM, webhookiem i kluczami

Długie wiadomości i polskie znaki

Bramka pracuje w trybie PDU. Długa wiadomość idzie jako jeden SMS wieloczęściowy, który telefon skleja w całość. Tekst z polskimi literami jest kodowany w UCS-2, czyli mieści 70 znaków w jednym SMS-ie i 67 w każdej części dłuższej wiadomości.

Każdy SMS jest wysyłany z prośbą o raport doręczenia. Dzięki temu bramka wie nie tylko, że przekazała wiadomość do sieci, ale też, że dotarła do telefonu.

Lista Wiadomości z filtrami po kliencie, kierunku, stanie i numerze, wśród wpisów testowa wiadomość z polskimi znakami wysłana w trzech częściach i oznaczona jako doręczona(enlarge)
Wiadomość z polskimi znakami wysłana w trzech częściach i doręczona

Podpisane webhooki

Zamiast odpytywać bramkę, aplikacja może dostawać zdarzenia: odebrany SMS, wysłany, doręczony, niedoręczony, błąd albo zmiana stanu bramki. Każde zdarzenie jest podpisane HMAC-SHA256 z czasem wysłania, więc klient sprawdzi, że pochodzi z bramki i nie jest powtórką.

Gdy klient nie odpowiada, bramka ponawia po 10 sekundach, 30 sekundach, 2, 10 i 30 minutach, a potem co godzinę. Po około 6 godzinach oznacza zdarzenie jako nieudane, a w panelu można je ponowić ręcznie.

Lista webhooków: zdarzenia message.received, message.delivered, message.sent i webhook.test, każde dostarczone za pierwszym razem z odpowiedzią HTTP 204, jedno rozwinięte z treścią JSON(enlarge)
Webhooki dostarczone do klienta, z treścią zdarzenia

Panel administracyjny

Bramka ma prosty panel, renderowany po stronie serwera. Logowanie wymaga hasła i kodu z aplikacji uwierzytelniającej, a sesje są zapisane w bazie. W panelu są:

  • pulpit z ruchem na obu kartach i wykresem z ostatnich 24 godzin,
  • klienci i klucze API,
  • wszystkie wiadomości z filtrami,
  • statystyki dzienne według klienta i karty,
  • webhooki z treścią zdarzeń i ręcznym ponawianiem,
  • dziennik zdarzeń: logowania, zmiany klientów i kluczy, nietypowe komunikaty z modemu.
Statystyki z 30 dni: 233 wysłane wiadomości, zero błędów, 12 odebranych i słupkowy wykres dzienny z podziałem na klientów(enlarge)
Statystyki z 30 dni według klienta
Dziennik zdarzeń: utworzenie i zmiana klientów oraz konfiguracja logowania dwuetapowego, z datą, kontem, szczegółami w JSON i rozmytym adresem IP(enlarge)
Dziennik zdarzeń z działaniami administratorów

Ostrożnie z wysyłką masową

Operator blokuje karty, które w krótkim czasie wysyłają dużo wiadomości, i nie podaje progu. Dlatego wysyłka zbiorcza jest celowo powolna:

  • około 8 sekund przerwy między wiadomościami, z losowym rozrzutem,
  • 5 minut pauzy po każdych 50 wiadomościach,
  • najwyżej 200 części SMS na godzinę.

Powiadomienie do kilkuset osób trwa więc dłużej, ale karta nie zostanie zablokowana w środku wysyłki.

Bramka SMS to mały modem i trochę cierpliwości. Najtrudniejsze nie było wysłanie wiadomości, tylko pewność, że dotarła i że operator nie zablokuje karty.
Aleksander Kowal

Co dalej

Dla ludzi, którzy nie chcą korzystać z API, powstał panel SMS do wysyłki powiadomień z przeglądarki. W planach mam pobieranie treści MMS, bo bramka już rozpoznaje powiadomienia o nich, oraz węzeł sieci LoRa jako osobną aplikację obok bramki.

Stack

  • Python, FastAPI i pyserial do obsługi modemu komendami AT,
  • SQLAlchemy z SQLite, Redis jako kolejka wysyłki masowej,
  • panel w Jinja2, hasła argon2id, kody TOTP,
  • Docker na serwerze w homelabie.

Was this useful?

New posts by e-mail

Every now and then, when a new post or project goes up. No ads.

Got an idea, a question or a comment? Write to me:Enable JavaScript to see the e-mail address

Comments

No comments yet. Be the first.

Click or scroll to zoom in. Drag to move around.Double tap or pinch to zoom in.

More projects

Local law register: five thousand acts in one search engine

Orders and resolutions were scattered across the BIP public information bulletin, signed packages from the document management system, a network drive and a paper archive. I built a register that joins these sources, shows each act's status, electronic signature and Official Journal publication, and points out gaps in the numbering.

SMS panel: notifications sent from the browser

A web front end for my SMS gateway: sending to numbers, contacts and groups, scheduled sending, conversations, a shared inbox and notification sign-ups confirmed with an SMS code. One codebase runs as two instances, each with its own SIM card and look.

My own SMS gateway: a GSM modem, two SIM cards and an API for many systems

My systems send text messages about interrupted streams, failing information boards and changes spotted by backups. Instead of paying for a commercial gateway, I built my own: a Quectel M95 modem, two SIM cards, a Python API, signed webhooks, delivery reports and a panel with two-factor login.