tedee-scripts

Shell scripts for controlling Tedee Smart Locks via the Tedee Bridge API.

Perfect for automating your lock with crontab or handling webhook events.

📑 Table of Contents

• Quick Start
• Project Structure
• Usage
• Automation with Crontab
• Telegram Notifications (Optional)
• Configuration Reference
• Lock States Reference
• Webhook Events
• Troubleshooting
• Tips & Best Practices
• Requirements
• Development
• License

🚀 Quick Start

1. Run Setup

The interactive setup script will guide you through all configuration:

./setup.sh

The setup script will:

• Guide you through entering all required settings
• Validate mandatory parameters (Bridge IP, API Token, Device ID)
• Optionally configure Telegram notifications
• Configure your preferred language (English or Spanish)
• Create the configuration file automatically
• Make all scripts executable

To reconfigure later, simply run ./setup.sh again.

2. Test It

Close/lock the door manually to verify everything works:

./bin/close

3. Automate It

Add to crontab to automatically close the door at a specific time:

crontab -e
# Close door every night at 10 PM
0 22 * * * /path/to/tedee-scripts/bin/close

That's it! 🎉

📁 Project Structure

tedee-scripts/
├── bin/                    # Executable scripts
│   ├── callback           # Webhook event handler
│   ├── close              # Close/lock the door
│   └── update             # Update repository
├── config/                 # Configuration files
│   └── tedee.conf         # Your config (not in git, generated by setup)
├── lib/                    # Shared libraries
│   └── tedee-common.sh    # Common functions
├── locales/                # Internationalization (i18n)
│   ├── en.sh              # English messages
│   └── es.sh              # Spanish messages
├── setup.sh               # Interactive setup
├── README.md
└── LICENSE

💻 Usage

Close/Lock the Door

./bin/close

The close script will:

• Check bridge connectivity before attempting to close
• Close/lock the door
• Retry on failure (configurable)
• Report lock status
• Send Telegram notification (if configured)
• Validate door state before and after closing

Handle Webhook Events

For Tedee Bridge API webhooks:

./bin/callback <event> <timestamp> <data>

Example:

./bin/callback "lock-status-changed" "2023-07-25T14:41:48.825Z" '{"deviceType":2,"deviceId":33819,"serialNumber":"19420103-000006","state":6,"jammed":0,"doorState":2}'

Update Scripts

Update to the latest version from GitHub:

# Update from main branch
./bin/update

# Update from a specific branch
./bin/update develop

Note: The update script uses curl and tar (no Git required). Perfect for Docker/minimal environments.

⏰ Automation with Crontab

This is the main use case for these scripts. Schedule automatic door locking/closing at specific times.

Basic Examples

# Edit your crontab
crontab -e

# Close door every night at 10 PM
0 22 * * * /path/to/tedee-scripts/bin/close

# Close every weekday at 11 PM
0 23 * * 1-5 /path/to/tedee-scripts/bin/close

# Close on weekends at midnight
0 0 * * 6,0 /path/to/tedee-scripts/bin/close

# With logging
0 22 * * * /path/to/tedee-scripts/bin/close >> /tmp/tedee-close.log 2>&1

Important: Always use absolute paths in crontab!

Testing Crontab

# Test manually first
./bin/close

# Check crontab logs (macOS)
log show --predicate 'process == "cron"' --last 1h

# Check system log (Linux)
grep CRON /var/log/syslog

Automatic Updates (Optional)

Schedule automatic script updates:

# Update weekly on Sunday at 3 AM
0 3 * * 0 /path/to/tedee-scripts/bin/update >> /tmp/tedee-update.log 2>&1

Alternative: Crontab UI with Docker

For easier management of cron jobs through a web interface, you can use crontab-ui with Docker Compose.

Create docker-compose.yml

Create a docker-compose.yml file in your preferred location:

services:
  crontab-ui:
    image: alseambusher/crontab-ui:latest
    container_name: crontab-ui
    restart: unless-stopped
    environment:
      - TZ=Europe/Madrid  # Set your timezone
      - BASIC_AUTH_USER=  # Set your username for web interface
      - BASIC_AUTH_PWD=   # Set your password for web interface
    ports:
      - "8000:8000"
    volumes:
      - /path/to/tedee:/scripts/tedee  # Mount your tedee-scripts directory
    
    # Health check to ensure the service is running
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

