Improve camera device error reporting

[PhilippeFerreiraDeSousa]

Summary

Translate Android Camera2 device callback errors into stable, actionable error codes and messages before they leave the glasses.

This change:

• adds a typed CameraOperationError shared by photo capture and camera warm-up
• maps all five CameraDevice.StateCallback error values
• carries the structured code and message through PhotoSession and every photo delivery path
• sends the specific error in photo_status, photo_response, and camera_status events
• keeps unclassified failures backward-compatible as CAMERA_CAPTURE_FAILED or camera_warm_up_failed
• retains the raw Android integer in the ASG log for diagnosis

Why

A React Native requestPhoto() call was rejected with:

CAMERA_CAPTURE_FAILED: Camera device error: 4

The integer is an Android Camera2 implementation detail. Error 4 means ERROR_CAMERA_DEVICE: the opened camera device encountered a fatal device-level error and must be closed and reopened. Neither an SDK consumer nor an example-app user should need to look up that integer to understand whether retrying is appropriate.

In the observed failure, a camera FOV setting restarted the HAL, warm-up was rejected during the restart cooldown, and the subsequent photo reached camera open just after the fixed cooldown expired. Camera2 then reported error 4 before the request reached configuring or capturing. The new response for that failure is:

CAMERA_DEVICE_ERROR: Camera hardware was not ready. Wait a few seconds and try again.

The ASG diagnostic log still records:

Camera open failed: CAMERA_DEVICE_ERROR (Android code 4)

Error mapping

Android callback	SDK event code	Message
ERROR_CAMERA_IN_USE	CAMERA_IN_USE	Camera is already in use. Wait and try again.
ERROR_MAX_CAMERAS_IN_USE	MAX_CAMERAS_IN_USE	Another camera operation is active. Wait and try again.
ERROR_CAMERA_DISABLED	CAMERA_DISABLED	Camera access is disabled by the system.
ERROR_CAMERA_DEVICE	CAMERA_DEVICE_ERROR	Camera hardware was not ready. Wait a few seconds and try again.
ERROR_CAMERA_SERVICE	CAMERA_SERVICE_ERROR	Camera service failed. Restart the glasses if the problem continues.

Unknown callback integers use CAMERA_DEVICE_ERROR and include the raw integer in the message.

Propagation

The typed failure is preserved through:

• camera open callbacks
• photo session lifecycle
• offline/button photos
• local gallery-save photos
• webhook-upload photos
• BLE fallback photos
• camera warm-up promise failures

Legacy string-only internal failures are wrapped in the existing generic codes, so this does not require a compatibility shim in the phone SDK.

Validation

• Added unit coverage for all five Camera2 mappings and unknown values.
• Added lifecycle coverage proving a structured device error survives PhotoSession unchanged.
• Added lifecycle coverage proving string failures during warm-up retain the camera_warm_up_failed fallback.
• Ran the complete ASG :app:testDebugUnitTest suite successfully.

---

Note

Medium Risk
Changes how error codes surface to phone/SDK clients across all photo and warm-up paths; behavior is backward-compatible for string callbacks but new codes may affect apps that assumed only CAMERA_CAPTURE_FAILED.

Overview
Introduces CameraOperationError (stable code + human-readable message) and threads it from Camera2 through photo capture and warm-up instead of opaque strings like Camera device error: 4.

Camera open failures now map all five CameraDevice.StateCallback error constants to named codes (CAMERA_IN_USE, CAMERA_DEVICE_ERROR, etc.); logs still include the raw Android integer. PhotoSession and CameraNeoService pass typed errors end-to-end; warm-up busy/reject paths use camera_busy via the same type.

MediaCaptureService forwards error.code() and error.message() into photo_status, photo_response, and camera_status on every photo delivery path (offline, local-save, webhook, BLE). Legacy string-only failures are wrapped as CAMERA_CAPTURE_FAILED or camera_warm_up_failed; callback interfaces gain optional onPhotoError(CameraOperationError) / onCameraError(CameraOperationError) defaults that delegate to the string overloads.

Unit tests cover the mapping table, callback delegation, and lifecycle preservation of structured errors during warm-up vs capture.

^{Reviewed by Cursor Bugbot for commit a15d584. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

📋 PR Review Helper

📱 Mobile App Build

⏳ Waiting for build...

🕶️ ASG Client Build

✅ Ready to test! (commit a15d584)

📥 Download ASG APK

---

🔀 Test Locally

gh pr checkout 3410

[github-actions]

PR Agent Orchestrator State

{
  "cycle": 1,
  "fixRound": 0,
  "totalReviewerRuns": 1,
  "consecutiveNoNewReviews": 1,
  "openFindings": [],
  "resolvedFindings": [],
  "nitFindings": [],
  "phase": "discovery",
  "status": "in_progress",
  "stagnationFixRounds": 0,
  "fingerprintReopenCounts": {},
  "mutedFingerprints": [],
  "lastPair": [],
  "lastOpenCount": 0
}

[github-actions]

🤖 PR Agent Review — cycle 1

✅ No blocking findings · 0 blocking · 0 nits
Reviewers this cycle: none

No model reviews ran this cycle.

_{Updated automatically by the PR Agent Orchestrator each review cycle. Nits do not block merge.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1b44b97368

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Keep legacy photo error callbacks source-compatible

For callers that still implement the previously documented string callback, this new typed overload is abstract, so an existing anonymous class passed to takePictureWithCallback/enqueuePhotoRequest with only onPhotoCaptured(...) and onPhotoError(String) now fails to compile despite the added default string overload. If the string callback is meant to remain backward-compatible, make the typed overload default/delegate to the string path or otherwise keep the old abstract contract so existing camera integrations are not forced to change.

Useful? React with 👍 / 👎.