Python API

Goal

Control a running instrument from Python. The Python API connects to the board, starts the selected instrument through the HTTP API, loads the generated drivers.json command metadata and calls public C++ driver methods.

The normal flow is:

1. Start or connect to an instrument.
2. Create a small Python wrapper for the C++ driver.
3. Call commands and receive typed results.

Connect to a board

from koheron import connect

host = "192.168.1.100"
client = connect(host, name="fft")

connect() calls run_instrument(host, ...), creates a TCP client and loads the generated driver command metadata. Arguments after host are passed to run_instrument, so name="fft" selects the FFT instrument.

Write a Python driver wrapper

A Python driver is a thin wrapper around the C++ driver. Use the @command() decorator to send a command before receiving the return value.

from koheron import command

class FFT:
    def __init__(self, client):
        self.client = client

    @command()
    def get_fft_size(self):
        return self.client.recv_uint32()

    @command()
    def set_input_channel(self, channel):
        pass

    @command()
    def read_psd(self):
        return self.client.recv_array((4096,), dtype='float32')

The Python class name and method names must match the exported C++ driver class and public method names in drivers.json, unless explicit names are passed to @command(classname=..., funcname=...). The decorator looks up the driver and command IDs, sends the command with the Python arguments, then runs the wrapped method to receive the result.

Application example

from koheron import connect
from fft import FFT

host = "192.168.1.100"
client = connect(host, name="fft")
fft = FFT(client)

print("FFT size:", fft.get_fft_size())
fft.set_input_channel(0)
psd = fft.read_psd()
print(psd[:10])

Upload and run an instrument

from koheron import upload_instrument, run_instrument

host = "192.168.1.100"
upload_instrument(host, "tmp/examples/alpha250/fft/fft.zip", run=True)
run_instrument(host, "fft", restart=True)

Query instrument status

from koheron import instrument_status

status = instrument_status("192.168.1.100")
print(status)

Receive typed results

Use the receive helper that matches the C++ return type:

• uint32_t: recv_uint32()
• int32_t: recv_int32()
• float: recv_float()
• double: recv_double()
• bool: recv_bool()
• std::string: recv_string()
• JSON string: recv_json()
• std::array<T, N>: recv_array(shape, dtype)
• std::vector<T>: recv_vector(dtype)
• std::tuple<...>: recv_tuple(fmt)

The client checks return-type metadata where available and raises an error if the receive helper does not match the exported C++ return type.

Send arrays and vectors

The command payload builder supports scalar arguments, strings, std::array and std::vector arguments when their C++ types are present in the generated metadata. Use NumPy arrays with matching dtype for array and vector arguments.

See also

• Documentation
• Linux C++ drivers
• Examples