Adding Linux Ubuntu Support To Your Flutter App A Step-by-Step Guide

Jul 13, 2025 by gitftunila 69 views

Add Support for Linux Ubuntu in Your Flutter App

In this comprehensive guide, we will walk you through the process of adding Linux Ubuntu support to your Flutter application, specifically focusing on the bitchat_flutter project. This involves modifying the app for seamless use on both Android and Linux Ubuntu, as well as preparing an installation script. We will cover the necessary steps, from installing Flutter on Ubuntu to troubleshooting common issues. This article aims to provide a detailed, step-by-step approach to ensure your Flutter app is fully functional on Linux Ubuntu.

Step 1: Install Flutter on Ubuntu

To begin, it's essential to ensure that Flutter is correctly installed and operational on your Ubuntu system. Flutter is a versatile framework that allows developers to build applications for various platforms, including Android, iOS, web, and desktop, from a single codebase. This makes it an ideal choice for projects like bitchat_flutter, which aims to be accessible across multiple platforms.

First, open your terminal and use the Snap package manager to install Flutter. Snap provides a convenient way to distribute applications and their dependencies, ensuring a smooth installation process. Execute the following command:

sudo snap install flutter --classic

The --classic flag is necessary because Flutter requires full access to the system to function correctly. Once the installation is complete, you should verify that Flutter is working as expected by running the flutter doctor command:

flutter doctor

This command checks your environment and displays a report of the status of your Flutter installation. It identifies any missing dependencies or configuration issues. Pay close attention to the output and resolve any problems that are reported. Common issues include missing Android SDK components, platform-specific dependencies, or outdated tools. Addressing these issues early on ensures a smoother development experience. For instance, you might need to install additional Android SDK components or update your system's PATH environment variable to include Flutter's binaries. Following the recommendations provided by flutter doctor is crucial for setting up a stable Flutter development environment on Ubuntu.

Step 2: Create the Flutter Project

After successfully installing Flutter on your Ubuntu system, the next step is to create a new Flutter project specifically for bitchat_flutter. This involves setting up the basic project structure and enabling Linux desktop support. By creating a dedicated project, you ensure a clean and organized codebase, which is essential for maintaining and scaling your application.

To create the project, open your terminal and navigate to the directory where you want to store your project files. Then, use the flutter create command followed by the name of your project:

flutter create bitchat_flutter

This command generates a new Flutter project with all the necessary files and directories. Once the project is created, navigate into the project directory:

cd bitchat_flutter

Now that you are inside the project directory, you need to explicitly enable Linux desktop support. By default, Flutter projects are configured for mobile platforms. To target Linux, you must enable desktop support using the flutter config command. This command configures Flutter to build applications for the Linux platform, which is a crucial step for ensuring your app runs smoothly on Ubuntu. Execute the following command:

flutter config --enable-linux-desktop

Enabling Linux desktop support adds the necessary configuration files and settings to your project, allowing Flutter to compile your code into a Linux executable. After enabling Linux support, it's a good practice to verify that Flutter recognizes the Linux platform as a target device. Use the flutter devices command to list all available devices:

flutter devices

The output should include Linux (desktop) in the list of available devices. This confirms that your Flutter environment is correctly configured for Linux development. If you don't see Linux listed, double-check that you have executed the flutter config command correctly and that your Flutter installation is up-to-date.

Step 3: Choose the BLE Package

When developing applications that interact with Bluetooth Low Energy (BLE) devices, selecting the right BLE package is crucial for ensuring compatibility and functionality. In the context of Linux, where BLE support can vary, choosing a robust and well-maintained package is especially important. For the bitchat_flutter project, which aims to support BLE functionality on Ubuntu, the recommended package is flutter_blue_plus.

FlutterBluePlus is a popular Flutter package that provides comprehensive BLE support across multiple platforms, including Linux. It offers a rich set of features and is actively maintained, making it a reliable choice for handling BLE interactions. The package simplifies the process of scanning for devices, connecting to them, and exchanging data. It is specifically recommended for Linux compatibility due to its stability and active support for the platform.

To install the flutter_blue_plus package, you need to add it as a dependency in your project's pubspec.yaml file. This file is located in the root directory of your Flutter project and lists all the dependencies your project relies on. Open the pubspec.yaml file in a text editor and add the following lines under the dependencies section:

dependencies:
  flutter:
    sdk: flutter
  flutter_blue_plus: ^1.32.5

The ^1.32.5 specifies the version of the flutter_blue_plus package you want to use. The ^ symbol indicates that Flutter's pub package manager is allowed to fetch compatible versions of the package with minor updates and bug fixes. After adding the dependency, save the pubspec.yaml file and run the following command in your terminal to fetch the package:

flutter pub get

This command instructs Flutter to download and install the flutter_blue_plus package and its dependencies. Once the command completes successfully, you are ready to use the package in your project. Choosing flutter_blue_plus ensures that your bitchat_flutter application can effectively interact with BLE devices on Linux Ubuntu, providing a solid foundation for implementing Bluetooth-related features.

