mqtt

Kind	ffi-c
Capabilities	ffi
Categories	networking ffi
Keywords	mqtt iot messaging pubsub protocol

MQTT protocol client bindings for Kit

Files

File	Description
`.editorconfig`	Editor formatting configuration
`.gitignore`	Git ignore rules for build artifacts and dependencies
`.tool-versions`	asdf tool versions (Zig, Kit)
`LICENSE`	MIT license file
`README.md`	This file
`c/kit_mqtt.c`	C FFI wrapper
`c/kit_mqtt.h`	C header for FFI wrapper
`examples/basic.kit`	Basic usage example
`kit.toml`	Package manifest with metadata and dependencies
`src/mqtt.kit`	Kit MQTT - MQTT protocol client bindings
`tests/mqtt.test.kit`	Tests for mqtt

Dependencies

No Kit package dependencies.

Installation

kit add gitlab.com/kit-lang/packages/kit-mqtt.git

System Requirements

Platform	Command
macOS	`brew install mosquitto`
Ubuntu	`sudo apt install libmosquitto-dev`
Fedora	`sudo dnf install mosquitto-devel`

Usage

import Kit.MQTT as Mqtt

main = fn =>
  match Mqtt.lib-init
    | Ok _ -> println "MQTT initialized"
    | Err e -> println ("Init error: " ++ e)

  match Mqtt.new "kit-client"
    | Ok client ->
      match Mqtt.connect client "localhost" 1883 60
        | Ok _ ->
          # Subscribe to a topic
          match Mqtt.subscribe client "kit/test" (Mqtt.qos-1)
            | Ok _ -> println "Subscribed"
            | Err e -> println ("Subscribe error: " ++ e)

          # Publish a message
          match Mqtt.publish client "kit/test" "Hello from Kit!" (Mqtt.qos-1) false
            | Ok _ -> println "Published"
            | Err e -> println ("Publish error: " ++ e)

          # Process network events
          match Mqtt.loop client 1000
            | Ok _ ->
              if Mqtt.has-message? then
                println ("Topic: " ++ Mqtt.get-last-topic)
                println ("Payload: " ++ Mqtt.get-last-payload)
                Mqtt.clear-message
            | Err e -> println ("Loop error: " ++ e)

          match Mqtt.disconnect client
            | Ok _ -> println "Disconnected"
            | Err e -> println ("Disconnect error: " ++ e)
        | Err e -> println ("Connect error: " ++ e)

      Mqtt.destroy client
    | Err e -> println ("Client error: " ++ e)

  Mqtt.lib-cleanup

main

Development

Running Examples

Run examples with the interpreter:

kit run examples/basic.kit

Compile examples to a native binary:

kit build examples/basic.kit && ./basic

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running kit dev

Run the standard development workflow (format, check, test):

kit dev

This will:

Format and check source files in src/
Run tests in tests/ with coverage

Generating Documentation

Generate API documentation from doc comments:

kit doc

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/mqtt/, making it available for import as Kit.MQTT in other projects.

License

This package is released under the MIT License - see LICENSE for details.

Mosquitto is released under the Eclipse Public License 2.0.

Exported Functions & Types

`qos-0`

QoS 0: At most once delivery (fire and forget).

Int

`qos-1`

QoS 1: At least once delivery (acknowledged).

Int

`qos-2`

QoS 2: Exactly once delivery (assured).

Int

`lib-init`

Initialize the MQTT library. Must be called before any other operations.

Returns:

Result Unit String

`lib-cleanup`

Clean up the MQTT library and release global resources.

Unit

`new`

Create a new MQTT client instance.

Parameters:

Returns:

NonEmptyString -> Result Ptr String

`destroy`

Destroy an MQTT client and free its resources.

Parameters:

Ptr -> Unit

`connect`

Connect to an MQTT broker.

Parameters:

Returns:

Ptr -> NonEmptyString -> PositiveInt -> PositiveInt -> Result Unit String

`disconnect`

Disconnect from the MQTT broker.

Parameters:

Returns:

Ptr -> Result Unit String

`reconnect`

Reconnect to the previously connected broker.

Parameters:

Returns:

Ptr -> Result Unit String

`publish`

Publish a message to a topic.

Parameters:

Returns:

Ptr -> NonEmptyString -> String -> Int -> Bool -> Result Unit String

`subscribe`

Subscribe to a topic.

Parameters:

Returns:

Ptr -> NonEmptyString -> Int -> Result Unit String

`unsubscribe`

Unsubscribe from a topic.

Parameters:

Returns:

Ptr -> NonEmptyString -> Result Unit String

`loop`

Process network events for the given timeout period.

Parameters:

Returns:

Ptr -> PositiveInt -> Result Unit String

`loop-start`

Start the background network loop thread.

Parameters:

Returns:

Ptr -> Result Unit String

`loop-stop`

Stop the background network loop thread.

Parameters:

Returns:

Ptr -> Result Unit String

`has-message?`

Check if a new message has been received.

Returns:

Bool

`get-last-topic`

Get the topic of the last received message.

Returns:

String

`get-last-payload`

Get the payload of the last received message.

Returns:

String

`clear-message`

Clear the last received message.

Unit

`set-credentials`

Set username and password for broker authentication.

Parameters:

Returns:

Ptr -> NonEmptyString -> NonEmptyString -> Result Unit String

`version`

Get the Mosquitto library version string.

Returns:

String