# 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
```python
# 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](https://github.com/adafruit/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](https://www.raviyp.com/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](https://www.waveshare.com/wiki/SIM800C_GSM/GPRS_HAT) - WaveShare, who makes the module that I have has a pretty decent documentation page.
* [usim800 python library](https://github.com/Bhagyarsh/usim800/tree/master/usim800) - 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](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html) - This is probably the single most important resource for understanding how MQTT actually works
* [mqtt-codec python library](https://github.com/kcallin/mqtt-codec) - 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/lioreshai/cellmqtt",
"name": "cellmqtt",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "MQTT,iot,cellular,gsm,gprs,sim800c",
"author": "Liore Shai",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/e3/c0/3651c14095a8f98b7251e25f02cc251e57b845c629b9700b5892b3822254/cellmqtt-0.1.0.tar.gz",
"platform": null,
"description": "# CellMQTT\n\nLightweight IoT MQTT library for mobile network chips (so far just SIM800c)\n\n## Overview\n\nThis 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.\n\nI 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.\n\n## Getting Started\n\n```python\n# Schedule library is required to run event-based commands while the forever-loop is running\nimport schedule\nimport logging\n\nfrom datetime import datetime\nfrom cellmqtt import CellMQTT, WirelessChip\n\n# Initialize a CellMQTT instance with your wireless chip and desired log level\n# > Values can be overridden here, but it is cleaner to configure them from \n# > a config.ini in your project directory\ncmqtt = CellMQTT(cell_chip=WirelessChip.SIM800C, log_level = logging.DEBUG)\n\n# You can also override MQTT connection parameters:\n# > cmqtt.connect(host='test.com', port=1883)\n# > or, just use none and they will be pulled from config.ini:\ncmqtt.connect()\n\ndef handle_test(topic: str, message: bytes):\n print('------ GOT MSG FROM TOPIC: ' + topic + '! ------')\n print(str(message, 'utf-8'))\n print('------ END OF MESSAGE ------')\n\ncmqtt.subscribe('ext/test', handle_test)\n\ndef publish_demo():\n cmqtt.publish('ext/test/date', str(datetime.utcnow()))\n\nschedule.every(40).seconds.do(publish_demo)\n\ncmqtt.loop()\n```\n\n### Configuration\n\nThere 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.\n\n## Acknowledgements\n\nThere 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:\n\n* [Adafruit CircuitPython_MiniMQTT](https://github.com/adafruit/Adafruit_CircuitPython_MiniMQTT/)\n This client library from Adafruit was really helpful to get an understanding of how MQTT clients work on a lower level.\n\n* [MQTT Protocol tutorial using SIM900/SIM800 modules \u2013 MQTT over TCP](https://www.raviyp.com/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.\n\n* [WaveShare Wiki - SIM800C GSM/GPRS HAT](https://www.waveshare.com/wiki/SIM800C_GSM/GPRS_HAT) - WaveShare, who makes the module that I have has a pretty decent documentation page.\n\n* [usim800 python library](https://github.com/Bhagyarsh/usim800/tree/master/usim800) - 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\n\n* [MQTT Version 3.1.1 protocol docs](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html) - This is probably the single most important resource for understanding how MQTT actually works\n\n* [mqtt-codec python library](https://github.com/kcallin/mqtt-codec) - 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.\n",
"bugtrack_url": null,
"license": "",
"summary": "Lightweight IoT MQTT library for mobile network chips.",
"version": "0.1.0",
"split_keywords": [
"mqtt",
"iot",
"cellular",
"gsm",
"gprs",
"sim800c"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f9a3bed4fc7799cc97fb413cafefca8210f576578918aee199d7b3ac081d0e3c",
"md5": "d03203e9b2baf944d61d3cb7fd01a3b9",
"sha256": "68d829cc4f69b509f726e5a53464ee347af87e0124f2ee2cf0f18e6b5e43c427"
},
"downloads": -1,
"filename": "cellmqtt-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d03203e9b2baf944d61d3cb7fd01a3b9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 8054,
"upload_time": "2023-02-02T04:06:42",
"upload_time_iso_8601": "2023-02-02T04:06:42.767319Z",
"url": "https://files.pythonhosted.org/packages/f9/a3/bed4fc7799cc97fb413cafefca8210f576578918aee199d7b3ac081d0e3c/cellmqtt-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e3c03651c14095a8f98b7251e25f02cc251e57b845c629b9700b5892b3822254",
"md5": "2fb33b82fac210961f857fbaeaf3ec2b",
"sha256": "b6c0c050142faaf60fb61697384ad159895e5615180f9fc9a576fa709e7035bd"
},
"downloads": -1,
"filename": "cellmqtt-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "2fb33b82fac210961f857fbaeaf3ec2b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 9947,
"upload_time": "2023-02-02T04:06:44",
"upload_time_iso_8601": "2023-02-02T04:06:44.780357Z",
"url": "https://files.pythonhosted.org/packages/e3/c0/3651c14095a8f98b7251e25f02cc251e57b845c629b9700b5892b3822254/cellmqtt-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-02 04:06:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "lioreshai",
"github_project": "cellmqtt",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "cellmqtt"
}
JSON
