This page contains known issues that may be encountered when using Orbbec SDK K4A Wrapper with Femto Bolt, along with troubleshooting tips.

Known Issues

On Linux platforms, the depth engine library requires OpenGL. If the application layer also uses OpenGL and makes cross-thread calls to OpenGL instances, context conflicts may occur, causing issues during depth engine initialization and inability to start the depth data stream properly.

If the application layer uses OpenGL rendering, the application layer needs to switch the Context under OpenGL: (https://www.khronos.org/opengl/wiki/OpenGL_and_multithreading)

Below is our solution using the glfw library:

1. Call glfwMakeContextCurrent(NULL) before starting the stream.
2. Then start the stream.
3. After the stream is finished, call glfwMakeContextCurrent(currentContext).

// github： file: tools/k4aviewer/k4adevicedockcontrol.cpp
GLFWwindow *currentContext = glfwGetCurrentContext(); // store the current context
glfwMakeContextCurrent(NULL);  // make current context to NULL

StartCameras(); //  will initialize the DepthEngine

glfwMakeContextCurrent(currentContext); // restore the current context

See GitHub Issues for other related issues.

Collecting Logs

Orbbec SDK K4A Wrapper logs are output by the underlying Orbbec SDK, by default to the Log directory under the application working directory. Logs are output in a cyclical overwrite manner to a fixed 4 files, with a default maximum of 100MB per file. It is recommended to package log files when reporting issues.

Device Not Listed in Device Manager

• Check the indicator light on the back – if blinking orange, power is insufficient. Try powering with the power adapter again. If it blinks white at that point, the USB connection is abnormal.
• Verify the power cable is connected and a USB3 port is being used for data transfer.
• Try a different USB3 port for the data connection (ports near the motherboard are recommended, e.g. rear USB ports on a PC).
• Inspect cable condition – damaged or poor quality cables can cause unreliable listings (device “blinking” in device manager).
• If connected to a laptop running on battery, the port power may be restricted.
• Restart the host computer.
• If the issue persists, there may be a compatibility problem.

K4A Viewer Cannot Open Camera

• First check the device appears in Windows Device Manager.

• Verify no other applications are using the device (e.g. Windows Camera app). Only one application can access the device at a time.
• Check log files for error messages.
• Open the Windows Camera app to verify it works properly.
• Power cycle the device, wait for streaming LED to go out, then retry using the device.
• Restart the host computer.
• Ensure latest graphics drivers are installed on the computer.
• If using your own SDK build, try the official release version if possible to resolve the issue.

Device Firmware Update Issues

• If the reported version number after update is incorrect, closing and reopening the device may be needed.
• If the device firmware update process was interrupted, repowering the device before retrying the update.

Image Quality Issues

• Launch the K4A Viewer to inspect device positioning for interference, sensor occlusion, or lens dirt.
• If the issue occurs in a specific mode, try different operating modes to narrow down the investigation.
• To work with the team on image quality issues:
  • Grab a paused snapshot from the K4A Viewer and screenshot
  • Record with the K4A Recorder, e.g. k4arecorder.exe -l 5 -r 5 output.mkv

Inconsistent or Unexpected Device Timestamps

Calling k4a_device_set_color_control can temporarily trigger timing changes in the device that may take a few captures to stabilize. Avoid calling the API in image capture loops to avoid resetting internal timing calculations per new image. Call it instead before starting cameras or when values need to change within image capture loops. Specifically avoid k4a_device_set_color_control(K4A_COLOR_CONTROL_AUTO_EXPOSURE_PRIORITY).

Using Body Tracking SDK with Unreal

To use the Body Tracking SDK with Unreal, ensure \tools is added to the PATH environment variable, and dnn_model_2_0.onnx + cudnn64_7.dll are copied to Program Files/Epic Games/UE_4.23/Engine/Binaries/Win64.

Using Femto Bolt on Headless Linux Systems

The Femto Bolt depth engine uses OpenGL on Linux. OpenGL requires a window instance, which needs a monitor connected to the system. The workaround is:

1. Enable auto-login for the user account planned for use. See this for instructions on enabling auto-login.
2. Power down the system, disconnect the display, then power on the system. Auto-login will force creation of an x-server session.
3. Connect via ssh and set the DISPLAY environment variable export DISPLAY=:0
4. Launch the Femto Bolt application.

The xtrlock utility can be used to immediately lock the screen after auto-login. Add the following command to launch the application or systemd service: bash -c “xtrlock -b”

Missing C# Documentation

Sensor SDK C++ documentation is located here.

Body Tracking SDK C++ documentation is located here.