English
Controlling a lock remotely: a few pitfalls between the software and the door
Between the command your software sends to a lock and the bolt that moves, where can the command get lost, and what do you have to check for yourself?
On the surface, a smart lock API looks like a web API: an address, a request, a response. But there is a difference of kind. A web API moves information from one piece of software to another. A smart lock API crosses a border: it leaves the software to reach the physical world.
At the far end of a web service there is usually a database, which answers at once, about a state that is its own. A smart lock API, by contrast, acts on a mechanical object that runs on batteries, sleeps most of the time, depends on a Wi-Fi connection it does not control, and runs firmware whose updates you do not always control either.
The API does let you send that object a command. But unlike a software interaction from end to end, the safe delivery of the command does not let you conclude that it was carried out. For that, you also have to examine the device and check its state. In some cases, the means of observation available to you turn out to be rather limited.
By way of example, here are a few typical pitfalls worth learning to recognise: a response that confirms the command was received, not executed; a state that dates from the last message received; a word that means a different operation from one brand to the next; and a device that changes without notice.
What we describe here is what every developer faces who talks directly to a manufacturer's API. The first two pitfalls come from physics and never go away, whatever sits in between. The other two come from the manufacturers, and they are what your software layer has to absorb: in another article, we explain how Seam goes about correcting or softening them.
The API answers as soon as the command is accepted, but the bolt moves later
In a web service, a positive response usually means the operation took place, because the server performs the operation before answering. With a connected device API, the response often says only that the command was received by the server relaying it.
We say so in our own documentation (Seam, action attempts): "devices exist in the physical world. The physical world is intrinsically asynchronous". If we returned an instant response, it "would imply instant completion of a long-lived physical process". A paradox, in short. Which is why a request to move a does not return a result but an "action attempt": a response that confirms the command has been taken on, that does not yet say whether it was carried out, and that has to be checked again.
Every integration with a connected device API runs into this, whatever the platform. With locks, there are six links between the command and the bolt: your server, the manufacturer's cloud, a or a installed at the customer's, a radio link, the lock's firmware, and finally the motor that drives the bolt. The response is sent back from the second link. The bolt is at the sixth, perhaps jammed against a misaligned strike, or caught by some other technical mishap.

