Embedded camera reference image storage: survive the eject reboot

You copied a folder of reference JPEGs into your smart camera's data folder, ejected the drive from the file manager, and the vision software went gray. The status LED still shows solid, the camera feels alive, and your program is dead. Most of the time nothing is broken: ejecting the storage share reboots the camera on purpose, and it needs about 30 seconds to come back. The remaining cases are a load path with no error handling, or a file that never decoded anywhere. You will separate those cases in a few minutes, work the storage and downtime arithmetic for an eight-image set on a 5 MP camera, and leave with a load routine whose size checks turn a bad reference into a logged error instead of a stopped line.

The symptom: the software grays out exactly when the drive ejects

The pattern repeats the same way on every host. You export the camera as a virtual flash drive, drag the JPEGs into its data folder, and the copy itself completes normally. The moment you eject that drive, your vision software grays the camera out or stops responding. It looks identical on a Windows workstation and on a Mac, and the status LED keeps reporting a live camera the whole time.

Three details matter. The copy succeeds, so storage addressing works. The failure lands on the eject, not on the upload. And the LED stays solid, so the processor is running. Together they point away from the files and toward what an eject does to an embedded camera. The next three sections rank the causes from most to least likely.

Cause 1, most likely: the eject reboot is designed in

A camera that appears on your desktop as a removable drive is running a USB mass-storage device over its USB link. The eject is a disconnect event, and firmware in this class treats disconnect as its cue to leave file mode and reboot into run mode. From the host side the device vanishes, the software marks the camera offline, and the camera re-enumerates when its boot finishes, about 30 seconds, the recovery time measured on this class of embedded vision sensor. Nothing crashed. The grayed-out entry is a reboot you triggered on purpose, and the copy had already finished, so the images are on the card before the reboot starts.

The test costs nothing: eject, start a stopwatch, touch nothing. If the camera reappears within roughly half a minute, this was the whole story and the fix is scheduling, not debugging.

Two follow-on effects bite after that reboot. The camera may not come back on the address you expect, either because the address came from DHCP or because its persistent address did not stick: a persistent IP address that does not survive a reboot and finding a DHCP camera's IP address after every reboot cover both hunts. And the first frames after reconnect can misbehave before the pipeline settles, as in a smart camera that misses its first images after a load.

Cause 2: the load path throws and nothing catches it

When the outage lasts minutes instead of half a minute, or the software locks hard rather than graying out, read your module code before blaming the camera. An on-device program that matches frames against reference images typically loads all of them at startup, one decode call per file. Each call can raise: a file the decoder cannot parse, a zero-byte leftover from an interrupted copy, a path that moved, an image smaller than the matcher's template window. If one of those exceptions escapes a helper function, the processing thread dies and the host tool reports a hung module, outwardly identical to the reboot.

The five-minute test: wrap every load in explicit error handling that prints the file name and the error, then run the same module on a bench PC. A desktop runtime prints verbose messages that an embedded runtime swallows, and the guilty file names itself. Most freezes reported right after an image upload end up here, in the helper code, not in the camera's operating system, which catches and reports decode errors when it is allowed to.

If the module also runs a detector or classifier on device, the same discipline covers model and label files; the storage and loading practices in running custom object detection models on embedded smart cameras carry over one to one.

Cause 3: the file is bad before it ever reaches the camera

Some files never decode anywhere. Interrupted copies leave zero-byte entries. A renamed extension does not change the bytes inside. Progressive or CMYK-encoded JPEGs are refused by some embedded decoders that accept baseline ones. And an image cropped below the matcher's template window decodes fine but fails at match time.

Three checks settle it in a minute. Stat each file: size above zero and inside the per-file budget. Decode each file on the bench and confirm you get pixels, not a null result. Compare the decoded width and height against the smallest window your matcher accepts; a reference that errors as too small is its own named failure, covered in template image too small errors. If an extension looks right but the decode still fails, read the bytes: the mismatch cases are laid out in loading image files by content when the extension is wrong.

