Documentation

edelkrone SDK User Guide

1 Getting Started

The edelkrone SDK controls edelkrone motion control equipment from Python over Bluetooth Low Energy. It supports heads, sliders, jibs, dollies, focus motors and tripods, used on their own or combined in a layout. Release 0.1 covers connecting, reading the device's identity and state, joystick control, stored poses, focus, settings and the tripod.

pip install edelkrone

A first program:

import edelkrone

for unit in edelkrone.discover():                  # units in range
    print(unit.to_json())

with edelkrone.connect(name="HeadPLUS V3") as device:
    print(device.info.to_json())                   # identity
    print(device.status.to_json())                 # current state

    device.move.joystick(pan=0.3)                  # a speed, not a target; repeat while moving
    device.move.stop()

    device.poses.store(0)                          # store the current position in slot 0
    result = device.poses.move_to(0)               # return to it
    if not result.is_success:
        print(result.reason)                       # the reason the move did not complete

The SDK follows three principles:

• Calls are synchronous. Each call returns when its operation has completed. No event loop is required. In asynchronous code, run a call in a worker thread, for example await asyncio.to_thread(device.poses.move_to, 0).
• The SDK polls the device. After connect(), the SDK requests a new reading four times per second, and device.status always holds the latest one.
• Refusals are returned; faults are raised. A request the device declines, such as a move to an empty slot, returns a result that states the reason. A failure of the connection or of a command raises an exception (section 9).

Not included in release 0.1. Targets and point mode, driving to coordinates, creating a dolly path and reading the dolly position, and timelapse. These functions are planned for later releases.

2 Connecting

2.1 edelkrone.connect()

connect() finds the unit, connects to it, reads its identity and a first reading, joins its modules if required, starts polling and returns a Device. If any of these steps fails, it raises an exception that identifies the step (section 9).

device = edelkrone.connect(name="HeadPLUS V3", mac="A4:C1:38:5E:7B:2D", timeout=20.0)

Specify a name, an address, or both; when both are given, both must match. When neither is given, the SDK connects to the only unit in range. If more than one unit is in range, the call is refused and the message lists the units found.

2.2 Finding Units in Range: edelkrone.discover()

edelkrone.discover(seconds=8.0) scans for the given time and returns every unit found as a list of Seen, ordered by signal strength. It accepts the same transport argument as connect().

for unit in edelkrone.discover():
    print(unit.to_json())

device = edelkrone.connect(mac=edelkrone.discover()[0].mac)

{"name": "HeadPLUS V3", "mac": "A4:C1:38:5E:7B:2D", "signal": -51,
 "layout": "pan_tilt_and_slide", "modules": ["SliderPLUS V6"], "recognised": true}

Connected units are not listed. A unit does not advertise while it is connected to another program or to the edelkrone application on a phone. If a powered unit in range is not listed, close any other connection to it.

2.3 Layouts

Modules mounted on a head, such as a slider, a jib or a dolly, are controlled through the head. The program connects to the head, which relays commands to its modules. device.info.modules lists the modules and device.info.layout names the layout, for example PAN_TILT_AND_SLIDE.

The two three-piece products are also layouts, and in both the program connects to the head:

• Krone X: a HeadPLUS V3 with a JibPLUS and a DollyPLUS (PAN_TILT_DOLLY_AND_JIB_PLUS).
• Krone S: a HeadPLUS V3 with a SliderPLUS and a DollyPLUS (PAN_TILT_DOLLY_AND_SLIDER).

Units that have been used together before advertise their layout, and connect() requires no further arguments. Units that have not been used together must be joined once. Pass the module addresses in with_modules; the SDK joins them by cable or by radio, as the hardware requires:

device = edelkrone.connect(mac="A4:C1:38:5E:7B:2D", with_modules=["C8:F0:9E:11:22:33"])

A combination of units that the SDK does not support is refused with NotSupported, and the message names the units.

2.4 Ending the Connection

device.disconnect() stops polling and closes the connection. If connect() opened the radio, it closes the radio as well. Calling it more than once has no further effect. A Device is a context manager, so a with block closes the connection in all cases:

with edelkrone.connect(name="SliderPLUS V6") as device:
    device.move.joystick(slide=0.2)
    time.sleep(1.0)
    device.move.stop()

