System designTroubleshooting

V4L2 timeperframe changed but fps stuck at 30: set the sensor mode

V4L2 timeperframe only requests a rate. Find the mode your sensor driver streams, fit exposure into the frame period, and measure why fps stays stuck at 30.

LumaSpec Vision10 min read Share on LinkedIn

On this page 10 sections
  1. 01timeperframe is a request; the sensor mode is the rate
  2. 02Likely causes, ranked
  3. 03Test 1: read back the rate the driver accepted
  4. 04Test 2: measure the delivered rate over a timed window
  5. 05Test 3: pin exposure below the target period
  6. 06Fix: stream the mode that carries your rate
  7. 07Worked example: the bandwidth behind the missing 60 fps mode
  8. 08When to skip the kernel fight
  9. 09Prevention: pin the mode before integration
  10. 10Questions

Your V4L2 application sets timeperframe to 15 or 60, the driver accepts the write without complaint, and the stream still lands at 30 fps. The value you changed is a request, not a control: the rate you get is the one the sensor's register mode produces, and most embedded camera drivers carry one register set per resolution, tuned to 30 fps. This guide shows how to find the modes your driver really has, why a compiled-in default changes nothing on its own, how to make the sensor deliver 15 or 60 fps, and how to measure the delivered rate so you can prove the fix worked.

timeperframe is a request; the sensor mode is the rate

A write of streamcap.timeperframe.denominator, or its userspace equivalent in VIDIOC_S_PARM, hands the driver a wish: numerator 1 with denominator 60 asks for 60 fps. Mapping that wish onto hardware is the driver's job, and embedded sensor drivers do it through a table of register blobs. Each blob is one supported combination of resolution and frame rate, expressed as pixel-clock dividers and frame-length registers. Those registers decide physically how long a frame takes. If the table holds no entry near your request at the current resolution, the driver stores the request and keeps streaming the 30 fps blob.

A compile-time define such as DEFAULT_FPS in a driver file like ov5640_mipi_v3.c only selects or labels one of those blobs. The rate still comes out of the registers the blob writes, which is why editing the define alone recompiled a new label onto the same 33.3 ms timing and changed nothing. The platform receiver simply follows the sensor: it never generates a frame rate of its own, so it cannot be the part that locks you at 30.

frame period (ms) = 1000 / fps

At 15 fps a frame lasts 66.7 ms, at 30 fps 33.3 ms, at 60 fps 16.7 ms. Every rate question below reduces to fitting exposure and link bandwidth inside those periods.

Likely causes, ranked

Three causes cover almost every stuck-at-30 case; run the tests in order, each takes minutes.

Likelihood Cause Test What it tells you
Most common No mode in the driver table at 15 or 60 fps for your resolution Read VIDIOC_G_PARM back (test 1) Driver clamped the request; sensor untouched
Common Source edited (DEFAULT_FPS, denominator) but mode registers unchanged Rebuild, reboot, measure over 10 s New label, same timing
Common Exposure longer than the target frame period Pin exposure at 1/100 s, re-measure (test 3) Frame stretched or request ignored
Occasional Application trusts a reported rate instead of the delivered one Count frames over 10 s (test 2) Believed fps and delivered fps differ
Rare CSI link bandwidth at high resolution Bandwidth arithmetic (worked example below) Matters only above 1080p

Test 1: read back the rate the driver accepted

Set the request, then immediately read it back:

int fd = -1;                           /* capture node from your open() call, e.g. /dev/video0 */
struct v4l2_streamparm parm;

memset(&parm, 0, sizeof(parm));
parm.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
parm.parm.capture.timeperframe.numerator   = 1;
parm.parm.capture.timeperframe.denominator = 60;
ioctl(fd, VIDIOC_S_PARM, &parm);

memset(&parm, 0, sizeof(parm));        /* fresh struct so G_PARM fills it */
parm.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
ioctl(fd, VIDIOC_G_PARM, &parm);
printf("driver accepted %u/%u fps",
       parm.parm.capture.timeperframe.denominator,
       parm.parm.capture.timeperframe.numerator);

