Metadata-Version: 2.4
Name: roboflex.transport.mqtt
Version: 0.1.8
Summary: Roboflex Transport mqtt Library
Home-page: https://github.com/flexrobotics/roboflex_transport_mqtt
Author: Colin Prepscius
Author-email: colinprepscius@gmail.com
License: MIT
Keywords: mqtt,robotics,middleware,flexbuffers,python,c++,c++20
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Framework :: Robot Framework
Classifier: Framework :: Robot Framework :: Library
Classifier: Framework :: Robot Framework :: Tool
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.0
Requires-Dist: roboflex
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# roboflex.transport.mqtt

Rooboflex support for the MQTT transport.

See https://mqtt.org/ for details.

Using MQTT, nodes can connect to other nodes, even running on different computers. You must run your own MQTT broker - broker functionality is not wrapped in any way.

any node -> MQTTPublisher ==MQTT BROKER==> MQTTSubscriber -> any node

## Contents

* [Install](#install)
* [Import](#import)
* [Classes](#classes)
    * [MQTTContext](#mqttontext)
    * [MQTTNodeBase](#mqttnodebase)
    * [MQTTPublisher](#mqttpublisher)
    * [MQTTSubscriber](#mqttsubscriber)


## System Dependencies

    apt-get install mosquitto
    apt-get install libmosquitto-dev

    ... or on mac ...
    brew install mosquitto

## Build

    mkdir build && cd build
    cmake ..
    make

## Run Examples (see [examples](examples))

    pub_sub_0_cpp
    python pub_sub_0_py

## Import

    import roboflex.transport.mqtt as rtm

# Classes

Roboflex's support for MQTT is embodied in four classes:

1. MQTTContext, which you just have to instantiate somewhere
2. MQTTNodeBase, a base class which you don't use
3. MQTTPublisher, which can publish to an mqtt topic somewhere
4. MQTTSubscriber, which can subscribe to an mqtt topic somewhere


## MQTTContext

In order to use the other MQTT classes, you must instantiate an MQTTContext, and its lifetime must be >= the lifetime of all other MQTT node classes. You must pass an instance of this class to the constructors
of both MQTTPublisher and MQTTSubscriber.

    # instantiate like so:
    mqtt_context = rtm.MQTTContext()

## MQTTNodeBase

Do not instantiate directly. This is the base class for MQTTPublisher and MQTTSubscriber, and holds common functionality and properties.

    # the address of the broker
    mqtt_node.broker_address -> str

    # the port number of the broker
    mqtt_node.broker_port -> int

    # the number of seconds between keepalive messages
    mqtt_node.keepalive_seconds -> int

    # the topic to publish or subscribe to
    mqtt_node.topic_name -> str

    # the mqtt quality-of-service
    mqtt_node.qos -> int

    # whether to print out debug messages
    mqtt_node.debug -> bool

## MQTTPublisher

_**(inherits MQTTNodeBase)**_

Publishes any messages it receives to some topic, on some broker. When it receives an message, it publishes the binary representation on the given topic, and then propagages the message verbatim.

    mqtt_publisher = rtm.MQTTPublisher(
        mqtt_context: rtm.MQTTContext,
        broker_address: str,
        broker_port: int,
        keepalive_seconds: int,
        topic_name: str,

        # optional...
        name: str = "MQTTPublisher",
        qos: int = 0,
        retained: bool = false,
        debug: bool = false,
    )

    # additional properties:

    # See the MQTT documentation for what the retained feature does:
    # https://www.hivemq.com/blog/mqtt-essentials-part-8-retained-messages/
    mqtt_publisher.retained -> bool

    # If you have some message 'in hand' in some other function,
    # you can just use an MQTTPublisher to publish the message
    # directly. This is just an alias for 'signal_self' on core::Node.
    mqtt_publisher.publish({"key1": 32})


## MQTTSubscriber

_**(inherits MQTTNodeBase)**_

Suscribes to some topic from some broker. Expects only Roboflex encoded messages.

    mqtt_subscriber = rtm.MQTTSubscriber(
        mqtt_context: rtm.MQTTContext,
        broker_address: str,
        broker_port: int,
        keepalive_seconds: int,
        topic_name: str,

        # optional...
        name: str = "MQTTSubscriber",
        qos: int = 0,
        loop_timeout_milliseconds: int = 100,
        debug: bool = false,
    )

    # additional properties:

    # number of milliseconds, max, to wait in the mqtt message loop,
    # before checking whether to continue or not.
    mqtt_subscriber.loop_timeout_milliseconds -> int
