INKBIRD ISC-027BW Reverse Engineering & Docker Monitor

A complete reverse engineering project and web dashboard for the INKBIRD ISC-027BW BBQ smoker temperature controller. This project provides 24/7 monitoring without needing to keep the official app running.

🎯 Project Goals

• Continuous Monitoring: 24/7 temperature monitoring without phone dependency
• Web Dashboard: Real-time web interface with device control
• Docker Deployment: Easy deployment on Unraid/NAS systems
• Protocol Documentation: Complete reverse engineering of Tuya IoT protocol
• Open Source Alternative: Replace unreliable official app functionality

📊 Current Status

Feature	Status	Notes
Device Communication	✅ Working	Tuya protocol v3.4
Fan Control (DPS 120)	✅ Working	On/off toggle
Alarm Monitoring (DPS 108)	✅ Working	14 alarm types decoded
Docker Container	✅ Working	Ready for Unraid deployment
Web Dashboard	✅ Working	Real-time updates, responsive UI
Temperature Monitoring	🔄 In Progress	Requires device in monitoring mode
Target Temperature Setting	🔄 In Progress	Needs protocol discovery
Meat Probe Monitoring	🔄 In Progress	Awaiting DPS 101 activation

🔧 Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  INKBIRD Device │◄──►│ Docker Container │◄──►│  Web Dashboard  │
│   ISC-027BW     │    │                  │    │ (Port 8086)     │
│                 │    │ • Python Flask   │    │                 │
│ • Tuya Protocol │    │ • tinytuya       │    │ • Real-time UI  │
│ • WiFi Connected│    │ • SQLite Logging │    │ • Device Control│
│ • 4 Temp Probes │    │ • Background     │    │ • Alarm Display │
└─────────────────┘    │   Data Collection│    └─────────────────┘
                       └──────────────────┘

🚀 Quick Start

Prerequisites

• Docker and Docker Compose
• INKBIRD ISC-027BW device on same network
• Device credentials (IP, Device ID, Local Key)

Deployment

1. Clone Repository

   git clone https://github.com/your-username/inkbird-reverse-engineering.git
   cd inkbird-reverse-engineering

2. Configure Device Settings

   # Edit docker-compose.yml with your device details
   nano docker-compose.yml

3. Deploy Container

   docker-compose up -d

4. Access Dashboard

   http://your-server-ip:8086
   

🔍 Reverse Engineering Process

This project documents the complete reverse engineering journey:

Phase 1: APK Analysis ✅

• Extracted INKBIRD Android APK using JADX
• Found Tuya credentials in AndroidManifest.xml
• Discovered device uses standard Tuya IoT protocol

Phase 2: Network Protocol Analysis ✅

• Captured network traffic during app usage
• Identified Tuya protocol version 3.4
• Extracted device credentials via ADB logcat

Phase 3: Device Communication ✅

• Established direct device communication
• Mapped Data Point Specifications (DPS):
  • DPS 108: Alarm status bitmap (14 alarm types)
  • DPS 120: Fan control (boolean on/off)
  • DPS 101: Temperature data (awaiting activation)
  • DPS 107: Configuration/settings

Phase 4: Protocol Implementation ✅

• Built Python communication layer using tinytuya
• Created Flask web application
• Implemented real-time monitoring and control

📋 Device Specifications

INKBIRD ISC-027BW

• 4 Temperature sensors (1 dome + 3 meat probes)
• WiFi connectivity (2.4GHz)
• Tuya IoT protocol v3.4
• Fan control for temperature regulation
• 14 different alarm conditions

🐳 Docker Configuration

Environment Variables

Variable	Default	Description
INKBIRD_IP	192.168.1.170	Device IP address
DEVICE_ID	ebe68bf20a45e83945l5q6	Tuya device ID
LOCAL_KEY	MiPEx}<M:Zj@8<X!	Tuya encryption key
PROTOCOL_VERSION	3.4	Tuya protocol version
DATA_LOG_INTERVAL	60	Data collection interval (seconds)

Volume Mounts

• /app/data - Persistent SQLite database storage

🌡️ Finding Your Device Credentials

If you need to find your own device credentials, use one of these methods:

Method 1: ADB Logcat (Recommended)

1. Enable Developer Options on Android device
2. Connect via USB and enable USB debugging
3. Run: adb logcat | grep -i tuya while connecting INKBIRD app
4. Look for device_id and local_key in logs

Method 2: APK Analysis

