Flutter Flame BLE Motion Control Demo

This project demonstrates how to use a Bluetooth Low Energy (BLE) enabled orientation sensor (peripheral) to control a player character in a game built with Flutter and the Flame engine (client).

🚀 Overview

TThe application runs on the client and, after a button press, scans for a specific BLE peripheral device, connects to it, and subscribes to a characteristic that provides orientation data (pitch, roll, and yaw). This data is then used to control the movement of a player on the screen in real-time.

✨ Features

• Manual BLE Device Scanning & Connection: Scans for and connects to a predefined BLE peripheral after the user presses a scan button.
• Real-time Player Control: Uses live orientation data from the sensor to move the player character.
• State Management with BLoC: Manages the BLE connection and orientation data state using the flutter_bloc package.
• Game Logic with Flame: Implements the game loop, rendering, and component management using the Flame engine.
• Clear Separation of Concerns: The project is structured to separate BLE communication, state management, and game logic.

🎮 Example Companion Peripheral Hardware

Mobile Phone

• flutter_ble_sensor_broadcaster
  • use a second mobile phone to broadcast orientation data via BLE.
  • use the same UUIDs as defined in lib/constants/ble_constants.dart.

Microcontroller with BLE Sensors

• TODO: Add example code for broadcasting orientation data from a microcontroller with BLE sensors.

⚙️ Project Structure

The project is organized into several directories to maintain a clean architecture:

lib/  
├── constants/  
│   └── ble_constants.dart      # UUIDs and device name for the BLE sensor  
├── cubit/  
│   ├── ble_cubit.dart          # BLoC for managing BLE state (scanning, connecting, data)  
│   ├── ble_state.dart          # States for the BleCubit  
│   ├── orientation_cubit.dart  # BLoC for managing orientation data  
│   └── orientation_state.dart  # States for the OrientationCubit  
├── game/  
│   ├── components/  
│   │   ├── ble_controller.dart   # Flame component to interact with BleCubit  
│   │   ├── motion_controller.dart# Flame component to move the player based on orientation  
│   │   ├── player.dart         # The player character component
│   │   ├── scan_button.dart    # Button component to initiate BLE scanning
│   │   └── status.dart         # Text component to display connection status
│   ├── ble_motion_control_game.dart # Main Flame game class  
│   └── game.dart               # Main game page widget  
├── repositories/  
│   └── ble_repository.dart     # Handles all BLE interactions  
└── main.dart                   # Main entry point of the application

📱 Platform Support

Platform	Supported	Tested
Android	✅	✅
iOS	✅	❌

🛠️ Getting Started

Prerequisites

• Flutter SDK installed.
• A physical Android/iOS device with Bluetooth capabilities (client).
• A companion BLE orientation sensor (peripheral) configured to broadcast with the service and characteristic UUIDs defined in lib/constants/ble_constants.dart. The default device name is "FSen".

Installation

1. Clone the repository:

   git clone https://github.com/IoT-gamer/flutter_flame_ble_motion_control_demo.git 
   cd flutter_flame_ble_controller_demo

2. Install dependencies:

   flutter pub get

3. Configure BLE Constants:
   Open lib/constants/ble_constants.dart and update the serviceUuid, characteristicUuid, and deviceName to match your BLE sensor.

   class BleConstants {  
     static const String serviceUuid = "YOUR_SERVICE_UUID";  
     static const String characteristicUuid = "YOUR_CHARACTERISTIC_UUID";  
     static const String deviceName = "YOUR_DEVICE_NAME";  
   }

Running the Application

1. Ensure your BLE orientation sensor (peripheral) is turned on and discoverable.
2. Connect your Android/iOS device (client) to your computer.
3. Run the app from your terminal:

   flutter run

The app will launch and display a "Start Scan" button. Press the button to start scanning for your device and connect to it automatically. Once connected, tilting the peripheral sensor will move the blue circle on the screen.

🔧 How It Works

1. Initialization: The main.dart file initializes the app, sets it to fullscreen and landscape mode, and launches the GamePage.
2. State Management Setup: The GamePage widget uses MultiBlocProvider to make the OrientationCubit and BleCubit available to the widget tree.
3. BLE Communication:
   • The BleRepository handles the low-level BLE operations using the flutter_blue_plus package.
   • The BleCubit coordinates the BLE logic, such as starting a scan, connecting to a device, and handling incoming data.
   • The BleController component within the Flame game listens to state changes from the BleCubit. When a device is connected, it discovers the correct service/characteristic and tells the cubit to subscribe.
4. Game Logic:
   • BleMotionControlGame is the main game class.
   • When the BleCubit receives data, it passes it to the OrientationCubit.
   • The MotionController component listens for new orientation data from the OrientationCubit.
   • It then calculates the player's velocity based on the sensor's pitch and roll, moving the Player component accordingly.
   • The Status component displays the current BLE connection status.