Android - Heimdall errors, "ERROR: Failed to detect compatible download-mode device."

Start off by making sure that you're plugged into a USB 2.0 port. Then,

put the device in download-mode,

$ sudo adb reboot download

continue flashing with heimdall,

$ sudo heimdall flash --RECOVERY recovery.img

That should work,

Initialising connection...
Detecting device...
Claiming interface...
Attempt failed. Detaching driver...
Claiming interface again...
Setting up interface...

Initialising protocol...
Protocol initialisation successful.

Beginning session...

Some devices may take up to 2 minutes to respond.
Please be patient!

Session begun.

Downloading device's PIT file...
PIT file download successful.

Uploading RECOVERY
100%
RECOVERY upload successful

Ending session...
Rebooting device...
Releasing device interface...
Re-attaching kernel driver...

One possible explanation is that you have confused recovery mode and download mode which are (I have just discovered) two different things on some phones, mine included. I had the same error and switching to download-mode fixed it.

Got the same issue years later, and solved it by.. using another USB cable!

Indeed, some USB cables are only made for energy transfer and do not support data transmission

You may also want to test other USB ports and check if your device is detected with lsusb