Ring Doorbell Monitor

A Go command-line application that monitors Ring doorbell events (doorbell presses and motion detection) and executes custom actions.

Features

• Authenticate with Ring API (supports 2FA)
• Token caching for persistent authentication
• Real-time monitoring of doorbell events
• Detects both doorbell presses and motion events
• Extensible callback system for custom actions
• Beautiful console output

Prerequisites

• Go 1.16 or higher
• A Ring account with at least one Ring device
• Your Ring email and password

Installation

1. Clone or download this repository
2. Navigate to the project directory
3. Install dependencies:

go mod download

Usage

Running the Monitor

Simply run the application:

go run main.go

On first run, you'll be prompted to enter:

• Your Ring account email
• Your Ring account password
• 2FA code (if enabled on your account)

The authentication token will be cached in .ring_token_cache.json for future use.

Building the Application

To build a standalone executable:

go build -o ring-monitor

Then run it:

./ring-monitor

How It Works

1. Authentication: The app authenticates with the Ring API using your credentials
2. Token Caching: Your authentication token is saved locally to avoid re-authentication
3. Device Discovery: Lists all your Ring devices
4. Event Monitoring: Polls the Ring API every 5 seconds for active events
5. Event Handling: When a doorbell press or motion is detected, it triggers callbacks

Debugging with Proxies

To inspect API traffic with tools like Proxyman, Charles, or mitmproxy, set these environment variables:

export HTTPS_PROXY=http://localhost:9090
export RING_SKIP_TLS_VERIFY=true
go run main.go

This will route all HTTPS traffic through your proxy and disable TLS verification to allow interception.

Output when proxy is enabled:

🔍 Using HTTPS proxy: http://localhost:9090
⚠️  WARNING: TLS certificate verification is DISABLED (RING_SKIP_TLS_VERIFY=true)

See DEBUGGING.md for detailed setup instructions for Proxyman and other proxy tools.

⚠️ Security Warning: Only use RING_SKIP_TLS_VERIFY=true for local debugging, never in production!

Customization

Adding Custom Actions

You can add custom actions when events are detected by modifying the callback in main.go:

listener.AddCallback(func(ding ring.Ding) {
    if ding.Kind == "ding" {
        // Custom action for doorbell press
        log.Println("Someone pressed the doorbell!")
        // Execute your custom command here
        // Examples:
        // - Send a notification
        // - Turn on lights
        // - Start recording
        // - Play a sound
    } else if ding.Kind == "motion" {
        // Custom action for motion detection
        log.Println("Motion detected!")
    }
})

Adjusting Poll Interval

Change the polling interval in main.go:

// Poll every 5 seconds (default)
listener := ring.NewEventListener(client, 5*time.Second)

// Poll every 2 seconds (more responsive but more API calls)
listener := ring.NewEventListener(client, 2*time.Second)

Event Information

When an event is detected, you have access to:

• ding.Kind - Event type: "ding" (doorbell) or "motion"
• ding.DoorbotID - ID of the device that triggered the event
• ding.DeviceKind - Type of device (e.g., "doorbell_v3")
• ding.CreatedAt - Timestamp of the event
• ding.State - Current state of the event
• ding.Snapshot - URL to snapshot image (if available)

Project Structure

.
├── main.go              # Main application entry point
├── ring/
│   ├── client.go        # Ring API client implementation
│   └── listener.go      # Event listener and polling logic
├── go.mod               # Go module dependencies
└── README.md            # This file

Security Notes

• Your authentication token is stored in .ring_token_cache.json with 0600 permissions
• Never share your token cache file
• Add .ring_token_cache.json to .gitignore if using version control

Limitations

• Ring does not provide an official API, so this implementation is based on reverse engineering
• The API may change without notice
• Polling interval affects responsiveness vs. API load
• Some Ring features may not be supported

Example Output

Ring Doorbell Monitor
=====================

Found cached authentication token
Authentication successful!

Fetching Ring devices...

Found 1 device(s):
1. Front Door (ID: 12345678, Type: doorbell_v3)

✓ Monitoring Ring doorbell events...
Press Ctrl+C to stop

🔔 Ring Event Detected!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Event Type:  Doorbell Press
Device ID:   12345678
Device Kind: doorbell_v3
Time:        2025-12-26 15:30:45
State:       ringing
Snapshot:    https://...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Troubleshooting

Authentication Failed

• Verify your Ring email and password are correct
• If you have 2FA enabled, make sure to enter the code when prompted
• Try deleting .ring_token_cache.json and re-authenticating

No Events Detected

• Make sure your Ring device is online and working
• Test by pressing the doorbell manually
• Check that your Ring account has access to the device
• Increase polling frequency for faster detection

API Errors

• Ring's unofficial API may change - check for updates
• Your token may have expired - delete the cache and re-authenticate

Credits

Based on the Ring integration from Home Assistant:

• https://github.com/home-assistant/core/tree/dev/homeassistant/components/ring
• https://github.com/python-ring-doorbell/python-ring-doorbell

License

This project is for educational purposes. Ring and the Ring logo are trademarks of Ring LLC.