Zequent Client SDK - Quick Start Guide

For Customers: Using the SDK in Your Project

This guide shows you how to use the Zequent Client SDK in your Java/Quarkus application.

Step 1: Add Dependency

Add the Zequent Client SDK to your pom.xml:

<dependency>
    <groupId>com.zequent.framework.client.sdk</groupId>
    <artifactId>java-client-sdk</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>

That's it for dependencies! Everything else is auto-configured.

Step 2: Configuration

Create a .env file in your project root (or configure via application.properties):

# .env
REMOTE_CONTROL_SERVICE_HOST=localhost
REMOTE_CONTROL_SERVICE_PORT=9091

MISSION_AUTONOMY_SERVICE_HOST=localhost
MISSION_AUTONOMY_SERVICE_PORT=9092

LIVE_DATA_SERVICE_HOST=localhost
LIVE_DATA_SERVICE_PORT=9093

Or copy one of our templates:

# Development
cp node_modules/zequent-client-sdk/.env.dev.example .env

# Production with Kubernetes
cp node_modules/zequent-client-sdk/.env.production.example .env

Step 3: Use the Client

Option A: With CDI Injection (Recommended)

Just inject ZequentClient - it's automatically configured!

package com.example.myapp;

import com.zequent.framework.client.sdk.ZequentClient;
import com.zequent.framework.client.sdk.models.*;
import jakarta.inject.Inject;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;

@Path("/drone")
public class DroneController {

    @Inject
    ZequentClient client;  // ← Auto-configured from .env!

    @POST
    @Path("/takeoff")
    public TakeoffResponse takeoff() {
        TakeoffRequest request = TakeoffRequest.builder()
            .sn("YOUR_DEVICE_SN")
            .latitude(47.3769)
            .longitude(8.5417)
            .altitude(100.0)
            .build();

        return client.remoteControl().takeoff(request);
    }

    @POST
    @Path("/land")
    public RemoteControlResponse land() {
        ReturnToHomeRequest request = ReturnToHomeRequest.builder()
            .sn("YOUR_DEVICE_SN")
            .build();

        return client.remoteControl().returnToHome(request);
    }
}

Option B: Standalone (without CDI)

If you're not using Quarkus/CDI:

package com.example.myapp;

import com.zequent.framework.client.sdk.ZequentClient;
import com.zequent.framework.client.sdk.config.ServiceConfig;

public class MyApp {

    public static void main(String[] args) {
        try (ZequentClient client = ZequentClient.builder()
                .remoteControl()
                    .host("localhost")
                    .port(9091)
                    .done()
                .build()) {

            var request = TakeoffRequest.builder()
                .sn("YOUR_DEVICE_SN")
                .latitude(47.3769)
                .longitude(8.5417)
                .altitude(100.0)
                .build();

            var response = client.remoteControl().takeoff(request);
            System.out.println("Success: " + response.isSuccess());
        }
    }
}

Complete Example

Here's a complete REST API using the Zequent SDK:

package com.example.drone;

import com.zequent.framework.client.sdk.ZequentClient;
import com.zequent.framework.client.sdk.models.*;
import jakarta.inject.Inject;
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.MediaType;

@Path("/api/drone")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class DroneAPI {

    @Inject
    ZequentClient zequent;  // ← Just inject!

    // Flight Operations
    @POST
    @Path("/{sn}/takeoff")
    public TakeoffResponse takeoff(
            @PathParam("sn") String sn,
            @QueryParam("lat") double latitude,
            @QueryParam("lon") double longitude,
            @QueryParam("alt") double altitude) {

        var request = TakeoffRequest.builder()
            .sn(sn)
            .latitude(latitude)
            .longitude(longitude)
            .altitude(altitude)
            .build();

        return zequent.remoteControl().takeoff(request);
    }

    @POST
    @Path("/{sn}/goto")
    public RemoteControlResponse goTo(
            @PathParam("sn") String sn,
            @QueryParam("lat") double latitude,
            @QueryParam("lon") double longitude,
            @QueryParam("alt") double altitude) {

        var request = GoToRequest.builder()
            .sn(sn)
            .latitude(latitude)
            .longitude(longitude)
            .altitude(altitude)
            .build();

        return zequent.remoteControl().goTo(request);
    }

    @POST
    @Path("/{sn}/return-home")
    public RemoteControlResponse returnToHome(@PathParam("sn") String sn) {
        var request = ReturnToHomeRequest.builder()
            .sn(sn)
            .build();

        return zequent.remoteControl().returnToHome(request);
    }

    // Dock Operations
    @POST
    @Path("/{sn}/dock/open-cover")
    public RemoteControlResponse openCover(@PathParam("sn") String sn) {
        var request = DockOperationRequest.builder()
            .sn(sn)
            .build();

        return zequent.remoteControl().openCover(request);
    }

    @POST
    @Path("/{sn}/dock/start-charging")
    public RemoteControlResponse startCharging(@PathParam("sn") String sn) {
        var request = DockOperationRequest.builder()
            .sn(sn)
            .build();

        return zequent.remoteControl().startCharging(request);
    }
}