Configuration

• TZ: Set your timezone (e.g., Europe/Madrid, America/New_York)
• BASIC_AUTH_USER: Username for web interface authentication
• BASIC_AUTH_PWD: Password for web interface authentication
• volumes: Mount the tedee-scripts directory to /scripts/tedee in the container
  • Replace /path/to/tedee with the absolute path to your tedee-scripts directory

Start the Service

# Start the container
docker compose up -d

# Check the logs
docker compose logs -f

# Stop the container
docker compose down

Note: On older setups, you may need to use docker-compose instead of docker compose.

Access the Web Interface

Open your browser and navigate to: http://localhost:8000

Login with the credentials you set in BASIC_AUTH_USER and BASIC_AUTH_PWD.

Adding Cron Jobs via UI

In the web interface, you can add cron jobs that run your tedee scripts:

• Expression: 0 22 * * * (10 PM every day)
• Command: /scripts/tedee/bin/close
• Name: Auto-close door at night

The UI provides a visual cron expression builder and validation to make scheduling easier.

🤖 Telegram Notifications (Optional)

To receive notifications about lock events via Telegram, you need to create a Telegram bot and obtain the necessary credentials.

1. Create a Telegram Bot

1. Open Telegram and search for @BotFather (the official bot for creating bots)
2. Start a chat with BotFather and send the command: /newbot
3. Follow the prompts:
   • Choose a name for your bot (e.g., "My Tedee Lock Bot")
   • Choose a username for your bot (must end in 'bot', e.g., "my_tedee_lock_bot")
4. BotFather will respond with a message containing your Bot Token
   • It looks like: 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ
   • Save this token - you'll need it for configuration

2. Get Your Chat ID

To find your Chat ID (the ID of the chat where notifications will be sent):

Method 1: Using userinfobot

1. Search for @userinfobot in Telegram
2. Start a chat and send any message
3. The bot will reply with your user information, including your Chat ID
   • It looks like: 123456789

Method 2: Using your bot and the Telegram API

1. Send a message to your newly created bot (any message works)
2. Open this URL in your browser (replace YOUR_BOT_TOKEN with your actual token):

   https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates
   

