From 21c35504bde0fa1b725f17bdf2379e8993e81879 Mon Sep 17 00:00:00 2001 From: Cole Nicholas Date: Thu, 27 Nov 2025 20:35:20 -0600 Subject: [PATCH] Update documentation with complete production configuration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CLAUDE.md updates: - Add current production configuration details (API tokens, ICS URL, device IDs) - Document repository setup with git.cybertek.systems as primary repo - Add Docker deployment commands and troubleshooting section - Include project status, setup history, and key implementation notes - Document door device vs door group implementation decision PROJECT.md updates: - Add complete production configuration with all credentials and URLs - Update current status with detailed setup achievements - Document API token resolution and testing progression - Add repository configuration and deployment details - Include key setup milestones and hardware testing status 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- CLAUDE.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- PROJECT.md | 35 ++++++++++++++++++++------ 2 files changed, 97 insertions(+), 10 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 9e809f0..8ba011d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,24 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Project Overview -This is a Python automation tool that integrates UniFi Access with Airbnb/Hostex reservations, automatically creating and managing visitor access for Airbnb guests. The system fetches reservations from either Hostex API or Airbnb ICS feed, creates UniFi Access visitor accounts with PIN codes based on phone numbers, and provides cross-verification between multiple booking systems. +This is a Python automation tool that integrates UniFi Access with Airbnb reservations, automatically creating and managing visitor access for Airbnb guests. The system fetches reservations from Airbnb ICS calendar feed, creates UniFi Access visitor accounts with PIN codes based on phone numbers, and provides comprehensive logging and monitoring. + +## Current Production Configuration + +### UniFi Access Settings +- **Controller IP**: `10.0.1.20:12445` +- **API Token**: `bNILUGf8zWZE6PVv926xAA` (Access API key with full visitor management permissions) +- **Target Door Device**: `847848a02017` (configured for individual door access, not door groups) + +### Airbnb Integration +- **ICS Calendar URL**: `https://www.airbnb.com/calendar/ical/1554481759780111413.ics?s=19f2a0faa64e47fd28a9879954c9a5c2` +- **Check-in Time**: `16:00:00` (4:00 PM) +- **Check-out Time**: `11:00:00` (11:00 AM) +- **PIN Code Digits**: `4` (uses last 4 digits of guest phone number) + +### Repository Setup +- **Primary Repository**: `https://git.cybertek.systems/cnicholas/unifi-access-airbnb.git` +- **Original Source**: `https://github.com/keithah/unifi-access-airbnb.git` (upstream reference) ## Core Commands @@ -15,9 +32,16 @@ This is a Python automation tool that integrates UniFi Access with Airbnb/Hostex - **Specify custom log file**: `python3 main.py -l custom.log` - **List available door groups**: `python3 main.py --list-door-groups` +### Docker Deployment (Recommended) +- **Build and run continuously**: `docker-compose up -d` +- **Run once manually**: `docker-compose --profile manual up unifi-access-airbnb-once` +- **View logs**: `docker-compose logs -f` +- **Stop container**: `docker-compose down` + ### Configuration Setup - **Setup configuration**: `cp unifi.conf.example unifi.conf` then edit with actual credentials - **Configuration file**: `unifi.conf` (contains API tokens, URLs, and settings) +- **Logs directory**: `logs/` (persistent storage for container deployments) ## Architecture Overview @@ -104,4 +128,48 @@ The `unifi.conf` file contains these key sections: ### Testing and Verification - Use `--list-door-groups` to verify UniFi Access connectivity and available door groups - Run with `-v` flag to see detailed operation logs -- Check log files for historical operation data and error analysis \ No newline at end of file +- Check log files for historical operation data and error analysis + +## Project Status and Setup History + +### Successfully Completed Setup +- ✅ UniFi Access API connection verified (10.0.1.20:12445) +- ✅ API token configured with proper Access permissions (not Console permissions) +- ✅ Individual door device configuration implemented (847848a02017) +- ✅ Airbnb ICS calendar integration working +- ✅ Docker containerization completed with multi-architecture support +- ✅ Raspberry Pi compatibility verified +- ✅ Repository migrated to git.cybertek.systems + +### Key Implementation Notes +- **Door Groups vs Individual Doors**: This implementation uses individual door devices (`"type": "door"`) rather than door groups (`"type": "door_group"`) due to UniFi Access UI configuration +- **API Token Type**: Must use UniFi Access API token (not Console API token) for visitor management permissions +- **Multi-day Stays**: System creates single visitor account spanning entire stay duration (check-in to check-out) +- **PIN Code Strategy**: Uses last 4 digits of guest phone number from Airbnb booking data + +### Testing Status +- **Ready for hardware testing**: Awaiting UniFi reader installation +- **Configuration validated**: All API connections and calendar parsing working +- **Docker deployment tested**: Container builds and runs successfully + +### Future Development +- **UniFi Protect Integration**: Planned expansion for automated recording based on guest stays +- **Required Hardware**: UniFi Gateway Max or Cloud Key Gen2+ with Protect license +- **Features**: Guest check-in/out recording, incident documentation, privacy controls + +## Troubleshooting Common Issues + +### API Connection Problems +- Verify controller IP address and port (12445 for UniFi Access) +- Ensure API token is from UniFi Access settings (not Console) +- Check network connectivity to UniFi controller + +### Door Group/Device Issues +- Use individual door device IDs instead of door groups for this implementation +- Verify device ID in UniFi Access dashboard +- Check that device has proper permissions configured + +### Calendar Integration Issues +- Verify Airbnb ICS URL is current and accessible +- Check that calendar contains guest phone numbers for PIN generation +- Monitor verbose logs for parsing errors \ No newline at end of file diff --git a/PROJECT.md b/PROJECT.md index e9e4415..69e646a 100644 --- a/PROJECT.md +++ b/PROJECT.md @@ -71,23 +71,32 @@ docker-compose up -d docker-compose logs -f ``` -## 📦 Current Configuration +## 📦 Production Configuration ### UniFi Access Setup - **Controller**: `10.0.1.20:12445` +- **API Token**: `bNILUGf8zWZE6PVv926xAA` (Access API key with full permissions) - **Target Device**: `847848a02017` (Front door reader) +- **Device Type**: Individual door device (not door group) - **API Access**: Full visitor management permissions ### Airbnb Integration -- **Calendar Source**: Airbnb ICS feed -- **Check-in Time**: 4:00 PM -- **Check-out Time**: 11:00 AM +- **Calendar URL**: `https://www.airbnb.com/calendar/ical/1554481759780111413.ics?s=19f2a0faa64e47fd28a9879954c9a5c2` +- **Check-in Time**: `16:00:00` (4:00 PM) +- **Check-out Time**: `11:00:00` (11:00 AM) - **PIN Generation**: Last 4 digits of guest phone number +- **PIN Length**: 4 digits + +### Repository Configuration +- **Production Repository**: `https://git.cybertek.systems/cnicholas/unifi-access-airbnb.git` +- **Upstream Source**: `https://github.com/keithah/unifi-access-airbnb.git` +- **Log Storage**: `logs/unifi_access_airbnb.log` ### Automation Schedule -- **Frequency**: Every 6 hours +- **Frequency**: Every 6 hours (configurable in docker-compose.yml) - **Processing Window**: Next 30 days of bookings - **Cleanup**: Automatic removal of expired visitors +- **Deployment**: Docker containerized with persistent logging ## 🏁 Current Status @@ -102,9 +111,19 @@ docker-compose logs -f - [x] Multi-day stay handling ### 🔄 **Ready for Testing** -- Awaiting UniFi reader hardware installation -- Configuration validated and tested -- Docker deployment verified +- **Hardware Status**: Awaiting new UniFi reader installation +- **API Testing**: UniFi Access connection verified (401 → 200 response progression) +- **Configuration**: Complete production config validated +- **Docker Deployment**: Multi-architecture container tested and working +- **Calendar Integration**: Airbnb ICS parsing successful +- **Repository**: Migrated to git.cybertek.systems with all customizations + +### 🛠 **Key Setup Achievements** +- **API Token Resolution**: Switched from Console API to Access API for proper permissions +- **Door Configuration**: Implemented individual door device support vs door groups +- **Calendar Testing**: Successfully connected and parsed Airbnb booking data +- **Cleanup Testing**: Verified automatic removal of test visitor accounts +- **Multi-day Support**: Confirmed seamless handling of extended guest stays ## 🔮 Future Roadmap