rvt-monitor 0.4.0

BLE Device Monitor for Ceily/Wally

RVT-Monitor

BLE Device Monitor and Control Tool for Ceily/Wally devices.

Installation

pip install rvt-monitor

Or install from source:

cd rvt-monitor
pip install -e .

Usage

rvt-monitor

Opens web UI at http://127.0.0.1:8000

BLE Protocol Reference

Device Information Service (0x180A)

Standard BLE SIG service for device identification.

Characteristic	UUID	Format	Example
Model Number	0x2A24	{device}-p{protocol}	ceily-p2, wally-p2
Hardware Revision	0x2A27	v{version}	v0, v1
Firmware Revision	0x2A26	semver	2.0.0

Custom Services

Service	UUID	Description
Control	0000ff20-...	Motion control
System Status	501a8cf5-98a7-4370-bb97-632c84910000	Device state
Dimension	cc9762a6-bbb7-4b21-b2e2-153059030000	Device config
LED	07ecc81b-b952-47e6-a1f1-0999577f0000	LED control
Log	cc9762a6-bbb7-4b21-b2e2-153059032200	Event logs

Motion Commands

Write to MOTION_CONTROL characteristic (0x0000ff21-...):

Command	Value	Ceily	Wally
STOP	0x00	Stop	Stop
UP/OPEN	0x01	Up	Open
DOWN/CLOSE	0x02	Down	Close

Motion States

Read from SYSTEM_STATUS characteristic (byte 0):

State	Value	Description
DOWN/CLOSED	0	At bottom/closed position
UP/OPENED	1	At top/opened position
MOVING_DOWN	2	Moving down/closing
MOVING_UP	3	Moving up/opening
STOP	4	Stopped mid-motion
EMERGENCY	5	Emergency stop
INIT	255	Initializing

Protocol Version Detection

By Device Info Service

from bleak import BleakClient

MODEL_NUMBER_UUID = "00002a24-0000-1000-8000-00805f9b34fb"

async def detect_protocol(client: BleakClient) -> int:
    """Detect protocol version from Model Number."""
    try:
        data = await client.read_gatt_char(MODEL_NUMBER_UUID)
        model = data.decode("utf-8").rstrip("\x00")
        # Format: "ceily-p2" or "wally-p2"
        if "-p" in model:
            return int(model.split("-p")[1])
    except Exception:
        pass
    return 1  # Legacy fallback

By Service Discovery

DEVICE_INFO_SERVICE = "0000180a-0000-1000-8000-00805f9b34fb"

async def detect_by_services(client: BleakClient) -> int:
    """Detect by checking for Device Info Service."""
    for service in client.services:
        if service.uuid.lower() == DEVICE_INFO_SERVICE:
            return 2
    return 1  # Legacy (no Device Info Service)

Example: Connect and Control

from bleak import BleakClient

MOTION_CONTROL_UUID = "0000ff21-0000-1000-8000-00805f9b34fb"
SYSTEM_STATUS_UUID = "501a8cf5-98a7-4370-bb97-632c84910001"

async def control_device(address: str):
    async with BleakClient(address) as client:
        # Read status
        data = await client.read_gatt_char(SYSTEM_STATUS_UUID)
        state = data[0]
        print(f"Current state: {state}")

        # Send UP command
        await client.write_gatt_char(MOTION_CONTROL_UUID, bytes([0x01]))

Project Structure

rvt-monitor/
├── rvt_monitor/
│   ├── ble/
│   │   ├── manager.py     # BLE connection management
│   │   ├── profiles.py    # Protocol version profiles
│   │   ├── protocol.py    # UUID definitions & parsers
│   │   └── scanner.py     # Device discovery
│   ├── server/
│   │   ├── app.py         # FastAPI server
│   │   └── routes/        # API endpoints
│   └── static/            # Web UI
└── pyproject.toml

Publishing to PyPI

Via Git Tag (Recommended)

# Update version in pyproject.toml first
git add pyproject.toml
git commit -m "chore(rvt-monitor): Bump version to x.y.z"

# Create and push tag
git tag rvt-monitor-vX.Y.Z
git push origin main --tags

CI/CD will automatically build and publish to PyPI.

Manual Trigger

1. Go to GitHub → Actions
2. Select "Publish rvt-monitor to PyPI"
3. Click "Run workflow"

Related

• Firmware: v1/common_components/ - Device-side BLE implementation
• OTA Tool: ota/ota.py - Firmware deployment