# Build a Flutter App that Integrates with Viam

Flutter is Google’s user interface toolkit for building applications for mobile, web, and desktop from a single codebase. If you’re looking to monitor and control individual machines with the same functionality you have on the [**CONTROL** tab](https://docs.viam.com/monitor/default-interface/#web-ui), you can use the general-purpose [Viam mobile app](https://docs.viam.com/monitor/default-interface/#viam-mobile-app) rather than creating your own. If you need custom functionality or a custom interface, you can use Viam’s [Flutter SDK](https://flutter.viam.dev/) to build a custom app to interact with your machines that run on Viam.

This tutorial guides you through creating a mobile app that shows your machines and their components. As you work through this project you will learn the following:

- Flutter development basics  
- How to trigger app behavior when a user presses a button  
- The basics of using Viam’s Flutter SDK

## Requirements

You do not need any hardware for this tutorial other than a computer capable of running [`viam-server`](https://docs.viam.com/set-up-a-machine/first-machine/).

This tutorial assumes you already have a machine [configured](https://docs.viam.com/set-up-a-machine/first-machine/).

## Set up your Flutter development environment

This tutorial uses [Visual Studio Code](https://code.visualstudio.com/download) (VS Code) as the development environment (IDE), and uses the VS Code [Flutter extension](https://marketplace.visualstudio.com/items?itemName=Dart-Code.flutter) to generate sample project code. You can use a different editor, but it will be much easier to follow along using VS Code.

### Platform compatibility

Flutter can compile and run on many different operating systems. For this tutorial, you will be developing for iOS. In other words, iOS is your development _target_.

You can always run your app on another platform later by configuring the code specific to that target.

### Install Flutter

Install Flutter according to [the Flutter documentation](https://docs.flutter.dev/get-started/install). Those instructions include installation of various tools and extensions for different development targets. For this walkthrough, you only need to install the following:

- Flutter SDK  
- Visual Studio Code with the [Flutter extension](https://marketplace.visualstudio.com/items?itemName=Dart-Code.flutter)  
- [Xcode](https://developer.apple.com/xcode/), which is required for developing for iOS  
  - When prompted, do install Cocoapods.  
    You need it to support the iOS simulator.

#### Flutter version

We recommend using Flutter 3.19.6, as this sample app was tested with this version. `fvm` is a useful tool for targeting specific flutter versions. You can run `fvm use 3.19.6` in the terminal before building your sample app to target Flutter 3.19.6.

## Start creating code

### Create your Flutter project

1. Launch VS Code.  
   Open the [command palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette) by pressing `Ctrl+Shift+P` or `Shift+Cmd+P`, depending on your system.

2. Start typing “flutter new.”  
   Click the **Flutter: New Project** command when it populates.

3. Click **Application**, then choose a folder in which to create your project.  
4. Give your project a name, for example, smart\_machine\_app.  
   Naming it smart\_machine\_app will make it slightly easier to follow along in later steps.

When you hit **Enter**, Flutter auto-generates a project folder with a useful starter project. VS Code automatically opens it.

If you don’t change any of the code files, you’ll have a counter app with a button that adds one to the total each time you press it. That’s not going to be very helpful for interacting with your fleet of machines, so in the next steps, you’ll edit three of these automatically-created files to start building out a Viam-integrated app.

### Edit the YAML configuration files

1. In the VS Code file explorer, find and open the pubspec.yaml file.  
   This file specifies your app’s metadata including its current version and dependencies.

2. Delete the contents of your pubspec.yaml file and replace them with the following configuration which, among others, specifies the `viam_sdk` as a dependency for your project:

```yaml

```

#### Note

If you named your app something other than `smart_machine_app`, change the `name` value in the first line of the pubspec.yaml file to the name you gave your app during setup.

3. Next, open the analysis\_options.yaml configuration file.  
   This file specifies how strictly Flutter should enforce best practices in your code when it checks for things like syntax errors.  
   For this tutorial, you will use a less strict analyzer configuration to start, but you can always tune this later.  
   If you later publish an actual production app, you will likely want to increase the strictness of the analyzer before sharing your app with others.

4. Replace the contents of the analysis\_options.yaml file with the following:

```yaml

```

### Configure iOS-specific code

Now you’ll update some configurations in the iOS-specific code to support the [Viam Flutter SDK](https://flutter.viam.dev/).

1. Open ios/Podfile.  
   If Podfile does not exist in that directory, generate it by running `flutter pub get` in the root directory of your app.  
   If the `flutter pub get` command returns an error, you may need to [upgrade the Flutter SDK](https://docs.flutter.dev/release/upgrade).

At the top of the file you will see the following lines:

```dart

```

2. Open ios/Runner/Info.plist.  
   It will look something like this:

3. Insert the following code into the first line after the `<dict>`.  
   These lines are [required to establish WebRTC and local device mDNS connections](https://github.com/viamrobotics/viam-flutter-sdk?tab=readme-ov-file#update-infoplist).

```xml

```

### Edit the main file

1. Open the lib/main.dart file.

2. Replace the contents of this file with the following code, which creates the scaffold of your app’s login screen:

```dart

```

If you chose a name other than `Smart Machine App` for your project, edit lines 15 and 32 with your own app title.

### Launch the app

You now have enough of your new app coded to be able to build and test a rendering of it.

Follow the steps below to build and preview the current state of your app.

1. Open lib/main.dart.  
   In the bottom right corner of VS Code, find the button that shows the current target device.  
   Click the button to change your target device.
   Make sure that you have your target device selected before you continue.

2. With lib/main.dart still open, find the “Start Debugging” button in the upper right corner of the VS Code window.  
   Click the button to build and render your app.
   
   A window should open up, displaying a rendering of your smart machine app:

## Add app navigation

### Add a new screen

Great work so far! Your app is successfully running, with a single screen and an inactive button. Next, you will add a new screen that pulls in some information from your organization. This new screen will be accessed from the login button.

In the VS Code file explorer on the left-hand side, right click lib/ and click **New File**, then name the new file home\_screen.dart.

Paste the following code into the home\_screen.dart file you just created:

```dart

```

### Get the Viam API key

Notice in the file the following line:

```dart

```

This line in the code defines how your Flutter app authenticates to the Viam platform, by referencing two environment variables that together comprise your Viam API key.

Follow the steps below to get your API key and create an environment variables file to store them in:

1. In your project folder, create a file to store your API keys.  
   Name it .env.  
   Copy and paste these two lines into the file:

```sh

```

2. Log into [Viam](https://app.viam.com/).

3. Click the organization dropdown menu on the right side of the top banner.  
   If you’re not already in the organization you want to connect to, click the correct organization name to navigate to it.

4. Click the organization dropdown menu again and click **Settings**.

5. Scroll to the **API Keys** section.  
   You can find and use an existing API key for your smart machine, or you can create a new one for this application.  
   To create a new one:
   1. Click **Generate key**.
   2. Give the key a name like “flutter-app-my-org-name.”
   3. Click the **Entity** dropdown and select your organization.
   4. Set **Role** to **Owner**.
   5. Click **Generate key**.
   6. Find your new key at the bottom of the list.  
   6. Use the copy buttons next to the API key ID and API key to copy each of them and paste them into your .env file.

#### Caution: Keep your API key safe

We strongly recommend that you add your API key as an environment variable.  
   Anyone with your API key can access your machine, and the computer running your machine.

7. In your lib/main.dart, find line 5:

```dart
     void main() async {
         // await dotenv.load(); // <-- This loads your API key; will un-comment later
         runApp(MyApp());
     }
```

Now that you have a .env file to load, un-comment that line so it loads the file.  
   Your `main()` function should look like this:

```dart
     void main() async {
         await dotenv.load(); // <-- This loads your API key
         runApp(MyApp());
     }
```

8. Reopen your pubspec.yaml file and paste the following two lines at the end of it, inside the `flutter:` section.  
   Listing the .env among your app’s assets lets the app access the file.

```yaml
assets:
  - .env
```

### Connect the login button to the home screen

In VS Code, reopen main.dart.

Add the following line to the imports at the top of the file:

```dart

```

Change `ElevatedButton` in the `Column` to the following:

```dart

```

Run the mobile application simulator again to see how your changes have taken effect.  
   Now, when you tap the login button, the app uses the API key to get the list of locations in your organization.  
   It displays the names of the locations on a new screen:

## Add more screens

### Add a location screen

At this point, you have an app that displays a list of locations, but nothing happens when you tap a location name.  
   In this step you will add functionality so that tapping a location name brings you to the list of smart machines in that location.
   In VS Code create a new file in the same folder as main.dart and home\_screen.dart.  
   Name it location\_screen.dart.

Paste the following code into the file:

```dart

```

### Add a robot screen

Create a new file named robot\_screen.dart and paste the following into the file:

```dart

```

### Connect the screens together

Now that you have the code for the screens in place, you can enable navigation between them.

Connect the home screen to the locations screen by un-commenting the following two lines in home\_screen.dart:

```dart

```

Add the following import to the top of the file:

```dart

```

## Next steps

Nice work! You have successfully made a Flutter app integrated with Viam!

At this point you could customize the robot screen to have more functionality to control the machine or to show data from the robot in neat ways.  
   The Viam Flutter SDK GitHub repo contains [more example apps](https://github.com/viamrobotics/viam-flutter-sdk/tree/main/example) for your reference.

You can also stylize the look and feel of your app to match your brand.  
   Look around [the Flutter documentation](https://docs.flutter.dev/) to learn how.

If you’re planning to release your app for general use, you will need to add an authentication flow to your app instead of adding API keys as environment variables.  
   If you need assistance with this, reach out to us on our [Discord](https://discord.gg/viam) and we’ll be happy to help.

When you’re ready to publish your app to the app stores you can follow these articles from Flutter on the subject:

- [iOS](https://docs.flutter.dev/deployment/ios)  
- [Android](https://docs.flutter.dev/deployment/android)