Skip to content

Commit 8428d6b

Browse files
dawnhogitbook-bot
dawnho
authored and
gitbook-bot
committed
GITBOOK-710: No subject
1 parent 1e546cf commit 8428d6b

File tree

3 files changed

+330
-6
lines changed

3 files changed

+330
-6
lines changed

‎docs/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -545,6 +545,7 @@
545545
* [Dormakaba Oracode Locks](device-guides/dormakaba-oracode-locks.md)
546546
* [Get started with dormakaba Oracode Locks](device-guides/get-started-with-dormakaba-oracode-locks.md)
547547
* [Creating dormakaba Oracode Offline Access Codes](device-and-system-integration-guides/dormakaba-oracode-locks/creating-dormakaba-oracode-offline-access-codes.md)
548+
* [Programming Offline Access Codes on Dormakaba Oracode Locks](device-and-system-integration-guides/dormakaba-oracode-locks/programming-offline-access-codes-on-dormakaba-oracode-locks.md)
548549
* [ecobee Thermostats](device-guides/ecobee-thermostats.md)
549550
* [Get Started with ecobee Thermostats](device-guides/get-started-with-ecobee-thermostats.md)
550551
* [Google Nest Thermostats](device-guides/google-nest-thermostats/README.md)

‎docs/device-and-system-integration-guides/dormakaba-oracode-locks/creating-dormakaba-oracode-offline-access-codes.md‎

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
description: >-
33
Learn how to create dormakaba Oracode offline access codes, including
44
understanding manufacturer-specific requirements.
5+
hidden: true
56
---
67

78
# Creating dormakaba Oracode Offline Access Codes
@@ -359,9 +360,6 @@ if (device.CanProgramOfflineAccessCodes == true) {
359360
}
360361
```
361362
{% endtab %}
362-
363-
364-
365363
{% endtabs %}
366364

367365
#### 2. Verify Successful Time-Bound Code Registration
@@ -656,9 +654,6 @@ if (device.CanProgramOfflineAccessCodes == true) {
656654
}
657655
```
658656
{% endtab %}
659-
660-
661-
662657
{% endtabs %}
663658

664659
#### 2. Verify Successful Time-Bound Code Registration

‎docs/device-and-system-integration-guides/dormakaba-oracode-locks/programming-offline-access-codes-on-dormakaba-oracode-locks.md‎