A naive integration would show "unlocked" on the app's screen the instant the response from the second link arrived. In that case, the user may well walk up to the door and find it still locked. You would hunt for the bug in vain, because nothing has actually failed: the app simply asserted something the API never said.
To find out whether the bolt moved, you still have to read the lock's state. That reading has limits of its own.
The state you read is not necessarily the device's, but the last one it reported
A second point follows from the first: when you query a manufacturer's API for a lock's state, it is usually not the lock you are asking. You are asking the cloud service for the last news it received from the device, and that is not quite the same question.
The SmartThings documentation is instructive on this point. It distinguishes
three health states for a device, not two. A device enrolled in health checks
has a check interval, set when it is installed. As long as it shows signs of
life within that interval, it is ONLINE, which SmartThings defines as "a
device can be expected to respond to a command". If it stays silent longer
than that, the device goes UNHEALTHY, "an intermediate state indicating that
a device is possibly offline", a state the platform attributes to "high
network latency, low battery, or tamper events on security devices". The
platform then tries to reach it; if it cannot, the device is finally declared
OFFLINE. How long does all this take? The documentation gives no figure: the
interval depends on the device, and the operator reading the state usually does
not know how long it is
(SmartThings, device health).
The intermediate state is, frankly, the most honest of the three. It does not say the device is broken, which it may not be; it only says that right now, its state cannot be known for certain. The platform would rather admit the uncertainty than guess. An integration that reduced a device's state to a boolean would be taking the risk of reporting false claims on a regular basis.
The SmartThings documentation illustrates the problem from another angle: "when a hub goes offline, all devices connected to this hub will also be marked OFFLINE". One box unplugged in a hallway, and dozens of devices change state at once, though not one of them has moved. Claim that they themselves have gone dead, and a technician rushes out to replace them or swap their batteries. For nothing.
Brands have several ways of defining what "setting a code" means
Two connected locks whose brochures say they accept access codes will not necessarily accept the same codes. Of the thirty-four commands the Matter specification defines for a door lock, only two are mandatory: lock and unlock. Everything about codes, schedules and users belongs to features that each device declares or does not, as it sees fit. Device names themselves follow no common rule either: every model number obeys the grammar of the company that wrote it.
"Setting a code" is therefore not one operation but a family of operations whose rules change with the brand: how many digits, which digits are allowed or where certain digits may appear, how many slots there are to store codes, whether a code can be read back or only confirmed to exist, whether a time window is handled by the lock or has to be handled in your software, and what procedure applies when all the slots are already taken. The API can accept a command and the lock refuse it, under a logic that varies with each brand, or with the cloud provider in use. Here again, expect the API's response to say nothing about it. The assumption is that you operate inside one system and its rules, which you are supposed to know. Everything is built as though you only ever worked with a single brand. Nothing is designed to let you move easily from one system to another.
Seam's API exists precisely to solve this problem. In another article, we go through some of the puzzles these differences create, and how, at Seam, we build all manner of workarounds to absorb them.
The hardware, the API and the firmware change, each at its own pace
Integrating a smart lock API directly means resting your code on a technical stack that belongs to another company. It is not your product, and it keeps evolving, at a pace you do not set and without any way for you to freeze how it works. By plugging your software into a manufacturer's API, you are building an unstable layer into the very core of your software.
The connected devices themselves are often installed in buildings you never see, and updated at a pace you are not always told about. The ground is mined, and it keeps shifting.
The hardware can change without its name changing. The same lock appears in two certification filings four years apart, with a different hardware version and a different radio generation, while the same product name can mean two different devices at the same time, on two continents. Your compatibility list holds the name, but it does not tell you which of the two devices the customer bought.
The API can change too, and even when the manufacturer announces it, a change
means reworking the integration. When Allegion replaced its GWE gateway with
the GWE2, the new model got an identifier of its own, gwe2: one character
more, and any software that had hard-coded gwe, in the address where it
looks up the gateway's firmware for example, has to be reworked
(Allegion, Gateway IP integration guide).
Allegion tells customers to check with their software provider that the new
model is supported
(Schlage, ENGAGE resources).
The fix is tiny. You still have to read the guides each of your manufacturers
publishes, and stay alert to the smallest of these changes.
Finally, to top it off, you will also discover that when the API is served by the box at the customer's, what it can do depends on the version of the firmware running in that box, and sometimes on that of the lock paired with it. A feature added in one version does not exist in the ones before, and your software has to account for that before assuming what the device accepts.
The versions pile up too: the document describing one bridge's API went through fourteen versions between 2017 and 2024, and each one added without removing. A manufacturer that introduces a hashed authentication token keeps the old plain-text token, because the software written against that token is not its own and it has no way to update it. Rightly so. As a result, your code finds itself having to accept both, indefinitely (the concrete case is detailed in our article on API versions).
The fleet you support is not simply today's products. You are, in effect, integrating everything the market has sold since the day you started.
| An ordinary web service | A device API | |
|---|---|---|
| A 2xx response means | Usually, that the operation completed | The command was received |
| Reading the state gives you | The current value | The last news the cloud received, of unknown age |
| The device is | Available or unavailable | Available, unavailable, or nobody knows |
| The failure to plan for | Timeouts, invalid data | Flat battery, jammed bolt, unplugged box |
| One manufacturer offers | One API | Often a cloud API, a local API and a radio |
| Two devices with the same feature | Behave the same way | Differ in their limits, slots, formats and the meaning of words |
| The contract changes | When you change version | When the manufacturer decides, or when a box updates itself |
The right-hand column is not a list of grievances: it is the list of assumptions to remove from the code. Each line cost somebody a week.
None of these pitfalls is a flaw in the APIs themselves. They keep their original promise: pass a command along, and return the information the cloud has. The real difficulty is handed straight back to you, on the part where these APIs promise you nothing: that the command reached the bolt, that the state you read is the device's state right now, that the word "code" means the same thing at the next brand, and that the device is still the one that was installed last month. Facing each of these pitfalls, the software giving the orders has to develop ways of observing, and do for itself the checks the API does not do.
You will have gathered that when you talk to each manufacturer directly, this work has to be done once per manufacturer, then done again every time one of them changes something. What you end up maintaining is a vast layered stack, with untimely surprises that never stop. What a platform builds on top of these APIs to absorb it, and what it can and cannot fix, is a subject we take up here.