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

> Learn to set up KEdge-Gateway for edge computing in KCloud-Platform-IoT. This guide covers reactive IoT messaging and local persistence on ARM devices.

- Repository: [laokou/kcloud-platform-iot](https://github.com/koushenhai/kcloud-platform-iot)
- Tags: how-to-guide
- Published: 2026-03-05

---

**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`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/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`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/pom.xml) automatically resolves Quarkus extensions and Vert.x dependencies.

```bash

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

```bash

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

```bash
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`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/KEdge-Gateway/sh/arm_aarch64_network.sh), a Bash utility for managing network configurations on ARM64 devices.

Enable DHCP on Ethernet:

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

```

Configure static IP addressing:

```bash
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:

```bash
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`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/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.

```yaml

# 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`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/TestResource.java) class located at [`KEdge-Gateway/src/main/java/org/laokou/edge/gateway/api/TestResource.java`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/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:

```bash
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`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/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`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/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`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/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`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/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`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/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`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/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.