{"id":64,"date":"2026-01-06T20:44:43","date_gmt":"2026-01-06T20:44:43","guid":{"rendered":"https:\/\/michaelwinchester.com\/mesh-plug\/?page_id=64"},"modified":"2026-01-06T20:44:44","modified_gmt":"2026-01-06T20:44:44","slug":"developer-reference","status":"publish","type":"page","link":"https:\/\/michaelwinchester.com\/mesh-plug\/developer-reference\/","title":{"rendered":"Developer Reference"},"content":{"rendered":"\n

Mesh-Plug for WordPress<\/h1>\n\n\n\n

Developer Reference and Integration Guide<\/h2>\n\n\n\n

Updated: January 2026 (v0.5.x)<\/strong><\/p>\n\n\n\n

Mesh-Plug bridges Meshtastic networks and MQTT data streams into WordPress, allowing developers to observe, store, enrich, and react<\/strong> to live mesh data using familiar WordPress tools.<\/p>\n\n\n\n

This document is a technical appendix for developers who want to extend Mesh-Plug beyond the default UI; custom dashboards, automations, integrations, and data pipelines.<\/p>\n\n\n\n

\n\n\n\n

1) Architecture Overview<\/h2>\n\n\n\n

Mesh-Plug is structured as layered services rather than a single monolith. Each layer can be extended or intercepted independently.<\/p>\n\n\n\n

MQTT Service Layer<\/h3>\n\n\n\n

Responsible for:<\/p>\n\n\n\n

    \n
  • Broker connection and authentication<\/li>\n\n\n\n
  • Topic subscription management<\/li>\n\n\n\n
  • MQTT-over-WebSocket handling (ws \/ wss)<\/li>\n\n\n\n
  • Payload ingestion and JSON decoding<\/li>\n<\/ul>\n\n\n\n

    Supported connection modes:<\/p>\n\n\n\n

      \n
    • Auto mode<\/strong>; broker resolved via site domain and proxy or tunnel<\/li>\n\n\n\n
    • Manual mode<\/strong>; explicit ws:\/\/<\/code> or wss:\/\/<\/code> endpoint with credentials, TLS, and ACLs<\/li>\n<\/ul>\n\n\n\n

      This layer is intentionally isolated from rendering and storage.<\/p>\n\n\n\n

      \n\n\n\n

      Data Manager<\/h3>\n\n\n\n

      Normalizes inbound messages and routes them to:<\/p>\n\n\n\n

        \n
      • Transient cache (always enabled)<\/li>\n\n\n\n
      • Optional database archive table<\/li>\n\n\n\n
      • Automation and event hooks<\/li>\n<\/ul>\n\n\n\n

        Archive table (optional):<\/p>\n\n\n\n

        {wp_prefix}meshtastic_archive\n<\/code><\/pre>\n\n\n\n
        Messages are normalized once and reused across the system.<\/p>\n\n\n\n
        \n\n\n\n
        NodeDB Cache (Optional)<\/h3>\n\n\n\n
        Lightweight, in-memory cache of node metadata:<\/p>\n\n\n\n
          \n
        • Node ID<\/li>\n\n\n\n
        • Node name<\/li>\n\n\n\n
        • Last seen timestamp<\/li>\n\n\n\n
        • Position (if available)<\/li>\n<\/ul>\n\n\n\n
          Used to enrich messages at render time. Stored as a WordPress option and rebuilt dynamically.<\/p>\n\n\n\n
          \n\n\n\n
          Shortcode and Rendering Layer<\/h3>\n\n\n\n
          Responsible for:<\/p>\n\n\n\n
            \n
          • Rendering live or archived data<\/li>\n\n\n\n
          • Tables, logs, charts, maps, and node summaries<\/li>\n\n\n\n
          • Live Refresh and timed refresh modes<\/li>\n\n\n\n
          • Theme-aware output<\/li>\n<\/ul>\n\n\n\n
            Rendering never talks directly to MQTT.<\/p>\n\n\n\n
            \n\n\n\n
            Automation Layer<\/h3>\n\n\n\n
            Rule-based engine that evaluates normalized messages and triggers actions such as:<\/p>\n\n\n\n
              \n
            • Email notifications<\/li>\n\n\n\n
            • Webhooks<\/li>\n\n\n\n
            • PHP callbacks<\/li>\n<\/ul>\n\n\n\n
              Rules are evaluated after normalization and before rendering.<\/p>\n\n\n\n
              \n\n\n\n
              REST API Layer<\/h3>\n\n\n\n
              Exposes read and write access for:<\/p>\n\n\n\n
                \n
              • JavaScript dashboards<\/li>\n\n\n\n
              • External systems<\/li>\n\n\n\n
              • Headless or hybrid front ends<\/li>\n<\/ul>\n\n\n\n
                All REST responses are derived from the same normalized message pool.<\/p>\n\n\n\n
                \n\n\n\n
                2) MQTT Message Normalization<\/h2>\n\n\n\n
                All inbound MQTT messages are converted into a common PHP array before use.<\/p>\n\n\n\n
                [\n  'topic'       => 'msh\/2\/e\/nodedata',\n  'timestamp'   => 1730828392,     \/\/ UNIX seconds (UTC)\n  'node_id'     => '2',\n  'node_name'   => 'FieldNode02',  \/\/ via NodeDB or payload\n  'text'        => 'Hello from Node 2',\n  'rssi'        => -67,\n  'snr'         => 9.5,\n  'battery'     => 3.81,\n  'temperature' => 22.4,\n  'raw'         => '{ ...original JSON... }'\n]\n<\/code><\/pre>\n\n\n\n
                Notes:<\/p>\n\n\n\n
                  \n
                • Unknown or custom fields are preserved<\/li>\n\n\n\n
                • Telemetry, position, and vendor-specific fields pass through untouched<\/li>\n\n\n\n
                • Normalization happens exactly once per message<\/li>\n<\/ul>\n\n\n\n
                  \n\n\n\n
                  3) Shortcode Reference<\/h2>\n\n\n\n
                  Universal shortcode<\/h3>\n\n\n\n
                  [mesh_plug_display]\n<\/code><\/pre>\n\n\n\n
                  Attributes<\/h3>\n\n\n\n
                  Attribute<\/th>Description<\/th>Example<\/th><\/tr><\/thead>
                  topic<\/code><\/td>Topic or wildcard<\/td>msh\/#<\/code><\/td><\/tr>
                  format<\/code><\/td>log, text, table, chart, map, nodes<\/td>format=\"table\"<\/code><\/td><\/tr>
                  limit<\/code><\/td>Max rows or messages<\/td>limit=\"20\"<\/code><\/td><\/tr>
                  order<\/code><\/td>asc or desc<\/td>order=\"desc\"<\/code><\/td><\/tr>
                  filter_field<\/code><\/td>Field name to filter on<\/td>filter_field=\"text\"<\/code><\/td><\/tr>
                  filter_value<\/code><\/td>Match value<\/td>filter_value=\"alert\"<\/code><\/td><\/tr>
                  refresh<\/code><\/td>Auto-refresh interval (seconds)<\/td>refresh=\"10\"<\/code><\/td><\/tr>
                  chart_type<\/code><\/td>line, bar, gauge, scatter<\/td>chart_type=\"line\"<\/code><\/td><\/tr>
                  value_field<\/code><\/td>Numeric field to chart<\/td>value_field=\"temperature\"<\/code><\/td><\/tr>
                  columns<\/code><\/td>Table column list<\/td>timestamp,node_name,rssi<\/code><\/td><\/tr>
                  empty_text<\/code><\/td>Display when no data<\/td>Waiting for data\u2026<\/code><\/td><\/tr>
                  nodedb<\/code><\/td>Enrich with NodeDB<\/td>nodedb=\"on\"<\/code><\/td><\/tr>
                  dedupe<\/code><\/td>Collapse duplicates<\/td>dedupe=\"on\"<\/code><\/td><\/tr>
                  theme<\/code><\/td>light, dark, system<\/td>theme=\"system\"<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                  Maps render automatically when latitude and longitude fields are present and map support is enabled.<\/p>\n\n\n\n
                  \n\n\n\n
                  Shortcode examples<\/h3>\n\n\n\n
                  [mesh_plug_display\n  topic=\"msh\/2\/e\/telemetry\"\n  format=\"chart\"\n  chart_type=\"line\"\n  value_field=\"temperature\"\n  refresh=\"30\"]\n<\/code><\/pre>\n\n\n\n
                  [mesh_plug_display\n  topic=\"msh\/#\"\n  format=\"table\"\n  columns=\"timestamp,node_name,text,rssi\"\n  filter_field=\"text\"\n  filter_value=\"alert\"\n  limit=\"20\"\n  order=\"desc\"\n  nodedb=\"on\"]\n<\/code><\/pre>\n\n\n\n
                  \n\n\n\n
                  4) PHP Hooks and Filters<\/h2>\n\n\n\n
                  4.1 mesh_plug_before_render<\/code><\/h3>\n\n\n\n
                  Filter the message array before rendering.<\/p>\n\n\n\n
                  add_filter('mesh_plug_before_render', function (array $messages, array $atts) {\n    return array_filter($messages, fn($m) => isset($m['rssi']) && $m['rssi'] > -70);\n}, 10, 2);\n<\/code><\/pre>\n\n\n\n
                  \n\n\n\n
                  4.2 mesh_plug_format_message<\/code><\/h3>\n\n\n\n
                  Modify or enrich individual messages.<\/p>\n\n\n\n
                  add_filter('mesh_plug_format_message', function (array $msg) {\n    if (isset($msg['rssi'])) {\n        $msg['signal_quality'] = $msg['rssi'] > -70 ? 'Good' : 'Weak';\n    }\n    return $msg;\n});\n<\/code><\/pre>\n\n\n\n
                  \n\n\n\n
                  4.3 mesh_plug_message<\/code><\/h3>\n\n\n\n
                  Triggered when a new MQTT message is received and normalized.<\/p>\n\n\n\n
                  add_action('mesh_plug_message', function (array $msg) {\n    error_log(\"Node {$msg['node_id']} sent: \" . ($msg['text'] ?? '[no text]'));\n});\n<\/code><\/pre>\n\n\n\n
                  \n\n\n\n
                  4.4 mesh_plug_automation_triggered<\/code><\/h3>\n\n\n\n
                  Runs after an automation rule executes.<\/p>\n\n\n\n
                  add_action('mesh_plug_automation_triggered', function (array $rule, array $result) {\n    \/\/ Inspect success, HTTP status, or error data\n});\n<\/code><\/pre>\n\n\n\n
                  \n\n\n\n
                  5) REST API<\/h2>\n\n\n\n
                  Base path:<\/p>\n\n\n\n
                  \/wp-json\/mesh-plug\/v1\/\n<\/code><\/pre>\n\n\n\n
                  Endpoints<\/h3>\n\n\n\n
                  Endpoint<\/th>Method<\/th>Description<\/th><\/tr><\/thead>
                  \/messages<\/code><\/td>GET<\/td>Recent messages<\/td><\/tr>
                  \/messages\/latest<\/code><\/td>GET<\/td>Latest per topic<\/td><\/tr>
                  \/topics<\/code><\/td>GET<\/td>Active topics with counts<\/td><\/tr>
                  \/automations<\/code><\/td>GET<\/td>Automation rules (redacted)<\/td><\/tr>
                  \/publish<\/code><\/td>POST<\/td>Publish MQTT message (optional)<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                  Example request:<\/p>\n\n\n\n
                  GET \/wp-json\/mesh-plug\/v1\/messages?topic=msh\/2\/e\/telemetry&limit=10\n<\/code><\/pre>\n\n\n\n
                  Authentication<\/h3>\n\n\n\n
                    \n
                  • Nonces required for POST requests<\/li>\n\n\n\n
                  • Default capability: manage_options<\/code> (filterable)<\/li>\n<\/ul>\n\n\n\n
                    \n\n\n\n
                    6) Automation Rule Schema<\/h2>\n\n\n\n
                    Internally stored as structured arrays.<\/p>\n\n\n\n
                    [\n  'id'   => 7,\n  'name' => 'Battery Warning',\n  'topic' => 'msh\/#',\n  'condition' => [\n      'field'    => 'battery',\n      'operator' => '<',\n      'value'    => 3.5\n  ],\n  'actions' => [\n    [\n      'type'    => 'email',\n      'to'      => 'admin@domain.com',\n      'subject' => 'Low Battery {{node_id}}',\n      'body'    => 'Battery: {{battery}}V'\n    ]\n  ]\n];\n<\/code><\/pre>\n\n\n\n
                    Template tokens such as {{battery}}<\/code> and {{node_name}}<\/code> are rendered at runtime.<\/p>\n\n\n\n
                    \n\n\n\n
                    7) JavaScript Front-End API<\/h2>\n\n\n\n
                    Mesh-Plug exposes a minimal browser API for dynamic interfaces.<\/p>\n\n\n\n
                    window.MeshPlug\n<\/code><\/pre>\n\n\n\n
                    Methods<\/h3>\n\n\n\n
                      \n
                    • subscribe(topic, callback)<\/code><\/li>\n\n\n\n
                    • unsubscribe(topic)<\/code><\/li>\n\n\n\n
                    • latest(topic)<\/code><\/li>\n\n\n\n
                    • publish(topic, payload)<\/code> (if enabled)<\/li>\n<\/ul>\n\n\n\n
                      Example:<\/p>\n\n\n\n
                      MeshPlug.subscribe('msh\/#', data => {\n  console.log('New message:', data);\n});\n<\/code><\/pre>\n\n\n\n
                      \n\n\n\n
                      8) PHP Utility Functions<\/h2>\n\n\n\n
                      Fetch messages<\/h3>\n\n\n\n
                      $messages = mesh_plug_get_messages([\n  'topic' => 'msh\/#',\n  'limit' => 10,\n  'order' => 'desc'\n]);\n<\/code><\/pre>\n\n\n\n
                      \n\n\n\n
                      Publish message<\/h3>\n\n\n\n
                      mesh_plug_publish('msh\/local\/toDevice', [\n  'text' => 'Hello from WordPress'\n]);\n<\/code><\/pre>\n\n\n\n
                      Publishing requires broker and plugin write permissions.<\/p>\n\n\n\n
                      \n\n\n\n
                      9) Database Schema (Archive)<\/h2>\n\n\n\n
                      Table:<\/p>\n\n\n\n
                      {wp_prefix}meshtastic_archive\n<\/code><\/pre>\n\n\n\n
                      Column<\/th>Type<\/th>Description<\/th><\/tr><\/thead>
                      id<\/td>BIGINT<\/td>Primary key<\/td><\/tr>
                      topic<\/td>VARCHAR(255)<\/td>MQTT topic<\/td><\/tr>
                      payload<\/td>LONGTEXT<\/td>Raw JSON<\/td><\/tr>
                      timestamp<\/td>DATETIME<\/td>Message time (UTC)<\/td><\/tr>
                      node_id<\/td>VARCHAR(64)<\/td>Node ID<\/td><\/tr>
                      node_name<\/td>VARCHAR(191)<\/td>Node name<\/td><\/tr>
                      rssi<\/td>FLOAT<\/td>Signal strength<\/td><\/tr>
                      battery<\/td>FLOAT<\/td>Battery voltage<\/td><\/tr>
                      hash<\/td>CHAR(40)<\/td>SHA1 for dedupe<\/td><\/tr>
                      created_at<\/td>DATETIME<\/td>Insert time<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                      Recommended indexes: topic<\/code>, timestamp<\/code>, node_id<\/code>, hash<\/code>.<\/p>\n\n\n\n
                      \n\n\n\n
                      10) Security and Best Practices<\/h2>\n\n\n\n
                        \n
                      • Always use credentials on remote brokers<\/li>\n\n\n\n
                      • Prefer TLS (wss:\/\/<\/code>) for public endpoints<\/li>\n\n\n\n
                      • Scope topics tightly in production<\/li>\n\n\n\n
                      • Escape custom output using WordPress helpers<\/li>\n\n\n\n
                      • Limit refresh intervals on high-traffic dashboards<\/li>\n<\/ul>\n\n\n\n
                        \n\n\n\n
                        11) Extending Mesh-Plug<\/h2>\n\n\n\n
                        class My_Custom_Extension {\n    public function __construct() {\n        add_action('mesh_plug_message', [$this, 'process']);\n    }\n\n    public function process(array $msg) {\n        if (!empty($msg['temperature']) && $msg['temperature'] > 30) {\n            wp_mail('alerts@domain.com', 'High Temperature', print_r($msg, true));\n        }\n    }\n}\n\nnew My_Custom_Extension();\n<\/code><\/pre>\n\n\n\n
                        \n\n\n\n
                        12) Debugging and Diagnostics<\/h2>\n\n\n\n
                          \n
                        • Enable WP_DEBUG_LOG<\/code><\/li>\n\n\n\n
                        • Optional constant:<\/li>\n<\/ul>\n\n\n\n
                          define('MESH_PLUG_DEBUG', true);\n<\/code><\/pre>\n\n\n\n
                            \n
                          • Diagnostics UI: Mesh-Plug \u2192 Diagnostics<\/strong><\/li>\n<\/ul>\n\n\n\n
                            If WP-CLI support is enabled:<\/p>\n\n\n\n
                            wp mesh-plug status\nwp mesh-plug subscribe msh\/# --limit=5\nwp mesh-plug publish msh\/test '{\"text\":\"Ping\"}'\n<\/code><\/pre>\n\n\n\n
                            \n\n\n\n
                            13) Compatibility<\/h2>\n\n\n\n
                              \n
                            • PHP: 8.1+<\/li>\n\n\n\n
                            • WordPress: 6.2+<\/li>\n\n\n\n
                            • Charts: Chart.js 4.x<\/li>\n\n\n\n
                            • Brokers: Mosquitto, EMQX, HiveMQ (WS\/WSS)<\/li>\n<\/ul>\n\n\n\n
                              Shortcode and REST contracts are stable across the 0.5.x series.<\/p>\n\n\n\n
                              \n\n\n\n
                              Final Notes<\/h2>\n\n\n\n
                              This reference is intentionally exhaustive. Mesh-Plug is designed to let developers stay inside WordPress<\/strong> while building real-time, mesh-aware systems.<\/p>\n\n\n\n
                              MQTT handles transport; WordPress handles presentation and logic. Mesh-Plug connects the two cleanly.<\/p>\n","protected":false},"excerpt":{"rendered":"
                              Mesh-Plug for WordPress Developer Reference and Integration Guide Updated: January 2026 (v0.5.x) Mesh-Plug bridges Meshtastic networks and MQTT data streams into WordPress, allowing developers to observe, store, enrich, and react to live mesh data using familiar WordPress tools. This document is a technical appendix for developers who want to extend Mesh-Plug beyond the default UI; […]<\/p>\n","protected":false},"author":1,"featured_media":0,"parent":0,"menu_order":0,"comment_status":"closed","ping_status":"closed","template":"","meta":{"footnotes":""},"class_list":["post-64","page","type-page","status-publish","hentry"],"_links":{"self":[{"href":"https:\/\/michaelwinchester.com\/mesh-plug\/wp-json\/wp\/v2\/pages\/64","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/michaelwinchester.com\/mesh-plug\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/michaelwinchester.com\/mesh-plug\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/michaelwinchester.com\/mesh-plug\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/michaelwinchester.com\/mesh-plug\/wp-json\/wp\/v2\/comments?post=64"}],"version-history":[{"count":3,"href":"https:\/\/michaelwinchester.com\/mesh-plug\/wp-json\/wp\/v2\/pages\/64\/revisions"}],"predecessor-version":[{"id":111,"href":"https:\/\/michaelwinchester.com\/mesh-plug\/wp-json\/wp\/v2\/pages\/64\/revisions\/111"}],"wp:attachment":[{"href":"https:\/\/michaelwinchester.com\/mesh-plug\/wp-json\/wp\/v2\/media?parent=64"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}