lippert-onecontrol/docs/ANALYSIS_GUIDE.md

# 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.