Skip to content

Tedee Binding ​

The Tedee binding integrates Tedee Smart Locks with openHAB through either:

  • the local Tedee Bridge API, or
  • the Tedee Cloud API.

Local communication does not require the Tedee Cloud API for normal operation. Cloud access is available as an optional alternative and can be used without a local Tedee Bridge. Tedee also requires the Bridge itself to have internet connectivity so that it can obtain and refresh access certificates for paired devices.

Cloud or local bridges control their assigned lock devices. Cloud and local bridge can operate on the same locks simultaneously.

Supported Things ​

Tedee Local Bridge ​

Configuration ​

ParameterTypeRequiredDefaultDescription
iptextYes—IP address of the Tedee Bridge
portintegerNo80HTTP port of the Tedee Bridge
apiTokenpasswordYes—Tedee Bridge API token, encryption set to ON
pollIntervalintegerNo300Configured interval in seconds for bridge monitoring

Tedee Cloud Bridge ​

Configuration ​

ParameterTypeRequiredDefaultDescription
personalAccessKeypasswordYes—Tedee Personal Access Key used for Cloud API authentication
pollIntervalintegerNo300Cloud status and discovery polling interval in seconds

The Personal Access Key should be treated as a secret and must not be published in repositories, screenshots or logs.

Tedee Lock ​

Configuration ​

ParameterTypeRequiredDefaultDescription
deviceIdintegerYes—Numeric Tedee device ID
pollIntervalintegerNo300Lock status polling interval in seconds

Channels ​

The Lock Thing exposes the following channels.

Lock Control ​

Channel IDItem TypeReadCommandDescription
lockSwitchYesON / OFFLock or unlock the Tedee lock
actionStringNoLOCK, UNLOCK, UNLOCK_NO_PULL, UNLOCK_OR_PULL, PULLExecute a specific Tedee action

The lock channel is the simple Switch interface:

  • ON → LOCK
  • OFF → normal UNLOCK

The action channel provides explicit actions:

  • LOCK
  • UNLOCK
  • UNLOCK_NO_PULL
  • UNLOCK_OR_PULL
  • PULL

When the Tedee lock has automatic pull spring enabled, normal UNLOCK can also perform the pull spring operation. UNLOCK_NO_PULL unlocks without pulling the spring.

Lock State ​

Channel IDItem TypeDescription
stateStringInternal Tedee lock state
door-stateStringDoor sensor state, if supported by the lock/sensor setup
batteryNumberBattery level in percent
chargingSwitchWhether the lock is charging
jammedSwitchWhether the lock reports a jam
connectedSwitchWhether the lock is connected to its Tedee transport

Tedee Lock States ​

StateMeaning
0UNCALIBRATED
1CALIBRATION
2OPEN
3PARTIALLY_OPEN
4OPENING
5CLOSING
6CLOSED
7PULL_SPRING
8PULLING
9UNKNOWN
255UNPULLING

Tedee Door States ​

ValueMeaning
0NOT_PAIRED
1UNKNOWN
2OPENED
3CLOSED

A physical door sensor is required for meaningful door-state testing.

Device Settings ​

The following Tedee device settings are exposed as read-only channels:

Channel IDItem TypeDescription
auto-lock-enabledSwitchAutomatic lock enabled
auto-lock-delayNumberAutomatic lock delay
auto-lock-implicit-enabledSwitchImplicit automatic lock enabled
auto-lock-implicit-delayNumberImplicit automatic lock delay
pull-spring-enabledSwitchPull spring feature enabled
pull-spring-durationNumberPull spring duration
auto-pull-spring-enabledSwitchAutomatic pull spring enabled
postponed-lock-enabledSwitchPostponed lock enabled
postponed-lock-delayNumberPostponed lock delay
button-lock-enabledSwitchPhysical button locking enabled
button-unlock-enabledSwitchPhysical button unlocking enabled

