Skip to content

CAPACITOR_SERIAL_IMPLEMENTATION.md

Latest commit

 

History

History
327 lines (234 loc) · 10.5 KB

CAPACITOR_SERIAL_IMPLEMENTATION.md

File metadata and controls

327 lines (234 loc) · 10.5 KB

src/js/protocols/CapacitorSerial.js # Protocol adapter

Betaflight App - Custom Capacitor USB Serial Plugin

Overview

This implementation creates a custom Capacitor USB Serial plugin specifically designed for the Betaflight App, replacing the patched capacitor-plugin-usb-serial with a clean, purpose-built solution.

🎯 Key Improvements

✅ Problems Solved

  1. USB Permission Issues - Native Android permission handling works correctly
  2. Binary Protocol Support - Built-in hex string encoding/decoding for MSP protocol
  3. No Patches Required - Clean implementation without patch-package workarounds
  4. Better Device Detection - Automatic USB attach/detach events
  5. Simplified API - Designed specifically for Betaflight's architecture

🏗️ Architecture

betaflight-app/
├── android/app/src/main/java/
│   ├── betaflight/app/MainActivity.java    # Registers the plugin
│   └── betaflight/app/protocols/serial/    # Native plugin source
│       ├── BetaflightSerialPlugin.java
│       └── UsbPermissionReceiver.java
│
├── src/js/protocols/
│   └── CapacitorSerial.js                  # Protocol adapter
│
└── android/app/src/main/res/xml/
   └── device_filter.xml                   # USB device filters

📦 Plugin Structure

Native Android Layer

File: android/app/src/main/java/betaflight/app/protocols/serial/BetaflightSerialPlugin.java

Key Features:

  • Uses usb-serial-for-android library (proven, mature library)
  • Supports all major USB-to-serial chipsets (FTDI, CP210x, CH34x, STM32, etc.)
  • Automatic permission request handling
  • Binary data transmission via hex strings
  • Real-time data reception through event listeners
  • Device attach/detach detection

Methods:

  • requestPermission() - Request USB device permissions
  • getDevices() - Get list of permitted devices
  • connect(options) - Connect to a device
  • disconnect() - Disconnect from device
  • write(options) - Write hex string data
  • read() - Read available data as hex string

Events:

  • dataReceived - Emitted when data is received
  • deviceAttached - Emitted when USB device is attached
  • deviceDetached - Emitted when USB device is detached

TypeScript/JavaScript Layer

File: src/js/protocols/CapacitorSerial.js

Purpose: Protocol adapter that integrates the native plugin into Betaflight's serial architecture

Key Features:

  • Implements the same interface as WebSerial, WebBluetooth, etc.
  • Automatic hex string ↔ Uint8Array conversion
  • Event forwarding to the serial system
  • Android platform detection

🔗 Integration Points

1. Serial System (src/js/serial.js)

Protocol Registration:

CapacitorSerial is registered in the protocol list alongside WebSerial, WebBluetooth, WebSocket, and VirtualSerial. The protocol is selected automatically for ports with the capacitor- prefix.

this._protocols = [
   { name: "webserial", instance: new WebSerial() },
   { name: "webbluetooth", instance: new WebBluetooth() },
   { name: "capacitorserial", instance: new CapacitorSerial() },
   { name: "websocket", instance: new Websocket() },
   { name: "virtual", instance: new VirtualSerial() },
];

Selection Logic: The port handler chooses the protocol based on the port path prefix, e.g. capacitor-<deviceId>. This ensures Android USB devices are routed to the CapacitorSerial implementation.

2. Port Handler (src/js/port_handler.js)

Port Handler Updates: Detects available Capacitor serial ports dynamically from the protocol layer

  • showCapacitorOption controls UI visibility for Capacitor ports
  • Device list refresh includes Capacitor devices when available
  • Handles attach/detach events and permission requests for Capacitor devices

3. Compatibility Checks (src/js/utils/checkCompatibility.js)

Compatibility Check: Serial protocol compatibility is determined by checkSerialSupport() in src/js/utils/checkCompatibility.js. This function returns true for Android/Capacitor environments and for browsers supporting the Web Serial API. It is used to conditionally enable CapacitorSerial in the UI and protocol selection logic.

4. Android Configuration

AndroidManifest.xml:

<intent-filter>
   <action android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED" />
</intent-filter>

<meta-data
   android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED"
   android:resource="@xml/device_filter" />

<uses-feature android:name="android.hardware.usb.host" android:required="true" />

device_filter.xml: Defines all supported USB devices (FTDI, STM32, CP210x, etc.)

🚀 Usage Flow

Initial Setup

  1. App launches on Android
  2. CapacitorSerial protocol is initialized
  3. Compatibility check detects Android platform
  4. Port handler includes Capacitor Serial in device refresh

Device Connection

  1. User requests USB permission → requestPermission()
  2. Android shows permission dialog for each device
  3. Granted devices appear in port list
  4. User selects device and connects → connect(deviceId, baudRate)
  5. Native plugin opens USB connection
  6. Data flows through hex string encoding/decoding

