m2m-python/README.md

m2m-python

Python library for controlling IoT modules (Quectel BG96, BG95, BC66, HiSilicon, etc.).

Features

• Robust AT Command Parser: Handles URCs, multi-line responses, and timeouts gracefully.
• Interactive Shell: A powerful CLI for manual control, diagnostics, and testing.
• Multiple Connectivity Options: Supports Serial ports (/dev/ttyUSB0), TCP sockets (socket://), and RFC2217.
• Vendor Agnostic Core: Abstract base class with specialized implementations for Quectel and HiSilicon.
• Advanced Diagnostics: Signal quality, cell info, SIM forensics, and network scanning.
• Network Services: Integrated Ping, DNS, HTTP(S), and Socket (UDP/TCP) support.

Installation

pip install .

Quick Start: Interactive Shell

The easiest way to get started is using the built-in interactive shell:

# Connect to a physical serial port
m2m-shell /dev/ttyUSB0 --type BG96

# Connect to a remote modem via TCP (e.g., using socat)
m2m-shell socket://192.168.1.50:3000 --type BG95

Available Commands

• info: Display module IMEI, IMSI, Firmware, and configuration.
• status: Check registration, signal quality, and current operator.
• nw_info: Show detailed network and serving cell info.
• cells: Show serving and neighbor cell information.
• forensics: Run a deep SIM card analysis.
• scan: Search for available network operators.
• connect [apn]: Establish a PDP context.
• disconnect: Deactivate PDP context.
• operator <mccmnc> [act]: Select operator manually.
• ping <host> [num]: Ping a remote host.
• dns <host>: Resolve a hostname.
• http_get <url>: Perform an HTTP GET request.
• udp_send <host> <port> <data>: Send a UDP packet.
• udp_listen <port>: Open a local UDP listener.
• tcp_client <host> <port>: Connect to a TCP server.
• sockets: List active sockets and their states.
• close <id>: Close a socket by ID.
• recv <id> [len]: Read data from a socket.
• sms_send <num> <msg>: Send an SMS message.
• sms_list [ALL|REC UNREAD]: List SMS messages.
• radio <on|off>: Toggle module radio.
• reboot: Reboot the module.
• mode <gsm|emtc|nb|all>: Set connectivity preference.
• psm <status|on|off|opt>: Control Power Saving Mode.
• edrx <mode> <act> <bits>: Configure eDRX settings.
• bands [gsm|catm|nb]: Show or lock frequency bands.
• gpio set <pin> <val>: Control GPIO pins.
• at <command>: Send raw AT command to the module.
• clock [show|sync]: Display or sync system clock via NTP.
• temp: Read module internal temperature.
• ls [pattern]: List files on the module filesystem.
• help: Show all available commands with descriptions.

Programmatic Usage

from m2m.nbiot import factory

# Initialize module
module = factory("BG95", "/dev/ttyUSB0")

with module:
    # Check signal
    rssi, ber = module.get_signal_quality()
    print(f"Signal Strength: {rssi}")

    # Connect to network
    if module.connect_network("iot.telefonica.de"):
        print("Connected!")
        
        # Perform DNS lookup
        ips = module.dns_query("google.com")
        print(f"Google IP: {ips[0]}")

Development

Install dev dependencies:

pip install -e .[dev]

Run tests:

pytest tests/