Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
245 lines (183 loc) · 9.48 KB

TROUBLESHOOTING.md

File metadata and controls

245 lines (183 loc) · 9.48 KB
Raw

Troubleshooting

Start with BasicCapture, a stable power supply, default Balanced settings, and Serial Monitor at 115200 baud. Change one variable at a time.

Build and installation

NiusCam.h: No such file or directory

  • Confirm the library is installed under the Arduino sketchbook's libraries directory.
  • The directory containing library.properties must be NiusCam.
  • Remove accidental nesting such as NiusCam-main/NiusCam.
  • Restart Arduino IDE and reopen the example from File > Examples > NiusCam.

Duplicate camera definitions or linker errors

  • Remove separately installed copies of esp32-camera.
  • Use the camera component bundled with esp32 by Espressif Systems 3.x.
  • Remove stale manual libraries from the sketchbook if Arduino reports multiple candidates.

Unsupported Arduino-ESP32 version

NiusCam targets Arduino-ESP32 3.x. Add Espressif's package URL and update the board package as described in Getting started.

Upload and serial monitor

No port appears

  • Use a data-capable USB cable.
  • Try a direct USB port rather than an unpowered hub.
  • Install the USB bridge driver required by the particular board.
  • For XIAO ESP32-S3, use its documented BOOT/RESET sequence to enter the ROM bootloader, then select the newly enumerated port.

ESP32-CAM will not upload

  • Select AI Thinker ESP32-CAM.
  • Cross TX/RX correctly and share ground.
  • Hold GPIO0 low while resetting into the bootloader.
  • Use a stable 5 V supply.
  • Remove GPIO0 from ground and reset after upload.

Upload works but Serial Monitor is blank

  • Set 115200 baud.
  • Reset once after opening the monitor.
  • Confirm the monitor opened the same port used for upload.
  • Check USB CDC settings if using a board's native USB rather than its UART bridge.

Camera initialization

camera not found

  1. Confirm the Arduino board selection matches the physical module.
  2. Reseat the camera ribbon with the contacts in the correct direction.
  3. Check that the Sense expansion board is fully seated.
  4. Use a stable supply and disconnect high-current accessories temporarily.
  5. Return to the default Balanced profile.
  6. Only then inspect or replace GPIO definitions.

The error means the bundled camera driver could not communicate with a valid sensor; changing JPEG quality or frame buffers does not repair SCCB wiring.

sensor does not match board profile

The camera responded, but its detected PID differs from the selected profile's expected sensor. Select the correct profile or create a custom profile for the actual sensor and wiring. Do not disable validateSensor merely to hide an unexpected identity.

Unsupported configuration

The requested format/frame-size pair is outside the selected sensor's capability table. Start with Balanced JPEG/VGA, inspect camera.capabilities(), and call supports() before reconfiguration.

Capture succeeds at small sizes but fails at larger sizes

  • Enable PSRAM in the Arduino board options.
  • Confirm camera.diagnostics().psramAvailable is true.
  • Use JPEG rather than RGB888/YUV422.
  • Reduce resolution or buffer count.
  • Begin with Balanced before requesting Turbo.
  • On compatible OV2640/ESP32-S3 paths, inspect whether PSRAM DMA was actually enabled rather than only requested.

OV5640 is detected or focuses, but every capture fails

Sensor identity and autofocus commands travel over SCCB; image pixels travel over the separate parallel DVP bus. Successful PID reads or focused status do not prove that VSYNC, HREF, PCLK, and D0-D7 are electrically compatible.

  • Confirm the replacement module has an ESP32-compatible DVP output, not MIPI.
  • Compare its connector pinout, contact orientation, I/O voltage, and power rails with the original module rather than relying on connector size alone.
  • Confirm the autofocus actuator supply is present when the module requires a separate AF rail.
  • Test a small RGB565 frame as well as JPEG. Failure in both paths points away from JPEG configuration and toward clock, power, connector, or DVP wiring.
  • Do not process a supposed frame when VSYNC, HREF, and PCLK remain static; resolve the electrical interface first.
  • A flex marked DC-5640 with MDP1/MDN1, MCP/MCN, and MDP0/MDN0 in its pin table is MIPI CSI-2 and is incompatible with the ESP32 parallel camera port. Select a module whose table explicitly lists DVP data pins and PCLK.

