wes
718a13c02f
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
224 lines
7.8 KiB
Markdown
224 lines
7.8 KiB
Markdown
# Lippert OneControl - Bluetooth Protocol Reverse Engineering
|
|
|
|
[](https://opensource.org/licenses/Apache-2.0)
|
|
[](https://github.com)
|
|
|
|
**Status**: ✅ **PROTOCOL FULLY REVERSED** - Ready for Testing
|
|
|
|
Reverse engineered Bluetooth protocol for Lippert OneControl RV control systems to enable Home Assistant integration.
|
|
|
|
## 🎉 Mission Accomplished
|
|
|
|
All 431 .NET assemblies successfully extracted and decompiled to C# source code. Complete protocol specification documented and working Python implementation created.
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
python -m venv venv
|
|
source venv/bin/activate
|
|
pip install bleak
|
|
```
|
|
|
|
### Scan for OneControl Device
|
|
|
|
```bash
|
|
python src/onecontrol_client.py
|
|
```
|
|
|
|
Edit the `ADDRESS` variable in `src/onecontrol_client.py` with your device's MAC address after scanning.
|
|
|
|
## 🔑 Protocol Details
|
|
|
|
### Bluetooth UUIDs (Confirmed from Source)
|
|
- **Service UUID**: `00000030-0200-A58E-E411-AFE28044E62C`
|
|
- **Write Characteristic**: `00000033-0200-A58E-E411-AFE28044E62C`
|
|
- **Read Characteristic**: `00000034-0200-A58E-E411-AFE28044E62C`
|
|
|
|
### Encoding
|
|
- **Protocol**: COBS (Consistent Overhead Byte Stuffing) with 6-bit packing
|
|
- **Checksum**: CRC8 (polynomial 0x07, init value 0x55)
|
|
- **Sequence**: 16-bit little-endian counter
|
|
|
|
### Packet Structure (Unencoded)
|
|
|
|
```
|
|
[Sequence (2 bytes, LE)] [Command Type (1)] [Table ID (1)] [Payload...] [CRC8 (1)]
|
|
```
|
|
|
|
Then COBS encoded before transmission.
|
|
|
|
### Command Types
|
|
|
|
| Command | Value | Description |
|
|
|---------|-------|-------------|
|
|
| GetDevices | `0x01` | Discover all RV devices |
|
|
| ActionSwitch | `0x40` | Lights, pumps, fans (on/off) |
|
|
| ActionMovement | `0x41` | Awnings, slides (extend/retract/stop) |
|
|
| ActionDimmable | `0x43` | Dimmable lights (0-100%) |
|
|
| ActionRgb | `0x44` | RGB lights |
|
|
| ActionHvac | `0x45` | Climate control |
|
|
|
|
## 📁 Project Structure
|
|
|
|
```
|
|
lippert-onecontrol/
|
|
├── src/ # Python implementation
|
|
│ ├── cobs_protocol.py # COBS encoder/decoder and CRC8
|
|
│ └── onecontrol_client.py # Complete BLE client
|
|
├── docs/ # Documentation
|
|
│ ├── PROTOCOL_FINDINGS.md
|
|
│ ├── IMPLEMENTATION_GUIDE.md
|
|
│ ├── HOME_ASSISTANT_INTEGRATION.md
|
|
│ └── MISSION_ACCOMPLISHED.md
|
|
├── scripts/ # Extraction tools (reference)
|
|
├── README.md
|
|
├── LICENSE
|
|
└── .gitignore
|
|
```
|
|
|
|
## 💻 Usage Example
|
|
|
|
```python
|
|
from src.onecontrol_client import OneControlClient
|
|
|
|
# Connect to device
|
|
client = OneControlClient("AA:BB:CC:DD:EE:FF")
|
|
await client.connect()
|
|
|
|
# Discover all RV devices
|
|
await client.get_devices()
|
|
|
|
# Control lights
|
|
await client.turn_on_light(5) # Turn on device ID 5
|
|
await client.turn_off_light(5) # Turn off device ID 5
|
|
|
|
# Control awning/slide
|
|
await client.control_awning(8, 1) # Extend (device ID 8)
|
|
await client.control_awning(8, 0) # Retract
|
|
await client.control_awning(8, 2) # Stop
|
|
|
|
# Dimmable light
|
|
await client.set_dimmer(3, 75) # Set device ID 3 to 75%
|
|
|
|
# Disconnect
|
|
await client.disconnect()
|
|
```
|
|
|
|
## 🔧 How It Was Done
|
|
|
|
1. **Extracted Lippert Connect APK** (v6.2.2) - Xamarin app
|
|
2. **Extracted 431 .NET assemblies** from 85MB XABA v2.2 blob using ilspycmd
|
|
3. **Decompiled to C# source** - Full protocol implementation visible
|
|
4. **Found BLE UUIDs** in `DirectConnectionMyRvLinkBle.cs`
|
|
5. **Reverse engineered COBS encoding** from `CobsEncoder.cs`
|
|
6. **Implemented CRC8** from `Crc8.cs`
|
|
7. **Created Python client** - Ready to test!
|
|
|
|
## 🎯 Next Steps
|
|
|
|
### When RV is Available (April 2025)
|
|
- [ ] Test Python client with actual RV
|
|
- [ ] Run `get_devices()` to discover device IDs
|
|
- [ ] Map device IDs to physical components
|
|
- [ ] Test all command types (lights, awnings, pumps, etc.)
|
|
- [ ] Document device ID mapping for your specific RV
|
|
|
|
### Home Assistant Integration
|
|
- [ ] Build custom component using Python client
|
|
- [ ] Implement entity types (light, switch, cover, sensor)
|
|
- [ ] Add configuration flow
|
|
- [ ] Set up ESPHome Bluetooth Proxy for range extension
|
|
- [ ] Test end-to-end
|
|
- [ ] Publish to HACS
|
|
|
|
## 📚 Documentation
|
|
|
|
### In This Repository
|
|
- [Protocol Findings](docs/PROTOCOL_FINDINGS.md) - Technical protocol specification
|
|
- [Implementation Guide](docs/IMPLEMENTATION_GUIDE.md) - Complete guide with code examples
|
|
- [Home Assistant Integration](docs/HOME_ASSISTANT_INTEGRATION.md) - HA integration plan
|
|
- [Mission Accomplished](docs/MISSION_ACCOMPLISHED.md) - Project summary
|
|
|
|
### Online Documentation
|
|
> 📖 **Coming Soon**: Full documentation will be published at a public URL (Quartz site)
|
|
>
|
|
> For now, see the [docs/](docs/) folder in this repository.
|
|
|
|
## 🛠️ Development Tools Used
|
|
|
|
- **Dexamarin** - Xamarin APK decompiler
|
|
- **ilspycmd** - .NET to C# decompiler
|
|
- **Bleak** - Python BLE library
|
|
- **ILSpy** - .NET assembly browser
|
|
|
|
## ⚡ RV Systems Supported
|
|
|
|
Based on decompiled source code:
|
|
- ✅ Lights (on/off, dimmable, RGB)
|
|
- ✅ Water pumps
|
|
- ✅ Awnings (extend/retract/stop)
|
|
- ✅ Slide-outs (extend/retract/stop)
|
|
- ✅ Water tank sensors (fresh, grey, black)
|
|
- ✅ HVAC/Climate control
|
|
- ✅ Generator controls
|
|
|
|
## 📞 Resources
|
|
|
|
- **Lippert Support**: service@lci1.com / +1 432-LIPPERT
|
|
- **Home Assistant Dev**: https://developers.home-assistant.io/
|
|
- **ESPHome**: https://esphome.io/components/bluetooth_proxy.html
|
|
- **Bleak Docs**: https://bleak.readthedocs.io/
|
|
|
|
## 🙏 Acknowledgments
|
|
|
|
- **Dexamarin**: https://github.com/alexisflive/Dexamarin
|
|
- **ILSpy**: https://github.com/icsharpcode/ILSpy
|
|
|
|
## ⚖️ Legal Notice & Disclaimer
|
|
|
|
### Purpose
|
|
This project is created for **educational and interoperability purposes only**. It enables owners of legally purchased Lippert OneControl hardware to integrate their RV systems with open-source home automation platforms (such as Home Assistant).
|
|
|
|
### Interoperability Defense
|
|
This work is protected under interoperability provisions of applicable copyright law, including:
|
|
- **DMCA Section 1201(f)** (United States) - Reverse engineering for interoperability
|
|
- **EU Software Directive Article 6** - Decompilation for interoperability
|
|
- **Legal Use of Owned Hardware** - Users have the right to interface with their legally purchased devices
|
|
|
|
### License
|
|
This project is licensed under the **Apache License 2.0** - see the [LICENSE](LICENSE) file for details.
|
|
|
|
The Apache 2.0 license includes a patent grant clause, providing additional protection to users and contributors.
|
|
|
|
### What This Project Contains
|
|
- ✅ **Original Python implementation** of the protocol (written by contributors)
|
|
- ✅ **Documentation** of publicly observable BLE communication
|
|
- ✅ **No proprietary code** - all implementations are clean-room
|
|
- ✅ **No binary files** from the original application
|
|
|
|
### What This Project Does NOT Contain
|
|
- ❌ Decompiled proprietary source code
|
|
- ❌ Original APK or binary files
|
|
- ❌ Copyrighted assets or resources
|
|
- ❌ Circumvention of copy protection or DRM
|
|
|
|
### Disclaimer
|
|
**This project is not affiliated with, endorsed by, or supported by Lippert Components Inc.**
|
|
|
|
This software is provided "AS IS" without warranty of any kind. Users assume all risks associated with using this software. The authors are not responsible for any damage to hardware, software, or data.
|
|
|
|
### Responsible Use
|
|
- This tool is intended for use with hardware you own
|
|
- Respect the intellectual property rights of Lippert Components Inc.
|
|
- Do not use this project to circumvent security measures
|
|
- Follow all applicable local laws and regulations
|
|
|
|
### For Lippert Components Inc.
|
|
If you have concerns about this project, please open an issue or contact the repository owner. We are committed to respecting intellectual property rights while enabling legitimate interoperability use cases.
|
|
|
|
---
|
|
|
|
**Current Status**: 🟢 Protocol fully reversed | 🟡 Awaiting RV access for testing (April 2025) | 🔵 Ready for HA integration development
|