pnoker
5bcd128db8
The driver register gRPC service has no HTTP security context, so BaseController.async never binds a tenant before its queries run. After D-1 installed the fail-closed TenantLineInnerInterceptor, the dc3_driver / dc3_driver_attribute / dc3_point_attribute / dc3_command_attribute / dc3_event_attribute queries in this path would raise TenantNotScopedException and break driver registration. Bind the driver's tenant (resolved from the gRPC payload's tenant code via TenantFacade, then carried by DriverBO.tenantId) for the duration of each method and clear it in a finally block to avoid leaking the ThreadLocal onto the gRPC thread pool. All queries here are scoped to a single tenant, so setTenantId is correct (not runIgnore).
English | 中文 | 日本語 | Tiếng Việt
AI assistants: Read README.ai.md first for a concise, AI-friendly overview of IoT DC3.
IoT DC3 — the open-source industrial IoT platform that lets large language models operate your devices directly.
Native Spring AI integration · Natural-language operations · 28 ready-to-use drivers
🔌 Multi-protocol connectivity · 🤖 AI Agentic Center · ☁️ Cloud-native microservices
📸 Product Preview
| 📸 Platform Overview | 📸 Device Management | 📸 AI Chat |
|---|---|---|
Home / Dashboard System overview · Online device metrics · Data trend charts |
Device Management Device list · Online status · Search and filtering |
AI Chat Natural-language device operations · Data queries · Intelligent analysis |
✨ Core Features
🔌 Multi-Protocol Device Connectivity
IoT DC3 includes 28 access driver modules for industrial automation, IoT communication, data bridging, basic communication, and simulation/debugging scenarios, reducing the cost of connecting common devices and data sources:
| Category | Driver Modules |
|---|---|
| 🏭 Industrial protocols | Modbus TCP · Modbus RTU · OPC UA · OPC DA · Siemens S7 · BACnet/IP · EtherNet/IP · Omron FINS · Mitsubishi MELSEC · IEC 60870-5-104 · SL651 · DLMS |
| 📡 IoT protocols | MQTT · CoAP · LwM2M · HTTP · BLE · Zigbee |
| 🗄️ Data bridging | MySQL · PostgreSQL · Oracle · SQL Server |
| 🔧 Basic communication and NMS | TCP/UDP · Serial · SNMP · CAN |
| 🧪 Simulation and debugging | Virtual · Listening Virtual |
The Driver SDK supports fast development of custom protocol drivers and registration into the runtime platform.
🤖 AI Capability Integration
The agentic center is built on Spring AI and connects large language models into IoT operations workflows:
- Natural-language device operations - LLMs can query devices, read/write points, and execute commands through Tool Calling
- Intelligent alarm analysis - AI assists with root-cause analysis and response suggestions
- Data insights - Query device data in natural language and generate visual charts
- Multi-model support - Compatible with OpenAI API-style providers and mainstream models such as GPT, Claude, DeepSeek, and Qwen
- Conversation memory - Multi-turn conversations and context memory persisted to the database
🏗️ Cloud-Native Microservices
Distributed microservice architecture based on Spring Boot 4 + Spring Cloud 2025:
- Service governance - Spring Cloud Gateway as the unified entrypoint, with static routes and flexible environment variables
- Efficient communication - gRPC service calls with Protobuf serialization
- Horizontal scaling - Stateless design for scaling individual services by workload
- Resilience - Replaceable service nodes and fault isolation
📊 Real-Time Data Engine
- Data collection - Drivers collect device telemetry and send it asynchronously through RabbitMQ
- Time-series storage - Efficient queries for real-time and historical data
- Rule engine - Flexible alarm rules with multi-level alarms and notifications
- Event traceability - Full command and event history
🔐 Enterprise Security and Multi-Tenancy
- Tenant isolation - Tenant-level isolation across database, cache, and API paths
- Authentication and authorization - JWT + Spring Security with RBAC
- Transport encryption - TLS/SSL communication support
- Audit tracking - User operation and system event logs
🧩 Developer Friendly
- Driver SDK - A complete driver development toolkit. See the Driver Authoring Guide
- Separated frontend and backend - Vue 3 + TypeScript frontend, RESTful and gRPC APIs
- Containerized deployment - One-command startup with Podman / Docker Compose, with a path toward Kubernetes and other container platforms
- Complete documentation - Online docs, quickstart guide, and troubleshooting guide
⚡ Quick Start
Prerequisites
| Dependency | Version |
|---|---|
| Java (JDK) | 21+ |
| Maven | 3.9+ |
| Podman or Docker | Latest stable |
Start in Three Steps
① Clone the repository
git clone https://github.com/pnoker/iot-dc3.git
cd iot-dc3
② Start base dependencies (PostgreSQL + RabbitMQ)
# Global registry
make up-db
# Mainland China users (Alibaba Cloud registry)
make up-db-cn
③ Load local environment variables, build, and start
source dc3/env/dev.env.sh
mvn -s .mvn/settings.xml clean package
dc3/env/dev.env.sh points local Java processes to the PostgreSQL, RabbitMQ, and gRPC ports published on localhost.
Run the following java -jar commands in the same terminal session.
Start services in order:
java -jar dc3-gateway/target/dc3-gateway.jar # API Gateway
java -jar dc3-center/dc3-center-auth/target/dc3-center-auth.jar # Auth Center
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar # Manager Center
java -jar dc3-center/dc3-center-data/target/dc3-center-data.jar # Data Center
java -jar dc3-center/dc3-center-agentic/target/dc3-center-agentic.jar # Agentic Center
java -jar dc3-driver/dc3-driver-virtual/target/dc3-driver-virtual.jar # Virtual Driver for demos
📖 For full local setup, see the Quickstart and Environment Variables docs.
🔧 More startup options (optional dependencies, single-service startup, environment variables)
Start optional infrastructure (EMQX, ELK/APM, Prometheus, Grafana, etc.):
make up-optional-cn # Start optional dependencies
make up-db-cn && make up-optional-cn && make up-dev-cn # Start all dependencies
Start selected services (useful for frontend/API testing):
make up SERVICES=agentic REGISTRY=cn # Single service
make up SERVICES="gateway agentic" REGISTRY=cn # Multiple services
make up GROUP=core REGISTRY=cn # Core service group
make up GROUP=drivers REGISTRY=cn # Driver service group
make logs SERVICES="gateway agentic" # Follow logs
Compose environment overrides:
cp .env.example .env # Copy the template
The root .env file is used for Compose variable interpolation, such as image registry, image tag, and published ports.
Application runtime variables are configured in dc3/env/dev.env. See
the environment documentation.
🏗️ Architecture Overview
Architecture at a Glance
Six-layer microservice architecture at a glance: clients → gateway → four center services → message bus → 28 protocol drivers → field devices. PostgreSQL (TimescaleDB + pgvector + AGE) persistence and optional observability stack (ELK + Prometheus + Grafana) laid out in one view.
Four-Layer Reference Architecture Mapping
Industry-standard IoT four-layer reference — Application, Platform, Network, Perception — plus security as a cross-cutting concern.
| Layer | IoT Reference Responsibilities | DC3 Implementation |
|---|---|---|
| Application | Operations · Alarms · Analytics · AIoT | Operations · Agentic Center · MCP |
| Platform | Device mgmt · Storage · Rules & compute | Center services · Data plane · TimescaleDB |
| Network | Fieldbus · IoT protocols · Wireless / WAN | 28 protocol drivers · Gateway · RabbitMQ |
| Perception | Sensing · Auto-ID · Actuators | Profile · Device · Point |
🧱 Design principles — cross-service calls always go through Facade interfaces; the DO/BO/VO three-tier model keeps persistence, business, and API shapes strictly separated; and tenant isolation runs end to end across database, cache, and API paths. Clear boundaries that scale across services and teams.
📖 For the full architecture documentation, see System Architecture Overview.
🛠️ Technology Stack
| Category | Technologies |
|---|---|
| Language and frameworks | Java 21 · Spring Boot 4 · Spring Cloud 2025 · Spring AI 2.0 |
| Data, cache, and scheduling | PostgreSQL · Caffeine · MyBatis-Plus · Quartz |
| Messaging and communication | RabbitMQ · gRPC · MQTT (Paho + EMQX) · Protobuf |
| Security and authentication | Spring Security · JWT · BouncyCastle |
| Observability | Micrometer · Prometheus · Grafana · ELK |
| Frontend | Vue 3 · TypeScript 6 · Vite 8 · Element Plus · AntV G2/G6 |
| Desktop | Tauri 2 |
| Deployment | Podman · Docker Compose |
💡 Frontend source code is in the
dc3-web/directory of this repository (the standaloneiot-dc3-webrepo is archived).
📖 Documentation and Community
| Resource | Link |
|---|---|
| 📚 Online docs | pnoker.github.io/iot-dc3 |
| 🚀 Quickstart | Quickstart Guide |
| 🏗️ Architecture | Modules and Dependencies |
| 🔧 Driver development | Driver Authoring Guide |
| 🐛 Troubleshooting | Troubleshooting |
| 📋 Changelog | Release Changelog |
| 🐛 Issue feedback | GitHub Issues |
| 🇨🇳 Gitee mirror | Gitee GVP Project |
🌍 Use Cases
| 🏭 | Smart Factory | Production-line device monitoring, process parameter collection, predictive maintenance, and OEE analysis |
| ⚡ | Energy Monitoring | Remote metering for power, water, and gas; energy trend analysis; anomaly alarms |
| 🌾 | Smart Agriculture | Greenhouse monitoring, automatic irrigation control, pest and disease warnings, yield forecasting |
| 🏙️ | Smart City | Streetlight management, environmental monitoring, municipal facility operations, safety monitoring |
🤝 Contributing
Contributions of all kinds are welcome. Please follow this workflow:
- Fork and branch - Create a branch from
main, using the formatfeature/your_name/feature_description(for example:feature/pnoker/mqtt_driver) - Develop and commit - Complete your changes on the new branch and follow the Conventional Commits specification
- Open a PR - Submit a Pull Request to the
developbranch for maintainer review and merge
📄 License
IoT DC3 is open source under the AGPL 3.0 license.
- ✅ Personal learning, research, and internal use - Free
- ✅ Modify the code and open source your changes - Welcome
- ⚠️ Offering it as a commercial service to third parties without open-sourcing modifications - Requires a commercial license
For commercial licensing details, see LICENSE.txt.