FreeSleep Notes

A curated subset of my additions to the FreeSleep project - an open-source alternative to Eight Sleep's proprietary software for controlling the Pod 3 sleep system.

Overview

FreeSleep provides temperature control and biometric monitoring for the Eight Sleep Pod 3 without requiring a subscription. This repository contains documentation, scripts, and source code extracted from my main development project to demonstrate the reverse engineering work and implementation approaches.

What's Included

📚 Documentation

• PodOS development guide with cross-compilation and deployment instructions
• Sensor data collection system documentation and setup guides
• Hardware specifications and interface documentation
• Algorithm documentation for sleep stage detection, personalization, and temperature control

🔧 Scripts and Tools

• Data collection scripts for automated sensor file retrieval from Pod
• Build environment with RPM packaging for PodOS deployment
• Monitoring tools for system health and data collection status
• Setup scripts for development environment configuration

💻 Source Code

• Go biometric processor (500Hz signal processing for heart rate/breathing)
• Hardware interfaces for thermal and sensor management
• Signal processing algorithms with Butterworth filters and peak detection
• Calibration tools for parameter tuning and historical data processing

⚙️ Configuration

• Service definitions for systemd integration
• Build specifications for cross-compilation to ARM64
• Processing parameters for biometric signal analysis
• Collection settings for automated data gathering

Key Capabilities

Data Collection ✅

• Automated RAW file collection from Pod filesystem
• Network-resilient transfer with retry mechanisms
• File rotation detection and metadata tracking
• Integration with systemd for service management

Deployment Infrastructure ✅

• Cross-compilation toolchain for ARM64/PodOS
• RPM packaging system with repository hosting
• Service configuration for production deployment
• Build automation with Make and shell scripts

Architecture

Pod Hardware (ARM64/PodOS)           Development Machine (x86_64)
├─ frankenfirmware                   ├─ Data Collection
├─ /persistent/*.RAW files ────────> ├─ Signal Processing (Go)
├─ Temperature control               └─ Build Environment (RPM/Cross-compile)
└─ Sensor monitoring                

Quick Start

Prerequisites

• Linux development machine with Docker (for cross-compilation)
• SSH access to "jailbroken" Eight Sleep Pod 3
• Python 3.10+ and Go 1.19+ installed

Setup Data Collection

# Configure sensor data collection
./bin/setup_collection.sh

# Start automated collection
./bin/collect_sensor_data.sh --daemon

# Monitor collection status  
./bin/monitor_collection.sh

Build Biometric Processor

cd src/biometrics
make build-arm64  # For Pod deployment
make build        # For local testing

Run Web Interface

cd src/freesleep
python main.py    # Starts Flask server on :5000

Project Status

This is a functional proof-of-concept demonstrating:

✅ Working Features

• RAW sensor data collection and parsing
• Heart rate and breathing detection algorithms (but they don't really work!)
• Cross-compilation and deployment to Pod

🚧 Limitations

• No sleep stage classification (algorithm documented but not implemented)
• Limited historical data analysis
• Basic presence detection (needs refinement)
• No mobile app (web interface only)

🔬 Reverse Engineering Achievements

• Decoded CBOR sensor data format (500Hz piezoelectric readings)
• Identified frankenfirmware interface (filesystem-based communication)
• Extracted signal processing requirements (filter specifications)
• Documented Pod hardware architecture (thermal and sensor systems)

File Organization

freesleep-notes/
├── doc/                    # Documentation and guides
│   ├── algorithms/         # Algorithm specifications  
│   ├── PodOS-Development-Guide.md
│   └── sensor_data_collection.md
├── bin/                    # Executable scripts
│   ├── collect_sensor_data.sh
│   └── setup_collection.sh
├── src/                    # Source code
│   ├── biometrics/         # Go signal processing
│   └── calibration/        # Parameter tuning tools
├── config/                 # Configuration files
│   ├── *.service          # Systemd services
│   └── *.yaml             # Processing parameters
└── build-env/              # Cross-compilation environment
    ├── tools/              # Build scripts
    └── rpmbuild/           # RPM packaging

Technical Highlights

Signal Processing

• 500Hz sampling rate for high-fidelity biometric detection
• Butterworth bandpass filters (0.8-3Hz heart rate, 0.1-0.5Hz breathing)
• Adaptive peak detection with outlier rejection
• Multi-channel processing (4 piezoelectric sensors)

System Integration

• Systemd service management for production deployment
• File-based communication with Pod firmware
• Network-resilient collection with automatic retry
• Cross-platform builds (x86_64 development, ARM64 deployment)

Legal Notice

This project is for educational and personal use only. Users are responsible for compliance with applicable laws, terms of service, and hardware warranties. The reverse engineering work documented here was performed on personally-owned hardware for interoperability purposes.

Related Projects

• free-sleep - Original temperature control implementation
• Eight Sleep API - Community API documentation

---

For detailed information about specific components, see the complete file index.