TSD-LC-26-001 · SISTEM PESAN NIRKABEL JARAK JAUH
Obrolan jarak jauh
tanpa internet.
Tanpa SIM. Tanpa BTS.
LoRa Chat menyalakan obrolan dua arah di tengah blank spot total: antarmuka Jetpack Compose bergaya iOS di ponsel Anda, jembatan Bluetooth ke gateway ESP32, lalu gelombang radio LoRa SX1278 menembus kilometer ke ponsel lawan bicara — dengan enkripsi ujung-ke-ujung, pelacak GPS, radar taktis, dan tombol SOS.
| Frekuensi RF | 915 MHz · ops. 433/868/923 |
| Modulasi | LoRa CSS · SF7 |
| Bandwidth / Coding | 125 kHz / 4-5 |
| Daya pancar | 17 dBm PA_BOOST |
| Sync word | 0x12 private net |
| Auto-ACK | 6 s × 3 retry |
| Anggaran frame | 240 B / plafon 255 B |
| Enkripsi | AES-256-GCM + PBKDF2 |
| Presensi peer | beacon 30 s · exp 90 s |
| Siaran SOS | setiap 15 s |
| Unit test | 325 PASS / 0 FAIL |
| APK release | ±1,9 MB |
Tentang Proyek
Satu ponsel, satu gateway seukuran kantong, dan spektrum radio terbuka. LoRa Chat adalah sistem pesan peer-to-peer yang tidak memerlukan internet, kartu SIM, menara BTS, maupun server terpusat — ponsel berbicara ke ESP32 lewat Bluetooth Classic (RFCOMM/SPP), dan gateway memancarkannya sebagai gelombang LoRa Chirp Spread Spectrum di pita ISM.
Dokumen ini disusun dari pembacaan langsung kode sumber pada commit d3f908c — setiap angka dapat dilacak ke file dan barisnya. Aplikasi Android ditulis dalam Kotlin 2.2.10 dengan Jetpack Compose Material 3, arsitektur bersih (domain murni, repository, ViewModel) dan injeksi dependensi manual tanpa framework. Ia berjalan dari Android 7.0 hingga target SDK 36.
Sisi perangkatnya sederhana dan murah: papan ESP32 DevKit V1 (dual core 240 MHz) plus modul radio Ai-Thinker Ra-02 berbasis Semtech SX1278, dengan total komponen seharga ratusan ribu rupiah. Firmware gateway 601 baris C++/Arduino berperan sebagai transparent bridge dua arah antara Bluetooth dan radio.
Skenarionya yang sesungguhnya: tanggap bencana saat jaringan seluler tumbang, pendakian di blank spot, pelayaran, atau komunitas perbatasan yang tak pernah tercakup BTS. Selama kedua pihak memegang ponsel dan gateway masing-masing, obrolan tetap berjalan — dari ratusan meter di perkotaan padat hingga belasan kilometer pada garis pandang bebas.
Sebagai alat riset, repo juga membawa dua firmware pendukung: Web Simulator yang menyalakan antarmuka chat lewat Wi-Fi SoftAP dengan satu ESP32 saja (tanpa modul LoRa), dan Wi-Fi Virtual Bridge sepasang node sebagai pengganti sambungan radio fisik saat pengembangan.
CATATAN PENGARANG — Topologi sebenarnya adalah BINTANG, bukan mesh: firmware tidak meneruskan paket LoRa-ke-LoRa, tidak ada multi-hop. Radio adalah medium broadcast; semua node dalam jangkauan saling mendengar, tetapi penyaringan alamat penerima terjadi di aplikasi Android, bukan di gateway.
Arsitektur
Satu pesan menempuh empat lapisan — aplikasi Compose, transport RFCOMM, gateway ESP32, lalu udara terbuka — dan tiba di ponsel lawan dalam hitungan detik.
Kotlin · Compose M3
Clean Architecture
RFCOMM/SPP
JSON + '\n'
dual core 240 MHz
transparent bridge
VSPI · 8 jalur
logika 3,3 V
modulasi CSS
CRC perangkat keras
SF7 · BW 125 kHz
17 dBm
para pengguna lain
topologi bintang
Setiap ponsel punya gateway sendiri; tidak ada routing dan hop count. Semua node dalam jangkauan radio saling mendengar, dan paket ditujukan lewat alamat pada JSON — disaring di aplikasi penerima.
ESP32 meneruskan frame apa pun antara Bluetooth dan radio, dua arah, tanpa memahami isinya. Gateway juga mengukur telemetri RSSI/SNR nyata dari paket terakhir dan melaporkannya sebagai network_status.
Enkripsi end-to-end terjadi di aplikasi — gateway hanya pernah memindahkan ciphertext yang tidak bisa dibukanya. Inilah yang membuat perlindungannya benar-benar ujung-ke-ujung.
▲ KIRIM ANDROID → PEER
- Tulis & kirim — batas UI 150 karakter; status
PENDINGdisimpan lebih dulu ke Room agar tak hilang bila aplikasi mati. - Bangun paket —
buildOutgoingPacket()mengenkripsi bila kontak punya passphrase; hasil di-cache permessageIdagar retry memakai byte yang sama persis. - Fragmentasi — bila serialisasi > 240 byte, pesan dipotong jadi
chat_fragmentdengan amplop terukur 142 byte (kasus terburuk). - Tulis ke RFCOMM — JSON satu baris +
\n; status menjadiSENT. - ESP32 memancarkan — frame > 255 byte ditolak dan dicatat; lalu
LoRa.beginPacket()ke udara terbuka. - Tunggu ACK — timeout 6 detik; hingga 3 kali retry (total 4 transmisi, ±24 detik) sebelum
FAILED.
▼ TERIMA PEER → ANDROID
- Radio mendengar —
LoRa.parsePacket()membaca payload sekaligus mengukur RSSI & SNR nyata paket terakhir. - Telemetri — ESP32 mengirim
network_status(rssi/snr) tiap paket; heartbeat tiap 10 detik; angka basi setelah 30 detik. - Parse & filter — urutan wajib: tolak milik sendiri → tolak untuk orang lain → dedup LRU 500 entri → baru kirim ACK.
- Dekripsi — hasil
PLAINTEXT/ENCRYPTED/UNDECRYPTABLE; ciphertext yang gagal dibuka tidak disimpan. - Rakit fragmen — buffer reassembly kedaluwarsa 60 detik; lengkap → diproses sebagai
chatutuh. - Tampil & beri tahu — disimpan ke Room, percakapan diperbarui, notifikasi pesan masuk via foreground service.
Index Fitur
Dirancang untuk skenario lapangan sesungguhnya — tanggap bencana, pendakian, laut, hingga operasi komunitas di daerah blank spot. Setiap entri berikut dijaga oleh satu atau lebih suite tes pada SEC.09.
Protokol Kabel
Semua komunikasi dibungkus JSON satu baris dengan pemisah newline (\n). Protokol v3 bersifat aditif: peer lama tetap bisa diajak bicara — field baru cukup dihilangkan, frame lama tetap identik byte-per-byte.
{
"protocol_version": 1,
"type": "chat",
"message_id": "msg_1758600000000_a1b2c3d4", // 26 karakter — dipakai dedup & ACK
"sender_id": "usr_tanz",
"sender_name": "Titan Tanz",
"receiver_id": "usr_budi", // kosong = broadcast
"timestamp": 1758600000000, // divalidasi & disanitasi
"message": "Halo Budi, koordinat evakuasi aman di posko A."
}{
"protocol_version": 2,
"type": "chat",
"message_id": "msg_1758600000000_a1b2c3d4",
"sender_id": "usr_tanz",
"sender_name": "Titan Tanz",
"receiver_id": "usr_budi",
"timestamp": 1758600000000,
"message": "Rk9vQmFyQmF6UXV4...", // ciphertext base64
"enc": 1, // penanda AES-256-GCM
"nonce": "tLN/FFL6xHfFvMDQ" // 12 byte acak per pesan
}{
"protocol_version": 3,
"type": "chat",
"message_id": "msg_1758600000000_a1b2c3d4",
"sender_id": "usr_tanz",
"sender_name": "Titan Tanz",
"receiver_id": "usr_budi",
"timestamp": 1758600000000,
"message": "v1|-6.2000000|106.8166667|12.5|35.0|gps|ab12cd34|1|1",
"kind": "location" // opsional; default "text"
}// Payload darurat dalam field "message" (terenkripsi bila E2E aktif)
"sos_v1|-6.20000|106.81667|12.5|35.0|gps|sos_ab12|@riris|ACTIVE"
// struktur: prefix|lat|lon|akurasi_m|elevasi_m|sumber|session|username|status
// status: ACTIVE → VERIFIED → STOPPED
// disiarkan berulang setiap 15 detik selama darurat berlangsung{ "protocol_version": 1, "type": "ack", "message_id": "msg_1758600000000_a1b2c3d4" } // Dikirim SETELAH paket lolos penyaringan (bukan milik sendiri, // memang untuk kita, dan belum pernah diterima) — urutan ini // mencegah node lain ikut meng-ACK paket yang bukan miliknya.
{ "protocol_version": 1, "type": "presence", "user_id": "usr_tanz", "username": "@tanz", "display_name": "Titan Tanz", "node_id": "gateway-local", "timestamp": 1758600000000 } // Beacon tiap 30 detik; peer dianggap offline setelah 90 detik.
{ "protocol_version": 1, "type": "network_status", "node_id": "esp32-gateway-local", "connected": true, "rssi": -72, "snr": 9.2 } // Telemetri gateway: RSSI/SNR nyata paket terakhir; basi setelah 30 dtk.
{ "protocol_version": 1, "type": "chat_fragment", "message_id": "msg_1758600000000_a1b2c3d4", "fragment_id": 1, "total_fragments": 4, "payload": "{\"protocol_version\":1,\"type\":\"chat\"..." } // payload = potongan JSON pesan utuh (bukan potongan teks!). // Buffer reassembly kedaluwarsa 60 detik.
chat_fragment terukur 136–142 byte via serialisasi nyata — versi lama salah 6 byte per fragmen.Enkripsi End-to-End
Radio LoRa adalah medium broadcast: siapa pun dengan penerima sepandan bisa mendengar. Karena itu enkripsi terjadi di aplikasi, sebelum byte menyentuh Bluetooth — gateway hanya pernah melihat ciphertext.
Penyadap hanya melihat ciphertext base64 yang tidak bisa dibuka.
Tag GCM menolak ciphertext yang diubah sedikit pun.
AAD mengikat routing — menulis ulang receiver_id merusak tag.
Siapa bicara dengan siapa dan kapan harus terbaca untuk routing; hanya isi yang terlindungi.
Satu kunci statis per pasangan; passphrase bocor hari ini = seluruh rekaman lama terbuka.
Pemalsuan masih mungkin — lihat ERRATA E-03.
PBKDF2-WithHmacSHA256 baru tersedia sejak API 26, sedangkan aplikasi berjalan dari minSdk 24. HMAC tidak bergantung pada ketahanan tabrakan SHA-1 dan NIST SP 800-132 masih menyetujuinya.
Kedua ujung harus menurunkan kunci yang sama tanpa bolak-balik di tautan yang mahal. Salt dihitung dari user id yang diurutkan — arah A→B dan B→A identik.
Enkripsi gagal = pesan tidak dikirim sama sekali dan berstatus FAILED. Jalan pintas "kirim saja plaintext" membocorkan pesan tanpa sepengetahuan pengguna.
Lokasi · Radar · SOS
Koordinat GPS dikirim hemat byte lewat radio, digabung menjadi kartu lokasi interaktif, diproyeksikan ke radar taktis — dan saat keadaan darurat, disiarkan ke seluruh jaringan.
SKALA 50 M – 250 KM · 4 CINCIN · 8 PENJURU
Membungkus android.location.LocationManager langsung — 100% kompatibel dengan perangkat AOSP/ROM tanpa GMS di lapangan. Fix instan dari getLastKnownLocation (< 2 menit, ≤ 100 m).
Jarak Haversine + bearing 8 penjuru ("450 m ke barat laut"), tombol buka di peta via intent geo: (Organic Maps / OsmAnd / GMaps) dengan fallback salin koordinat, dan tombol izin lokasi kontekstual.
Satu sesi = 1 fix tiap 30 detik selama 3 menit via foreground service tipe location, dengan notifikasi sisa waktu + tombol hentikan. Titik berurutan dalam 5 menit digabung jadi satu kartu timeline.
TacticalRadarMath memilih skala dari daftar standar 50 m – 250 km, menggambar 4 cincin jarak, dan menandai peer yang keluar radar — plus dialog radar layar penuh.
Satu tombol di layar chat menyiarkan paket sos_v1 berisi koordinat, sumber fix, identitas, dan status ke seluruh node dalam jangkauan — diulang otomatis setiap 15 detik hingga dihentikan atau diverifikasi. Penerima melihat banner peringatan dengan jarak & arah ke korban, plus dialog SOS dengan radar.
Hardware & Firmware
Profil default: ESP32 DevKit V1 + modul Ai-Thinker Ra-02 (SX1278). Firmware gateway 601 baris C++/Arduino berperan sebagai jembatan transparan dua arah Bluetooth ⇄ LoRa.
Modul Ra-02/SX1278 beroperasi pada logika 3,3 V. Menyambungkan VCC ke pin 5V/VIN ESP32 akan membakar modul radio secara permanen. Pin DIO1–DIO5 tidak perlu dihubungkan.
| TBL. 03 — Pengkabelan Ra-02 / SX1278 → ESP32 DevKit V1 | |||
|---|---|---|---|
| VCC | 3V3 | Catu daya | WAJIB 3,3 V — bukan 5V/VIN |
| GND | GND | Ground | ground bersama |
| NSS / CS | GPIO 5 | VSPI SS | chip select, aktif LOW |
| MOSI | GPIO 23 | VSPI MOSI | data keluar SPI |
| MISO | GPIO 19 | VSPI MISO | data masuk SPI |
| SCK / CLK | GPIO 18 | VSPI SCK | clock SPI |
| RST | GPIO 14 | Reset modul | — |
| DIO0 | GPIO 26 | Interupsi | indikator RX/TX done |
| — | GPIO 2 | LED status | LED biru bawaan board |
| TBL. 04 — Profil Board (satu #define) | |||||||
|---|---|---|---|---|---|---|---|
| Profil | SCK | MISO | MOSI | SS | RST | DIO0 | LED |
| DevKit V1 + Ra-02 ★ | 18 | 19 | 23 | 5 | 14 | 26 | 2 |
| TTGO LoRa32 T3 V2.1.6 | 5 | 19 | 27 | 18 | 23 | 26 | 25 |
| Heltec WiFi LoRa 32 V2 | 5 | 19 | 27 | 18 | 14 | 26 | 25 |
Uji coba menyeluruh hanya dengan satu ESP32 tanpa modul LoRa: Bluetooth SPP ke ponsel + Wi-Fi SoftAP (192.168.4.1, SSID ESP32-LoRa-WebChat) dengan Web UI sebagai "pengguna kedua". Seluruh perilaku radio disimulasikan virtual di dalam chip.
- Auto-ACK virtual dengan delay RF ±150 ms
- Ring buffer chat + REST API & event polling
- Partisi Huge APP 3 MB via
partitions.csv
Pasangan firmware dua node (node_a_devkit_ap + node_b_cam_sta) yang menjembatani dua ESP32 lewat Wi-Fi sebagai pengganti sambungan LoRa fisik — untuk pengembangan dan demo saat modul radio belum tersedia.
- Node A berperan sebagai Access Point
- Node B sebagai station + kamera opsional
- Helper bonded-device di
firmware/common/
Aplikasi Android
Clean Architecture + MVVM dengan DI manual (AppContainer), Kotlin Coroutines & StateFlow di seluruh aliran data, dan tema Material 3 kustom identitas sky/cyan "instrument panel" — kontras terukur WCAG; status tidak pernah disampaikan lewat warna saja.
Nama & username wajib saat pertama jalan — identitas untuk presence.
Daftar percakapan, FAB "Chat Baru", strip telemetri jaringan.
Direktori + pencarian, badge E2E, atur passphrase per kontak (tekan lama).
Gelembung pesan, status kirim, pemisah hari, gembok enkripsi, kartu lokasi & radar, tombol SOS.
Pindai, pasangkan, dan sambungkan gateway — kartu status per keadaan.
Profil, anggaran payload LoRa (160–240 B), timeout ACK, mode debug.
Log frame mentah TX/RX secara langsung untuk riset protokol.
| TBL. 05 — Matriks Teknologi | ||
|---|---|---|
| Lapisan | Teknologi | Peran |
| Bahasa | Kotlin 2.2.10 | seluruh aplikasi · coroutines + StateFlow 1.10.2 |
| UI | Jetpack Compose · Material 3 | UI deklaratif bergaya iOS · BOM 2024.09.00 |
| Arsitektur | Clean Architecture + MVVM | domain murni · DI manual tanpa framework |
| Persistensi | Room 2.7.0 + DataStore 1.1.7 | riwayat offline & preferensi |
| Transport | Bluetooth Classic RFCOMM/SPP | latensi rendah ke ESP32 · framing newline |
| Kripto | AES-256-GCM + PBKDF2 (JCA) | E2E tanpa dependensi baru |
| Mikrokontroler | ESP32-WROOM-32 dual core 240 MHz | bridge FreeRTOS |
| Radio | Semtech SX1278/SX1276 | modulasi CSS jarak jauh |
| Build | Gradle 9.3.1 · AGP 9.1.1 · PlatformIO | otomasi app + firmware |
| Tes | JUnit4 · Robolectric 1.59 · Roborazzi | 325 tes + verifikasi screenshot baseline |
Kualitas & Pengujian
Unit test berjalan di JVM dengan Robolectric — tanpa emulator. Screenshot test memakai Roborazzi dengan roborazzi.test.verify: ./gradlew testDebugUnitTest memverifikasi gambar terhadap baseline dan gagal bila berbeda, bukan diam-diam merekam ulang.
| TBL. 06 — Suite Tes Utama | ||
|---|---|---|
| Suite | Cakupan | Yang dijaga |
| EncryptionTest · BugHuntCryptoProtocol | primitif kripto & kontrak kabel | kedua ujung menurunkan kunci sama · nonce selalu baru · passphrase salah / ciphertext diubah / AAD tak cocok semuanya ditolak |
| EncryptionIntegrationTest | dua repository penuh (Alice & Bob) | enkripsi lewat jalur kirim/terima sungguhan termasuk fragmentasi; retry memakai ciphertext asli, bukan seal ulang |
| ProtocolTest · FrameWriterTest | framing & serialisasi | amplop terukur 136–142 byte · dedup LRU 500 · sanitasi timestamp |
| PresenceTruthTest | kebenaran status online | liveness dari contacts.lastSeen — peer diam tapi online tidak boleh "offline" |
| PostReviewFixTest | regresi 4 cacat review | hapus pesan menghentikan retransmisi · fail-closed passphrase · migrasi v1 menjaga data · flag security di-reset benar |
| SosAlertManagerTest · SosPayloadTest | siaran darurat | format sos_v1 · interval 15 dtk · transisi ACTIVE→VERIFIED→STOPPED |
| TacticalRadar*Test · LocationCard*Test | radar & kartu lokasi | proyeksi bearing · cincin skala · jarak Haversine · label mata angin |
| LocationMigrationTest | skema Room v2→v3 | pesan lama terbaca sebagai TEXT tanpa konversi data |
Errata
Dokumentasi internal proyek ini ditulis dari pembacaan langsung kode sumber dan memisahkan yang terverifikasi dari yang belum. Berikut temuan materialnya — disajikan sebagai errata, bukan disimpan diam-diam.
BLOKIR
Firmware memakai 4 API BluetoothSerial dari Arduino-ESP32 core 2.x, sedangkan PlatformIO kini menarik core 3.x. Jalan keluar: kunci framework-arduinoespressif32@~2.0.17, atau migrasi ke API GAP (esp_bt_gap_*). Aplikasi Android tidak terpengaruh.
KLARIFIKASI
Firmware tidak meneruskan paket LoRa-ke-LoRa — tidak ada multi-hop atau routing. Label "mesh" pada metadata awal tidak didukung implementasi dan sudah dikoreksi.
KEAMANAN
Siapa pun yang tahu sync word bisa memancarkan presence palsu atau ack palsu. Direkomendasikan: menandatangani kedua jenis paket itu, atau memperluas skema enkripsi mencakupnya.
KRIPTO
Kunci statis per pasangan: passphrase bocor membuka rekaman lama. Dedup messageId bersifat per-proses. Passphrase tersimpan apa adanya di database lokal — perangkat yang di-root bisa membacanya.
EFISIENSI
Base64 membesarkan isi ±49%: pesan 150 karakter menjadi 5 fragmen, dan kehilangan satu fragmen menggagalkan seluruh pesan. Praktiknya: pesan singkat saat enkripsi aktif.
RANCANG
Spesifikasi jittered exponential backoff (Android) + listen-before-talk CAD (ESP32) ada di docs/superpowers/ namun belum masuk kode — tabrakan paket masih mungkin bila dua node memancar bersamaan.
LEGAL
README menautkan badge Apache-2.0 tetapi filenya tidak ada — secara hukum proyek belum berlisensi eksplisit. Sisanya: beberapa dependensi (moshi, plugin gemini) tersisa tak terpakai dari scaffolding awal.
VERIFIKASI
Jangkauan radio nyata (klaim umum LoRa, bukan pengukuran proyek), board TTGO/Heltec, perilaku Android 12–16 (uji fisik: Android 11), dan enkripsi antar dua perangkat fisik — semua tes E2E berjalan di satu JVM.
Prosedur Awal
Butuh: ESP32 DevKit V1 + modul Ra-02, Android Studio (JDK 17/21), PlatformIO, dan dua smartphone untuk uji penuh.
Buka firmware/esp32_lora_gateway/ di PlatformIO. Default sudah menarget DevKit V1 + Ra-02; board TTGO/Heltec tersedia sebagai environment terpisah.
Buka repo di Android Studio, sambungkan HP via USB debugging, lalu jalankan tes dan build. APK release butuh keystore via KEYSTORE_PATH.
Pengaturan → Bluetooth → pair ESP32-LoRa-Gateway (Just Works, PIN lama: 1234). Di app: tab Bluetooth → Connect → LED menyala stabil → obrolan siap mengudara.