Skip to main content

SDK Reference

NE503 applications use the Python package hailo_ipc_sdk. The distribution package is hailo-ipc-sdk, and the current source version is 0.4.0. The obsolete package name in older examples is not the current import path.

This page covers module selection and platform constraints. See the neoruntime-sdks Python API documentation for complete classes, parameters, and return values.

1. Confirm the package and version​

Import it as follows:

from hailo_ipc_sdk import InferenceClient, EventClient

The source directory used in image builds is python/hailo_ipc_sdk, and setup.py names the distribution hailo-ipc-sdk. Match the SDK version to the platform version; do not diagnose an installation from an old import name.

Check the installed package inside the container:

python -c "import hailo_ipc_sdk; print(hailo_ipc_sdk.__version__)"

See SDK Workflow §4 First SDK Call for image and deployment steps.

2. Choose a module by task​

These classes are exported from the hailo_ipc_sdk top level. Keep complete signatures in the SDK API documentation rather than duplicating them in application guides.

TaskClassMain capability
Single-frame and streaming AI inferenceInferenceClientinfer(), infer_batch(), subscribe(), model queries and registration
Raw video framesFdMediaClientDMA-BUF/raw-frame reads, subscriptions, and stream enumeration
Encoded videoEncodedStreamClientEncoded-frame reads and subscriptions
Event BusEventClientPublish, batch publish, subscribe, topic queries, and statistics
Device controlDeviceClient, IrCutModeLights, IR-CUT, PTZ, lens, and GPIO
Camera pipelineCameraClientISP, encoder, RTSP, OSD, configuration, and stream status
AI overlayOverlayClientConfigure and apply AI overlays
Application managementAppClientApp list, state, statistics, and logs
Audio controlAudioClient, AudioStreamClientAudio devices, capture, playback, and streams
Runtime configurationConfigApp ID, IPC endpoints, and debug settings
PluginsPluginDiscovery, PluginServerDiscover capabilities and provide plugin services

An app may combine several clients, but each client should be closed on exit. Do not rely on a forced process kill to release a long-running subscription.

3. Platform constraints​

3.1 Stream and model names come from the target device​

InferenceClient.subscribe() accepts stream, model, fps, session_id, and raw_output_only. Names are runtime resources, not SDK constants:

from hailo_ipc_sdk import FdMediaClient, InferenceClient

media = FdMediaClient()
inference = InferenceClient()

print("raw streams:", media.list_streams())
print("models:", [m.model_id for m in inference.list_models()])

Confirm the resources first, then pass them to subscribe(). Depending on firmware, camera configuration, and app manifest, stream names may be main, sub, third, or another configured value.

3.2 Use raw_output_only only for raw outputs​

for frame_seq, result in inference.subscribe(
    stream="main",
    model="person_vehicle_v1",
    fps=10,
    raw_output_only=False,
):
    for obj in result.objects:
        print(obj.label, obj.score)

Set raw_output_only=True only when your code will parse tensors itself, then read result.raw_outputs. Keep the default when you need SDK-parsed fields such as objects, classifications, or landmarks.

3.3 Streaming subscriptions are blocking iterators​

subscribe() waits for results and blocks in the for loop. Handle shutdown and close the client in finally:

try:
    for frame_seq, result in inference.subscribe(
        stream="main", model="person_vehicle_v1", fps=10
    ):
        handle(result)
finally:
    inference.close()

Stopping the generator cancels the underlying streaming RPC; close() is still the explicit cleanup action an application should keep. The same rule applies to EventClient, FdMediaClient, and DeviceClient; context managers are also supported.

3.4 Model registration is permission-controlled​

Call register_model() only when inference.allow_register_model is enabled in the manifest and the path, model ID, and runtime all satisfy their requirements. A normal inference app should declare registered models instead of registering one unconditionally at startup.

4. Endpoints and container environment​

By default the SDK connects to platform services through Unix Sockets inside the container. Environment variables can override them:

Environment variableDefault
AI_RUNTIME_ENDPOINTunix:///run/aipc/ai-runtime.sock
EVENT_BUS_ENDPOINTunix:///run/aipc/event-bus.sock
DEVICE_CONTROL_ENDPOINTunix:///run/aipc/device-control.sock
CAMERA_CONTROL_ENDPOINTunix:///run/aipc/camera-control.sock
APP_MANAGER_ENDPOINTunix:///run/aipc/app-manager.sock
SHM_BASE_PATH/run/aipc/shm
ENCODED_SOCKET_DIR/run/aipc/encoded
APP_IDunknown
DEBUG0
LOG_LEVELINFO

Usually you do not need to write these endpoints in application code. Confirm permissions and container configuration in App Reference, then use the SDK defaults.

5. Minimal inference skeleton​

The main and person_vehicle_v1 values below appear in repository examples only to show the call shape. Replace them after checking the target device as described in Section 3.1:

from hailo_ipc_sdk import InferenceClient


def main():
    inference = InferenceClient()
    try:
        for frame_seq, result in inference.subscribe(
            stream="main",
            model="person_vehicle_v1",
            fps=10,
        ):
            people = result.count_by_label("person")
            if people:
                print(f"frame={frame_seq}, people={people}")
    finally:
        inference.close()


if __name__ == "__main__":
    main()

Result fields depend on the model. Do not assume every model returns objects; declare the models, streams, and inference permissions together in app.yaml.

6. How this fits the development flow​