> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# System ($SYS) Topics

> Complete reference for system topics - monitoring, configuration, and controlling the Coreflux MQTT Broker

## Overview

The Coreflux MQTT Broker provides a comprehensive set of `$SYS` topics that enable you to monitor broker status, read configuration, track connections, and access LoT entity code. These topics follow the MQTT standard convention of using the `$SYS` prefix for broker-specific information.

<Warning>
  Topics starting with `$` are special topics in MQTT. They are not included when subscribing with wildcards like `#` at the root level. You must explicitly subscribe to them.
</Warning>

## Why Use \$SYS Topics?

When managing an MQTT broker in production, you need visibility into what's happening inside. How many clients are connected? What version is running? What LoT entities are deployed? System topics give you this insight without external monitoring tools.

<Tip>
  **Think of \$SYS topics as the broker's dashboard in MQTT form.** Instead of a web interface, you get live data streams—subscribe to them like any other topic and watch the broker's vital signs in real-time.
</Tip>

***

## Topic Hierarchy & Quick Reference

System topics in Coreflux follow a hierarchical structure:

```
$SYS/
├── Coreflux/
│   ├── Command                    # Send commands to broker
│   ├── Command/Output             # Receive command responses
│   ├── Config/New                 # Publish new configuration
│   ├── Version                    # Broker version info
│   ├── License                    # License information
│   ├── Resources/                 # Memory usage stats
│   ├── Config                     # Current configuration
│   ├── Config/Users               # User list
│   ├── Config/Rules               # Rules count
│   ├── Comms/
│   │   ├── Sessions               # Active sessions
│   │   ├── Clients                # Connected clients
│   │   └── Logins                 # Login events
│   ├── Actions/<name>             # Action LoT code
│   ├── Models/<name>              # Model LoT code
│   ├── Routes/<name>              # Route LoT code
│   └── Rules/<name>               # Rule LoT code
└── <OS>/                          # Platform-specific (e.g., Linux-x64, Windows-x64)
    ├── Python/Info                # Python integration status
    └── Comms/
        ├── TCP/Listeners          # Active TCP listeners
        ├── TCP/ActiveConnections  # TCP connections
        └── UDP/                    # UDP statistics
```

### Read-Only Topics

| Topic                          | Content                      |
| ------------------------------ | ---------------------------- |
| `$SYS/Coreflux/Version`        | Broker version JSON          |
| `$SYS/Coreflux/License`        | License status               |
| `$SYS/Coreflux/Config`         | Current configuration        |
| `$SYS/Coreflux/Config/Users`   | User list (passwords masked) |
| `$SYS/Coreflux/Comms/Sessions` | Active sessions              |
| `$SYS/Coreflux/Comms/Clients`  | Connected clients            |
| `$SYS/Coreflux/Actions/{name}` | Action LoT code              |
| `$SYS/Coreflux/Models/{name}`  | Model LoT code               |
| `$SYS/Coreflux/Routes/{name}`  | Route LoT code               |
| `$SYS/Coreflux/Rules/{name}`   | Rule LoT code                |

### Writable Topics

| Topic                      | Purpose              |
| -------------------------- | -------------------- |
| `$SYS/Coreflux/Command`    | Send broker commands |
| `$SYS/Coreflux/Config/New` | Update configuration |

***

## In This Page

