Merge branch 'feature/cameras' into main

.devcontainer/devcontainer.json

@@ -11,6 +11,17 @@
     ],
     "service": "barton",
 
+    // Forward the camera reference app's HTTP media server (`cs`). The app connects to the
+    // camera over WebRTC in-container (direct UDP, no TURN) and serves the video as fragmented
+    // MP4 over this port; it opens in VS Code's embedded Simple Browser (an editor tab).
+    "forwardPorts": [8088],
+    "portsAttributes": {
+        "8088": {
+            "label": "Camera stream",
+            "onAutoForward": "openPreview"
+        }
+    },
+
     // keep the local path of our tree the same within the container
     "workspaceMount": "source=${localWorkspaceFolder},target=${localWorkspaceFolder},type=bind",
     "workspaceFolder": "${localWorkspaceFolder}",
@@ -42,6 +53,22 @@
         "GIT_PS1_SHOWCOLORHINTS": "true",
         "PROMPT_COMMAND": "${localEnv:PROMPT_COMMAND}",
 
+        // X11 display. Dev Containers already bridges the developer's display to the
+        // container's :0 socket (it sets REMOTE_CONTAINERS_DISPLAY_SOCK=/tmp/.X11-unix/X0
+        // but does not export DISPLAY). Setting it here lets GUI/GStreamer apps — e.g. the
+        // camera reference app's autovideosink — render straight to the developer's screen
+        // with no VNC bridge or URL. Harmless when no host X server is present: GUI apps
+        // simply fail to open the display, and non-GUI processes ignore it.
+        "DISPLAY": ":0",
+
+        // Force GStreamer's autovideosink to choose the software ximagesink here. The
+        // forwarded X display (:0 above) only supports basic X drawing, not OpenGL/Xv, so
+        // GPU sinks like glimagesink fail over the tunnel. This is a limitation of the
+        // VS Code remote devcontainer environment, NOT of reference-app environments in
+        // general — real reference devices have a local GPU and should let autovideosink
+        // pick a hardware sink — so the constraint lives here rather than in the app.
+        "GST_PLUGIN_FEATURE_RANK": "ximagesink:MAX",
+
         // see `docker/setupDockerEnv.sh` for more details on these custom PATHs
         // NOTE: do not add a custom PATH here without first defining it in setupDockerEnv.sh
         // Build-tree path comes first so freshly compiled libraries are used without `make install`.

.github/skills/validate-sbmd/SKILL.md

@@ -27,15 +27,15 @@ The `validate_sbmd_specs` target uses Node.js to extract each driver's registrat
 ### Validate SBMD Spec Files
 
 ```bash
-python3 scripts/ci/validate_sbmd_v4_specs.py \
+python3 scripts/ci/validate_sbmd_specs.py \
     core/deviceDrivers/matter/sbmd/schema \
     core/deviceDrivers/matter/sbmd/specs/*.sbmd.js
 ```
 
 This:
 1. Uses Node.js to evaluate each `.sbmd.js` file in a sandbox
 2. Extracts the `SbmdDriver()` registration object as JSON (functions → `true`)
-3. Validates the JSON against `sbmd-spec-schema-v4.0.json`
+3. Validates the JSON against `sbmd-spec-schema.json`
 
 The validator evaluates each `.sbmd.js` file, extracts the `SbmdDriver()` registration object, and validates it against the JSON schema.
 
@@ -44,9 +44,9 @@ The validator evaluates each `.sbmd.js` file, extracts the `SbmdDriver()` regist
 | Item | Location |
 |------|----------|
 | SBMD spec files | `core/deviceDrivers/matter/sbmd/specs/*.sbmd.js` |
-| JSON schema | `core/deviceDrivers/matter/sbmd/schema/sbmd-spec-schema-v4.0.json` |
+| JSON schema | `core/deviceDrivers/matter/sbmd/schema/sbmd-spec-schema.json` |
 | TypeScript definitions (editor tooling only — not used by the validator) | `core/deviceDrivers/matter/sbmd/scriptCommon/sbmd-script.d.ts` |
-| Validation script | `scripts/ci/validate_sbmd_v4_specs.py` |
+| Validation script | `scripts/ci/validate_sbmd_specs.py` |
 | Extraction harness | `scripts/ci/sbmd_extract_registration.js` |
 
 ## Discovering Available SBMD Specs

api/c/src/barton-core-client.c

@@ -38,6 +38,7 @@
 #include "deviceServicePrivate.h"
 #include "event/deviceEventProducer.h"
 #include "icTypes/icLinkedList.h"
+#include "observability/observability.h"
 #include "icTypes/icLinkedListFuncs.h"
 #include "observability/observability.h"
 

