API Reference
Comprehensive reference documentation for the Kneron Host SDK (Python & C++). Control the NPU, manage memory, and execute inference pipelines.
pip install kneron-toolchainModule: kneron_api
The primary entry point for interaction with Kneron devices. Conventionally imported as kp.
Global Functions
connect(device_id: int = 0) -> Device
Connects to a specific Kneron USB accelerator.
Parameters
device_id(int): The index of the device to connect to (default: 0).
Returns
Device: A handle to the connected NPU.
Raises
DeviceNotFoundError: If no device is found at the specified index.DeviceBusyError: If the device is already in use by another process.
scan_devices() -> List[Dict]
Scans the USB bus for available Kneron devices.
Returns
[
{'index': 0, 'serial': '32310001', 'model': 'KL520'},
{'index': 1, 'serial': '32310002', 'model': 'KL720'}
]Class: Device
Represents a physical connection to an NPU.
| Description | |
|---|---|
load_model(path: str) -> Model | Uploads a compiled .nef binary to the NPU's SRAM/DRAM. |
reset() | Soft-resets the NPU firmware state. |
close() | Releases the USB handle. |
firmware_version() -> str | Returns the currently installed firmware string (e.g., "v1.3.4"). |
Class: Model
Represents a loaded neural network ready for inference.
inference(data: numpy.ndarray) -> InferenceResult
Performs a synchronous inference operation.
Parameters
data: Input tensor. For image models, usually (H, W, C) in RGB format.
Example
import cv2
img = cv2.imread("cat.jpg")
result = model.inference(img)
print(result.latency)Class: InferenceResult
Structured output from the NPU.
Properties
-
raw_output: List[np.ndarray]
Direct output tensors from the last layer. -
latency: float
NPU execution time in milliseconds. -
throughput: float
Current FPS estimate.
Helper Methods
-
parse_yolo() -> List[Box]
Auto-decodes standard YOLO output layers. -
parse_imagenet() -> TopK
Returns top-k classification indices.
#include "kneron_host_lib.h"C++ Core Library
High-performance, zero-copy API for embedded Linux and RTOS.
Typedefs
- kdp_device_t
- kdp_model_t
- kdp_status_t
Function Reference
| Signature | Description |
|---|---|
| int kdp_init(kdp_device_t* dev, int id); | Initializes the device context for a specific USB ID. |
| int kdp_load_model_file(kdp_device_t* dev, const char* path, kdp_model_t* model); | Loads model binary from filesystem. |
| int kdp_inference(kdp_device_t* dev, void* input_buf, int len, void* output_buf); | Blocking inference call. Input buffer must be 32-byte aligned. |
| int kdp_update_fw(kdp_device_t* dev, const char* scpu_path, const char* ncpu_path); | Flashes new firmware to the device flash storage. |
Example
#include <stdio.h>
#include "kneron_host_lib.h"
int main() {
kdp_device_t dev;
if (kdp_init(&dev, 0) != 0) {
printf("Failed to connect\n");
return -1;
}
// ... application logic ...
kdp_deinit(&dev);
return 0;
}Error Code Reference
These codes apply to both Python (via Exceptions) and C++ (return values).
| Code | Macro / Exception | Description | Troubleshooting |
|---|---|---|---|
| 0 | KP_SUCCESS | Operation completed. | - |
| -1 | KP_ERR_NO_DEVICE | Device not found. | Check USB connection and permissions (udev rules). |
| -2 | KP_ERR_TIMEOUT | USB Timeout. | Device may be hung. Try replugging. |
| -3 | KP_ERR_MODEL_INVALID | Bad model format. | Ensure .nef file matches the target chip (KL520 != KL720). |
| -4 | KP_ERR_MEM_ALLOC | Host memory error. | Check available RAM. |
| -5 | KP_ERR_FW_VERSION | Firmware mismatch. | Update device firmware via kneron dfu. |
| -10 | KP_ERR_AUTH_FAIL | License key invalid. | Contact sales for activation key. |