# DC3 API Data

## Overview

`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.

## Module Information

- **Group ID**: io.github.pnoker
- **Artifact ID**: dc3-api-data
- **Version**: 2026.5.22
- **Package**: `io.github.pnoker.api.center.data`

## Proto Definitions

### point_value.proto

Defines point value query RPC calls and data structures for device data collection.

**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

```bash
# Build the module
mvn -s ../../.mvn/settings.xml clean package

# Install to local repository
mvn -s ../../.mvn/settings.xml clean install
```

## 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)