Core Concepts and Mental Model
To use IoT DC3 well, you need a simple object model in your head. This page gives you that: a one-sentence summary, an entity-relationship diagram, a walk through each object, the often-confused "three layers of configuration," and the tenant boundary that runs through everything. After this, the terminology in the rest of the docs will make sense.
You are here: you've read the platform positioning, and want the concepts straight before getting hands-on. Next, see choose a path by role or jump to Quick Start.
One-Sentence Mental Model
Drivers connect devices, profiles describe capabilities, devices bind profiles, points carry data; the data center stores values and dispatches commands.
Breaking that down: a protocol Driver talks to devices. A Profile describes what a class of similar devices can do (which points, commands, and events they have). A Device is a concrete instance bound to a profile and a driver. A Point is a data item to collect or write. The collected value is a PointValue.
Objects and Relationships
These relationships are fixed: a profile contains multiple points, commands, and events. A device binds to exactly one profile (since Phase-1, Device.profileId is a single foreign key, no longer many-to-many) and one driver. A point produces many point values.
Object by Object
- Driver (
dc3-driver-*): a protocol-adapter service that talks to devices or data sources. On startup it registers itself, plus the configuration items (attributes) it accepts, with the management center. The platform ships 28 built-in drivers covering Modbus, OPC UA, S7, MQTT, and more — see the module map. - Profile: a capability template for similar devices. It records which points this kind of device has, which custom commands it supports, and which events it reports, so devices can reuse it.
- Device: the platform's mirror of a real physical device in the field. It binds to one profile (which sets its points) and one driver (which sets how it communicates).
- Point: a data item. Its key fields are
pointTypeFlag(data type) andrwFlag(read/write direction).
Read/write is decided by the Point itself
Whether a point can be written depends on its rwFlag (READ_ONLY / WRITE_ONLY / READ_WRITE), not on the command table. Writes to a READ_ONLY point are rejected. A point can also carry a unit and a linear conversion (baseValue / multiple) that turns the raw value into an engineering value.
Three Layers of Configuration: Param, Attribute, Config
This is the part people trip over most. IoT DC3 splits "configuration" into three layers, each answering a different question:
| Layer | Object | Question it answers | Source |
|---|---|---|---|
| Business layer Param | CommandParam / EventParam | Which input/output parameters does this command/event have | Defined in the profile model |
| Protocol layer Attribute | DriverAttribute / PointAttribute / CommandAttribute / EventAttribute | Which configuration items does this driver have | Registered from application.yml when the driver starts |
| Instance layer Config | PointAttributeConfigDO, etc. | The concrete values this device fills in for those items | Set by the user for the device/point |
For example, the Modbus driver declares that "a point needs a register address" (the Attribute, registered by the driver), while "device #3's temperature point lives at address 40001" (the Config, the value the device instance supplies). Once this distinction clicks, the "configure point attributes" step in Device Onboarding makes sense.
Data Flow and Command Flow
Around these objects, the platform runs two opposing pipelines. The data flow pulls device values up, stores them, and exposes them for querying. The command flow sends read/write requests back down to devices for execution.
For the full implementation of both pipelines (exchanges, queues, lifecycle, acknowledgements), see the Data Plane and Command Plane.
Tenant Boundary
Business data is isolated by tenant (tenantId). When you call APIs, create devices, query data, or dispatch commands, keep the tenant context consistent. The platform checks the tenant context at the controller layer (requireTenant / filterTenant) — accessing another tenant's records by id or in bulk is treated as not-found (a 404 rather than the data itself). In development the default tenant is usually default; in production it follows your organization and permission model. For how isolation is enforced layer by layer, see Auth · Tenant · RBAC.
Concept Reference
Each core concept has its own entry covering its definition, key fields, relationships, lifecycle, and common pitfalls:
- Profile (Thing Model) — capability template for a class of devices, aggregating points / commands / events
- Device — a platform mirror of one field device
- Driver — a protocol adapter service that talks to devices
- Point — a single data item (a value to read or write)
- Point Value — a snapshot of a point's value at a moment
- Command — trigger a device action (vs. writing a point)
- Event — a business occurrence a device reports
- Attribute & Config — the Param / Attribute / Config layers
- Tenant — the business-data isolation boundary
Further Reading
- Choose a Path by Role — pick a reading order based on your goal
- Device Onboarding — turn the concepts into a real onboarding
- Domain Model — DO/BO/VO layering and field details
- Quick Start — bring up the stack locally