{"id":13737012,"url":"https://github.com/zevv/nmqtt","last_synced_at":"2025-10-15T02:27:43.019Z","repository":{"id":87657565,"uuid":"223614360","full_name":"zevv/nmqtt","owner":"zevv","description":"Native Nim MQTT client library","archived":false,"fork":false,"pushed_at":"2025-08-07T03:28:25.000Z","size":190,"stargazers_count":50,"open_issues_count":6,"forks_count":8,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-10-04T11:46:20.394Z","etag":null,"topics":["mqtt","mqtt-broker","mqtt-client","mqtt-library","mqtt-server"],"latest_commit_sha":null,"homepage":null,"language":"Nim","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zevv.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-23T15:54:07.000Z","updated_at":"2025-08-07T03:28:26.000Z","dependencies_parsed_at":"2024-10-30T04:42:43.175Z","dependency_job_id":null,"html_url":"https://github.com/zevv/nmqtt","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/zevv/nmqtt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zevv%2Fnmqtt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zevv%2Fnmqtt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zevv%2Fnmqtt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zevv%2Fnmqtt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zevv","download_url":"https://codeload.github.com/zevv/nmqtt/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zevv%2Fnmqtt/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279035415,"owners_count":26089677,"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","status":"online","status_checked_at":"2025-10-15T02:00:07.814Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["mqtt","mqtt-broker","mqtt-client","mqtt-library","mqtt-server"],"created_at":"2024-08-03T03:01:33.528Z","updated_at":"2025-10-15T02:27:42.971Z","avatar_url":"https://github.com/zevv.png","language":"Nim","funding_links":[],"categories":["Web"],"sub_categories":["Protocols"],"readme":"# Native Nim MQTT client library and binaries\n\nThis is a hybrid package including a native Nim MQTT library and\nbinaries for a MQTT broker, publisher and subscriber.\n\n* [Install](#Install)\n* [Binaries](#Binaries)\n  * [nmqtt](#nmqtt)\n  * [nmqtt_password](#nmqtt_password)\n  * [nmqtt_pub](#nmqtt_pub)\n  * [nmqtt_sub](#nmqtt_sub)\n* [Library](#Library)\n  * [Examples](#Examples)\n  * [Procs](#Procs)\n\n\n# Install\n\nYou can install this package with Nimble:\n```nim\n$ nimble install nmqtt\n```\n\nor cloning and installing:\n```nim\n$ git clone https://github.com/zevv/nmqtt.git \u0026\u0026 cd nmqtt\n$ nimble install\n```\n\n# Binaries\n\nThe package provides 4 MQTT binaries:\n1) `nmqtt` -\u003e Broker\n2) `nmqtt_password` -\u003e Password utility for the broker\n3) `nmqtt_pub` -\u003e MQTT publisher\n4) `nmqtt_sub` -\u003e MQTT subscriber\n\n\n## nmqtt\n\nA default configuration file is provided in `config/nmqtt.conf`. You can copy and paste this file to a desired location, or run `nimble setup nmqtt` which will guide you through it.\n\n```\n$ nmqtt --help\nnmqtt version 1.0.0\n\nnmqtt is a MQTT v3.1.1 broker\n\nUSAGE\n  nmqtt [options]\n  nmqtt [-c /path/to/config.conf]\n  nmqtt [-h hostIP -p port]\n\nCONFIG\n  Use the configuration file for detailed settings,\n  such as SSL, adjusting keep alive timer, etc. or\n  specify options at the command line.\n\n  To add and delete users from the password file\n  please use nmqtt_password:\n    - nmqtt_password -a|-b|-d [options]\n\nOPTIONS\n  -?, --help          print this cligen-erated help\n  -c=, --config=      absolute path to the config file. Overrides all other options.\n  -h=, --host=        IP-address to serve the broker on.\n  -p=, --port=        network port to accept connecting from.\n  -v=, --verbosity=   verbosity from 0-3.\n  --max-conn=         max simultaneous connections. Defaults to no limit.\n  --clientid-maxlen=  max lenght of clientid. Defaults to 65535.\n  --clientid-spaces   allow spaces in clientid. Defaults to false.\n  --clientid-empty    allow empty clientid and assign random id. Defaults to false.\n  --client-kickold    kick old client, if new client has same clientid. Defaults to false.\n  --clientid-pass     pass clientid in payload {clientid:payload}. Defaults to false.\n  --password-file=    absolute path to the password file\n  --ssl               activate ssl for the broker - requires --ssl-cert and --ssl-key.\n  --ssl-cert=         absolute path to the ssl certificate.\n  --ssl-key=          absolute path to the ssl key.\n```\n\n\n## nmqtt_password\n```\n$ nmqtt_password --help\nnmqtt_password is a user and password manager for nmqtt\nnmqtt_password is based upon nmqtt version 1.0.0\n\nUSAGE\n  nmqtt_password -a {password_file.conf} {username}\n  nmqtt_password -b {password_file.conf} {username} {password}\n  nmqtt_password -d {password_file.conf} {username}\n\nCONFIG\n  Add or delete users from nmqtt password file.\n\nOPTIONS\n  -?, --help     print this cligen-erated help\n  -a, --adduser  add a new user to the password file.\n  -b, --batch    run in batch mode to allow passing passwords on the command line.\n  -d, --deluser  delete a user from the password file.\n```\n\n\n## nmqtt_pub\n```\n$ ./nmqtt_pub --help\nnmqtt_pub is a MQTT client for publishing messages to a MQTT-broker.\nnmqtt_pub is based upon nmqtt version 1.0.0\n\nUsage:\n  nmqtt_pub [options] -t {topic} -m {message}\n  nmqtt_pub [-h host -p port -u username -P password] -t {topic} -m {message}\n\nOPTIONS\n  -?, --help         print this cligen-erated help\n  -h=, --host=       IP-address of the broker.\n  -p=, --port=       network port to connect too.\n  --ssl              use ssl.\n  -c=, --clientid=   your connection ID. Defaults to nmqttpub- appended with processID.\n  -u=, --username=   provide a username\n  -P=, --password=   provide a password\n  -t=, --topic=      mqtt topic to publish to.\n  -m=, --msg=        message payload to send.\n  -q=, --qos=        quality of service level to use for all messages.\n  -r, --retain       retain messages on the broker.\n  --repeat=          repeat the publish N times.\n  --repeatdelay=     if using --repeat, wait N seconds between publish. Defaults to 0.\n  --willtopic=       set the will's topic\n  --willmsg=         set the will's message\n  --willqos=         set the will's quality of service\n  --willretain       set to retain the will message\n  -v=, --verbosity=  set the verbosity level from 0-2. Defaults to 0.\n```\n\n\n## nmqtt_sub\n```\n$ ./nmqtt_sub --help\nnmqtt_sub is a MQTT client that will subscribe to a topic on a MQTT-broker.\nnmqtt_sub is based upon nmqtt version 1.0.0\n\nUsage:\n  nmqtt_sub [options] -t {topic}\n  nmqtt_sub [-h host -p port -u username -P password] -t {topic}\n\nOPTIONS\n  -?, --help         print this cligen-erated help\n  -h=, --host=       IP-address of the broker. Defaults to 127.0.0.1\n  -p=, --port=       network port to connect too. Defaults to 1883.\n  --ssl              use ssl.\n  -c=, --clientid=   your connection ID. Defaults to nmqttsub- appended with processID.\n  -u=, --username=   provide a username\n  -P=, --password=   provide a password\n  -t=, --topic=      MQTT topic to subscribe too. For multipe topics, separate them by comma.\n  -q=, --qos=        quality of service level to use for all messages. Defaults to 0.\n  -k=, --keepalive=  keep alive in seconds for this client. Defaults to 60.\n  --removeretained   clear any retained messages on the topic\n  --willtopic=       set the will's topic\n  --willmsg=         set the will's message\n  --willqos=         set the will's quality of service\n  --willretain       set to retain the will message\n  -v=, --verbosity=  set the verbosity level from 0-2. Defaults to 0.\n```\n\n\n# Library\n\nThis library includes all the needed proc's for publishing MQTT messages to\na MQTT-broker and for subscribing to a topic on a MQTT-broker. The library supports QOS 1, 2 and 3 for both publishing and subscribing and sending retained messages.\n\n## Examples\n\n### Subscribe to topic\n```nim\nimport nmqtt, asyncdispatch\n\nlet ctx = newMqttCtx(\"nmqttClient\")\nctx.set_host(\"test.mosquitto.org\", 1883)\n#ctx.set_auth(\"username\", \"password\")\n#ctx.set_ping_interval(30)\n#ctx.set_ssl_certificates(\"cert.crt\", \"private.key\")\n\nproc mqttSub() {.async.} =\n  await ctx.start()\n  proc on_data(topic: string, message: string) =\n    echo \"got \", topic, \": \", message\n\n  await ctx.subscribe(\"nmqtt\", 2, on_data)\n\nasyncCheck mqttSub()\nrunForever()\n```\n\n### Publish msg\n```nim\nproc mqttPub() {.async.} =\n  await ctx.start()\n  await ctx.publish(\"nmqtt\", \"hallo\", 2)\n  await sleepAsync 500\n  await ctx.disconnect()\n\nwaitFor mqttPub()\n```\n\n### Subscribe and publish\n```nim\nproc mqttSubPub() {.async.} =\n  await ctx.start()\n\n  # Callback when receiving on the topic\n  proc on_data(topic: string, message: string) =\n    echo \"got \", topic, \": \", message\n\n  # Subscribe to topic the topic `nmqtt`\n  await ctx.subscribe(\"nmqtt\", 2, on_data)\n  await sleepAsync 500\n\n  # Publish a message to the topic `nmqtt`\n  await ctx.publish(\"nmqtt\", \"hallo\", 2)\n  await sleepAsync 500\n\n  # Disconnect\n  await ctx.disconnect()\n\nwaitFor mqttSubPub()\n```\n\n\n\n## Procs\n\n### newMqttCtx*\n\n```nim\nproc newMqttCtx*(clientId: string): MqttCtx =\n```\n\nInitiate a new MQTT client\n\n\n____\n\n### set_ping_interval*\n\n```nim\nproc set_ping_interval*(ctx: MqttCtx, txInterval: int) =\n```\n\nSet the clients ping interval in seconds. Default is 60 seconds.\n\n____\n\n### set_ssl_certificates*\n\n```nim\nproc set_ssl_certificates*(ctx: MqttCtx, sslCert: string, sslKey: string) =\n```\n\nSets the SSL Certificate and Key files to use Mutual TLS authentication\n\n____\n\n### set_host*\n\n```nim\nproc set_host*(ctx: MqttCtx, host: string, port: int=1883, sslOn=false) =\n```\n\nSet the MQTT host\n\n\n____\n\n### set_auth*\n\n```nim\nproc set_auth*(ctx: MqttCtx, username: string, password: string) =\n```\n\nSet the authentication for the host\n\n\n____\n\n### set_will*\n\n```nim\nproc set_will*(ctx: MqttCtx, topic, msg: string, qos=0, retain=false) =\n```\n\nSet the clients will.\n\n\n____\n\n### connect*\n\n```nim\nproc connect*(ctx: MqttCtx) {.async.} =\n```\n\nConnect to the broker.\n\n\n____\n\n### start*\n\n```nim\nproc start*(ctx: MqttCtx) {.async.} =\n```\n\nAuto-connect and reconnect to the broker. The client will try to\nreconnect when the state is `Disconnected` or `Error`. The `Error`-state\nhappens, when the broker is down, but the client will try to reconnect\nuntil the broker is up again.\n\n\n____\n\n### disconnect*\n\n```nim\nproc disconnect*(ctx: MqttCtx) {.async.} =\n```\n\nDisconnect from the broker.\n\n\n____\n\n### publish*\n\n```nim\nproc publish*(ctx: MqttCtx, topic: string, message: string, qos=0, retain=false) {.async.} =\n```\n\nPublish a message.\n\n**Required:**\n  - topic: string\n  - message: string\n\n**Optional:**\n  - qos: int     = 0, 1 or 2\n  - retain: bool = true or false\n\n**Publish message:**\n```nim\nctx.publish(topic = \"nmqtt\", message = \"Hey there\", qos = 0, retain = true)\n```\n\n**Remove retained message on topic:**\n\nSet the `message` to _null_.\n```nim\nctx.publish(topic = \"nmqtt\", message = \"\", qos = 0, retain = true)\n```\n\n\n____\n\n### subscribe*\n\n```nim\nproc subscribe*(ctx: MqttCtx, topic: string, qos: int, callback: PubCallback): Future[void] =\n```\n\nSubscribe to a topic\n\nAccess the callback with:\n```nim\nproc callbackName(topic: string, message: string) =\n  echo \"Topic: \", topic, \": \", message\n```\n\n____\n\n\n### unsubscribe*\n\n```nim\nproc unsubscribe*(ctx: MqttCtx, topic: string): Future[void] =\n```\n\nUnubscribe from a topic.\n\n\n____\n\n### isConnected*\n\n```nim\nproc isConnected*(ctx: MqttCtx): bool =\n```\n\nReturns true, if the client is connected to the broker.\n\n\n____\n\n### msgQueue*\n\n```nim\nproc msgQueue*(ctx: MqttCtx): int =\n```\n\nReturns the number of unfinished packages, which still are in the work queue.\nThis includes all publish and subscribe packages, which has not been fully\nsend, acknowledged or completed.\n\nYou can use this to ensure, that all your of messages are sent, before\nexiting your program.\n\n\n____\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzevv%2Fnmqtt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzevv%2Fnmqtt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzevv%2Fnmqtt/lists"}