GuicedEE Cerial Skill | Agent Skills

GuicedEE Cerial

Lifecycle-aware serial port connectivity for GuicedEE using jSerialComm and Vert.x 5.

Core Concept

Inject @Named CerialPortConnection singletons by port number, configure with CRTP-fluent setters, and let the framework handle connection lifecycle, idle monitoring, automatic reconnect with exponential backoff, MicroProfile Health reporting, and optional OpenTelemetry tracing.

Required Flow

Add com.guicedee:cerial dependency.

Inject a named connection by port number:

@Inject @Named("1")
private CerialPortConnection connection;

Configure and connect:

connection.setBaudRate(BaudRate.$9600)
          .setDataBits(DataBits.$8)
          .setParity(Parity.None)
          .setStopBits(StopBits.$1)
          .setFlowControl(FlowControl.None)
          .connect();

Send and receive data:

// Write
connection.write("Hello, device!");

// Read (callback on Vert.x worker thread)
connection.setComPortRead((data, port) -> {
    String message = new String(data).trim();
    System.out.println("Received: " + message);
});

Configure module-info.java:

module my.app {
    requires com.guicedee.cerial;
    opens my.app.serial to com.google.guice;
}

Port Configuration

| Method | Default | Values | |---|---|---| | setBaudRate() | BaudRate.$9600 | $300 to $256000 | | setDataBits() | DataBits.$8 | $5, $6, $7, $8 | | setParity() | Parity.None | None, Odd, Even, Mark, Space | | setStopBits() | StopBits.$1 | $1, $1_5, $2 | | setFlowControl() | FlowControl.None | None, RtsCtsIn, RtsCtsOut, XonXoffIn, XonXoffOut |

Connection Status

12 states grouped into Exception, Transitional, and Active sets:

Active: Silent, Running, Logging, Simulation
Transitional: Opening, OperationInProgress, FileTransfer
Exception: Offline, Missing, Failed, InUse, GeneralException

Reconnect with Exponential Backoff

Starts at 1 s, doubles each attempt, capped at 60 s
Resets on successful reconnect
Configurable: setInitialReconnectDelaySeconds(), setMaxReconnectDelaySeconds()

Idle Monitoring

CerialIdleMonitor detects silent connections via Vert.x periodic timer. Status transitions to Silent when idle beyond threshold.

Shutdown ownership

CerialPortConnection.onDestroy() marks shutdown before cancelling reconnect and monitor timers. It detaches the native data listener before closing the port, with a bounded native-close wait. Preserve this sequence: an in-flight error callback must not schedule another reconnect during shutdown. disconnect() alone is not the terminal lifecycle operation.

Health Check

CerialHealthCheck implements @Liveness, @Readiness, @Startup and reports status of all active connections (requires health module).

Non-Negotiable Constraints

Module must requires com.guicedee.cerial;.
Ports 0–999 are pre-bound as @Named("0") through @Named("999") singletons.
Serial packages must opens to com.google.guice.
The module is registered automatically — no provides needed.
Graceful shutdown via IGuicePreDestroy closes all open ports.

Agent Skills: GuicedEE Cerial

Install this agent skill to your local

Skill Files