Getting Started with ThingsBoard Mobile Application

Welcome! This guide walks you through creating and configuring your own ThingsBoard PE mobile application from scratch for your ThingsBoard instance.

Before you begin, choose the mobile app version that matches your ThingsBoard platform using the compatibility matrix. Using incompatible versions is the most common cause of sign-in issues or unexpected behavior.

• Access to a ThingsBoard instance. The easiest way is to use ThingsBoard Cloud. Alternatively, install ThingsBoard using the official installation guide.
• Prepare the environment for building the ThingsBoard PE mobile application:
  • Install the Flutter SDK version that corresponds to your app version (see the compatibility matrix).
  • Install Git to get the app source code.
  • For Android: install Android Studio with the Android SDK.
  • For iOS: use a Mac with Xcode and CocoaPods installed. iOS apps can’t be built on Windows or Linux.
  • Run flutter doctor and fix the issues it reports for the platforms you build for.
  • (Recommended) Configure your IDE (e.g., Visual Studio Code) for Flutter development.
  • If you’re new to Flutter, review the “Write your first Flutter app” tutorial.

The Mobile center is your control hub to create, configure, and manage mobile apps. It lets you quickly launch a mobile app tailored to your ThingsBoard platform.

A bundle contains both your Android and/or iOS app configurations — including OAuth 2.0 settings, layout preferences, and self registration options — all in one place for easier setup.

1. Go to the Mobile center page.
2. On the Bundle tab, click + Add bundle in the top-right corner.

1. Enter a bundle title.
2. Click Create new next to your target mobile platform (Android or iOS). This opens the Add application dialog:
   • Enter the application package name.
   • An Application Secret is generated automatically (you can also set your own).
   • Set the Published application status — application is ready for release.
   • (Optional) Specify minimum and latest app versions along with release notes.
   • Add store information:
     • Android: Google Play Store link and SHA256 certificate fingerprints.
     • iOS: App Store link and App ID.
   • Click Add to save and continue.
3. Click Next.

Click Create new in the appropriate section (Android Application or iOS Application). Android Application. Enter the application package name. Remember the autogenerated Application Secret or input your own. Specify application statuses. Optionally, specify minimum and latest app versions with release notes. Add store info: Google Play Store link and SHA256 certificate fingerprints. Click Add. iOS Application. Enter the application package name. Remember the autogenerated Application Secret or input your own. Specify application statuses. Optionally, specify minimum and latest app versions with release notes. Add store info: App Store link and App ID. Click Add. Click Next.

• OAuth 2.0 providers — Configure external OAuth for the ThingsBoard PE mobile app if required. Click Next when done.
• Configure layout — Customize the navigation menu for quick access to features and dashboards. Add menu items, set icons/labels, and reorder entries.
• Self registration — Customize the self registration page for your new customers.

Configure authentication using external OAuth 2.0 providers. Then click Next to continue. Configure the layout for quick access to the features and dashboards you use most often. Add new menu items, customize icons and labels, and reorganize the navigation menu. Click Next to continue. Customize the self registration page for your new customers. Click Add to finalize adding the bundle.

After adding the bundle, a step-by-step dialog appears to guide you through the remaining setup and deployment steps. Follow it carefully to complete ThingsBoard PE mobile application configuration.

The dialog walks through these steps:

1. Get the source code. Clone the app repository:

   git clone -b master https://github.com/thingsboard/flutter_thingsboard_pe_app.git

   The master branch holds the latest release. To build a specific version, check out its release tag, for example git checkout v1.9.1. Pick the version from the compatibility matrix.

2. Configure the app settings. Click Download file to get configs.json, and put it in the project root, next to pubspec.yaml. The file holds your server address, app ID, app name and app secrets, so the app needs no code changes.

3. Run the app. From the project root, run:

   flutter run --dart-define-from-file configs.json

Pass --dart-define-from-file configs.json to every flutter run and flutter build command. Without it, the app starts with the default ThingsBoard settings instead of yours.

You can maintain multiple configuration files by using different names and passing the appropriate filename to --dart-define-from-file.

Depending on your mobile platform (Android or iOS), you should see a result similar to the following:

Android iOS

ThingsBoard uses Firebase to send notifications from your ThingsBoard instance directly to the mobile application. This setup requires each platform tenant to configure Firebase specifically for their account to begin distributing notifications to their mobile app.

1. Sign in to your Firebase account and click Create a project.
2. Enter your desired project name and click Continue.
3. Decide on Google Analytics for your project (you can keep it enabled or disable it). Click Continue.
4. Confirm project creation by clicking Create project.
5. Once ready, click Continue to open the Firebase project control panel.
6. In the left menu, go to Project Overview → Project settings.
7. In Project settings, switch to the Cloud Messaging tab. Ensure the Firebase Cloud Messaging API is enabled.
8. Go to the Service accounts tab. Under Admin SDK configuration snippet, select the Java section. Click Generate new private key. Keep this key safe — you’ll need it for ThingsBoard server-side operations.
9. Confirm by clicking Generate key.
10. Sign in to your ThingsBoard instance and open Settings. Navigate to the Notifications tab and uncheck Use system mobile settings (if logged in as a tenant) in the Mobile settings section. Upload the private key file and click Save.