3. Look for the "chat":{"id": field in the JSON response
   • Example: "chat":{"id":123456789,...}

3. Configure in tedee-scripts

Once you have your Bot Token and Chat ID:

1. Run the setup script: ./setup.sh
2. When prompted for Telegram configuration:
   • Enter your Bot Token when asked
   • Enter your Chat ID when asked
3. The setup will save these credentials to your config file

Alternatively, you can manually add them to config/tedee.conf:

TELEGRAM_TOKEN="123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ"
CHAT_ID="123456789"

4. Test Your Configuration

Test that notifications work:

# The close script will send a Telegram notification if configured
./bin/close

You should receive a notification in your Telegram chat!

Note: Telegram notifications are optional. If not configured, the scripts will work normally without sending notifications.

🔧 Configuration Reference

Configuration is stored in config/tedee.conf (automatically created by ./setup.sh).

Configuration Variables

Variable	Required	Default	Description
BRIDGE_IP	✅ Yes	-	Tedee Bridge IP address
TEDEE_TOKEN	✅ Yes	-	Tedee API token
AUTH_TYPE	✅ Yes	encrypted	Authentication type: encrypted or non-encrypted
DEVICE_ID	✅ Yes	-	Lock device ID
TELEGRAM_TOKEN	❌ No	-	Telegram bot token (for notifications)
CHAT_ID	❌ No	-	Telegram chat ID (for notifications)
MAX_RETRIES	✅ Yes	3	Number of retry attempts
SLEEP_BETWEEN	✅ Yes	5	Seconds between retries
LOCALE	✅ Yes	en	Language for notifications: en or es

Example Configuration

BRIDGE_IP="192.168.1.100"
TEDEE_TOKEN="your-api-token-here"
AUTH_TYPE="encrypted"
DEVICE_ID="289001"
TELEGRAM_TOKEN="123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ"
CHAT_ID="123456789"
MAX_RETRIES=3
SLEEP_BETWEEN=5
LOCALE="en"

🔐 Lock States Reference

Understanding lock states helps with debugging and webhook event handling.

Code	State	Description
0	Uncalibrated	Lock needs calibration
1	Calibration	Lock is calibrating
2	Open	🔓 Door is open/unlocked
3	Partially Open	Partially open
4	Opening	🔄 Currently opening
5	Closing	🔄 Currently closing
6	Closed	🔒 Door is closed/locked
7	Pull Spring	Pull spring mode
8	Pulling	Currently pulling
9	Unknown	Unknown state
255	Unpulling	Currently unpulling

📡 Webhook Events

The callback script handles all event types from the Tedee Bridge API and sends Telegram notifications for lock events.

Note: Webhook setup requires Telegram notifications to be configured. The callback script sends notifications about lock events, so it makes no sense to set up webhooks if you haven't configured Telegram notifications first. See Telegram Notifications section.

Requirements

To receive webhook events from your Tedee Bridge, you need:

1. A server that can receive POST HTTP requests - This can be any server accessible from your local network
2. A webhook handler - A service that receives HTTP requests and executes the callback script
3. Telegram notifications configured - The callback script sends notifications via Telegram

Setup with Docker (Recommended)

The easiest way to set up a webhook server is using TheCatLady/docker-webhook with Docker Compose.

1. Create docker-compose.yml

Create a docker-compose.yml file in your preferred location:

services:
  webhook:
    image: thecatlady/webhook:latest
    container_name: webhook
    command: -verbose -hooks=/config/hooks.yml -hotreload
    restart: unless-stopped
    environment:
      - TZ=Europe/Madrid  # Set your timezone
    ports:
      - "9000:9000"
    volumes:
      - /path/to/webhook/config:/config
      # Mount your tedee-scripts directory
      - /path/to/tedee-scripts:/scripts/tedee

Configuration:

• TZ: Set your timezone (e.g., Europe/Madrid, America/New_York)
• ports: Exposes webhook server on port 9000 (change if needed)
• volumes:
  • Mount a config directory for hooks.yml
  • Mount your tedee-scripts directory to /scripts/tedee

2. Create hooks.yml

Create a hooks.yml file in your webhook config directory:

- id: tedee/callback
  execute-command: /scripts/tedee/bin/callback
  command-working-directory: /scripts/tedee
  pass-arguments-to-command:
    - source: payload
      name: event
    - source: payload
      name: timestamp
    - source: payload
      name: data

This configuration:

• Creates a webhook endpoint at /hooks/tedee/callback
• Executes the callback script when triggered
• Passes event data from the payload to the script

3. Start the Webhook Server

# Start the container
docker compose up -d

# Check the logs to verify it's running
docker compose logs -f webhook

# You should see something like:
# [webhook] 2024/01/08 10:00:00 [webhook] version 2.x.x starting
# [webhook] 2024/01/08 10:00:00 [webhook] serving hooks on http://0.0.0.0:9000/hooks/{id}

Note: On older setups, you may need to use docker-compose instead of docker compose.

Register Callback with Tedee Bridge

Once your webhook server is running, you need to register it with your Tedee Bridge.

1. Access Bridge Swagger UI

The Tedee Bridge provides a Swagger UI for API operations:

http://your-bridge-local-ip

Example: http://192.168.1.100

2. Authenticate

1. Open the Swagger UI in your browser
2. Look for the authentication section
3. Enter your API token (from config/tedee.conf -> TEDEE_TOKEN)

Note: If you have encryption enabled, you may need to temporarily disable it for easier Swagger UI access. After registering the callback, it's recommended to re-enable token encryption for security.

3. Register the Callback

1. Find the POST /callback endpoint in the Swagger UI
2. Click "Try it out"
3. Use this request body:

{
  "url": "http://your-webhook-server-ip:9000/hooks/tedee/callback",
  "method": "POST"
}

Example:

{
  "url": "http://192.168.1.50:9000/hooks/tedee/callback",
  "method": "POST"
}

4. Click "Execute"
5. Verify the response is successful (200 OK)

Important: Make sure to use the correct IP address of the machine running your webhook server, not localhost or 127.0.0.1.

4. Verify Registration

After registering, test that webhooks are working:

1. Perform an action on your lock (open/close via app)
2. Check webhook server logs: docker compose logs -f webhook
3. You should see incoming POST requests
4. Check that you receive Telegram notifications

Supported Events

The callback script handles all event types from the Tedee Bridge API:

• backend-connection-changed - Bridge connection to backend changes (connected/disconnected)
• device-connection-changed - Device connection status to bridge changes (connected/disconnected)
• device-settings-changed - Device settings are modified
• lock-status-changed - Lock state changes (includes lock status, jammed status, and door state)
• device-battery-level-changed - Battery level changes significantly
• device-battery-fully-charged - Battery reaches 100%
• device-battery-start-charging - Device starts charging
• device-battery-stop-charging - Device stops charging

Manual Testing

You can test the callback script manually without webhooks:

# Timestamp format: ISO 8601 (e.g., 2023-07-25T14:41:48.825Z)
./bin/callback "lock-status-changed" "2023-07-25T14:41:48.825Z" '{"deviceId":289001,"state":6}'

This is useful for:

• Testing your Telegram notification setup
• Debugging callback script behavior
• Understanding event data structures

Troubleshooting Webhooks

Webhook not receiving events

Solutions:

1. Verify webhook server is running:

   docker compose ps
   docker compose logs webhook

2. Test webhook endpoint manually:

   curl -X POST http://your-webhook-server-ip:9000/hooks/tedee/callback \
        -H "Content-Type: application/json" \
        -d '{"event":"test","timestamp":"2024-01-08T10:00:00Z","data":"{}"}'

3. Check that callback is registered in Bridge Swagger UI (GET /callback endpoint)

4. Verify network connectivity between Bridge and webhook server:

   # From the machine running the bridge
   ping your-webhook-server-ip

Callback script not executing

Solutions:

1. Check webhook logs for errors:

   docker compose logs -f webhook

2. Verify script permissions inside container:

   docker compose exec webhook ls -la /scripts/tedee/bin/callback

3. Verify tedee-scripts directory is mounted correctly:

   docker compose exec webhook ls -la /scripts/tedee/

4. Test callback script manually from host:

   ./bin/callback "test" "2024-01-08T10:00:00Z" "{}"

No Telegram notifications

Solutions:

1. Verify Telegram is configured in config/tedee.conf:

   grep 'TELEGRAM_TOKEN|CHAT_ID' config/tedee.conf

2. Test Telegram notifications work:

   ./bin/close  # Should send a notification

3. Check callback script has access to config:

   docker compose exec webhook cat /scripts/tedee/config/tedee.conf

Alternative Setup (Without Docker)

If you prefer not to use Docker, you can set up webhooks using:

• webhook binary directly: https://github.com/adnanh/webhook
• nginx + CGI script
• Node.js express server
• Any HTTP server that can execute shell scripts on POST requests

The key requirement is that your server must:

1. Accept POST requests at a specific endpoint
2. Extract event, timestamp, and data from the request payload
3. Execute: /path/to/tedee-scripts/bin/callback "$event" "$timestamp" "$data"

Documentation

For complete event documentation and payload structures, see the official Tedee webhook events documentation.

🐛 Troubleshooting

"Bridge is not responding"

Possible causes:

• Bridge is powered off
• Bridge is not connected to the network
• Wrong IP address in configuration

Solutions:

1. Check if bridge is powered on and connected
2. Verify BRIDGE_IP in config/tedee.conf
3. Test connectivity: ping <BRIDGE_IP>
4. Check your router to confirm the bridge's IP address

"Configuration file not found"

Solution: Run the setup script to create the configuration file:

./setup.sh

Or verify that config/tedee.conf exists in the correct location.

"Permission denied"

Solution: Make scripts executable:

chmod +x bin/*
chmod +x setup.sh

The setup script should do this automatically, but you can run it manually if needed.

Telegram notifications not working

Possible causes:

• Incorrect bot token
• Incorrect chat ID
• Bot hasn't been started (need to send /start to the bot first)

Solutions:

1. Verify TELEGRAM_TOKEN is correct in config/tedee.conf
2. Verify CHAT_ID is correct
3. Send /start to your bot in Telegram
4. Test with a simple curl command:

   curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/sendMessage" \
        -d "chat_id=<YOUR_CHAT_ID>" \
        -d "text=Test message"

Note: Telegram notifications are optional - scripts work fine without them.

Crontab job not running

Possible causes:

• Using relative paths instead of absolute paths
• Scripts not executable
• Environment variables not set in cron context

Solutions:

1. Always use absolute paths in crontab:

   # Good
   0 22 * * * /home/user/tedee-scripts/bin/close
   
   # Bad
   0 22 * * * ~/tedee-scripts/bin/close
   0 22 * * * close

2. Add logging to debug:

   0 22 * * * /path/to/tedee-scripts/bin/close >> /tmp/tedee.log 2>&1

3. Check cron logs:

   # macOS
   log show --predicate 'process == "cron"' --last 1h
   
   # Linux
   grep CRON /var/log/syslog

Lock state not updating

Solution: The close script waits for the lock to reach the closed state. If it times out:

1. Check if the lock is physically working (battery, calibration)
2. Increase retry attempts in config/tedee.conf:

   MAX_RETRIES=5
   SLEEP_BETWEEN=10

3. Check lock state manually via Tedee app

💡 Tips & Best Practices

1. Test Before Automating

Always run scripts manually first to verify behavior before adding to crontab:

./bin/close
# Verify it worked, then add to crontab

2. Backup Your Configuration

Keep a backup of your config/tedee.conf:

cp config/tedee.conf config/tedee.conf.backup

3. Use Logging for Cron Jobs

Always add logging when running from crontab:

0 22 * * * /path/to/tedee-scripts/bin/close >> /tmp/tedee.log 2>&1

This helps with debugging if something goes wrong.

4. Use Absolute Paths

Always use absolute paths in crontab to avoid issues:

# Good
0 22 * * * /home/user/tedee-scripts/bin/close

# Also good (if added to PATH)
0 22 * * * close

5. Telegram is Optional

Don't worry if you don't need notifications - the scripts work perfectly without Telegram.

6. Change Language Anytime

Run ./setup.sh again to switch between English and Spanish notifications.

7. Update Regularly

Keep your scripts up to date:

./bin/update

Or automate it:

# Update weekly on Sunday at 3 AM
0 3 * * 0 /path/to/tedee-scripts/bin/update

8. Monitor Bridge Connectivity

The close script checks bridge connectivity before each operation, but you can also:

# Add this to crontab to get notified if bridge is down
*/30 * * * * ping -c 1 <BRIDGE_IP> || echo "Bridge is down" | mail -s "Tedee Alert" your@email.com

📋 Requirements

• curl - For API requests and downloading updates
• sha256sum - For API token generation (or shasum -a 256 on macOS)
• ping - For bridge connectivity checks
• tar - For extracting updates (usually pre-installed)

All these tools are typically pre-installed on macOS and Linux systems.

🛠️ Development

The project is structured to make it easy to add new scripts.

Project Architecture

• bin/ - Executable scripts that users run directly
• lib/ - Shared library functions (API communication, state checking, notifications)
• locales/ - Internationalization support (en, es)
• config/ - User configuration (generated, not in git)

Adding a New Script

1. Create a new script in bin/:

   touch bin/my-script
   chmod +x bin/my-script

2. Source the common library:

   #!/bin/bash
   SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
   . "$SCRIPT_DIR/../lib/tedee-common.sh"

3. Use shared functions:

   load_config
   get_lock_state "$DEVICE_ID"
   send_telegram_notification "Your message"

4. Test it:

   ./bin/my-script

Shared Functions Available

The lib/tedee-common.sh library provides:

• load_config() - Load and validate configuration
• get_lock_state() - Get current lock state
• wait_for_state() - Wait for lock to reach a specific state
• close_lock() - Close/lock the door
• send_telegram_notification() - Send Telegram message
• generate_api_key() - Generate API authentication key
• check_bridge_connectivity() - Test bridge connection

See lib/tedee-common.sh for complete function list and documentation.

🔗 Useful Links

• Tedee Bridge API Documentation
• Tedee Webhook Events Documentation
• Telegram Bot API
• Crontab Guru - Cron expression generator and explainer

📝 License

See LICENSE file for details.