AstroDMx Capture for Linux - Technical Information


Any procedures suggested on this website should be used carefully and will be at the users risk. Performing these procedures implies acceptance that the responsibility is with the user and the author of this website will not be held responsible for any problems arising from the use of these procedures.

Runtime Problems

The current version of AstroDMx Capture for Linux is 0.50.9

If the software fails to run then drop to a command prompt and execute the following commands. The error messages will show what is causing the problem, for example, if you have missing dependencies.

  • cd /usr/local/AstroDMx_Capture/bin
  • ./astrodmx_capture -D2

If the software throws a segmentation fault on startup (discovered from the procedure above) and you have had a previous version installed then you might have to delete the configuration file as detailed below and then rerun the software.

Do NOT do the following as root.

  • cd $HOME/.AstroDMx
  • rm *camera_timeouts
  • rm *config
  • rm *msg_state
  • rm *v4l2_buffers

Some Linux distributions do not support SELinux. While AstroDMx Capture does not directly use SELinux, it does require the library to run. If you have such a distribution then you will need to use my dummy SELinux library; details of which follow:

RPM Installation - Missing SELinux Dependency

If installing via the RPM package and your system does not have SELinux then you will need to install the RPM from the terminal by typing the following command before downloading the dummy SELinux library below:

  • rpm --nodeps -ivh AstroDMx_Capture*.rpm

Please note, installing an RPM without dependency checking will allow the application to install regardless of the system's dependencies. Therefore, it is possible that you might have to manually check to see which dependencies are missing and then install them via your distributions package management system.

Dummy SELinux

If the software fails to run because is missing (details obtained from running the software from the terminal) then download the archive below. This download is not an implementation of SELinux, instead it simply supplies the required dependency and reports back to AstroDMx Capture that SELinux is not available and so allows the software to run.

Once downloaded, extract the archive and copy the library to /usr/local/AstroDMx_Capture/lib

ZWO USB2 Camera Issues

The Problem

ZWO USB2 cameras can be problematic under Linux, this is due to the fact that the camera firmware uses a USB maxPacket size of 1024 instead of following the USB2 standard of 512.

Previously, in order to get these cameras to work, one had to either install the compatible firmware (available from the ZWO website) or patch the Linux Kernel. The compatible firmware fixed this problem by using a maxPacket size of 512 instead of 1024. Patching the Kernel fixed this problem by stopping Linux from blocking USB2 devices which had an invalid maxPacket size.

It is important to add that using the compatible firmware meant that ZWO USB2 cameras could not be used for 16-bit long exposures. Furthermore, patching the kernel meant that these cameras could be used in 16-bit long exposure mode.

Current kernel versions no longer block USB2 devices which have a maxPacket size greater than 512 and so, these cameras should work out-of-the-box. The author of this website is not sure when this change happened, but it appears to be somewhere between kernel versions 4.14.0 and 4.15.0.

Fixes and work-arounds

If your ZWO USB2 camera does not work in AstroDMx Capture, then there are various things that can be done. First and foremost, make sure that your operating system is fully updated and then check to see if the kernel version is higher than 4.15.0. If your kernel is lower than 4.15.0 then you might have to either patch or upgrade the kernel. More information about patching the kernel can be found at step number 2 below.

  1. EHCI / xHCI USB Controllers Issues

Some modern computers do not have a EHCI USB controller. On such computers, the xHCI controller handles all ports, including USB2. Unfortunately, the USB2 ZWO cameras do not seem to be compatible with the xHCI controller unless the compatible firmware is installed.

Furthermore, if your computer has both an xHCI and an EHCI controller, ZWO USB2 cameras still might not work unless your xHCI controller redirects USB packets to the EHCI. The following procedure will show your USB hardware configuration and will explain how to redirect packets to the EHCI.

If you computer does not have a EHCI controller then you will have to use the compatible firmware. See step 3 below for more information.

  1. Patching the Kernel

As mentioned above, modern kernels do not require patching. However, if your distribution does not offer a newer kernel version or, for whatever reason, you want to use an older version then you can patch the kernel. Note, patching the kernel will only work if your computer has an EHCI controller (see point 1).

As there are so many different distributions, I will not explain how to actually compile the kernel. For this information, please consult your distribution’s documentation.

  • Download the kernel source by following your distribution’s kernel compilation instructions. Once the kernel sources have been downloaded, edit the following source file (the path starts from the kernel source directory).
  • drivers/usb/core/config.c
  • Search the source file for “static const unsigned short high_speed_maxpacket_maxes”. You should see the following function:

static const unsigned short high_speed_maxpacket_maxes[4] =




