{"id":22382487,"url":"https://github.com/jcoreio/sparkplug-client-js","last_synced_at":"2025-06-14T18:08:43.922Z","repository":{"id":22570551,"uuid":"96711732","full_name":"jcoreio/sparkplug-client-js","owner":"jcoreio","description":"MQTT client for communications using the Sparkplug Specification from Cirrus Link Solutions","archived":false,"fork":false,"pushed_at":"2022-07-07T06:50:16.000Z","size":81,"stargazers_count":1,"open_issues_count":4,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-26T19:45:38.847Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"epl-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jcoreio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-07-09T21:12:48.000Z","updated_at":"2020-07-25T20:37:40.000Z","dependencies_parsed_at":"2022-07-11T19:57:20.999Z","dependency_job_id":null,"html_url":"https://github.com/jcoreio/sparkplug-client-js","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcoreio%2Fsparkplug-client-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcoreio%2Fsparkplug-client-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcoreio%2Fsparkplug-client-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcoreio%2Fsparkplug-client-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jcoreio","download_url":"https://codeload.github.com/jcoreio/sparkplug-client-js/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcoreio%2Fsparkplug-client-js/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":257113351,"owners_count":22492017,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-05T00:13:13.110Z","updated_at":"2025-06-14T18:08:43.899Z","avatar_url":"https://github.com/jcoreio.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"Sparkplug Client\n=========\n\nMQTT client for communications using the Sparkplug Specification from Cirrus Link Solutions\n\nhttps://s3.amazonaws.com/ignition-modules/Current/Sparkplug+Specification.pdf\n\nThe client will connect to an MQTT Server and act as an MQTT Edge of Network\n(EoN) Node.  It will publish birth certificates (NBIRTH), node data messages\n(NDATA), and process node command messages (NCMD) that have been sent from\nanother MQTT client.\n\nThe client also provides and interface for MQTT Device application code to\npublish device birth certificates (DBIRTH), device data messages (DDATA),\ndevice death certificates (DDEATH), and receive device command messages (DCMD)\nthat have been sent from another MQTT client.\n\n## Installation\n\n  npm install sparkplug-client\n\n## Usage\n\n### Creating and configuring a new Sparkplug client\n\nA configuration object is required when creating a new client.  A configuration\nmust contain the following properties:\n\n* serverUrl: The URL of the MQTT server.\n* username: The username for the MQTT server connection.\n* password: The password for the MQTT server connection.\n* groupId: An ID representing a logical grouping of MQTT EoN Nodes and Devices\n  into the infrastructure.\n* edgeNode: An ID that uniquely identifies the MQTT EoN Node within the\n  infrastructure.\n* clientId: A unique ID for the MQTT client connection.\n* publishDeath: A flag indicating if a Node DEATH Certificate (NDEATH) should\n  be published when the client is stopped (defaults to false).\n* version: The Sparkplug version (currently: A or B).  This will indicate how\n  the payload of the published Sparkplug messages are formatted. \n\nHere is a code example of creating and configuring a new client:\n\n```javascript\nvar sparkplug = require('sparkplug-client'),\n    config = {\n        'serverUrl' : 'tcp://localhost:1883',\n        'username' : 'username',\n        'password' : 'password',\n        'groupId' : 'Sparkplug Devices',\n        'edgeNode' : 'Test Edge Node',\n        'clientId' : 'JavaScriptSimpleEdgeNode',\n        'version' : 'spBv1.0'\n    },\n    client = sparkplug.newClient(config);\n```\n\n### Stopping the client\n\nOnce a client has been created and configured it will automatically connect to\nthe MQTT Server.  the client provides a function for stopping the client and\ncleanly disconnecting from the MQTT Server.  Once a client has been stopped, a\nnew client must be created and configured in order to re-establish a connection\nwith the server.\n\nHere is a code example of stopping a client:\n\n```javascript\n// Stop the sparkplug client\nclient.stop();\n```\n\n### Publishing messages\n\nThis client provides functions for publishing three types of messages: a device\nbirth certificate (DBIRTH), device data message (DDATA), device death\ncertificate (DDEATH)\n\n#### Message Payloads ####\n\nThe payload format for Sparkplug messages differs based on the Sparkplug version.\nA full description of each versions payload format is beyond the scope of this\nreadme and can be found in the Sparkplug specification linked above.  The examples\nin this readme will be using Sparkplug B.  \n\nHere is a quick summary of the main changes in version B (over A):\n\n* Added more supported data types for metric values\n* Added support for generic property sets\n* Removed required \"position\" field\n* Change the name of the metrics list field from \"metric\" to \"metrics\".\n\n#### Publish Options\n\nEach of the publish methods below can optionally take an object as an additional \nargument.  This object contains any configured options for the publish.\n\n##### Compression Option\n\nA payload can be compressed before it is published by enabling payload compression\nin the options object and passing it to a plush command.  For example:\n\n```javascript\nvar options = {\n    \"compress\" : true\n};\n\n// Publish device data\nclient.publishDeviceData(deviceId, payload, options);\n```\n\nAdditionally the compression algorithm can be specified as well.  Currently \nsupported algorithms are: DEFLATE and GZIP.  DEFLATE will be used if not algorithm\nis specified. For example:\n\n```javascript\nvar options = {\n    \"compress\" : true,\n    \"algorithm\" : \"GZIP\"\n};\n\n// Publish device data\nclient.publishDeviceData(deviceId, payload, options);\n```\n\n#### Edge Node Birth Certificate (NBIRTH)\n\nA Sparkplug node birth certificate (NBIRTH) message will contain all data points,\nprocess variables, and/or metrics for the edge node. The payload for this message\nwill differ slightly between the different Sparkplug versions.\n\n* timestamp:  A UTC timestamp represented by 64 bit integer.\n* metrics:  An array of metric objects. Each metric in the array must contain\n  the following:\n  * name:  The name of the metric.\n  * value:  The value of the metric.\n  * type:  The type of the metric.  The following types are supported: int, \n    int8, int16, int32, int64, uint8, uint16, uint32, uint64, float, double, \n    boolean, string, datetime, text, uuid, dataset, bytes, file, or template.\n\nHere is a code example of publishing a NBIRTH message:\n\n```javascript\nvar payload = {\n        \"timestamp\" : 1465577611580,\n        \"metrics\" : [\n            {\n                \"name\" : \"my_int\",\n                \"value\" : 456,\n                \"type\" : \"int32\"\n            },\n            {\n                \"name\" : \"my_float\",\n                \"value\" : 1.23,\n                \"type\" : \"float\"\n            }\n        ]\n    };\n\n// Publish device birth\nclient.publishNodeBirth(payload);\n```\n\n\n#### Device Birth Certificate (DBIRTH)\n\nA Sparkplug device birth certificate (DBIRTH) message will contain all data points,\nprocess variables, and/or metrics for the device. The payload for this message\nwill differ slightly between the different Sparkplug versions.\n\n* timestamp:  A UTC timestamp represented by 64 bit integer.\n* metrics:  An array of metric objects. Each metric in the array must contain\n  the following:\n  * name:  The name of the metric.\n  * value:  The value of the metric.\n  * type:  The type of the metric.  The following types are supported: int, \n    int8, int16, int32, int64, uint8, uint16, uint32, uint64, float, double, \n    boolean, string, datetime, text, uuid, dataset, bytes, file, or template.\n\nHere is a code example of publishing a DBIRTH message:\n\n```javascript\nvar deviceId = \"testDevice\",\n    payload = {\n        \"timestamp\" : 1465577611580,\n        \"metrics\" : [\n            {\n                \"name\" : \"my_int\",\n                \"value\" : 456,\n                \"type\" : \"int32\"\n            },\n            {\n                \"name\" : \"my_float\",\n                \"value\" : 1.23,\n                \"type\" : \"float\"\n            }\n        ]\n    };\n\n// Publish device birth\nclient.publishDeviceBirth(deviceId, payload);\n```\n\n\n#### Node Data Message (NDATA)\n\nAn edge node data message (NDATA) will look similar to NBIRTH but is not required\nto publish all metrics. However, it must publish at least one metric.\n\nHere is a code example of publishing a DBIRTH message:\n\n```javascript\nvar payload = {\n        \"timestamp\" : 1465456711580,\n        \"metrics\" : [\n            {\n                \"name\" : \"my_int\",\n                \"value\" : 412,\n                \"type\" : \"int32\"\n            }\n        ]\n    };\n\n// Publish device data\nclient.publishNodeData(payload);\n```\n\n\n#### Device Data Message (DDATA)\n\nA device data message (DDATA) will look similar to DBIRTH but is not required\nto publish all metrics. However, it must publish at least one metric.\n\nHere is a code example of publishing a DBIRTH message:\n\n```javascript\nvar deviceId = \"testDevice\",\n    payload = {\n        \"timestamp\" : 1465456711580,\n        \"metrics\" : [\n            {\n                \"name\" : \"my_int\",\n                \"value\" : 412,\n                \"type\" : \"int32\"\n            }\n        ]\n    };\n\n// Publish device data\nclient.publishDeviceData(deviceId, payload);\n```\n\n#### Node Death Certificate (NDEATH)\n\nAn edge node death certificate (NDEATH) is published to indicated that the edge\nnode has gone offline or has lost a connection.  It registered as an MQTT LWT\nby the SparkplugClient instance and published on the applications behalf.\n\n\n#### Device Death Certificate (DDEATH)\n\nA device death certificate (DDEATH) can be published to indicated that the\ndevice has gone offline or has lost a connection.  It should contain only a\ntimestamp.\n\nHere is a code example of publishing a DBIRTH message:\n\n```javascript\nvar deviceId = \"testDevice\",\n    payload = {\n        \"timestamp\" : 1465456711580\n    };\n\n// Publish device death\nclient.publishDeviceDeath(deviceId, payload);\n```\n\n### Receiving events\n\nThe client uses an EventEmitter to emit events to device applications.  The\nclient emits a \"rebirth\" event, \"command\" event, and four MQTT connection\nevents: \"connect\", \"reconnect\", \"error\", and \"close\".\n\n#### Birth Event\n\nA \"birth\" event is used to signal the device application that a DBIRTH \nmessage is requested.  This event will be be emitted immediately after the \nclient initially connects or re-connects with the MQTT Server.\n\nHere is a code example of handling a \"birth\" event:\n\n```javascript\nsparkplugClient.on('birth', function () {\n    // Publish Node BIRTH certificate\n    sparkplugClient.publishNodeBirth(getNodeBirthPayload());\n    // Publish Device BIRTH certificate\n    sparkplugClient.publishDeviceBirth(deviceId, getDeviceBirthPayload());\n});\n```\n\n#### Command Events\n\nA Device Command event is used to communicate a Device Command message (DCMD)\nfrom another MQTT client to a device. A 'dcmd' event will include the device ID \nand a payload containing a list of metrics (as described above).  Any metrics \nincluded in the payload represent attempts to write a new value to the data \npoints or process variables that they represent.  After the device application\nprocesses the request the device application should publish a DDATA message \ncontaining any metrics that have changed or been updated.\n\nHere is a code example of handling a \"dcmd\" event:\n\n```javascript\nclient.on('dcmd', function (deviceId, payload) {\n    console.log(\"received 'dcmd' event\");\n    console.log(\"device: \" + device);\n    console.log(\"payload: \" + payload);\n\n    //\n    // Process metrics and create new payload containing changed metrics\n    //\n\n    client.publishDeviceData(deviceId, newPayload);\n});\n```\n\nA Node Command event is used to communicate an Edge Node Command message (DCMD) \nor Edge Node Command message (NCMD) from another MQTT client to a device.  An \n'ncmd' event will include a payload containing a list of metrics (as described \nabove).  Any metrics included in the payload may represent attempts to write a \nnew value to the data points or process variables that they represent or they\nmay represent control messages sent to the edge node such as a \"rebirth\" \nrequest.\n\nHere is a code example of handling a \"ncmd\" event:\n\n```javascript\nclient.on('ncmd', function (payload) {\n    console.log(\"received 'ncmd' event\");\n    console.log(\"payload: \" + payload);\n\n    //\n    // Process metrics and create new payload containing changed metrics\n    //\n\n    client.publishNodeData(newPayload);\n});\n```\n\n#### Connect Event\n\nA \"connect\" event is emitted when the client has connected to the server.\n\nHere is a code example of handling a \"connect\" event:\n\n```javascript\nclient.on('connect', function () {\n    console.log(\"received 'connect' event\");\n});\n```\n\n#### Reconnect Event\n\nA \"reconnect\" event is emitted when the client is attempting to reconnect to\nthe server.\n\nHere is a code example of handling a \"reconnect\" event:\n\n```javascript\nclient.on('reconnect', function () {\n    console.log(\"received 'reconnect' event\");\n});\n```\n\n#### Error Event\n\nAn \"error\" event is emitted when the client has experienced an error while\ntrying to connect to the server.\n\nHere is a code example of handling a \"error\" event:\n\n```javascript\nclient.on('error', function (error) {\n    console.log(\"received 'error' event: \" + error);\n});\n```\n\n#### Close Event\n\nA \"close\" event is emitted when the client's connection to the server has been\nclosed.\n\nHere is a code example of handling a \"close\" event:\n\n```javascript\nclient.on('close', function () {\n    console.log(\"received 'close' event\");\n});\n```\n\n## Release History\n\n* 1.0.0 Initial release\n* 1.0.2 Bug Fixes\n* 1.1.0 Added more emitted events (connect, reconnect, error, close)\n* 1.2.0 Added 'publishDeath' config option, updated MQTT.js version\n* 2.0.0 Added support for Sparkplug B and made the version configurable.\n* 3.0.0 Added events for Node Birth/Command events. Renamed 'command' event\n        to distiguish between 'dcmd' (device commands) and 'ncmd' (node \n        commands). Renamed 'rebirth' event to 'birth'. Updated dependency\n        versions and removed bytebuffer as a dependency.\n* 3.1.0 Added support for payload compression/decompression with DEFLATE\n        and Gzip algorithms, added logging with Winston to replace console\n        logging, and other minor bug fixes.\n\n## License\n\nCopyright (c) 2016-2017 Cirrus Link Solutions\n\nAll rights reserved. This program and the accompanying materials\nare made available under the terms of the Eclipse Public License v1.0\nwhich accompanies this distribution, and is available at\nhttp://www.eclipse.org/legal/epl-v10.html\n\nContributors: Cirrus Link Solutions\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjcoreio%2Fsparkplug-client-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjcoreio%2Fsparkplug-client-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjcoreio%2Fsparkplug-client-js/lists"}