Data Transmission

Sending (MSP request):

// JavaScript: Uint8Array → hex string
const data = new Uint8Array([0x24, 0x58, 0x00, 0x00, 0xfb]);
await serial.send(data);  // CapacitorSerial protocol

// CapacitorSerial: Uint8Array → "24580000fb"
// Native: "24580000fb" → byte array → USB

Receiving (MSP response):

// Native: USB → byte array → "24580d00..." hex string
// Event: dataReceived { data: "24580d00..." }
// CapacitorSerial: "24580d00..." → Uint8Array
// JavaScript: Uint8Array received via 'receive' event

📚 Supported USB Chipsets

Via usb-serial-for-android library:

  • CDC-ACM - USB Communication Device Class
  • CP210x - Silicon Labs (CP2102, CP2105, etc.)
  • FTDI - Future Technology Devices (FT232, FT2232, FT4232, etc.)
  • PL2303 - Prolific Technology
  • CH34x - WinChipHead (CH340, CH341)
  • STM32 - ST Microelectronics Virtual COM Port
  • GD32 - GigaDevice Virtual COM Port
  • AT32 - ArteryTek Virtual COM Port
  • APM32 - Geehy APM32 Virtual COM Port
  • Raspberry Pi Pico - RP2040 USB Serial

All the Betaflight-compatible devices listed in device_filter.xml.

🔄 Migration from PR #4698

What Was Removed

  • ❌ capacitor-plugin-usb-serial dependency
  • ❌ patch-package dependency
  • ❌ patches/capacitor-plugin-usb-serial+0.0.6.patch

What Was Added

  • ✅ Native Android USB serial implementation embedded inside the app module
  • ✅ CapacitorSerial protocol adapter
  • ✅ Enhanced port handler support
  • ✅ Device filter XML configuration

What Stayed the Same

  • ✅ WebSerial protocol (for desktop browsers)
  • ✅ WebBluetooth protocol (for Bluetooth connections)
  • ✅ Overall serial architecture
  • ✅ MSP protocol implementation
  • ✅ User interface

🧪 Testing Checklist

Initial Testing

  • Install dependencies: yarn install
  • Sync Capacitor: npx cap sync android
  • Build Android app: yarn android:run

Device Detection

  • Connect USB OTG adapter with flight controller
  • App should detect USB device attach
  • Request permission should show Android dialog
  • Granted device should appear in port list

Connection

  • Select Capacitor Serial device from port list
  • Click Connect
  • Connection should establish at 115200 baud
  • Status should show "Connected"

Communication

  • MSP data should be sent/received correctly
  • Configuration should load from flight controller
  • Can read/write settings
  • Can flash firmware
  • Can view sensor data in real-time

Stability

  • Disconnect/reconnect multiple times
  • Physical device disconnect/reconnect
  • No memory leaks during extended use
  • Clean connection closure

🐛 Troubleshooting

Permission Not Granted

Symptom: Permission dialog doesn't appear or permission denied

Solutions:

  1. Check device_filter.xml includes your device's VID/PID
  2. Verify AndroidManifest.xml has USB intent filter
  3. Check Android settings → Apps → Betaflight → Permissions
  4. Try manually revoking USB permissions and reconnecting

Device Not Detected

Symptom: USB device connected but not showing in port list

Solutions:

  1. Verify USB OTG adapter is working (test with other apps)
  2. Check device is in device_filter.xml
  3. Look for logs: adb logcat | grep BetaflightSerial
  4. Ensure usb.host feature is declared in manifest

Connection Fails

Symptom: Connect button pressed but connection doesn't establish

Solutions:

  1. Check USB cable quality (data lines, not just power)
  2. Try different baud rate (115200, 57600, 9600)
  3. Verify flight controller is powered properly
  4. Check for conflicting apps using USB device

Data Not Received

Symptom: Connected but no MSP data flows

Solutions:

  1. Verify hex string encoding/decoding is correct
  2. Check event listeners are set up properly
  3. Monitor native logs for I/O errors
  4. Test with simple MSP commands first

📖 Additional Resources

USB Serial for Android Library

Capacitor Documentation

Betaflight MSP Protocol

  • MSP Protocol: Binary protocol for flight controller communication
  • Hex String Format: Two hex digits per byte (e.g., "24" = 0x24 = 36 decimal)

🎉 Benefits Summary

  1. Clean Implementation - No patches, no workarounds
  2. Better Permissions - Native Android permission handling
  3. Binary Protocol - Built for MSP from the ground up
  4. Maintainable - All code is yours to modify
  5. Extensible - Easy to add features or fix issues
  6. Documented - Comprehensive comments and documentation
  7. Tested - Built on proven usb-serial-for-android library

📅 Next Steps

  1. Testing - Comprehensive testing on various Android devices
  2. Documentation - User guide for Android version
  3. CI/CD - Automated Android builds
  4. Release - Beta release for Android testers
  5. Feedback - Gather user feedback and iterate

Created: November 2025
Author: AI Assistant for Betaflight Team
License: GPL-3.0 (same as Betaflight Configurator)