| Section                                         | Description                                    |
| ----------------------------------------------- | ---------------------------------------------- |
| [Command Topics](#command-topics)               | Send commands and receive responses            |
| [LoT Entity Topics](#lot-entity-topics)         | Access Actions, Models, Routes, and Rules code |
| [Broker Information](#broker-information)       | Version, license, and resource usage           |
| [Configuration Topics](#configuration-topics)   | Current config, users, and rules               |
| [Connection Monitoring](#connection-monitoring) | Sessions, clients, and logins                  |
| [Platform Topics](#platform-topics)             | OS-specific communication and Python info      |

***

## Command Topics

Send commands to the broker and receive responses through a publish/subscribe pattern.

<Steps>
  <Step title="Subscribe to output">
    Using any MQTT client (such as MQTT Explorer), subscribe to `$SYS/Coreflux/Command/Output` to receive responses
  </Step>

  <Step title="Publish command">
    Publish your command to `$SYS/Coreflux/Command`
  </Step>

  <Step title="Receive response">
    The broker publishes the result to the output topic
  </Step>
</Steps>

### \$SYS/Coreflux/Command

Publish command strings to this topic to control the broker.

**Topic:** `$SYS/Coreflux/Command`

**Direction:** Client → Broker

**Example:**

Use any MQTT client (such as MQTT Explorer) to publish to this topic. The message payload contains the command to execute:

| Field       | Value                                                                                                             |
| ----------- | ----------------------------------------------------------------------------------------------------------------- |
| **Topic**   | `$SYS/Coreflux/Command`                                                                                           |
| **Payload** | `-addAction DEFINE ACTION Heartbeat ON EVERY 10 SECONDS DO PUBLISH TOPIC "system/heartbeat" WITH TIMESTAMP "UTC"` |
| **Auth**    | Use `root` credentials                                                                                            |

### \$SYS/Coreflux/Command/Output

Subscribe to receive responses from commands.

**Topic:** `$SYS/Coreflux/Command/Output`

**Direction:** Broker → Client

**Example responses:**

```
Action 'Heartbeat' added successfully
```

```
Failed to add action: Syntax error at line 3
```

***

## LoT Entity Topics

These topics contain the actual LoT code for each entity running in the broker.

<Tip>
  Subscribe to these topics to retrieve the current LoT code for any Action, Model, Route, or Rule. This is useful for backup, debugging, or understanding what's running in the broker.
</Tip>

### \$SYS/Coreflux/Actions/\{ActionName}

Contains the LoT code for the specified action.

**Topic Pattern:** `$SYS/Coreflux/Actions/{ActionName}`

**Payload:** The complete LoT action definition

**Example:**

Subscribe to a specific action using MQTT Explorer or any MQTT client:

| Field     | Value                             |
| --------- | --------------------------------- |
| **Topic** | `$SYS/Coreflux/Actions/Heartbeat` |

**Payload received:**

```lot theme={null}
DEFINE ACTION Heartbeat
ON EVERY 10 SECONDS DO
    PUBLISH TOPIC "system/heartbeat" WITH TIMESTAMP "UTC"
```

### \$SYS/Coreflux/Models/\{ModelName}

Contains the LoT code for the specified model.

**Topic Pattern:** `$SYS/Coreflux/Models/{ModelName}`

### \$SYS/Coreflux/Routes/\{RouteName}

Contains the LoT code for the specified route.

**Topic Pattern:** `$SYS/Coreflux/Routes/{RouteName}`

### \$SYS/Coreflux/Rules/\{RuleName}

Contains the LoT code for the specified rule.

**Topic Pattern:** `$SYS/Coreflux/Rules/{RuleName}`

#### Subscribe to All Entities

Use your MQTT client to subscribe to these wildcard topics:

| Entity Type | Topic Pattern             |
| ----------- | ------------------------- |
| All Actions | `$SYS/Coreflux/Actions/#` |
| All Models  | `$SYS/Coreflux/Models/#`  |
| All Routes  | `$SYS/Coreflux/Routes/#`  |
| All Rules   | `$SYS/Coreflux/Rules/#`   |

***

## Broker Information

### \$SYS/Coreflux/Version

Broker version and build information.

**Topic:** `$SYS/Coreflux/Version`

**Payload:**

```json theme={null}
{
  "version": {
    "major": 0,
    "minor": 0,
    "patch": 0,
    "branch": "release",
    "os": "Linux-x64",
    "stage": "stable",
    "timestamp": "2025-09-12T16:41:00Z",
    "notes": "New Features:\n- Python integration for LoT\n"
  }
}
```

### \$SYS/Coreflux/License

License status and feature availability.

**Topic:** `$SYS/Coreflux/License`

**Payload:**

```json theme={null}
{
  "LicensedTo": "N/A",
  "IsActive": false,
  "Features": {
    "EnableLOTAdvancedFunctions": false,
    "EnableRouteAdvancedTiers": false,
    "EnableCluster": false
  }
}
```

### \$SYS/Coreflux/Resources

Memory usage statistics for the broker.

| Topic                                     | Description                    |
| ----------------------------------------- | ------------------------------ |
| `$SYS/Coreflux/Resources/MemoryInfoTotal` | Total available memory (bytes) |
| `$SYS/Coreflux/Resources/MemoryInfoUsage` | Current memory usage (bytes)   |

***

## Configuration Topics

### \$SYS/Coreflux/Config

The current broker configuration as JSON.

**Topic:** `$SYS/Coreflux/Config`

**Payload:**

```json theme={null}
{
  "Name": "Coreflux DataHub",
  "Port": 1883,
  "TlsPort": 8883,
  "WebsocketPortTls": 443,
  "WebsocketPort": 5000,
  "FullDebugLog": false,
  "AnonymousLogin": true,
  "BindIPForMQTT": "0.0.0.0",
  "BindIPForMQTTwithTls": "0.0.0.0",
  "BindIpForWebSockets": "0.0.0.0",
  "BindIpForWebSocketsTls": "0.0.0.0",
  "ServerCertificatePath": null,
  "ServerCertificateKeyPath": null,
  "ServerCertificatePassword": null,
  "RootCACertificatePath": null,
  "ClientCertificateSourcePath": null,
  "ClientCertificationValidation": false,
  "ClientCertificateRevocationListPath": null,
  "CheckCertificateRevokationList": false,
  "CheckCertificateChainValidation": false,
  "ResendRetainTopics": false
}
```

<Note>
  To update the configuration, publish to `$SYS/Coreflux/Config/New`. See [Broker Configuration](/mqtt-broker/configuration) for details.
</Note>

### \$SYS/Coreflux/Config/Users

List of configured users (passwords are masked).

**Topic:** `$SYS/Coreflux/Config/Users`

**Payload:**

```json theme={null}
[
  {
    "UserName": "root",
    "Password": "********",
    "AllowedBaseTopic": "",
    "AllowedSystemConfiguration": true,
    "AllowedAssetManipulation": false,
    "AllowedUserManagement": false,
    "AllowedLogManagement": false
  }
]
```

#### User Permission Fields

| Field                        | Description                         |
| ---------------------------- | ----------------------------------- |
| `AllowedBaseTopic`           | Base topic restriction for the user |
| `AllowedSystemConfiguration` | Can modify broker configuration     |
| `AllowedAssetManipulation`   | Can add/remove LoT entities         |
| `AllowedUserManagement`      | Can manage other users              |
| `AllowedLogManagement`       | Can access and manage logs          |

### \$SYS/Coreflux/Config/Rules

Information about configured rules.

**Topic:** `$SYS/Coreflux/Config/Rules`

***

## Connection Monitoring

### \$SYS/Coreflux/Comms/Sessions

Active MQTT sessions.

**Topic:** `$SYS/Coreflux/Comms/Sessions`

**Payload:**

```json theme={null}
[
  {
    "CreatedTimestamp": "2025-12-27T00:01:36.5008146Z",
    "DisconnectedTimestamp": null,
    "ExpiryInterval": 0,
    "Id": "mqtt-explorer-274f0040",
    "Items": {},
    "PendingApplicationMessagesCount": 0
  }
]
```

### \$SYS/Coreflux/Comms/Clients

Detailed information about connected clients.

**Topic:** `$SYS/Coreflux/Comms/Clients`

**Payload:**

```json theme={null}
[
  {
    "BytesReceived": 173,
    "BytesSent": 3943557,
    "ConnectedTimestamp": "2025-12-27T00:01:36.5008189Z",
    "Endpoint": "172.17.0.1:52256",
    "Id": "mqtt-explorer-274f0040",
    "LastNonKeepAlivePacketReceivedTimestamp": "2025-12-27T00:01:36.5168761Z",
    "LastPacketReceivedTimestamp": "2025-12-27T00:51:56.2986984Z",
    "LastPacketSentTimestamp": "2025-12-27T00:51:36.9346062Z",
    "ProtocolVersion": 4,
    "ReceivedApplicationMessagesCount": 16070,
    "ReceivedPacketsCount": 16124,
    "SentApplicationMessagesCount": 0,
    "SentPacketsCount": 53,
    "Session": {
      "CreatedTimestamp": "2025-12-27T00:01:36.5008146Z",
      "DisconnectedTimestamp": null,
      "ExpiryInterval": 0,
      "Id": "mqtt-explorer-274f0040",
      "Items": {},
      "PendingApplicationMessagesCount": 0
    }
  }
]
```

#### Client Fields

| Field                              | Description                                   |
| ---------------------------------- | --------------------------------------------- |
| `BytesReceived`                    | Total bytes received from client              |
| `BytesSent`                        | Total bytes sent to client                    |
| `ConnectedTimestamp`               | When the client connected                     |
| `Endpoint`                         | Client IP and port                            |
| `Id`                               | Client ID                                     |
| `ProtocolVersion`                  | MQTT protocol version (3=3.1, 4=3.1.1, 5=5.0) |
| `ReceivedApplicationMessagesCount` | Messages received                             |
| `SentApplicationMessagesCount`     | Messages sent to client                       |

### \$SYS/Coreflux/Comms/Logins

Login event information.

**Topic:** `$SYS/Coreflux/Comms/Logins`

**Example Payload:**

```
ClientId = lotvstudio-a6kjtbkwp, Endpoint = 172.17.0.1:53454, Username = root, Password = ******, CleanSession = True, ReasonCode = Success
```

***

## Platform Topics

These topics are prefixed with the operating system identifier (e.g., `Linux-x64`, `Windows-x64`).

<Note>
  The OS prefix matches your broker's platform. Check `$SYS/Coreflux/Version` to see the current OS identifier.
</Note>

### \$SYS/{OS}/Python/Info

Python integration status and available scripts.

**Topic:** `$SYS/Linux-x64/Python/Info` (example for Linux)

**Payload:**

```json theme={null}
{
  "Available": true,
  "Version": "3.11.2 (main, Apr 28 2025, 14:11:48) [GCC 12.2.0]",
  "Scripts": []
}
```

### \$SYS/{OS}/Comms/TCP/Listeners

Active TCP listeners (ports the broker is listening on).

**Topic:** `$SYS/Linux-x64/Comms/TCP/Listeners`

**Payload:**

```json theme={null}
[
  {"Address": "0.0.0.0", "Port": "1883"},
  {"Address": "0.0.0.0", "Port": "80"},
  {"Address": "0.0.0.0", "Port": "443"},
  {"Address": "0.0.0.0", "Port": "5000"},
  {"Address": "::", "Port": "80"},
  {"Address": "::", "Port": "443"},
  {"Address": "::", "Port": "3000"}
]
```

### \$SYS/{OS}/Comms/TCP/ActiveConnections

Currently active TCP connections.

**Topic:** `$SYS/Linux-x64/Comms/TCP/ActiveConnections`

**Payload:**

```json theme={null}
[
  {
    "State": "Established",
    "LocalEndPoint": "172.17.0.2:5000",
    "RemoteEndPoint": "172.17.0.1:52256"
  }
]
```

### \$SYS/{OS}/Comms/UDP

UDP communication statistics.

**Topic:** `$SYS/Linux-x64/Comms/UDP`

***

## Access Control

By default, only authenticated users with appropriate permissions can access `$SYS` topics:

```lot theme={null}
DEFINE RULE MonitoringAccess
    FOR USER "monitor-client"
    ALLOW SUBSCRIBE TO "$SYS/Coreflux/#"
    DENY PUBLISH TO "$SYS/Coreflux/Command"
```

<Warning>
  Be careful when granting access to `$SYS/Coreflux/Command`. Users with publish access can execute administrative commands on the broker.
</Warning>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Broker Configuration" icon="gear" href="/mqtt-broker/configuration">
    Configure your broker settings
  </Card>

  <Card title="Broker Commands" icon="terminal" href="/mqtt-broker/commands">
    Learn all available broker commands
  </Card>
</CardGroup>