Testing a Matter Gateway: From UART Responses to Apple Home State Synchronization

Connect the boards, tap a button on your phone, and the light turns on. It is tempting to think the difficult part of a smart-home project is over.

Then unplug the lamp. The phone may still show it as on. Restart the gateway, and perhaps the device needs pairing again. Turn the light off with its own button, and the icon in Apple Home might not change.

Those failures belong to command execution, state synchronization and recovery. A single successful demonstration reveals very little about them.

The previous development-board checklist covered the hardware needed for validation. This article sets out what evidence the first integration round should produce, and what must pass before we move on.

Our PC Matter prototype already connects to Apple Home, and the Linux image has been built. Actual interoperability between the Silicon Labs NCP and Telink devices, feedback from real lights, and recovery of the complete system still need testing. This is our first-round acceptance plan, not a report of completed hardware tests.

Start with one light and a fixed baseline

Apple Home connects to the Linux gateway over the local network. The gateway calls a Silicon Labs Bluetooth Mesh NCP through UART/BGAPI, and the NCP controls a Telink Mesh device. Device state must travel back through the same layers.

For the first round, connect one device and test basic on/off behavior. Dimming, color temperature, scenes and multi-channel switches can wait. Extra device types create more possible explanations for each failure.

Record the host program commit, NCP firmware and SDK versions, device firmware and serial settings. Photograph the wiring, especially voltage levels, ground and RTS/CTS. Avoid changing the host and module firmware together and remembering only that it worked afterward.

First validate the NCP and device with a host example supplied for the selected SDK. Then substitute our Rust host program while keeping hardware and firmware unchanged. If the official example also fails, investigate firmware capabilities and model configuration first. If only our program fails, focus on frame parsing and call sequencing.

Separate four meanings of success

Layer	What it establishes	What it does not establish
Host writes to UART	Bytes were handed to the serial interface	The NCP parsed them correctly
BGAPI response arrives	The NCP returned a result for that API call	The remote light executed it
Device state arrives	The remote model reported a present or target state	Matter attributes and the phone are synchronized
Apple Home agrees	The displayed state agrees with the observed result	The system remains correct after a restart or outage

The meaning of a BGAPI response depends on the command documentation. A successful return code is not a universal light-is-on confirmation. Asynchronous events can also arrive between responses; parsing cannot assume a simple write-one/read-one conversation.

Host logs should connect each operation to its target device, requested state, send time, API response, relevant state event and final outcome. I plan to assign an internal operation identifier for this purpose. That does not imply that BGAPI or every Mesh message echoes that identifier.

Initially, allow only one pending operation per device. Match incoming state using its source address, element, model and timing. A neighboring device’s report, or an old state received before the action, must not count as confirmation.

Provisioning is only the beginning

Joining a network is a useful milestone, but it does not prove control works. Read Composition Data to identify the element and model that implement the required function. Then configure AppKeys, model bindings and any publication or subscription settings required by the communication method.

Two devices labeled Bluetooth Mesh may share only some standard models. Vendor-specific features require separate work.

Start with unicast to a known on/off model at a specific address. Prefer acknowledged operations, and cross-check with a state query. This keeps the investigation focused on addresses, key bindings, model support and reception rather than group addressing and multiple replies.

Also distinguish a reply to a control command from unsolicited state publication. One working does not prove the other is configured. After a physical button changes the state, check publication and reception if the firmware supports reporting that change. If it does not, assess polling and its delay rather than promising real-time updates.

Test three paths independently

First, control the light from the host without Matter involved. Check the physical change and then the reported state. For transitions, distinguish the present value, target value and remaining transition time. An intended future value is not an observation of completion.

Second, change the light locally using a supported button or another known control path. Do not send an on/off command from the host; observe whether the new state arrives. A successful query is not a substitute for testing unsolicited publication. If polling is the chosen design, measure its update time separately.

Third, control the real light from Apple Home. The phone sends the command, the light acts, the gateway receives state, and Matter attribute updates and reporting convey it to the controller. Then change the light locally and verify that the phone follows.

If the host has the new state but Apple Home does not, the likely investigation area is device mapping, attribute updates and subscription reporting. Reprovisioning at that point usually destroys useful evidence.