1. Download INKBIRD APK from device or APK mirror
2. Decompile with JADX: jadx inkbird.apk
3. Search for credentials in AndroidManifest.xml

Method 3: Network Analysis

1. Use Wireshark to capture traffic during app connection
2. Look for UDP packets to device IP
3. Extract credentials from packet data

📊 Data Point Specifications (DPS)

DPS	Type	Description	Status
101	String	Temperature readings (dome + 3 probes)	🔄 Awaiting activation
107	String	Device settings/configuration	✅ Partially mapped
108	Integer	Alarm status bitmap (14 types)	✅ Fully decoded
120	Boolean	Fan control on/off	✅ Working

Alarm Bitmap Decoding (DPS 108)

Bit 0-3:  High Temperature Alarms (Dome, Probe1, Probe2, Probe3)
Bit 4-7:  Low Temperature Alarms (Dome, Probe1, Probe2, Probe3)  
Bit 8-11: Probe Lost Alarms (Dome, Probe1, Probe2, Probe3)
Bit 12:   Internal High Temperature
Bit 13:   Grill Open Detection

🛠️ Development Setup

Local Development

# Create virtual environment
python -m venv inkbird-env
source inkbird-env/bin/activate  # Linux/Mac
# or
inkbird-env\Scripts\activate     # Windows

# Install dependencies  
pip install -r requirements.txt

# Run development server
python docker_app.py

Testing Device Communication

# Test basic connectivity
python test_correct_device.py

# Safe monitoring (read-only)
python safe_monitoring_only.py

# Protocol analysis
python probe_activation_test.py

🔧 Troubleshooting

Device Not Responding

• Verify device IP address is correct
• Check network connectivity: ping DEVICE_IP
• Ensure device is on same network as Docker container

App Crashes When Accessing Device

• Device may be in corrupted state
• Try factory reset (hold button + power cycle)
• Contact INKBIRD support for firmware recovery

No Temperature Data (DPS 101)

• Device needs to be in active monitoring mode
• Use official app to start monitoring session
• Connect all temperature probes
• Ensure probes are functional

📁 Project Structure

inkbird-reverse-engineering/
├── README.md                     # This file
├── docker-compose.yml            # Docker deployment config
├── Dockerfile                    # Container build instructions  
├── requirements.txt              # Python dependencies
├── docker_app.py                 # Main Flask application
├── safe_monitoring_only.py       # Read-only device monitoring
├── test_correct_device.py        # Basic connectivity test
├── probe_activation_test.py      # Temperature activation testing
├── network_device_scanner.py     # Network analysis tools
├── docs/                         # Additional documentation
│   ├── REVERSE_ENGINEERING.md    # Detailed RE process
│   ├── PROTOCOL_ANALYSIS.md      # Tuya protocol documentation
│   └── TROUBLESHOOTING.md        # Common issues and solutions
└── scripts/                      # Utility scripts
    ├── capture_working_protocols.py
    ├── temperature_troubleshooting.py
    └── usb_firmware_analysis.py

🤝 Contributing

Contributions are welcome! This project needs:

• Temperature Protocol Discovery: Help activate DPS 101 temperature monitoring
• Target Temperature Setting: Reverse engineer temperature target commands
• UI Improvements: Enhance web dashboard functionality
• Documentation: Improve setup and troubleshooting guides
• Device Testing: Test with other INKBIRD models

Development Guidelines

1. Always test with safe_monitoring_only.py first
2. Never send experimental commands to working devices
3. Document any new DPS discoveries
4. Follow existing code style and structure

⚠️ Disclaimer

This project is for educational and personal use only.

• Warranty: Using this software may void your device warranty
• Risk: Reverse engineering IoT devices carries risk of device corruption
• Legal: Ensure compliance with local laws regarding reverse engineering
• Support: This is not affiliated with or supported by INKBIRD

Use at your own risk. Always maintain backups and working official app access.

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• tinytuya library for Tuya device communication
• JADX for APK decompilation
• Flask for web framework
• INKBIRD for creating hackable IoT devices
• Tuya for (somewhat) open IoT protocol

📞 Support

• Issues: Use GitHub Issues for bug reports and feature requests
• Discussions: Use GitHub Discussions for questions and help
• Wiki: Check the Wiki for additional documentation

---

⚠️ Important: This project currently provides device control and monitoring framework. Temperature monitoring (DPS 101) requires device to be in active monitoring mode via official app or protocol discovery.

🎯 Goal: Build a complete replacement for the INKBIRD app with reliable 24/7 monitoring capabilities.