Reorganize repository structure into logical folders

Structure: - src/ - Python implementation (cobs_protocol.py, onecontrol_client.py) - docs/ - All documentation markdown files - scripts/ - Extraction scripts (for reference only) Changes: - Moved Python files to src/ - Moved all .md docs to docs/ - Moved extraction scripts to scripts/ - Updated README.md with new structure - Updated import paths in README examples - Added placeholder for future Quartz documentation URL Benefits: - Cleaner repository organization - Easier to navigate - Separates code from documentation - Follows standard project conventions
2025-12-29 09:33:20 -05:00
parent c62fbf1bd4
commit 718a13c02f
11 changed files with 29 additions and 19 deletions
@@ -0,0 +1,230 @@
+# Lippert OneControl Reverse Engineering - Summary
+
+## Mission Accomplished ✓
+
+We successfully reverse engineered the Lippert OneControl Bluetooth protocol.
+**MAJOR SUCCESS**: We extracted the assemblies, decompiled the code, and fully documented the protocol structure!
+
+## What We Discovered
+
+### 1. Bluetooth Protocol Details (CONFIRMED)
+- **Service UUID**: `00000030-0200-A58E-E411-AFE28044E62C`
+- **Write Char**: `00000033-0200-A58E-E411-AFE28044E62C`
+- **Encoding**: **COBS** (Consistent Overhead Byte Stuffing) + **CRC8**
+
+### 2. Extracted Assemblies
+We successfully cracked the XABA v2.2 compression format and extracted 431 assemblies.
+We decompiled the key libraries using `ilspycmd` and found the source code for:
+- `OneControl.Direct.IdsCanAccessoryBle.dll` - Sensor logic
+- `OneControl.Direct.MyRvLinkBle.dll` - **Main Connection Logic**
+- `OneControl.Direct.MyRvLink.dll` - **Command Structures**
+- `IDS.Portable.Common.dll` - **COBS & CRC8 Algorithms**
+
+### 3. Protocol Commands
+We identified the exact packet structure for controlling devices:
+- `ActionSwitch` (0x40): Controls lights, pumps, etc.
+- `ActionMovement` (0x41): Controls awnings, slides.
+- `GetDevices` (0x01): Lists available devices.
+
+## Challenges Encountered
+
+### Modern Xamarin Format
+The app uses XABA v2.2 format which we successfully reversed using a custom Python script.
+
+### Solution Accomplished
+- ✓ Cracked XABA v2.2 format
+- ✓ Extracted all DLLs
+- ✓ Decompiled DLLs to C# source code
+- ✓ Analyzed C# code to find UUIDs and Command structures
+
+## Recommended Next Steps
+
+### Build the Integration (Now)
+
+You have all the technical details needed to build the Python library and Home Assistant integration.
+See `HOME_ASSISTANT_INTEGRATION.md` for the updated implementation plan with confirmed UUIDs and encoding logic.
+
+### Verify with RV (April)
+1. Connect using the confirmed UUIDs.
+2. Send `GetDevices` to map your RV's specific Device IDs.
+3. Enjoy controlling your RV from Home Assistant!
+- **Awnings** - Extend/Retract commands
+- **Lights** - On/Off control (possibly dimming)
+- **Water Pumps** - On/Off control
+- **Tank Sensors** - Water level monitoring
+- **Slide-outs** - Extend/Retract
+- **Heating** - Temperature control
+
+### 3. Command Architecture
+The protocol uses relay-based commands:
+- `RelayBasicSwitch` - Simple on/off relays
+- `RelayBasicLatching` - Latching relays (toggle states)
+- `RelayMomentary` - Momentary/pulse relays (like a doorbell)
+
+### 4. App Architecture
+- **Platform**: Xamarin .NET (C# code compiled to Android)
+- **Assembly Format**: XABA v2.2 (434 .NET DLLs in compressed format)
+- **Key DLLs**:
+  - `OneControl.Direct.IdsCanAccessoryBle.dll` - BLE accessory protocol
+  - `OneControl.Direct.MyRvLinkBle.dll` - MyRV Link BLE protocol
+  - `OneControl.dll` - Core device library
+  - `Plugin.BLE.dll` - BLE communication library
+
+## Challenges Encountered
+
+### Modern Xamarin Format
+The app uses XABA v2.2 format which:
+- Stores assemblies in a compressed blob inside an ELF shared object
+- Uses LZ4 compression for individual assemblies
+- Requires special extraction tools
+- Current tools (Dexamarin, pyxamstore v1.0) don't fully support this format
+
+### Solution Accomplished
+- ✓ Identified `XALZ` magic header for compressed blocks
+- ✓ Reversed the block structure (Header + Uncompressed Prefix + LZ4 Stream)
+- ✓ Created `extract_xaba_v2_new.py` to extract all 431 assemblies
+- ✓ Manually identified key DLLs by content analysis
+
+## Recommended Next Steps
+
+### Option 1: Decompile the Extracted DLLs (NOW)
+
+**You now have the DLLs!**
+1. Download the `extracted_assemblies_complete` folder.
+2. Open `OneControl.Direct.IdsCanAccessoryBle.dll` in **ILSpy** or **dnSpy**.
+3. Look for:
+   - `BleAccessoryManager` or similar classes
+   - `BuildCommand` methods
+   - `GattCharacteristic` GUIDs
+   - Protocol definition structs
+
+### Option 2: BLE Sniffing (April)
+
+### Option 3: Contact Lippert
+
+They might have official documentation:
+- **Email**: service@lci1.com
+- **Phone**: +1 432-LIPPERT
+- **Ask for**: Developer API documentation for OneControl BLE protocol
+
+## Files & Tools We Created
+
+### Documentation
+- `PROTOCOL_FINDINGS.md` - Technical findings
+- `HOME_ASSISTANT_INTEGRATION.md` - Complete HA integration plan
+- `ANALYSIS_GUIDE.md` - Assembly analysis guide
+- `SUMMARY.md` - This file
+
+### Scripts & Tools
+- `extract_xaba_v2_new.py` - **The WORKING extractor for XABA v2.2**
+- `next_steps.sh` - Next steps guide
+- `try_ilspy.sh` - ILSpy helper
+
+### Extracted Data
+- `extracted_assemblies_complete/` - **ALL 431 extracted .NET DLLs**
+  - `OneControl.Direct.IdsCanAccessoryBle.dll`
+  - `OneControl.Direct.MyRvLinkBle.dll`
+  - `Plugin.BLE.dll`
+- `payload.bin` - Raw XABA assembly archive
+- `decompiled/sources/` - Decompiled Java wrappers
+
+### Development Environment
+- `venv/` - Python virtual environment with:
+  - pyxamstore (XABA parser)
+  - lz4 (decompression)
+  - termcolor (output formatting)
+
+## Home Assistant Integration - Ready to Build
+
+Once you have the protocol (from BLE sniffing in April), implementation is straightforward:
+
+### 1. Python Library (1-2 days)
+```python
+# lippert_onecontrol/client.py
+import bleak
+
+class OneControlClient:
+    SERVICE_UUID = "c4570b0f-2eeb-428b-b55c-8fa225621e86"
+    # Add characteristic UUIDs from sniffing
+
+    async def control_light(self, device_id, state):
+        packet = build_packet(device_id, state)  # From sniffing
+        await self.client.write_gatt_char(CHAR_UUID, packet)
+```
+
+### 2. Home Assistant Integration (2-3 days)
+- Light entities for RV lights
+- Switch entities for pumps
+- Cover entities for awnings/slides
+- Sensor entities for tank levels
+- Climate entity for heating
+
+See `HOME_ASSISTANT_INTEGRATION.md` for complete code templates.
+
+## Success Metrics
+
+What we achieved **without physical access**:
+- ✅ Identified BLE service UUID
+- ✅ Mapped all controllable RV systems
+- ✅ Understood app architecture
+- ✅ Located protocol implementation DLLs
+- ✅ Created extraction tools and scripts
+- ✅ Designed complete HA integration plan
+
+What remains (requires camper or advanced tools):
+- ⏳ Extract exact command byte structures
+- ⏳ Identify GATT characteristic UUIDs
+- ⏳ Document device ID mapping
+
+## Timeline Estimate
+
+**Path A: BLE Sniffing (April)**
+- Protocol capture: 30 minutes
+- Protocol documentation: 1-2 hours
+- Python library: 1-2 days
+- HA integration: 2-3 days
+- Testing: 1-2 days
+- **Total: ~1 week**
+
+**Path B: Assembly Extraction (Now)**
+- Tool updates/workarounds: 1-3 days
+- Assembly analysis: 2-4 days
+- Protocol documentation: 1-2 days
+- (Then same as Path A for implementation)
+- **Total: ~2 weeks**
+
+## Recommendation
+
+**Wait until April and use BLE sniffing.** It's:
+- 10x faster than assembly reverse engineering
+- 100% accurate (real protocol, not decompiled approximation)
+- Easier to debug issues
+- Provides exact byte sequences immediately
+
+In the meantime:
+- Review `HOME_ASSISTANT_INTEGRATION.md`
+- Set up Home Assistant development environment
+- Learn about `bleak` Python library
+- Study BLE GATT protocol basics
+
+## Quick Start for April
+
+```bash
+# 1. Install nRF Connect on phone
+# 2. Enable Bluetooth HCI logging on Android
+# 3. Use app, pull logs
+# 4. Analyze with Wireshark
+# 5. Come back to this project with the protocol documented
+# 6. Build HA integration using our templates
+```
+
+You're in great shape! All the groundwork is done. When you have camper access, you'll be able to complete this quickly.
+
+## Resources
+
+- **BLE Tutorial**: https://learn.adafruit.com/introduction-to-bluetooth-low-energy/gatt
+- **Wireshark BLE**: https://wiki.wireshark.org/Bluetooth
+- **HA Dev Docs**: https://developers.home-assistant.io/
+- **Bleak Library**: https://bleak.readthedocs.io/
+
+Good luck! Feel free to reach out if you need help in April! 🚐