Meshtastic Java Client API Guide

client.addEventListener(new MeshtasticEventListener() {
    @Override
    public void onStartupStateChanged(StartupState previousState, StartupState newState) {
        switch (newState) {
            case SYNC_LOCAL_CONFIG -> statusLabel.setText("Reading local radio...");
            case SYNC_MESH_CONFIG -> statusLabel.setText("Reading mesh state...");
            case READY -> statusLabel.setText("Ready");
            case DISCONNECTED -> statusLabel.setText("Disconnected");
        }
    }
});

client.connect(new SerialTransport(cfg));

NodeDatabase db = new InMemoryNodeDatabase();
MeshtasticClient client = new MeshtasticClient(db);
AdminService admin = client.getAdminService();

client.addEventListener(new MeshtasticEventListener() {
    @Override
    public void onStartupStateChanged(StartupState previous, StartupState next) {
        switch (next) {
            case SYNC_LOCAL_CONFIG -> uiStore.setStatus("Reading local radio...");
            case SYNC_MESH_CONFIG -> uiStore.setStatus("Reading mesh state...");
            case READY -> uiStore.setStatus("Ready");
            case DISCONNECTED -> uiStore.setStatus("Disconnected");
        }
    }

    @Override
    public void onNodeDiscovery(NodeDiscoveryEvent event) {
        uiStore.upsertNode(event.getNode());
    }

    @Override
    public void onTelemetryUpdate(TelemetryUpdateEvent event) {
        uiStore.updateTelemetry(event.getNodeId(), event.getTelemetry());
    }

    @Override
    public void onPositionUpdate(PositionUpdateEvent event) {
        uiStore.updatePosition(event.getNodeId(), event.getPosition());
    }

    @Override
    public void onAdminModelUpdate(AdminModelUpdateEvent event) {
        // Keep settings pages in sync while app is connected.
        uiStore.markAdminSectionDirty(event.getSection(), event.getChannelIndex());
    }

    @Override
    public void onRequestLifecycleUpdate(RequestLifecycleEvent event) {
        uiStore.logRequest(
                event.getStage() + " id=" + event.getRequestId()
                        + " port=" + event.getPort()
                        + " msg=" + event.getMessage()
        );
    }
});

client.connect(new SerialTransport(cfg));

NodeDatabase db = new InMemoryNodeDatabase();
MeshtasticClient client = new MeshtasticClient(db);
AdminService admin = client.getAdminService();

CountDownLatch readyLatch = new CountDownLatch(1);

client.addEventListener(new MeshtasticEventListener() {
    @Override
    public void onStartupStateChanged(StartupState previous, StartupState next) {
        if (next == StartupState.READY) {
            readyLatch.countDown();
        }
    }

    @Override
    public void onTextMessage(ChatMessageEvent event) {
        botEngine.handleInboundMessage(event);
    }
});

client.connect(new SerialTransport(cfg));
readyLatch.await(45, TimeUnit.SECONDS);

// Periodic task: refresh security + mqtt every 10 minutes.
ScheduledExecutorService jobs = Executors.newSingleThreadScheduledExecutor();
jobs.scheduleAtFixedRate(() ->
        admin.refreshSecurityConfig()
             .thenCompose(cfgSec -> admin.refreshMqttConfig())
             .exceptionally(ex -> {
                 log.warn("Periodic refresh failed: {}", ex.getMessage());
                 return null;
             }),
        0, 10, TimeUnit.MINUTES
);

MESHTASTIC_TEST_TRANSPORT=serial \
MESHTASTIC_TEST_PORT=/dev/cu.usbmodem80B54ED11F101 \
mvn -Phardware-it verify

MESHTASTIC_TEST_TRANSPORT=tcp \
MESHTASTIC_TEST_TCP_HOST=192.168.1.40 \
MESHTASTIC_TEST_TCP_PORT=4403 \
mvn -Phardware-it verify

client.requestNodeInfo(nodeId);
client.requestPosition(nodeId);
client.requestTelemetry(nodeId);

client.requestNodeInfoAwaitPayload(nodeId);
client.requestPositionAwaitPayload(nodeId);
client.requestTelemetryAwaitPayload(nodeId);

