midge 0.2

MQTT 3.1.1 client for classic AmigaOS

Short:        MQTT 3.1.1 client for classic AmigaOS
Author:       simond@irrelevant.org (Simon Dick)
Uploader:     simond irrelevant org (Simon Dick)
Type:         comm/net
Version:      0.2
Requires:     68020
Architecture: m68k-amigaos >= 3.1

midge is a native MQTT 3.1.1 client for classic AmigaOS, aimed at putting
your Amiga on a modern smart-home network (Home Assistant, Mosquitto, EMQX)
- as a display and control surface, and as a publisher of its own telemetry.

This release ships:

  mqtt_pub      - publish a message to a broker topic (needs mqtt.library,
                   below, copied to LIBS: first)
  mqtt_sub      - subscribe to topic filters and print incoming messages
                   (needs mqtt.library, below, copied to LIBS: first)
  mqtt_pub-static - the same mqtt_pub, statically linked: no mqtt.library
                     install needed, but QoS 0 publish only
  mqtt_sub-static - the same mqtt_sub, statically linked: no mqtt.library
                     install needed
  libs/mqtt.library - a shared library exposing the same MQTT client to
                       other AmigaOS programs (copy to LIBS: to install -
                       required by mqtt_pub/mqtt_sub above)
  developer/    - mqtt.library's .sfd/.fd/proto/inline/clib headers,
                   its mqtt.doc autodoc, and two example caller programs
                   (pubexample.c/subexample.c) for third-party developers

mqtt_pub/mqtt_sub and their -static counterparts all follow the same
AmigaDOS conventions (ReadArgs templates, Ctrl-C to stop) and speak plain
MQTT 3.1.1 over TCP. mqtt_pub/mqtt_sub are backed by mqtt.library and
support QoS 0 and QoS 1 publish, plus TLS via AmiSSL (TLS/TLSINSECURE -
needs AmiSSL installed separately, see Requirements below);
mqtt_pub-static/mqtt_sub-static talk to bsdsocket.library directly with no
library install required, but mqtt_pub-static only supports QoS 0 publish
and neither -static tool supports TLS. mqtt.library itself also exposes an
optional auto-reconnect mode to programs written against it directly. See
https://sidick.github.io/midge/mqtt-library/ for the full mqtt.library
guide.

Planned for future releases: a ReAction dashboard application with Home
Assistant MQTT discovery.

Requirements
------------
  - AmigaOS 3.1+ (3.2 is the reference platform), 68020 or better.
  - A TCP/IP stack providing bsdsocket.library (Roadshow, AmiTCP, Miami,
    or an emulator-provided stack).
  - For TLS (mqtt_pub/mqtt_sub's TLS/TLSINSECURE switches): AmiSSL 5.x
    (https://github.com/jens-maus/amissl), installed separately - not
    bundled with this archive. Software TLS is CPU-intensive; a genuinely
    stock, unaccelerated 68020 may see intermittent failures under it -
    see https://sidick.github.io/midge/CLI-Reference/ for details.

Quick start
-----------
  mqtt_sub HOST 192.168.1.10 TOPIC home/#
  mqtt_pub HOST 192.168.1.10 TOPIC home/amiga/hello MESSAGE "hello from midge"

AI disclosure
-------------
  midge is written largely by an AI coding agent (Anthropic's Claude /
  Claude Code), under human direction, review and on-hardware testing.
  The protocol codec is verified against MQTT 3.1.1 specification vectors
  and tested against real brokers; full source is open (BSD) for review.

Documentation, source and licence
---------------------------------
  Free and open source, BSD 2-Clause. Full documentation (versioned per
  release, and included as midge.guide in this archive), source and issue
  tracker:
      https://sidick.github.io/midge/
      https://github.com/sidick/midge