Create a Viam application

Create and deploy a custom web interface for your machines without managing hosting infrastructure and authentication. Once deployed, your application is accessible from a dedicated URL (appname_publicnamespace.viamapplications.com), and Viam handles hosting and authentication.

Users log in and the application then renders your custom interface for interacting with the user’s machines. You can choose to build an application that can access and operate a single-machine or multiple machines.

Requirements

brew tap viamrobotics/brews
brew install viam

sudo curl -o /usr/local/bin/viam https://storage.googleapis.com/packages.viam.com/apps/viam-cli/viam-cli-stable-linux-arm64
sudo chmod a+rx /usr/local/bin/viam

sudo curl -o /usr/local/bin/viam https://storage.googleapis.com/packages.viam.com/apps/viam-cli/viam-cli-stable-linux-amd64
sudo chmod a+rx /usr/local/bin/viam

brew tap viamrobotics/brews
brew install viam

go install go.viam.com/rdk/cli/viam@latest

echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.bashrc

viam login

viam login api-key --key-id <api-key-id> --key <organization-api-key-secret>

Build a custom web interface

You can build a custom web interface to access your machines using your preferred framework like React, Vue, Angular, or others.

import * as VIAM from "@viamrobotics/sdk";
import Cookies from "js-cookie";

let apiKeyId = "";
let apiKeySecret = "";
let host = "";
let machineId = "";

async function main() {
  const opts: VIAM.ViamClientOptions = {
    serviceHost: "https://app.viam.com",
    credentials: {
      type: "api-key",
      payload: apiKeySecret,
      authEntity: apiKeyId,
    },
  };

  const client = await VIAM.createViamClient(opts);
  const machine = await client.appClient.getRobot(machineId);
}

document.addEventListener("DOMContentLoaded", async () => {
  // Extract the machine identifier from the URL
  let machineCookieKey = window.location.pathname.split("/")[2];
  ({
    apiKey: { id: apiKeyId, key: apiKeySecret },
    machineId: machineId,
    hostname: host,
  } = JSON.parse(Cookies.get(machineCookieKey)!));

  main().catch((error) => {
    console.error("encountered an error:", error);
  });
});

import * as VIAM from "@viamrobotics/sdk";
import Cookies from "js-cookie";

let access_token = "";
// optionally specify a fragmentID to use with the listMachineSummaries API call
let fragmentID = "";

async function main() {
  const opts: VIAM.ViamClientOptions = {
    serviceHost: "https://app.viam.com",
    credentials: {
      type: "access-token",
      payload: access_token,
    },
  };

  const client = await VIAM.createViamClient(opts);
  const locationSummaries = await client.appClient.listMachineSummaries("", [
    fragmentID,
  ]);
}

document.addEventListener("DOMContentLoaded", async () => {
  const userTokenRawCookie = Cookies.get("userToken")!;
  const startIndex = userTokenRawCookie.indexOf("{");
  const endIndex = userTokenRawCookie.indexOf("}");
  const userTokenValue = userTokenRawCookie.slice(startIndex, endIndex + 1);
  access_token = JSON.parse(userTokenValue).access_token;

  main().catch((error) => {
    console.error("encountered an error:", error);
  });
});

Local development

For developing your application on localhost:

1. Run your web server. Take note of its port number for the next step.

2. Run the following commands specifying the address where your app is running on localhost and a machine to test on.

   • Single-machine application
   • Multi-machine application

   The command will proxy your local app and open a browser window and navigate to http://localhost:8012/machine/<machineHostname> for the machine provided with –machine-id.

   • Template
   • Example

   viam login
   viam module local-app-testing --app-url http://localhost:<PORT-YOUR-WEB-SERVER-IS-ON> --machine-id <MACHINE-ID>
   

   viam login
   viam module local-app-testing --app-url http://localhost:3000 --machine-id a1b2c3d4-e5f6-7890-abcd-ef1234567890
   

   The command will proxy your local app and open a browser window and navigate to http://localhost:8012/.

   • Template
   • Example

   viam login
   viam module local-app-testing --app-url http://localhost:<PORT>
   

   viam login
   viam module local-app-testing --app-url http://localhost:3000
   

Deploy your web interface

To deploy your web interface with Viam, you must create a FILE>meta.json file and package it with yoru web application as a module.

{
  "module_id": "your-namespace:your-module",
  "visibility": "public",
  "url": "https://github.com/your-org/your-repo",
  "description": "Your module description",
  "applications": [
    {
      "name": "your-app-name",
      "type": "single_machine|multi_machine",
      "entrypoint": "dist/index.html",
      "fragmentIds": [],
      "logoPath": "static/logo.png",
      "customizations": {
        "machinePicker": {
          "heading": "Heading to display on branded authentication page",
          "subheading": "Subheading to display on branded authentication page"
        }
      }
    }
  ]
}

{
  "module_id": "acme:dashboard",
  "visibility": "public",
  "url": "https://github.com/acme/dashboard",
  "description": "An example dashboard for a fictitious air quality company called acme.",
  "applications": [
    {
      "name": "dashboard",
      "type": "single_machine",
      "entrypoint": "dist/index.html",
      "fragmentIds": [],
      "logoPath": "static/logo.png",
      "customizations": {
        "machinePicker": {
          "heading": "Air monitoring dashboard",
          "subheading": "Sign in and select your devices to view your air quality metrics in a dashboard."
        }
      }
    }
  ]
}

viam module create --name="app-name" --public-namespace="namespace"

viam module create --name="air-quality" --public-namespace="naomi"

tar -czvf module.tar.gz <static-website-files> meta.json
viam module upload --upload=module.tar.gz --platform=any --version=0.0.1

Access your application

After uploading your module with the application configuration, your application will be available at:

https://your-app-name_your-public-namespace.viamapplications.com

Users will be prompted to authenticate with their Viam credentials before accessing your application:

1. User navigates to your-app-name_your-public-namespace.viamapplications.com.
2. User authenticates with Viam credentials.
3. For single-machine applications, the user selects an organization, location, and machine and is redirected to your-app-name_your-public-namespace.viamapplications.com/machine/<machineHostname>. For multi-machine applications, the user is redirected to your-app-name_your-public-namespace.viamapplications.com/.
4. Your application is rendered with access to the selected machine. The credentials for that one machine are provided in the cookies.

Examples

• For a multi-machine TypeScript application see Monitor Air Quality with a Fleet of Sensors.

• For a single-machine React application that shows camera feeds for a machine, see Viam Camera Viewer.

Limitations

• All modules with applications must have public visibility.
• The page will always render the latest version.
• Browsers with cookies disabled are not supported.
• Viam applications serve static files. If you are building an application with server-side rendering or need other back-end capabilities, Viam applications is not the right choice.

Security considerations

• Customer applications are stored publicly on the internet, so avoid uploading sensitive information in your application code or assets.
• API keys and secrets are stored in the browser’s cookies.
• Users authenticate with FusionAuth.

FAQ

Can I use a custom domain?

Viam does not currently support using custom domains (for example: app.mycustomdomain.com/machine/<machineHostname>) to serve your Viam application. You can, however, redirect from your domain to your Viam application (app.mycustomdomain.com -> your-app-name_your-public-namespace.viamapplications.com). You can configure a redirect (HTTP 301) on your web server or hosting provider from app.mycustomdomain.com/* to your-app-name_your-public-namespace.viamapplications.com/*.