esphome-sesame3

ESPHome Smart Lock component for CANDYHOUSE SESAME 5 / SESAME 5 PRO / SESAME bot / SESAME 3 / SESAME 4 / SESAME Bike, control via Bluetooth LE

[!NOTE] This component does not use ESPHome's built-in BTClient functionality. Therefore, this component cannot coexist with other BLE components in the same ESP32. Use this component in a separate ESP32 device from other BLE components.

When upgrading to 0.10.0 or later from previous versions

See Upgrade Guide.

Setup this component

You need to add compiler / library options to ESPHome base configuration, and external_components section link to this component.

esphome:
  libraries:
    - https://github.com/homy-newfs8/libsesame3bt#0.17.0
  platformio_options:
    build_flags:
      - -std=gnu++17 -Wall -Wextra
      - -DMBEDTLS_DEPRECATED_REMOVED -DCONFIG_BT_NIMBLE_ROLE_BROADCASTER_DISABLED -DCONFIG_BT_NIMBLE_ROLE_PERIPHERAL_DISABLED
# Configure the maximum number of connections as required
      - -DCONFIG_BT_NIMBLE_MAX_CONNECTIONS=4
    build_unflags:
      - -std=gnu++11
    lib_ldf_mode: 'deep'

esp32:
  board: esp32-c3-devkitm-1
  framework:
    type: arduino

external_components:
  - source:
      type: git
      url: https://github.com/homy-newfs8/esphome-sesame3
      ref: v0.10.0
    components: [ sesame, sesame_ble ]

Select the ESP32 board you want to use. Arduino framework is required.

