Skip to content

RaftStatePublisherSysMod

Jump to bottom
Rob Dobson edited this page Jan 24, 2026 · 6 revisions

StatePublisher SysMod

Overview

The StatePublisher module is responsible for handling the publication of state information from other SysMods. It supports subscriptions, dynamic updates, and efficient data transfer by using a hashing mechanism to detect changes in state that might trigger publishing. The module is highly configurable via JSON, allowing for flexible publication settings.

Any SysMod can be a publisher of state information.

Publication Records

Publication sources are created dynamically when SysMods register as data sources via the registerDataSource API. There is no need to pre-configure publication topics - they are automatically added when a SysMod registers with its unique PubTopic. Each publication source must have a unique topic name.

A SysMod with data to publish must register with the StatePublisher, specifying the PubTopic under which it wants to publish its data, along with message generation and state detection callbacks.

For further information see Registering a Data Source for Publishing

JSON Configuration

The StatePublisher is configured using minimal JSON settings. Publication sources are now created automatically when SysMods register as data sources - there is no need to pre-configure publication topics. Publishing requires explicit subscription via the REST API for ALL interfaces (including BLE and serial). Subscriptions specify publishing rate, trigger type, and minimum time between messages.

See StatePublisher Settings

Example JSON Configuration for StatePublisher

The StatePublisher configuration is minimal - publication topics are added automatically when SysMods register:

"Publish": {
    "enable": 1
}

Note: When a SysMod calls registerDataSource with a topic name, the publication source is automatically created. Clients must explicitly subscribe via the REST API to receive data on any interface (including BLE, WebSocket, and serial).

StatePublisher publishing operation

Once the state change is detected, the system calls the msgGenCB to generate the actual data to be published. This message is then sent through the appropriate communication channel.

Here’s the flow for publishing data:

  1. Check Interface: Before publishing, the system checks whether the specified communication channel is available for sending data.
  2. Generate Message: The msgGenCB is invoked to generate the message content.
  3. Send Data: The message is sent using the CommsCoreIF::outboundHandleMsg function.

Subscription Mechanism

Subscriptions are created and updated through the /subscription REST API endpoint. This allows clients to dynamically subscribe to specific messages based on the publication name, interface, and rate. All publishing now requires explicit subscription - there are no pre-configured automatic publications.

  • Subscription Request: The client sends a request to the /subscription endpoint with the details of the publications they want to subscribe to. The request contains:
    • action: The type of action to perform (only update is provided and this will either update an existing record or create a new one if one matching topic doesn't exist)
    • pubRecs: The publication records to subscribe to, including the topic, rate, and optional trigger and minimum time between messages.

Subscriptions are specific to the communication channel on which the request is made.

Example Subscription Request:

{
    "action": "update",
    "pubRecs": [
        {
            "topic": "devjson",
            "rateHz": 1.0,
            "trigger": "timeorchange",
            "minTimeBetweenMs": 100
        }
    ]
}

Subscription Parameters:

  • topic (required): Topic name to subscribe to (must match a configured publication topic)
  • rateHz (required): Publishing rate in Hz, or 0 to disable the subscription
  • trigger (optional): Override the default trigger type ("change", "time", "timeorchange")
  • minTimeBetweenMs (optional): Minimum interval between messages in milliseconds

Note: For information about the devjson and devbin topics automatically published by DeviceManager, see Device Data Publishing.

Connection State Management

The StatePublisher includes sophisticated connection state tracking and automatic retry logic with progressive backoff:

  • ACTIVE: Publishing normally
  • LOST: Connection lost, attempting fast retry
  • BACKOFF_STAGE_1: Slower retry interval (5 seconds)
  • BACKOFF_STAGE_2: Even slower retry (30 seconds)
  • BACKOFF_STAGE_3: Slowest retry (60 seconds)

When publishing fails, the system tracks consecutive failures and progressively backs off to reduce overhead. When the connection is restored, publishing resumes at the normal rate. This replaces the previous suppression mechanism and provides more robust handling of unreliable connections.

Clone this wiki locally