Worked example: eight reference JPEGs for a 5 MP vision sensor

The case: an on-device classifier that matches camera frames against reference JPEGs stored in the camera's own data folder. The camera class is the 5 MP color vision sensor; the MV-SC3050XC-16M-ATN-H is a current example of it.

The inputs, and where each comes from:

• 8 reference files, the working set this case keeps in the camera's data folder.
• 5 MP per frame, printed for the camera above.
• USB 2.0 mass-storage share, this case's transfer path to the host.
• JPEG packs a raw frame 8 to 10 times smaller at high quality, a compression estimate; measure your own saved files once and use the real ratio from then on.
• About 30 seconds of recovery per eject, the field figure behind the timeout below.

The rules, in words: the set's size is file count times per-file budget; the copy time is that size divided by the link's practical throughput; the reconnect timeout is twice the measured recovery.

The arithmetic, step by step:

• Raw frame: 5,000,000 pixels × 3 bytes per pixel = 15,000,000 bytes ≈ 15 MB.
• Per-file JPEG budget: 15 MB ÷ 10 ≈ 1.5 MB and 15 MB ÷ 8 ≈ 1.9 MB, so budget 2 MB per file.
• Full set: 8 files × 2 MB = 16 MB.
• Copy time: USB 2.0 signals at 480 Mbit/s ≈ 60 MB/s, and real mass-storage copies land near half of that, so at 30 MB/s: 16 MB ÷ 30 MB/s ≈ 0.5 s.
• Recovery per eject: about 30 s. Eight separate ejects: 8 × 30 s = 240 s ≈ 4 minutes. One batched session: 30 s.
• Reconnect timeout: 2 × 30 s = 60 s.

The result: the copy itself costs half a second, every eject costs about 30 seconds of camera downtime, and the eight files total 16 MB.

The decision, with its thresholds: batch all eight files into one session and eject once per changeover, which alone saves about 3.5 minutes per update round. Set the application's reconnect timeout to 60 seconds. Hold each reference to 2 MB or less so the budget check rejects a bloated or corrupted file before the decoder opens it.

The same arithmetic scales with the sensor. The HK-TD032-12-WBN is a 1.6 MP mono vision sensor. That is roughly a third of the pixel count of the 5 MP case, so at 1.6 MP the raw frame is 1,600,000 pixels × 3 bytes = 4.8 MB, and the per-file budget tightens to about 0.6 MB.

The fix: a transfer routine that treats the reboot as part of the job

1. Stage and validate on the bench. Before any cable moves, decode every reference, check that width and height clear the matcher's template window, and confirm each file sits between 1 byte and the per-file budget, 2 MB in the 5 MP case above.
2. Copy the whole set in one session. Drag all eight files onto the camera's data folder at once and let the copy finish. One session means one eject, and one eject means one 30-second reboot instead of eight.
3. Eject once, then keep your hands off. Use the host's eject, start the stopwatch, and touch nothing for 30 seconds: no power-cycle, no unplug, no re-mount.
4. Reconnect with a 60-second timeout. Let the software re-enumerate the camera on its own schedule, and re-point the application if the address moved.
5. Prove the load. Re-run the job and read the startup log: every reference prints one loaded line, eight for this set. A count below eight means a file failed its decode, and the log names it.

Load code that fails loudly instead of hanging

The routine below is plain Python. cv2.imread and os.path.getsize are documented calls of the imaging and standard libraries; MAX_REFERENCE_BYTES, MIN_SIDE_PIXELS, references, load_reference and the file list are this example's own variables.

import os
import cv2

MAX_REFERENCE_BYTES = 2_000_000   # bytes, per-file budget from the worked example
MIN_SIDE_PIXELS = 32              # px, smallest side the matcher accepts
references = {}                   # dict[str, image], filled only by load_reference()