These settings are read from the Tedee lock response and refreshed by polling or REFRESH. Writing settings is not currently implemented.

Thing Properties ​

The Lock Thing exposes these properties:

PropertyDescription
nameTedee lock name
serialNumberTedee serial number
deviceTypeTedee device type
firmwareVersionFirmware/software version reported by the Tedee API

Text .things Configuration ​

The Things can be defined in a .things file.

Local Tedee Bridge ​

dsl
Bridge tedee:local-bridge:home "Tedee Bridge" [
    ip="BRIDGE_IP",
    port=80,
    apiToken="YOUR_API_TOKEN",
    pollInterval=300
] {
    Thing lock:lockname "lock label" [
        deviceId=XXX,
        pollInterval=300
    ]
}

Tedee Cloud ​

dsl
Bridge tedee:cloud-bridge:cloud "Tedee Cloud" [
    personalAccessKey="YOUR_PERSONAL_ACCESS_KEY",
    pollInterval=300
] {
    Thing lock:lockname "Lock label" [
        deviceId=XXXX,
        pollInterval=300
    ]
}

Items ​

Channels need to be linked to Items before their states are consumed by openHAB rules, UI pages or other automation.

Main Lock Items ​

ItemTypeChannelDescription
Tedee_LockSwitchlockLock/unlock control
Tedee_StateStringstateLock state
Tedee_Door_StateStringdoor-stateDoor sensor state
Tedee_BatteryNumberbatteryBattery level
Tedee_ChargingSwitchchargingCharging state
Tedee_JammedSwitchjammedJam status
Tedee_ConnectedSwitchconnectedConnection status
Tedee_ActionStringactionExplicit Tedee actions

Main Lock Items Example ​

dsl
Switch Tedee_Lock "Lock" {channel="tedee:lock:home:locknamehome:lock"}
String Tedee_State "Lock State [%s]" {channel="tedee:lock:home:locknamehome:state"}
String Tedee_Door_State "Door State [%s]" {channel="tedee:lock:home:locknamehome:door-state"}
Number Tedee_Battery "Battery [%.0f %%]" {channel="tedee:lock:home:locknamehome:battery"}
Switch Tedee_Charging "Charging" {channel="tedee:lock:home:locknamehome:charging"}
Switch Tedee_Jammed "Jammed" {channel="tedee:lock:home:locknamehome:jammed"}
Switch Tedee_Connected "Connected" {channel="tedee:lock:home:locknamehome:connected"}
String Tedee_Action "Action" {channel="tedee:lock:home:locknamehome:action"}

The same Item definitions can be used for a Cloud Lock by replacing the Thing UID:

text
tedee:lock:cloud:locknamecloud:<channel>

For example:

dsl
Switch Tedee_Cloud_Connected "Cloud Lock Connected" {channel="tedee:lock:cloud:locknamecloud:connected"}

Device Settings Items ​

ItemTypeChannelDescription
Tedee_AutoLockEnabledSwitchauto-lock-enabledAutomatic lock
Tedee_AutoLockDelayNumberauto-lock-delayAutomatic lock delay
Tedee_AutoLockImplicitEnabledSwitchauto-lock-implicit-enabledImplicit automatic lock
Tedee_AutoLockImplicitDelayNumberauto-lock-implicit-delayImplicit automatic lock delay
Tedee_PullSpringEnabledSwitchpull-spring-enabledPull spring enabled
Tedee_PullSpringDurationNumberpull-spring-durationPull spring duration
Tedee_AutoPullSpringEnabledSwitchauto-pull-spring-enabledAutomatic pull spring
Tedee_PostponedLockEnabledSwitchpostponed-lock-enabledPostponed locking
Tedee_PostponedLockDelayNumberpostponed-lock-delayPostponed lock delay
Tedee_ButtonLockEnabledSwitchbutton-lock-enabledButton locking
Tedee_ButtonUnlockEnabledSwitchbutton-unlock-enabledButton unlocking

