Core concepts

This section explains the objects you will meet. Reading it once is enough to follow the rest of the documentation.

Main objects

Object	Purpose	Example
Workspace	The boundary for data and access. Every other object lives inside it. It has a route (a unique slug) that cannot be changed.	cold-storage
Member	A user who joined the workspace with one or more roles.	Andi (Admin), Sari (Operator)
Role	A set of permission blocks (scope, object, actions, allow/deny).	Admin, Operator, Viewer, or custom
Channel	A logical stream on which messages are published. It becomes part of the MQTT topic.	warehouse-telemetry
Device	A piece of equipment that sends or receives messages. It has an ID, a device key, and an optional Serial.	Freezer Room A1 Sensor
Gateway	A special device that represents many sensors behind it.	Building A Gateway
Connection	A device’s permission to publish and/or subscribe to a channel.	A1 → warehouse-telemetry (publish)
Group	A hierarchical grouping of devices and channels, and the vehicle for permission inheritance.	Building A → Floor 1
Rule	A message-processing flow: input, logic, output. The only way to store messages.	Store in Internal DB
Alarm	An event produced by a rule (or a device) for people to handle.	Inlet temperature above limit
Dashboard	A page of widgets for monitoring data.	Warehouse Monitoring
Report	A CSV or PDF report from stored data, optionally scheduled.	Weekly temperature report

Data flow

The journey of a message.

1. A device connects to the broker with username = device ID and password = device key, then publishes to the topic m/<workspace>/c/<channel>[/<subtopic>].
2. The broker checks that the device may publish to that channel (a connection must exist). If not, the connection is dropped.
3. A rule subscribed to that channel (Channel Subscriber) receives the message, runs its logic, and then runs its outputs.
4. The Internal DB output writes the message to the time-series database. From there it can be read in Messages, dashboards, reports, and the API.

No rule, no storage

Celestian does not store messages automatically. If a channel has no storage rule, messages are still received and visible in Live mode, but they do not appear in the Messages table. A channel without a storage rule is marked Not stored, and there is a one-click button to create one.

MQTT topics

m/<workspace>/c/<channel>[/<subtopic>]

<workspace> and <channel> can be a route (readable) or a UUID. The subtopic is free-form and only acts as a label, for example a location name. The sender is not in the topic: the broker records the authenticated device as the publisher, so it cannot be forged through the message body. Details are in Connecting devices (MQTT).

Data formats

Format	Best for	Can be aggregated and charted
SenML (RFC 8428)	Metrics with units, an open standard	Yes
SenFlat v1 and v2	Memory-constrained devices, gateways, history	Yes
Free-form JSON	Any payload	No (view and filter only)

Full explanation: Payload formats.

Access model

A member's effective rights.

• The basic rule is deny by default: without a written permission, access is refused. deny always beats allow.
• You cannot grant a permission you do not hold yourself (anti-escalation).
• A workspace always keeps at least one active Admin.
• A person who is not a member of a workspace gets 404, not 403, so the workspace’s existence does not leak.

Details: Members and roles and the Permission catalog.

Workspace owner and quotas

The creator of a workspace is its owner. The owner may delete the workspace and transfer ownership. The number of workspaces, devices, and channels the owner can create is limited by a quota set by the platform administrator. Other members who create devices in that workspace use the owner’s quota.