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
This commit is contained in:
@@ -0,0 +1,214 @@
|
||||
# Lippert OneControl - Analysis Guide
|
||||
|
||||
## What We've Accomplished
|
||||
|
||||
We successfully:
|
||||
1. ✅ Extracted the XAPK file
|
||||
2. ✅ Decompiled the Android APK
|
||||
3. ✅ Identified the Xamarin .NET assembly blob format (XABA v2.2)
|
||||
4. ✅ Located 434 .NET assemblies in the payload
|
||||
5. ✅ Identified key BLE service UUID
|
||||
6. ✅ Mapped RV control systems
|
||||
|
||||
## Key Findings
|
||||
|
||||
### Bluetooth Protocol
|
||||
- **Service UUID**: `c4570b0f-2eeb-428b-b55c-8fa225621e86`
|
||||
- **Library Used**: Plugin.BLE (Xamarin Bluetooth plugin)
|
||||
- **Protocol Type**: BLE GATT (Read/Write/Notify characteristics)
|
||||
|
||||
### RV Systems Controlled
|
||||
- Awnings (extend/retract)
|
||||
- Lights (on/off, possibly dimming)
|
||||
- Water Pumps
|
||||
- Water Tank Sensors
|
||||
- Slide-outs
|
||||
- Heating Systems
|
||||
|
||||
### Command Types
|
||||
From code analysis, the system uses:
|
||||
- `RelayBasicSwitch` - Simple on/off relays
|
||||
- `RelayBasicLatching` - Latching relays
|
||||
- `RelayMomentary` - Momentary/pulse relays
|
||||
- Message-based protocol with device IDs
|
||||
|
||||
### Key Assemblies to Analyze
|
||||
|
||||
The protocol implementation is in these DLLs:
|
||||
1. **OneControl.Direct.IdsCanAccessoryBle.dll** - BLE protocol for IDS CAN accessories
|
||||
2. **OneControl.Direct.MyRvLinkBle.dll** - MyRV Link BLE protocol
|
||||
3. **OneControl.dll** - Core OneControl library with device definitions
|
||||
4. **Plugin.BLE.dll** - BLE communication library
|
||||
5. **IDS.Portable.CAN.dll** - CAN bus protocol (if using CAN gateway)
|
||||
|
||||
## Next Steps - Manual Analysis with ILSpy
|
||||
|
||||
Since the Xamarin assemblies are in a complex format, here's how to analyze them manually:
|
||||
|
||||
### Option 1: Use Android Studio APK Analyzer
|
||||
```bash
|
||||
# Install Android Studio, then:
|
||||
# File > Profile or Debug APK
|
||||
# Select: extracted/com.lci1.lippertconnect.apk
|
||||
# Navigate to lib/armeabi-v7a/libassemblies.armeabi-v7a.blob.so
|
||||
# Android Studio can sometimes extract these automatically
|
||||
```
|
||||
|
||||
### Option 2: Use Online .NET Decompiler
|
||||
1. Go to: https://www.decompiler.com/
|
||||
2. Upload `arch_apk/lib/armeabi-v7a/libassemblies.armeabi-v7a.blob.so`
|
||||
3. Let it extract and decompile the assemblies
|
||||
4. Download the decompiled source code
|
||||
|
||||
### Option 3: Use `pyaxmlparser` and manual extraction
|
||||
```bash
|
||||
pip3 install --user pyaxmlparser
|
||||
# Then write a custom Python script to parse XABA format
|
||||
```
|
||||
|
||||
### Option 4: Recommended - BLE Sniffing When You Get Access
|
||||
|
||||
When you have access to your camper in April, this is the FASTEST way:
|
||||
|
||||
1. **Using nRF Connect App** (Easiest):
|
||||
- Install nRF Connect on your phone
|
||||
- Scan for your OneControl device
|
||||
- Connect and explore services/characteristics
|
||||
- Try writing values and observe what happens
|
||||
- Document the commands
|
||||
|
||||
2. **Using Android HCI Snoop** (Most detailed):
|
||||
```bash
|
||||
# On your Android phone:
|
||||
# Settings > Developer Options > Enable Bluetooth HCI Snoop Log
|
||||
# Use the Lippert Connect app to control your RV
|
||||
# Control each system (lights, awnings, pumps, etc.)
|
||||
|
||||
# Pull the log:
|
||||
adb pull /data/misc/bluetooth/logs/btsnoop_hci.log
|
||||
|
||||
# Analyze with Wireshark:
|
||||
wireshark btsnoop_hci.log
|
||||
# Filter by: bluetooth.uuid == 0xc4570b0f
|
||||
```
|
||||
|
||||
## What to Look For in ILSpy/Decompiled Code
|
||||
|
||||
When you get the assemblies decompiled, search for:
|
||||
|
||||
### 1. Characteristic UUIDs
|
||||
```csharp
|
||||
// Look for GUID/UUID definitions
|
||||
public static Guid ServiceUuid = new Guid("c4570b0f-2eeb-428b-b55c-8fa225621e86");
|
||||
public static Guid CharacteristicUuid = new Guid(...);
|
||||
```
|
||||
|
||||
### 2. Command Building
|
||||
```csharp
|
||||
// Look for methods like:
|
||||
byte[] BuildCommand(DeviceType type, CommandType cmd, params)
|
||||
byte[] BuildRelayCommand(int deviceId, bool state)
|
||||
```
|
||||
|
||||
### 3. Device IDs/Addressing
|
||||
```csharp
|
||||
// How devices are identified:
|
||||
enum DeviceType { Light = 0x01, Awning = 0x02, ... }
|
||||
class Device {
|
||||
int Id;
|
||||
DeviceType Type;
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Message Format
|
||||
```csharp
|
||||
// Packet structure:
|
||||
[StartByte][Length][Command][DeviceID][Data...][Checksum]
|
||||
```
|
||||
|
||||
## Protocol Reverse Engineering Worksheet
|
||||
|
||||
When analyzing, fill this out:
|
||||
|
||||
### Message Structure
|
||||
```
|
||||
Byte 0: [?] # Start byte or length?
|
||||
Byte 1: [?] # Command type?
|
||||
Byte 2: [?] # Device ID?
|
||||
Byte 3-N: [?] # Data
|
||||
Byte N+1: [?] # Checksum/CRC?
|
||||
```
|
||||
|
||||
### Known Commands (to discover)
|
||||
```
|
||||
Light On: [??][??][??]...
|
||||
Light Off: [??][??][??]...
|
||||
Awning Extend: [??][??][??]...
|
||||
Awning Retract: [??][??][??]...
|
||||
```
|
||||
|
||||
### Device IDs (to discover)
|
||||
```
|
||||
Living Room Light: 0x??
|
||||
Kitchen Light: 0x??
|
||||
Awning: 0x??
|
||||
Water Pump: 0x??
|
||||
```
|
||||
|
||||
## Building the Home Assistant Integration
|
||||
|
||||
Once you have the protocol documented, creating the HA integration will be straightforward:
|
||||
|
||||
### 1. Create Python Library
|
||||
```python
|
||||
# lippert_onecontrol/client.py
|
||||
import bleak
|
||||
|
||||
class OneControlClient:
|
||||
SERVICE_UUID = "c4570b0f-2eeb-428b-b55c-8fa225621e86"
|
||||
CHAR_WRITE_UUID = "???" # From analysis
|
||||
CHAR_READ_UUID = "???" # From analysis
|
||||
|
||||
async def send_command(self, device_id, command):
|
||||
# Build packet based on protocol
|
||||
packet = self._build_packet(device_id, command)
|
||||
await self.client.write_gatt_char(self.CHAR_WRITE_UUID, packet)
|
||||
```
|
||||
|
||||
### 2. Home Assistant Custom Component
|
||||
Follow the structure in `HOME_ASSISTANT_INTEGRATION.md`
|
||||
|
||||
## Resources
|
||||
|
||||
- **ILSpy GUI**: Run `avaloniailspy` to open the GUI decompiler
|
||||
- **Bluetooth Spec**: https://www.bluetooth.com/specifications/specs/
|
||||
- **BLE GATT**: https://learn.adafruit.com/introduction-to-bluetooth-low-energy/gatt
|
||||
- **Home Assistant Dev**: https://developers.home-assistant.io/
|
||||
|
||||
## Timeline
|
||||
|
||||
- **Now - April**: Analyze assemblies, understand protocol from code
|
||||
- **April (with camper access)**: Verify protocol with BLE sniffing
|
||||
- **After verification**: Build Python library
|
||||
- **Final**: Create Home Assistant integration
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Files in this Project
|
||||
```
|
||||
PROTOCOL_FINDINGS.md - Initial reverse engineering findings
|
||||
HOME_ASSISTANT_INTEGRATION.md - HA integration plan
|
||||
ANALYSIS_GUIDE.md - This file
|
||||
next_steps.sh - Automated next steps script
|
||||
payload.bin - Extracted XABA assembly blob
|
||||
extracted_assemblies/ - Extracted DLL files (partial)
|
||||
decoded_apk/ - Decompiled Android resources
|
||||
decompiled/sources/ - Decompiled Java code
|
||||
```
|
||||
|
||||
### Important Contact Info
|
||||
- **Lippert Support**: service@lci1.com
|
||||
- **Phone**: +1 432-LIPPERT
|
||||
- **Potential API docs**: Ask Lippert for developer documentation
|
||||
|
||||
Good luck! Feel free to ask questions when you need help with the analysis.
|
||||
Reference in New Issue
Block a user