Device Settings Items Example ​

dsl
Switch Tedee_AutoLockEnabled "Auto Lock Enabled" {channel="tedee:lock:home:locknamehome:auto-lock-enabled"}
Number Tedee_AutoLockDelay "Auto Lock Delay" {channel="tedee:lock:home:locknamehome:auto-lock-delay"}
Switch Tedee_PullSpringEnabled "Pull Spring Enabled" {channel="tedee:lock:home:locknamehome:pull-spring-enabled"}
Number Tedee_PullSpringDuration "Pull Spring Duration" {channel="tedee:lock:home:locknamehome:pull-spring-duration"}
Switch Tedee_Tedee_AutoLockImplicitEnabled "Auto Lock Implicit Enabled" {channel="tedee:lock:home:locknamehome:auto-lock-implicit-enabled"}
Number Tedee_AutoLockImplicitDelay "Auto Lock Implicit Delay" {channel="tedee:lock:home:locknamehome:auto-lock-implicit-delay"}
Switch Tedee_AutoPullSpringEnabled "Auto Pull Spring Enabled" {channel="tedee:lock:home:locknamehome:auto-pull-spring-enabled"}
Switch Tedee_PostponedLockEnabled "Postponed Lock Enabled" {channel="tedee:lock:home:locknamehome:postponed-lock-enabled"}
Number Tedee_PostponedLockDelay "Postponed Lock Delay" {channel="tedee:lock:home:locknamehome:postponed-lock-delay"}
Switch Tedee_ButtonLockEnabled "Button Lock Enabled" {channel="tedee:lock:home:locknamehome:button-lock-enabled"}
Switch Tedee_ButtonUnlockEnabled "Button Unlock Enabled" {channel="tedee:lock:home:locknamehome:button-unlock-enabled"}

Commands ​

Explicit Actions Through the Action Channel ​

The action Item accepts:

text
LOCK
UNLOCK
UNLOCK_NO_PULL
PULL

UNLOCK_NO_PULL is useful when automatic pull spring is enabled but the desired operation is to unlock without pulling the spring.

The Tedee APIs return an acknowledgement as soon as the operation has started. The final state is reported later through polling and/or local callback events.

Rules Examples ​

Unlock Without Pull ​

DSL-style rule:

java
sendCommand(Tedee_Action, "UNLOCK_NO_PULL")

Lock ​

java
sendCommand(Tedee_Action, "LOCK")

Pull Spring ​

java
sendCommand(Tedee_Action, "PULL")

Refresh ​

The binding supports RefreshType.

A linked Item can receive:

text
openhab:send Tedee_Battery REFRESH

or:

text
openhab:send Tedee_Action REFRESH

A refresh triggers a complete lock refresh rather than updating only the requested channel. The API response contains multiple values, so all lock channels and properties are updated together.

The default lock polling interval is currently 300 seconds.

Local Webhooks ​

Webhooks apply to the local Tedee Bridge connection.

The binding contains an HTTP webhook endpoint:

text
/tedee/webhook

The Tedee Bridge can POST status events to this endpoint.

Callback Configuration ​

json
{
  "url": "http://OPENHAB_IP:8080/tedee/webhook",
  "method": "POST",
  "headers": [
    {
      "header_name": "X-Tedee-Webhook-Secret",
      "header_value": "generated by the binding"
    }
  ]
}

The callback must point to the LAN address of the openHAB server, not localhost or 127.0.0.1. The local Bridge Handler generates a separate secret for each configured local bridge and validates it before applying webhook updates. The handler also removes stale or duplicate binding callbacks.

Implemented Webhook Events ​

The servlet processes:

text
lock-status-changed
device-connection-changed
device-settings-changed
device-battery-level-changed
device-battery-start-charging
device-battery-stop-charging
device-battery-fully-charged

Example payload received from a real Tedee Bridge:

