Project Overview: What Is This?

🎯 The Purpose (In Simple Terms)

This project is a tutorial and toolkit for people who bought a SIM7600G-H 4G modem and want to:

Receive SMS messages on their computer
Learn how GSM/LTE modems work
Build SMS-based projects (notifications, IoT, automation)

Think of it as a bridge between your computer and your modem that makes working with SMS super easy.

🤔 The Problem It Solves

Without This Project:

You buy a SIM7600G-H modem
You plug it in via USB
You have NO idea how to use it!
You need to:
- Figure out which COM port it's on
- Learn AT commands (cryptic modem language)
- Write serial communication code
- Parse incoming SMS format
- Handle errors and edge cases

With This Project:

python -m sim7600 sms receive

Done! It automatically:

Finds your modem
Connects to it
Receives and logs SMS messages
Shows them on screen in real-time

🏗️ What It Does (Technically)

Core Functionality:

Auto-Detection
- Scans all USB COM ports
- Identifies the SIM7600G-H modem
- Connects to the correct "AT PORT"
SMS Receiving
- Sends AT commands to modem (AT+CMGF=1, AT+CNMI=2,2,0,0,0)
- Switches modem to "push mode" (SMS come automatically)
- Listens for incoming +CMT: messages
- Parses sender, timestamp, and message text
Logging
- Saves to text file: logs/sms.log
- Optionally saves to JSON: logs/sms.jsonl
- Shows on screen in real-time
- Rotating log files (doesn't fill your disk)

📚 The Architecture (How It Works)

The Flow:

[Phone] --SMS--> [Cell Tower] --SMS--> [SIM Card in Modem]
                                              |
                                              v
                                    [SIM7600G-H Modem]
                                              |
                                    USB Connection
                                              |
                                              v
                                    [Your Computer]
                                              |
                                    Serial Port (COM10)
                                              |
                                              v
                                    [This Python Program]
                                              |
                  +---------------------------+---------------------------+
                  |                           |                           |
                  v                           v                           v
            Console Output              logs/sms.log              logs/sms.jsonl
         (shows on screen)             (text file)              (JSON format)

The Code Components:

sim7600/
├── modem.py           # Talks to the hardware
│   ├── find_sim7600_port()    → Finds modem automatically
│   ├── Modem class            → Opens serial connection
│   ├── write_cmd()            → Sends AT commands
│   └── readline()             → Reads responses
│
├── cli.py             # Main program
│   ├── Parse arguments        → --port, --logfile, etc.
│   ├── Connect to modem       → Uses modem.py
│   ├── Initialize modem       → Send setup AT commands
│   └── Listen forever         → Wait for SMS messages
│
├── parser.py          # Understands SMS format
│   └── parse_cmt_header()     → Extracts phone number, timestamp
│
└── logger_config.py   # Sets up logging
    └── setup_logging()        → Creates rotating log files

🔑 Key Concepts You Should Know

1. Serial Communication

Your modem appears as a "COM port" (COM10, COM8, etc.)
Python uses pyserial library to talk to it
It's like a very basic text chat with the modem

2. AT Commands

Language that modems understand
Examples:
- AT → "Are you there?" (modem replies "OK")
- AT+CMGF=1 → "Use text mode for SMS"
- AT+CNMI=2,2,0,0,0 → "Push SMS to me immediately"

3. +CMT Format

When an SMS arrives, modem sends:

+CMT: "+1234567890","","25/10/18,14:30:00+00"
Hello, this is the message text!

Your program parses this into:

{
    "sender": "+1234567890",
    "timestamp": "25/10/18,14:30:00+00",
    "text": "Hello, this is the message text!"
}

4. The SIM7600 Creates Multiple Ports

When you plug it in, Windows creates 5 COM ports:

COM8: NMEA (GPS data)
COM10: AT PORT ← This is what we need!
COM11: Audio
COM12: Diagnostics
COM9: Modem

Your program automatically picks the right one.

🎓 Why This Is a "Tutorial" Project

Educational Value
- Teaches you how modems work
- Shows real-world serial communication
- Demonstrates AT command usage
- Good example of Python project structure
Starting Point
- You can build on this
- Add sending SMS
- Create notification systems
- Build IoT projects
Beginner-Friendly
- Well-documented
- Step-by-step guide
- Auto-detection (no manual config)
- Clear error messages

💼 Real-World Use Cases

People could use this to:

IoT Projects
- Receive alerts from remote sensors
- Control devices via SMS commands
- Monitor farm equipment, weather stations
Notifications
- Get 2FA codes on your computer
- Backup important SMS to files
- Archive business messages
Development/Testing
- Test SMS features in your app
- Debug SMS gateway issues
- Log message patterns
Learning
- Understand cellular communication
- Learn Python serial programming
- Experiment with AT commands

🔍 What Makes This Project Well-Designed

Auto-Detection
- No manual port configuration needed
- Works on any Windows computer
- Handles multiple SIM7600 ports correctly
Clean Architecture
- Separated concerns (modem, parser, CLI, logging)
- Each file has one job
- Easy to extend
Error Handling
- Graceful failures
- Clear error messages
- Doesn't crash on bad input
Documentation
- README for users
- DEVELOPMENT.md for developers
- Code comments explain "why"
Flexibility
- Command-line flags for options
- Environment variables (.env file)
- Multiple output formats (console, log, JSON)

🚀 What Could Be Added (Future Features)

The architecture supports adding:

Sending SMS (main missing feature)
```
modem.send_sms("+1234567890", "Hello!")
```
Web Dashboard
- View messages in browser
- See statistics
- Search through messages
REST API
- Programmatic access
- Integration with other apps
Auto-Reply Bot
- Keyword-based responses
- Simple chatbot
Forwarding
- Send to email
- Post to webhook
- Telegram notifications

🎯 Summary: What Is This Project?

In one sentence:

A beginner-friendly Python toolkit that automatically connects to your SIM7600G-H modem and receives/logs SMS messages.

The value proposition:

For beginners: Learn how cellular modems work
For developers: Ready-to-use SMS receiving functionality
For tinkerers: Foundation for SMS-based projects
For learning: Well-structured example of Python serial programming

What makes it special:

Auto-detection (no manual configuration)
Tutorial-focused (educational value)
Production-ready code (not just a quick hack)
Extensible (easy to add features)

🤷 Common Questions

"Why would I need this?"

If you have a SIM7600 modem and want to do anything with SMS on your computer, this is your starting point.

"Is this just for learning?"

No! While it's great for learning, the code is production-ready. You could use it to:

Monitor SMS for your business
Build IoT notification systems
Create SMS-based automation

"Why not use Twilio/cloud SMS services?"

This is free (after buying the modem)
No internet needed (just cellular signal)
Privacy (messages stay on your computer)
Control (you own the hardware)
Learning (understand how it works)

"What's the difference between this and SMS gateway software?"

This is:

Open source (you can see and modify the code)
Python-based (easy to extend)
Educational (teaches you how it works)
Free (no licensing fees)
Customizable (add any features you want)

🎓 Key Takeaway

This project is a bridge between hardware and software. It takes something complex (cellular modem communication) and makes it simple (one Python command). The architecture is clean enough to learn from, yet powerful enough to build real projects on.

It's both a tutorial (teaching you how modems work) and a toolkit (giving you reusable code) for SMS projects.

FilesExpand file tree

PROJECT_OVERVIEW.md

Latest commit

History