opensource/iot-dc3
3
0
Fork 0
mirror of https://gitee.com/pnoker/iot-dc3.git synced 2026-09-01 15:29:04 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(readme): refresh module documentation

Browse Source
This commit is contained in:
hongyuan.zhang
2026-08-11 22:58:30 +08:00
parent 9099ad093d
commit 6b37cb5ccd
75 changed files with 1360 additions and 1744 deletions
Download Patch File Download Diff File Expand all files Collapse all files
dc3-api/README.md
+36
View File
@@ -0,0 +1,36 @@
# DC3 API
`dc3-api` owns the protobuf contracts shared between IoT DC3 processes. It contains generated-contract modules only;
business logic belongs in `dc3-common-*` implementations.
## Modules
| Module | Contract surface | Primary consumers |
|---|---|---|
| `dc3-api-auth` | tenant, user, token, permission, resource registry, MCP runtime | gateway and center services |
| `dc3-api-data` | point values, command history, event history | manager, drivers, and data clients |
| `dc3-api-driver` | driver registration and driver-scoped device/point metadata | protocol drivers |
| `dc3-api-manager` | manager-scoped driver, device, profile, point, command, and event metadata | data and other centers |
Proto sources live under each module's `src/main/protobuf/` directory. Generated Java sources are build artifacts and
must not be edited directly.
## Contract changes
1. Update the affected `.proto` files.
2. Preserve field numbers and RPC compatibility where practical.
3. Compile the affected module to regenerate Java sources.
4. Update server implementations, builders, and clients together.
5. Verify tenant propagation, `GrpcR` error handling, and single/list cardinality naming.
```bash
mvn -s .mvn/settings.xml -q -f dc3-api/pom.xml compile
```
Use `GetXxx` for single results and `ListXxx` for collections, pages, or maps. Do not reintroduce legacy `SelectXxx`
RPC names.
## Documentation ownership
Each child README documents its current services and messages. The `.proto` files remain the authoritative source for
method names, request/response types, and field definitions.
dc3-api/dc3-api-auth/README.md
+26 -187
View File
@@ -1,202 +1,41 @@
# DC3 API Auth
## Overview
`dc3-api-auth` defines the authentication and authorization gRPC contracts. Generated Java types use the
`io.github.pnoker.api.center.auth` package; proto sources live under `src/main/protobuf/api/common/auth/`.
`dc3-api-auth` provides gRPC service definitions for authentication and authorization in the IoT DC3 platform. It
defines the interfaces for tenant management, user authentication, token validation, and local credential lookup.
## Services
## Module Information
| Service | RPCs | Purpose |
|---|---|---|
| `TenantApi` | `GetByCode` | resolve tenant metadata |
| `UserApi` | `GetById`, `GetByPrincipalId` | resolve user identity |
| `TokenApi` | `CheckValid` | validate login/token material |
| `LocalCredentialApi` | `GetByLoginName` | resolve local credentials |
| `PermissionApi` | `ListPermissionCodes` | resolve effective permission codes |
| `ResourceRegistryApi` | `Sync` | synchronize annotated API/menu resources |
| `McpRuntimeApi` | `Introspect`, `ListTools`, `ResolveTool`, `AuthorizeToolCall`, `Audit` | authorize and audit MCP tools |
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-api-auth
- **Version**: 2026.5.22
- **Package**: `io.github.pnoker.api.center.auth`
Every response uses a contract-specific wrapper containing `GrpcR`. Callers must inspect the result envelope before
reading response data.
## Proto Definitions
## Consumers and implementation
### tenant.proto
- `dc3-common-auth` implements the servers as Spring `@Service` beans extending generated `*ImplBase` classes.
- `dc3-common-facade-grpc` creates shared blocking stubs and exposes transport-independent auth facades.
- `dc3-gateway` uses auth facades for ingress authentication and authorization.
Defines tenant-related RPC calls and data structures.
Business code should depend on facade interfaces instead of generated stubs unless it is itself a transport adapter.
**Service**: `TenantApi`
## Build and Verification
- `GetByCode` - Query tenant information by tenant code
**Key Messages**:
- `GrpcCodeQuery` - Request wrapper for tenant code queries
- `GrpcRTenantDTO` - Response wrapper containing tenant information
- `GrpcTenantDTO` - Tenant data structure (name, code, enable flag)
### token.proto
Defines token validation RPC calls and data structures.
**Service**: `TokenApi`
- `CheckValid` - Validate authentication tokens
**Key Messages**:
- `GrpcLoginQuery` - Request wrapper with login credentials (tenant, name, password, token)
- `GrpcRTokenDTO` - Response wrapper with validation result
### user.proto
Defines user-related RPC calls and data structures.
**Service**: `UserApi`
- `GetById` - Query user information by user ID
- `GetByPrincipalId` - Query user information by principal ID
**Key Messages**:
- `GrpcIdQuery` - Request wrapper for user ID queries
- `GrpcRUserDTO` - Response wrapper containing user information
- `GrpcUserDTO` - User data structure (nickname, username, phone, email)
### local_credential.proto
Defines local credential lookup RPC calls and data structures.
**Service**: `LocalCredentialApi`
- `GetByLoginName` - Query local credential information by login name
**Key Messages**:
- `GrpcLoginNameQuery` - Request wrapper for login-name queries
- `GrpcRLocalCredentialDTO` - Response wrapper containing local credential information
- `GrpcLocalCredentialDTO` - Local credential data structure (login name, principal ID)
### permission.proto
Defines permission lookup RPC calls for RBAC.
**Service**: `PermissionApi`
- `ListPermissionCodes` - List the permission codes granted to a principal
### resource_registry.proto
Defines resource registry synchronization RPC calls.
**Service**: `ResourceRegistryApi`
- `Sync` - Synchronize API/menu resource definitions into the registry
### mcp_runtime.proto
Defines MCP (Model Context Protocol) runtime RPC calls for AI tool integration.
**Service**: `McpRuntimeApi`
- `Introspect` - Introspect an MCP connection
- `ListTools` - List the tools exposed by an MCP connection
- `ResolveTool` - Resolve a tool definition by name
- `AuthorizeToolCall` - Authorize an MCP tool invocation
- `Audit` - Record an MCP tool-call audit entry
## Dependencies
This module depends on common proto definitions:
- `api/common/base.proto` - Base entity fields (ID, timestamps)
- `api/common/r.proto` - Common response wrapper
## Usage
### 1. Add Dependency
```xml
<dependency>
<groupId>io.github.pnoker</groupId>
<artifactId>dc3-api-auth</artifactId>
<version>2026.5.22</version>
</dependency>
```
### 2. Import Proto Files
```protobuf
import "api/center/auth/tenant.proto";
import "api/center/auth/token.proto";
import "api/center/auth/user.proto";
import "api/center/auth/local_credential.proto";
```
### 3. Implement Service
```java
public class TenantServiceImpl extends TenantApiGrpc.TenantApiImplBase {
@Override
public void getByCode(GrpcCodeQuery request,
StreamObserver<GrpcRTenantDTO> responseObserver) {
// Implementation
}
}
```
## API Features
### Multi-Tenancy Support
- Tenant isolation through tenant codes
- Tenant-scoped user management
- Cross-tenant operations support
### Authentication Flow
1. Client queries tenant by code
2. Local credential lookup via `LocalCredentialApi`
3. Token validation via `TokenApi`
4. User information retrieval by principal via `UserApi`
### Security Features
- Server-side password hashing
- Token-based authentication
- User credential management
- Login tracking with principal IDs
## Data Models
### Tenant Model
- **tenant_name**: Display name of the tenant
- **tenant_code**: Unique tenant identifier
- **enable_flag**: Active/inactive status (1=enabled, 0=disabled)
### User Model
- **nick_name**: Display name
- **user_name**: Unique username
- **phone**: Contact phone number
- **email**: Email address
- **social_ext**: Encrypted social account information
- **identity_ext**: Encrypted identity verification data
### Login Lookup Model
- **login_name**: Username for authentication
- **user_id**: Reference to user entity
- **principal_id**: Reference to unified auth principal
- **enable_flag**: Account status
## Build Instructions
Run from the repository root:
```bash
# Build the module
mvn -s ../../.mvn/settings.xml clean package
# Install to local repository
mvn -s ../../.mvn/settings.xml clean install
mvn -s .mvn/settings.xml -q -pl dc3-api/dc3-api-auth -am compile
```
## License
This module has no handwritten runtime code or module-specific tests. A successful compile verifies proto syntax and
generated Java sources; server/facade behaviour is tested in the implementing modules.
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
When changing the contract, preserve field numbers, update implementations and clients together, and verify that
tenant and authorization context remain explicit.
dc3-api/dc3-api-data/README.md
+21 -260
View File
@@ -1,273 +1,34 @@
# DC3 API Data
## Overview
`dc3-api-data` defines gRPC contracts for values, commands, events, status, and system-health queries. Generated Java
types use `io.github.pnoker.api.center.data`; proto sources live under `src/main/protobuf/api/common/data/`.
`dc3-api-data` provides gRPC service definitions for device data collection and management in the IoT DC3 platform. It
defines interfaces for querying real-time device point values and historical data retrieval.
## Services
## Module Information
| Service | RPCs | Purpose |
|---|---|---|
| `PointValueApi` | `GetLastValue`, `ListHistoryValues` | query point values |
| `PointValueApi` | `ReadCommand`, `WriteCommand` | submit point read/write commands |
| `CommandHistoryApi` | `CallCommand`, `GetByRecordId`, `ListByPage` | dispatch and query command history |
| `EventHistoryApi` | `ReportEvent`, `GetByRecordId`, `ListByPage` | report and query event history |
| `StatusHealthApi` | device/driver status and system-health RPCs | expose status snapshots and summaries |
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-api-data
- **Version**: 2026.5.22
- **Package**: `io.github.pnoker.api.center.data`
Single-result RPCs use `GetXxx`; collection/page results use `ListXxx` or an explicitly named status aggregation. Do
not reintroduce legacy `SelectXxx` names.
## Proto Definitions
## Consumers and implementation
### point_value.proto
- `dc3-common-data` implements the data-side servers.
- `dc3-common-facade-grpc` wraps generated stubs in transport-independent facades.
- Manager and other business modules should call the facade API rather than construct channels directly.
Defines point value query RPC calls and data structures for device data collection.
All write/report requests must carry tenant context through the transport and into the business layer.
**Service**: `PointValueApi`
- `GetLastValue` - Query the latest collected value of a device point
- `ListHistoryValues` - Query historical values of a device point
- `ReadCommand` - Trigger a read command for a device point
- `WriteCommand` - Trigger a write command for a device point
**Key Messages**:
- `GrpcPointValueQuery` - Request wrapper for point value queries (device_id, point_id, tenant_id)
- `GrpcRPointValueDTO` - Response wrapper containing point value information
- `GrpcPointValueDTO` - Point value data structure
### event_history.proto
Defines device event history RPC calls.
**Service**: `EventHistoryApi`
- `ReportEvent` - Report a device event
- `GetByRecordId` - Query an event history record by record ID
- `ListByPage` - Query event history with pagination support
### command_history.proto
Defines device command history RPC calls.
**Service**: `CommandHistoryApi`
- `CallCommand` - Issue a command to a device
- `GetByRecordId` - Query a command history record by record ID
- `ListByPage` - Query command history with pagination support
### status_health.proto
Defines device/driver status and system health RPC calls.
**Service**: `StatusHealthApi`
- `DeviceStatusesByIds` - Query device statuses by device IDs
- `DeviceStatusesByProfileId` - Query device statuses by profile ID
- `DriverStatusesByIds` - Query driver statuses by driver IDs
- `DriverDeviceStatusSummary` - Summarize device statuses under a driver
- `SystemHealth` - Query overall system health
## Data Models
### Point Value Model
The `GrpcPointValueDTO` represents collected data from device points:
```protobuf
message GrpcPointValueDTO {
int64 id = 1; // Point value record ID
int64 device_id = 2; // Source device identifier
int64 point_id = 3; // Point identifier
string value = 4; // Processed/converted value
string raw_value = 5; // Raw value from device
int64 create_time = 6; // Storage timestamp
}
```
### Field Descriptions
| Field | Type | Description |
|---------------|--------|------------------------------------------------------|
| `id` | int64 | Unique identifier for the point value record |
| `device_id` | int64 | ID of the device that generated the data |
| `point_id` | int64 | ID of the point (tag) within the device |
| `value` | string | Processed value after data conversion and formatting |
| `raw_value` | string | Original raw value collected from the device |
| `create_time` | int64 | Unix timestamp when data was stored (milliseconds) |
## Dependencies
This module depends on common proto definitions:
- `api/common/r.proto` - Common response wrapper (GrpcR)
## Usage
### 1. Add Dependency
```xml
<dependency>
<groupId>io.github.pnoker</groupId>
<artifactId>dc3-api-data</artifactId>
<version>2026.5.22</version>
</dependency>
```
### 2. Import Proto Files
```protobuf
import "api/center/data/point_value.proto";
```
### 3. Implement Service
```java
public class PointValueServiceImpl extends PointValueApiGrpc.PointValueApiImplBase {
@Override
public void getLastValue(GrpcPointValueQuery request,
StreamObserver<GrpcRPointValueDTO> responseObserver) {
// Query latest point value from database
// Return GrpcRPointValueDTO with point value data
}
}
```
### 4. Query Example
```java
// Build query request
GrpcPointValueQuery query = GrpcPointValueQuery.newBuilder()
.setDeviceId(12345L)
.setPointId(67890L)
.setTenantId(1L)
.build();
// Call service
GrpcRPointValueDTO response = pointValueApi.getLastValue(query);
// Extract data
if(response.
getResult().
getOk()){
GrpcPointValueDTO pointValue = response.getData();
String value = pointValue.getValue();
String rawValue = pointValue.getRawValue();
long timestamp = pointValue.getCreateTime();
}
```
## API Features
### Real-Time Data Access
- Query latest point values by device and point IDs
- Support for both raw and processed values
- Tenant-scoped data access
### Data Processing
- **Raw Value**: Original data read from the device without processing
- **Processed Value**: Converted and formatted value after applying:
- Unit conversion
- Scale factors
- Precision formatting
- Data type conversion
### Data Flow
```
Device → Driver → Data Collection → Time Series DB → PointValueApi
```
## Use Cases
### 1. Real-Time Monitoring
```java
// Monitor device point value in real-time
GrpcPointValueDTO latestValue = getLastValue(deviceId, pointId);
displayValue(latestValue.getValue());
```
### 2. Data Analysis
```java
// Compare raw vs processed values
String raw = pointValue.getRawValue();
String processed = pointValue.getValue();
analyzeConversion(raw, processed);
```
### 3. Time Series Operations
```java
// Use timestamp for time-based queries
long timestamp = pointValue.getCreateTime();
Date collectionTime = new Date(timestamp);
```
## Performance Considerations
- **Query Optimization**: Always include tenant_id for proper data isolation
- **Caching**: Consider caching recent point values for high-frequency queries
- **Time Series Store**: This API queries the time-series store through `dc3-common-repository` (PostgreSQL with the
TimescaleDB extension)
- **Data Volume**: Point value queries can generate high traffic in large-scale deployments
## Integration Points
### Driver Services
Drivers write point values to the data layer:
```
Driver Service → Device SDK → Point Collection → Data Store
```
### Manager Service
Manager service provides device/point metadata:
```
PointValueApi → ManagerApi (get point info) → Return value with metadata
```
### Application Layer
Upper applications consume point value data for:
- Real-time dashboards
- Data analytics
- Alarm monitoring
- Historical data queries
## Data Retention
Point values are typically stored in time-series databases with:
- **High-frequency data**: Raw values for immediate processing
- **Aggregated data**: Processed values for long-term storage
- **Retention policies**: Configurable by tenant or device type
## Build Instructions
## Build and Verification
```bash
# Build the module
mvn -s ../../.mvn/settings.xml clean package
# Install to local repository
mvn -s ../../.mvn/settings.xml clean install
mvn -s .mvn/settings.xml -q -pl dc3-api/dc3-api-data -am compile
```
## Related Modules
- `dc3-api-driver` - Driver interface for point data collection
- `dc3-api-manager` - Device and point metadata management
- `dc3-common-data` - Data models and DTOs
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
This contract module has no module-specific tests. Compile it after proto changes, then run the matching server and
facade tests in `dc3-common-data` and `dc3-common-facade-grpc`.
dc3-api/dc3-api-driver/README.md
+35 -380
View File
@@ -1,400 +1,55 @@
# DC3 API Driver
## Overview
`dc3-api-driver` defines the gRPC contract used by protocol drivers to register with the Manager Center and retrieve
driver-scoped device and point configuration. Generated Java types use `io.github.pnoker.api.common.driver`.
`dc3-api-driver` provides gRPC service definitions for driver services in the IoT DC3 platform. It defines the
communication interface between device drivers and the platform's manager service, enabling device registration,
metadata synchronization, and point value collection.
## Services
## Module Information
| Service | RPC | Response | Purpose |
|---|---|---|---|
| `DriverApi` | `DriverRegister` | `GrpcRDriverRegisterDTO` | register metadata and receive assigned configuration |
| `DriverApi` | `GetById` | `GrpcRDriverRegisterDTO` | reload registered driver metadata |
| `DeviceApi` | `ListByPage` | `GrpcRPageDeviceDTO` | page through driver-owned devices |
| `DeviceApi` | `GetById` | `GrpcRDeviceDTO` | get one device with attached attribute configuration |
| `PointApi` | `ListByPage` | `GrpcRPagePointDTO` | page through driver-visible points |
| `PointApi` | `GetById` | `GrpcRPointDTO` | get one point with attached configuration |
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-api-driver
- **Version**: 2026.5.22
- **Package**: `io.github.pnoker.api.common.driver`
Proto sources live under `src/main/protobuf/api/common/driver/`. The `.proto` files are authoritative for fields and
wrapper shapes.
## Proto Definitions
## Registration flow
### driver_driver.proto
1. `dc3-common-driver` builds `GrpcDriverRegisterDTO` from the driver's `application.yml` metadata.
2. The driver calls `DriverApi.DriverRegister` on the Manager Center.
3. The response supplies driver metadata, device IDs, and supported driver/point/command/event attributes.
4. `DeviceClient` and `PointClient` load attached configuration with `GetById` or `ListByPage`.
5. The SDK initializes protocol scheduling, metadata subscriptions, commands, and value dispatch.
Defines driver registration RPC calls and data structures.
**Service**: `DriverApi`
- `DriverRegister` - Register a driver instance with the platform (used by drivers on startup)
- `GetById` - Query driver registration information by driver ID
**Key Messages**:
- `GrpcDriverRegisterDTO` - Driver registration request information
- `GrpcRDriverRegisterDTO` - Driver registration response with configuration data
### driver_device.proto
Defines device-related RPC calls for driver services.
**Service**: `DeviceApi`
- `ListByPage` - Query devices with pagination support
- `GetById` - Query device by device ID
**Key Messages**:
- `GrpcPageDeviceQuery` - Paginated device query request
- `GrpcDeviceQuery` - Single device query request
- `GrpcRPageDeviceDTO` - Paginated device list response
- `GrpcRDeviceDTO` - Single device response
- `GrpcRDeviceAttachDTO` - Device with full configuration (device + points + attributes)
### driver_point.proto
Defines point-related RPC calls for driver services.
**Service**: `PointApi`
- `ListByPage` - Query points with pagination support
- `GetById` - Query point by point ID
**Key Messages**:
- `GrpcPagePointQuery` - Paginated point query request
- `GrpcPointQuery` - Single point query request
- `GrpcRPagePointDTO` - Paginated point list response
- `GrpcRPointDTO` - Single point response
### driver_entity.proto
Defines driver entity structures used during registration.
**Key Messages**:
- `GrpcDriverRegisterDTO` - Complete driver registration information including:
- Tenant identification
- Driver client name (service instance identifier)
- Driver metadata (GrpcDriverDTO)
- Driver attribute definitions
- Point attribute definitions
### driver_query.proto
Defines query structures for driver services.
**Key Messages**:
- `GrpcDriverQuery` - Driver query by driver_id
- `GrpcDeviceQuery` - Device query by driver_id and device_id
- `GrpcPointQuery` - Point query by driver_id and point_id
### driver_query_page.proto
Defines paginated query structures for driver services.
**Key Messages**:
- `GrpcPageDeviceQuery` - Paginated device query with filters (tenant, driver, device)
- `GrpcPagePointQuery` - Paginated point query with filters (tenant, driver, device, profile)
## Dependencies
This module depends on common proto definitions:
- `api/common/entity.proto` - Common entity definitions (Driver, Device, Point, Attributes)
- `api/common/page.proto` - Pagination support
- `api/common/r.proto` - Common response wrapper
## Usage
### 1. Add Dependency
```xml
<dependency>
<groupId>io.github.pnoker</groupId>
<artifactId>dc3-api-driver</artifactId>
<version>2026.5.22</version>
</dependency>
```
### 2. Driver Registration Flow
```protobuf
// 1. Driver builds registration request
GrpcDriverRegisterDTO registerRequest = GrpcDriverRegisterDTO.newBuilder()
.setTenant("default")
.setClient("modbus-tcp-driver-001")
.setDriver(driverInfo)
.addAllDriverAttributes(driverAttributes)
.addAllPointAttributes(pointAttributes)
.build();
// 2. Call registration service
GrpcRDriverRegisterDTO response = driverApi.driverRegister(registerRequest);
// 3. Extract configuration from response
GrpcDriverDTO driver = response.getDriver();
List<Long> deviceIds = response.getDeviceIdsList();
List<GrpcDriverAttributeDTO> driverAttrs = response.getDriverAttributesList();
List<GrpcPointAttributeDTO> pointAttrs = response.getPointAttributesList();
// 4. Load device configurations
for (Long deviceId : deviceIds) {
GrpcDeviceQuery query = GrpcDeviceQuery.newBuilder()
.setDriverId(driver.getId())
.setDeviceId(deviceId)
.build();
GrpcRDeviceDTO deviceResponse = deviceApi.getById(query);
// Process device configuration
}
```
### 3. Query Device Configuration
## Response handling example
```java
// Query device with full configuration
GrpcRDeviceAttachDTO deviceAttach = deviceApi.getById(deviceQuery);
// Extract device information
GrpcDeviceDTO device = deviceAttach.getDevice();
List<Long> pointIds = deviceAttach.getPointIdsList();
List<GrpcDriverAttributeConfigDTO> driverConfigs = deviceAttach.getDriverConfigsList();
List<GrpcPointAttributeConfigDTO> pointConfigs = deviceAttach.getPointConfigsList();
// Initialize device connection
initializeDevice(device, driverConfigs, pointConfigs);
```
### 4. Query Point Configuration
```java
// Query point by ID
GrpcPointQuery pointQuery = GrpcPointQuery.newBuilder()
.setDriverId(driverId)
.setPointId(pointId)
.build();
GrpcRPointDTO pointResponse = pointApi.getById(pointQuery);
GrpcPointDTO point = pointResponse.getData();
// Configure point reading
configurePoint(point);
```
## Driver Service Lifecycle
### 1. Startup Phase
```
Driver Service Start
↓
Build GrpcDriverRegisterDTO
↓
Call DriverApi.driverRegister()
↓
Receive Driver Configuration
↓
Load Device Configurations
↓
Load Point Configurations
↓
Initialize Device Connections
↓
Ready for Data Collection
```
### 2. Runtime Phase
```
Periodic Data Collection
↓
Read Point Values from Device
↓
Convert and Format Values
↓
Send to Data Center
↓
Repeat
```
### 3. Shutdown Phase
```
Driver Service Stop
↓
Close Device Connections
↓
Unregister from Manager
↓
Cleanup Resources
```
## Data Models
### Driver Metadata (GrpcDriverDTO)
- **driver_name**: Display name
- **driver_code**: Unique identifier
- **service_name**: Driver service type
- **service_host**: Deployment location
- **driver_type_flag**: Driver type (e.g., virtual, modbus, opc-ua)
- **driver_ext**: Extended configuration (JSON)
- **enable_flag**: Active status
- **signature**: Driver signature for validation
- **version**: Configuration version
### Device Metadata (GrpcDeviceDTO)
- **device_name**: Display name
- **device_code**: Unique identifier
- **driver_id**: Associated driver
- **device_ext**: Extended configuration (JSON)
- **enable_flag**: Active status
- **signature**: Device signature
- **version**: Configuration version
### Point Metadata (GrpcPointDTO)
- **point_name**: Display name
- **point_code**: Unique identifier
- **point_type_flag**: Data type (digital, analog, string)
- **rw_flag**: Read/write permission
- **base_value**: Base value for conversion
- **multiple**: Scale factor
- **value_decimal**: Precision
- **unit**: Measurement unit
- **profile_id**: Associated profile template
### Attribute Configuration
Drivers and points can have configurable attributes:
- **Driver Attributes**: Driver-level configuration (e.g., connection settings)
- **Point Attributes**: Point-level configuration (e.g., register address)
Attributes support:
- Type specification (string, number, boolean)
- Default values
- Per-device configuration overrides
- Dynamic configuration updates
## API Features
### Multi-Tenancy Support
- Tenant-scoped driver registration
- Tenant-isolated device and point queries
- Cross-tenant operation prevention
### Configuration Synchronization
- Automatic configuration distribution on registration
- Version-based configuration updates
- Signature-based change detection
### Extensibility
- Custom driver types via driver_type_flag
- Extended configuration via *_ext fields
- Custom attribute definitions
### Query Optimization
- Pagination support for large device/point lists
- Driver-scoped queries for performance
- Profile-based filtering for template queries
## Integration Points
### Driver Implementation
```java
// Driver service implements DriverApi for registration
public class ModbusTcpDriverService {
private final DriverApiGrpc.DriverApiBlockingStub driverApi;
private final DeviceApiGrpc.DeviceApiBlockingStub deviceApi;
private final PointApiGrpc.PointApiBlockingStub pointApi;
public void start() {
// Register driver
registerDriver();
// Load configurations
loadDeviceConfigurations();
// Start data collection
startDataCollection();
}
GrpcRDeviceDTO response = deviceApiBlockingStub.getById(deviceQuery);
if (!response.getResult().getOk()) {
throw new IllegalStateException(response.getResult().getMessage());
}
GrpcRDeviceAttachDTO attachment = response.getData();
GrpcDeviceDTO device = attachment.getDevice();
```
### Manager Service
`DeviceApi.GetById` returns `GrpcRDeviceDTO`; `GrpcRDeviceAttachDTO` is its `data` field, not the RPC's top-level return
type.
Manager service implements these APIs to provide:
## Implementation
- Driver registration handling
- Device metadata management
- Point metadata management
- Configuration distribution
The Manager Center implements these services. Drivers are clients; they do not implement `DriverApi` themselves.
`dc3-common-driver` creates shared stubs through `DriverClientStubConfig` and exposes higher-level clients to driver
implementations.
### Data Collection
```
Driver Device SDK → Read Device → Convert Data → Send to Data Center
```
## Communication Pattern
### Synchronous Queries
- Configuration queries (device, point)
- Registration operations
### Asynchronous Events
- Device connection status updates
- Point value changes (via message queue)
- Configuration change notifications
## Error Handling
### Registration Failures
- Invalid tenant
- Duplicate driver instance
- Missing required attributes
### Query Failures
- Device not found
- Point not found
- Permission denied
- Driver not registered
## Performance Considerations
- **Connection Pooling**: Reuse gRPC channels for manager communication
- **Configuration Caching**: Cache device/point configurations locally
- **Batch Queries**: Use pagination queries for loading multiple devices/points
- **Lazy Loading**: Load device configurations on-demand
## Build Instructions
## Build and Verification
```bash
# Build the module
mvn -s ../../.mvn/settings.xml clean package
# Install to local repository
mvn -s ../../.mvn/settings.xml clean install
mvn -s .mvn/settings.xml -q -pl dc3-api/dc3-api-driver -am compile
```
## Related Modules
- `dc3-api-manager` - Manager service API for device/driver/point management
- `dc3-api-data` - Data service API for point value storage
- `dc3-common-driver` - Driver framework SDK
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
After a contract change, run the matching gRPC server/client tests in `dc3-common-manager` and `dc3-common-driver`.
Preserve field numbers and tenant context when evolving registration or query messages.
dc3-api/dc3-api-manager/README.md
+30 -166
View File
@@ -1,186 +1,50 @@
# DC3 API Manager
## Overview
`dc3-api-manager` defines Manager Center gRPC contracts for metadata lookups used by distributed facades and other
services. Generated Java types use `io.github.pnoker.api.center.manager`.
`dc3-api-manager` provides gRPC service definitions for the Manager Center in the IoT DC3 platform. It defines the
interfaces used by the Data service and other consumers to query driver, device, point, profile, command, and event
metadata from the Manager Center.
## Services
## Module Information
| Service | Single-result RPCs | Collection/page RPCs |
|---|---|---|
| `DriverApi` | `GetByDriverId`, `GetByDeviceId` | `ListByPage`, `ListByDriverIds` |
| `DeviceApi` | `GetByDeviceId` | `ListByPage`, `ListByProfileId`, `ListByDriverId`, `ListByDeviceIds` |
| `PointApi` | `GetById` | `ListByPage`, `ListByIds` |
| `ProfileApi` | `GetByProfileId` | `ListByPage`, `ListByProfileIds`, `ListByDeviceId` |
| `CommandApi` | `GetById` | `ListByPage`, `ListByIds` |
| `EventApi` | `GetById` | `ListByPage`, `ListByIds` |
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-api-manager
- **Version**: 2026.5.22
- **Package**: `io.github.pnoker.api.center.manager`
Proto sources live under `src/main/protobuf/api/common/manager/`. Shared query and page messages are defined in
`manager_query.proto` and `manager_query_page.proto`.
## Proto Definitions
## Usage boundary
### manager_driver.proto
Business services should inject facade interfaces such as `DriverFacade`, `DeviceFacade`, or `PointFacade` from
`dc3-common-facade-api`. The distributed implementation in `dc3-common-facade-grpc` owns generated blocking stubs,
channel selection, error-envelope handling, and BO conversion.
Defines driver-related RPC calls from the manager perspective.
**Service**: `DriverApi`
- `ListByPage` - Query drivers with pagination support
- `GetByDriverId` - Query driver information by driver ID
- `ListByDriverIds` - Query drivers by a list of driver IDs
- `GetByDeviceId` - Query driver information by device ID
**Key Messages**:
- `GrpcPageDriverQuery` - Paginated driver query request
- `GrpcDriverQuery` - Driver query by driver ID / device ID
- `GrpcDriverIdsQuery` - Driver query by a list of driver IDs
- `GrpcRDriverDTO` - Response wrapper containing driver information
- `GrpcRPageDriverDTO` / `GrpcRDriverListDTO` - Paginated / list responses
- `GrpcDriverDTO` - Driver data structure (service name, driver type, host, etc.)
### manager_device.proto
Defines device-related RPC calls from the manager perspective.
**Service**: `DeviceApi`
- `ListByPage` - Query devices with pagination support
- `ListByProfileId` - Query devices by profile ID
- `ListByDriverId` - Query devices by driver ID
- `GetByDeviceId` - Query device information by device ID
- `ListByDeviceIds` - Query devices by a list of device IDs
**Key Messages**:
- `GrpcPageDeviceQuery` - Paginated device query request
- `GrpcDeviceQuery` - Single device query
- `GrpcDeviceIdsQuery` - Device query by a list of device IDs
- `GrpcRDeviceDTO` / `GrpcRPageDeviceDTO` / `GrpcRDeviceListDTO` - Single / paginated / list responses
### manager_point.proto
Defines point-related RPC calls from the manager perspective.
**Service**: `PointApi`
- `ListByPage` - Query points with pagination support
- `GetById` - Query point information by point ID
- `ListByIds` - Query points by a list of point IDs
**Key Messages**:
- `GrpcPagePointQuery` - Paginated point query request
- `GrpcPointQuery` - Single point query
- `GrpcPointIdsQuery` - Point query by a list of point IDs
- `GrpcRPointDTO` / `GrpcRPagePointDTO` / `GrpcRPointListDTO` - Single / paginated / list responses
### manager_command.proto
Defines command-related RPC calls from the manager perspective.
**Service**: `CommandApi`
- `ListByPage` - Query commands with pagination support
- `GetById` - Query command information by command ID
- `ListByIds` - Query commands by a list of command IDs
### manager_event.proto
Defines event-related RPC calls from the manager perspective.
**Service**: `EventApi`
- `ListByPage` - Query events with pagination support
- `GetById` - Query event information by event ID
- `ListByIds` - Query events by a list of event IDs
### manager_profile.proto
Defines profile-related RPC calls from the manager perspective.
**Service**: `ProfileApi`
- `ListByPage` - Query profiles with pagination support
- `GetByProfileId` - Query profile information by profile ID
- `ListByProfileIds` - Query profiles by a list of profile IDs
- `ListByDeviceId` - Query profiles bound to a device
### manager_query.proto / manager_query_page.proto
Shared query and paginated query structures for manager RPC calls.
## Dependencies
This module depends on common proto definitions:
- `api/common/entity.proto` - Common entity definitions
- `api/common/page.proto` - Pagination support
- `api/common/r.proto` - Common response wrapper
## Usage
### 1. Add Dependency
```xml
<dependency>
<groupId>io.github.pnoker</groupId>
<artifactId>dc3-api-manager</artifactId>
<version>2026.5.22</version>
</dependency>
```
### 2. Inject gRPC Client
A transport adapter that needs the generated API calls the current cardinality-matching methods, for example:
```java
@GrpcClient(ManagerConstant.SERVICE_NAME)
private DriverApiGrpc.DriverApiBlockingStub driverApiBlockingStub;
@GrpcClient(ManagerConstant.SERVICE_NAME)
private PointApiGrpc.PointApiBlockingStub pointApiBlockingStub;
```
### 3. Query Driver by Device
```java
GrpcDeviceQuery query = GrpcDeviceQuery.newBuilder()
GrpcDeviceQuery request = GrpcDeviceQuery.newBuilder()
.setDeviceId(deviceId)
.setTenantId(tenantId)
.build();
GrpcRDriverDTO response = driverApiBlockingStub.getByDeviceId(query);
if(response.
getResult().
getOk()){
String serviceName = response.getData().getServiceName();
}
GrpcRDriverDTO response = driverApiBlockingStub.getByDeviceId(request);
```
## Integration Points
Do not use removed `SelectXxx` RPC names or ad hoc channel construction in business code.
- Used by `dc3-common-data` to resolve the target driver service name before publishing RabbitMQ commands
- Used by `dc3-common-data` to look up point metadata for data queries
## Implementation
## Build Instructions
`dc3-common-manager` implements the services as Spring `@Service` beans extending generated `*ImplBase` classes.
`dc3-common-facade-grpc` consumes them through stubs created by `GrpcStubConfig`.
## Build and Verification
```bash
# Build the module (run from repo root)
mvn -s .mvn/settings.xml clean package
# Install to local repository
mvn -s .mvn/settings.xml clean install
# Build this module only
mvn -s ../../.mvn/settings.xml clean package
mvn -s .mvn/settings.xml -q -pl dc3-api/dc3-api-manager -am compile
```
## Related Modules
- `dc3-api-driver` - Driver-side gRPC API for driver registration and config sync
- `dc3-common-data` - Consumes this API to resolve driver/point metadata
- `dc3-common-manager` - Implements this API as `@GrpcService` server
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
After proto changes, run the Manager gRPC server tests and facade contract tests. Verify tenant propagation and update
the corresponding server, builder, facade, and caller in the same change.
dc3-center/README.md
+53
View File
@@ -0,0 +1,53 @@
# DC3 Center
`dc3-center` contains the deployable backend applications. Most business logic lives in matching `dc3-common-*`
modules; center modules assemble dependencies, configuration, and process boundaries.
## Applications
| Module | HTTP | gRPC | Base path | Purpose |
|---|---:|---:|---|---|
| `dc3-center-single` | 8100 | 9100 | `/single` | auth, manager, and data in one JVM |
| `dc3-center-auth` | 8300 | 9300 | `/auth` | identity, authorization, OAuth2, and MCP authorization |
| `dc3-center-manager` | 8400 | 9400 | `/manager` | device and metadata management |
| `dc3-center-data` | 8500 | 9500 | `/data` | values, commands, events, and status |
| `dc3-center-agentic` | 8600 | n/a | `/agentic` | AI-assisted operations |
Ports are defaults; environment variables in each `application.yml` are authoritative. The distributed applications use
static, environment-overridable gRPC addresses. They do not depend on Nacos service discovery.
## Run locally
From the repository root:
```bash
make up-db
make up-dev GROUP=core
```
To run source processes instead, start one command per terminal:
```bash
make run SERVICE=auth
make run SERVICE=manager
make run SERVICE=data
make run SERVICE=agentic
```
Run the all-in-one process directly because the root Makefile does not define a `single` service alias:
```bash
mvn -s .mvn/settings.xml -pl dc3-center/dc3-center-single -am spring-boot:run
```
Start the gateway separately when testing public HTTP routes.
## Verification
```bash
mvn -s .mvn/settings.xml -q -f dc3-center/pom.xml -DskipTests compile
mvn -s .mvn/settings.xml -f dc3-center/pom.xml test
```
For runtime configuration, read the affected module's `application.yml` plus its active profile file. Do not duplicate
profile-specific host or port values in new documentation.
dc3-center/dc3-center-agentic/README.md
+14 -10
View File
@@ -11,7 +11,6 @@ shell; the agentic logic lives in `dc3-common-agentic`.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-center-agentic
- **Version**: 2026.5.22
- **Package**: `io.github.pnoker.center.agentic`
## Service Ports
@@ -44,25 +43,30 @@ The WebFlux base path is `/agentic`; through the gateway the service is reached
### 1. Start Infrastructure and Center Services
```bash
podman compose -f dc3/docker-compose-db.yml up -d
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
make up-db
make up-dev SERVICES="auth manager data"
```
The agentic service has gRPC facade channels for Auth, Manager, and Data centers. Start all three before exercising
platform tools; the gateway is optional when calling the agentic service directly.
### 2. Build and Run
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-center/dc3-center-agentic -am package
java -jar dc3-center/dc3-center-agentic/target/dc3-center-agentic.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-center/dc3-center-agentic -am test
```
## Related Modules
- `dc3-common-agentic` — agentic SDK: Spring AI chat client, platform tools, conversation memory, model management
- `dc3-common-facade-grpc` — gRPC facade for cross-service access
- `dc3-common-resource-registrar` — registers this service's API / menu resources
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-center/dc3-center-auth/README.md
+18 -17
View File
@@ -10,15 +10,14 @@ control.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-center-auth
- **Version**: 2026.5.22
- **Package**: `io.github.pnoker.center.auth`
## Service Ports
| Protocol | Port |
|-----------|------------------------------------------------------|
| HTTP REST | `8300` (default, overridable via `SERVER_PORT`) |
| gRPC | `9300` (default, overridable via `GRPC_SERVER_PORT`) |
| Protocol | Port | Configuration variable |
|-----------|--------|------------------------|
| HTTP REST | `8300` | `DC3_AUTH_PORT` |
| gRPC | `9300` | `DC3_AUTH_GRPC_PORT` |
## Key Responsibilities
@@ -26,8 +25,8 @@ control.
- **Tenant Management**: Multi-tenant registration, lookup by tenant code
- **User Authentication**: Local credential validation with server-side password hashing
- **Dictionary Services**: Provide lookup dictionaries for auth-scoped data
- **gRPC Server**: Exposes `TenantApi`, `UserApi`, `LocalCredentialApi`, `TokenApi` for inter-service consumption (e.g.,
Gateway)
- **gRPC Server**: Exposes tenant, user, credential, token, permission, resource-registry, and MCP-runtime APIs for
facade-backed inter-service consumption
## REST Endpoints (via Gateway)
@@ -56,21 +55,21 @@ This service wires `dc3-common-auth` which contains all business logic controlle
- `application.yml` — base port and profile config
- `application-dev.yml` — dev env: Postgres connection via `${ENV:default}` vars
- `application-pre.yml` — pre-release: Nacos-based service discovery
- `application-pro.yml` — production: Nacos-based service discovery
- `application-pre.yml` — pre-release datasource and runtime overrides
- `application-pro.yml` — production datasource and runtime overrides
## Running Locally
### 1. Start Infrastructure
```bash
podman compose -f dc3/docker-compose-db.yml up -d
make up-db
```
### 2. Build
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-center/dc3-center-auth -am package
```
### 3. Run
@@ -79,14 +78,16 @@ mvn -s .mvn/settings.xml clean package
java -jar dc3-center/dc3-center-auth/target/dc3-center-auth.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-center/dc3-center-auth -am test
```
## Related Modules
- `dc3-api-auth` - gRPC API contracts for auth service
- `dc3-common-auth` - Business logic implementation
- `dc3-gateway` - Consumes token validation via gRPC
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-center/dc3-center-data/README.md
+27 -23
View File
@@ -10,24 +10,24 @@ exposing data query APIs.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-center-data
- **Version**: 2026.5.22
- **Package**: `io.github.pnoker.center.data`
## Service Ports
| Protocol | Port |
|-----------|------------------------------------------------------|
| HTTP REST | `8500` (default, overridable via `SERVER_PORT`) |
| gRPC | `9500` (default, overridable via `GRPC_SERVER_PORT`) |
| Protocol | Port | Configuration variable |
|-----------|--------|------------------------|
| HTTP REST | `8500` | `DC3_DATA_PORT` |
| gRPC | `9500` | `DC3_DATA_GRPC_PORT` |
## Key Responsibilities
- **Point Value Ingestion**: Receives point values from drivers via RabbitMQ (`dc3.e.value` exchange,
`dc3.q.value.point` queue) and persists them to the time-series storage
- **Point Value Query**: Exposes REST and gRPC APIs to query the latest and historical point values
- **Device Command Dispatch**: Receives read/write commands, resolves the target driver via Manager gRPC (
`ManagerConstant.SERVICE_NAME`), and publishes to `dc3.e.command`
- **Driver Status**: Tracks driver online/offline status events
- **Point Command Dispatch**: Resolves the target driver through `DriverFacade` and publishes point read/write commands
to `dc3.e.point_command`
- **Custom Command Dispatch**: Publishes custom device commands to `dc3.e.command`
- **Driver and Device Status**: Tracks state, timeout, and alarm events
- **Data Query**: Supports pagination query, real-time telemetry, and historical data retrieval
## REST Endpoints (via Gateway)
@@ -36,11 +36,13 @@ Accessible through the gateway at `/api/v3/data/**` (authentication required).
## Messaging Topics
| Exchange | Direction | Purpose |
|-----------------|-----------|-----------------------------------------|
| `dc3.e.value` | Inbound | Receive point values from drivers |
| `dc3.e.command` | Outbound | Dispatch read/write commands to drivers |
| `dc3.e.event` | Inbound | Receive driver/device status events |
| Exchange | Direction | Purpose |
|-----------------------|-----------|-----------------------------------------|
| `dc3.e.value` | Inbound | Receive point values from drivers |
| `dc3.e.point_command` | Outbound | Dispatch point read/write commands |
| `dc3.e.command` | Outbound | Dispatch custom device commands |
| `dc3.e.state` | Inbound | Receive driver/device state events |
| `dc3.e.event` | Inbound | Receive reported domain events |
## Dependencies
@@ -58,21 +60,21 @@ This service wires `dc3-common-data` which contains all business logic.
- `application.yml` — base port and profile config
- `application-dev.yml` — dev env: Postgres, RabbitMQ, gRPC client addresses
- `application-pre.yml` — pre-release: Nacos-based service discovery
- `application-pro.yml` — production: Nacos-based service discovery
- `application-pre.yml` — pre-release datasource, messaging, and static gRPC client addresses
- `application-pro.yml` — production datasource, messaging, and static gRPC client addresses
## Running Locally
### 1. Start Infrastructure
```bash
podman compose -f dc3/docker-compose-db.yml up -d
make up-db
```
### 2. Build
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-center/dc3-center-data -am package
```
### 3. Run (after auth and manager are up)
@@ -81,15 +83,17 @@ mvn -s .mvn/settings.xml clean package
java -jar dc3-center/dc3-center-data/target/dc3-center-data.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-center/dc3-center-data -am test
```
## Related Modules
- `dc3-api-data` - gRPC API contracts for point value queries
- `dc3-api-manager` - gRPC API for resolving driver/point metadata
- `dc3-common-data` - Business logic implementation
- `dc3-common-repository` - Pluggable time-series storage adapter
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-center/dc3-center-manager/README.md
+22 -21
View File
@@ -10,15 +10,14 @@ management, and command interfaces.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-center-manager
- **Version**: 2026.5.22
- **Package**: `io.github.pnoker.center.manager`
## Service Ports
| Protocol | Port |
|-----------|------------------------------------------------------|
| HTTP REST | `8400` (default, overridable via `SERVER_PORT`) |
| gRPC | `9400` (default, overridable via `GRPC_SERVER_PORT`) |
| Protocol | Port | Configuration variable |
|-----------|--------|------------------------|
| HTTP REST | `8400` | `DC3_MANAGER_PORT` |
| gRPC | `9400` | `DC3_MANAGER_GRPC_PORT` |
## Key Responsibilities
@@ -49,12 +48,12 @@ Key endpoint prefixes (defined in `ManagerConstant`):
## gRPC Services (consumed by drivers and data service)
| Service | Used By |
|------------------------------|----------------------------------|
| `DriverApi.driverRegister` | Drivers on startup |
| `DeviceApi.selectById` | Drivers fetching device config |
| `PointApi.selectById` | Drivers and data service |
| `DriverApi.selectByDeviceId` | Data service for command routing |
| Service | Used by |
|----------------------------|-------------------------------------------------|
| `DriverApi.DriverRegister` | Drivers registering on startup |
| `DeviceApi.GetById` | Drivers fetching device configuration |
| `PointApi.GetById` | Drivers fetching point configuration |
| `DriverApi.GetByDeviceId` | Distributed facades resolving command routing |
## Dependencies
@@ -72,21 +71,21 @@ This service wires `dc3-common-manager` which contains all business logic.
- `application.yml` — base port and profile config
- `application-dev.yml` — dev env: Postgres, RabbitMQ, gRPC client addresses
- `application-pre.yml` — pre-release: Nacos-based service discovery
- `application-pro.yml` — production: Nacos-based service discovery
- `application-pre.yml` — pre-release datasource, messaging, and static gRPC client addresses
- `application-pro.yml` — production datasource, messaging, and static gRPC client addresses
## Running Locally
### 1. Start Infrastructure
```bash
podman compose -f dc3/docker-compose-db.yml up -d
make up-db
```
### 2. Build
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-center/dc3-center-manager -am package
```
### 3. Run (after auth is up)
@@ -95,14 +94,16 @@ mvn -s .mvn/settings.xml clean package
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-center/dc3-center-manager -am test
```
## Related Modules
- `dc3-api-driver` - Driver-side gRPC API implemented by this service
- `dc3-api-manager` - Manager-side gRPC API implemented by this service
- `dc3-common-manager` - Business logic implementation
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-center/dc3-center-single/README.md
+15 -14
View File
@@ -9,15 +9,14 @@ management services into a single deployable module for simplified single-node o
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-center-single
- **Version**: 2026.5.22
- **Package**: `io.github.pnoker.center.single`
## Service Ports
| Protocol | Port |
|-----------|------------------------------------------------------|
| HTTP REST | `8100` (default, overridable via `SERVER_PORT`) |
| gRPC | `9100` (default, overridable via `GRPC_SERVER_PORT`) |
| Protocol | Port | Configuration variable |
|-----------|--------|------------------------|
| HTTP REST | `8100` | `DC3_SINGLE_PORT` |
| gRPC | `9100` | `DC3_SINGLE_GRPC_PORT` |
## Key Responsibilities
@@ -57,7 +56,7 @@ Wires all three common service modules:
- `application.yml` — base port and profile config
- `application-dev.yml` — dev env: single Postgres/RabbitMQ config
- `application-pre.yml` — pre-release: Nacos-based service discovery
- `application-pre.yml` — pre-release runtime overrides for the all-in-one process
- `application-pro.yml` — production target config
## Running Locally
@@ -65,13 +64,13 @@ Wires all three common service modules:
### 1. Start Infrastructure
```bash
podman compose -f dc3/docker-compose-db.yml up -d
make up-db
```
### 2. Build
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-center/dc3-center-single -am package
```
### 3. Run
@@ -80,15 +79,17 @@ mvn -s .mvn/settings.xml clean package
java -jar dc3-center/dc3-center-single/target/dc3-center-single.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-center/dc3-center-single -am test
```
## Related Modules
- `dc3-center-auth` — Standalone auth service
- `dc3-center-data` — Standalone data service
- `dc3-center-manager` — Standalone manager service
- `dc3-common-auth` / `dc3-common-data` / `dc3-common-manager` — Shared business logic
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-common/README.md
+60
View File
@@ -0,0 +1,60 @@
# DC3 Common
`dc3-common` contains reusable backend libraries and the shared business implementations assembled by the deployable
center and driver applications.
## Domain modules
| Module | Responsibility |
|---|---|
| `dc3-common-auth` | authentication, authorization, identity, OAuth2, and auth gRPC servers |
| `dc3-common-manager` | driver/device/profile/point metadata and manager APIs |
| `dc3-common-data` | values, commands, events, status, and data APIs |
| `dc3-common-agentic` | AI models, sessions, tools, and assisted operations |
| `dc3-common-driver` | driver SDK, registration, scheduling, metadata, command, and value runtime |
| `dc3-common-gateway` | gateway routes, authentication filter, and ingress support |
## Contracts and models
| Module | Responsibility |
|---|---|
| `dc3-common-model` | shared BO/VO/DTO bases, builders, extension models, validation groups, and domain enums |
| `dc3-common-public` | response envelope, `BaseService`, shared entities/utilities, and tenant markers |
| `dc3-common-api` | shared gRPC conversion helpers |
| `dc3-common-facade` | cross-service facade contracts and implementations |
| `dc3-common-constant` | stable shared constants |
| `dc3-common-exception` | shared exception hierarchy |
## Infrastructure modules
| Module | Responsibility |
|---|---|
| `dc3-common-dal` | shared label/group persistence |
| `dc3-common-postgres` | datasource and MyBatis-Plus configuration |
| `dc3-common-repository` | point-value storage abstraction |
| `dc3-common-rabbitmq` | shared exchanges, connection configuration, and message conversion |
| `dc3-common-mqtt` | MQTT client configuration |
| `dc3-common-quartz` | scheduling infrastructure |
| `dc3-common-thread` | managed executors |
| `dc3-common-web` | WebFlux, springdoc, security, and controller support |
| `dc3-common-log` | logging defaults |
| `dc3-common-sql` | SQL utilities |
| `dc3-common-resource-registrar` | API/resource annotation discovery and synchronization |
| `dc3-common-test` | shared tests, harnesses, and Testcontainers |
## Architecture rules
- Preserve `Controller -> Service -> Manager -> Mapper` layering.
- Keep tenant scope in queries, cache keys, gRPC calls, and cross-service lookups.
- Use BOs in persistent business services and builders for VO/BO/DO conversion.
- Use facade interfaces for cross-service business calls.
- Add dependencies to the narrowest module that owns the required capability.
## Verification
```bash
mvn -s .mvn/settings.xml -q -f dc3-common/pom.xml -DskipTests compile
mvn -s .mvn/settings.xml -f dc3-common/pom.xml test
```
Use the child README for module-specific configuration and tests.
dc3-common/dc3-common-agentic/README.md
+9 -8
View File
@@ -10,7 +10,6 @@ model uses to read and operate platform resources.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-common-agentic
- **Version**: 2026.5.22
## Key Components
@@ -37,16 +36,18 @@ model uses to read and operate platform resources.
## Build Instructions
```bash
mvn -s ../../.mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-agentic -am package
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-agentic -am test
```
## Related Modules
- `dc3-center-agentic` — the service shell that exposes this SDK over HTTP (`/api/v3/agentic/**`)
- `dc3-common-facade-*` — facades the platform tools call to reach other services
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-common/dc3-common-api/README.md
+10 -9
View File
@@ -9,7 +9,6 @@ builder utilities for constructing gRPC request/response objects from domain mod
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-common-api
- **Version**: 2026.5.22
## Key Components
@@ -24,16 +23,18 @@ protobuf classes.
## Build Instructions
```bash
mvn -s ../../.mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-api -am package
```
## Testing
This module currently has no module-specific automated tests. Verify generated or production sources by compiling the
affected reactor from the repository root:
```bash
mvn -s .mvn/settings.xml -q -pl dc3-common/dc3-common-api -am -DskipTests compile
```
## Related Modules
- `dc3-api-auth` / `dc3-api-data` / `dc3-api-driver` / `dc3-api-manager` — gRPC API contracts that use these utilities
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-common/dc3-common-auth/README.md
+21 -15
View File
@@ -10,7 +10,6 @@ functionality. It is wired directly into `dc3-center-auth`.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-common-auth
- **Version**: 2026.5.22
## Key Components
@@ -18,22 +17,36 @@ functionality. It is wired directly into `dc3-center-auth`.
|--------------|----------------------------------------------------------------------------|
| Controllers | REST controllers for user, tenant, token, dictionary endpoints |
| Services | `TokenService`, `UserService`, `TenantService`, `DictionaryForAuthService` |
| gRPC Servers | `TenantServer`, `UserServer`, `TokenServer` (`@GrpcService`) |
| gRPC Servers | Spring `@Service` beans extending generated `*ImplBase` server classes |
| DAL | MyBatis-Plus mappers and DAL managers for auth tables |
| Init | `AuthInitRunner` for startup checks |
## gRPC Services Exposed
| Service | Consumed By |
|-------------|------------------------------|
| `TokenApi` | Gateway (`Authentic` filter) |
| `TenantApi` | Gateway, other services |
| `UserApi` | Gateway, other services |
| Service | Purpose |
|---|---|
| `TokenApi` | Validate login and token material for gateway authentication |
| `TenantApi` | Resolve tenant metadata by code |
| `UserApi` | Resolve users by ID or principal ID |
| `LocalCredentialApi` | Resolve local credentials by login name |
| `PermissionApi` | List effective permission codes |
| `ResourceRegistryApi` | Synchronize discovered API and menu resources |
| `McpRuntimeApi` | Introspect, authorize, resolve, and audit MCP tool calls |
Distributed callers use the corresponding facade interfaces; they should not construct gRPC channels in business code.
## Build Instructions
```bash
mvn -s ../../.mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-auth -am package
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-auth -am test
```
## Related Modules
@@ -41,10 +54,3 @@ mvn -s ../../.mvn/settings.xml clean package
- `dc3-center-auth` — Bootstraps this module as a Spring Boot service
- `dc3-api-auth` — gRPC contract implemented by this module
- `dc3-common-model` — Entity, BO, VO, DTO definitions
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-common/dc3-common-constant/README.md
+32 -26
View File
@@ -10,7 +10,6 @@ and common modules.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-common-constant
- **Version**: 2026.5.22
## Key Components
@@ -27,18 +26,22 @@ and common modules.
`RabbitConstant` defines all exchange names, queue name prefixes, and routing key prefixes:
| Constant | Value |
|----------------------------------|--------------------------|
| `TOPIC_EXCHANGE_COMMAND` | `dc3.e.command` |
| `TOPIC_EXCHANGE_METADATA` | `dc3.e.metadata` |
| `TOPIC_EXCHANGE_VALUE` | `dc3.e.value` |
| `TOPIC_EXCHANGE_EVENT` | `dc3.e.event` |
| `ROUTING_DEVICE_COMMAND_PREFIX` | `dc3.r.command.device.` |
| `ROUTING_DRIVER_METADATA_PREFIX` | `dc3.r.metadata.driver.` |
| `ROUTING_POINT_VALUE_PREFIX` | `dc3.r.value.point.` |
| Constant | Base value |
|----------------------------------|--------------------------------|
| `TOPIC_EXCHANGE_POINT_COMMAND` | `dc3.e.point_command` |
| `TOPIC_EXCHANGE_COMMAND` | `dc3.e.command` |
| `TOPIC_EXCHANGE_METADATA` | `dc3.e.metadata` |
| `TOPIC_EXCHANGE_VALUE` | `dc3.e.value` |
| `TOPIC_EXCHANGE_EVENT` | `dc3.e.event` |
| `ROUTING_POINT_COMMAND_PREFIX` | `dc3.r.point_command.` |
| `ROUTING_COMMAND_PREFIX` | `dc3.r.command.` |
| `ROUTING_DRIVER_METADATA_PREFIX` | `dc3.r.metadata.driver.` |
| `ROUTING_POINT_VALUE_PREFIX` | `dc3.r.value.point.` |
> **Important**: RabbitMQ routing keys are suffixed with the driver's service name. These constants must not be renamed
> without updating all consumers.
The runtime may prepend the `dc3.rabbit.tag` system-property value to exchange, queue, and selected routing constants.
Point read/write operations use the point-command constants; `TOPIC_EXCHANGE_COMMAND` is reserved for custom commands.
Routing keys are suffixed with the driver's service name. Do not rename them without updating every producer, binding,
consumer, and deployed queue migration.
### Common Constants
@@ -53,26 +56,29 @@ and common modules.
Located in `io.github.pnoker.common.enums`:
- `EnableFlagEnum` — Entity enable/disable status
- `DriverStatusEnum` — Driver online/offline/fault states
- `DriverTypeFlagEnum` — Driver protocol type classification
- `PointTypeFlagEnum` — Point value type (int, float, bool, string, etc.)
- `MetadataOperateTypeEnum` — Metadata operation (add/update/delete)
- `DeviceCommandTypeEnum` — Device command type (READ/WRITE)
- And many others (`AttributeTypeFlagEnum`, `ProfileShareFlagEnum`, etc.)
- `EnableFlagEnum` — Boolean-like enable/disable state
- `EntityStatusEnum` — Online, offline, maintenance, and fault states
- `DriverTypeEnum` — Driver client/server, gateway, and connection classifications
- `PointTypeEnum` — Point value types such as string, numeric, and boolean
- `MetadataOperateTypeEnum` — Metadata add/delete/update operations
- `PointCommandTypeEnum` — Point read, batch-read, write, batch-write, and configuration commands
- `AttributeTypeEnum` — Attribute value types
- `ProfileShareTypeEnum` — Tenant-, driver-, and user-scoped profile sharing
## Build Instructions
```bash
mvn -s ../../.mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-constant -am package
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-constant -am test
```
## Related Modules
Used as a dependency by virtually all other `dc3-common-*` and `dc3-center-*` modules.
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-common/dc3-common-dal/README.md
+10 -9
View File
@@ -9,7 +9,6 @@ manager implementations, and shared data structures used across multiple service
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-common-dal
- **Version**: 2026.5.22
## Key Components
@@ -20,7 +19,16 @@ manager implementations, and shared data structures used across multiple service
## Build Instructions
```bash
mvn -s ../../.mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-dal -am package
```
## Testing
This module currently has no module-specific automated tests. Verify generated or production sources by compiling the
affected reactor from the repository root:
```bash
mvn -s .mvn/settings.xml -q -pl dc3-common/dc3-common-dal -am -DskipTests compile
```
## Related Modules
@@ -28,10 +36,3 @@ mvn -s ../../.mvn/settings.xml clean package
- `dc3-common-postgres` — PostgreSQL and MyBatis-Plus base configuration
- `dc3-common-model` — Base BO/VO/DTO model definitions
- `dc3-common-manager` / `dc3-common-auth` / `dc3-common-data` — Consumers of this DAL layer
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-common/dc3-common-data/README.md
+30 -23
View File
@@ -10,40 +10,54 @@ into `dc3-center-data`.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-common-data
- **Version**: 2026.5.22
## Key Components
| Layer | Contents |
|--------------|------------------------------------------------------------------------------------------|
| Controllers | REST controllers for point value read/write, query, status |
| Services | `PointCommandService`, `PointValueService`, `DriverStatusService`, `DeviceStatusService` |
| gRPC Clients | `@GrpcClient(ManagerConstant.SERVICE_NAME)` stubs for `DriverApi`, `PointApi` |
| RabbitMQ | Producer for `dc3.e.command`; Consumer for `dc3.e.value`, `dc3.e.event` |
| Init | `DataInitRunner` for startup preparation |
| Layer | Contents |
|--------------|---------------------------------------------------------------------------------------------------|
| Controllers | REST controllers for point values, point/custom commands, events, status, and health |
| Services | Point value, point command, command history, event history, driver status, and device status |
| Facades | `DriverFacade`, `PointFacade`, and related transport-independent cross-service APIs |
| RabbitMQ | Point/custom-command producers plus value, state, alarm, event, and result consumers |
| Init | `DataInitRunner` for startup preparation |
## Command Dispatch Flow
```
REST /api/v3/data/point_value/read
→ PointCommandServiceImpl
→ gRPC: driverApiBlockingStub.selectByDeviceId()
→ RabbitMQ: dc3.e.command / dc3.r.command.device.{serviceName}
→ DriverFacade.getByDeviceId(tenantId, deviceId)
→ RabbitMQ: dc3.e.point_command / dc3.r.point_command.{serviceName}
→ Driver receives and acts
```
Custom device commands follow the parallel `dc3.e.command` / `dc3.r.command.{serviceName}` route through
`CommandHistoryServiceImpl`.
## MQ Topics
| Exchange | Queue | Direction |
|-----------------|---------------------------------------------|-------------------------|
| `dc3.e.value` | `dc3.q.value.point` | Inbound (from drivers) |
| `dc3.e.command` | `dc3.q.command.device.{service}` | Outbound (to drivers) |
| `dc3.e.event` | `dc3.q.event.driver` / `dc3.q.event.device` | Inbound (status events) |
| Exchange | Queue or routing key | Direction |
|-----------------------|-------------------------------------|-----------------------------|
| `dc3.e.value` | `dc3.q.value.point` | Inbound point values |
| `dc3.e.point_command` | `dc3.r.point_command.{service}` | Outbound point read/write |
| `dc3.e.command` | `dc3.r.command.{service}` | Outbound custom commands |
| `dc3.e.state` | `dc3.q.state.driver` / `dc3.q.state.device` | Inbound driver/device state |
| `dc3.e.event` | `dc3.q.event.report` | Inbound reported events |
The optional `dc3.rabbit.tag` system property prefixes runtime names; `RabbitConstant` remains authoritative.
## Build Instructions
```bash
mvn -s ../../.mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-data -am package
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-data -am test
```
## Related Modules
@@ -52,10 +66,3 @@ mvn -s ../../.mvn/settings.xml clean package
- `dc3-api-manager` — gRPC API consumed by this module for driver/point resolution
- `dc3-common-repository` — Storage adapter for persisting point values
- `dc3-common-rabbitmq` — RabbitMQ exchange/queue configuration
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-common/dc3-common-driver/README.md
+21 -16
View File
@@ -10,7 +10,6 @@ scheduled data collection.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-common-driver
- **Version**: 2026.5.22
## Key Components
@@ -28,24 +27,37 @@ scheduled data collection.
```
Driver startup
→ DriverInitRunner
→ gRPC: dc3-center-manager / DriverApi.driverRegister()
→ gRPC: dc3-center-manager / DriverApi.DriverRegister
← Returns: driver ID, driver attributes, point attributes, device IDs
→ Subscribe to metadata queue: dc3.q.metadata.driver.{serviceName}
→ Subscribe to command queue: dc3.q.command.driver.{serviceName}
→ Subscribe to point-command queue: dc3.q.point_command.{serviceName}
→ Subscribe to custom-command queue: dc3.q.command.{serviceName}
```
## RabbitMQ Integration
| Exchange | Queue | Purpose |
|------------------|-----------------------------------|-------------------------------------|
| `dc3.e.metadata` | `dc3.q.metadata.driver.{service}` | Receive config change events |
| `dc3.e.command` | `dc3.q.command.driver.{service}` | Receive READ/WRITE commands |
| `dc3.e.value` | — | Publish point values to data center |
| Exchange | Queue | Purpose |
|-----------------------|-------------------------------------|--------------------------------------|
| `dc3.e.metadata` | `dc3.q.metadata.driver.{service}` | Receive configuration changes |
| `dc3.e.point_command` | `dc3.q.point_command.{service}` | Receive point read/write commands |
| `dc3.e.command` | `dc3.q.command.{service}` | Receive custom device commands |
| `dc3.e.value` | — | Publish point values to Data Center |
The optional `dc3.rabbit.tag` system property prefixes runtime names; use `RabbitConstant` and `DriverTopicConfig` as
the authoritative definitions.
## Build Instructions
```bash
mvn -s ../../.mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-driver -am package
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-driver -am test
```
## Related Modules
@@ -54,10 +66,3 @@ mvn -s ../../.mvn/settings.xml clean package
- `dc3-api-driver` — gRPC contracts consumed by this SDK
- `dc3-common-rabbitmq` — RabbitMQ exchange configuration
- `dc3-common-constant` — `RabbitConstant` routing key prefixes
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-common/dc3-common-exception/README.md
+16 -12
View File
@@ -9,7 +9,6 @@ services and modules use these exceptions to signal business errors consistently
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-common-exception
- **Version**: 2026.5.22
## Key Components
@@ -23,13 +22,17 @@ services and modules use these exceptions to signal business errors consistently
| `DeleteException` | Entity delete failure |
| `NotFoundException` | Entity or resource not found |
| `JsonException` | JSON serialization/deserialization error |
| `AuthException` | Authentication/authorization failure |
| `SecurityException` | General security policy violation |
| `UnAuthorizedException` | Missing or invalid authentication |
| `AccessDeniedException` | Authenticated principal lacks access |
| `DuplicateException` | Duplicate entity conflict |
### Utilities
- **`ExceptionUtil`** — Helper methods for wrapping and rethrowing exceptions with context
- **`ExceptionConstant`** — Standard exception message strings (e.g., `UTILITY_CLASS`)
- **`ExceptionUtil`** — Builds shared service-unavailable messages
- **`ExceptionMessageFormatter`** — Internal `{}` placeholder and trailing-cause formatter used by business exceptions
Shared message constants such as `ExceptionConstant` belong to `dc3-common-constant`.
## Usage
@@ -41,16 +44,17 @@ throw new AddException("Failed to add driver: " + entityBO.getServiceName());
## Build Instructions
```bash
mvn -s ../../.mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-exception -am package
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-exception -am test
```
## Related Modules
Used by all `dc3-common-*` service modules and `dc3-center-*` services.
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-common/dc3-common-facade/README.md
+29
View File
@@ -0,0 +1,29 @@
# DC3 Common Facade
The facade modules define and implement cross-service business boundaries without binding callers directly to gRPC or
in-process service classes.
## Modules
| Module | Role |
|---|---|
| `dc3-common-facade-api` | transport-independent facade interfaces and request/result contracts |
| `dc3-common-facade-grpc` | distributed implementations backed by shared gRPC stubs |
| `dc3-common-facade-local-auth` | in-process auth facade implementation |
| `dc3-common-facade-local-data` | in-process data facade implementation |
| `dc3-common-facade-local-manager` | in-process manager facade implementation |
| `dc3-common-facade-local` | convenience POM aggregating all local implementations |
## Selection
- Distributed center applications normally use `dc3-common-facade-grpc`.
- Single-process applications use the required domain-specific local modules.
- Depend on `dc3-common-facade-local` only when the application intentionally needs every local facade.
- Business code imports interfaces from `dc3-common-facade-api`; transport selection belongs in assembly/configuration.
## Verification
```bash
mvn -s .mvn/settings.xml -q -f dc3-common/dc3-common-facade/pom.xml -DskipTests compile
mvn -s .mvn/settings.xml -f dc3-common/dc3-common-facade/pom.xml test
```
dc3-common/dc3-common-facade/dc3-common-facade-api/README.md
+10 -8
View File
@@ -17,7 +17,6 @@ services never depend on transport details.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-common-facade-api
- **Version**: 2026.5.22
## Facade Contracts
@@ -42,16 +41,19 @@ auto-configuration.
## Build Instructions
```bash
mvn -s ../../../.mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-facade/dc3-common-facade-api -am package
```
## Testing
This module currently has no module-specific automated tests. Verify generated or production sources by compiling the
affected reactor from the repository root:
```bash
mvn -s .mvn/settings.xml -q -pl dc3-common/dc3-common-facade/dc3-common-facade-api -am -DskipTests compile
```
## Related Modules
- `dc3-common-facade-grpc` — gRPC-backed implementation
- `dc3-common-facade-local-auth` / `-data` / `-manager` — in-process implementations
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-common/dc3-common-facade/dc3-common-facade-grpc/README.md
+10 -8
View File
@@ -11,7 +11,6 @@ is the default implementation for the distributed (multi-service) deployment.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-common-facade-grpc
- **Version**: 2026.5.22
## Implementations
@@ -35,16 +34,19 @@ auth channel points at `dc3-center-auth:9300`).
## Build Instructions
```bash
mvn -s ../../../.mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-facade/dc3-common-facade-grpc -am package
```
## Testing
This module currently has no module-specific automated tests. Verify generated or production sources by compiling the
affected reactor from the repository root:
```bash
mvn -s .mvn/settings.xml -q -pl dc3-common/dc3-common-facade/dc3-common-facade-grpc -am -DskipTests compile
```
## Related Modules
- `dc3-common-facade-api` — facade contracts
- `dc3-common-facade-local-*` — in-process alternative used by `dc3-center-single`
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-common/dc3-common-facade/dc3-common-facade-local-auth/README.md
+9 -8
View File
@@ -10,7 +10,6 @@ local classpath — used inside the `dc3-center-single` monolith where auth, man
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-common-facade-local-auth
- **Version**: 2026.5.22
## Implementations
@@ -30,16 +29,18 @@ Active when the in-process facade mode is selected (`dc3.facade.mode=local`) and
## Build Instructions
```bash
mvn -s ../../../.mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-facade/dc3-common-facade-local-auth -am package
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-facade/dc3-common-facade-local-auth -am test
```
## Related Modules
- `dc3-common-facade-grpc` — gRPC alternative for distributed deployments
- `dc3-common-facade-local-data` / `-manager` — sibling in-process facades
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-common/dc3-common-facade/dc3-common-facade-local-data/README.md
+9 -8
View File
@@ -10,7 +10,6 @@ issuing gRPC calls — used inside the `dc3-center-single` monolith.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-common-facade-local-data
- **Version**: 2026.5.22
## Implementations
@@ -30,16 +29,18 @@ Active when the in-process facade mode is selected (`dc3.facade.mode=local`) and
## Build Instructions
```bash
mvn -s ../../../.mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-facade/dc3-common-facade-local-data -am package
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-facade/dc3-common-facade-local-data -am test
```
## Related Modules
- `dc3-common-facade-grpc` — gRPC alternative for distributed deployments
- `dc3-common-facade-local-auth` / `-manager` — sibling in-process facades
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-common/dc3-common-facade/dc3-common-facade-local-manager/README.md
+9 -8
View File
@@ -10,7 +10,6 @@ issuing gRPC calls — used inside the `dc3-center-single` monolith.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-common-facade-local-manager
- **Version**: 2026.5.22
## Implementations
@@ -31,16 +30,18 @@ classpath.
## Build Instructions
```bash
mvn -s ../../../.mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-facade/dc3-common-facade-local-manager -am package
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-facade/dc3-common-facade-local-manager -am test
```
## Related Modules
- `dc3-common-facade-grpc` — gRPC alternative for distributed deployments
- `dc3-common-facade-local-auth` / `-data` — sibling in-process facades
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-common/dc3-common-facade/dc3-common-facade-local/README.md
+30
View File
@@ -0,0 +1,30 @@
# DC3 Common Facade Local
`dc3-common-facade-local` is a dependency-only POM that aggregates every in-process facade implementation:
- `dc3-common-facade-local-auth`
- `dc3-common-facade-local-data`
- `dc3-common-facade-local-manager`
It contains no Java implementation sources. Use it for an all-in-one process that deliberately needs the complete local
surface. Other applications should depend on the narrowest domain-specific local facade to avoid unrelated transitive
dependencies.
## Usage
```xml
<dependency>
<groupId>io.github.pnoker</groupId>
<artifactId>dc3-common-facade-local</artifactId>
</dependency>
```
## Verification
Verify the aggregate and its dependencies from the repository root:
```bash
mvn -s .mvn/settings.xml -q \
-pl dc3-common/dc3-common-facade/dc3-common-facade-local -am \
-DskipTests compile
```
dc3-common/dc3-common-gateway/README.md
+12 -9
View File
@@ -10,7 +10,6 @@ factory and supporting services that validate tokens with the Auth Center before
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-common-gateway
- **Version**: 2026.5.22
## Key Components
@@ -26,7 +25,9 @@ factory and supporting services that validate tokens with the Auth Center before
```
Incoming HTTP request with Authorization: Bearer {token}
→ AuthenticGatewayFilter
→ gRPC: dc3-center-auth / TokenApi.checkTokenValid()
→ FilterServiceImpl
→ TokenFacade.checkValid()
→ distributed mode: gRPC TokenApi.CheckValid
← token valid: inject signed X-Auth-Principal header
← token invalid: return 401 Unauthorized
→ Forward to backend service
@@ -35,7 +36,15 @@ Incoming HTTP request with Authorization: Bearer {token}
## Build Instructions
```bash
mvn -s ../../.mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-gateway -am package
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-gateway -am test
```
## Related Modules
@@ -43,9 +52,3 @@ mvn -s ../../.mvn/settings.xml clean package
- `dc3-gateway` — Bootstraps this module
- `dc3-api-auth` — gRPC contract for token validation
- `dc3-center-auth` — Token validation backend
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-common/dc3-common-log/README.md
+26 -26
View File
@@ -2,46 +2,46 @@
## Overview
`dc3-common-log` is the shared logging aspect module of the IoT DC3 platform. It provides a custom AOP-based `@Logs`
annotation for declarative method-level logging across all services.
`dc3-common-log` provides the shared Logback configuration used by IoT DC3 applications. It contributes console and
rolling JSON file appenders plus the Logstash Logback encoder dependency.
The former annotation/aspect logging implementation was removed. This module does not currently register Spring
auto-configuration or provide `@Logs`, `LogsType`, or `LogsAspect` APIs.
## Module Information
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-common-log
- **Version**: 2026.5.22
## Key Components
## Resources
| Component | Purpose |
|--------------|-------------------------------------------------------------------------------|
| `@Logs` | Method annotation to enable structured logging for controller/service methods |
| `LogsType` | Enum defining log types (e.g., `SysLog`, `OpLog`) |
| `LogsAspect` | Spring AOP aspect that intercepts annotated methods and records log entries |
| Resource | Purpose |
|---|---|
| `logback.xml` | Runtime console logging and size/time-based rolling JSON files |
| `logback-test.xml` | Test logging defaults |
| `AutoConfiguration.imports` | Intentionally empty; documents that no logging aspect is registered |
## Usage
Spring Boot discovers the shared `logback.xml` from the dependency classpath. Applications normally set
`logging.file.name` in their own `application.yml`; important overrides include `DC3_LOG_LEVEL`, `LOG_FILE`,
`FILE_LOG_THRESHOLD`, and the standard `LOGBACK_ROLLINGPOLICY_*` properties.
```java
@Logs(title = "Add Driver", type = LogsType.OpLog)
@PostMapping("/add")
public Mono<R<String>> add(@Validated(Add.class) @RequestBody DriverVO entityVO) {
// method body
}
```
Keep log messages in English, use parameterized placeholders, and never log credentials, tokens, passwords, or raw
private payloads.
## Build Instructions
```bash
mvn -s ../../.mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-log -am package
```
## Testing
This module has no Java implementation classes or module-specific tests. Verify packaging from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-log -am package
```
## Related Modules
Used by controller layers in `dc3-common-auth`, `dc3-common-data`, `dc3-common-manager`.
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
Center, gateway, and driver applications consume the shared Logback resources through their module dependencies.
dc3-common/dc3-common-manager/README.md
+10 -10
View File
@@ -10,7 +10,6 @@ Center. It is wired into `dc3-center-manager`.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-common-manager
- **Version**: 2026.5.22
## Key Components
@@ -18,7 +17,7 @@ Center. It is wired into `dc3-center-manager`.
|-------------------------------|-----------------------------------------------------------------------------------------------------|
| Controllers | REST controllers for driver, device, profile, point, group, label, topic, etc. |
| Services | `DriverService`, `DeviceService`, `ProfileService`, `PointService`, `DriverRegisterService` |
| gRPC Servers (`@GrpcService`) | `DriverDriverServer`, `DriverDeviceServer`, `DriverPointServer`, `ManagerPointServer` |
| gRPC Servers (Spring `@Service`) | `DriverDriverServer`, `DriverDeviceServer`, `DriverPointServer`, `ManagerPointServer` |
| DAL Managers | `DriverManager`, `DeviceManager`, `ProfileManager`, `PointManager` (MyBatis-Plus `IService`) |
| Metadata Events | `MetadataEventPublisher`, `MetadataEventListener` — async metadata change notification via RabbitMQ |
| Scheduled Jobs | `ScheduleForManagerServiceImpl` — Quartz-based hourly statistics |
@@ -47,7 +46,15 @@ REST: update device/point
## Build Instructions
```bash
mvn -s ../../.mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-manager -am package
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-manager -am test
```
## Related Modules
@@ -56,10 +63,3 @@ mvn -s ../../.mvn/settings.xml clean package
- `dc3-api-driver` — gRPC contracts implemented by this module
- `dc3-api-manager` — Manager-side gRPC contracts implemented by this module
- `dc3-common-model` — BO/VO/DTO/DO entities
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-common/dc3-common-model/README.md
+26 -20
View File
@@ -2,24 +2,26 @@
## Overview
`dc3-common-model` is the shared domain model module of the IoT DC3 platform. It defines all base classes, domain
entities (BO/VO/DTO/DO), validation group interfaces, and query objects used across all services and drivers.
`dc3-common-model` is the shared domain model module of the IoT DC3 platform. It defines the base BO/VO/DTO classes,
MapStruct builder contracts, JSON extension models, domain enums, validation groups, and shared transport DTOs used
across services and drivers. Persistence DO classes remain in the modules that own their database tables.
## Module Information
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-common-model
- **Version**: 2026.5.22
## Key Components
### Base Classes
| Class | Purpose |
|----------|--------------------------------------------------------------------------------------------|
| `BaseBO` | Base business object — `id`, audit fields (creatorId, createTime, operatorId, operateTime) |
| `BaseDO` | Base database object (MyBatis-Plus entity with `@TableId`) |
| `BaseVO` | Base view object for REST request/response |
| Class | Purpose |
|---------------|---------------------------------------------------------------------------------------------|
| `BaseBO` | Base business object with ID, remark, and creator/operator audit fields |
| `BaseVO` | Base web view object with ID, remark, and creator/operator audit fields |
| `BaseDTO` | Base cross-process DTO with ID and audit timestamps |
| `BaseBuilder` | MapStruct conversion contract for `VO <-> BO <-> DTO` |
| `BaseExt` | Base JSON extension model used by domain-specific `*Ext` classes |
### Validation Groups
@@ -32,11 +34,14 @@ Used with `@Validated(...)` in controllers:
| `Select` | Marks fields for query operations |
| `Read` / `Auth` | Specialized validation groups |
### Common Entities
### Shared DTOs and Extensions
- `RequestHeader.PrincipalHeader` — Carries tenant/user ID extracted from gateway-injected headers
- `Pages` — Pagination parameters (current page, page size)
- `TreeNode` — Generic tree structure for hierarchical data
- `MetadataEventDTO` — Metadata-change event transferred to driver listeners
- `PointCommandDTO` / `PointCommandResultDTO` — Point command request/result payloads
- `CommandCallDTO` / `CommandCallResultDTO` — Custom command request/result payloads
- Domain-specific `*Ext` classes — JSON extension-column shapes
`RequestHeader`, `Pages`, `TreeNode`, `R<T>`, and `TenantOwned` belong to `dc3-common-public`, not this module.
## Usage Example
@@ -52,16 +57,17 @@ public Mono<R<String>> update(@Validated(Update.class) @RequestBody DriverVO ent
## Build Instructions
```bash
mvn -s ../../.mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-model -am package
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-model -am test
```
## Related Modules
Foundation for all `dc3-common-*`, `dc3-center-*`, and `dc3-driver-*` modules.
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-common/dc3-common-mqtt/README.md
+10 -10
View File
@@ -10,7 +10,6 @@ the MQTT driver and any service requiring MQTT connectivity.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-common-mqtt
- **Version**: 2026.5.22
## Key Components
@@ -49,18 +48,19 @@ MQTT driver (`dc3-driver-mqtt`) depends on this module as its primary integratio
## Build Instructions
```bash
mvn -s ../../.mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-mqtt -am package
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-mqtt -am test
```
## Related Modules
- `dc3-driver-mqtt` — Primary consumer of this module
- MQTT broker: the dev profile points at the RabbitMQ MQTT plugin (`dc3-rabbitmq:2883`); EMQX is also available via the
optional stack (`podman compose -f dc3/docker-compose-optional.yml up -d`, port `31883`)
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
optional stack (`make up-optional`, port `31883`)
dc3-common/dc3-common-postgres/README.md
+9 -8
View File
@@ -10,7 +10,6 @@ their primary storage.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-common-postgres
- **Version**: 2026.5.22
## Key Components
@@ -52,16 +51,18 @@ Each center service uses a separate Postgres schema via `currentSchema` in the J
## Build Instructions
```bash
mvn -s ../../.mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-postgres -am package
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-postgres -am test
```
## Related Modules
- `dc3-common-manager`, `dc3-common-auth`, `dc3-common-data` — Include this as a dependency for Postgres access
- `dc3-common-dal` — Builds on top of this for shared DAL entities
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-common/dc3-common-public/README.md
+16 -13
View File
@@ -2,15 +2,14 @@
## Overview
`dc3-common-public` is the foundational common utilities module of the IoT DC3 platform. It provides the universal
response wrapper (`R<T>`), base entity classes, JWT key management, HTTP client configuration, and shared utility
functions used across all platform modules.
`dc3-common-public` is the foundational public contracts and utilities module of the IoT DC3 platform. It provides the
universal response wrapper (`R<T>`), `BaseService`, shared request/pagination/tree entities, tenant markers, HTTP client
configuration, HMAC signing, and framework-neutral utility functions.
## Module Information
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-common-public
- **Version**: 2026.5.22
## Key Components
@@ -45,9 +44,11 @@ Fields: `ok` (boolean), `code` (String), `message` (String), `data` (T)
| Utility | Purpose |
|-----------------------|----------------------------------------------------------|
| `JsonUtil` | Jackson JSON serialization/deserialization helpers |
| `PrincipalHeaderUtil` | Extracts `PrincipalHeader` from reactive WebFlux context |
| `HostUtil` | Resolves host/IP information |
| `ResponseUtil` | Writes HTTP responses in WebFlux context |
| `PageUtil` | Converts and normalizes pagination objects |
| `HmacAuthSigner` | Signs and verifies trusted gateway principal headers |
WebFlux-specific `BaseController`, `PrincipalHeaderUtil`, and `ResponseUtil` belong to `dc3-common-web`.
### HTTP Client
@@ -79,15 +80,17 @@ Secret lookup order:
## Build Instructions
```bash
mvn -s ../../.mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-public -am package
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-public -am test
```
## Related Modules
Foundation for all `dc3-common-*`, `dc3-center-*`, and `dc3-driver-*` modules.
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-common/dc3-common-quartz/README.md
+9 -8
View File
@@ -10,7 +10,6 @@ and Driver modules for periodic tasks.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-common-quartz
- **Version**: 2026.5.22
## Key Components
@@ -35,15 +34,17 @@ quartzService.startScheduler();
## Build Instructions
```bash
mvn -s ../../.mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-quartz -am package
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-quartz -am test
```
## Related Modules
- `dc3-common-manager` — Uses `QuartzService` for hourly data-volume statistics jobs
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-common/dc3-common-rabbitmq/README.md
+31 -23
View File
@@ -2,34 +2,40 @@
## Overview
`dc3-common-rabbitmq` is the shared RabbitMQ configuration module of the IoT DC3 platform. It defines all topic
exchanges, queue bindings, and connection configuration used for asynchronous communication between services and
drivers.
`dc3-common-rabbitmq` is the shared RabbitMQ infrastructure module of the IoT DC3 platform. It defines the durable
platform exchanges, connection factory, message conversion, and profile activation used by services and drivers.
Domain modules own their queues and bindings.
## Module Information
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-common-rabbitmq
- **Version**: 2026.5.22
## Key Components
| Component | Purpose |
|-----------------------------|----------------------------------------------------------------------|
| `ExchangeConfig` | Declares all 5 topic exchanges as persistent Spring beans |
| `ExchangeConfig` | Declares the shared durable topic exchanges |
| `RabbitConfig` | Connection factory and Jackson-based message converter configuration |
| `RabbitmqEnvironmentConfig` | Binds RabbitMQ connection properties from environment variables |
| `ActiveRabbitProfileConfig` | Profile-conditional activation |
| `RabbitmqEnvironmentConfig` | Loads RabbitMQ environment defaults |
| `ActiveRabbitProfileConfig` | Activates the `rabbit` profile unless explicitly disabled |
## Topic Exchanges
| Exchange Bean | Exchange Name | Purpose |
|--------------------|------------------|---------------------------------------------|
| `eventExchange` | `dc3.e.event` | Driver/device status events (load-balanced) |
| `metadataExchange` | `dc3.e.metadata` | Metadata change broadcast to drivers |
| `commandExchange` | `dc3.e.command` | Commands from data service to drivers |
| `valueExchange` | `dc3.e.value` | Point values from drivers to data center |
| `mqttExchange` | `dc3.e.mqtt` | MQTT-to-platform message bridging |
| Exchange bean(s) | Base exchange name(s) | Purpose |
|---|---|---|
| `stateExchange`, `alarmExchange` | `dc3.e.state`, `dc3.e.alarm` | Driver/device state and alarm processing |
| `metadataExchange` | `dc3.e.metadata` | Metadata change broadcast to drivers |
| `pointCommandExchange` | `dc3.e.point_command` | Point read/write commands |
| `valueExchange` | `dc3.e.value` | Point values from drivers to Data Center |
| `mqttExchange` | `dc3.e.mqtt` | MQTT-to-platform message bridging |
| `stateTimeoutDelayExchange`, `stateTimeoutCheckExchange` | `dc3.e.state_timeout_delay`, `dc3.e.state_timeout_check` | Delayed state-timeout checks |
| `commandExchange`, `commandResultExchange`, `commandDeadExchange` | `dc3.e.command`, `dc3.e.command_result`, `dc3.e.command_dead` | Custom commands, results, and dead letters |
| `eventExchange` | `dc3.e.event` | Reported domain events |
`ExchangeConfig` currently declares 12 shared exchanges. Data and driver modules add queues, bindings, and specialized
dead-letter/result exchanges. The optional `dc3.rabbit.tag` system property prefixes runtime names, so use
`RabbitConstant` rather than duplicating literal names in code.
## Configuration Properties
@@ -56,18 +62,20 @@ and set Spring Boot's native `spring.rabbitmq.ssl.trust-store`, `trust-store-typ
## Build Instructions
```bash
mvn -s ../../.mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-rabbitmq -am package
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-rabbitmq -am test
```
## Related Modules
- `dc3-common-constant` / `RabbitConstant` — All exchange/queue/routing key names
- `dc3-common-data` — Consumes `dc3.e.value`, publishes to `dc3.e.command`
- `dc3-common-data` — Consumes values/state/events and publishes point/custom commands
- `dc3-common-manager` — Publishes to `dc3.e.metadata`
- `dc3-common-driver` — Consumes from `dc3.e.metadata`, `dc3.e.command`; publishes to `dc3.e.value`
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
- `dc3-common-driver` — Consumes metadata and point/custom commands; publishes values and command results
dc3-common/dc3-common-repository/README.md
+10 -9
View File
@@ -10,7 +10,6 @@ backends without coupling business logic to a specific storage implementation.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-common-repository
- **Version**: 2026.5.22
## Key Components
@@ -51,16 +50,18 @@ Set `dc3.repository.auto-profile=false` to opt out of automatic `repository` pro
## Build Instructions
```bash
mvn -s ../../.mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-repository -am package
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-repository -am test
```
## Related Modules
- `dc3-common-data` — Uses `RepositoryStrategyFactory` to route point-value persistence operations
- `dc3-common-data` — Caches latest point values with in-process `LocalCacheService` alongside repository storage
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
- `dc3-common-data` — Caches latest point values with `PointValueLocalCache` alongside repository storage
dc3-common/dc3-common-resource-registrar/README.md
+9 -8
View File
@@ -10,7 +10,6 @@ deployed, so permissions can be granted against real endpoints.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-common-resource-registrar
- **Version**: 2026.5.22
## Key Components
@@ -34,16 +33,18 @@ gRPC or in-process facade transport.
## Build Instructions
```bash
mvn -s ../../.mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-resource-registrar -am package
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-resource-registrar -am test
```
## Related Modules
- `dc3-center-*` — include this module to register their API resources
- `dc3-common-auth` — owns the resource registry on the receiving side
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-common/dc3-common-sql/README.md
+9 -8
View File
@@ -10,7 +10,6 @@ and query execution, so each database driver only supplies its dialect/connectio
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-common-sql
- **Version**: 2026.5.22
## Key Components
@@ -26,16 +25,18 @@ and query execution, so each database driver only supplies its dialect/connectio
## Build Instructions
```bash
mvn -s ../../.mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-sql -am package
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-sql -am test
```
## Related Modules
- `dc3-driver-mysql`, `dc3-driver-oracle`, `dc3-driver-postgresql`, `dc3-driver-sqlserver` — JDBC drivers that extend
`AbstractJdbcDriverCustomService`
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-common/dc3-common-test/README.md
+11 -9
View File
@@ -10,7 +10,6 @@ fixtures.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-common-test
- **Version**: 2026.5.22
## Key Components
@@ -27,21 +26,24 @@ fixtures.
## Usage
Add as a `test`-scoped dependency. Integration tests requiring real infrastructure use the Testcontainers helpers
(PostgreSQL + TimescaleDB, RabbitMQ, MQTT), which need a running container runtime (`podman`).
(PostgreSQL + TimescaleDB, RabbitMQ, MQTT), which need a Docker-compatible container runtime.
## Build Instructions
```bash
mvn -s ../../.mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-test -am package
```
## Testing
This module currently has no module-specific automated tests. Verify generated or production sources by compiling the
affected reactor from the repository root:
```bash
mvn -s .mvn/settings.xml -q -pl dc3-common/dc3-common-test -am -DskipTests compile
```
## Related Modules
- `dc3-e2e` — backend end-to-end suite built on these helpers
- Consumed test-scoped by `dc3-common-*` and `dc3-center-*` modules
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-common/dc3-common-thread/README.md
+11 -11
View File
@@ -10,7 +10,6 @@ concurrent point reads and batch message handling.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-common-thread
- **Version**: 2026.5.22
## Key Components
@@ -33,8 +32,8 @@ dc3:
## Usage
Inject the executor you need, e.g. `private final ExecutorService virtualThreadExecutor;` in `PointValueJob` /
`MqttScheduleJob`, or `private final ThreadPoolExecutor threadPoolExecutor;` in `DriverReadScheduleJob`.
Inject the executor you need, for example `virtualThreadExecutor` in `MqttScheduleJob`, or `threadPoolExecutor` in
`DriverReadScheduleJob`. Data services also inject the shared executors for concurrent persistence and message work.
> Note: Spring's `@Async` does **not** use these beans — it runs on Spring Boot's default `applicationTaskExecutor`.
> These executors are obtained by explicit constructor injection, not via `@Async`.
@@ -42,7 +41,15 @@ Inject the executor you need, e.g. `private final ExecutorService virtualThreadE
## Build Instructions
```bash
mvn -s ../../.mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-thread -am package
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-thread -am test
```
## Related Modules
@@ -50,10 +57,3 @@ mvn -s ../../.mvn/settings.xml clean package
- `dc3-common-data` / `dc3-common-mqtt` — inject `virtualThreadExecutor` for batch persistence / message handling
- `dc3-common-driver` — injects `threadPoolExecutor` for concurrent device reads
- `dc3-driver-opc-da` — injects `scheduledThreadPoolExecutor`
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-common/dc3-common-web/README.md
+16 -15
View File
@@ -10,16 +10,16 @@ REST-based center services.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-common-web
- **Version**: 2026.5.22
## Key Components
| Component | Purpose |
|-------------------|--------------------------------------------------------------------------------------|
| `WebFluxConfig` | Global WebFlux configuration (codecs, CORS, message converters) |
| `ExceptionConfig` | `@ControllerAdvice` global exception handler mapping exceptions to `R<T>` responses |
| `WebFilterConfig` | Registers global web filters (e.g., request logging, context enrichment) |
| `ResponseUtil` | Utilities for writing non-controller `ServerHttpResponse` bodies in reactive context |
| Component | Purpose |
|-------------------------|--------------------------------------------------------------------------------------|
| `WebFluxConfig` | Global WebFlux configuration (codecs, CORS, message converters) |
| `WebFluxSecurityConfig` | Security chain, public-path rules, and facade-backed authorization |
| `RequestIdWebFilter` | Adds and propagates request IDs for tracing |
| `ExceptionConfig` | `@ControllerAdvice` global exception handler mapping exceptions to `R<T>` responses |
| `ResponseUtil` | Utilities for writing non-controller `ServerHttpResponse` bodies in reactive context |
## Exception Handling
@@ -36,17 +36,18 @@ All exceptions thrown by controllers are caught by `ExceptionConfig` and mapped
## Build Instructions
```bash
mvn -s ../../.mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-web -am package
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-common/dc3-common-web -am test
```
## Related Modules
- `dc3-common-auth`, `dc3-common-data`, `dc3-common-manager` — All include this for reactive web support
- `dc3-common-public` — Provides `R<T>` response wrapper
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-coverage/README.md
+38
View File
@@ -0,0 +1,38 @@
# DC3 Coverage
`dc3-coverage` is a report-only Maven module. It aggregates JaCoCo execution data from the covered handwritten-code
modules and applies the repository's absolute coverage gate.
## Generate and Verify the Report
From the repository root:
```bash
make coverage
```
Equivalent Maven command:
```bash
mvn -s .mvn/settings.xml -B -Dmaven.test.skip=false -pl dc3-coverage -am verify
```
Outputs:
- HTML: `dc3-coverage/target/site/jacoco-aggregate/index.html`
- XML: `dc3-coverage/target/site/jacoco-aggregate/jacoco.xml`
## Gate
The minimum line and branch ratios are configured in this module's `pom.xml`. The verify phase passes the aggregate XML
to `scripts/check_coverage.py`, which checks those absolute thresholds.
There is currently no baseline-relative regression calculation. Do not describe the build as enforcing a percentage
drop against a previous commit unless such a comparison is implemented.
Use `-Dcoverage.check.skip=true` only for local diagnosis; do not disable the gate in normal CI or release validation.
## Adding covered modules
Add a dependency in `pom.xml` only for a module whose handwritten classes should contribute to the aggregate. Generated
API artifacts and deployment-only wrappers should remain excluded unless the coverage policy changes deliberately.
dc3-driver/README.md
+47
View File
@@ -0,0 +1,47 @@
# DC3 Drivers
`dc3-driver` contains protocol adapters built on `dc3-common-driver`. Each driver owns protocol I/O and user-facing
attribute metadata; the SDK owns registration, scheduling, metadata refresh, health integration, commands, and value
dispatch.
## Modules
| Family | Modules |
|---|---|
| Industrial protocols | `bacnet-ip`, `can`, `dlms`, `ethernet-ip`, `fins`, `iec104`, `melsec`, `modbus-rtu`, `modbus-tcp`, `opc-da`, `opc-ua`, `plcs7`, `sl651`, `snmp` |
| Messaging/network | `coap`, `http`, `lwm2m`, `mqtt`, `tcp-udp` |
| Databases | `mysql`, `oracle`, `postgresql`, `sqlserver` |
| Local/device buses | `ble`, `serial`, `zigbee` |
| Simulation | `virtual`, `listening-virtual` |
The following drivers currently declare incomplete protocol I/O and must be treated as work in progress: `can`, `dlms`,
`ethernet-ip`, `iec104`, `lwm2m`, `mqtt`, `opc-da`, and `zigbee`. Check the child README and implementation before
production use.
## Driver metadata
`src/main/resources/application.yml` is authoritative for:
- stable driver `code` and client/server `type`;
- driver, point, command, and event attribute codes/types/defaults;
- scheduling and health defaults;
- local buffering configuration.
Changing a driver code requires a metadata and RabbitMQ routing migration. Keep display names and remarks in English.
## Build and run
```bash
mvn -s .mvn/settings.xml -q -f dc3-driver/pom.xml -DskipTests compile
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-modbus-tcp -am test
make run SERVICE=modbus-tcp
```
Replace `modbus-tcp` with the desired driver service. A runnable driver also needs database/messaging infrastructure and
the required center services; use the root Makefile to start the appropriate stack.
## Child README requirements
Every driver README should document readiness, prerequisites, the supported attribute surface, read/write operations,
a focused test command, limitations, and any host/container device requirements. Include exact codes/defaults when they
help operators, but treat `application.yml` as the authoritative metadata definition.
dc3-driver/dc3-driver-bacnet-ip/README.md
+14 -10
View File
@@ -10,7 +10,6 @@ number, object type, object instance, and property identifier.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-driver-bacnet-ip
- **Version**: 2026.5.22
- **Driver Name**: BACnet IP Driver
## Driver Attributes (Device-level)
@@ -41,6 +40,9 @@ number, object type, object instance, and property identifier.
| Object Instance | Object instance number |
| Property ID | Property identifier |
The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and
local buffering. Keep this README aligned when those user-facing settings change.
## Prerequisites
A reachable BACnet/IP device (or simulator) on the network. Communication uses UDP, typically on port 47808.
@@ -50,23 +52,25 @@ A reachable BACnet/IP device (or simulator) on the network. Communication uses U
### 1. Start Infrastructure and Center Services
```bash
podman compose -f dc3/docker-compose-db.yml up -d
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
make up-db
make up-dev GROUP=core
```
### 2. Build and Run
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-bacnet-ip -am package
java -jar dc3-driver/dc3-driver-bacnet-ip/target/dc3-driver-bacnet-ip.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-bacnet-ip -am test
```
## Related Modules
- `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-driver/dc3-driver-ble/README.md
+14 -10
View File
@@ -10,7 +10,6 @@ characteristics.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-driver-ble
- **Version**: 2026.5.22
- **Driver Name**: Bluetooth LE Driver
## Driver Attributes (Device-level)
@@ -37,6 +36,9 @@ characteristics.
| Service UUID | GATT Service UUID |
| Characteristic UUID | GATT Characteristic UUID for writing |
The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and
local buffering. Keep this README aligned when those user-facing settings change.
## Prerequisites
A host with a Bluetooth adapter and the TinyB native library available, plus a reachable BLE peripheral exposing the
@@ -47,23 +49,25 @@ configured GATT service and characteristics.
### 1. Start Infrastructure and Center Services
```bash
podman compose -f dc3/docker-compose-db.yml up -d
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
make up-db
make up-dev GROUP=core
```
### 2. Build and Run
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-ble -am package
java -jar dc3-driver/dc3-driver-ble/target/dc3-driver-ble.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-ble -am test
```
## Related Modules
- `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-driver/dc3-driver-can/README.md
+14 -10
View File
@@ -15,7 +15,6 @@ SocketCAN interface, parsing frame payloads into device point values and sending
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-driver-can
- **Version**: 2026.5.22
- **Driver Name**: CAN Bus Driver
## Driver Attributes (Device-level)
@@ -45,6 +44,9 @@ SocketCAN interface, parsing frame payloads into device point values and sending
| CAN ID | CAN identifier to write to |
| Data | Frame data (supports `${value}`) |
The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and
local buffering. Keep this README aligned when those user-facing settings change.
## Prerequisites
A Linux host with an available SocketCAN interface (e.g. `can0`) and the `can-utils` package installed (`candump`,
@@ -55,23 +57,25 @@ A Linux host with an available SocketCAN interface (e.g. `can0`) and the `can-ut
### 1. Start Infrastructure and Center Services
```bash
podman compose -f dc3/docker-compose-db.yml up -d
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
make up-db
make up-dev GROUP=core
```
### 2. Build and Run
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-can -am package
java -jar dc3-driver/dc3-driver-can/target/dc3-driver-can.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-can -am test
```
## Related Modules
- `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-driver/dc3-driver-coap/README.md
+14 -10
View File
@@ -10,7 +10,6 @@ resource path and the write path performs CoAP PUT requests.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-driver-coap
- **Version**: 2026.5.22
- **Driver Name**: CoAP Driver
## Driver Attributes (Device-level)
@@ -28,6 +27,9 @@ resource path and the write path performs CoAP PUT requests.
| Write Path | CoAP resource path for writing point data |
| Content Format | Content format: json, text, cbor, octet-stream |
The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and
local buffering. Keep this README aligned when those user-facing settings change.
## Prerequisites
A reachable CoAP device (or simulator) exposing the configured resource paths. CoAP commonly uses UDP port 5683.
@@ -37,23 +39,25 @@ A reachable CoAP device (or simulator) exposing the configured resource paths. C
### 1. Start Infrastructure and Center Services
```bash
podman compose -f dc3/docker-compose-db.yml up -d
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
make up-db
make up-dev GROUP=core
```
### 2. Build and Run
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-coap -am package
java -jar dc3-driver/dc3-driver-coap/target/dc3-driver-coap.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-coap -am test
```
## Related Modules
- `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-driver/dc3-driver-dlms/README.md
+14 -10
View File
@@ -17,7 +17,6 @@ and decode DLMS frames.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-driver-dlms
- **Version**: 2026.5.22
- **Driver Name**: DLMS/COSEM Driver
## Driver Attributes (Device-level)
@@ -42,6 +41,9 @@ and decode DLMS frames.
| Logical Name | Object logical name / OBIS code (e.g. 1.0.1.8.0.255) |
| Attribute ID | Attribute ID (2 = Present Value) |
The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and
local buffering. Keep this README aligned when those user-facing settings change.
## Prerequisites
A reachable DLMS/COSEM device (or simulator) over TCP (default port 4059) or serial, plus the matching client/ server
@@ -52,23 +54,25 @@ addresses and authentication settings.
### 1. Start Infrastructure and Center Services
```bash
podman compose -f dc3/docker-compose-db.yml up -d
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
make up-db
make up-dev GROUP=core
```
### 2. Build and Run
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-dlms -am package
java -jar dc3-driver/dc3-driver-dlms/target/dc3-driver-dlms.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-dlms -am test
```
## Related Modules
- `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-driver/dc3-driver-ethernet-ip/README.md
+14 -10
View File
@@ -17,7 +17,6 @@ services.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-driver-ethernet-ip
- **Version**: 2026.5.22
- **Driver Name**: EtherNet/IP Driver
## Driver Attributes (Device-level)
@@ -43,6 +42,9 @@ services.
|--------------|--------------------------------------|
| Send Command | Value to write (supports `${value}`) |
The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and
local buffering. Keep this README aligned when those user-facing settings change.
## Prerequisites
A reachable Rockwell Allen-Bradley (or compatible) EtherNet/IP PLC, typically on TCP port 44818.
@@ -52,23 +54,25 @@ A reachable Rockwell Allen-Bradley (or compatible) EtherNet/IP PLC, typically on
### 1. Start Infrastructure and Center Services
```bash
podman compose -f dc3/docker-compose-db.yml up -d
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
make up-db
make up-dev GROUP=core
```
### 2. Build and Run
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-ethernet-ip -am package
java -jar dc3-driver/dc3-driver-ethernet-ip/target/dc3-driver-ethernet-ip.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-ethernet-ip -am test
```
## Related Modules
- `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-driver/dc3-driver-fins/README.md
+14 -10
View File
@@ -10,7 +10,6 @@ supports the D, W, H, and C memory areas. No external protocol library is used.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-driver-fins
- **Version**: 2026.5.22
- **Driver Name**: Omron FINS Driver
## Driver Attributes (Device-level)
@@ -43,6 +42,9 @@ supports the D, W, H, and C memory areas. No external protocol library is used.
| Address | Word address within the area |
| Data Type | Value data type |
The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and
local buffering. Keep this README aligned when those user-facing settings change.
## Prerequisites
A reachable Omron PLC speaking FINS over TCP, typically on port 9600.
@@ -52,23 +54,25 @@ A reachable Omron PLC speaking FINS over TCP, typically on port 9600.
### 1. Start Infrastructure and Center Services
```bash
podman compose -f dc3/docker-compose-db.yml up -d
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
make up-db
make up-dev GROUP=core
```
### 2. Build and Run
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-fins -am package
java -jar dc3-driver/dc3-driver-fins/target/dc3-driver-fins.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-fins -am test
```
## Related Modules
- `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-driver/dc3-driver-http/README.md
+14 -10
View File
@@ -10,7 +10,6 @@ via request body templates containing a `${value}` placeholder.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-driver-http
- **Version**: 2026.5.22
- **Driver Name**: HTTP REST Client Driver
## Driver Attributes (Device-level)
@@ -38,6 +37,9 @@ via request body templates containing a `${value}` placeholder.
| Path | API path for command |
| Method | HTTP method for command |
The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and
local buffering. Keep this README aligned when those user-facing settings change.
## Prerequisites
A reachable HTTP/REST endpoint that the driver can call as configured via the device's Base URL and point paths.
@@ -47,23 +49,25 @@ A reachable HTTP/REST endpoint that the driver can call as configured via the de
### 1. Start Infrastructure and Center Services
```bash
podman compose -f dc3/docker-compose-db.yml up -d
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
make up-db
make up-dev GROUP=core
```
### 2. Build and Run
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-http -am package
java -jar dc3-driver/dc3-driver-http/target/dc3-driver-http.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-http -am test
```
## Related Modules
- `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-driver/dc3-driver-iec104/README.md
+14 -10
View File
@@ -16,7 +16,6 @@ polling for IEC 104 client connections.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-driver-iec104
- **Version**: 2026.5.22
- **Driver Name**: IEC 104 Driver
## Driver Attributes (Device-level)
@@ -44,6 +43,9 @@ polling for IEC 104 client connections.
|--------------|-------------|
| Send Command | |
The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and
local buffering. Keep this README aligned when those user-facing settings change.
## Prerequisites
A reachable IEC 60870-5-104 server (substation/telecontrol device or simulator) addressable by the configured host and
@@ -54,23 +56,25 @@ port.
### 1. Start Infrastructure and Center Services
```bash
podman compose -f dc3/docker-compose-db.yml up -d
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
make up-db
make up-dev GROUP=core
```
### 2. Build and Run
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-iec104 -am package
java -jar dc3-driver/dc3-driver-iec104/target/dc3-driver-iec104.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-iec104 -am test
```
## Related Modules
- `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-driver/dc3-driver-listening-virtual/README.md
+14 -10
View File
@@ -10,7 +10,6 @@ patterns supporting both TCP and UDP transports.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-driver-listening-virtual
- **Version**: 2026.5.22
- **Driver Name**: Listening Virtual TCP/UDP Driver
## Service Ports
@@ -31,28 +30,33 @@ patterns supporting both TCP and UDP transports.
This driver declares no device-level driver attributes; all configuration is per-point.
The module `application.yml` and its profile-specific variants are authoritative for attribute codes, types, default
values, scheduling, health, and local buffering. Keep this README aligned when that metadata changes.
## Running Locally
### 1. Start Infrastructure and Center Services
```bash
podman compose -f dc3/docker-compose-db.yml up -d
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
make up-db
make up-dev GROUP=core
```
### 2. Build and Run
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-listening-virtual -am package
java -jar dc3-driver/dc3-driver-listening-virtual/target/dc3-driver-listening-virtual.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-listening-virtual -am test
```
## Related Modules
- `dc3-common-driver` — Driver SDK for registration and RabbitMQ integration
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-driver/dc3-driver-lwm2m/README.md
+14 -10
View File
@@ -14,7 +14,6 @@ Instance / Resource ID.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-driver-lwm2m
- **Version**: 2026.5.22
- **Driver Name**: LwM2M Driver
## Driver Attributes (Device-level)
@@ -38,6 +37,9 @@ Instance / Resource ID.
| Resource ID | LwM2M Resource ID (e.g. 5700=Sensor Value) |
| Observe | Enable LwM2M Observe: true, false |
The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and
local buffering. Keep this README aligned when those user-facing settings change.
## Prerequisites
LwM2M client devices that register with the embedded Leshan server. The server binds to the configured `Server Host` /
@@ -48,23 +50,25 @@ LwM2M client devices that register with the embedded Leshan server. The server b
### 1. Start Infrastructure and Center Services
```bash
podman compose -f dc3/docker-compose-db.yml up -d
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
make up-db
make up-dev GROUP=core
```
### 2. Build and Run
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-lwm2m -am package
java -jar dc3-driver/dc3-driver-lwm2m/target/dc3-driver-lwm2m.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-lwm2m -am test
```
## Related Modules
- `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-driver/dc3-driver-melsec/README.md
+14 -10
View File
@@ -10,7 +10,6 @@ the MC protocol using the `iot-communication` library, reading and writing devic
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-driver-melsec
- **Version**: 2026.5.22
- **Driver Name**: Mitsubishi Melsec Driver
## Driver Attributes (Device-level)
@@ -28,6 +27,9 @@ the MC protocol using the `iot-communication` library, reading and writing devic
| Device Address | Device memory address (D100, M0, X10, W200 etc.) |
| String Length | String read length (0 for non-string types) |
The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and
local buffering. Keep this README aligned when those user-facing settings change.
## Prerequisites
A reachable Mitsubishi Melsec PLC (or simulator) exposing the MC protocol over TCP, addressable by the configured host
@@ -38,23 +40,25 @@ and port.
### 1. Start Infrastructure and Center Services
```bash
podman compose -f dc3/docker-compose-db.yml up -d
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
make up-db
make up-dev GROUP=core
```
### 2. Build and Run
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-melsec -am package
java -jar dc3-driver/dc3-driver-melsec/target/dc3-driver-melsec.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-melsec -am test
```
## Related Modules
- `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-driver/dc3-driver-modbus-rtu/README.md
+14 -10
View File
@@ -10,7 +10,6 @@ values to coils and holding registers.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-driver-modbus-rtu
- **Version**: 2026.5.22
- **Driver Name**: Modbus RTU Driver
## Driver Attributes (Device-level)
@@ -40,6 +39,9 @@ values to coils and holding registers.
| Offset | Register or coil address offset |
| Value Template | Value template rendered with command params |
The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and
local buffering. Keep this README aligned when those user-facing settings change.
## Prerequisites
A Modbus RTU slave device connected to an accessible serial port (e.g. `/dev/ttyUSB0`, `COM3`) on the host running the
@@ -50,23 +52,25 @@ driver.
### 1. Start Infrastructure and Center Services
```bash
podman compose -f dc3/docker-compose-db.yml up -d
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
make up-db
make up-dev GROUP=core
```
### 2. Build and Run
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-modbus-rtu -am package
java -jar dc3-driver/dc3-driver-modbus-rtu/target/dc3-driver-modbus-rtu.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-modbus-rtu -am test
```
## Related Modules
- `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-driver/dc3-driver-modbus-tcp/README.md
+14 -10
View File
@@ -9,7 +9,6 @@ devices, reads coil/register values periodically, and supports write commands fo
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-driver-modbus-tcp
- **Version**: 2026.5.22
- **Driver Name**: Modbus TCP Driver
## Driver Attributes (Device-level)
@@ -36,6 +35,9 @@ devices, reads coil/register values periodically, and supports write commands fo
| Offset | Register/coil address offset |
| Value Template | Template for the value to write |
The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and
local buffering. Keep this README aligned when those user-facing settings change.
## Prerequisites
A running Modbus TCP slave device or simulator accessible on the network.
@@ -45,23 +47,25 @@ A running Modbus TCP slave device or simulator accessible on the network.
### 1. Start Infrastructure and Center Services
```bash
podman compose -f dc3/docker-compose-db.yml up -d
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
make up-db
make up-dev GROUP=core
```
### 2. Build and Run
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-modbus-tcp -am package
java -jar dc3-driver/dc3-driver-modbus-tcp/target/dc3-driver-modbus-tcp.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-modbus-tcp -am test
```
## Related Modules
- `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-driver/dc3-driver-mqtt/README.md
+15 -11
View File
@@ -13,7 +13,6 @@ topics, parse incoming payloads as device point values, and forward commands to
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-driver-mqtt
- **Version**: 2026.5.22
- **Driver Name**: MQTT Driver
## Point Attributes
@@ -39,13 +38,16 @@ topics, parse incoming payloads as device point values, and forward commands to
| Event Code Path | Path to the event code in payload |
| Payload Path | Path to the event payload |
The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and
local buffering. Keep this README aligned when those user-facing settings change.
## Prerequisites
An MQTT broker must be running. The dev profile connects to the RabbitMQ MQTT plugin (`dc3-rabbitmq:2883`), which ships
with the base stack:
```bash
podman compose -f dc3/docker-compose-db.yml up -d
make up-db
```
EMQX is available as an alternative via the optional stack (`docker-compose-optional.yml`, port `31883`); point
@@ -56,24 +58,26 @@ EMQX is available as an alternative via the optional stack (`docker-compose-opti
### 1. Start Infrastructure and Center Services
```bash
podman compose -f dc3/docker-compose-db.yml up -d
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
make up-db
make up-dev GROUP=core
```
### 2. Build and Run
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-mqtt -am package
java -jar dc3-driver/dc3-driver-mqtt/target/dc3-driver-mqtt.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-mqtt -am test
```
## Related Modules
- `dc3-common-driver` — Driver SDK for registration and RabbitMQ integration
- `dc3-common-mqtt` — MQTT client configuration and utilities
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-driver/dc3-driver-mysql/README.md
+14 -10
View File
@@ -10,7 +10,6 @@
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-driver-mysql
- **Version**: 2026.5.22
- **Driver Name**: MySQL Driver
## Driver Attributes (Device-level)
@@ -37,6 +36,9 @@
|---------------|----------------------------------|
| Execute Query | SQL query to execute for command |
The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and
local buffering. Keep this README aligned when those user-facing settings change.
## Prerequisites
A reachable MySQL database addressable by the configured host, port, and credentials.
@@ -46,24 +48,26 @@ A reachable MySQL database addressable by the configured host, port, and credent
### 1. Start Infrastructure and Center Services
```bash
podman compose -f dc3/docker-compose-db.yml up -d
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
make up-db
make up-dev GROUP=core
```
### 2. Build and Run
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-mysql -am package
java -jar dc3-driver/dc3-driver-mysql/target/dc3-driver-mysql.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-mysql -am test
```
## Related Modules
- `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration
- `dc3-common-sql` — Abstract JDBC driver service (connection pooling, read/write query execution)
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-driver/dc3-driver-opc-da/README.md
+18 -10
View File
@@ -5,11 +5,14 @@
`dc3-driver-opc-da` is the OPC DA (Data Access) protocol driver of the IoT DC3 platform. It connects to OPC DA servers
using DCOM/J-Interop to read real-time process data from OPC-compliant industrial devices and SCADA systems.
> **Work in progress.** Protocol-level I/O is not fully implemented in `OpcDaDriverCustomServiceImpl`. Treat this
> module as an integration skeleton, not a production-ready OPC DA driver, until its read/write TODOs are completed and
> verified against a real server.
## Module Information
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-driver-opc-da
- **Version**: 2026.5.22
- **Driver Name**: OPC DA Driver
## Driver Attributes (Device-level)
@@ -28,6 +31,9 @@ using DCOM/J-Interop to read real-time process data from OPC-compliant industria
| Group | OPC DA item group name |
| Tag | OPC DA item tag name |
The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and
local buffering. Keep this README aligned when those user-facing settings change.
## Prerequisites
- An OPC DA server running on a Windows host accessible via DCOM
@@ -39,23 +45,25 @@ using DCOM/J-Interop to read real-time process data from OPC-compliant industria
### 1. Start Infrastructure and Center Services
```bash
podman compose -f dc3/docker-compose-db.yml up -d
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
make up-db
make up-dev GROUP=core
```
### 2. Build and Run
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-opc-da -am package
java -jar dc3-driver/dc3-driver-opc-da/target/dc3-driver-opc-da.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-opc-da -am test
```
## Related Modules
- `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-driver/dc3-driver-opc-ua/README.md
+14 -10
View File
@@ -9,7 +9,6 @@ servers to read and write node values from industrial automation systems using t
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-driver-opc-ua
- **Version**: 2026.5.22
- **Driver Name**: OPC UA Driver
## Driver Attributes (Device-level)
@@ -27,6 +26,9 @@ servers to read and write node values from industrial automation systems using t
| Namespace | OPC UA node namespace index |
| Tag | OPC UA node identifier |
The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and
local buffering. Keep this README aligned when those user-facing settings change.
## Prerequisites
An OPC UA server (e.g., Milo server, Prosys OPC UA Simulation Server) accessible on the network.
@@ -36,23 +38,25 @@ An OPC UA server (e.g., Milo server, Prosys OPC UA Simulation Server) accessible
### 1. Start Infrastructure and Center Services
```bash
podman compose -f dc3/docker-compose-db.yml up -d
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
make up-db
make up-dev GROUP=core
```
### 2. Build and Run
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-opc-ua -am package
java -jar dc3-driver/dc3-driver-opc-ua/target/dc3-driver-opc-ua.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-opc-ua -am test
```
## Related Modules
- `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-driver/dc3-driver-oracle/README.md
+14 -10
View File
@@ -11,7 +11,6 @@ queries and writes through configured `UPDATE`/`INSERT` queries. JDBC connection
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-driver-oracle
- **Version**: 2026.5.22
- **Driver Name**: Oracle Driver
## Driver Attributes (Device-level)
@@ -41,6 +40,9 @@ queries and writes through configured `UPDATE`/`INSERT` queries. JDBC connection
|---------------|----------------------------------|
| Execute Query | SQL query to execute for command |
The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and
local buffering. Keep this README aligned when those user-facing settings change.
## Prerequisites
A reachable Oracle database addressable by the configured host, port, credentials, and connection type (SID or Service
@@ -51,24 +53,26 @@ Name).
### 1. Start Infrastructure and Center Services
```bash
podman compose -f dc3/docker-compose-db.yml up -d
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
make up-db
make up-dev GROUP=core
```
### 2. Build and Run
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-oracle -am package
java -jar dc3-driver/dc3-driver-oracle/target/dc3-driver-oracle.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-oracle -am test
```
## Related Modules
- `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration
- `dc3-common-sql` — Abstract JDBC driver service (connection pooling, read/write query execution)
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-driver/dc3-driver-plcs7/README.md
+14 -10
View File
@@ -9,7 +9,6 @@
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-driver-plcs7
- **Version**: 2026.5.22
- **Driver Name**: PLC S7 Driver
## Driver Attributes (Device-level)
@@ -28,6 +27,9 @@
| Byte Offset | Byte offset within the data block |
| Bit Offset | Bit offset within the byte (for boolean points) |
The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and
local buffering. Keep this README aligned when those user-facing settings change.
## Prerequisites
- Siemens S7 PLC (S7-200 Smart, S7-1200, S7-1500 or compatible)
@@ -39,23 +41,25 @@
### 1. Start Infrastructure and Center Services
```bash
podman compose -f dc3/docker-compose-db.yml up -d
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
make up-db
make up-dev GROUP=core
```
### 2. Build and Run
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-plcs7 -am package
java -jar dc3-driver/dc3-driver-plcs7/target/dc3-driver-plcs7.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-plcs7 -am test
```
## Related Modules
- `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-driver/dc3-driver-postgresql/README.md
+14 -10
View File
@@ -11,7 +11,6 @@ JDBC URL `jdbc:postgresql://<host>:<port>/<database>` using the `org.postgresql.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-driver-postgresql
- **Version**: 2026.5.22
- **Driver Name**: PostgreSQL Driver
## Driver Attributes (Device-level)
@@ -38,6 +37,9 @@ JDBC URL `jdbc:postgresql://<host>:<port>/<database>` using the `org.postgresql.
|---------------|--------------|--------|----------------------------------|
| Execute Query | executeQuery | STRING | SQL query to execute for command |
The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and
local buffering. Keep this README aligned when those user-facing settings change.
## Prerequisites
A reachable PostgreSQL database. The connection URL, credentials, and the SQL queries to run are all supplied through
@@ -48,24 +50,26 @@ the driver and point attributes above — nothing is hardcoded.
### 1. Start Infrastructure and Center Services
```bash
podman compose -f dc3/docker-compose-db.yml up -d
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
make up-db
make up-dev GROUP=core
```
### 2. Build and Run
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-postgresql -am package
java -jar dc3-driver/dc3-driver-postgresql/target/dc3-driver-postgresql.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-postgresql -am test
```
## Related Modules
- `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration
- `dc3-common-sql` — `AbstractJdbcDriverCustomService` base class providing JDBC read/write logic
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-driver/dc3-driver-serial/README.md
+14 -10
View File
@@ -12,7 +12,6 @@ with the `${value}` placeholder substituted.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-driver-serial
- **Version**: 2026.5.22
- **Driver Name**: Serial Port Driver
## Driver Attributes (Device-level)
@@ -47,6 +46,9 @@ with the `${value}` placeholder substituted.
| Send Command | sendCommand | STRING | ${value} | HEX command template with ${value} placeholder |
| Byte Order | byteOrder | STRING | BIG | Byte order for encoding value: BIG, LITTLE |
The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and
local buffering. Keep this README aligned when those user-facing settings change.
## Prerequisites
A serial device connected to a serial port reachable from the host running the driver (e.g. `/dev/ttyUSB0`). The port
@@ -57,23 +59,25 @@ path and line parameters (baud rate, data/stop bits, parity, timeout) are suppli
### 1. Start Infrastructure and Center Services
```bash
podman compose -f dc3/docker-compose-db.yml up -d
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
make up-db
make up-dev GROUP=core
```
### 2. Build and Run
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-serial -am package
java -jar dc3-driver/dc3-driver-serial/target/dc3-driver-serial.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-serial -am test
```
## Related Modules
- `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-driver/dc3-driver-sl651/README.md
+14 -10
View File
@@ -17,7 +17,6 @@ false`); only the custom schedule and device health check are enabled.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-driver-sl651
- **Version**: 2026.5.22
- **Driver Name**: SL651 Hydrological Telemetry Driver
## Service Ports
@@ -41,6 +40,9 @@ The listen port is exposed as a driver attribute (see below) and read at startup
|---------------|-------|------|---------|-------------------------------------------------------|
| Element Index | index | INT | 0 | Zero-based index into the telemetry body element list |
The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and
local buffering. Keep this README aligned when those user-facing settings change.
## Prerequisites
SL651-2014 remote stations configured to report to this driver's listen port (default 5001). The `iot-communication`
@@ -52,23 +54,25 @@ the SL651 API is unavailable.
### 1. Start Infrastructure and Center Services
```bash
podman compose -f dc3/docker-compose-db.yml up -d
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
make up-db
make up-dev GROUP=core
```
### 2. Build and Run
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-sl651 -am package
java -jar dc3-driver/dc3-driver-sl651/target/dc3-driver-sl651.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-sl651 -am test
```
## Related Modules
- `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-driver/dc3-driver-snmp/README.md
+14 -10
View File
@@ -10,7 +10,6 @@ issue an SNMP SET, with one SNMP session cached per device.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-driver-snmp
- **Version**: 2026.5.22
- **Driver Name**: SNMP Driver
## Driver Attributes (Device-level)
@@ -41,6 +40,9 @@ issue an SNMP SET, with one SNMP session cached per device.
| OID | oid | STRING | | |
| SNMP Type | snmpType | STRING | OCTET_STRING | |
The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and
local buffering. Keep this README aligned when those user-facing settings change.
## Prerequisites
A reachable SNMP agent. The agent host/port, SNMP version, community string, and per-point OIDs are supplied through the
@@ -52,23 +54,25 @@ supports SNMP v1 and v2c.
### 1. Start Infrastructure and Center Services
```bash
podman compose -f dc3/docker-compose-db.yml up -d
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
make up-db
make up-dev GROUP=core
```
### 2. Build and Run
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-snmp -am package
java -jar dc3-driver/dc3-driver-snmp/target/dc3-driver-snmp.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-snmp -am test
```
## Related Modules
- `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-driver/dc3-driver-sqlserver/README.md
+14 -10
View File
@@ -13,7 +13,6 @@ using the `com.microsoft.sqlserver.jdbc.SQLServerDriver`.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-driver-sqlserver
- **Version**: 2026.5.22
- **Driver Name**: SQL Server Driver
## Driver Attributes (Device-level)
@@ -42,6 +41,9 @@ using the `com.microsoft.sqlserver.jdbc.SQLServerDriver`.
|---------------|--------------|--------|----------------------------------|
| Execute Query | executeQuery | STRING | SQL query to execute for command |
The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and
local buffering. Keep this README aligned when those user-facing settings change.
## Prerequisites
A reachable Microsoft SQL Server instance. The connection URL, credentials, encryption flags, and the SQL queries to run
@@ -52,24 +54,26 @@ are all supplied through the driver and point attributes above — nothing is ha
### 1. Start Infrastructure and Center Services
```bash
podman compose -f dc3/docker-compose-db.yml up -d
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
make up-db
make up-dev GROUP=core
```
### 2. Build and Run
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-sqlserver -am package
java -jar dc3-driver/dc3-driver-sqlserver/target/dc3-driver-sqlserver.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-sqlserver -am test
```
## Related Modules
- `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration
- `dc3-common-sql` — `AbstractJdbcDriverCustomService` base class providing JDBC read/write logic
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-driver/dc3-driver-tcp-udp/README.md
+14 -10
View File
@@ -14,7 +14,6 @@ directly.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-driver-tcp-udp
- **Version**: 2026.5.22
- **Driver Name**: TCP/UDP Raw Driver
## Driver Attributes (Device-level)
@@ -47,6 +46,9 @@ directly.
|--------------|-------------|--------|----------|-------------|
| Send Command | sendCommand | STRING | ${value} | |
The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and
local buffering. Keep this README aligned when those user-facing settings change.
## Prerequisites
A reachable TCP or UDP endpoint. The protocol selection, host/port, timeouts, and per-point HEX commands are supplied
@@ -57,23 +59,25 @@ through the driver and point attributes above.
### 1. Start Infrastructure and Center Services
```bash
podman compose -f dc3/docker-compose-db.yml up -d
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
make up-db
make up-dev GROUP=core
```
### 2. Build and Run
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-tcp-udp -am package
java -jar dc3-driver/dc3-driver-tcp-udp/target/dc3-driver-tcp-udp.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-tcp-udp -am test
```
## Related Modules
- `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-driver/dc3-driver-virtual/README.md
+14 -10
View File
@@ -10,7 +10,6 @@ hardware.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-driver-virtual
- **Version**: 2026.5.22
- **Driver Name**: Virtual Driver
## Driver Attributes
@@ -42,6 +41,9 @@ hardware.
## Data Collection Schedule
The module `application.yml` and its profile-specific variants are authoritative for attribute codes, types, default
values, scheduling, health, and local buffering. Keep this README aligned when that metadata changes.
Configured in `application-dev.yml`:
```yaml
@@ -57,14 +59,14 @@ dc3:
### 1. Start Infrastructure and Center Services
```bash
podman compose -f dc3/docker-compose-db.yml up -d
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
make up-db
make up-dev GROUP=core
```
### 2. Build and Run
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-virtual -am package
java -jar dc3-driver/dc3-driver-virtual/target/dc3-driver-virtual.jar
```
@@ -76,12 +78,14 @@ The driver logs show gRPC registration with Manager Center on startup:
Driver register success, service name: dc3-driver-virtual
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-virtual -am test
```
## Related Modules
- `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-driver/dc3-driver-zigbee/README.md
+14 -10
View File
@@ -17,7 +17,6 @@ attributes addressed by node IEEE address / endpoint / cluster / attribute, and
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-driver-zigbee
- **Version**: 2026.5.22
- **Driver Name**: Zigbee Driver
## Driver Attributes (Device-level)
@@ -48,6 +47,9 @@ attributes addressed by node IEEE address / endpoint / cluster / attribute, and
| Cluster ID | clusterId | INT | 0 | Cluster ID for writing |
| Attribute ID | attributeId | INT | 0 | Attribute ID for writing |
The module `application.yml` is authoritative for attribute codes, types, default values, scheduling, health, and
local buffering. Keep this README aligned when those user-facing settings change.
## Prerequisites
A Zigbee coordinator dongle connected to a serial port on the host running the driver. The dependencies bundle the
@@ -59,23 +61,25 @@ the driver attributes above (see the work-in-progress warning).
### 1. Start Infrastructure and Center Services
```bash
podman compose -f dc3/docker-compose-db.yml up -d
java -jar dc3-center/dc3-center-manager/target/dc3-center-manager.jar
make up-db
make up-dev GROUP=core
```
### 2. Build and Run
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-zigbee -am package
java -jar dc3-driver/dc3-driver-zigbee/target/dc3-driver-zigbee.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-driver/dc3-driver-zigbee -am test
```
## Related Modules
- `dc3-common-driver` — Driver SDK for registration, scheduling, and RabbitMQ integration
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-e2e/README.md
+2 -8
View File
@@ -10,7 +10,6 @@ storage, RabbitMQ delivery, and TimescaleDB hypertables.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-e2e
- **Version**: 2026.5.22
- **Packaging**: jar (test sources only)
## Test Suites
@@ -34,16 +33,11 @@ make test-e2e
# = DC3_E2E=true mvn -s .mvn/settings.xml -B -Dmaven.test.skip=false -Dskip.unit.tests=true -pl dc3-e2e -am -Pe2e verify
```
Requires a container runtime (`podman`) for the Testcontainers-backed dependencies provided by `dc3-common-test`.
Requires a Docker-compatible container runtime for the Testcontainers-backed dependencies provided by
`dc3-common-test`.
## Dependencies
- `dc3-common-test` — Testcontainers and test harnesses
- `dc3-common-model` — domain models
- `rest-assured` — HTTP assertions
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-gateway/README.md
+11 -11
View File
@@ -10,7 +10,6 @@ routing, and reverse proxying.
- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-gateway
- **Version**: 2026.5.22
- **Package**: `io.github.pnoker.gateway`
## Service Ports
@@ -73,30 +72,31 @@ Route definitions and the auth gRPC channel are shared in `dc3-common-gateway`'s
### 1. Start Infrastructure
```bash
podman compose -f dc3/docker-compose-db.yml up -d
make up-db
```
### 2. Build
```bash
mvn -s .mvn/settings.xml clean package
mvn -s .mvn/settings.xml -pl dc3-gateway -am package
```
### 3. Run (start first before any center service)
### 3. Run after the required center services are available
```bash
java -jar dc3-gateway/target/dc3-gateway.jar
```
## Testing
Run the module tests from the repository root:
```bash
mvn -s .mvn/settings.xml -pl dc3-gateway -am test
```
## Related Modules
- `dc3-common-gateway` — `Authentic` filter implementation and gateway utilities
- `dc3-api-auth` — gRPC API contracts for token validation
- `dc3-center-auth` — Token validation backend
## License
Copyright 2016-present the IoT DC3 original author or authors.
Licensed under the GNU Affero General Public License v3.0 (AGPL 3.0)
dc3-web/README.md
+38 -21
View File
@@ -1,34 +1,51 @@
## 1. Prepare
# DC3 Web
- `git`
- `Visual Studio Code`
- `nodejs` >= 22 (enforced by `engines` in `package.json`)
- `pnpm` 11.3.0 (pinned via `packageManager`), install using
`corepack enable && corepack prepare pnpm@11.3.0 --activate`
`dc3-web` is the Vue and TypeScript management frontend for IoT DC3. It communicates with the backend exclusively
through `dc3-gateway`.
## 2. Source code
## Prerequisites
- Node.js 22 or newer, as declared by `engines` in `package.json`.
- Corepack enabled.
- The pnpm version declared by `packageManager` in `package.json`.
```bash
git clone https://github.com/pnoker/iot-dc3.git
corepack enable
pnpm install
```
## 3. Develop
Use pnpm only. Do not generate npm or Yarn lockfiles. When changing the package-manager version, keep `package.json` and
the Dockerfile toolchain pin aligned.
## Develop
```bash
cd iot-dc3/dc3-web
# install
pnpm install
# run
pnpm dev
```
The dev server runs on `http://localhost:8080` and proxies API calls to the backend gateway (`http://localhost:8000`),
so start the backend stack first.
The development server uses the port and API proxy configured by `vite.config.ts` and `src/config/env/`. Its defaults
are `http://localhost:8080` for the UI and `http://localhost:8000` for the gateway. The UI can start without the backend,
but login and data requests require a running gateway and center services.
## 4. More
## Build and verify
For the full command surface (build, type-check, lint, unit/component/E2E tests), the tech stack, environment
configuration (`src/config/env/`), and project conventions, see
[`AGENTS.md`](./AGENTS.md).
```bash
pnpm check
pnpm lint:check
pnpm test:guard
pnpm test:ci
pnpm build
```
Run focused suites with `pnpm test:unit`, `pnpm test:api`, `pnpm test:component`, or `pnpm test:views`. Browser workflows
use `pnpm test:e2e`; see [tests/README.md](./tests/README.md) for the test layers and fixture policy.
## Project conventions
- Vite environment files live under `src/config/env/` and use the `APP_` prefix.
- Java 64-bit IDs are represented as strings and decoded with the existing JSONBigInt support.
- Type-only imports must use `import type` because `verbatimModuleSyntax` is enabled.
- API wrapper names mirror backend cardinality: `getXxx` for one result and `listXxx` for collections/pages/maps.
- Every router-guard branch must settle navigation.
Repository-wide architecture, commit, and verification rules are in [../AGENTS.md](../AGENTS.md).