If you want to use more than four SESAME devices with one ESP32 module, edit the CONFIG_BT_NIMBLE_MAX_CONNECTIUONS parameter (It might be a good idea to check the free memory with ESPHome's Debug component).

Configure for your SESAME

Minimum configuration

sesame:
  model: sesame_5
  # 6 bytes colon separated Bluetooth address
  address: "ab:cd:ef:01:02:03"
  # 16 bytes binary in hexadecimal
  secret: "0123456789abcdef0123456789abcdef"
  # 64 bytes binary in hexadecimal (Empty for SESAME 5 / PRO)
  public_key: ""
  lock:
    id: lock_1
    name: Lock1
    tag: "My awesome system"

If define id: of sesame: component, it will be used as logging prefix.

sesame:
  id: sesame1
  model: sesame_5
    :
    :

[05:23:27][D][sesame1:317]: connecting
[05:23:31][D][sesame1:321]: connect done
[05:23:31][I][sesame1:283]: Authenticated by SESAME

Configuration variables

model (Required): Model of SESAME. Use one of: sesame_5, sesame_5_pro, sesame_touch, sesame_touch_pro, open_sensor, sesame_bike_2, sesame_4, sesame_3, sesame_bot, sesame_bike
address (Required, string): See below.
secret (Required, string): See below.
public_key (Required for SESAME OS2 models, string): See below.
timeout (Optional, Time): Connection to SESAME timeout value. Defaults to 10s.
connect_retry_limit (Optional, int): Specifies the number of connection failures before reboot the ESP32 module. Defaults to 0 (do not reboot).
always_connect (Optional, bool): Keep connection with SESAME. Must be true when this component contains lock object. Defaults to true. If set to false, disconnect from SESAME after receiving the status (and reconnect if update_interval is set).
update_interval (Optional, Time): Request SESAME to send current status with this interval. Some devices (SESAME Touch) do not send updated status without this option. Defaults to never.
lock (Optional, sesame_lock): Lock specific configurations. See below.

Expose SESAME status as sensors

battery_pct (Optional, Sensor): See below
- name (Required, string): The name of the battery level sensor.
- All other options from sensor
battery_voltage (Optional, Sensor): See below
- name (Required, string): The name of the voltage sensor.
- All other options from sensor
connection_sensor (Optional, Binary Sensor): SESAME connection state is exposed as a binary sensor.
- name (Required, string): The name of connection sensor.
- All other options from binary_sensor

Lock specific variables

In addition to base Lock variables:

tag (Optional, string): Tag value recorded on operation history. Defaults to "ESPHome". If you want to use various tag values on automation, see below.
history_tag (Optional, Text Sensor): See below
- name (Required, string): The name of the history tag text_sensor.
- All other options from text_sensor
history_type (Optional, Sensor): See below
- name (Required, string): The name of the history type sensor.
- All other options from sensor
unknown_state_alternative (Optional, lock_state): If the lock state of SESAME is unknown (for example, before connecting or during disconnection), this module notifies HomeAssistant of the NONE state. Currently, HomeAssinstant seems to treat the NONE state as "Unlocked".
If you don't want it to be treated as "Unlocked", you can send the unknown state as any other state (candidates: NONE, LOCKED, UNLOCKED, JAMMED, LOCKING, UNLOCKING). If not set as this variable, this module will not send LOCKING and UNLOCKING, so you can write automation scripts that interpret these values as "UNKNOWN".
unknown_state_timeout (Optional, Time): If you do not want disconnection from SESAME to be immediately treated as unknown, set a timeout value with this variable. Defaults to 20s.

Parameter values for your SESAME

`address` (Bluetooth LE MAC Address)

You can identify your SESAME address by using ESPHome BLE tracker with sesame_ble component. First, remove sesame: component definition and add below to your configuration:

logger:

sesame_ble:

(logger must be specified for logging output)

Upload and start ESP32, logging message contains discovered SESAME devices information:

[08:20:23][I][sesame_ble:107]: 01:02:03:04:05:06 SESAME 5 UUID=01020304-0102-0102-0102-010203040506

Colon separated 6 bytes is Bluetooth address, if you have multiple SESAME devices, distinguish with UUID (You can check the UUID of a SESAME using the SESAME smartphone app).

Configuration for this device will be:

sesame:
  address: 01:02:03:04:05:06

[!NOTE] sesame component cannot coexist with other BLE components including esp32_ble_tracker. Once you have identified SESAME's BLE address, you will need to remove the above configuration.

`secret` (Secret key of your SESAME)

Secret is PSK for authentication and encryption. You can retrieve your SESAME's secret from QR code shown on SESAME smartphone app.

Easy way

Use sesame-qr-reader. Display Owner or Manager key on SESAME smartphone app, then upload the QR code image. Use the displayed Secret Key value.

DIY way

Display Owner or Manager key and decode the QR code with any QR decoder. Decoded string is URI like below:

ssm://UI?t=sk&sk=BQECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUm&l=1&n=セサミ 5

Query parameter sk is base64 encoded binary data.

Above base64 string is decoded as below:

00000000  05 01 02 03 04 05 06 07  08 09 0a 0b 0c 0d 0e 0f  |................|
00000010  10 11 12 13 14 15 16 17  18 19 1a 1b 1c 1d 1e 1f  |................|
00000020  20 21 22 23 24 25 26                              | !"#$%&|

First one byte is model number: 0 = SESAME 3, 2 = SESAME bot, 5 = SESAME 5, and so on. And following 16 bytes are the secret.

The example data above shows that the model is SESAME 5 and the secret is 16 bytes from 01 to 10. So, configuration is:

sesame:
  address: 01:02:03:04:05:06
  secret: "0102030405060708090a0b0c0d0e0f10"

On SESAME OS2 devices (SESAME 3 / 4 / bot / bike), sk is more long string and decoded binary is 99 bytes. Still the location and length of secret is the same.

`public_key` (Public key for SESAME OS2 devices)

Public key for encryption. Do not specify this parameter for SESAME OS3 devices (SESAME 5 / SESAME 5 PRO).

On OS2 devices, you can retrieve key value from QR code.

Easy way

As above, use sesame-qr-reader. Use Public Key value.

DIY way

Decoded OS2 QR code is:

ssm://UI?t=sk&sk=AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4
OTo7PD0+P0BBQkNERUZHSElKS0xNTk9QUVJTVFVWV1hZWltcXV5fYGFi&l=1&n=セサミ 3

Base64 decoded sk value is:

00000000  00 01 02 03 04 05 06 07  08 09 0a 0b 0c 0d 0e 0f  |................|
00000010  10 11 12 13 14 15 16 17  18 19 1a 1b 1c 1d 1e 1f  |................|
00000020  20 21 22 23 24 25 26 27  28 29 2a 2b 2c 2d 2e 2f  | !"#$%&'()*+,-./|
00000030  30 31 32 33 34 35 36 37  38 39 3a 3b 3c 3d 3e 3f  |0123456789:;<=>?|
00000040  40 41 42 43 44 45 46 47  48 49 4a 4b 4c 4d 4e 4f  |@ABCDEFGHIJKLMNO|
00000050  50 51 52 53 54 55 56 57  58 59 5a 5b 5c 5d 5e 5f  |PQRSTUVWXYZ[\]^_|
00000060  60 61 62                                          |`ab|

publik_key is the 64 bytes following the secret, so public_key configuration is:

sesame:
  address: 01:02:03:04:05:06
  secret: "0102030405060708090a0b0c0d0e0f10"
  public_key: "1112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f303132333435363738393a3b3c3d3e3f404142434445464748494a4b4c4d4e4f50"

Expose SESAME battery information as sensor value

You can expose SESAME battery remaining percentage and voltage value, then show on your dashboard, use with your automation and etc. (in ESPHome and HomeAssistant)

sesame:
    :
    :
  battery_pct:
    name: "Lock1_battery_level"
  battery_voltage:
    name: "Lock1_battery_voltage"

Operation History TAG and History type

You can expose who or what operated SESAME. These values are updated before lock/unlock state. Therefore, you can use history values in your automation's lock state change actions.

sesame:
    :
    :
  lock:
    history_tag:
      name: "Lock1_history_tag"
    history_type:
      name: "Lock1_history_type"

History is Lock specific feature, so define these sensors under lock: object.

TAG string

User name of SESAME smartphone app
Registered fingerprint name of SESAME Touch
tag value of this module
Other API argument (Official Web API, SDK, etc.)

Type value

Value	Name	Comment
0	NONE
1	BLE_LOCK	By BT API (Smartphone app, SESAME Touch, this component, etc.)
2	BLE_UNLOCK	By BT API (Smartphone app, SESAME Touch, this component, etc.)
3	TIME_CHANGED
4	AUTOLOCK_UPDATED
5	MECH_SETTING_UPDATED
6	AUTOLOCK
7	MANUAL_LOCKED	By hand
8	MANUAL_UNLOCKED	By hand
9	MANUAL_ELSE
10	DRIVE_LOCKED	SESAME bot
11	DRIVE_UNLOCKED	SESAME bot
12	DRIVE_FAILED
13	BLE_ADV_PARAM_UPDATED
14	WM2_LOCK	By smartphone app (via Wi-Fi Module 2)
15	WM2_UNLOCK	By smartphone app (via Wi-Fi Module 2)
16	WEB_LOCK	By Official Web API
17	WEB_UNLOCK	By Official Web API
21	DRIVE_CLICKED	SESAME bot (Not listed in Android API)

Notes on SESAME bot

SESAME bot supports lock.open action in addition to lock.lock and lock.unlock actions. lock.open performs the same behavior as a smartphone SESAME app.

Using various tag values on operation

SESAME records the TAG string of each operation in the operation history. If you want to use different TAG values for automation, call lock, unlock, click functions directory from lambda. Below is a sample service definition that can be called from Home Assistant.

esphome:
  name: entrance
api:
  services:
  - service: sesame_with_tag
    variables:
      is_lock: bool
      tag: string
    then:
      lambda: |-
        if (is_lock) {
          id(lock_1).lock(tag);
        } else {
          id(lock_1).unlock(tag);
        }

sesame:
    :
    :
  lock:
    id: lock_1
    name: Lock1
      :
      :

This service will be seen as esphome.entrance_sesame_with_tag on Home Assistant ("entrance" is the entity name of ESPHome device).

# Example Home Assistant Service Call to toggle lock
service: esphome.entrance_sesame_with_tag
data:
  is_lock: "{{ not is_state('lock.entrance_lock1', 'locked') }}"
  tag: "{{ ***Anything*** }}"

Full example configuration file

See sesame.yaml.

wifi_ssid, wifi_passphrase, sesame_pubkey, sesame_secret, sesame_address must be set according to your configuration. If you know how to use secrets.yaml, use it. If you don't, edit sesame.yaml (Remove !secret when replace values).

Avoid WiFi issues

This module starts connecting to SESAME after the WiFi connection when ESPHome starts, so it should not interfere with the WiFi connection.

If this module seems to be interfering with your WiFi connection, please try the following settings.

sesame:
  setup_priority: 0
    :
    :

This setting defers the connection to SESAME until the very end of ESPHome's initialization.

Upgrade Guide to 0.10.0 or later

There are big structural changes in configuration YAML. It's not difficult to convert to new schema, for example:

OLD:

esphome:
  libraries:
    - https://github.com/homy-newfs8/libsesame3bt#0.16.0
    :
    :
external_components:
- source:
    type: git
    url: https://github.com/homy-newfs8/esphome-sesame3
    ref: v0.9.0
  components: [ sesame_lock, sesame_ble ]

lock:
- platform: sesame_lock
  name: Lock1
  id: lock_1
  model: sesame_5
  tag: "My awesome system"
  address: "ab:cd:ef:01:02:03"
  secret: "0123456789abcdef0123456789abcdef"
  battery_pct:
    name: Lock1_battery_level
  history_tag:
    name: Lock1_history_tag

NEW:

esphome:
  libraries:
    - https://github.com/homy-newfs8/libsesame3bt#0.17.0
    :
    :
external_components:
- source:
    type: git
    url: https://github.com/homy-newfs8/esphome-sesame3
    ref: v0.10.0
  components: [ sesame, sesame_ble ]

sesame:
  model: sesame_5
  address: "ab:cd:ef:01:02:03"
  secret: "0123456789abcdef0123456789abcdef"
  battery_pct:
    name: Lock1_battery_level
  lock:
    name: Lock1
    id: lock_1
    tag: "My awesome system"
    history_tag:
      name: Lock1_history_tag

In summary,

Update libsesame3bt version.
External component name changed from sesame_lock to sesame.
Definition starts with sesame: object.
Lock-specific settings have been moved under the lock: object.
Non-locking devices (such as SESAME Touch) are supported. There is no need to define a lock: object for such devices.

If you want to control multiple SESAME devices by one ESP32, define multiple sesame objects:

sesame:
- id: lock1
  model: sesame_5
  address: "ab:cd:ef:01:02:03"
  secret: "0123456789abcdef0123456789abcdef"
  battery_pct:
    name: Lock1_battery_level
  lock:
    name: Lock1
    id: lock_1
    tag: "My awesome system"
    history_tag:
      name: Lock1_history_tag
- id: touch1
  model: sesame_touch
  address: "12:34:56:78:9a:bc"
  secret: "0123456789abcdef0123456789abcdef"
  battery_pct:
    name: Touch1_battery_level
  update_interval: 12h

The id: of the sesame object is not required. However, it is used as a logging prefix, which is useful for troubleshooting in multiple device environments.

SESAME access library for ESP32 libsesame3bt
SESAME 5 / SESAME 5 PRO Smart Lock CANDY HOUSE (SESAME 3 and 4 are End of Sale)

homy-newfs8/esphome-sesame3

esphome-sesame3

When upgrading to 0.10.0 or later from previous versions

Setup this component

Configure for your SESAME

Minimum configuration

Configuration variables

Expose SESAME status as sensors

Lock specific variables

Parameter values for your SESAME

address (Bluetooth LE MAC Address)

secret (Secret key of your SESAME)

Easy way

DIY way

public_key (Public key for SESAME OS2 devices)

Easy way

DIY way

Expose SESAME battery information as sensor value

Operation History TAG and History type

TAG string

Type value

Notes on SESAME bot

Using various tag values on operation

Full example configuration file

Avoid WiFi issues

Upgrade Guide to 0.10.0 or later

Related

`address` (Bluetooth LE MAC Address)

`secret` (Secret key of your SESAME)

`public_key` (Public key for SESAME OS2 devices)