Skip to main content

PX4FLOW Optical Flow Sensor Setup Guide

Download and Flash Firmware

Download the APM's version of PX4FLOW Firmware from: (The expanded firmware should be px4flow-klt-06Dec2014.px4)

  • Connect the PX4Flow unit to your PC via USB.
  • Make sure the I2C cable between PX4FLOW and Pixhawk is disconnected (otherwise, the Pixhawk will try to boot via PX4Flow and fail due to insufficient power).
  • Use QGroundControl to load the binary firmware downloaded in the previous section.

NOTE: Some versions of QGroundControl are missing the menu to upload custom firmware from local filesystem. Use the latest version (v2.8.0) in order to upload the custome firmware to PX4FLOW. v2.8.0 also has PX4FLOW specific settings menu with auto-video streaming. If you want to run an older version of QGroundControl, use v2.5.2 or earlier in order to be able to load custom firmware to PX4FLOW.

All release versions of QGroundControl can be found here.

Adjust Lens Focus

NOTE: Do this before mounting PX4FLOW to your vehicle as it's much easier.

  • Connect PX4FLOW to QGroundControl via USB.
  • With the latest version of QGroundControl, video is automatically streamed and displayed in the PX4FLOW specific settings menu.
  • From the parameters menu, set VIDEO_ONLY=1 in order to view high-resolution video for adjusting lens focus.
  • While view the video stream via USB, twist the focus ring on the PX4FLOW lens so that the image is focused and edges are sharp at around 3 meters (or your average hovering height, which is 1m in my case).
  • Tighten the focus ring screw once focus has been adjusted.
  • Disable high-resolution video streaming mode by setting VIDEO_ONLY parameter to 0.

Connect PX4FLOW to Pixhawk/PXF

Once lens focus has been adjusted properly, mount the PX4FLOW to the underside of your vehichle using a good anti-vibration mount. - Use DF13 4 pos connector to connect I2C port of PX4FLOW to I2C port of Pixhawk/PXF. - Pay attention to the mounting direction as described in the wiki. It's different from the orientation PX4 Native Stack uses. - Vibration can hinder the performance greatly.

