cellmqtt 0.0.6

Lightweight IoT MQTT library for mobile network chips.

CellMQTT

Lightweight IoT MQTT library for mobile network chips (so far just SIM800c)

Overview

This MQTT client library was born out of the seeming lack of documentation/support for the SIM800c GPRS chip. As of this writing, it is now January 2023 and GSM/GPRS is mostly phased out, and the SIM800c chip has been left in the dust - but it is still cheap and widely available, so hopefully this helps someone else get started.

I also tried to make the API as chip-agnostic as possible, so while there is only one implementation now, for the SIM800c, please feel free to roll your own for another chip and make a PR.

Getting Started

# Schedule library is required to run event-based commands while the forever-loop is running
import schedule
import logging

from datetime import datetime
from cellmqtt import CellMQTT, WirelessChip

# Initialize a CellMQTT instance with your wireless chip and desired log level
#  > Values can be overridden here, but it is cleaner to configure them from 
#  > a config.ini in your project directory
cmqtt = CellMQTT(cell_chip=WirelessChip.SIM800C, log_level = logging.DEBUG)

# You can also override MQTT connection parameters:
# > cmqtt.connect(host='test.com', port=1883)
# > or, just use none and they will be pulled from config.ini:
cmqtt.connect()

def handle_test(topic: str, message: bytes):
    print('------ GOT MSG FROM TOPIC: ' + topic + '! ------')
    print(str(message, 'utf-8'))
    print('------ END OF MESSAGE ------')

cmqtt.subscribe('ext/test', handle_test)

def publish_demo():
    cmqtt.publish('ext/test/date', str(datetime.utcnow()))

schedule.every(40).seconds.do(publish_demo)

cmqtt.loop()

Configuration

There is a config-sample.ini file which should be renamed to config.ini. These values can also be overridden when initializing the CellMQTT class in your program.

Acknowledgements

There were a lot of great resources that helped me understand the workings of GSM/GPRS chips, serial connections, MQTT protocols, and more. Some are more relevant, some less, but all of the following were extremely helpful to me:

• Adafruit CircuitPython_MiniMQTT This client library from Adafruit was really helpful to get an understanding of how MQTT clients work on a lower level.

• MQTT Protocol tutorial using SIM900/SIM800 modules – MQTT over TCP - This blog post and associated YouTube video from Ravi Pujar was what gave me the initial boost of confidence that I could actually get this done with the SIM800c module I had on hand. He does explain the underlying concepts, but there is definitely not much to copy/paste and get going here.

• WaveShare Wiki - SIM800C GSM/GPRS HAT - WaveShare, who makes the module that I have has a pretty decent documentation page.

• usim800 python library - This library was what I was initially going to use to simply make HTTP requests - but it turned out to not really meet my needs - playing around with @Bhagyarsh library helped me gain a lot of understanding of the underlying AT commands for the SIM800c

• MQTT Version 3.1.1 protocol docs - This is probably the single most important resource for understanding how MQTT actually works

• mqtt-codec python library - Last, but absolutely not least, is the mqtt-codec library. Until I found this it was an absolute uphill battle for me to get MQTT packets correctly formed.