If you’re hosting your own ThingsBoard instance (e.g. https://thingsboard.maksonlee.com) and want to run the official mobile app on Android, this guide walks you through everything, from configuring the server to running the app using Flutter on Windows.
Part 1: Create a Mobile App Bundle in ThingsBoard
Before running the mobile app, you must define a Mobile App Bundle in your ThingsBoard server. This bundle tells the app how to log in, which dashboards to load, and how the interface should look.
- Open Mobile Center
- Log in as System Administrator
- Navigate to Mobile center → Bundles
- Click Add bundle
- Basic Bundle Settings
| Field | Value / Description |
|---|---|
| Title | Makson Mobile App |
| Description (optional) | Mobile client for ThingsBoard at maksonlee.com |
- Android Application Configuration
Click Create new under the Android Application section and enter:
| Field | Value / Description |
|---|---|
| Application Package | org.thingsboard.app (or com.makson.tbmobile) |
| Platform Type | Android |
| Application Secret | Auto-generated, save this value |
| Status | Change from Draft to Published |
Click Add, then Next.
- Configure OAuth 2.0
| Field | Value / Description |
|---|---|
| Enable OAuth 2.0 | Enabled |
| OAuth 2.0 Clients | Keycloak Login (select existing) |
Need help setting up Keycloak with ThingsBoard?
See: How to Enable OAuth2 Login in ThingsBoard 4.0.1 CE Using Keycloak and HAProxy
Click Add, then Next.
- Layout
Use the default layout settings provided by ThingsBoard. No changes are needed unless you want to customize dashboard tabs, menus, or mobile actions.
Click Save to complete the mobile app bundle.
Part 2: Build and Run the App
Once the mobile app bundle is ready, you can build and run the ThingsBoard Flutter app on Android using Windows.
- Clone the Mobile App Source Code
git clone https://github.com/thingsboard/flutter_thingsboard_app
cd flutter_thingsboard_pe_app
- Install Flutter Version
Use FVM on Windows to ensure the correct version is installed:
fvm install
- Configure Server Endpoint and Secret
Open:
lib/constants/app_constants.dart
Update the following constants:
const thingsBoardApiEndpoint = 'https://iot.maksonlee.com';
const thingsboardAndroidAppSecret = 'YOUR_APPLICATION_SECRET_HERE';
Replace YOUR_APPLICATION_SECRET_HERE with the actual value copied from your Android app definition in ThingsBoard.
Since we’re using OAuth, and we configured a custom domain iot.maksonlee.com, so we use it here instead of thingsboard.maksonlee.com
Save the file.
- Run the App on Android
You can use either an emulator or a real Android device:
- Start an emulator from Android Studio
or
- Connect a phone with USB debugging enabled
Then run:
fvm flutter clean
fvm flutter run
The app should launch and show the login screen. Log in using your Keycloak OAuth provider or a regular ThingsBoard tenant/customer account.
Java 21 Compatibility Issue
If you encounter the error:
unsupported class file major version 65
This is caused by Flutter or Gradle using Java 21, which is not fully compatible with some Android builds.
Follow this guide to fix it:
Fix Unsupported Class File Major Version 65 in Flutter Android Builds (Java 21 Issue)