EdgeX SMS Forwarder Service

A FastAPI microservice that integrates with EdgeX Foundry to forward notifications as SMS messages via Twilio. This service acts as a bridge between EdgeX's notification system and SMS delivery.

Features

• ✅ Receives EdgeX notifications via REST webhooks
• ✅ Supports both JSON and plain text payload formats
• ✅ Automatically adds Indian country code (+91) when needed
• ✅ Integrates with Twilio for SMS delivery
• ✅ Health check endpoints for monitoring
• ✅ Docker containerized for easy deployment
• ✅ Comprehensive logging for debugging

Architecture

EdgeX Foundry → Subscription Service → FastAPI SMS Forwarder → Twilio API → SMS Delivery

Prerequisites

• Python 3.10+
• Docker and Docker Compose
• Twilio account with SMS capabilities
• EdgeX Foundry (Napa release or later)

Installation

1. Clone the Repository

git clone <your-repo-url>
cd edgex-sms-forwarder

2. Environment Variables

Create a .env file:

TWILIO_SID=your_twilio_account_sid
TWILIO_TOKEN=your_twilio_auth_token
TWILIO_PHONE=your_twilio_phone_number  # Format: +1234567890

3. Build Docker Image

docker build -t edgex-sms-forwarder:1.0.0 .

Configuration

EdgeX Subscription Setup

Create a subscription in EdgeX to forward notifications:

curl -X POST http://<edgex-host>:59860/api/v3/subscription \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "sms-alerts",
    "channels": [{
      "type": "REST",
      "host": "edgex-sms-forwarder",
      "port": 9876,
      "path": "/send-sms/7358886350",  # Phone number in path
      "httpMethod": "POST"
    }],
    "categories": ["ALERT", "SECURITY"],
    "severities": ["CRITICAL"],
    "resendLimit": 3
  }'

Docker Compose Integration

Add to your docker-compose.yml:

sms-forwarder:
    image: edgex-sms-forwarder:1.1.3
    container_name: edgex-sms-forwarder
    ports:
      - "9876:9876"
    environment:
      - TWILIO_SID=
      - TWILIO_TOKEN=
      - TWILIO_PHONE=
    networks:
      magistrala-base-net: null
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9876/health"]
      interval: 30s
      timeout: 10s
      retries: 3

API Endpoints

Send SMS

POST /send-sms/{phone_number}

Parameters:

• phone_number: Phone number (with or without +91 country code)
• body: Notification content (JSON or plain text)

Supported JSON Formats:

// Simple format
{"content": "Alert message", "severity": "CRITICAL"}

// EdgeX format
[{"apiVersion": "v3", "notification": {"content": "Alert", "severity": "CRITICAL"}}]

// Plain text
"Smoke alert: 200% exceeds threshold"

Health Check

GET /health

Returns service status and Twilio configuration status.

Root

GET /

Service information endpoint.

Usage Examples

Test with curl

# Plain text
curl -X POST http://localhost:9876/send-sms/7358556350 \
  -H "Content-Type: text/plain" \
  -d "Server temperature critical: 95°C"

# JSON
curl -X POST http://localhost:9876/send-sms/7358556350 \
  -H "Content-Type: application/json" \
  -d '{"content": "Network outage detected", "severity": "CRITICAL"}'

Phone Number Formats

• 788856350 → automatically converted to +91788856350
• +91788856350 → used as-is
• 91788856350 → converted to +91788856350

Troubleshooting

Common Issues

1. 422 Unprocessable Entity: Check if EdgeX is sending proper JSON format
2. SMS not delivered: Verify Twilio credentials and phone number format
3. Connection refused: Ensure the service is running on port 9876

Logs

docker logs edgex-sms-forwarder

Health Check

curl http://localhost:9876/health

Development

Local Development

python -m venv venv
source venv/bin/activate
pip install -r app/requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 9876 --reload

Testing

# Test with sample payloads
python test_sms.py

Security Notes

• 🔒 Never commit Twilio credentials to version control
• 🔒 Use EdgeX secret store for production credentials
• 🔒 Validate phone numbers to prevent SMS abuse
• 🔒 Consider adding authentication for the API endpoints

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

1. Check the logs: docker logs edgex-sms-forwarder
2. Verify Twilio account status
3. Ensure EdgeX subscription is properly configured
4. Check network connectivity between containers

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Submit a pull request

---

Note: This service is designed for EdgeX Foundry Napa release and may require adjustments for other versions.