def load_reference(path: str) -> None:
    size = os.path.getsize(path)          # int, bytes
    if size <= 0 or size > MAX_REFERENCE_BYTES:
        raise ValueError(f"{path}: {size} bytes is outside the 1 byte to 2 MB budget")
    img = cv2.imread(path, cv2.IMREAD_GRAYSCALE)  # None when the decode fails
    if img is None:
        raise ValueError(f"{path}: decoder returned no image")
    if img.shape[0] < MIN_SIDE_PIXELS or img.shape[1] < MIN_SIDE_PIXELS:
        raise ValueError(f"{path}: {img.shape[0]}x{img.shape[1]} px is under the matcher window")
    references[path] = img

for name in ("ref1.jpg", "ref2.jpg", "ref3.jpg", "ref4.jpg",
             "ref5.jpg", "ref6.jpg", "ref7.jpg", "ref8.jpg"):
    try:
        load_reference("/data/references/" + name)
    except ValueError as err:
        print(err)                        # log it; keep the loop alive
print(f"loaded {len(references)} of 8 references")

The test that proves it: point the loop at a folder holding seven good JPEGs and one zero-byte file. Seven entries land in references, the zero-byte file raises ValueError naming itself, the printout reads loaded 7 of 8 references, and the inspection loop keeps running on the seven good references. Swap cv2.imread for your runtime's decode call and the discipline transfers unchanged.

Where the references belong

For a single camera, on the device. The camera reboots at every eject and must reload its own references at every boot without a copy from the host, which is the entire point of the data folder. A sensor with the lens already on board keeps the pipeline to one device: the MV-SCB007EC-12S-WBN is a 1.6 MP color sensor with an integrated 12 mm lens focused by hand.

For a line of cameras, one master set on a vision controller, pushed to every camera at changeover so two stations never drift onto different references. The MV-VC2140-128G40-1T pairs an Intel N-series N97 processor with 8 GB of memory, a 128 GB SSD and a 1 TB HDD, and its 4 built-in light channels also drive the illumination those cameras share.

Keep references and job files under the same archive, because storage and load order interact: settings that vanish after a job load are the same failure one directory up, as worked through in camera configuration lost after a job load. If you also keep captured frames or model weights on the device, the layout rules in wrist camera image storage apply to the same folders.

Cameras that reach the host over Ethernet instead of a USB gadget take files by network copy and skip the reboot entirely; the smart cameras pages filter by interface, so the class is visible at a glance.

When the reboot is not the whole story

Give the camera two minutes after an eject; inside that window, everything above applies. Still absent at the two-minute mark, power-cycle once and re-check the card. A camera that stays offline across a clean power-cycle has a storage or filesystem fault, and the vendor's documented re-image of the card is the recovery path. A freeze that persists while the camera is fully online is a different failure altogether, the in-use lock case, worked through in camera stuck in use after a crash.

Prevention checklist

One pass per station; each item kills one of the causes above.

• One copy session per update, then one eject: turns eight 30-second reboots into one.
• Decode every reference on the bench before the copy: a file that never decoded anywhere must not ride to the camera.
• Enforce the per-file budget in code, 2 MB at 5 MP: catches truncated copies and bloated re-saves before the decoder sees them.
• Reconnect timeout at 60 seconds, twice the measured recovery: the software waits out the reboot instead of declaring the camera dead.
• One loaded log line per reference, counted at startup: turns a silent hang into a named file and a count.
• Keep the reference set in the job archive: the vendor's re-image procedure then restores software and references together in one step.
• After any reboot, confirm the camera's address before blaming the application: the persistent-IP article above is the two-minute version of that hunt.

Next step

Pick the camera by interface and resolution in the camera finder, and let the system configurator walk the camera, lens, light and controller chain in order. The systems topic page collects the adjacent field guides. If a station on your line still hangs exactly the way this page describes, send the load log through the contact page and we will read it with you.