Sign in to Firebase and click Create a project. Enter your desired project name and click Continue. Choose whether to enable Google Analytics, then click Continue. Click Create project. Your Firebase project is ready. Click Continue to open the control panel. In the left menu, go to Project Overview → Project settings. Switch to the Cloud Messaging tab and ensure the Firebase Cloud Messaging API is enabled. In the Service accounts tab, select the Java section and click Generate new private key. Click Generate key and save the file. Sign in to ThingsBoard, open Settings → Notifications → Mobile settings. Uncheck Use system mobile settings (if logged in as a tenant). Upload the private key file and click Save.

To integrate Firebase into the mobile application, complete the initial two steps outlined in the Add Firebase to your Flutter app guide.

Upload an APNs authentication key to Firebase.

1. Create an APNs authentication key in the Apple Developer Member Center using Apple’s official documentation.
2. Inside your Firebase project, go to the Cloud Messaging tab of Project Settings. Scroll down to the Apple app configuration section.
3. In APNs authentication key, click Upload.
4. Add the key and enter the Key ID and Team ID in the corresponding fields.
5. Click Upload.

Go to the Cloud Messaging tab → Project Settings. Scroll down to the Apple app configuration section. In the APNs authentication key section, click Upload. Add the APNs key and enter the Key ID and Team ID. Click Upload. APNs authentication key is uploaded.

After completing these steps, make sure your project contains the following files:

• iOS: ios/Runner/GoogleService-Info.plist
• Android: android/app/google-services.json

To confirm Firebase has been integrated properly, run your application:

flutter run --dart-define-from-file configs.json

If everything is configured correctly, the notifications menu in your mobile application should be active:

Starting with version 1.9.1, a push notification shows the icon and icon color set for the Mobile app delivery method in the notification template:

• Android — the icon appears on the right side of the notification, whether the app is open, in the background or closed.
• iOS — the app includes a notification service extension that adds the icon as a thumbnail on the right side of the banner. It works once the platform sends push notifications with mutable-content enabled; until then, iOS notifications show the title and text only. The extension must be signed together with the app (see Configure signing).

Learn more about notifications and how to configure them in the Notifications guide.

If you need to build and release the ThingsBoard PE mobile application for iOS or Android, refer to the Build and release guide.

ThingsBoard mobile app supports specific Flutter versions. A newer Flutter version may not yet be compatible with the current release.

How to check the required Flutter version:

1. Check the release notes on GitHub: flutter_thingsboard_pe_app releases.

2. Check the .fvmrc file in the project root:

{
  "flutter": "3.29.3"
}

Installing the correct Flutter version:

Option 1 (Recommended): Use FVM — Flutter Version Manager

FVM lets you manage multiple Flutter versions across projects and switch between them per project. Install it following the official guide, then prefix Flutter commands with fvm:

fvm install
fvm flutter run --dart-define-from-file configs.json
fvm flutter build apk --no-tree-shake-icons --dart-define-from-file configs.json

fvm install reads .fvmrc and downloads the Flutter version the project needs.

Option 2: Manually set the global Flutter version (not recommended if you work on multiple projects)

cd ~/dev/flutter
git checkout 3.29.3
flutter --version

Replace ~/dev/flutter with the folder where your Flutter SDK is installed, and the version with the one from .fvmrc.

This usually means Firebase wasn’t set up correctly.

1. Delete the file: lib/firebase_options.dart
2. Re-run the FlutterFire CLI:

   flutterfire configure

3. Ensure firebase_options.dart is regenerated and contains configuration for Android, iOS, or both.

The mobile app opens the dashboard in a WebView — the ThingsBoard platform handles all actual loading. For the dashboard to work, the app and platform must be able to communicate.

Check the log for this message:

Invoked tbMobileReadyHandler

• If missing: The platform isn’t signaling the app that it’s ready. Open an issue in the ThingsBoard platform repository.
• If the log appears but the dashboard still won’t load: Open an issue in the PE mobile repository.

Include credentials to your instance privately via ThingsBoard Support — never post them publicly.

Check the compatibility matrix between your platform and mobile app versions. Mismatches are the most common cause of sign-in issues.

If versions are aligned and you’re still stuck, open an issue in the flutter_thingsboard_pe_app repository and include:

• Platform version
• Mobile app version
• Logs and screenshots
• Device details (OS, version)

Open an issue in the flutter_thingsboard_pe_app repository with as much context as possible: screenshots, logs, versions, and platform setup.