open-sesame

n8n trigger node for SESAME smart lock events via AWS IoT MQTT

Package Information

Downloads: 5 weeklyĀ /Ā 17 monthly
Latest Version: 0.1.0

Available Nodes

Sesame Trigger icon
Sesame Trigger
Triggers the workflow when a SESAME smart lock is locked or unlocked

Documentation

n8n-nodes-open-sesame

A custom n8n trigger node that detects SESAME smart lock (CANDY HOUSE) lock/unlock events in real time.

It subscribes to Sesame device shadow updates via AWS IoT MQTT over WebSocket, enabling instant detection of lock/unlock events.

Installation

  1. Open your n8n instance
  2. Go to Settings > Community Nodes
  3. Enter n8n-nodes-open-sesame and click Install

Alternatively, install via CLI:

# In your n8n installation directory
npm install n8n-nodes-open-sesame

Setup

1. Get Your Sesame Device UUID

Open the device settings in the Sesame app and find your UUID.

2. Configure Credentials in n8n

  1. Start n8n
  2. Go to Credentials > New > Sesame API
  3. Enter your device UUID(s) in Device UUID(s) (comma-separated for multiple devices)

3. Create a Workflow

  1. Add a Sesame Trigger node
  2. Select your Sesame API credential
  3. Choose an Event Filter:
    • All Events ā€” both lock and unlock
    • Locked Only ā€” lock events only
    • Unlocked Only ā€” unlock events only
  4. Enable Emit Only On Change to trigger only when the state changes
  5. Connect downstream nodes (Slack, email, etc.)

Output Data

The trigger emits the following data:

{
  "event": "locked",
  "deviceUuid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "batteryVoltage": 5.92,
  "batteryPercentage": 95,
  "isBatteryCritical": false,
  "position": 123,
  "target": 0,
  "isInLockRange": true,
  "isInUnlockRange": false,
  "timestamp": "2026-02-09T12:00:00.000Z",
  "raw": {
    "mechst": "e803..."
  }
}

Field Reference

Field Type Description
event "locked" | "unlocked" Lock state
deviceUuid string Device UUID
batteryVoltage number Battery voltage (V)
batteryPercentage number Battery level (%)
isBatteryCritical boolean Low battery warning
position number Current lock position
target number Target position
timestamp string Event timestamp (ISO 8601)

Slack Notification Example

Connect Sesame Trigger to a Slack node and use expressions like:

šŸ” Sesame Lock Event
Event: {{ $json.event }}
Device: {{ $json.deviceUuid }}
Battery: {{ $json.batteryPercentage }}%
Time: {{ $json.timestamp }}

Testing

MQTT Subscribe Test

You can verify the AWS IoT connection and topic subscription without n8n:

npm install
npx tsx test/subscribe.ts <DEVICE_UUID>

The test runs through the following steps:

  1. Cognito Authentication ā€” obtain temporary credentials
  2. MQTT Connection ā€” WebSocket connection to the AWS IoT endpoint
  3. Topic Subscribe ā€” subscribe to the device shadow topic

After a successful subscription, it enters a message-waiting state. Operating the lock via the Sesame app or physically will display lock state and battery information in real time. Press Ctrl+C to exit.

How It Works

  • Obtains temporary credentials from AWS Cognito Identity Pool (unauthenticated public access)
  • Subscribes to device shadow updates via AWS IoT MQTT over WebSocket
  • Automatically refreshes credentials before expiration
  • Parses the mechst payload to extract lock state and battery information

License

MIT

Discussion