json
{
  "event": "lock-status-changed",
  "timestamp": "2026-09-22T21:34:40.395Z",
  "data": {
    "deviceType": 2,
    "deviceId": XXX,
    "serialNumber": "XXXXXXX-000004",
    "state": 4,
    "jammed": 0,
    "source": 18,
    "user_id": 0,
    "doorState": 0
  }
}

The handler applies these values immediately:

  • state
  • doorState
  • jammed

The normal polling/refresh mechanism remains available as the fallback for the corresponding values.

Local API ​

The local binding communicates with the Tedee Bridge through:

text
http://<BRIDGE-IP>/v1.0

Main Local Endpoints ​

MethodEndpointPurpose
GET/v1.0/bridgeBridge status
GET/v1.0/lock/{id}Read one lock
GET/v1.0/lockRead available locks for discovery
POST/v1.0/lock/{id}/lockLock
POST/v1.0/lock/{id}/unlockUnlock
POST/v1.0/lock/{id}/pullPull spring
POST/v1.0/lock/{id}/unlock?mode=3Unlock without pull
POST/v1.0/lock/{id}/unlock?mode=4Decision whether unlock or pull action is performed, based on lockposition
GET/v1.0/callbackRead callbacks
POST/v1.0/callbackRegister callback
PUT/v1.0/callback/{callbackId}Update callback
DELETE/v1.0/callback/{callbackId}Remove callback

The mode=3 unlock operation is used for UNLOCK_NO_PULL.

Tedee documents lock, unlock and pull as asynchronous operations. The initial HTTP response confirms that the operation has started; the final state can be observed through a subsequent refresh, polling cycle or callback event.

Cloud Operations ​

The Cloud transport supports the same lock operations exposed by the local transport:

  • LOCK
  • UNLOCK
  • UNLOCK_NO_PULL
  • PULL

Cloud lock status is retrieved by polling. No local webhook or callback registration is required for Cloud Things.

Cloud Discovery ​

The Cloud Bridge provides automatic lock discovery from the Tedee account. Discovered locks use their Tedee deviceId as the representation property and are created below the Cloud Bridge.

Local and Cloud in Parallel ​

Local and Cloud bridges can be configured at the same time. For example, the same physical lock can be represented through both transports:

dsl
Bridge tedee:local-bridge:home "Tedee Bridge" [
    ip="BRIDGE_IP",
    port=80,
    apiToken="YOUR_API_TOKEN",
    pollInterval=300
] {
    Thing lock:lockname "Lock label" [
        deviceId=XXXXXX,
        pollInterval=300
    ]
}

Bridge tedee:cloud-bridge:cloud "Tedee Cloud" [
    personalAccessKey="YOUR_PERSONAL_ACCESS_KEY",
    pollInterval=300
] {
    Thing lock:lockname "Lock label" [
        deviceId=XXXXXX,
        pollInterval=300
    ]
}

The two Things are independent and use different transport paths to the same Tedee device. The api token for the local bridge can be extracted from the bridge in your tedee APP. The Personal Access Key can be retrieved from the tedee web.

Known Limitations ​

  • Door state cannot be fully validated as no supported door sensor available.
  • Additional device information such as RSSI and device revision is not currently exposed as channels or properties.
  • Device settings are currently read-only.
  • Local webhook processing is currently focused on lock-status-changed; other documented webhook events continue to be handled through polling/refresh.

References ​

Tedee ​

Full example ​

The following example shows a local Tedee Bridge and a Tedee Cloud Bridge. The same lock may be configured through both transports; use separate Thing and Item names for each representation.

tedee.things ​

dsl
Bridge tedee:local-bridge:home "Tedee Bridge" [
    ip="192.168.1.50",
    port=80,
    apiToken="YOUR_API_TOKEN",
    pollInterval=300
] {
    Thing lock:frontdoor "Front Door" [
        deviceId=123456,
        pollInterval=300
    ]
}