Setup RangeFinder

  • It's almost always better to use LiDAR, but if you want to use the sonar module on PX4FLOW, use analog pins and connect it to ADC input of Pixhawk.
  • The sonar module that comes with 3DR PX4FLOW module is either LV-MaxSonar-EZ4 (a.k.a MB1040, according to the schematics) or HRLV-MaxSonar-EZ4 (a.k.a. MB1043, according to 3DR's site).
  • MB1040 is a low-resolution version that has 1 inch resolution and usable range of 6 to 254 inches (152mm to 6,450mm).
  • MB1043 is a high-resolution version that has 1mm resolution and usable range of 300mm to 5,000mm.
  • The following assumes you have MB1043.

Sonar Connection

  • Analog output on the EZ4 sonar is pin 3.
  • GND is pin 7.
  • Range of analog output is between 0.0v and the Vcc supplied to the sonar. So if you hook it up to 3.3 Vcc, maximum will be 3.3V. If you use 5V source, maximum output will be 5V.
  • PX4FLOW supplies 5V to the sonar, so the maximum output voltage from pin 3 is going to be roughly 5V (slightly lower in practice). Note that this fluctuates depending on the quality of power source. When powered via USB, it's usually lower than 5v, but when powered via battery and power module, it goes over 5V.


  • Make sure you connect the analog out of the sonar to Pixhawk's 6.6V ADC input.
  • DO NOT connect the PX4FLOW's sonar to the 3.3V ADC input directly as the maximum voltage will be too high for the 3.3V ADC port.
  • Pixhawk's 6.6V ADC input socket is 3 pos DF13. The center pin is the analog input. The pin on the right (when viewed from above) is the ground (if you are using pre-assembled cable from 3DR, it will be the other black cable). On Pixhawk, pin #1 (one one the left) is always Vcc on any of the DF13 sockets.
  • DO NOT connect 5V (red wire) to the sonar.

If in doubt, consult these pages. - - -

Sonar Configuration

# Analog=1, I2C=4
# Analog output on EZ4 is linear

# Analog input pin on ADC 6.6V socket is mapped to virtual pin 15.
# If you've connected the sonar to ADC 3.3V socket (using voltage converter), it will either be virtual pin 13 or 14 (ADC 3.3V socket has 2 analog input pins combined).

# EZ4 is linear and ratiometric

# Don't connect stop pin (sonar will always be on)

# The wiki says you should set this to 7m for EZ0 and EZ4, but that's for XL-MaxSonar series. HRLV-Max-Sonar-EZ4 on PX4FLOW only mesures up to 5m.
# EZ4 on PX4FLOW won't return reliable data if the distance is closer than 30cm.

# Adjust the following according to the description given by Paul Riseborough below.

# Distance in cm of the PX4FLOW unit from the ground.
# In theory, the voltage range should be between 0.293V and 4.885V (300mm to 5000mm) when Vcc = 5V for the EZ4 sonar on PX4FLOW.
# Acroding to the datasheet, EZ4 will return 4.885V at 5m when given 5V Vcc.
# 5m / 4.885v

Testing Sonar

  • Before arming with a range finder attached, you need to raise the aircraft to at least 50cm, but no more than 2m in height. Pre-arm logic checks the rangefinder's health status by confirming that both minimum and maximum values registered before arming is within certian pre-determined threshold (i.e. if the range does not go over 50cm, pre-arm check will fail. It will also fail if the reading goes over 200cm)
  • If the sonar is noisy and if it spikes to full output even for a short while before pre-arm check clears, you won't be able to ARM unless you reboot.
  • Also, if your sonar is mounted too close to the ground, the output on these EZ sonars tend to max out or fluctuate between min and max values, and you won't be able to arm. Again, you'll have to reboot.

Using Standalone Analog MaxSonar

  • Analog output on the EZ series sonar is pin 3.
  • GND is pin 7.
  • Range of Analog output is between 0v and the voltage supplied to the sonar via Vcc.
  • Only 3.3V Vcc on Pixhawk is the power pin on the safety switch connector, so if you want to connect an analog MaxSonar to Pixhawk's 3.3V ADC, you will need to supply Vcc via this power pin.
  • If you use 6.6V ADC input port, you can power the sonar via 5V Vcc which is supplied on 6.6V socket's Vcc pin.

Other Range Finders

  • Details to be filled...

Update Copter Firmware on Pixhawk

Known Issues

  • If you don't take off immediately after arming and bring your copter to at least about 1 meter, EKF will stop using OF data and you'll be flying manually.
  • Sometimes OF drops out suddenly mid-flight when readings are off, but there's no warning or indication. Only way to know is to look at the dataflash logs.
  • When flying with OF, the aircraft starts to drift off as time goes by. It appears EKF5.FIX and EKF5.FIY gets too large over time.
  • Loiter mode feels a little "sluggish" compared to stabilize, etc., and it's easy to get confused and panic as it seems like the copter is not responding to your RC input at all.
  • If you are getting nothing in the logs (make sure you are looking at the dataflash logs and not the telemetry logs), fire up NSH, and issue px4flow status command to see if the PX4FLOW module is detected on I2C and the driver is loaded. You should see a bunch of readouts if it's functioning correctly and error message otherwise.
  • At least one of the PX4FLOW clones (one without the on-board sonar module, bought from China) did not work when connected via I2C. It can be very confusing as it appears to be working just fine when connected directly to the PC via USB. PX4FLOW with sonar (bought direct from 3DR) doesn't have this problem.


Misc. Notes

  • The PX4FLOW firmware binary APM Recommended Version above is apparently built from the source code here, but the resulting binary built from the soure does not work with APM:Copter.
  • The latest upstream version, when built from the source does not seem to work with APM:Copter. OPTICAL_FLOW.flow_comp_m_x etc. in both telemetry and dataflash logs didn't look right.
  • In both cases, the values reported by the Copter didn't look right (values were too small, biased towards one direction only, less frequently updated, etc.). Although they look OK if you connect to PX4FLOW and look at the mavlink data directly.

If you want to build PX4FLOW firmware from the source:

NOTE: This is just for reference. Don't do this as it won't produce the same binary as above.

git clone
make upload-usb