/* Bulk should be 512, but some devices use 1024: we will warn below */




  • Edit the number, 512, (highlighted in bold) and change it to 1024. If it is 1024, then your kernel is already patched correctly. Once edited, save the source file and continue with building the kernel by using your distribution’s instructions.

The procedure above will patch the kernel so that it does not block USB2 devices which have a endpoint greater than 512. You may need to combine patching the kernel with redirecting xHCI controller packets to the EHCI controller (see point 1 above).

  1. Compatible Firmware

Finally, if none of the above work for your installation or your computer does not have an EHCI controller, then the only way to get these cameras to work is to install the compatible firmware. Previously, ZWO provided a Linux firmware flashing tool but this has since been removed from their website. Therefore, the only way to flash ZWO cameras is to use Microsoft Windows.

For more information about flashing ZWO cameras, please see the ZWO website.

USB3 Compatibility

  • It is generally considered that the USB3 protocol is fully backwards compatible with USB2. However, this is not always the case.

Let's consider a working example. The Imaging Source DFK-21AU04.AS camera operating in YUYV does not work correctly when plugged into a USB3 port (it is worth noting that this problem is limited to YUYV, other formats work perfectly). The aforementioned camera streams okay but it is impossible to change any of the camera controls. Furthermore, on some modern computers, the DFK-21AU04.AS (connected via YUYV) fails in the same way even if it is connected to a USB2 port.

Another example of this incompatibility problem can be observed with ZWO USB2 cameras. If a ZWO USB2 camera has the standard firmware loaded it might not stream if connected to a USB3 port, or in some cases, will not stream if connected to a USB2 port. For more information about using USB2 ZWO cameras, please click here.

USB3 to USB2 compatibility issues could be observed in many other ways. If you experience problems with a USB2 camera then the following workaround might help. This procedure should work on all but the newest computers but it does require that your computer has an EHCI USB controller. It will not work if your computer is a pure xHCI based machine. For pure xHCI machines, there is no workaround.


Many computers have both an xHCI and an EHCI controller, however, as detailed above, some USB2 cameras do not work correctly when connected to a xHCI controller. The following procedure will cause the xHCI controller to forward USB2 packets to the EHCI controller which solves this problem.

Drop to a command prompt and execute the following commands as root. This can be done by typing su or by prefixing the commands with sudo.

  • lspci -nn | grep USB

The output will look something like the following, the exact output will be dependent upon your hardware. Do not use the information from this sample because it will not work on your system.

00:14.0 USB controller [0c03]: Intel Corporation 7 Series/C210 Series Chipset Family USB xHCI Host Controller [8086:1e31] (rev 04)

00:1a.0 USB controller [0c03]: Intel Corporation 7 Series/C216 Chipset Family USB Enhanced Host Controller #2 [8086:1e2d] (rev 04)

00:1d.0 USB controller [0c03]: Intel Corporation 7 Series/C216 Chipset Family USB Enhanced Host Controller #1 [8086:1e26] (rev 04)

Make a note of the sequence which is highlighted in bold and then type the following command as root. If you do not see an EHCI controller (sometimes listed as an 'Enhanced Host Controller' as in the example above) listed then this procedure will not work.

  • setpci -H1 -d 8086:1e31 d0.l=0

This change will only last until the system is rebooted and so the procedure will have to be repeated each time. Once you have obtained the controller information you only need to type the setpci command. For convenience, this command can be entered into a script and then the script can be run to invoke the change when required.

Finally, disconnect and reconnect your camera.

  • Depending upon your BIOS, it might be possible to avoid this procedure by selecting USB Compatibility mode in your BIOS.

Ubuntu Unity Users

Please note, if you are using Ubuntu Unity and the UI does not render correctly then you will need to download the following archive. Once downloaded, follow the instruction below. This is required because there is an issue with Ubuntu Unity and without this file the UI will not render correctly. Once this is implemented the AstroDMx Capture UI will render with a generic theme instead of the operating system's theme.

  • Close AstroDMx Capture
  • tar xzvf ubuntu_unity.tar.gz
  • cp /usr/local/AstroDMx_Capture/lib
  • Start AstroDMx Capture

This is not required for any other operating system, including other flavours of Ubuntu or newer versions of Ubuntu that no longer use the Unity Desktop (For example, 18.04).

It is best to run the software first and if you encounter UI rendering problems, then install this library.

Known Issues

All Versions: If multiple camera controls are changed during a long exposure then the last control will take effect, all others will be cancelled. For example, if the user changes the exposure to one minute and then immediately changes the gain, then the exposure control will be cancelled. To avoid this issue, change one control and wait for the exposure to complete.

This behaviour will be changed in a future version.