Lines changed: 328 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,328 @@
1+
# Programming Offline Access Codes on Dormakaba Oracode Locks
2+
3+
Dormakaba Oracode locks use offline access codes (PIN codes) that are generated remotely and work without requiring the lock to be online. This guide explains how to create these codes and the requirements you need to understand.
4+
5+
### Understanding Oracode offline access codes
6+
7+
[**Offline access codes**](../../products/smart-locks/access-codes/offline-access-codes.md) are PIN codes generated by Seam that work on the lock without an internet connection. Dormakaba maintains a server-based registry of synchronized encryption keys that enable these codes to work offline.
8+
9+
Once generated, you can share these codes with guests through messaging or your property management system—guests don't need to install any special app to unlock the door.
10+
11+
***
12+
13+
### Before you create codes
14+
15+
#### Time slot requirements (Required)
16+
17+
**Dormakaba Oracode locks require predefined time slots** (also called "user levels") to create access codes. You cannot create codes with arbitrary check-in/check-out times.
18+
19+
**What are time slots?**
20+
21+
Time slots define check-in and check-out times of day that are pre-configured by your Dormakaba installer. For example, a "4:00 PM → 10:00 AM" slot can be used for any booking that checks in at 4:00 PM and checks out at 10:00 AM, regardless of how many nights the guest stays.
22+
23+
**How Seam matches your bookings:**
24+
25+
When you create an access code, Seam automatically rounds your booking times (within 1 hour) to match an available time slot. The access code will use the time slot's times, not your exact booking times.
26+
27+
Example:
28+
29+
* Your booking: 3:45 PM → 10:15 AM
30+
* Available slot: 4:00 PM → 10:00 AM
31+
* Result: Code created for 4:00 PM → 10:00 AM ✓
32+
33+
If your booking times are more than 1 hour away from any configured slot, code creation will fail.
34+
35+
#### Retrieving available time slots
36+
37+
Before creating access codes, check which time slots are configured for your device:
38+
39+
{% tabs %}
40+
{% tab title="Python" %}
41+
```python
42+
# Get device and time slots
43+
device = seam.devices.get(device_id="your-device-id")
44+
time_slots = device.properties
45+
.get("dormakaba_oracode_metadata", {})
46+
.get("predefined_time_slots", [])
47+
48+
print(time_slots)
49+
[
50+
{
51+
"name": "Guest RCI D 7am-7pm",
52+
"prefix": 0,
53+
"is_master": false,
54+
"is_24_hour": false,
55+
"is_one_shot": false,
56+
"check_in_time": "07:00:00[America/Los_Angeles]",
57+
"check_out_time": "19:00:00[America/Los_Angeles]",
58+
"is_biweekly_mode": false,
59+
"dormakaba_oracode_user_level_id": "f23721ec-6dce-4c54-8971-40d58449a366",
60+
"ext_dormakaba_oracode_user_level_prefix": 0
61+
},
62+
...
63+
]
64+
65+
```
66+
67+
68+
{% endtab %}
69+
70+
{% tab title="Javascript" %}
71+
```javascript
72+
// Get device and time slots
73+
const device = await seam.devices.get({
74+
device_id: "your-device-id"
75+
});
76+
77+
const timeSlots = device.properties.dormakaba_oracode_metadata?
78+
.predefined_time_slots || [];
79+
80+
console.log(timeSlots)
81+
print(time_slots)
82+
[
83+
{
84+
"name": "Guest RCI D 7am-7pm",
85+
"prefix": 0,
86+
"is_master": false,
87+
"is_24_hour": false,
88+
"is_one_shot": false,
89+
"check_in_time": "07:00:00[America/Los_Angeles]",
90+
"check_out_time": "19:00:00[America/Los_Angeles]",
91+
"is_biweekly_mode": false,
92+
"dormakaba_oracode_user_level_id": "f23721ec-6dce-4c54-8971-40d58449a366",
93+
"ext_dormakaba_oracode_user_level_prefix": 0
94+
},
95+
...
96+
]
97+
98+
```
99+
100+
101+
{% endtab %}
102+
{% endtabs %}
103+
104+
105+
106+
**Understanding time slot format:**
107+
108+
Time slots use Seam's Time of Day (TOD) format: `15:30:00-08:00[America/Los_Angeles]`
109+
110+
* `15:30:00` - Hour and minute (3:30 PM)
111+
* `-08:00` - UTC offset
112+
* `[America/Los_Angeles]` - IANA timezone
113+
114+
**Time slot properties:**
115+
116+
Each time slot includes:
117+
118+
* `name`: Display name (e.g., "Guest Standard 4pm-10am")
119+
* `check_in_time`: Check-in time in TOD format
120+
* `check_out_time`: Check-out time in TOD format
121+
* `is_24_hour`: Whether this is a daily-bound slot
122+
* `is_biweekly_mode`: Whether this uses biweekly scheduling
123+
* `is_one_shot`: Whether code expires after first use (not currently supported)
124+
* `is_master`: Whether this provides master access (not currently supported)
125+
126+
For detailed guidance on configuring time slots, see our [Time Slot Configuration Guide](https://seam-knowledge-base.help.usepylon.com/articles/3198102890-dormakaba-oracode-time-slot-configuration).
127+
128+
#### Other important limitations
129+
130+
**Duration limit:** Access codes can be valid for a maximum of 31 consecutive days.
131+
132+
**Cannot be updated or deleted:** Dormakaba Oracode access codes cannot be modified after creation. Be mindful of device-specific code limits when creating large numbers of codes.
133+
134+
**Time zone considerations:** All times must be in the lock's local time zone. When creating codes, use the time and offset that match the lock's configured time zone (e.g., `2024-09-10T16:00:00-07:00` for Pacific time).
135+
136+
**View device timezone:**
137+
138+
```python
139+
# Python
140+
device = seam.devices.get(device_id="your-device-id")
141+
timezone = device.properties.get("dormakaba_oracode_metadata", {}).get("iana_timezone")
142+
print(f"Device timezone: {timezone}")
143+
```
144+
145+
***
146+
147+
### Creating hourly-bound access codes
148+
149+
Hourly-bound codes let you specify exact check-in and check-out times (within the constraints of available time slots).
150+
151+
#### Step 1: Create the access code
152+
153+
Provide the `device_id`, set `is_offline_access_code` to `true`, and specify `starts_at` and `ends_at` timestamps. Make sure these times match a configured time slot on the device (within 1 hour tolerance).
154+
155+
**Python example:**
156+
157+
```python
158+
# Get the device
159+
device = seam.locks.get(
160+
device_id="11111111-1111-1111-1111-444444444444"
161+
)
162+
163+
# Confirm offline access code support
164+
if device.can_program_offline_access_codes:
165+
# Create the code
166+
access_code = seam.access_codes.create(
167+
device_id=device.device_id,
168+
name="Guest - Room 101",
169+
starts_at="2024-09-10T16:00:00-07:00", # Must match lock's timezone
170+
ends_at="2024-09-15T10:00:00-07:00",
171+
is_offline_access_code=True
172+
)
173+
174+
print(f"Code created: {access_code.code}")
175+
print(f"Status: {access_code.status}")
176+
```
177+
178+
#### Step 2: Verify the code was set
179+
180+
Access codes go through three lifecycle phases:
181+
182+
1. **Unset**: Code created but not yet active
183+
2. **Setting**: Seam is registering the code with Dormakaba's server
184+
3. **Set**: Code is ready to use
185+
186+
**Option A: Polling method**
187+
188+
```python
189+
import time
190+
191+
# Poll until status is 'set'
192+
access_code = seam.access_codes.get(access_code_id="your-code-id")
193+
while access_code.status != "set":
194+
time.sleep(1)
195+
access_code = seam.access_codes.get(access_code_id=access_code.access_code_id)
196+
197+
print(f"Code ready! PIN: {access_code.code}")
198+
```
199+
200+
**Option B: Webhook method**
201+
202+
Subscribe to `access_code.set_on_device` webhook events to receive notifications when codes are ready.
203+
204+
***
205+
206+
### Creating daily-bound access codes
207+
208+
Daily-bound codes are useful when you need day-level granularity and want more flexible rounding.
209+
210+
#### Step 1: Create the access code
211+
212+
For daily-bound codes, specify the same time (but different dates) in `starts_at` and `ends_at`. You can also set `max_time_rounding` to `1day` to allow Seam to round up to a full day to match available slots.
213+
214+
{% tabs %}
215+
{% tab title="Python" %}
216+
```python
217+
# Create daily-bound code
218+
access_code = seam.access_codes.create(
219+
device_id=device.device_id,
220+
name="Guest - Room 101",
221+
starts_at="2024-09-16T00:00:00-07:00",
222+
ends_at="2024-09-18T23:59:00-07:00",
223+
max_time_rounding="1d", # Allow day-level rounding
224+
is_offline_access_code=True
225+
)
226+
227+
print(f"Code created: {access_code.code}")
228+
```
229+
{% endtab %}
230+
231+
{% tab title="Javascript" %}
232+
```javascript
233+
// Create daily-bound code
234+
const accessCode = await seam.accessCodes.create({
235+
device_id: device.device_id,
236+
name: "Guest - Room 101",
237+
starts_at: "2024-09-16T00:00:00-07:00",
238+
ends_at: "2024-09-18T23:59:00-07:00",
239+
max_time_rounding: "1d", // Allow day-level rounding
240+
is_offline_access_code: true
241+
});
242+
243+
console.log(`Code created: ${accessCode.code}`);
244+
```
245+
{% endtab %}
246+
{% endtabs %}
247+
248+
#### Step 2: Verify the code was set
249+
250+
Use the same polling or webhook methods as hourly-bound codes to confirm the code is ready.
251+
252+
***
253+
254+
### Troubleshooting
255+
256+
**"No time slots found" error**
257+
258+
This means your booking times don't match any configured time slot within the 1-hour tolerance.
259+
260+
**Check what's configured:**
261+
262+
```python
263+
# List all time slots for debugging
264+
device = seam.devices.get(device_id="your-device-id")
265+
time_slots = device.properties.get("dormakaba_oracode_metadata", {}).get("predefined_time_slots", [])
266+
267+
if not time_slots:
268+
print("❌ No time slots configured on this device")
269+
else:
270+
print(f"✓ {len(time_slots)} time slots configured:")
271+
for slot in time_slots:
272+
print(f" • {slot['name']}")
273+
print(f" Check-in: {slot['check_in_time']}")
274+
print(f" Check-out: {slot['check_out_time']}")
275+
```
276+
277+
**Solutions:**
278+
279+
* Adjust your booking times to be within 1 hour of an available slot
280+
* Contact your Dormakaba installer to add time slots matching your booking patterns
281+
282+
**Code creation fails silently**
283+
284+
This typically happens with automated systems. Verify that:
285+
286+
* Time slots are configured for the door
287+
* Booking times are within 1 hour of a configured slot
288+
* The device supports offline access codes (`can_program_offline_access_codes` is `true`)
289+
290+
**Different behavior on different doors**
291+
292+
Time slots are configured per door. Check each device individually:
293+
294+
python
295+
296+
```python
297+
# Check all devices in an account
298+
devices = seam.devices.list(connected_account_id="your-account-id")
299+
300+
for device in devices:
301+
time_slots = device.properties.get("dormakaba_oracode_metadata", {}).get("predefined_time_slots", [])
302+
print(f"{device.properties.get('name')}: {len(time_slots)} time slots")
303+
304+
if not time_slots:
305+
print(f" ⚠️ WARNING: No time slots configured!")
306+
```
307+
308+
***
309+
310+
### Best practices
311+
312+
**Always check for time slots first:** Before attempting to create codes, verify that time slots are configured on the device.
313+
314+
**Plan your time slots carefully:** Work with your installer to configure time slots that match your most common booking patterns. Include a 24-hour slot (12:00 PM → 12:00 PM) for maximum flexibility.
315+
316+
**Test before going live:** After your installer configures time slots, wait 30 minutes for Seam to sync, then create test codes to verify everything works.
317+
318+
**Monitor code limits:** Since codes cannot be deleted, be aware of your device's code limit to avoid reaching capacity.
319+
320+
**Use consistent naming:** Include meaningful names for codes (e.g., "Guest - Room 101 - Sept 10-15") to help with tracking and troubleshooting.
321+
322+
***
323+
324+
### Need help?
325+
326+
* For time slot configuration: Contact your Dormakaba installer
327+
* For Seam API questions: [[email protected]](mailto:[email protected])
328+
* For detailed time slot guidance: See our [Time Slot Configuration Guide](https://seam-knowledge-base.help.usepylon.com/articles/3198102890-dormakaba-oracode-time-slot-configuration)

0 commit comments

Comments
 (0)