The readback is the whole test. A printout of 30/1 after a request for 60 means the mode table had no faster blob at this resolution: the driver refused quietly and you have the diagnosis. A readback of 60/1 with frames still arriving at 30 points at exposure or measurement instead.

Test 2: measure the delivered rate over a timed window

The readback is a claim; frames are the fact. Count frames for 10.0 s and divide: fps = frames / 10. A real 30 fps stream shows 300 frames, a 60 fps stream shows 597 to 600, and 15 fps shows 150. The 10 s window even separates a true 30.0 from a clamped 29.7 fps mode, because they land at 300 versus 297 frames. Driver timestamps give the same number with a moving average; the method is in Camera frame rate measurement from timestamped frames. If your rate currently comes from a framework property, read Video FPS returns zero in OpenCV: read frame rate reliably first: that value can be zero or a container default rather than the sensor.

Test 3: pin exposure below the target period

At 16.7 ms per frame, 60 fps leaves no room for a 20 ms auto-exposure value; the sensor responds by stretching the frame, or the driver ignores the faster request. Switch exposure to manual at 1/100 s (10 ms) with the gain fixed and measure again: a jump to about 60 fps convicts exposure. The same arithmetic bounds every capture - a frame needs exposure plus readout time, worked through in Maximum frame rate on a hardware trigger: exposure plus readout time. If exposure writes have no effect at all, the driver is dropping them, and Set exposure via sensor registers when the SDK has no API shows the register-level route. A stuck 15 fps request, by contrast, is almost never exposure: its 66.7 ms period fits anything the 30 fps mode already runs.

Fix: stream the mode that carries your rate

  1. List the blobs. Open the sensor driver source and read its mode table - the array of register sets labelled by resolution and fps - or enumerate the sensor subdevice's formats with the media controller utility on the running system. Write down every rate that exists and the resolution it is bound to.
  2. Stream the resolution the fast blob is bound to. On a 5 MP sensor the 60 fps entry usually sits at 1080p or below; the bandwidth example below shows why. Set exactly that resolution and pixel format on every pad of the pipeline, not only on the capture node. A half-matched pipeline delivers short frames or hangs instead of a new rate, which CSI camera short frame errors: match the mode to the sensor output walks end to end. If the advertised list itself looks wrong, Camera frame rate mode missing: verify advertised modes is the check.
  3. Add the blob if it does not exist. Clone the register set closest to your target and change only the timing groups - pixel-clock dividers and frame length - so the period lands on 16.7 ms for 60 fps or 66.7 ms for 15 fps. The register names and their legal ranges come from the sensor's register map in the manufacturer's documentation.
  1. Rebuild, reload or reboot, then repeat test 1. The readback should now accept the requested denominator.
  2. Re-run the 10 s measurement: about 600 frames for 60 fps, 150 for 15 fps, 300 for 30.

Worked example: the bandwidth behind the missing 60 fps mode

Take a 5 MP sensor at full frame, 2592 × 1944, streaming YUV422 at 2 bytes per pixel over a four-lane CSI-2 link (MB = 10^6 bytes):

bytes per frame = 2592 × 1944 × 2 = 10,077,696 ≈ 10.1 MB link at 30 fps = 10,077,696 × 30 = 302.3 MB/s link at 60 fps = 10,077,696 × 60 = 604.7 MB/s 1080p at 60 fps = 1920 × 1080 × 2 × 60 = 248.8 MB/s 720p at 60 fps = 1280 × 720 × 2 × 60 = 110.6 MB/s

Full-frame 5 MP at 60 fps demands about 605 MB/s sustained, more than a four-lane embedded receiver runs at practical serial clock rates, while 302 MB/s at 30 fps is already near its ceiling. At 1080p the same 60 fps costs 249 MB/s and at 720p only 111 MB/s, both with margin. That arithmetic is why driver authors bind 60 fps to a reduced resolution: the platform can stream 60 fps, but not at 5 MP over four lanes. Full resolution at 15 fps needs 151 MB/s, and its 66.7 ms period fits a 50 ms exposure - the slow, high-quality mode the 30 fps default was hiding.

When to skip the kernel fight

