pnoker
abd826bf6e
Align the four api READMEs with the actual protos: Select*->Get*/List* per the CRUD verb convention, fix api/common->api/center import paths for auth/data, drop the fabricated manager SelectByServiceName RPC, and document the previously omitted auth/data/manager services.
English | 中文 | 日本語 | Tiếng Việt
AI assistants: Read README.ai.md first for a concise, AI-friendly overview of IoT DC3.
IoT DC3 is an open-source distributed IoT platform evolving for AI scenarios.
It covers device connectivity, data collection, operations management, and intelligent analytics for industrial IoT solutions.
🔌 28 access driver modules · 🤖 AI capability integration · ☁️ 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
| Layer | Responsibilities |
|---|---|
| Driver Layer | SDK-based driver development, standard/proprietary device access, southbound data collection, and command execution |
| Data Layer | Device data collection, storage, and query services for real-time and historical data |
| Management Layer | Microservice collaboration core: service registration, device/driver management, command orchestration, configuration governance |
| Application Layer | Data openness, scheduling, alarms, logging, third-party integration, and AI automation |
📖 For full module dependencies and runtime flow, see Modules and Dependencies.
🛠️ 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 iot-dc3-web repository.
📖 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.