Bridge tedee:cloud-bridge:account "Tedee Cloud" [
    personalAccessKey="YOUR_PERSONAL_ACCESS_KEY",
    pollInterval=300
] {
    Thing lock:frontdoor-cloud "Front Door (Cloud)" [
        deviceId=123456,
        pollInterval=300
    ]
}

The bridge IDs (home and account) and lock IDs (frontdoor and frontdoor-cloud) are examples. Replace the credentials and deviceId with values from your installation. For a local-only setup, omit the cloud bridge and its child Thing.

tedee.items ​

dsl
Group gTedee "Tedee Locks"

Switch TedeeFrontDoorLock "Front Door Lock" (gTedee) {channel="tedee:lock:home:frontdoor:lock"}
String TedeeFrontDoorState "Front Door State [%s]" (gTedee) {channel="tedee:lock:home:frontdoor:state"}
String TedeeFrontDoorDoorState "Front Door Door State [%s]" (gTedee) {channel="tedee:lock:home:frontdoor:door-state"}
Number TedeeFrontDoorBattery "Front Door Battery [%d %%]" (gTedee) {channel="tedee:lock:home:frontdoor:battery"}
Switch TedeeFrontDoorCharging "Front Door Charging" (gTedee) {channel="tedee:lock:home:frontdoor:charging"}
Switch TedeeFrontDoorJammed "Front Door Jammed" (gTedee) {channel="tedee:lock:home:frontdoor:jammed"}
Switch TedeeFrontDoorConnected "Front Door Connected" (gTedee) {channel="tedee:lock:home:frontdoor:connected"}
String TedeeFrontDoorAction "Front Door Action [%s]" (gTedee) {channel="tedee:lock:home:frontdoor:action"}
Switch TedeeFrontDoorAutoLockEnabled "Front Door Auto-Lock" (gTedee) {channel="tedee:lock:home:frontdoor:auto-lock-enabled"}
Number TedeeFrontDoorAutoLockDelay "Front Door Auto-Lock Delay [%d s]" (gTedee) {channel="tedee:lock:home:frontdoor:auto-lock-delay"}
Switch TedeeCloudFrontDoorLock "Front Door Lock (Cloud)" {channel="tedee:lock:account:frontdoor-cloud:lock"}
String TedeeCloudFrontDoorState "Front Door State (Cloud) [%s]" {channel="tedee:lock:account:frontdoor-cloud:state"}

The lock channel accepts ON and OFF commands. Use the action channel to send the string commands LOCK, UNLOCK, UNLOCK_NO_PULL, UNLOCK_OR_PULL, or PULL.

tedee.sitemap ​

dsl
sitemap tedee label="Tedee Locks" {
    Frame label="Front Door (Local)" {
        Switch item=TedeeFrontDoorLock label="Lock"
        Selection item=TedeeFrontDoorAction label="Action" mappings=[
            LOCK="Lock",
            UNLOCK="Unlock",
            UNLOCK_NO_PULL="Unlock without pull",
            UNLOCK_OR_PULL="Unlock or pull",
            PULL="Pull"
        ]
        Text item=TedeeFrontDoorState label="Lock state"
        Text item=TedeeFrontDoorDoorState label="Door state"
        Default item=TedeeFrontDoorBattery label="Battery"
        Text item=TedeeFrontDoorCharging label="Charging"
        Text item=TedeeFrontDoorJammed label="Jammed"
        Text item=TedeeFrontDoorConnected label="Connected"
        Text item=TedeeFrontDoorAutoLockEnabled label="Auto-lock enabled"
        Text item=TedeeFrontDoorAutoLockDelay label="Auto-lock delay"
    }
    Frame label="Front Door (Cloud)" {
        Switch item=TedeeCloudFrontDoorLock label="Lock"
        Text item=TedeeCloudFrontDoorState label="Lock state"
    }
}