nemo-mqtt-bridge 2.0.0

MQTT integration plugin for NEMO tool usage events

NEMO_mqtt_bridge

Knowing a tool's status (interlock enabled or disabled) is critical in most labs using NEMO, but many setups only indicate this via NEMO itself or a simple LED. This project enables NEMO to send MQTT messages to displays on each tool, providing detailed, real-time status information such as current user, start time, and previous user.

The hardware, firmware, and broker code associated with this project can be found at: https://github.com/alexanderenrique/NEMO-Tool-Display

This is a Django plugin that publishes NEMO tool usage events to MQTT (tool enable/disable, tool saves). Uses PostgreSQL LISTEN/NOTIFY and a separate bridge process to keep broker connections out of Django.

Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────────┐    ┌─────────────┐
│   Django NEMO   │───▶│   PostgreSQL     │───▶│ PostgreSQL–MQTT      │───▶│ MQTT Broker │
│  (signals)      │    │  (event queue)   │    │ Bridge (standalone)  │    │             │
└─────────────────┘    └──────────────────┘    └─────────────────────┘    └─────────────┘

• Django: Signal handlers (Tool save, UsageEvent) insert into MQTTEventQueue and use pg_notify to wake the bridge.
• Bridge: Separate process runs python -m NEMO_mqtt_bridge.postgres_mqtt_bridge; it LISTENs for notifications, fetches events, and publishes to the MQTT broker with QoS 1.
• Topics: nemo/tools/{id}/enabled, nemo/tools/{id}/disabled

Configuration is stored in Django (e.g. /customization/mqtt/) and loaded by the bridge on each connection.

Installation

Prerequisites: Python 3.8+, Django 3.2+, NEMO-CE 4.0+, MQTT broker (e.g. Mosquitto), PostgreSQL (NEMO's database). The plugin uses the same PostgreSQL database as NEMO; no Redis required.

Simplified deployment: The plugin package is NEMO_mqtt_bridge. Add 'NEMO_mqtt_bridge' to INSTALLED_APPS, then run python manage.py setup_nemo_integration (use --write-urls to add the URL include to NEMO/urls.py) and python manage.py migrate NEMO_mqtt_bridge.

From PyPI (recommended)

pip install nemo-mqtt-bridge
cd /path/to/your/nemo-ce
# Add 'NEMO_mqtt_bridge' to INSTALLED_APPS in your settings (see Manual below).
python manage.py setup_nemo_integration
python manage.py migrate NEMO_mqtt_bridge

Local / testing: The command above only prints integration steps (no file changes). Add NEMO_mqtt_bridge to INSTALLED_APPS and any logging config yourself. Use --write-urls to add the MQTT URL include to NEMO/urls.py.

Production with GitLab/Ansible: If your config is in version control and deployed by GitLab or Ansible, run with --gitlab so no files are changed on the server; the command will print the snippets to add to your repo:

python manage.py setup_nemo_integration --gitlab
# Add the printed snippets to your repo (INSTALLED_APPS and URLs; configure logging as needed for your environment), commit, and deploy. Then on the server:
python manage.py migrate NEMO_mqtt_bridge

Manual

1. pip install nemo-mqtt-bridge
2. Add 'NEMO_mqtt_bridge' to INSTALLED_APPS in your settings.
3. (Optional) If you use Django's LOGGING setting, add a NEMO_mqtt_bridge logger with your preferred level and handlers (e.g. DEBUG in dev/test, INFO or WARNING in production). What and how you log is installation-dependent.
4. run python manage.py setup_nemo_integration to print integration steps, or add path("mqtt/", include("NEMO_mqtt_bridge.urls")) to NEMO/urls.py yourself. Use --write-urls to have the command add the URL include.
5. Run python manage.py migrate NEMO_mqtt_bridge.

After install

1. Configure: Open /customization/mqtt/ in NEMO, set broker host/port (and auth if needed), enable the config.
2. Start NEMO (e.g. python manage.py runserver). With the default AUTO mode, the plugin uses the PostgreSQL–MQTT bridge and a local Mosquitto broker for development.

Production: Use EXTERNAL mode so the plugin does not start or kill brokers: set PostgresMQTTBridge(auto_start=False) in NEMO_mqtt_bridge/apps.py (or configure the bridge to not auto-start Mosquitto). Then start the MQTT broker yourself, and run the bridge separately (e.g. python -m NEMO_mqtt_bridge.postgres_mqtt_bridge or as a systemd service).

---

• Monitoring: Event stream at /mqtt/monitor/; CLI tools in NEMO_mqtt_bridge.monitoring (see src/NEMO_mqtt_bridge/monitoring/README.md).
• HMAC: Optional payload signing
• License: MIT. Issues · Discussions