Keep the desired state separate from the last confirmed actual state. An on request can create a pending operation; a suitable device report confirms the observed state. An optimistic display needs explicit timeout and correction behavior. Successful UART submission must not leave an unplugged light recorded as on indefinitely.

Define a measurable first-round threshold

Without a waiting limit and repeat count, “occasionally a little slow” can remain unresolved forever.

My initial plan is 20 on/off cycles with one light at a fixed short distance, waiting for each operation to finish before starting the next. Record physical response, device-state arrival and phone update times separately. Use five seconds as the provisional end-to-end waiting limit; a timeout is a failure with retained logs.

Twenty cycles and five seconds are project-specific trial criteria, not Matter or Bluetooth Mesh requirements, and not measured performance. They make the first run comparable; we can tighten them after evaluating device behavior and user experience.

Passing means no unexplained state errors, no forgotten pending operations after timeouts, and no need to restart the program to continue. A successful retry does not erase the initial failure.

Out-of-order updates need attention too. A reply to an older query may arrive after a newer action; arrival order alone must not determine which state wins. Serializing the first test reduces this risk, but fast repeated taps will need separate tests for queuing, stale responses and convergence.

Introduce one fault at a time

Once normal control passes, test outages and restarts separately. Return to a stable baseline between cases.

Fault	What to observe	Required after recovery
Light loses power	Request timeout handling and when it becomes unreachable	Control returns and the actual state is obtained
NCP restarts	Reset detection and handling of unfinished operations	Serial session and initialization recover; existing devices remain controllable
Host process restarts	Persistence of device records, Matter identity and mappings	No duplicate lights and no need to add the gateway again
Gateway loses LAN access	Matter connectivity and downstream Mesh behavior separately	State is synchronized again instead of displaying old cached values indefinitely

A single unanswered query may not justify marking a light offline. Define an observation window and failure count, and log the reason for the decision. Set policy according to power characteristics, reporting mechanisms and network behavior instead of applying one heartbeat rule to every node.

Avoiding duplicate devices requires stable identity and mappings. The host cannot allocate a fresh Matter endpoint number every time it rediscovers a light. Persist device, element and bridged-endpoint relationships and restore them as the stack requires.

Mesh keys, address allocation, sequence numbers and replay-protection state also need stack-appropriate persistence. Establish which state belongs to the NCP and which to the host. A manually chosen sequence-number offset is not a general power-loss recovery mechanism.

This round tests restarting the original hardware. Replacing an NCP is a different recovery problem because its persistent state may need migration. Passing a restart test does not prove module replacement works.

Preserve evidence before a factory reset

Deleting and adding an unresponsive light may temporarily fix it while hiding the cause: a binding mistake, stale cache, or inconsistent keys and device records.

For each failure, preserve versions, steps, device identification and relevant logs. Remove keys, commissioning credentials and other sensitive information before sharing logs publicly. A simple blank record is enough to start:

Field	Entry
Test ID and version combination	To fill in
Physical and host states before the action	To fill in
Steps and expected outcome	To fill in
UART response, device report and phone update times	To fill in
Pass/fail and log location	To fill in
Recovery action and reproducibility	To fill in

Be precise about removal, too. Removing the gateway from a Matter platform differs from removing and resetting a downstream Mesh light. Cleaning up a phone pairing must not casually erase the entire downstream network.

When to add more devices

At the end of round one, I want a repeatable process using specified firmware and host versions: configure one light, control it, receive independent state changes, keep the phone consistent with the real device, and recover after separate light, NCP and host restarts.

Then add a second light to check address and endpoint isolation, followed by dimming, color temperature and group control. Large networks, long-duration stress testing, OTA, module replacement and certification remain separate tasks.

The most useful early result is the ability to locate failures. When a light does not respond, the records should identify where the command stopped. When the phone is wrong, they should reveal the last trustworthy device state. That is a sound foundation for adding features.

Further reading

• Matter gateway hardware and validation checklist
• Rust and rs-matter: bridging devices into Apple Home
• Silicon Labs Bluetooth Mesh API reference: use the documentation matching your SDK for precise command, response and event semantics.

Working on a Bluetooth Mesh–Matter bridge too? Get in touch to discuss state synchronization and recovery.