HiveMind-presence

Local-network presence and discovery for HiveMind nodes. A node announces itself on the LAN so satellites can find the hub without being told its IP address, and a satellite scans the LAN to discover reachable hubs.

It sits next to hivemind-core (the hub) and the client libraries. The hub advertises its WebSocket address with hivemind-presence announce. A client uses hivemind-presence scan (or the LocalDiscovery API) to locate it and open a connection.

Discovery transports

• mDNS / Zeroconf: multicast DNS service discovery. The optional zeroconf dependency is LGPL and imported lazily. Install it to enable mDNS.
• UPnP / SSDP: an SSDP server advertises a UPnP device descriptor. The scanner discovers it over SSDP.

The roadmap moves the default transport to HiveBeacon, a zero-dependency UDP broadcast beacon absorbed from the archived HiveBeacon project, and keeps mDNS as an optional transport. UPnP is being retired. Until the beacon transport ships, mDNS and UPnP are the available transports.

Prerequisites

• Python 3.10+
• A HiveMind hub (hivemind-core) reachable on the LAN for scan to find anything.
• For mDNS: the optional zeroconf package (pip install zeroconf). Without it, announce/scan silently fall back to UPnP only.

Install

pip install hivemind-presence

From source:

git clone https://github.com/JarbasHiveMind/HiveMind-presence
cd HiveMind-presence
pip install -e .

To include mDNS support:

pip install hivemind-presence zeroconf

Quickstart

On the hub (advertise the node):

hivemind-presence announce --port 5678 --name living_room

On a satellite (discover hubs on the LAN):

hivemind-presence scan

            HiveMind Nodes
┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━┓
┃ Friendly Name ┃ Host         ┃ Port ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━┩
│   living_room │ 192.168.1.9  │ 5678 │
│       kitchen │ 192.168.1.13 │ 5678 │
└───────────────┴──────────────┴──────┘

Both announce and scan use mDNS by default (--zeroconf true --upnp false). Pass --upnp true to add the UPnP/SSDP transport.

Programmatic use

Announce from a hub process:

from hivemind_presence import LocalPresence

presence = LocalPresence(port=5678, name="living_room")
presence.start()
# ... run your hub ...
presence.stop()

Discover and connect from a client:

from hivemind_presence import LocalDiscovery

disc = LocalDiscovery()
for node in disc.scan(timeout=25):
    bus = node.connect(key="my-access-key", crypto_key="my-crypto-key")
    break

HiveMindNode.connect() returns a running HiveMessageBusClient connected to the discovered hub.

Configuration

announce and scan options:

At least one transport must be enabled for scan. LocalDiscovery raises an error if both are disabled.

Documentation

See docs/:

• How it works: the announce/scan flow and the transports.
• Configuration reference: every CLI option and API argument.
• Examples: discover-then-connect, hub announce loop.

License

MIT