client.requestNodeInfoAwaitPayloadOrSnapshot(nodeId, Duration.ofSeconds(15));
client.requestPositionAwaitPayloadOrSnapshot(nodeId, Duration.ofSeconds(15));
client.requestTelemetryAwaitPayloadOrSnapshot(nodeId, Duration.ofSeconds(15));

// 1) Typical direct message to a single node on the primary channel.
client.sendDirectText(targetNodeId, "hello from java");

// 2) Broadcast to the public/default chat on the primary channel.
client.sendChannelText(MeshConstants.PRIMARY_CHANNEL_INDEX, "hello mesh");

// 3) Broadcast to a specific shared channel such as channel 1 ("Test").
client.sendChannelText(1, "hello test channel");

// 4) Advanced: direct message to one node while using a non-primary
// shared channel context for encryption/key selection.
client.sendDirectText(targetNodeId, 1, "hello on channel 1");

AdminService admin = client.getAdminService();

AdminService admin = client.getAdminService();

// Immediate render from cached state
renderChannels(admin.getChannelSnapshots());
renderConfig(admin.getConfigSnapshots());
renderModules(admin.getModuleConfigSnapshots());

// On-demand refresh for a channels/security page
admin.refreshChannelsAndSecurity().thenAccept(model -> {
    renderChannels(admin.getChannelSnapshots());
    renderSecurity(admin.getConfigSnapshot(ConfigType.SECURITY_CONFIG).orElse(null));
    renderMqtt(admin.getModuleConfigSnapshot(ModuleConfigType.MQTT_CONFIG).orElse(null));
});

// Explicit deep refresh (all channel slots 0..7)
admin.refreshAllChannelsAndSecurity().thenAccept(model -> {
    renderChannels(admin.getChannelSnapshots());
});

admin.refreshCore();            // metadata + owner + core config blocks
admin.refreshCoreConfigs();     // lora/device/display/network
admin.refreshModules();         // all supported module config sections
admin.refreshMqttConfig();      // mqtt only
admin.refreshSecurityConfig();  // security only

admin.setVerificationPolicy(
        AdminVerificationPolicy.builder()
                .maxAttempts(3)
                .initialRetryDelay(Duration.ofMillis(400))
                .retryBackoffMultiplier(1.8)
                .maxRetryDelay(Duration.ofSeconds(2))
                .build()
);

CompletableFuture<AdminWriteResult> resultFuture =
        admin.setConfigResult(configPayload, true);

resultFuture.thenAccept(result -> {
    switch (result.status()) {
        case VERIFIED_APPLIED -> showSuccess("Applied and verified.");
        case ACCEPTED -> showSuccess("Accepted by radio.");
        case REJECTED -> showError("Rejected: " + result.message());
        case TIMEOUT -> showError("Timed out: " + result.message());
        case VERIFICATION_FAILED -> showWarning("Accepted but read-back mismatch.");
        case FAILED -> showError("Write failed: " + result.message());
    }
});

// Throwing validation.
ProtocolConstraints.validateChannelIndex(slot);
ProtocolConstraints.validateChannelName(channelName);
ProtocolConstraints.validateChannelPsk(pskByteString);

// Non-throwing validation for form-level error display.
List<ProtocolConstraints.ValidationIssue> issues =
        ProtocolConstraints.validateChannelIssues(channelPayload);
if (!issues.isEmpty()) {
    renderValidationErrors(issues);
}

// Name update (default verifies by readback)
admin.setChannelName(2, "meshMKT");

// Password/PSK update
admin.setChannelPassword(2, "shared-secret");
admin.setPrimaryChannelPassword("primary-secret");

Config.SecurityConfig security = Config.SecurityConfig.newBuilder()
        .setAdminChannelEnabled(true)
        .build();
admin.setSecurityConfig(security, true);

ModuleConfig.MQTTConfig mqtt = ModuleConfig.MQTTConfig.newBuilder()
        .setEnabled(true)
        .setAddress("mqtt.example.com")
        .setUsername("mesh-user")
        .build();
admin.setMqttConfig(mqtt, true);

