System designHow-to

Change camera SPI pins on an ESP32: move CS, keep the bus

Change a camera's SPI pins on an ESP32: CS moves freely, the data lines stay on the controller, and the frame budget decides when bit-banged SPI works.

LumaSpec Vision11 min read Share on LinkedIn

On this page 11 sections
  1. 01The decision, up front
  2. 02What you need
  3. 03Step 1: free the default pins instead of moving them
  4. 04Step 2: move CS first, and only CS
  5. 05Step 3: the second hardware controller
  6. 06Step 4: budget the bus before you accept software SPI
    1. Worked example: one 3 MP frame on each path
  7. 07Step 5: switch the driver to software SPI and verify
  8. 08Common mistakes that cost an afternoon
  9. 09When SPI is the wrong bus entirely
  10. 10Pick the branch, then the pins
  11. 11Questions

You planned the board around the camera, and the camera lost the pin fight: three of its four SPI lines are driven by a hardware controller, and the pins that controller uses are already taken. This guide is for engineers integrating an SPI camera module into an ESP32-class controller who need the bus on different pins. It gives the decision up front, the pin facts behind it, a frame-rate budget that shows whether bit-banged software SPI can carry your application, and verification steps that catch a mis-wired bus in minutes. The short version: change CS freely, keep MOSI, MISO and SCK on controller pins, and let the arithmetic, not hope, choose between the second bus and software SPI.

The decision, up front

CS and the data lines are not the same kind of signal. The library drives CS as a plain general-purpose output, so it moves to any free pin. MOSI, MISO and SCK are outputs and inputs of a hardware SPI controller, and they stay fast and reliable only on that controller's pins. That is why the CS change took an afternoon and the MOSI change will not.

The decision tree has three branches, in this order:

  1. Free the three default pins. Relocate whatever else sits on them. The camera keeps the controller and its tested speed.
  2. Move the camera to the second hardware controller — HSPI on classic parts, SCK on GPIO 14, MISO on GPIO 12, MOSI on GPIO 13 — if the camera library accepts a bus or pin choice when it initialises.
  3. Bit-bang the bus in software on arbitrary pins, and only after the frame budget in Step 4 shows your frames still fit.

Each step down costs speed. Branch 2 is equivalent hardware on different pins. Branch 3 is a loop that any timer interrupt or slow digital write can stretch mid-frame.

What you need

  • The camera module and its library, already capturing on the default wiring. Rewire nothing before you have that baseline.
  • The pin map of everything else on the board, with the genuinely free pins marked. The shared IO pin check is the habit to copy before any wire moves.
  • A multimeter, and ideally a logic analyser or scope for Step 5.
  • Ten minutes of arithmetic for the frame budget.

Step 1: free the default pins instead of moving them

Before you move the camera, move the problem. Look at what occupies the controller's MOSI, MISO and SCK, and ask what each occupant can live on instead. A slow configuration sensor belongs on I2C. Peripherals that each want their own select line can share these same three lines behind separate CS pins — that sharing is what SPI is for. A display tolerates a bit-banged connection, because a missed refresh is invisible where a lost camera byte is not. Release whichever line you can: the camera keeps the controller and none of the harder branches below is needed. On a board whose layout is still yours to change, this is almost always the right branch.

Step 2: move CS first, and only CS

CS has no controller behind it. Pass the new pin number where the camera initialises, keep the line idling high, and re-run the baseline capture before anything else moves. Two rules decide which pins qualify:

  • The pin must be output-capable. On classic parts the input-only GPIOs cannot drive CS.
  • The pin must not be a strapping pin the module samples at reset, and not one the module keeps for its own flash or PSRAM.

While the header is off, check drive level and protection for the new line. The GPIO wiring and power-fault triage guide covers the failure modes worth designing out at exactly this stage.

Step 3: the second hardware controller

If the data lines themselves are occupied and nothing on them can move, the next-best branch stays in hardware. The chip has a second general-purpose controller — HSPI on classic parts — with SCK on GPIO 14, MISO on GPIO 12 and MOSI on GPIO 13. Whether the camera can use it is decided by the library, so read the driver's initialisation signature. Some drivers accept a SPI object or a pin set: hand them the second controller and wire 14/12/13. A driver that takes nothing but a CS number is written against the default controller, and no sketch-side setting will reassign its data lines. That board is on branch 1 or branch 3, not this one.

One strapping check before you commit the wiring:

