JVM Helper: Using the NSP Python SDK with Java Apps - NSP

When NSP attaches to a Java application, you access it through the standard Session interface — get_str, get_int, get_bool, and execute() all work exactly as they do for other runtimes. When you need to go further — reading a specific Java field or invoking a method by class name — session.jvm gives you a JVMSessionProxy with those primitives.

Detecting JVM apps

Filter the list_apps() results by runtime == "jvm" to identify Java processes.

apps = await client.list_apps()
jvm_apps = [a for a in apps if a.runtime == "jvm"]

for app in jvm_apps:
    print(f"{app.app_name}  pid={app.pid}  conf={app.confidence:.2f}")

Attaching to a JVM app

Attach by display name, just like any other runtime.

session = await client.attach("ArduPilot GCS")
print(f"Runtime: {session.state.runtime}")   # jvm
print(f"Confidence: {session.confidence:.2f}")

Reading state with standard accessors

The same flat dot-notation key-value map that NSP exposes for V8 and CLR apps is also available for JVM apps. Java object fields are normalized into SSF keys automatically.

altitude  = session.get_float("flight.altitude_m", 0.0)
mode      = session.get_str("flight.mode")
is_armed  = session.get_bool("flight.is_armed")
sat_count = session.get_int("gps.satellite_count", 0)

print(f"Alt={altitude:.1f}m  Mode={mode}  Armed={is_armed}  Sats={sat_count}")

Retrieve everything under a prefix to inspect the full namespace:

flight_keys = session.state.keys_with_prefix("flight.")
for key, value in flight_keys.items():
    print(f"  {key}: {value}")

Reading fields directly with `session.jvm`

session.jvm gives you read_field() for fetching a specific Java class field by fully-qualified class name. The value is returned as a native Python type.

alt    = await session.jvm.read_field("com.ardupilot.GCS", "altitude")
mode   = await session.jvm.read_field("com.ardupilot.GCS", "flightMode")
armed  = await session.jvm.read_field("com.ardupilot.GCS", "isArmed")

print(f"Alt: {alt:.1f}m  Mode: {mode}  Armed: {armed}")

Invoking Java methods

Use session.jvm.invoke() to call a Java method on the live process. Python values are coerced to JVM types based on the method’s declared signature.

# Parameterless method — returns a string
status = await session.jvm.invoke("com.ardupilot.GCS", "getStatusText")
print(status)   # "3D GPS Fix — 14 satellites"

# String argument
await session.jvm.invoke("com.ardupilot.GCS", "setMode", ["GUIDED"])

# Numeric arguments — add a waypoint
await session.jvm.invoke(
    "com.ardupilot.WaypointManager",
    "addWaypoint",
    [34.052, -118.243, 150.0],   # double, double, double
)

The raw_return field in the ActionResponse carries the JVM return value when an action maps to a method invocation. Inspect it to confirm what the method returned.

result = await session.execute(
    "get_waypoint_count",
    parameters={},
)
print(f"Waypoint count: {result.raw_return}")

Enumerating loaded classes

Use session.jvm.list_classes() to discover which classes are loaded in the target JVM. Filter by package prefix to narrow the results.

classes = await session.jvm.list_classes(prefix="com.ardupilot")
for cls in classes:
    print(cls)
# com.ardupilot.GCS
# com.ardupilot.WaypointManager
# com.ardupilot.MAVLinkConnection

Type coercion reference

Python type	JVM type
`bool`	`boolean` / `Boolean`
`int`	`int`, `long`, `short`, `byte`
`float`	`double`, `float`
`str`	`String`
`list`	`List<T>`, `T[]`
`dict`	`Map<String, Object>`
`None`	`null`

Cold probe timing

The first time NSP attaches to a JVM process, the initial probe can take 10 to 90 seconds. During this time probe_status reads "attaching" or "cold_probe". Wait for "active" before executing actions or reading fields.

apps = await client.list_apps()
target = next((a for a in apps if a.app_name == "ArduPilot GCS"), None)

if target and target.probe_status != "active":
    print(f"Probe warming up: {target.probe_status}")

After the initial attachment, JVM apps operate at a confidence range of 0.93–0.97. Call await session.refresh(fresh_probe=True) immediately after attaching to confirm the first snapshot is ready before issuing commands.

Complete example: ArduPilot telemetry monitor

ardupilot_monitor.py

import asyncio
import nelieo_nsp as nsp

async def ardupilot_monitor():
    async with nsp.NSPClient() as client:
        session = await client.attach("ArduPilot GCS")
        print(f"Connected. Runtime: {session.state.runtime}")

        # Confirm first probe is ready
        await session.refresh(fresh_probe=True)
        print(f"Confidence: {session.confidence:.2f}")

        # Discover loaded classes
        classes = await session.jvm.list_classes(prefix="com.ardupilot")
        print(f"Found {len(classes)} ArduPilot class(es)")

        # Continuous telemetry loop
        while True:
            try:
                alt    = await session.jvm.read_field("com.ardupilot.GCS", "altitude")
                mode   = await session.jvm.read_field("com.ardupilot.GCS", "flightMode")
                status = await session.jvm.invoke("com.ardupilot.GCS", "getStatusText")

                print(f"Alt={alt:.1f}m  Mode={mode}  Status: {status}")
            except nsp.NSPActionError as e:
                print(f"JVM error [{e.code}]: {e.message}")

            await asyncio.sleep(1.0)

asyncio.run(ardupilot_monitor())

​Detecting JVM apps

​Attaching to a JVM app

​Reading state with standard accessors

​Reading fields directly with session.jvm

​Invoking Java methods

​Enumerating loaded classes

​Type coercion reference

​Cold probe timing

​Complete example: ArduPilot telemetry monitor

Detecting JVM apps

Attaching to a JVM app

Reading state with standard accessors

Reading fields directly with `session.jvm`

Invoking Java methods

Enumerating loaded classes

Type coercion reference

Cold probe timing

Complete example: ArduPilot telemetry monitor