Stop the equipment before disconnecting. Disconnecting does not stop moving equipment. Call device.move.stop() first, and place both calls in a finally block so that the equipment stops if the program fails.

3 The Device

connect() returns a Device. Its info and status describe the unit, and four groups provide the operations: move, poses, focus and settings. The Device itself manages the connection:

3.1 Identity: device.info

An Info object, read when connecting and unchanged until the connection is closed. to_dict() returns it as a dictionary and to_json() as a JSON object; the field names match the Python attributes. All readings and results in the SDK provide the same two methods.

{
  "name": "HeadPLUS V3",
  "mac": "A4:C1:38:5E:7B:2D",
  "firmware": "0.31",
  "radio_firmware": "0.34",
  "firmware_ok": true,
  "layout": "pan_tilt_and_slide",
  "modules": ["SliderPLUS V6"],
  "axes": ["pan", "slide", "tilt"],
  "capabilities": ["focus", "manual_drive", "position", "settings", "stored_pose"]
}

3.2 State: device.status

A DeviceStatus object holding the latest reading, in degrees, centimetres, percent and seconds. It is held in memory, so reading it does not communicate with the device. Polling updates it four times per second, and device.refresh() requests a reading immediately. Any field may be null, which always means that the device does not report the value. For example, a slider has no pan angle and a tripod reports no battery level.

{
  "model": "HeadPLUS V3",
  "at": 1789822822.031,
  "activity": "idle",
  "pose": {"pan_deg": 89.96, "tilt_deg": 0.0, "slide_cm": 12.4, "focus_cm": null, "jib_pan_deg": null, "jib_tilt_deg": null},
  "slide_fraction": 0.31,
  "battery_percent": 82.0,
  "is_calibrated": true,
  "has_focus_motor": false,
  "layout": "pan_tilt_and_slide",
  "stored_pose_slots": [0, 3],
  "modules_responding": true,
  "move_progress": null,
  "position_is_trusted": true,
  "has_status_frame": true,
  "tilt_deg": 1.2,
  "is_level": true,
  "orientation_warning": false
}

To receive each reading as it arrives, subscribe to status_updates:

for status in device.status_updates.subscribe(max_pending=8):
    print(status.pose.pan_deg, status.battery_percent)

A subscription is a queue that the program reads at its own pace. max_pending sets how many readings it holds (256 by default); when it is full, the oldest reading is discarded. Read the subscription on a separate thread and do not send commands from within it: the SDK refuses a command sent from a subscription callback, because the reply would have to be delivered on the thread that is waiting for it.

4 Moving

4.1 Joystick Control: device.move.joystick()

joystick() sets a speed for each axis, from −1 to 1 as a fraction of the maximum speed. It does not set a target position. The command must be repeated approximately every 100 ms for as long as the equipment is to move; when commands stop arriving, the device decelerates and stops after approximately one second. Call stop() to end the movement.

deadline = time.monotonic() + 2.0
try:
    while time.monotonic() < deadline:
        device.move.joystick(pan=0.3, tilt=-0.1)
        time.sleep(0.1)
finally:
    device.move.stop()

Axes not present in the layout are ignored, so passing zero for them has no effect. Values outside ±1 are limited to ±1. A value that is not a number is refused.

4.2 Stopping

Polling pauses during joystick control. While any joystick axis is non-zero, the SDK pauses polling to keep the joystick responsive. During this time status_updates delivers no readings and device.status keeps the last one. Polling resumes after move.stop() or a joystick command with all axes at zero.

5 Poses

A pose is the position of every axis in the layout, stored in a numbered slot on the device. move_to() returns the equipment to a stored pose; the device plans the motion so that all axes arrive at the same time.

device.poses.store(0)
result = device.poses.move_to(0, style=MoveStyle(speed=0.15, acceleration=0.4))
print(result.to_json())        # {"accepted": true, "completed": true, "duration": 3.4, "reason": null}

The result of a move is a MoveOutcome:

A MoveStyle defines how a move is performed. Its two values range from 0 to 1 as fractions of the device's maximum:

MoveStyle(speed=0.15, acceleration=0.4)             # slow, with long acceleration and deceleration
MoveStyle(speed=1.0, acceleration=0.01)             # the fastest possible move
MoveStyle()                                         # speed 0.5, acceleration 0.25: the default of move_to()
MoveStyle(speed=0.3, acceleration=0.25, loop=True)  # moves back and forth between two poses until move.stop()