If the module boots with the camera on GPIO 12, this branch keeps you on controller hardware at controller speeds on new pins. If it will not boot, the branch is closed and the frame budget in Step 4 decides whether software SPI fits your application.

Step 4: budget the bus before you accept software SPI

Software SPI replaces the controller with a loop of digital writes on whatever pins you have. It works on any pins and it is slow on all of them, so the branch decision is arithmetic:

frame_bits = width_px × height_px × 16 (raw, 2 bytes per pixel) frame_bits = jpeg_bytes × 8 (JPEG, bytes from the frame header) t_frame = frame_bits / f_SPI (s) fps_bus = 1 / t_frame fps_actual = min(fps_bus, fps_sensor, fps_processing)

Two inputs decide the result: the clock your loop actually sustains, and the bytes per frame. A hardware controller on short traces sustains tens of MHz; a digital-write loop on an ESP32-class part lands near 0.5-1 MHz. The worked example uses 40 MHz and 1 MHz as illustrative inputs. Measure your own loop before you trust either one:

Worked example: one 3 MP frame on each path

Take an illustrative 2048 × 1536 sensor (3.1 MP) sending raw frames at 2 bytes per pixel, and a JPEG capture of the same scene at 250 kB.

Raw, hardware controller at 40 MHz:

  • 2048 × 1536 = 3,145,728 px; × 16 bit/px = 50,331,648 bit per frame.
  • 50,331,648 bit ÷ 40,000,000 bit/s = 1.26 s per frame, which is 0.79 fps.
  • Bit-banged at 1 MHz: 50,331,648 bit ÷ 1,000,000 bit/s = 50 s per frame. Raw at 3 MP does not survive software SPI in any useful sense.

JPEG at 250 kB: 250,000 bytes × 8 = 2,000,000 bit.

  • Hardware at 40 MHz: 2,000,000 bit ÷ 40,000,000 bit/s = 0.05 s per frame, a 20 fps ceiling from the bus.
  • Bit-banged at 1 MHz: 2,000,000 bit ÷ 1,000,000 bit/s = 2.0 s, or 0.5 fps.

JPEG size moves the answer. At 40 MHz a plain 100 kB frame clears the bus in 0.02 s (a 50 fps ceiling) and a busy 400 kB frame in 0.08 s (12.5 fps). Every doubling of the clock halves the frame time. The real rate is the smallest of the three caps in the last formula line — bus, sensor capture, processing — so treat fps_bus as a ceiling, not a promise.

Path Clock 250 kB JPEG frame 3 MP raw frame
Default controller 40 MHz 0.05 s, 20 fps ceiling 1.26 s, 0.79 fps
Second controller (HSPI) 40 MHz identical to default identical to default
Bit-banged software SPI 1 MHz 2.0 s, 0.5 fps 50 s, unusable

The decision this produces: an inspection that needs 2-5 fps of JPEG frames fits a hardware controller with margin and fails a bit-banged bus outright at half a frame per second. If the application needs the raw pixels, neither bit-banging nor the controller carries a 3 MP raw stream at inspection rates, and no clock setting changes that order of magnitude.

If the camera shares the controller with other traffic, add their bytes to the same budget. The multi-camera data bottleneck guide works the same arithmetic across several cameras. Note that the bit-banged path is your own code, not the standard Arduino SPI library, which drives a hardware controller.

Step 5: switch the driver to software SPI and verify

Where the library accepts a software SPI object, construct one on your chosen pins and pass it where the camera initialises, keeping the same mode and bit order the hardware path used. Where it accepts none, the data lines cannot move without editing the driver itself — treat that as a porting project with its own test plan, not a configuration change.

Then verify in this order:

  1. CS toggles on the new pin — high at idle, low for each transaction, never floating.
  2. Byte counts match. Read the frame length from the module's header and compare it with the bytes received; a short count means dropped bits.
  3. Ten frames time consistently. Timestamp ten captures with the millisecond counter; a spread under a few percent is a clean loop, and a wandering time is an interrupt stretching the bit-bang mid-frame.
  4. Cold boot still works. Power-cycle from off five times; strapping conflicts appear at reset, not in the sketch.
  5. The image is structurally right — correct dimensions, no diagonal tearing (a shifted bit), no repeated lines (a dropped chunk).

If the camera rides a carrier or IO board, confirm the connector side too: the IO board pin alignment check is written for exactly that fault.