Step 4: Basic BLE Scan App

Now that you have the flutter_blue_plus package installed, the next step is to implement a basic BLE scanning functionality within your Flutter application. This involves creating a user interface that allows you to initiate a scan for nearby Bluetooth devices and display the results. To achieve this, you will modify the default lib/main.dart file with the necessary code to handle BLE scanning. This will serve as the foundation for more advanced BLE interactions in your application.

Open the lib/main.dart file in your project and replace its contents with the following code:

import 'package:flutter/material.dart';
import 'package:flutter_blue_plus/flutter_blue_plus.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget{
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: const BLEScanPage(),
      debugShowCheckedModeBanner: false,
    );
  }
}

class BLEScanPage extends StatefulWidget {
  const BLEScanPage({super.key});

  @override
  State<BLEScanPage> createState() => _BLEScanPageState();
}

class _BLEScanPageState extends State<BLEScanPage> {
  List<ScanResult> devices = [];
  bool scanning = false;

  void startScan() {
    setState(() {
      devices.clear();
      scanning = true;
    });
    FlutterBluePlus.startScan(timeout: const Duration(seconds: 5)).listen(
      (scanResult) {
        setState(() {
          devices.add(scanResult);
        });
      },
      onDone: () => setState(() => scanning = false),
    );
  }

  @override
  void initState() {
    super.initState();
    FlutterBluePlus.adapterState.listen((state) {
      if (state == BluetoothAdapterState.on) {
        startScan();
      }
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('BLE Device Scanner'),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: scanning ? null : startScan,
        child: Icon(scanning ? Icons.bluetooth_searching : Icons.bluetooth),
      ),
      body: devices.isEmpty
          ? const Center(child: Text('No devices found yet'))
          : ListView.builder(
              itemCount: devices.length,
              itemBuilder: (context, i) => ListTile(
                title: Text(devices[i].device.platformName.isNotEmpty
                    ? devices[i].device.platformName
                    : "Unknown Device"),
                subtitle: Text(devices[i].device.remoteId.toString()),
                trailing: Text('RSSI: ${devices[i].rssi}'),
              ),
            ),
    );
  }
}

This code creates a simple Flutter application with a BLEScanPage widget. The widget includes a FloatingActionButton that initiates a BLE scan when pressed. The startScan function uses FlutterBluePlus.startScan to scan for nearby devices for a duration of 5 seconds. The scan results are stored in the devices list, and the UI is updated using setState to display the list of discovered devices. Each device is shown in a ListTile with its name, ID, and RSSI (Received Signal Strength Indication). The initState method listens for changes in the Bluetooth adapter state and starts scanning automatically if Bluetooth is already turned on. This basic implementation provides a functional BLE scanner that you can build upon to create more complex features for your bitchat_flutter application.

Step 5: Linux Dependencies (Important)

To ensure the seamless functioning of your Flutter application with Bluetooth Low Energy (BLE) on Linux Ubuntu, it is crucial to install the necessary Linux dependencies. These dependencies include essential libraries and tools that facilitate Bluetooth communication and ensure that your application can interact with BLE devices without any issues. Neglecting this step can lead to various problems, such as the application not being able to detect or connect to Bluetooth devices.

First, update the package lists for upgrades and new installations. This ensures that you have the latest versions of the packages and their dependencies. Open your terminal and run the following command:

sudo apt-get update

After updating the package lists, install the required Bluetooth libraries and development tools. These packages provide the necessary components for compiling and running Bluetooth-enabled applications on Linux. The following command installs clang, cmake, ninja-build, pkg-config, libgtk-3-dev, libbluetooth-dev, and bluez:

sudo apt-get install \
    clang \
    cmake \
    ninja-build \
    pkg-config \
    libgtk-3-dev \
    libbluetooth-dev \
    bluez

clang: A compiler used for building software.
cmake: A cross-platform build system generator.
ninja-build: A small build system with a focus on speed.
pkg-config: A utility for retrieving information about installed libraries.
libgtk-3-dev: Development files for GTK+ 3, a GUI toolkit.
libbluetooth-dev: Development files for the BlueZ Bluetooth stack.
bluez: The official Linux Bluetooth protocol stack.

Next, ensure that the Bluetooth service is running on your system. The Bluetooth service is responsible for managing Bluetooth devices and connections. You can enable and start the service using the following commands:

sudo systemctl enable bluetooth
sudo systemctl start bluetooth

The first command ensures that the Bluetooth service starts automatically on boot, while the second command starts the service immediately. It's also important to check if your user is in the bluetooth group. Being in the bluetooth group grants the necessary permissions to access Bluetooth devices. Add your user to the bluetooth group using the following command:

sudo usermod -a -G bluetooth $USER