Image is mirrored, upside down, dark, or incorrectly colored

  • Use horizontalMirror() and verticalFlip() for module orientation.
  • Allow automatic exposure, gain, and white balance to settle.
  • Confirm the correct sensor/profile was detected.
  • Remove manual exposure/gain overrides.
  • Test whiteBalanceMode() under fixed lighting.
  • Use the sensor test pattern to distinguish capture corruption from optics or scene lighting.
  • For OV2640 low-light use, apply the documented 50/60 Hz automatic frame-rate control after selecting the final resolution. This trades FPS for exposure and does not power an IR emitter; see OV2640 low-light timing.

Image contains only soft color regions or large light circles

A threaded fixed-focus lens can arrive far outside its usable focus position. The resulting frame may look like irregular color data even when capture is electrically correct.

  • Remove any protective cap or film; do not remove the lens itself.
  • Point the camera at text or another high-contrast target 1-2 meters away.
  • Rotate the threaded lens slowly while watching a VGA preview, then secure it at the sharpest position.
  • Use the internal test pattern as a diagnostic: a sharp color bar with a blurred natural image confirms the digital capture path but not lens focus.
  • Do not use JPEG size or a numerical sharpness score alone to declare success; inspect the decoded frame for recognizable scene detail.

Memory and stability

Free heap or PSRAM is too low

  • Release Frame objects promptly.
  • Reduce frame buffers, resolution, or uncompressed pixel depth.
  • Include only the optional modules used by the sketch.
  • Stop HTTP streaming before starting another camera owner.
  • Avoid retaining native frame pointers.

Camera works once, then capture stalls

A Frame may still own the only available buffer. Let it leave scope or call frame.release() before the next lifecycle operation or long delay.

Reconfiguration or sleep restoration fails

  • Release every frame first.
  • Check the returned Result.
  • Use camera.recover() to restart the current known configuration after a driver fault.
  • BoardPowerDown is unsupported when no physical PWDN pin is wired; fall back to DriverOff.

microSD

Card does not mount

  • Format it as FAT32 on a computer and safely eject it.
  • Insert it fully while the board is unpowered, then power-cycle.
  • Confirm the correct board profile.
  • For XIAO ESP32-S3 Sense, reseat the expansion board and verify its J3 SD/SPI bridge according to Seeed's documentation.
  • Try a known-good card within the board vendor's supported capacity.
  • Improve power stability.

CMD0 or GO_IDLE_STATE failure

This occurs before filesystem mounting: the card did not answer the bus reset command. Reformatting cannot repair an absent electrical response. Reseat and power-cycle the card, inspect the expansion-board/bridge connection and bus wiring, and test another card.

Card mounts but file saving fails

  • Inspect storage.info().freeBytes.
  • Use an absolute path beginning with /.
  • Keep filenames/directories reasonably short.
  • Ensure the captured frame is JPEG.
  • Check the Result from every save.
  • Test at a lower requested storage frequency on custom wiring.

A .part file remains

A previous atomic write was interrupted before final rename. On the next write to the same path, NiusCam removes the stale temporary file. After power loss, remount and verify the card on a computer if the filesystem reports errors.

HTTP and UDP

Browser page does not open

  • Confirm Wi-Fi startup succeeded.
  • Connect the phone/computer to the NiusCam SoftAP.
  • Use the IP printed by the sketch, not an assumed address.
  • Disable mobile-network switching/VPN temporarily if it routes around the local SoftAP.
  • Confirm server.begin(camera) returned success.

Snapshot works but MJPEG stops

  • Do not capture concurrently from loop().
  • Keep the camera in JPEG mode.
  • Reduce resolution or increase the JPEG quality number to shrink frames.
  • Check signal strength and power stability.
  • Reopen /stream after the client disconnects.

UDP receiver shows corrupted or partial images

A receiver must wait for every chunk and validate complete-frame CRC32 before decoding. Drop incomplete frames; do not concatenate packets only by arrival order. See UDP protocol.

UDP loss is high

  • Reduce JPEG size or frame rate.
  • Move the receiver closer and reduce interference.
  • Ensure the receiver processes packets promptly with a sufficient socket buffer.
  • Try a small packetIntervalUs value.
  • Prefer MJPEG/TCP when reliable delivery matters more than latest-frame latency.

Collect useful diagnostics

Report these public facts when seeking help:

  • Camera module and detected sensor
  • Arduino-ESP32 version
  • Selected Arduino board and PSRAM option
  • NiusCam version
  • Result::message() and native code
  • Requested profile, format, and frame size
  • Diagnostics PSRAM/DMA state and free memory
  • Whether the minimal bundled example reproduces the issue

Do not publish Wi-Fi credentials, private network addresses, device identifiers, or unrelated serial logs.