{"id":16017160,"url":"https://github.com/njh/ruby-mqtt","last_synced_at":"2025-05-14T19:01:54.411Z","repository":{"id":1714359,"uuid":"2444141","full_name":"njh/ruby-mqtt","owner":"njh","description":"Pure Ruby gem that implements the MQTT protocol, a lightweight protocol for publish/subscribe messaging.","archived":false,"fork":false,"pushed_at":"2024-04-03T00:11:54.000Z","size":554,"stargazers_count":526,"open_issues_count":31,"forks_count":133,"subscribers_count":23,"default_branch":"main","last_synced_at":"2024-04-14T09:23:35.270Z","etag":null,"topics":["mqtt","ruby","rubygems"],"latest_commit_sha":null,"homepage":"http://www.rubydoc.info/gems/mqtt","language":"Ruby","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/njh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2011-09-23T13:41:09.000Z","updated_at":"2024-05-19T08:33:14.336Z","dependencies_parsed_at":"2023-01-13T11:20:01.241Z","dependency_job_id":"ff9d3e72-d214-479a-a842-efae9faf786b","html_url":"https://github.com/njh/ruby-mqtt","commit_stats":{"total_commits":347,"total_committers":36,"mean_commits":9.63888888888889,"dds":0.1469740634005764,"last_synced_commit":"271ee631f128e66732ece935e752f13970d4267b"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njh%2Fruby-mqtt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njh%2Fruby-mqtt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njh%2Fruby-mqtt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njh%2Fruby-mqtt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/njh","download_url":"https://codeload.github.com/njh/ruby-mqtt/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248688550,"owners_count":21145765,"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":["mqtt","ruby","rubygems"],"created_at":"2024-10-08T16:04:14.063Z","updated_at":"2025-04-13T08:59:37.110Z","avatar_url":"https://github.com/njh.png","language":"Ruby","funding_links":[],"categories":["Clients"],"sub_categories":["Ruby"],"readme":"[![Build Status](https://github.com/njh/ruby-mqtt/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/njh/ruby-mqtt/actions/workflows/build.yml?query=branch%3Amain)\n\nruby-mqtt\n=========\n\nPure Ruby gem that implements the [MQTT] protocol, a lightweight protocol for publish/subscribe messaging.\n\nAlso includes a class for parsing and generating [MQTT-SN] packets.\n\n\nTable of Contents\n-----------------\n* [Installation](#installation)\n* [Quick Start](#quick-start)\n* [Library Overview](#library-overview)\n* [Resources](#resources)\n* [License](#license)\n* [Contact](#contact)\n\n\nInstallation\n------------\n\nYou may get the latest stable version from [Rubygems]:\n\n    $ gem install mqtt\n\nAlternatively, to use a development snapshot from GitHub using [Bundler], add this to your `Gemfile`:\n\n~~~ ruby\n    gem 'mqtt', :github =\u003e 'njh/ruby-mqtt'\n~~~\n\nQuick Start\n-----------\n\n~~~ ruby\nrequire 'mqtt'\n\n# Publish example\nMQTT::Client.connect('test.mosquitto.org') do |c|\n  c.publish('test', 'message')\nend\n\n# Subscribe example\nMQTT::Client.connect('test.mosquitto.org') do |c|\n  # If you pass a block to the get method, then it will loop\n  c.get('test') do |topic,message|\n    puts \"#{topic}: #{message}\"\n  end\nend\n~~~\n\n\nLibrary Overview\n----------------\n\n### Connecting ###\n\nA new client connection can be created by passing either a [MQTT URI], a host and port or by passing a hash of attributes.\n\n~~~ ruby\nclient = MQTT::Client.connect('mqtt://myserver.example.com')\nclient = MQTT::Client.connect('mqtts://user:pass@myserver.example.com')\nclient = MQTT::Client.connect('myserver.example.com')\nclient = MQTT::Client.connect('myserver.example.com', 18830)\nclient = MQTT::Client.connect(:host =\u003e 'myserver.example.com', :port =\u003e 1883 ... )\n~~~\n\nTLS/SSL is not enabled by default, to enabled it, pass ```:ssl =\u003e true```:\n\n~~~ ruby\nclient = MQTT::Client.connect(\n  :host =\u003e 'test.mosquitto.org',\n  :port =\u003e 8883,\n  :ssl =\u003e true\n)\n~~~\n\nAlternatively you can create a new Client object and then configure it by setting attributes. This example shows setting up client certificate based authentication:\n\n~~~ ruby\nclient = MQTT::Client.new\nclient.host = 'myserver.example.com'\nclient.ssl = true\nclient.cert_file = path_to('client.pem')\nclient.key_file  = path_to('client.key')\nclient.ca_file   = path_to('root-ca.pem')\nclient.connect()\n~~~\n\nThe connection can either be made without the use of a block:\n\n~~~ ruby\nclient = MQTT::Client.connect('test.mosquitto.org')\n# perform operations\nclient.disconnect()\n~~~\n\nOr, if using a block, with an implicit disconnection at the end of the block.\n\n~~~ ruby\nMQTT::Client.connect('test.mosquitto.org') do |client|\n  # perform operations\nend\n~~~\n\nFor more information, see and list of attributes for the [MQTT::Client] class and the [MQTT::Client.connect] method.\n\n\n### Publishing ###\n\nTo send a message to a topic, use the ```publish``` method:\n\n~~~ ruby\nclient.publish(topic, payload, retain=false)\n~~~\n\nThe method will return once the message has been sent to the MQTT server.\n\nFor more information see the [MQTT::Client#publish] method.\n\n\n### Subscribing ###\n\nYou can send a subscription request to the MQTT server using the subscribe method. One or more [Topic Filters] may be passed in:\n\n~~~ ruby\nclient.subscribe( 'topic1' )\nclient.subscribe( 'topic1', 'topic2' )\nclient.subscribe( 'foo/#' )\n~~~\n\nFor more information see the [MQTT::Client#subscribe] method.\n\n\n### Receiving Messages ###\n\nTo receive a message, use the get method. This method will block until a message is available. The topic is the name of the topic the message was sent to. The message is a string:\n\n~~~ ruby\ntopic,message = client.get\n~~~\n\nAlternatively, you can give the get method a block, which will be called for every message received and loop forever:\n\n~~~ ruby\nclient.get do |topic,message|\n  # Block is executed for every message received\nend\n~~~\n\nFor more information see the [MQTT::Client#get] method.\n\n\n### Parsing and serialising of packets ###\n\nThe parsing and serialising of MQTT and MQTT-SN packets is a separate lower-level API.\nYou can use it to build your own clients and servers, without using any of the rest of the\ncode in this gem.\n\n~~~ ruby\n# Parse a string containing a binary packet into an object\npacket_obj = MQTT::Packet.parse(binary_packet)\n    \n# Write a PUBACK packet to an IO handle\nios \u003c\u003c MQTT::Packet::Puback(:id =\u003e 20)\n    \n# Write an MQTT-SN Publish packet with QoS -1 to a UDP socket\nsocket = UDPSocket.new\nsocket.connect('localhost', MQTT::SN::DEFAULT_PORT)\nsocket \u003c\u003c MQTT::SN::Packet::Publish.new(\n  :topic_id =\u003e 'TT',\n  :topic_id_type =\u003e :short,\n  :data =\u003e \"The time is: #{Time.now}\",\n  :qos =\u003e -1\n)\nsocket.close\n~~~\n\nLimitations\n-----------\n\n * QoS 2 is not currently supported by client\n * Automatic re-connects to the server are not supported\n * No local persistence for packets\n\n\nResources\n---------\n\n* API Documentation: http://rubydoc.info/gems/mqtt\n* Protocol Specification v3.1.1: http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html\n* Protocol Specification v3.1: http://public.dhe.ibm.com/software/dw/webservices/ws-mqtt/mqtt-v3r1.html\n* MQTT-SN Protocol Specification v1.2: http://mqtt.org/new/wp-content/uploads/2009/06/MQTT-SN_spec_v1.2.pdf\n* MQTT Homepage: http://www.mqtt.org/\n* GitHub Project: http://github.com/njh/ruby-mqtt\n\n\nLicense\n-------\n\nThe mqtt ruby gem is licensed under the terms of the MIT license.\nSee the file LICENSE for details.\n\n\nContact\n-------\n\n* Author:    Nicholas J Humfrey\n* Email:     njh@aelius.com\n* Twitter:   [@njh]\n* Home Page: http://www.aelius.com/njh/\n\n\n\n[@njh]:           http://twitter.com/njh\n[MQTT]:           http://www.mqtt.org/\n[MQTT-SN]:        http://mqtt.org/2013/12/mqtt-for-sensor-networks-mqtt-sn\n[Rubygems]:       http://rubygems.org/\n[Bundler]:        http://bundler.io/\n[MQTT URI]:       https://github.com/mqtt/mqtt.github.io/wiki/URI-Scheme\n[Topic Filters]:  http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html#_Toc388534397\n\n[MQTT::Client]:           http://rubydoc.info/gems/mqtt/MQTT/Client#instance_attr_details\n[MQTT::Client.connect]:   http://rubydoc.info/gems/mqtt/MQTT/Client.connect\n[MQTT::Client#publish]:   http://rubydoc.info/gems/mqtt/MQTT/Client:publish\n[MQTT::Client#subscribe]: http://rubydoc.info/gems/mqtt/MQTT/Client:subscribe\n[MQTT::Client#get]:       http://rubydoc.info/gems/mqtt/MQTT/Client:get\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnjh%2Fruby-mqtt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnjh%2Fruby-mqtt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnjh%2Fruby-mqtt/lists"}