GortJava Framework

GortJava is a modular IoT framework for Java 21. It follows the same product shape as GortJS, but uses Gradle, Spring Boot, Java records, and hexagonal architecture so application logic can run against simulated devices, Arduino/Firmata, or custom hardware adapters without changing the use cases.

Current documented release: 0.9.0

Core Idea

• Keep application logic decoupled from hardware specifics.
• Model runtime behavior through reusable devices and event flows.
• Support the same app lifecycle with mock or firmata.
• Provide configuration, automation, persistence, REST, WebSocket, health, logs, plugins, and cluster visibility out of the box.
• Keep contracts and ports in Java modules so REST, persistence, drivers, and hardware SDKs remain replaceable adapters.

Modules

• :contracts: shared records, event envelopes, config records, plugin contracts, runtime summaries, and port interfaces.
• :events: in-memory, noop, Redis, WebSocket, and composite event buses.
• :devices: base devices plus typed sensors, actuators, and Johnny-Five-compatible generic components.
• :mock-driver: simulation driver for local development and tests.
• :firmata-driver: Arduino/Firmata driver adapter.
• :persistence: memory, file, and Redis persistence adapters.
• :core: GortApp, device orchestration, commands, automation, validation, plugins, metrics, and health.
• :runtime: reusable app bootstrap, config loading, event bridge, cluster manager, runtime logger, and admin port.
• :rest-spring-boot: REST and WebSocket exposure for a running GortApp.
• :cli: validation, runtime startup, inspection, templates, scaffolds, compatibility, plugin, and cluster commands.
• :basic-app: runnable Spring Boot example application.

What Changed In 0.9.0

• Java 21 multi-module Gradle framework split by contracts, core, adapters, runtime, REST, CLI, and app.
• JS-compatible event names such as app:ready, device:registered, device:{id}:state-changed, and device:{id}:command:executed.
• REST and WebSocket endpoints with static/JWT auth, scopes, filtered streams, replay, diagnostics, logs, audit, runtime, plugin, and cluster views.
• File, memory, and Redis persistence for event history and device state snapshots.
• Workflow engine with command, delay, event, workflow, branch, retry, schedule, and JSON if support.
• Generic component coverage aligned with the GortJS Johnny-Five registry.
• Plugin lifecycle, cluster node registration, remote command routing, event bridge adapters, and CLI scaffolds.

Quick Start

./gradlew test
./gradlew :basic-app:bootRun
./gradlew :cli:run --args='templates'

The demo app loads apps/basic-app/config/iot.config.json by default. You can switch configs with GORT_CONFIG_PATH:

GORT_CONFIG_PATH=apps/basic-app/config/iot.config.static-auth.json ./gradlew :basic-app:bootRun
GORT_CONFIG_PATH=apps/basic-app/config/iot.config.jwt-auth.json ./gradlew :basic-app:bootRun
GORT_CONFIG_PATH=apps/basic-app/config/iot.config.redis-persistence.json ./gradlew :basic-app:bootRun
GORT_CONFIG_PATH=apps/basic-app/config/iot.config.firmata.json ./gradlew :basic-app:bootRun

Minimal Example

import io.gortjava.runtime.AppRuntime;

import java.nio.file.Path;

public class Main {
  public static void main(String[] args) {
    try (var runtime = AppRuntime.fromFile(Path.of("apps/basic-app/config/iot.config.json"))) {
      runtime.start();

      System.out.println(runtime.getApp().snapshot());
      System.out.println(runtime.getAdmin().runtimeSummary());
    }
  }
}

REST Example

curl http://127.0.0.1:3000/api/gort/status
curl http://127.0.0.1:3000/api/gort/devices
curl -X POST http://127.0.0.1:3000/api/gort/devices/led1/commands \
  -H 'Content-Type: application/json' \
  -d '{"name":"blink","payload":{"interval":250}}'

WebSocket Example

ws://127.0.0.1:3000/ws?eventName=device:led1:state-changed&replay=50

When rest.auth is enabled, pass a bearer token through the Authorization header or ?token=....

Console Events

The basic app also mirrors runtime events in the Spring Boot console when runtime.logging.console is enabled:

EVENT device:temp1:sensor:reading {deviceId=temp1, deviceType=temperature, value=25.2}
EVENT rule:normal_temp_alert:executed {ruleId=normal_temp_alert}
EVENT device:led1:command:executed {deviceId=led1, deviceType=led, command=off}

Typical Use Cases

• Build a local IoT app against mock, then switch to firmata for Arduino hardware.
• Register devices, rules, workflows, persistence, plugins, and REST settings from JSON.
• Expose runtime state over REST and filtered WebSocket streams.
• Persist events and state snapshots for debugging and auditability.
• Run declarative automation rules and scheduled workflows.
• Inspect plugin catalogs, logs, audit trail, cluster state, jobs, and metrics through REST or CLI.
• Move from a single local app to a connected multi-runtime topology with a control plane.
• Bootstrap new apps, plugins, drivers, and devices with the CLI.

Product Docs

• docs/architecture.md
• apps/basic-app/README.md
• apps/basic-app/config/README.md
• apps/basic-app/keys/README.md

Module Documentation

Each module includes its own README with scope, examples, and integration notes:

• packages/contracts/README.md
• packages/events/README.md
• packages/devices/README.md
• packages/core/README.md
• packages/persistence/README.md
• packages/runtime/README.md
• packages/rest-spring-boot/README.md
• packages/cli/README.md
• packages/drivers/mock/README.md
• packages/drivers/firmata/README.md

License

MIT. See LICENSE.