gp-mqtt-client

A simple console base MQTT client for development purpose.

About

This simple console base MQTT client is for my personal development requirement. It allows me to:

• subscribe to a topic and listen for messages or just get the last one (if any)
• publish a message to a topic

It doesn't support authentication.

Install

The easiest way is to install via npm:

sudo npm i -g gp-mqtt-client

Alternatively, you can clone, build and install:

git clone https://github.com/gpfister/gp-mqtt-client.git
cd gp-mqtt-client
npm ci
sudo npm -g install $(npm pack . | tail -1)

Usage

It uses yargs with a command approach:

$ ./bin/gp-mqtt-client --help
gp-mqtt-client [command]

Commands:
  gp-mqtt-client sub [topic] [options]      Subscribe to a topic
  gp-mqtt-client pub [topic] [message]      Publish a message to a topic
  [options]

Options:
      --help      Show help                                            [boolean]
      --version   Show version number                                  [boolean]
  -h, --hostname  The hostname of the MQTT server[string] [default: "localhost"]
  -p, --port      The port of the MQTT server           [number] [default: 1883]
  -P, --protocol  The protocol to use to connect to the MQTT server
                                                      [string] [default: "mqtt"]
  -v, --verbose                                       [boolean] [default: false]
  -d, --debug                                         [boolean] [default: false]

For more detail, visit https://github.com/gpfister/gp-mqtt-client

This is a free software (MIT License), enjoy !

sub command

This command allow to subscribe to a topic. If the --listen option is used, it will listen to incomming message, reconnecting if needed.

Messages can be decoded using base64 (option --base64).

$ ./bin/gp-mqtt-client sub --help
gp-mqtt-client sub [topic] [options]

Subscribe to a topic

Positionals:
  topic  The topic to subscribe to                                      [string]

Options:
      --help      Show help                                            [boolean]
      --version   Show version number                                  [boolean]
  -h, --hostname  The hostname of the MQTT server[string] [default: "localhost"]
  -p, --port      The port of the MQTT server           [number] [default: 1883]
  -P, --protocol  The protocol to use to connect to the MQTT server
                                                      [string] [default: "mqtt"]
  -v, --verbose                                       [boolean] [default: false]
  -d, --debug                                         [boolean] [default: false]
  -q, --qos       QoS (Quality Of Service) of the topic    [number] [default: 0]
  -b, --base64    Apply base64 decoding               [boolean] [default: false]
  -j, --json      Output as pretty json               [boolean] [default: false]
  -o, --output    Output each message as file to a folder               [string]
  -l, --listen    Listen for new message              [boolean] [default: false]

pub command

This command allow to publish a message to a topic.

$ ./bin/gp-mqtt-client pub --help
gp-mqtt-client pub [topic] [message] [options]

Publish a message to a topic

Positionals:
  topic    The topic to publish to                                      [string]
  message  The message to publish                                       [string]

Options:
      --help      Show help                                            [boolean]
      --version   Show version number                                  [boolean]
  -h, --hostname  The hostname of the MQTT server[string] [default: "localhost"]
  -p, --port      The port of the MQTT server           [number] [default: 1883]
  -P, --protocol  The protocol to use to connect to the MQTT server
                                                      [string] [default: "mqtt"]
  -v, --verbose                                       [boolean] [default: false]
  -d, --debug                                         [boolean] [default: false]
  -q, --qos       QoS (Quality Of Service) of the topic    [number] [default: 0]
  -r, --retain    Add retain flag to message          [boolean] [default: false]

Build

Requirements

This project has been built using

• Ubuntu 20.04
• Node.js v16
• NPM v8
• Mosquitto MQTT Server
• libmosquitto and libmosquitto-dev

To install dependencies on Ubuntu 20.04:

apt install -y mosquitto libmosquitto libmosquitto-dev

Build

To build, first get all dependencies:

npm ci

Then, build the source code:

npm run build

When successfully built, simply run npm run help or ./bin/gp-mqtt-client --help.

Unit test

To run the test script:

npm test

Examples

The following example is used in the context of IoT devices interface to Google Cloud Platform via Cloud IoT Core, emulated via a local Mosquitto MQTT Server, and Firebase emulated via the provided emulators. A Mosquitto server (without authentication) is used.

To monitor device config (QoS = 1):

gp-mqtt-client sub "/devices/<DEVICE_ID>/config" -q 1 -l

The following example publishes a message to a topic on a Mosquitto server (without authentication):

gp-mqtt-client pub "/devices/<DEVICE_ID>/config" "{\"hello\": \"world !\"}" -q 1

Contributions

See instructions here.

License

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

See license here.