TaraTXT ESP32 SMS Gateway Device-it-yourself

A modular ESP32-based SMS gateway that bridges SMS messages with MQTT communication using a SIM800L GSM module.

📁 Project Structure

taratxt/
├── taratxt.ino          # Main Arduino sketch
├── config.example.h     # Example configuration file
├── wifi_handler.h       # Wi-Fi connection management
├── gsm_handler.h        # GSM/SIM800L module management
├── mqtt_handler.h       # MQTT communication handling
├── sms_handler.h        # SMS processing and parsing
├── README.md            # This documentation
└── .gitignore           # Git ignore rules

🏗️ Modular Architecture

config.h

• Purpose: Central configuration file
• Contains:
  • WiFi credentials
  • MQTT server settings
  • Device identification
  • Pin definitions
  • Timing constants
  • Debug mode flag

wifi_handler.h

• Purpose: Wi-Fi connection management
• Functions:
  • connectToWiFi() - Initial Wi-Fi connection
  • ensureWiFiConnected() - Reconnection handling

gsm_handler.h

• Purpose: GSM/SIM800L module management
• Functions:
  • initializeGSM() - Hardware initialization
  • waitForNetworkRegistration() - Network registration with retry
  • setupSMSMode() - Configure SMS text mode and storage

mqtt_handler.h

• Purpose: MQTT communication
• Functions:
  • connectToMQTT() - MQTT broker connection
  • mqttCallback() - Handle incoming MQTT messages
  • publishHeartbeat() - Send device status updates
  • publishStatus() - Publish SMS delivery status

sms_handler.h

• Purpose: SMS processing and management
• Functions:
  • checkUnreadSMS() - Query unread SMS messages
  • parseSMSResponse() - Parse AT command responses
  • publishSMStoMQTT() - Forward SMS to MQTT
  • deleteSMS() - Remove processed SMS
  • escapeJsonString() - JSON string sanitization

🔧 Hardware Configuration

ESP32 Pins:
- MODEM_RST: GPIO 5
- MODEM_PWKEY: GPIO 4
- MODEM_POWER_ON: GPIO 23
- MODEM_TX: GPIO 27
- MODEM_RX: GPIO 26

📡 MQTT Topics

Direction	Topic Pattern	Purpose
Subscribe	outbound/[deviceKey]	Receive SMS send commands
Publish	inbound/[deviceKey]	Forward received SMS
Publish	status/[deviceKey]	Device status and delivery reports

📋 Message Formats

Outbound SMS Command

{
  "id": "msg123",
  "number": "+1234567890",
  "content": "Hello World!"
}

Inbound SMS Notification

{
  "type": "inbound",
  "from": "+9876543210",
  "content": "Reply message",
  "timestamp": "25/07/30,10:30:45+00",
  "device": "TX67edf688995dc"
}

Status Updates

{
  "id": "msg123",
  "status": "sent"
}

🚀 Benefits of Modular Structure

✅ Maintainability

• Each module handles specific functionality
• Easy to locate and fix issues
• Clear separation of concerns

✅ Reusability

• Modules can be reused in other projects
• Easy to swap implementations

✅ Testability

• Individual modules can be tested separately
• Easier debugging and development

✅ Scalability

• Easy to add new features
• Simple to extend functionality

✅ Readability

• Clean, organized code structure
• Self-documenting module names
• Reduced complexity in main file

🔧 Required Libraries

Install these libraries in Arduino IDE:

• WiFi (ESP32 Core)
• PubSubClient by Nick O'Leary
• ArduinoJson by Benoit Blanchon
• TinyGSM by Volodymyr Shymanskyy

⚙️ Configuration

1. Copy config.example.h and rename it to config.h.

2. Update config.h with your:

   • Wi-Fi credentials
   • MQTT server details
   • Device key and secret
   • Set debugMode = false for production

3. Verify pin connections match your hardware setup

4. Upload to ESP32 and monitor serial output (if debug enabled)

🔍 Troubleshooting

• Network Issues: Check Wi-Fi credentials and GSM antenna
• MQTT Problems: Verify broker address and authentication
• SMS Issues: Ensure SIM card is inserted and has credit
• Debug Output: Enable debugMode = true for detailed logging

---

Note: The include errors shown in the IDE are normal for the development environment and won't affect compilation when all required libraries are properly installed.