speed sets the speed. acceleration sets the share of the move used for acceleration at the start and deceleration at the end. loop repeats the move back and forth.

Short moves. If the equipment is within approximately 3° of the stored pose, the device may not start the planned move. In this case move_to() returns a result with is_success set to False and a reason stating that the equipment did not move. This is a property of the device and not a fault.

Axes stored in a pose. A pose stores only the axes of the current layout. If a head is connected without its modules, its poses contain pan and tilt only. Check device.info.layout before storing poses.

6 Focus

A head with a focus motor, or a focus module on its own, sets focus as a percentage of the lens travel, from 0 at one end to 100 at the other. The motor must first learn the lens: it sets its reference, finds both ends of the travel and measures the distance between them. setup() performs these three steps. It must be called once per connection and turns the focus ring from one end to the other; the duration depends on the lens. Keep the focus ring clear while it runs.

device.focus.setup()                    # once per connection; turns the focus ring
reached = device.focus.move_to_percent(50)
print(device.focus.percent())           # current position of the focus ring

setup() is required before other operations. On a unit that reports a focus motor, the following calls raise CommandError · needs_focus_setup until setup() has been called on the current connection: the joystick, all stored-pose operations, the settings and the tripod operations. The following calls are always available: all reads (info, status, refresh(), poses.stored), move.stop() and move.wait_until_idle(), disconnect() and setup().

The reason is that a stored pose on such a unit includes the focus position, which is measured from the ends found by setup(). A pose stored or recalled before setup() would place the focus ring at an unintended position.

When connect() connects to a unit with a focus motor, it issues a UserWarning stating that setup() is required. To suppress it, use warnings.filterwarnings("ignore", message=".*focus motor.*"). Units without a focus motor are not affected.

Focus in centimetres, that is a distance to the subject, is not supported in this release.

7 Settings

The device does not acknowledge settings. The call returns once the command has been sent.

8 Tripod

A motorized tripod levels itself and raises or lowers its column. The two operations are reached through device.settings and are refused on units other than tripods.

device.settings.level_tripod()          # starts the automatic levelling

end = time.monotonic() + 3.0            # raises the column for 3 seconds
while time.monotonic() < end:
    device.settings.drive_tripod(40)
    time.sleep(0.2)
device.settings.drive_tripod(0)         # stops the column

The tripod does not acknowledge these commands. The calls return once the command has been sent.

9 Errors

The SDK distinguishes two kinds of failure. A refusal, such as an empty slot, a slider that is not referenced or a move that did not start, is returned as a result with is_success and a reason. A fault raises one of three exceptions, all subclasses of edelkrone.Error. Each carries a reason code, a message and a cause with technical details for support requests.

try:
    device = edelkrone.connect(name="HeadPLUS V3")
except edelkrone.ConnectionError as e:
    print(f"{e.reason}: {e.message}")        # not_found: HeadPLUS V3 was not seen in 20.0 s. Seen: …

Signal strength. A unit at the edge of the radio range can be found by discover() but may fail after connecting, with dropped, not_connected or no_reply. Layouts with modules are affected first. If connections are unreliable, reduce the distance to the unit.

10 Diagnostic Log

The SDK writes diagnostic messages to EdelkroneLog. The log is disabled by default. To enable it, assign a function to EdelkroneLog.sink and, optionally, set EdelkroneLog.minimum_level to an EdelkroneLogLevel: TRACE, DEBUG, INFO (the default), WARNING or ERROR.

from edelkrone import EdelkroneLog, EdelkroneLogLevel

EdelkroneLog.sink = lambda level, message: print(f"[{level.name}] {message}")
EdelkroneLog.minimum_level = EdelkroneLogLevel.DEBUG

A sink is an EdelkroneLogSink: a function that takes the level and the message. It may be called from several threads, must not raise exceptions and must return quickly. To forward messages to Python's logging module, call a logging logger from the sink.

11 API Summary

The following table lists every name exported by import edelkrone and the section that describes it.

This content is subject to change.

If you have any questions about this document, please contact edelkrone.

Copyright © 2026 edelkrone.