Common mistakes that cost an afternoon

  • Rewiring before there is a baseline. Capture on the default wiring first, then move one line at a time and re-run the baseline after each, so a fault is never more than one wire away.
  • A strapping pin under the camera. The GPIO 12 warning in Step 3 applies to every pin you assign anywhere. Check the module's strapping table for each new pin, not just the data lines.
  • Controller speed through jumper wire. The tens of MHz a controller sustains on a PCB survive a few centimetres of jumper lead. On longer runs, drop the clock by half or shorten the wire; the symptom is shifted bits and torn rows.
  • Budgeting with a hoped-for clock. Use the loop speed you measured with the 10 kB test, not the one you assumed.
  • Forgetting shared traffic. Every other device on the same three lines spends the same budget the camera does.

When SPI is the wrong bus entirely

If the budget says even the controller cannot carry your frames — raw 3 MP at inspection rates is the common case — the fix is not a faster bit-bang but a different transport. A USB3 board-level camera moves a raw 6.3 MB frame in tens of milliseconds into a host with USB3 ports, and a GigE module covers the cable runs USB3 will not. At that point frames arrive at a rate the SPI path cannot approach, and the design question moves from pins to pixel formats. The board camera evaluation checklist is the tool for that step, the board-level cameras category is where the parts live, and the camera finder filters them by interface and resolution.

The LS-BCM-0003 is a 3.1 MP USB3 board-level camera with a global shutter, rated at 120 fps. The MV-CB060-10UM-B is a 6 MP mono USB3 board camera on an IMX178, supplied as a bare board. The LS-BCM-0020 is a 6.3 MP GigE board camera / module with a CS-mount, for runs too long for USB3.

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-CB060-10UM-B 6 MP Board Level Camera, USB3, IMX178, Mono, Bare Board, V4MV-CB060-10UM-B
Sensor format
1/1.8"
Interface
USB3
$239.00View part
Board-level cameras6.3 MP board-level camera, IMX178, 1/1.8" rolling shutter, 18 fps (LS-BCM-0020)LS-BCM-0020
Sensor format
1/1.8"
Lens mount
CS-mount
$290.00View part
CamerasBoard-level cameras

Compact cameras to build in

120 models · from $179.00

Pick the branch, then the pins

The order is fixed. Free the default pins if any occupant can move. Take HSPI on GPIO 14/12/13 if the driver accepts a bus choice, after the strapping check. Bit-bang only when the frame budget proves your fps survives the measured loop clock. Change transport when the budget fails even on the controller. For everything that hangs off the camera once the bus is settled — lens, lighting, trigger wiring — the configurator started at the camera step walks those choices in the same order, and the systems topic page collects the wiring, trigger and bring-up guides around this one.

Questions

How much slower is bit-banged software SPI than the hardware controller?

Plan on roughly 40 to 80 times slower on an ESP32-class part: plain digital-write loops clock out near 0.5-1 MHz, while a hardware controller sustains 20-40 MHz on short traces. Measure your own loop rather than trusting either number: send a 10 kB test buffer, timestamp it with the millisecond counter, and divide bytes by seconds. Put that measured value, not a guess, into the frame budget.

Which pins should I not use for the new CS line?

Three groups fail. The classic part's input-only GPIOs (34-39) cannot drive an output, so they cannot select the chip. Strapping pins that the module samples at reset can stop it booting if a camera or pull-up holds the wrong level. And any pin the module keeps for its own flash or PSRAM is out of reach from the sketch. Check the module's pin list and strapping table before you commit a choice.

How big is one frame from a 3 MP SPI camera?

Raw, budget 2 bytes per pixel: a 2048 × 1536 frame is about 6.3 MB, which a 40 MHz controller moves in roughly 1.3 s. JPEG compresses the same scene to anywhere from about 100 kB for a plain target to 400 kB for a busy one, and the size changes with the scene and quality setting, so read the length the module reports in its frame header instead of assuming one number.

Can the camera share the SPI bus with my other sensors?

Yes, and it is usually the right answer to a pin shortage: keep MOSI, MISO and SCK shared on the controller and give each device its own CS line. The bandwidth is shared too, so add every device's traffic into the frame budget, and be careful with peripherals that hold the lines or stretch transactions. A slow device on the shared bus costs the camera frames exactly as a slow loop would.

Why is the image corrupted when the camera sits further from the board?

Signal integrity. At the tens of MHz a hardware controller runs, SPI signals survive only a few centimetres of jumper wire; on longer runs you see shifted bits and torn frames. Shorten the run, drop the clock by half, or fit 22-33 Ω series resistors at the driver. If the distance is fixed by the machine, that is the case for a different interface such as GigE, not a higher clock.