mirror of
https://github.com/m5stack/StackChan.git
synced 2026-04-28 11:27:59 +00:00
袁智鸿
372 lines
9.7 KiB
Markdown
372 lines
9.7 KiB
Markdown
# StackChan App
|
|
|
|
[](https://opensource.org/licenses/MIT)
|
|
[](https://flutter.dev/)
|
|
[](https://dart.dev/)
|
|
|
|
A powerful Flutter application for controlling and interacting with the StackChan AI robot companion. Features include
|
|
Bluetooth connectivity, AI conversation capabilities, facial expression rendering, and dance choreography.
|
|
|
|
## Features
|
|
|
|
- 🤖 **Bluetooth Device Management** - Connect and control StackChan robots via BLE
|
|
- 💬 **AI Conversation** - Natural language interaction powered by XiaoZhi AI
|
|
- 🎭 **Facial Expression Rendering** - Real-time 3D face animation using Three.js
|
|
- 🎵 **Music & Dance** - Create and play dance choreographies with music
|
|
- 📷 **Camera Integration** - AR features and face detection
|
|
- 🔐 **Secure Communication** - RSA encryption for data transmission
|
|
|
|
## System Requirements
|
|
|
|
- **Flutter SDK**: 3.0+
|
|
- **Dart SDK**: 3.0+
|
|
- **iOS**: 14.0+ (for iOS deployment)
|
|
- **Android**: API 21+ (for Android deployment)
|
|
- **macOS**: 11.0+ (for macOS deployment)
|
|
## Installation
|
|
|
|
### 1. Install Flutter
|
|
|
|
Follow the official Flutter installation guide for your operating system:
|
|
|
|
#### macOS
|
|
|
|
```bash
|
|
# Download Flutter SDK
|
|
git clone https://github.com/flutter/flutter.git -b stable
|
|
export PATH="$PATH:`pwd`/flutter/bin"
|
|
|
|
# Verify installation
|
|
flutter doctor
|
|
```
|
|
|
|
#### Windows
|
|
|
|
```bash
|
|
# Download Flutter SDK from https://flutter.dev/docs/get-started/install/windows
|
|
# Extract and add to PATH
|
|
|
|
# Verify installation
|
|
flutter doctor
|
|
```
|
|
|
|
#### Linux
|
|
|
|
```bash
|
|
# Download Flutter SDK
|
|
git clone https://github.com/flutter/flutter.git -b stable
|
|
export PATH="$PATH:`pwd`/flutter/bin"
|
|
|
|
# Install dependencies
|
|
sudo apt-get install clang cmake ninja-build pkg-config libgtk-3-dev liblzma-dev
|
|
|
|
# Verify installation
|
|
flutter doctor
|
|
```
|
|
|
|
### 2. Set Up Project
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone <repository-url>
|
|
cd StackChan
|
|
|
|
# Install dependencies
|
|
flutter pub get
|
|
```
|
|
|
|
### 3. Configure Backend Server
|
|
|
|
The application requires a backend server for full functionality. Configure the server endpoints before building:
|
|
|
|
#### Option A: Using Environment Configuration (Recommended)
|
|
|
|
Create a `.env` file in the project root or modify the configuration directly in code.
|
|
|
|
#### Option B: Direct Code Configuration
|
|
|
|
Modify `lib/network/urls.dart` to set your backend server URL:
|
|
|
|
```dart
|
|
// lib/network/urls.dart
|
|
class Urls {
|
|
// Update this to your backend server address
|
|
static const String url = "your-backend-server:port/";
|
|
|
|
// ... rest of the configuration
|
|
}
|
|
```
|
|
|
|
#### Option C: Configure Value Constants
|
|
|
|
Update `lib/util/value_constant.dart` for encryption keys and other constants:
|
|
|
|
```dart
|
|
// lib/util/value_constant.dart
|
|
class ValueConstant {
|
|
// Server RSA Public Key for encryption
|
|
static const String serverPublicKey = """
|
|
-----BEGIN PUBLIC KEY-----
|
|
YOUR_SERVER_PUBLIC_KEY_HERE
|
|
-----END PUBLIC KEY-----
|
|
""";
|
|
|
|
// Client RSA Private Key for decryption
|
|
static const String clientPrivateKey = """
|
|
-----BEGIN RSA PRIVATE KEY-----
|
|
YOUR_CLIENT_PRIVATE_KEY_HERE
|
|
-----END RSA PRIVATE KEY-----
|
|
""";
|
|
}
|
|
```
|
|
|
|
**Important**: For production deployments, use environment variables or secure key management instead of hardcoding
|
|
keys.
|
|
|
|
## Building the Application
|
|
|
|
### iOS
|
|
|
|
```bash
|
|
# Install CocoaPods dependencies
|
|
cd ios
|
|
pod install
|
|
cd ..
|
|
|
|
# Run on iOS simulator
|
|
flutter run -d ios
|
|
|
|
# Build for release (iOS device)
|
|
flutter build ios --release
|
|
```
|
|
|
|
### Android
|
|
|
|
```bash
|
|
# Run on Android emulator or connected device
|
|
flutter run -d android
|
|
|
|
# Build APK for release
|
|
flutter build apk --release
|
|
|
|
# Build App Bundle for Google Play
|
|
flutter build appbundle --release
|
|
```
|
|
|
|
### Android Release Signing (JKS)
|
|
|
|
For release builds (`apk --release` / `appbundle --release`), configure a keystore instead of hardcoding passwords in
|
|
`build.gradle.kts`.
|
|
|
|
#### 1. Generate a JKS file
|
|
|
|
```bash
|
|
keytool -genkeypair -v \
|
|
-keystore android/app/release.jks \
|
|
-alias release \
|
|
-keyalg RSA -keysize 2048 -validity 10000
|
|
```
|
|
|
|
#### 2. Create `android/key.properties`
|
|
|
|
```properties
|
|
storePassword=YOUR_STORE_PASSWORD
|
|
keyPassword=YOUR_KEY_PASSWORD
|
|
keyAlias=release
|
|
storeFile=../app/release.jks
|
|
```
|
|
|
|
> `android/.gitignore` already ignores `key.properties` and `*.jks`. Keep these files private.
|
|
|
|
#### 3. Load the properties in `android/app/build.gradle.kts`
|
|
|
|
Use Kotlin DSL style configuration:
|
|
|
|
```kotlin
|
|
import java.util.Properties
|
|
|
|
val keystoreProperties = Properties()
|
|
val keystorePropertiesFile = rootProject.file("key.properties")
|
|
if (keystorePropertiesFile.exists()) {
|
|
keystoreProperties.load(keystorePropertiesFile.inputStream())
|
|
}
|
|
|
|
android {
|
|
signingConfigs {
|
|
create("release") {
|
|
if (keystorePropertiesFile.exists()) {
|
|
storeFile = file(keystoreProperties["storeFile"] as String)
|
|
storePassword = keystoreProperties["storePassword"] as String
|
|
keyAlias = keystoreProperties["keyAlias"] as String
|
|
keyPassword = keystoreProperties["keyPassword"] as String
|
|
}
|
|
}
|
|
}
|
|
|
|
buildTypes {
|
|
release {
|
|
signingConfig = signingConfigs.getByName("release")
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### 4. Build release artifacts
|
|
|
|
```bash
|
|
flutter build apk --release
|
|
flutter build appbundle --release
|
|
```
|
|
|
|
#### 5. CI/CD recommendation
|
|
|
|
In CI, inject signing values through environment variables or secure secrets storage. Do not commit keystore passwords or
|
|
private keys to the repository.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
lib/
|
|
├── main.dart # Application entry point
|
|
├── app_state.dart # Global state management
|
|
├── model/ # Data models
|
|
│ ├── XiaoZhi/ # AI service models
|
|
│ ├── blue_device_info.dart # Bluetooth device models
|
|
│ ├── dance_list.dart # Dance choreography models
|
|
│ └── ...
|
|
├── network/ # Network layer
|
|
│ ├── http.dart # HTTP client with interceptors
|
|
│ ├── urls.dart # API endpoint configurations
|
|
│ └── web_socket_util.dart # WebSocket management
|
|
├── util/ # Utilities
|
|
│ ├── value_constant.dart # App constants and keys
|
|
│ ├── rsa_util.dart # RSA encryption/decryption
|
|
│ ├── blue_util.dart # Bluetooth utilities
|
|
│ ├── music_util.dart # Music and audio processing
|
|
│ └── ...
|
|
└── view/ # UI layer
|
|
├── home/ # Home screens
|
|
├── popup/ # Modal screens
|
|
└── util/ # UI components and widgets
|
|
```
|
|
|
|
## Backend API Integration
|
|
|
|
The application integrates with two main backend services:
|
|
|
|
### 1. StackChan Backend (`lib/network/urls.dart`)
|
|
|
|
- Device registration and management
|
|
- Dance choreography storage
|
|
- User authentication
|
|
- File upload and media management
|
|
|
|
### 2. XiaoZhi AI Service (`lib/util/XiaoZhi_util.dart`)
|
|
|
|
- AI conversation and chat functionality
|
|
- Agent management and configuration
|
|
- TTS (Text-to-Speech) voice selection
|
|
- License and activation management
|
|
|
|
**Base URL Configuration:**
|
|
|
|
- StackChan Backend: `http://<server-ip>:<port>/stackChan/`
|
|
- XiaoZhi AI: `https://XiaoZhi.me/`
|
|
|
|
## Development
|
|
|
|
### Code Style
|
|
|
|
This project follows the official Dart and Flutter style guidelines:
|
|
|
|
- Use `camelCase` for variables and functions
|
|
- Use `PascalCase` for classes and types
|
|
- Use `snake_case` for JSON keys (API communication)
|
|
- Document public APIs with doc comments
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# Run all tests
|
|
flutter test
|
|
|
|
# Run specific test file
|
|
flutter test test/widget_test.dart
|
|
|
|
# Run with coverage
|
|
flutter test --coverage
|
|
```
|
|
|
|
### Linting
|
|
|
|
```bash
|
|
# Run static analysis
|
|
flutter analyze
|
|
```
|
|
|
|
## Contributing
|
|
|
|
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for more details.
|
|
|
|
1. Fork the repository
|
|
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
|
|
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
|
|
4. Push to the branch (`git push origin feature/amazing-feature`)
|
|
5. Open a Pull Request
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
**1. Flutter doctor reports missing dependencies**
|
|
|
|
- Follow the instructions provided by `flutter doctor` to install missing components
|
|
- For iOS: Ensure Xcode is installed and command line tools are selected
|
|
- For Android: Ensure Android Studio and SDK are properly configured
|
|
|
|
**2. Bluetooth not working**
|
|
|
|
- Ensure Bluetooth permissions are granted
|
|
- For iOS: Check `NSBluetoothAlwaysUsageDescription` in Info.plist
|
|
- For Android: Check `BLUETOOTH_SCAN` and `BLUETOOTH_CONNECT` permissions
|
|
|
|
**3. Backend connection fails**
|
|
|
|
- Verify server URL is correct in `lib/network/urls.dart`
|
|
- Check network connectivity
|
|
- Verify backend server is running and accessible
|
|
- Check SSL certificates for HTTPS connections
|
|
|
|
**4. Build fails on iOS**
|
|
|
|
```bash
|
|
cd ios
|
|
rm -rf Pods Podfile.lock
|
|
pod install --repo-update
|
|
cd ..
|
|
flutter clean
|
|
flutter pub get
|
|
```
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
|
|
## Acknowledgments
|
|
|
|
- M5Stack Technology CO LTD for the StackChan hardware
|
|
- Flutter team for the amazing framework
|
|
- Three.js for 3D rendering capabilities
|
|
- All contributors and open source libraries used in this project
|
|
|
|
## Support
|
|
|
|
For support, please:
|
|
|
|
1. Check the [Issues](../../issues) page for known problems
|
|
2. Create a new issue if your problem isn't already listed
|
|
3. For security issues, please contact security@m5stack.com directly
|
|
|
|
---
|
|
|
|
**Note**: This application requires compatible StackChan hardware and backend services for full functionality. |