iot-dc3/dc3-api/dc3-api-driver

DC3 API Driver

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.

Services

Service	RPC	Response	Purpose
DriverApi	DriverRegister	GrpcDriverRegistrationDTO	register metadata and receive assigned configuration
DriverApi	GetById	GrpcDriverRegistrationDTO	reload registered driver metadata
DriverApi	RenewLease	stream of GrpcDriverLeaseDTO	renew one runtime lease and stream its owned-device snapshot
DeviceApi	List	GrpcOffsetPageDeviceDTO	offset page through driver-owned devices
DeviceApi	GetById	GrpcDeviceAttachDTO	get one device with attached attribute configuration
PointApi	List	GrpcOffsetPagePointDTO	offset page through driver-visible points
PointApi	GetById	GrpcPointDTO	get one point with attached configuration

Proto sources live under src/main/protobuf/api/common/driver/. The .proto files are authoritative for fields and wrapper shapes.

Registration flow

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. Each runtime instance calls DriverApi.RenewLease to renew its bounded lease and receive the devices it currently owns. Command routing uses the active owner and assignment version to fence stale instances.
5. DeviceClient and PointClient load attached configuration with GetById or List.
6. The SDK initializes protocol scheduling, metadata subscriptions, commands, and value dispatch.

Response handling example

GrpcDeviceAttachDTO attachment = deviceApiBlockingStub.getById(deviceQuery);
GrpcDeviceDTO device = attachment.getDevice();

Errors are returned through standard gRPC status codes; a successful response is the typed attachment payload.

Implementation

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.

Build and Verification

mvn -s .mvn/settings.xml -q -pl dc3-api/dc3-api-driver -am compile

After a contract change, run the matching gRPC server/client tests in dc3-common-manager and dc3-common-driver. Keep tenant context explicit when evolving registration or query messages.