If the deliverable is a dependable non-30 stream rather than driver surgery, move capture to an interface where tested sensor modes are already the product. Over USB3 or GigE, frame rate is a runtime control in the SDK or the GigE Vision stream configuration: no rebuild, no register blob. The LS-BCM-0003 board-level module streams 3.1 MP at 120 fps over USB3 with a global shutter. The MV-CB016-10GM-M-W covers 1.6 MP over GigE with an IMX296 global shutter where a longer cable run matters. For standard industrial optics and GenICam control, the same rates exist across the area scan cameras range.

Board-level cameras3.1 MP USB3 board-level camera, IMX252, 1/1.8" global shutter, 120 fps (LS-BCM-0003)LS-BCM-0003
Sensor format
1/1.8"
Lens mount
C-mount
$690.00View part
Board-level camerasHikrobot MV-CB016-10GM-M-W 1.6 MP GigE board-level camera, IMX296, Mono, M12 lens mount, WTB GigE portMV-CB016-10GM-M-W
Sensor format
1/2.9"
Lens mount
M12
$559.00View part

The board-level cameras category holds both mounting styles, and the board camera evaluation checklist for inspection systems gives the bench checks to run before you commit one way or the other.

Prevention: pin the mode before integration

Five habits keep the delivered rate honest:

  • Record every BSP's mode table (resolution and fps labels) when you accept it; a missing rate is a finding to log, not a surprise at integration.
  • Read VIDIOC_G_PARM back after every format or rate change; it is one ioctl and it catches a silent clamp immediately.
  • Measure 10 s of delivered frames at integration and after each driver update, and write the count into the release note.
  • Pin exposure and gain manually whenever frame rate matters, as test 3 does.
  • Budget bandwidth before choosing resolution and rate; the bytes-per-second formula above settles a 60 fps at 5 MP debate in one line.

The same readback discipline applies to settings that survive a reboot: Camera startup frame rate: verify saved settings and readback covers what to check at power-on.

If the CSI route costs more engineering than the project can spend, pick a module whose modes are factory-tested instead: start at the camera finder, configure a system around your resolution and rate, or bring the frame-rate question to the contact page. The remaining frame-rate fault walks sit on the systems topic page.

Questions

Does setting timeperframe in V4L2 force the sensor to that frame rate?

No. The ioctl is a request: the driver maps it onto a supported register mode and reports what it accepted through VIDIOC_G_PARM. If the mode table has no blob at or near the requested rate for the current resolution, the driver keeps its 30 fps default. The delivered rate is produced by the sensor's registers, never by the request value alone.

Why did changing DEFAULT_FPS in the sensor driver file not change the fps?

That define only picks or labels a mode at build time. The frame rate comes from the mode's register writes - pixel-clock dividers and frame length. Editing the define leaves those registers untouched, so frames still arrive every 33.3 ms. Change the register blob you actually stream, rebuild, reload, then confirm with a frame count over 10 s.

How do I measure the frame rate a camera really delivers?

Count frames over a timed window and divide: fps = frames / seconds. Use 10 s, so 60 fps shows about 600 frames and a clamped 29.7 fps mode shows 297 - clearly distinct from 300. Driver timestamps give the same number; rates reported by application frameworks can be zero or defaults and should not be trusted for this test.

How short must exposure be to run 60 fps?

The frame period at 60 fps is 16.7 ms, so exposure must fit inside it with margin: keep it at or below about 13 ms, and a fixed 1/100 s (10 ms) exposure is a comfortable choice. Indoor auto exposure often holds 20-30 ms, which stretches the frame and pulls the delivered rate back toward 30 no matter what was requested.

At which resolution can a 5 MP sensor stream 60 fps?

Whichever mode the driver binds the 60 fps label to - on 5 MP parts that is normally 1080p or below. At full 2592 × 1944 resolution a YUV422 frame is about 10.1 MB, so 60 fps would push 605 MB/s through the CSI-2 link; 1080p needs 249 MB/s and 720p needs 111 MB/s, which four lanes carry with margin.

Can I get 15 fps without editing the driver?

Yes. Capture the existing 30 fps stream and drop every second frame in software: the images, the 33.3 ms latency and the exposure headroom stay the same while your pipeline sees 15 fps. Edit or add a register mode only when you need the true 66.7 ms exposure window that a real 15 fps mode provides.