# Python Sparkplug B Wrapper
This python module implements an easy way to create Sparkplug B entities on Python, abstracting one level up the already existing python Eclipse Tahu Sparkplug B v1.0 core modules.
The *mqtt-spb-wrapper* python module provides the following high level objects to handle generic Sparkplug B entities in an easy way:
- **MqttSpbEntityEdgeNode** - End of Network (EoN) entity
- This entity can publish NDATA, NBIRTH, NDEATH messages and subscribe to its own commands NCMD as well as to the STATUS messages from the SCADA application.
- **MqttSpbEntityDevice** - End of Network Device (EoND) entity
- This entity that can publish DDATA, DBIRTH, DDEATH messages and subscribe to its own commands DCMD as well as to the STATUS messages from the SCADA application.
- **MqttSpbEntityApplication** - Application entity
- This entity can publish NDATA, NBIRTH, NDEATH messages and subscribe to its own commands NCMD, to the STATUS messages from the SCADA application as well as to all other messages from the Sparkplug B Domain ID.
- **MqttSpbEntityScada** - SCADA entity
- This entity can publish NDATA, NBIRTH, NDEATH messages as well as to send commands to all EoN and EoND (NCMD, DCMD), and subscribe to all other messages from the Sparkplug B Domain ID.
Other helper classes:
- **MqttSpbPayload**
- Class to decode the Sparkplug B binary payloads ( Google protobuf format )
- **MqttSpbTopic**
- Class to parse, decode and handle MQTT Sparkplug B topics.
## Examples
The repository includes a folder with some basic examples for the different type of entities, **see the folder /examples** in this repository for more examples.
### Basic EoN Device
The following code shows how to create an EoND entity that transmit some simple data.
```python
import time
from mqtt_spb_wrapper import *
_DEBUG = True # Enable debug messages
print("--- Sparkplug B example - End of Node Device - Simple")
def callback_command(payload):
print("DEVICE received CMD: %s" % (payload))
def callback_message(topic, payload):
print("Received MESSAGE: %s - %s" % (topic, payload))
# Create the spB entity object
group_name = "Group-001"
edge_node_name = "Gateway-001"
device_name = "SimpleEoND-01"
device = MqttSpbEntityDevice(group_name, edge_node_name, device_name, _DEBUG)
device.on_message = callback_message # Received messages
device.on_command = callback_command # Callback for received commands
# Set the device Attributes, Data and Commands that will be sent on the DBIRTH message --------------------------
# Attributes
device.attributes.set_value("description", "Simple EoN Device node")
device.attributes.set_value("type", "Simulated-EoND-device")
device.attributes.set_value("version", "0.01")
# Data / Telemetry
device.data.set_value("value", 0)
# Commands
device.commands.set_value("rebirth", False)
# Connect to the broker --------------------------------------------
_connected = False
while not _connected:
print("Trying to connect to broker...")
_connected = device.connect("localhost8", 1883)
if not _connected:
print(" Error, could not connect. Trying again in a few seconds ...")
time.sleep(3)
# Send birth message
device.publish_birth()
# Send some telemetry values ---------------------------------------
value = 0 # Simple counter
for i in range(5):
# Update the data value
device.data.set_value("value", value)
# Send data values
print("Sending data - value : %d" % value)
device.publish_data()
# Increase counter
value += 1
# Sleep some time
time.sleep(5)
# Disconnect device -------------------------------------------------
# After disconnection the MQTT broker will send the entity DEATH message.
print("Disconnecting device")
device.disconnect()
print("Application finished !")
```
### Basic Listener Application
The following code shows how to create an application entity to listen to all Sparkplug B messages on a given group.
```python
import time
from mqtt_spb_wrapper import *
_DEBUG = True # Enable debug messages
print("--- Sparkplug B example - Application Entity Listener")
def callback_app_message(topic, payload):
print("APP received MESSAGE: %s - %s" % (topic, payload))
def callback_app_command(payload):
print("APP received CMD: %s" % payload)
domain_name = "Domain-001"
app_entity_name = "ListenApp01"
app = MqttSpbEntityApplication(domain_name, app_entity_name, debug_info=_DEBUG)
# Set callbacks
app.on_message = callback_app_message
app.on_command = callback_app_command
# Set the device Attributes, Data and Commands that will be sent on the DBIRTH message --------------------------
# Attributes
app.attributes.set_value("description", "Test application")
# Commands
app.commands.set_value("rebirth", False)
# Connect to the broker----------------------------------------------------------------
_connected = False
while not _connected:
print("Trying to connect to broker...")
_connected = app.connect("localhost8", 1883)
if not _connected:
print(" Error, could not connect. Trying again in a few seconds ...")
time.sleep(3)
# Send birth message
app.publish_birth()
# Loop forever, messages and commands will be handeled by the callbacks
while True:
time.sleep(1000)
```
## Eclipse Sparkplug B v1.0
Sparkplug is a specification for MQTT enabled devices and applications to send and receive messages in a stateful way. While MQTT is stateful by nature it doesn't ensure that all data on a receiving MQTT application is current or valid. Sparkplug provides a mechanism for ensuring that remote device or application data is current and valid. The main Sparkplug B features include:
- Complex data types using templates
- Datasets
- Richer metrics with the ability to add property metadata for each metric
- Metric alias support to maintain rich metric naming while keeping bandwidth usage to a minimum
- Historical data
- File data
Sparkplug B Specification: [https://www.eclipse.org/tahu/spec/Sparkplug%20Topic%20Namespace%20and%20State%20ManagementV2.2-with%20appendix%20B%20format%20-%20Eclipse.pdf](https://www.eclipse.org/tahu/spec/Sparkplug Topic Namespace and State ManagementV2.2-with appendix B format - Eclipse.pdf)
## Eclipse Tahu spB v1.0 implementation
Eclipse Tahu provide client libraries and reference implementations in various languages and for various devices to show how the device/remote application must connect and disconnect from the MQTT server using the Sparkplug specification explained below. This includes device lifecycle messages such as the required birth and last will & testament messages that must be sent to ensure the device lifecycle state and data integrity.
The *mqtt-spb-wrapper* python module uses the open source Sparkplug core function from Eclipse Tahu repository, located at: https://github.com/eclipse/tahu (The current release used is v0.5.15 ).
For more information visit : https://github.com/eclipse/tahu
Raw data
{
"_id": null,
"home_page": null,
"name": "mqtt-spb-wrapper",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "sparkplug, mqtt, ecliplse, tahu, iiot, iot",
"author": "Javier FG",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/57/75/996fe10bfe337c1890097be6f07cdf8d15a73a5d50108c584d1f21b285f2/mqtt_spb_wrapper-1.0.20.tar.gz",
"platform": null,
"description": "# Python Sparkplug B Wrapper\n\nThis python module implements an easy way to create Sparkplug B entities on Python, abstracting one level up the already existing python Eclipse Tahu Sparkplug B v1.0 core modules.\n\nThe *mqtt-spb-wrapper* python module provides the following high level objects to handle generic Sparkplug B entities in an easy way:\n\n- **MqttSpbEntityEdgeNode** - End of Network (EoN) entity \n - This entity can publish NDATA, NBIRTH, NDEATH messages and subscribe to its own commands NCMD as well as to the STATUS messages from the SCADA application.\n- **MqttSpbEntityDevice** - End of Network Device (EoND) entity \n - This entity that can publish DDATA, DBIRTH, DDEATH messages and subscribe to its own commands DCMD as well as to the STATUS messages from the SCADA application.\n- **MqttSpbEntityApplication** - Application entity \n - This entity can publish NDATA, NBIRTH, NDEATH messages and subscribe to its own commands NCMD, to the STATUS messages from the SCADA application as well as to all other messages from the Sparkplug B Domain ID.\n- **MqttSpbEntityScada** - SCADA entity \n - This entity can publish NDATA, NBIRTH, NDEATH messages as well as to send commands to all EoN and EoND (NCMD, DCMD), and subscribe to all other messages from the Sparkplug B Domain ID.\n\nOther helper classes:\n\n- **MqttSpbPayload**\n - Class to decode the Sparkplug B binary payloads ( Google protobuf format )\n- **MqttSpbTopic** \n - Class to parse, decode and handle MQTT Sparkplug B topics.\n\n## Examples\n\nThe repository includes a folder with some basic examples for the different type of entities, **see the folder /examples** in this repository for more examples.\n\n### Basic EoN Device\n\nThe following code shows how to create an EoND entity that transmit some simple data.\n\n```python\nimport time\nfrom mqtt_spb_wrapper import *\n\n_DEBUG = True # Enable debug messages\n\nprint(\"--- Sparkplug B example - End of Node Device - Simple\")\n\n\ndef callback_command(payload):\n print(\"DEVICE received CMD: %s\" % (payload))\n\n\ndef callback_message(topic, payload):\n print(\"Received MESSAGE: %s - %s\" % (topic, payload))\n\n\n# Create the spB entity object\ngroup_name = \"Group-001\"\nedge_node_name = \"Gateway-001\"\ndevice_name = \"SimpleEoND-01\"\n\ndevice = MqttSpbEntityDevice(group_name, edge_node_name, device_name, _DEBUG)\n\ndevice.on_message = callback_message # Received messages\ndevice.on_command = callback_command # Callback for received commands\n\n# Set the device Attributes, Data and Commands that will be sent on the DBIRTH message --------------------------\n\n# Attributes\ndevice.attributes.set_value(\"description\", \"Simple EoN Device node\")\ndevice.attributes.set_value(\"type\", \"Simulated-EoND-device\")\ndevice.attributes.set_value(\"version\", \"0.01\")\n\n# Data / Telemetry\ndevice.data.set_value(\"value\", 0)\n\n# Commands\ndevice.commands.set_value(\"rebirth\", False)\n\n# Connect to the broker --------------------------------------------\n_connected = False\nwhile not _connected:\n print(\"Trying to connect to broker...\")\n _connected = device.connect(\"localhost8\", 1883)\n if not _connected:\n print(\" Error, could not connect. Trying again in a few seconds ...\")\n time.sleep(3)\n\n# Send birth message\ndevice.publish_birth()\n\n\n# Send some telemetry values ---------------------------------------\nvalue = 0 # Simple counter\nfor i in range(5):\n # Update the data value\n device.data.set_value(\"value\", value)\n\n # Send data values\n print(\"Sending data - value : %d\" % value)\n device.publish_data()\n\n # Increase counter\n value += 1\n\n # Sleep some time\n time.sleep(5)\n\n# Disconnect device -------------------------------------------------\n# After disconnection the MQTT broker will send the entity DEATH message.\nprint(\"Disconnecting device\")\ndevice.disconnect()\n\nprint(\"Application finished !\")\n```\n\n\n\n### Basic Listener Application\n\nThe following code shows how to create an application entity to listen to all Sparkplug B messages on a given group.\n\n```python\nimport time\nfrom mqtt_spb_wrapper import *\n\n_DEBUG = True # Enable debug messages\n\nprint(\"--- Sparkplug B example - Application Entity Listener\")\n\n\ndef callback_app_message(topic, payload):\n print(\"APP received MESSAGE: %s - %s\" % (topic, payload))\n\n\ndef callback_app_command(payload):\n print(\"APP received CMD: %s\" % payload)\n\n\ndomain_name = \"Domain-001\"\napp_entity_name = \"ListenApp01\"\n\napp = MqttSpbEntityApplication(domain_name, app_entity_name, debug_info=_DEBUG)\n\n# Set callbacks\napp.on_message = callback_app_message\napp.on_command = callback_app_command\n\n# Set the device Attributes, Data and Commands that will be sent on the DBIRTH message --------------------------\n\n# Attributes\napp.attributes.set_value(\"description\", \"Test application\")\n\n# Commands\napp.commands.set_value(\"rebirth\", False)\n\n# Connect to the broker----------------------------------------------------------------\n_connected = False\nwhile not _connected:\n print(\"Trying to connect to broker...\")\n _connected = app.connect(\"localhost8\", 1883)\n if not _connected:\n print(\" Error, could not connect. Trying again in a few seconds ...\")\n time.sleep(3)\n\n# Send birth message\napp.publish_birth()\n\n\n# Loop forever, messages and commands will be handeled by the callbacks\nwhile True:\n time.sleep(1000)\n```\n\n\n\n## Eclipse Sparkplug B v1.0\n\nSparkplug is a specification for MQTT enabled devices and applications to send and receive messages in a stateful way. While MQTT is stateful by nature it doesn't ensure that all data on a receiving MQTT application is current or valid. Sparkplug provides a mechanism for ensuring that remote device or application data is current and valid. The main Sparkplug B features include:\n\n- Complex data types using templates\n- Datasets\n- Richer metrics with the ability to add property metadata for each metric\n- Metric alias support to maintain rich metric naming while keeping bandwidth usage to a minimum\n- Historical data\n- File data\n\nSparkplug B Specification: [https://www.eclipse.org/tahu/spec/Sparkplug%20Topic%20Namespace%20and%20State%20ManagementV2.2-with%20appendix%20B%20format%20-%20Eclipse.pdf](https://www.eclipse.org/tahu/spec/Sparkplug Topic Namespace and State ManagementV2.2-with appendix B format - Eclipse.pdf)\n\n\n\n## Eclipse Tahu spB v1.0 implementation\n\nEclipse Tahu provide client libraries and reference implementations in various languages and for various devices to show how the device/remote application must connect and disconnect from the MQTT server using the Sparkplug specification explained below. This includes device lifecycle messages such as the required birth and last will & testament messages that must be sent to ensure the device lifecycle state and data integrity.\n\nThe *mqtt-spb-wrapper* python module uses the open source Sparkplug core function from Eclipse Tahu repository, located at: https://github.com/eclipse/tahu (The current release used is v0.5.15 ).\n\nFor more information visit : https://github.com/eclipse/tahu\n\n",
"bugtrack_url": null,
"license": null,
"summary": "MQTT Sparkplug B v1.0 Wrapper",
"version": "1.0.20",
"project_urls": {
"Homepage": "https://github.com/javier-fg/mqtt-spb-wrapper"
},
"split_keywords": [
"sparkplug",
" mqtt",
" ecliplse",
" tahu",
" iiot",
" iot"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6127f89e4524a4c74f593b5f631c39d3749d3f324d0d6d08ac6b165e2dc6917b",
"md5": "79e71687eef0af538f07b41137c2576c",
"sha256": "66926fbfa8cb3261bb228315cc0cec34a23d37bcedab062fc59d36f757c44bbe"
},
"downloads": -1,
"filename": "mqtt_spb_wrapper-1.0.20-py3-none-any.whl",
"has_sig": false,
"md5_digest": "79e71687eef0af538f07b41137c2576c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 23615,
"upload_time": "2024-04-26T18:54:41",
"upload_time_iso_8601": "2024-04-26T18:54:41.934973Z",
"url": "https://files.pythonhosted.org/packages/61/27/f89e4524a4c74f593b5f631c39d3749d3f324d0d6d08ac6b165e2dc6917b/mqtt_spb_wrapper-1.0.20-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5775996fe10bfe337c1890097be6f07cdf8d15a73a5d50108c584d1f21b285f2",
"md5": "f10b6015d27f5ecd93a916839f9e844b",
"sha256": "e64b6da573642c727d4084be78939b01986be58fadd8180ab2352d27d8a37cb2"
},
"downloads": -1,
"filename": "mqtt_spb_wrapper-1.0.20.tar.gz",
"has_sig": false,
"md5_digest": "f10b6015d27f5ecd93a916839f9e844b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 25119,
"upload_time": "2024-04-26T18:54:45",
"upload_time_iso_8601": "2024-04-26T18:54:45.201106Z",
"url": "https://files.pythonhosted.org/packages/57/75/996fe10bfe337c1890097be6f07cdf8d15a73a5d50108c584d1f21b285f2/mqtt_spb_wrapper-1.0.20.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-26 18:54:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "javier-fg",
"github_project": "mqtt-spb-wrapper",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mqtt-spb-wrapper"
}
JSON