admin.setChannelResult(2, channel, true);
admin.setConfigResult(config, true);
admin.setModuleConfigResult(moduleConfig, true);
admin.setOwnerResult(targetNodeId, "Long Name", "short", true);

// 1) Snapshot render (instant)
renderChannels(admin.getChannelSnapshots());

// 2) Refresh slots on page open
admin.refreshChannels().thenAccept(channels -> {
    renderChannels(channels);
});

// rename slot 2
admin.setChannelName(2, "meshMKT")
     .thenAccept(applied -> refreshChannelsUi());

// set password/psk on slot 2
admin.setChannelPassword(2, "shared-secret")
     .thenAccept(applied -> refreshChannelsUi());

// full channel payload update with structured status
admin.setChannelResult(2, updatedChannel, true)
     .thenAccept(this::handleWriteResult);

admin.getConfigSnapshot(ConfigType.SECURITY_CONFIG)
     .ifPresent(this::renderSecuritySnapshot);

admin.refreshSecurityConfig().thenAccept(config -> {
    if (config.hasSecurity()) {
        renderSecurity(config.getSecurity());
    }
});

Config.SecurityConfig security = Config.SecurityConfig.newBuilder()
        .setAdminChannelEnabled(true)
        .build();

admin.setSecurityConfig(security, true)
     .thenAccept(applied -> {
         if (applied) showSuccess("Security settings applied.");
         else showWarning("Security settings accepted but not verified.");
     });

admin.getModuleConfigSnapshot(ModuleConfigType.MQTT_CONFIG)
     .ifPresent(snapshot -> {
         if (snapshot.hasMqtt()) {
             renderMqtt(snapshot.getMqtt());
         }
     });

admin.refreshMqttConfig().thenAccept(moduleConfig -> {
    if (moduleConfig.hasMqtt()) {
        renderMqtt(moduleConfig.getMqtt());
    }
});

ModuleConfig.MQTTConfig mqtt = ModuleConfig.MQTTConfig.newBuilder()
        .setEnabled(true)
        .setAddress("mqtt.example.com")
        .setUsername("mesh-user")
        // set password/tls/root fields as required by your deployment
        .build();

admin.setMqttConfig(mqtt, true).thenAccept(applied -> {
    if (applied) {
        showSuccess("MQTT settings applied.");
    } else {
        showWarning("MQTT settings accepted but read-back mismatch.");
    }
});

// open page
admin.refreshDeviceConfig().thenAccept(this::renderDevice);
admin.refreshLoraConfig().thenAccept(this::renderLora);
admin.refreshNetworkConfig().thenAccept(this::renderNetwork);
admin.refreshDisplayConfig().thenAccept(this::renderDisplay);

// save page
admin.setDeviceConfig(deviceConfig, true).thenAccept(this::handleBooleanWrite);
admin.setLoraConfig(loraConfig, true).thenAccept(this::handleBooleanWrite);
admin.setNetworkConfig(networkConfig, true).thenAccept(this::handleBooleanWrite);
admin.setDisplayConfig(displayConfig, true).thenAccept(this::handleBooleanWrite);

admin.refreshModules().thenAccept(model -> {
    renderModules(admin.getModuleConfigSnapshots());
});

admin.refreshTelemetryModuleConfig().thenAccept(this::renderTelemetryModule);
admin.refreshSerialModuleConfig().thenAccept(this::renderSerialModule);
admin.refreshStoreForwardModuleConfig().thenAccept(this::renderStoreForwardModule);

private void handleWriteResult(AdminWriteResult result) {
    switch (result.status()) {
        case VERIFIED_APPLIED -> showSuccess(result.operation() + ": verified.");
        case ACCEPTED -> showSuccess(result.operation() + ": accepted.");
        case REJECTED -> showError(result.operation() + ": rejected (" + result.message() + ")");
        case TIMEOUT -> showError(result.operation() + ": timeout (" + result.message() + ")");
        case VERIFICATION_FAILED -> showWarning(result.operation() + ": verification failed.");
        case FAILED -> showError(result.operation() + ": failed (" + result.message() + ")");
    }
}