Content
# 🚲 Engwe N1 Air — BLE Reverse Engineering + Claude MCP Server
> Reverse engineered the Engwe N1 Air e-bike's Bluetooth protocol and built a Claude AI integration to control it from your Mac.
## What This Does
- 🚀 **Unlock speed limit** via Bluetooth (up to 40 km/h)
- 🔒 **Lock/unlock** the bike remotely via IoT API
- 🔊 **Find your bike** (sound + light alarm)
- 🔋 **Battery, mileage, cadence** real-time stats
- 📍 **Geo-fence** management
- 💪 **PAS level** control via Bluetooth
- 🤖 **Claude AI integration** — control your bike by talking to Claude
- 🖥️ **Mac menubar app** — one-click access to all features
---
## How It Was Built
### Step 1 — API Discovery (Charles Proxy)
Captured network traffic from the Engwe iOS app using Charles Proxy. Found the main API endpoint at `app-api.engweapp.com` with JWT authentication.
### Step 2 — APK Decompile (JADX)
Decompiled the Android APK using JADX to find all internal API endpoints and BLE command codes.
```bash
jadx -d engwe-source ENGWE_2.7.2_APKPure.xapk
grep -r "iot/device" engwe-source --include="*.java" | grep -o '"[^"]*iot/device[^"]*"' | sort -u
```
### Step 3 — BLE Protocol Reverse Engineering
Found the complete BLE protocol in `ProtocolUtil.java` and `BLEBikeCommand.java`.
**V2 Protocol Format:**
```
456E + CMD(4) + LEN(4) + DATA + CRC16(4) + 7765
```
**BLE UUIDs (from BluetoothRegulate.java):**
```
Service: 00001820-0000-1000-8000-00805f9b34fb
Write: 00001822-0000-1000-8000-00805f9b34fb
Notify: 00001821-0000-1000-8000-00805f9b34fb
```
---
## BLE Command Reference
All commands use V2 protocol format: `456E + CMD + LEN + DATA + CRC16 + 7765`
| Command | Hex | Description |
|---------|-----|-------------|
| Speed Limit | `2A65` | 0x00=0, 0x10=10, 0x20=20, 0x30=30, 0x40=40 km/h |
| PAS Level | `010A` | 0x00–0x05 |
| Motor Current Limit | `2A66` | Under investigation |
| Cruise Control Set | `0128` | Under investigation |
| Wheel Diameter | `08C3` | Under investigation |
| Factory Reset | `8049` | ⚠️ Irreversible |
| Lock State | `0108` | Query lock |
| Power On/Off | `0107` | 01=on, 02=off |
| Auto Shutdown Time | `1000` | Minutes |
**Speed Limit Example (40 km/h):**
```python
# Index 4 * 16 = 0x40
command = "456E2A650001406A237765"
```
**CRC16 Calculation (ModBus):**
```python
def crc16(hex_str):
data = bytes.fromhex(hex_str)
crc = 0xFFFF
for byte in data:
crc ^= byte
for _ in range(8):
crc = (crc >> 1) ^ 0xA001 if crc & 1 else crc >> 1
return format(crc, "04X")
# CRC input = CMD + LEN + DATA
# Example: crc16("2A65" + "0001" + "40") = "6A23"
```
---
## IoT API Endpoints
Base URL: `https://app-api.engweapp.com`
| Endpoint | Description |
|----------|-------------|
| `/api/app/iot/device/lockSwitch` | Lock/unlock bike |
| `/api/app/iot/device/findVehicle` | Sound + light alarm |
| `/api/app/iot/device/vibrationAlarmSwitch` | Vibration alarm + signal |
| `/api/app/iot/device/fenceSwitch` | Geo-fence on/off |
| `/api/app/iot/device/getFenceList` | List geo-fences |
| `/api/app/iot/device/bleSenselessSwitch` | BLE auto-unlock |
| `/api/app/iot/device/headlightSwitch` | Headlight + realtime PAS/charge |
| `/api/app/iot/device/attr/newest` | Battery SOC/SOH, mileage, cadence |
| `/api/app/iot/device/version` | IoT/BT/4G firmware versions |
| `/api/app/iot/device/attr/newest` | Real-time attributes |
| `/api/app/paypal/syDetail` | IoT subscription info |
| `/api/app/ride-data/index` | Weekly ride statistics |
---
## Installation
### Requirements
- Node.js 18+
- Python 3.9+
- Mac (for menubar app)
```bash
git clone https://github.com/SafaAslan/engwe-n1air-mcp
cd engwe-n1air-mcp
npm install
pip3 install bleak
```
### Get Your Token
Use Charles Proxy to capture traffic from the Engwe iOS/Android app. Find the `Authorization` header in any request to `app-api.engweapp.com`.
### Configure Claude Desktop
`~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"engwe-n1air": {
"command": "node",
"args": ["/path/to/engwe-n1air-mcp/index.js"],
"env": {
"ENGWE_IMEI": "YOUR_IMEI",
"ENGWE_BLE_MAC": "YOUR_BLE_MAC",
"ENGWE_TOKEN": "YOUR_JWT_TOKEN"
}
}
}
}
```
### Find Your IMEI & BLE MAC
```bash
# IMEI — visible in Engwe app under bike settings
# BLE MAC — run while bike is on:
python3 -c "
import asyncio
from bleak import BleakScanner
async def scan():
devices = await BleakScanner.discover(timeout=10)
for d in devices:
if d.name and 'ENGWE' in d.name.upper():
print(d.address, d.name)
asyncio.run(scan())
"
```
---
## Usage
### Claude AI (via MCP)
Once configured, just talk to Claude:
- *"Lock my bike"*
- *"What's my battery level?"*
- *"Set speed limit to 35 km/h"*
- *"Show my ride stats for this week"*
### Menubar App (Mac)
```bash
npm install electron
./node_modules/.bin/electron tray.js
```
### Auto-start on Boot
```bash
chmod +x setup_autostart.sh
bash setup_autostart.sh
```
### Speed Limit Script (standalone)
```bash
python3 ble_speed3.py
```
---
## Project Structure
```
engwe-n1air-mcp/
├── index.js # Claude MCP server (18 tools)
├── tray.js # Mac menubar app
├── ble_speed3.py # Standalone speed limit script
├── ble_scan2.py # BLE device scanner
├── setup_autostart.sh # Mac autostart setup
└── README.md
```
---
## ⚠️ Disclaimer
Unlocking the speed limit above 25 km/h is **illegal on public roads in the EU**. This project is for educational and off-road/private use only. Use at your own risk. This project is not affiliated with Engwe.
---
## Contributing
Pull requests welcome! Especially interested in:
- Testing on other Engwe models (P275 SE, M20, etc.)
- Cruise control command (`0128`)
- Motor current limit (`2A66`)
- Android version of menubar app
---
## License
MIT