This command adds the current user ($USER) to the bluetooth group. For the changes to take effect, you need to reboot your system. Rebooting ensures that the new group membership is applied and that all Bluetooth-related services and permissions are correctly configured. After rebooting, your Flutter application should be able to access Bluetooth devices without any permission issues. These steps are essential for setting up the Linux environment for BLE development and ensuring that your application can effectively interact with Bluetooth devices.

Step 6: Run Your Flutter App

After configuring your Flutter project and installing the necessary Linux dependencies, you are now ready to run your Flutter app on Ubuntu. This step involves compiling your Flutter code and launching the application on your Linux desktop environment. By running your app, you can verify that the Bluetooth functionality is working correctly and that the user interface is behaving as expected. This is a crucial step in the development process, allowing you to identify and address any issues early on.

To launch your Flutter app on Linux, open your terminal and navigate to the root directory of your Flutter project, which is where the pubspec.yaml file is located. Once you are in the project directory, use the flutter run command with the -d linux flag to specify that you want to run the application on the Linux desktop. Execute the following command:

flutter run -d linux

The flutter run command compiles your Flutter code and launches the application on the specified target device. The -d linux flag tells Flutter to build and run the application for the Linux desktop environment. Flutter will then build your app and launch it in a new window. You should see a basic graphical user interface (GUI) with a scan button, as implemented in the lib/main.dart file during Step 4. This confirms that your Flutter application is running successfully on Linux.

Step 7: Verify Functionality

Once your Flutter application is running on Linux, the next critical step is to verify its functionality, particularly the Bluetooth Low Energy (BLE) scanning feature. This involves ensuring that your app can discover nearby BLE devices and display them correctly in the user interface. Proper verification is essential to confirm that the application behaves as expected and that the BLE integration is working seamlessly.

First, make sure that any BLE devices you intend to discover are discoverable. BLE devices often have a discovery mode that needs to be enabled to allow other devices to find them. Refer to the documentation of your BLE devices to learn how to enable discovery mode. This ensures that the devices are broadcasting their presence and can be detected by your Flutter application.

Next, in your running Flutter application, click the FloatingActionButton that you implemented in Step 4. This button is designed to initiate a BLE scan. When you click the button, the application should start scanning for nearby BLE devices. If the scan is successful, the list of discovered devices should begin to populate in the user interface. By observing the behavior of the application, you can confirm that the scanning functionality is working as expected.

Confirm that the devices appear correctly in the UI. The application should display each discovered device with its name, ID, and RSSI (Received Signal Strength Indication). If the device names are not available, the application should display a default name like "Unknown Device". The device IDs should be unique identifiers for each device, and the RSSI values indicate the signal strength of the Bluetooth connection. Verify that this information is displayed accurately for each discovered device. If the devices are listed correctly with their respective details, it confirms that your Flutter application is successfully scanning for and displaying BLE devices on Linux Ubuntu. This step is crucial for validating the core BLE functionality of your application and ensuring that it meets the intended requirements.

Step 8: Troubleshooting Tips

Even with careful setup, you might encounter issues when running your Flutter application with BLE on Linux. Troubleshooting is a crucial part of the development process. These tips can help you diagnose and resolve common problems, ensuring your application works smoothly.

If you face issues, start by checking the Bluetooth status on your system. You can use the rfkill command to list Bluetooth devices and their block status. Open your terminal and run the following command:

rfkill list bluetooth

This command displays a list of Bluetooth devices and indicates whether they are blocked. If a device is blocked, it cannot be used for Bluetooth communication. To unblock a Bluetooth device, use the rfkill unblock command followed by the device identifier. For example, if the output of rfkill list bluetooth shows that 0: hci0: Bluetooth is blocked, you can unblock it using the following command:

rfkill unblock bluetooth

This command unblocks the specified Bluetooth device, allowing it to be used for Bluetooth communication. If rfkill commands are needed, it indicates a software block that was preventing Bluetooth from functioning correctly.

Additionally, verify BLE scan from the terminal. This helps determine if the issue is with your Flutter application or with the underlying Bluetooth system. Use the bluetoothctl command-line tool to scan for BLE devices directly from the terminal. First, start the bluetoothctl tool by running the following command:

bluetoothctl

Once inside the bluetoothctl interface, turn on the Bluetooth controller by typing power on and pressing Enter. Then, start scanning for devices by typing scan on and pressing Enter:

power on
scan on

If this doesn't work, your hardware or drivers may have compatibility issues. When running scan on, bluetoothctl should display a list of nearby Bluetooth devices. If bluetoothctl can discover devices, but your Flutter application cannot, it suggests that the issue may be within your application's code or configuration. Double-check your Flutter code, particularly the BLE scanning logic, and ensure that you have correctly implemented the necessary permissions and settings. If bluetoothctl cannot discover devices either, it indicates a more fundamental problem with your Bluetooth hardware or drivers. In this case, you may need to update your Bluetooth drivers, check your hardware connections, or consult your system's documentation for further troubleshooting steps. These troubleshooting tips provide a systematic approach to diagnosing and resolving common issues with BLE on Linux, helping you ensure that your Flutter application functions correctly.