config/cmake/platforms/dev/linux.cmake

@@ -34,6 +34,9 @@ set(CMAKE_PREFIX_PATH "${CMAKE_BINARY_DIR}/matter-install" CACHE PATH "Path to M
 
 set(BCORE_GEN_GIR ON CACHE BOOL "Gir generation")
 
+# Build the reference app's camera stream command (GStreamer WebRTC) in the dev platform.
+set(BCORE_REFERENCE_CAMERA_SUPPORT ON CACHE BOOL "Enable reference app camera support")
+
 # Matter settings
 include(${CMAKE_SOURCE_DIR}/config/cmake/modules/BCoreMatterHelper.cmake)
 

core/CMakeLists.txt

@@ -207,10 +207,10 @@ if (BCORE_MATTER)
     list(APPEND XTRA_LIBS ${BCORE_MATTER_LIB} ${OPENSSL_LINK_LIBRARIES} jsoncpp)
     link_directories(${CMAKE_BINARY_DIR}/matter-install/lib)
 
-    # SBMD v4 specification validation
+    # SBMD specification validation
     if (BCORE_MATTER_VALIDATE_SCHEMAS)
         set(SBMD_SCHEMA_DIR "${CMAKE_CURRENT_SOURCE_DIR}/deviceDrivers/matter/sbmd/schema")
-        set(SBMD_VALIDATOR "${CMAKE_SOURCE_DIR}/scripts/ci/validate_sbmd_v4_specs.py")
+        set(SBMD_VALIDATOR "${CMAKE_SOURCE_DIR}/scripts/ci/validate_sbmd_specs.py")
         set(SBMD_EXTRACTOR "${CMAKE_SOURCE_DIR}/scripts/ci/sbmd_extract_registration.js")
 
         find_package(Python3 COMPONENTS Interpreter REQUIRED)
@@ -224,10 +224,10 @@ if (BCORE_MATTER)
                 COMMAND ${Python3_EXECUTABLE} ${SBMD_VALIDATOR} ${SBMD_SCHEMA_DIR} ${SBMD_SPEC_FILES}
                 DEPENDS ${SBMD_SPEC_FILES} ${SBMD_SCHEMA_FILES} ${SBMD_VALIDATOR} ${SBMD_EXTRACTOR}
                 WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
-                COMMENT "Validating SBMD v4 specification files against schema..."
+                COMMENT "Validating SBMD specification files against schema..."
             )
         else()
-            message(STATUS "No SBMD v4 spec files found in ${SBMD_SPECS_DIR}; skipping spec validation")
+            message(STATUS "No SBMD spec files found in ${SBMD_SPECS_DIR}; skipping spec validation")
         endif()
     endif()
 endif()

core/deviceDrivers/matter/MatterDevice.cpp

@@ -419,7 +419,12 @@ bool MatterDevice::SendCommandFromTlv(std::forward_list<std::promise<bool>> &pro
     }
 
     bool isTimedRequest = timedInvokeTimeoutMs.has_value();
