How to Set Up the KEdge-Gateway for Edge Computing in KCloud-Platform-IoT

The KEdge-Gateway is a lightweight, Quarkus 3.x-based edge computing module that uses Vert.x-MQTT for reactive IoT messaging and SQLite for local persistence, deployable as both JVM applications and native binaries on ARM edge devices.

Setting up the KEdge-Gateway for edge computing in KCloud-Platform-IoT establishes a high-performance bridge between resource-constrained IoT devices and cloud services. This edge gateway, located in the KEdge-Gateway/ directory of the koushenhai/kcloud-platform-iot repository, compiles to ultra-low footprint native executables ideal for ARM-based single-board computers while maintaining full MQTT broker capabilities.

Architecture and Key Components

The KEdge-Gateway architecture centers on Quarkus 3.32.2 with a reactive core designed for sub-second startup times. In KEdge-Gateway/pom.xml, the build file declares three critical dependencies: io.vertx:vertx-mqtt for asynchronous MQTT client operations, io.quarkiverse.jdbc:quarkus-jdbc-sqlite4j for embedded zero-configuration database storage, and standard Quarkus extensions for containerization.

The SQLite integration provides local persistence for device metadata and offline caching without external database dependencies. Vert.x-MQTT handles high-throughput publish/subscribe patterns with IoT sensors, while the embedded REST layer exposes health check endpoints for container orchestration platforms.

Building the KEdge-Gateway

JVM Mode Compilation

For standard deployments or development environments, build the JVM-mode artifact using Maven. The pom.xml automatically resolves Quarkus extensions and Vert.x dependencies.

# Navigate to the gateway module

cd KEdge-Gateway

# Compile the application

mvn clean package

# Run in development mode with hot-reload

mvn quarkus:dev

# Or execute the production JAR

java -jar target/quarkus-app/quarkus-run.jar

Native Binary Compilation for ARM Edge Devices

For production deployments on Raspberry Pi or Rockchip boards, compile to a native binary using GraalVM. This eliminates JVM overhead and reduces memory consumption to tens of megabytes.

# Build native binary using containerized GraalVM (no local GraalVM installation required)

mvn package -Pnative -Dquarkus.native.container-build=true

# The executable appears at:

# target/kedge-gateway-1.0.0-SNAPSHOT-runner

Execute the native binary directly on the target device:

chmod +x target/kedge-gateway-1.0.0-SNAPSHOT-runner
./target/kedge-gateway-1.0.0-SNAPSHOT-runner

Configuring Network Interfaces on ARM Devices

Edge deployments require reliable network connectivity across Ethernet, 4G, or Wi-Fi interfaces. The repository includes KEdge-Gateway/sh/arm_aarch64_network.sh, a Bash utility for managing network configurations on ARM64 devices.

Enable DHCP on Ethernet:

chmod +x sh/arm_aarch64_network.sh
sudo sh/arm_aarch64_network.sh connect_eth0_dhcp

Configure static IP addressing:

sudo sh/arm_aarch64_network.sh connect_eth0_static eth0 192.168.1.100 192.168.1.1 8.8.8.8

Scan available Wi-Fi networks:

sh/arm_aarch64_network.sh scan_wlan0

The script returns true/false status strings or interface metadata (MAC address, IP, gateway) that automation tools can parse for dynamic network provisioning.

Application Configuration and Deployment

The minimal configuration in KEdge-Gateway/src/main/resources/application.yml defines the service name and runtime parameters. Extend this file or use environment variables to specify MQTT broker URLs, Nacos service registry endpoints, and SQLite database paths.

# Example application.yml structure

quarkus:
  application:
    name: kedge-gateway
  datasource:
    db-kind: sqlite
    jdbc:
      url: jdbc:sqlite:edge_cache.db

When deploying to Kubernetes or Docker environments, override these values via ConfigMaps or environment variables rather than modifying the YAML directly. The gateway registers with the central Nacos service registry if enabled, enabling cloud-side discovery of edge nodes.

Verifying the REST Endpoint

The TestResource.java class located at KEdge-Gateway/src/main/java/org/laokou/edge/gateway/api/TestResource.java exposes a basic health check endpoint for load balancers and orchestration tools.

Test the deployment:

curl http://localhost:8080/test/

A response of test confirms the Quarkus HTTP layer, JAX-RS routing, and embedded server are functioning correctly on the edge device.

Summary

• KEdge-Gateway leverages Quarkus 3.x and Vert.x-MQTT to provide reactive MQTT messaging at the edge with minimal resource overhead.
• Build the project using standard Maven commands for JVM mode, or use -Pnative for GraalVM compilation to ARM64 binaries under 50MB.
• Configure network interfaces using the provided arm_aarch64_network.sh script, which supports DHCP, static IP assignment, and Wi-Fi scanning.
• Local persistence uses SQLite via quarkus-jdbc-sqlite4j, requiring zero external database infrastructure.
• Verify deployments using the /test endpoint defined in TestResource.java before connecting production IoT devices.

Frequently Asked Questions

What hardware platforms support KEdge-Gateway deployment?

The gateway targets ARM64 single-board computers including Raspberry Pi 4/5 and Rockchip-based devices. The native compilation support in pom.xml generates Linux ARM64 binaries, while JVM mode runs on any platform supporting Java 17 or higher.

How does KEdge-Gateway handle offline network scenarios?

The embedded SQLite database in KEdge-Gateway caches device metadata and MQTT messages locally when cloud connectivity drops. Once the network interface restored via arm_aarch64_network.sh reconnection routines, the gateway synchronizes cached state with the central Nacos registry and upstream MQTT brokers.

Can I customize the MQTT broker configuration without rebuilding?

Yes. While application.yml contains minimal defaults, override MQTT broker URLs and authentication credentials using environment variables or external configuration mounted at runtime. Quarkus configuration profiles allow maintaining separate settings for development, staging, and production edge environments without modifying the source pom.xml or Java classes.

What is the typical memory footprint of the native binary?

According to the Quarkus 3.x native compilation settings in the build configuration, the kedge-gateway-1.0.0-SNAPSHOT-runner binary typically consumes under 80MB of RAM at runtime, compared to 200MB+ for JVM mode, making it suitable for edge devices with 512MB or less total system memory.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}