218 lines
9.2 KiB
Markdown
218 lines
9.2 KiB
Markdown
# Codebase Structure
|
|
|
|
**Analysis Date:** 2026-04-16
|
|
|
|
## Directory Layout
|
|
|
|
```
|
|
ch34/ # Flutter plugin root
|
|
├── lib/ # Dart source code
|
|
│ ├── ch34.dart # Main library entry point (exports)
|
|
│ ├── ch34_platform_interface.dart # Backward compat: re-exports src/
|
|
│ ├── ch34_method_channel.dart # Backward compat: re-exports src/
|
|
│ └── src/ # Core implementation
|
|
│ ├── ch34_manager.dart # Public static API facade
|
|
│ ├── ch34_platform_interface.dart # Abstract platform interface
|
|
│ ├── ch34_method_channel.dart # MethodChannel implementation
|
|
│ └── types/
|
|
│ └── ch34_types.dart # All data types and enums
|
|
├── android/ # Android native code
|
|
│ ├── build.gradle # Android library build config
|
|
│ ├── settings.gradle # Gradle settings
|
|
│ ├── libs/ # Native dependency JARs
|
|
│ │ └── CH34XUARTDriver.jar # WCH UART library
|
|
│ └── src/
|
|
│ ├── main/java/com/example/ch34/
|
|
│ │ ├── Ch34Plugin.java # Main plugin + MethodCallHandler
|
|
│ │ ├── Ch34DataStreamHandler.java # Data EventChannel handler
|
|
│ │ ├── Ch34ModemStreamHandler.java # Modem EventChannel handler
|
|
│ │ ├── Ch34UsbStateStreamHandler.java # USB hotplug handler
|
|
│ │ └── Ch34TypeConverter.java # Type conversion utilities
|
|
│ └── test/java/com/example/ch34/
|
|
│ └── Ch34PluginTest.java # Unit tests
|
|
├── example/ # Example Flutter app
|
|
│ ├── lib/
|
|
│ │ └── main.dart # Example app with device scan/connect/send
|
|
│ ├── test/
|
|
│ │ └── widget_test.dart # Widget test (stub)
|
|
│ └── integration_test/
|
|
│ └── plugin_integration_test.dart # Integration test
|
|
├── test/ # Plugin unit tests
|
|
│ ├── ch34_test.dart # Platform interface + manager tests
|
|
│ └── ch34_method_channel_test.dart # MethodChannel mock tests
|
|
├── docs/
|
|
│ └── CH34X-api_docs.md # WCH API documentation reference
|
|
├── pubspec.yaml # Plugin package manifest
|
|
├── analysis_options.yaml # Dart linting config
|
|
├── CHANGELOG.md # Version history
|
|
├── LICENSE # License file
|
|
├── README.md # Plugin documentation
|
|
└── .gitignore # Git ignore rules
|
|
```
|
|
|
|
## Directory Purposes
|
|
|
|
### `lib/` - Dart Source
|
|
- **Purpose:** All Dart code for the Flutter plugin
|
|
- **Key files:**
|
|
- `lib/ch34.dart` - Primary consumer import: `import 'package:ch34/ch34.dart';`
|
|
- `lib/src/ch34_manager.dart` - Static facade, all public APIs
|
|
- `lib/src/ch34_platform_interface.dart` - Abstract interface with 33 methods
|
|
- `lib/src/ch34_method_channel.dart` - MethodChannel + EventChannel implementation
|
|
- `lib/src/types/ch34_types.dart` - Shared data models and enums
|
|
|
|
### `android/` - Android Native
|
|
- **Purpose:** Java implementation bridging to WCH CH34X UART library
|
|
- **Key files:**
|
|
- `android/src/main/java/com/example/ch34/Ch34Plugin.java` - Plugin entry point (788 lines)
|
|
- `android/build.gradle` - Library configuration (compileSdk 34, minSdk 21, Java 8)
|
|
- `android/libs/CH34XUARTDriver.jar` - WCH vendor SDK (binary dependency)
|
|
|
|
### `example/` - Sample Application
|
|
- **Purpose:** Demonstrates plugin usage for development and testing
|
|
- **Key files:**
|
|
- `example/lib/main.dart` - Full working example: scan devices, open, set params, send/receive data
|
|
|
|
### `test/` - Plugin Tests
|
|
- **Purpose:** Unit tests for the Dart plugin code
|
|
- **Contains:** MethodChannel mock tests, platform interface mock implementation
|
|
|
|
## Key File Locations
|
|
|
|
**Entry Points:**
|
|
- `lib/ch34.dart`: Main library entry, consumer-facing import
|
|
- `android/src/main/java/com/example/ch34/Ch34Plugin.java`: Android plugin entry, registered via `pubspec.yaml`
|
|
|
|
**Configuration:**
|
|
- `pubspec.yaml`: Plugin declaration, Android platform registration (`package: com.example.ch34`, `pluginClass: Ch34Plugin`)
|
|
- `android/build.gradle`: Android library build configuration
|
|
- `analysis_options.yaml`: Dart linting (extends `flutter_lints`)
|
|
|
|
**Core Logic:**
|
|
- `lib/src/ch34_manager.dart`: Static API facade (all consumer methods)
|
|
- `lib/src/ch34_platform_interface.dart`: Abstract interface contract
|
|
- `lib/src/ch34_method_channel.dart`: Channel communication implementation
|
|
- `android/src/main/java/com/example/ch34/Ch34Plugin.java`: Native bridge logic
|
|
|
|
**Types:**
|
|
- `lib/src/types/ch34_types.dart`: All data classes (`UsbDeviceInfo`, `SerialParameter`, `ModemStatus`, `GpioStatus`) and enums (`DataBits`, `StopBits`, `Parity`, `GpioDirection`, `GpioValue`, `SerialErrorType`)
|
|
|
|
**Testing:**
|
|
- `test/ch34_method_channel_test.dart`: Unit tests with mock platform
|
|
- `test/ch34_test.dart`: Integration-style tests with real MethodChannel mock
|
|
- `example/integration_test/plugin_integration_test.dart`: On-device integration test
|
|
|
|
## Naming Conventions
|
|
|
|
**Files:**
|
|
- Dart: `snake_case.dart` for all files (e.g., `ch34_manager.dart`, `ch34_types.dart`)
|
|
- Java: `PascalCase.java` for all classes (e.g., `Ch34Plugin.java`, `Ch34TypeConverter.java`)
|
|
|
|
**Dart Classes:**
|
|
- Public API class: `Ch34Manager` (static methods, facade pattern)
|
|
- Platform interface: `Ch34Platform` (abstract, extends `PlatformInterface`)
|
|
- Channel implementation: `MethodChannelCh34` (extends `Ch34Platform`)
|
|
- Data types: `UsbDeviceInfo`, `SerialParameter`, `ModemStatus`, `GpioStatus`
|
|
- Enums: `DataBits`, `StopBits`, `Parity`, `GpioDirection`, `GpioValue`, `SerialErrorType`
|
|
- Exception: `Ch34Exception`
|
|
|
|
**Java Classes:**
|
|
- Main plugin: `Ch34Plugin` (implements `FlutterPlugin`, `MethodCallHandler`)
|
|
- Stream handlers: `Ch34DataStreamHandler`, `Ch34ModemStreamHandler`, `Ch34UsbStateStreamHandler`
|
|
- Utility: `Ch34TypeConverter` (static methods only, private constructor)
|
|
|
|
**MethodChannel names:**
|
|
- Method channel: `'ch34'`
|
|
- Data event channel: `'ch34/data'`
|
|
- Modem event channel: `'ch34/modem'`
|
|
- USB state event channel: `'ch34/usb_state'`
|
|
|
|
**Method names:** Match Dart method names exactly (e.g., `enumDevice`, `openDevice`, `setSerialParameter`, `writeData`, `readData`)
|
|
|
|
## Where to Add New Code
|
|
|
|
**New Dart API Method:**
|
|
1. Add abstract method signature to `lib/src/ch34_platform_interface.dart`
|
|
2. Add concrete implementation to `lib/src/ch34_method_channel.dart` (using `methodChannel.invokeMethod()`)
|
|
3. Add static wrapper to `lib/src/ch34_manager.dart` (delegating to `Ch34Platform.instance`)
|
|
4. Add mock implementation in `test/ch34_method_channel_test.dart` for testing
|
|
5. Add native handler in `android/src/main/java/com/example/ch34/Ch34Plugin.java`
|
|
|
|
**New EventChannel (streaming):**
|
|
1. Create new `*StreamHandler.java` in `android/src/main/java/com/example/ch34/`
|
|
2. Register in `Ch34Plugin.onAttachedToEngine()`
|
|
3. Add `EventChannel` and `StreamSubscription` in `lib/src/ch34_method_channel.dart`
|
|
4. Add platform interface methods to `Ch34Platform`
|
|
5. Add static wrappers to `Ch34Manager`
|
|
|
|
**New Data Type:**
|
|
- Add to `lib/src/types/ch34_types.dart`
|
|
- Add corresponding conversion in `android/src/main/java/com/example/ch34/Ch34TypeConverter.java`
|
|
|
|
**New Native Utility:**
|
|
- Add to `android/src/main/java/com/example/ch34/` as a new Java class or extend existing
|
|
|
|
## Module Boundaries
|
|
|
|
### Dart Layer
|
|
```
|
|
lib/ch34.dart (exports)
|
|
|
|
|
v
|
|
lib/src/ch34_manager.dart (static facade)
|
|
|
|
|
v
|
|
lib/src/ch34_platform_interface.dart (abstract contract)
|
|
|
|
|
v
|
|
lib/src/ch34_method_channel.dart (concrete implementation)
|
|
|
|
|
+---> lib/src/types/ch34_types.dart (shared types)
|
|
```
|
|
|
|
### Native Layer
|
|
```
|
|
Ch34Plugin.java (MethodCallHandler + 3 EventChannels)
|
|
|
|
|
+---> Ch34DataStreamHandler.java (data streaming)
|
|
+---> Ch34ModemStreamHandler.java (modem status streaming)
|
|
+---> Ch34UsbStateStreamHandler.java (USB hotplug streaming)
|
|
+---> Ch34TypeConverter.java (type conversion utilities)
|
|
|
|
|
v
|
|
CH34XUARTDriver.jar (WCH vendor SDK)
|
|
```
|
|
|
|
### Platform Bridge
|
|
```
|
|
Dart: MethodChannel('ch34') <---> Java: Ch34Plugin (MethodCallHandler)
|
|
Dart: EventChannel('ch34/data') <---> Java: Ch34DataStreamHandler
|
|
Dart: EventChannel('ch34/modem') <---> Java: Ch34ModemStreamHandler
|
|
Dart: EventChannel('ch34/usb_state') <---> Java: Ch34UsbStateStreamHandler
|
|
```
|
|
|
|
## Special Directories
|
|
|
|
**`android/libs/`:**
|
|
- Purpose: Contains binary JAR dependency (`CH34XUARTDriver.jar`)
|
|
- Generated: No, committed to repo
|
|
- Referenced by: `android/build.gradle` via `flatDir` repository
|
|
|
|
**`example/`:**
|
|
- Purpose: Self-contained Flutter app demonstrating plugin usage
|
|
- Generated: No, committed to repo
|
|
- Note: The example app package is `ch34_example`
|
|
|
|
**`docs/`:**
|
|
- Purpose: API documentation reference for WCH WCHUARTManager
|
|
- Contains: `CH34X-api_docs.md` - comprehensive API documentation in Markdown
|
|
|
|
**`lib/` root-level files:**
|
|
- Purpose: Backward compatibility re-exports
|
|
- `lib/ch34_platform_interface.dart` exports `src/ch34_platform_interface.dart`
|
|
- `lib/ch34_method_channel.dart` exports `src/ch34_method_channel.dart`
|
|
|
|
---
|
|
|
|
*Structure analysis: 2026-04-16*
|