-    auto commandSender = std::make_unique<chip::app::CommandSender>(this, &exchangeMgr, isTimedRequest);
+
+    // Allow large (TCP) payloads when the session supports them so large commands do not fail
+    // to serialize against the MRP/UDP single-message limit.
+    bool allowLargePayload = sessionHandle->AllowsLargePayload();
+    auto commandSender =
+        std::make_unique<chip::app::CommandSender>(this, &exchangeMgr, isTimedRequest, false, allowLargePayload);
 
     if (!commandSender)
     {
@@ -545,7 +550,13 @@ bool MatterDevice::SendCommandWithCallbacks(chip::ClusterId clusterId,
     }
 
     bool isTimedRequest = timedInvokeTimeoutMs.has_value();
-    auto commandSender = std::make_unique<chip::app::CommandSender>(this, &exchangeMgr, isTimedRequest);
+
+    // Allow large (TCP) payloads when the session supports them. Without this the CommandSender
+    // caps its buffer at the MRP/UDP single-message limit (~1280 bytes), which makes large
+    // commands such as a WebRTC ProvideOffer SDP fail to serialize.
+    bool allowLargePayload = sessionHandle->AllowsLargePayload();
+    auto commandSender =
+        std::make_unique<chip::app::CommandSender>(this, &exchangeMgr, isTimedRequest, false, allowLargePayload);
 
     if (!commandSender)
     {
@@ -578,6 +589,10 @@ bool MatterDevice::SendCommandWithCallbacks(chip::ClusterId clusterId,
 
     if (err != CHIP_NO_ERROR)
     {
+        icError("Failed to enter TLV container for deferred command cluster 0x%x cmd 0x%x: %s",
+                clusterId,
+                commandId,
+                err.AsString());
         return false;
     }
 
@@ -587,12 +602,22 @@ bool MatterDevice::SendCommandWithCallbacks(chip::ClusterId clusterId,
 
         if (err != CHIP_NO_ERROR)
         {
+            // A buffer-too-small/no-memory error here typically means the payload exceeds what the
+            // session's transport allows (e.g. a large SDP over an MRP/UDP session that is not
+            // large-payload capable). Establishing the session with a large-payload (TCP) transport
+            // resolves it.
+            icError("Failed to copy TLV element for deferred command cluster 0x%x cmd 0x%x "
+                    "(payload may exceed the session's transport limit): %s",
+                    clusterId,
+                    commandId,
+                    err.AsString());
             return false;
         }
     }
 
     if (err != CHIP_END_OF_TLV)
     {
+        icError("Malformed TLV for deferred command cluster 0x%x cmd 0x%x: %s", clusterId, commandId, err.AsString());
         return false;
     }
 
@@ -603,6 +628,13 @@ bool MatterDevice::SendCommandWithCallbacks(chip::ClusterId clusterId,
 
     if (err != CHIP_NO_ERROR)
     {
+        // As with CopyElement above, this commonly indicates the payload exceeds the session's
+        // transport limit; a large-payload (TCP) session is required for oversized commands.
+        icError("Failed to finish deferred command cluster 0x%x cmd 0x%x "
+                "(payload may exceed the session's transport limit): %s",
+                clusterId,
+                commandId,
+                err.AsString());
         return false;
     }
 

core/deviceDrivers/matter/MatterDeviceDriver.cpp

@@ -948,25 +948,30 @@ bool MatterDeviceDriver::ConnectAndExecute(const std::string &deviceId, connect_
     chip::Callback::Callback<OnDeviceConnected> successCb(OnMatterDeviceConnectionSuccess,
                                                           static_cast<void *>(&workWrapper));
 
-    // SDK event size limitations prevent directly capturing too many objects.
-    // connectPromise is directly pointed at in failCb.mContext, so it is indirectly
-    // captured via failCb.
-
-    auto err = chip::DeviceLayer::SystemLayer().ScheduleLambda([&deviceId, &successCb, &failCb]() {
-        auto nodeId = Subsystem::Matter::UuidToNodeId(deviceId);
-
-        CHIP_ERROR getConnectedErr =
-            Matter::GetInstance().GetCommissioner()->GetConnectedDevice(nodeId, &successCb, &failCb);
-        if (getConnectedErr != CHIP_NO_ERROR)
-        {
-            icError("Failed to start device connection: %s", getConnectedErr.AsString());
-            static_cast<std::promise<bool> *>(failCb.mContext)->set_value(false);
-        }
+    // Initiate the connection on the Matter thread. GetConnectedDevice is non-blocking (it starts
+    // the connection and returns immediately; successCb/failCb fire later). RunOnMatterSync marshals
+    // this onto the Matter thread (via ScheduleLambda) but blocks until it has run, so
+    // GetConnectedDevice is guaranteed to execute before ConnectAndExecute can proceed or time out.
+    // That ordering is the point: unlike a bare ScheduleLambda whose deferred work could run *after*
+    // ConnectAndExecute has returned, the connection is never initiated once we are past this call,
+    // so a timed-out call can never later invoke GetConnectedDevice with dangling callback pointers.
+    // Blocking here also keeps the by-reference captures (including the stack-owned callbacks) alive
+    // for the whole call, and RunOnMatterSync's std::function work is not subject to the LambdaBridge
+    // 24-byte capture limit that applies to using ScheduleLambda directly.
+    chip::NodeId nodeId = Subsystem::Matter::UuidToNodeId(deviceId);
+    // Seed with an error so that if RunOnMatterSync fails to schedule the work (e.g. the stack goes
+    // down between the IsRunning() check above and this call), getConnectedErr stays non-OK and we
+    // fail fast below instead of waiting out the full connect timeout on a promise that would never
+    // be satisfied.
+    CHIP_ERROR getConnectedErr = CHIP_ERROR_INCORRECT_STATE;
+
+    RunOnMatterSync([&]() {
+        getConnectedErr = Matter::GetInstance().GetCommissioner()->GetConnectedDevice(nodeId, &successCb, &failCb);
     });
 
-    if (err != CHIP_NO_ERROR)
+    if (getConnectedErr != CHIP_NO_ERROR)
     {
-        icError("Failed to schedule connect task: %s", err.AsString());
+        icError("Failed to start device connection: %s", getConnectedErr.AsString());
         return false;
     }
 

core/deviceDrivers/matter/sbmd/SpecBasedMatterDeviceDriver.cpp

@@ -35,6 +35,7 @@
 #include "matter/sbmd/mquickjs/SbmdHandlerInvoker.h"
 #endif
 
+#include <algorithm>
 #include <app/ConcreteAttributePath.h>
 #include <cinttypes>
 #include <lib/core/TLVReader.h>
@@ -531,6 +532,14 @@ std::optional<uint8_t> SpecBasedMatterDeviceDriver::ConvertModesToBitmask(const
         {
             bitmask |= RESOURCE_MODE_EXECUTABLE;
         }
+        else if (mode == "dynamic" || mode == "emitEvents")
+        {
+            // Both are enabled by default (see the initial bitmask). Accept them as explicit
+            // no-ops so specs that list these default-on modes register successfully. Contradictory
+            // combinations with their opt-out counterparts ("static"/"noEvents") are rejected at
+            // spec-validation time by the schema's modes constraint, so no runtime resolution is
+            // needed here.
+        }
         else if (mode == "static")
         {
             bitmask &= ~(RESOURCE_MODE_DYNAMIC | RESOURCE_MODE_DYNAMIC_CAPABLE);
@@ -547,6 +556,11 @@ std::optional<uint8_t> SpecBasedMatterDeviceDriver::ConvertModesToBitmask(const
         {
             bitmask |= RESOURCE_MODE_SENSITIVE;
         }
+        else if (mode == "volatile")
+        {
+            // Caching policy (CACHING_POLICY_NEVER) is applied separately in
+            // DoRegisterDriverResources; this mode contributes no access bit.
+        }
         else
         {
             icError("Unsupported resource mode: %s", mode.c_str());
@@ -643,8 +657,17 @@ bool SpecBasedMatterDeviceDriver::DoRegisterDriverResources(icDevice *device)
             // Resources without explicit read handlers are updated via attribute subscriptions,
             // so use CACHING_POLICY_ALWAYS to return the DB-cached value on read.
             // Resources with explicit read handlers use CACHING_POLICY_NEVER so the driver is called.
+            // The 'volatile' mode also forces CACHING_POLICY_NEVER so that, for a resource that emits
+            // events, updateResource delivers an event on every call (no value-change suppression) even
+            // when the value is unchanged. CACHING_POLICY_NEVER also means updateResource does not
+            // persist the value (or dateOfLastSyncMillis) to the device DB, and readable resources are
+            // served from the driver rather than the DB cache. 'volatile' is therefore intended for
+            // event-only signaling resources and should not be applied to subscription-backed state
+            // resources whose reads rely on the DB-cached value.
+            bool isVolatile =
+                std::find(resource.modes.begin(), resource.modes.end(), "volatile") != resource.modes.end();
             ResourceCachingPolicy cachingPolicy =
-                resource.read.has_value() ? CACHING_POLICY_NEVER : CACHING_POLICY_ALWAYS;
+                (resource.read.has_value() || isVolatile) ? CACHING_POLICY_NEVER : CACHING_POLICY_ALWAYS;
 
             // Seed initial value if there's a seed handler
             const char *initialValue = nullptr;

core/deviceDrivers/matter/sbmd/schema/CHANGELOG.md

@@ -1,5 +1,27 @@
 # SBMD Schema Changelog
 
+The schema lives in a single file, `sbmd-spec-schema.json`, whose version is not
+encoded in the filename. This changelog records the schema version history, and
+each spec's `schemaVersion` field is validated against the schema's expected
+version. Each versioned heading below describes the changes introduced by that
+version.
+
+## v5.0
+
+- The schema version is no longer encoded in the schema filename
+  (`sbmd-spec-schema.json`) or in docs; `schemaVersion` is still validated
+  against the schema's expected version
+- Breaking: attribute/event/command handlers must bind via `aliases`. The inline
+  `clusterId` + `attributeId`/`attributeIds` (and `eventId`/`eventIds`,
+  `commandId`/`commandIds`) binding form has been removed; declare an alias in the
+  spec's `aliases` map and reference it by name
+- Add the `volatile` resource mode: disables value caching (`CACHING_POLICY_NEVER`)
+  so event-only signaling resources emit an update event on every `updateResource`
+  call even when the value is unchanged; it also stops persisting the value to the
+  device DB, so it is for event-only resources, not subscription-backed state
+- `modes` now rejects the mutually-exclusive pairs `static`/`dynamic` and
+  `noEvents`/`emitEvents`
+
 ## v4.0
 
 - First schema for the JavaScript-native driver format: specs are authored as