Environment-Specific Configuration

Development

# .env
REMOTE_CONTROL_SERVICE_HOST=localhost
REMOTE_CONTROL_SERVICE_PORT=9091

mvn quarkus:dev

Staging (Docker Compose)

# .env
REMOTE_CONTROL_SERVICE_HOST=remote-control-service
REMOTE_CONTROL_SERVICE_PORT=9091

docker-compose up

Production (Kubernetes)

# deployment.yaml
env:
  - name: REMOTE_CONTROL_SERVICE_USE_STORK
    value: "true"
  - name: REMOTE_CONTROL_SERVICE_STORK_NAME
    value: "remote-control-service"
  - name: REMOTE_CONTROL_SERVICE_USE_PLAINTEXT
    value: "false"

Available Services

Remote Control

client.remoteControl().takeoff(...)
client.remoteControl().goTo(...)
client.remoteControl().returnToHome(...)
client.remoteControl().lookAt(...)
client.remoteControl().openCover(...)
client.remoteControl().closeCover(...)
client.remoteControl().startCharging(...)
client.remoteControl().stopCharging(...)
client.remoteControl().rebootAsset(...)

Mission Autonomy

client.missionAutonomy().createMission(...)
client.missionAutonomy().createTask(...)
client.missionAutonomy().startTask(...)
client.missionAutonomy().createScheduler(...)

Live Data

client.liveData().streamTelemetryData(request, onData, onError)

Automatic Retry - Retries failed requests (configurable) Circuit Breaker - Prevents cascading failures Load Balancing - Round-robin, random, least-requests Service Discovery - Stork integration for Kubernetes Connection Management - Keep-alive, reconnection Environment Variables - No code changes between environments

Configuration Reference

All settings can be configured via environment variables:

# Service Endpoints
REMOTE_CONTROL_SERVICE_HOST=localhost
REMOTE_CONTROL_SERVICE_PORT=9091
MISSION_AUTONOMY_SERVICE_HOST=localhost
MISSION_AUTONOMY_SERVICE_PORT=9092
LIVE_DATA_SERVICE_HOST=localhost
LIVE_DATA_SERVICE_PORT=9093

# Resilience
ZEQUENT_MAX_RETRY_ATTEMPTS=3
ZEQUENT_RETRY_DELAY_MS=1000
ZEQUENT_CIRCUIT_BREAKER_THRESHOLD=5

# Stork (for Kubernetes)
REMOTE_CONTROL_SERVICE_USE_STORK=true
REMOTE_CONTROL_SERVICE_STORK_NAME=remote-control-service

# Load Balancing
REMOTE_CONTROL_SERVICE_LOAD_BALANCER=ROUND_ROBIN  # or LEAST_REQUESTS, RANDOM

See CONFIGURATION.md for complete reference.

Troubleshooting

ZequentClient not injecting?

Check 1: Make sure you have Quarkus Arc (CDI) in your pom.xml:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-arc</artifactId>
</dependency>

Check 2: Verify your class has a CDI scope:

@ApplicationScoped  // or @RequestScoped, @Singleton
public class MyService {
    @Inject
    ZequentClient client;
}

Connection refused?

Check: Services are running on configured ports:

echo $REMOTE_CONTROL_SERVICE_HOST
echo $REMOTE_CONTROL_SERVICE_PORT
telnet $REMOTE_CONTROL_SERVICE_HOST $REMOTE_CONTROL_SERVICE_PORT

Configuration not loading?

Check: .env file is in project root and properly formatted:

ls -la .env
cat .env

Support

For issues or questions:

Documentation: CONFIGURATION.md
GitHub Issues: https://github.com/Zequent/zequent-framework/issues
Email: support@zequent.com

Summary

Add dependency to pom.xml
Create .env with service endpoints
Inject ZequentClient in your code
Use it! client.remoteControl().takeoff(...)

That's all! No interfaces to implement, no complex setup!