Program a Machine

You can write code to control your machines using the following software development kits (SDKs):

The SDKs provide idiomatic wrappers around Viam’s robot gRPC APIs.

Diagram showing how a client connects to a machine with Viam. Diagram shows a client as a computer sending commands to a machine. Robot 1 then communicates with other robotic parts over gRPC and WebRTC and communicating that information back to the client.

Requirements

Before you get started with your program, ensure that you have installed viam-server on the computer you want to use to control your machine (likely a single-board computer), and configured your machine.

Next, to install your preferred Viam SDK on your Linux or macOS development machine or single-board computer, run one of the following commands in your terminal:

If you are using the Python SDK, set up a virtual environment to package the SDK inside before running your code, avoiding conflicts with other projects or your system.

pip install viam-sdk

If you intend to use the ML (machine learning) model service, use the following command instead, which installs additional required dependencies along with the Python SDK:

pip install 'viam-sdk[mlmodel]'
go get go.viam.com/rdk/robot/client
npm install --save @viamrobotics/sdk
flutter pub add viam_sdk

Hello world: the Code Sample tab

Create a program in the language of your choice to connect to your machine and use methods built into the SDK’s client API libraries to interact with and control the resources on the machine.

Start by navigating to your machine’s page on the Viam app. Select the Code Sample tab, select your preferred SDK, and copy the code generated for you. This code snippet imports all the necessary libraries to set up a connection with your machine and interface with its configured components and services.

Your boilerplate code sample should look similar to this:

Click this to see example boilerplate code from the Code Sample tab

Save this file on your development machine with the file type of your preferred SDK.

The sample code contains the required imports as well as the connect logic which establishes a connection for your client application to communicate with the machine’s viam-server instance. This section of the boilerplate code contains your machine’s address and a placeholder for the API key.

Authenticate

To authenticate yourself to your machine, you need

  1. The machine part’s API key:

    To authenticate, use a machine part API key or an API key with access to the machine. Copy and paste the API key ID and the API key into your environment variables or directly into the code:

    async def connect():
        opts = RobotClient.Options.with_api_key(
            # Replace "<API-KEY>" (including brackets) with your machine's API key
            api_key='<API-KEY>',
            # Replace "<API-KEY-ID>" (including brackets) with your machine's API key
            # ID
            api_key_id='<API-KEY-ID>'
        )
        return await RobotClient.at_address('ADDRESS FROM THE VIAM APP', opts)
    
    robot, err := client.New(
        context.Background(),
        "ADDRESS FROM THE VIAM APP",
        logger,
        client.WithDialOptions(rpc.WithEntityCredentials(
        // Replace "<API-KEY-ID>" (including brackets) with your machine's API key ID
        "<API-KEY-ID>",
        rpc.Credentials{
            Type:    rpc.CredentialsTypeAPIKey,
            // Replace "<API-KEY>" (including brackets) with your machine's API key
            Payload: "<API-KEY>",
        })),
    )
    
    // Replace with the host of your actual machine running Viam.
    const host = "ADDRESS FROM THE VIAM APP";
    
    const robot = await VIAM.createRobotClient({
      host,
      credential: {
        type: "api-key",
        // Replace "<API-KEY>" (including brackets) with your machine's API key
        payload: "<API-KEY>",
      },
      // Replace "<API-KEY-ID>" (including brackets) with your machine's API key ID
      authEntity: "<API-KEY-ID>",
      signalingAddress: "https://app.viam.com:443",
    });
    
    std::string host("ADDRESS FROM THE VIAM APP");
    DialOptions dial_opts;
    dial_opts.set_type("api-key");
    // Replace "<API-KEY-ID>" with your machine's API key ID
    dial_opts.set_entity("<API-KEY-ID>");
    // Replace "<API-KEY>" with your machine's API key
    Credentials credentials("<API-KEY>");
    dial_opts.set_credentials(credentials);
    boost::optional<DialOptions> opts(dial_opts);
    Options options(0, opts);
    
    auto robot = RobotClient::at_address(host, options);
    
    Future<void> connectToViam() async {
      const host = 'ADDRESS FROM THE VIAM APP';
      // Replace '<API-KEY-ID>' (including brackets) with your API key ID
      const apiKeyID = '<API-KEY-ID>';
      // Replace '<API-KEY>' (including brackets) with your API key
      const apiKey = '<API-KEY>';
    
      final robot = await RobotClient.atAddress(
        host,
        RobotClientOptions.withApiKey(apiKeyId, apiKey),
      );
      print(robot.resourceNames);
    }
    
  1. The machine’s remote address:

    Include the address, which resembles 12345.somemachine-main.viam.cloud. The machine address is a public address to connect to your machine. You can find this address at the top of the machine’s Control tab or in the Code sample tab.

Run the sample code

Once you have saved the sample code, execute your program.

You can run your program on any computer which:

  1. has the appropriate SDK installed
  2. can establish a connection to your machine through the cloud, on a local or wide area network (LAN or WAN), or locally

The program will connect to your machine and print a list of the available resources.

Edit the sample code

Once you have successfully run the sample code, you can edit the boilerplate code by adding control logic to make a client application that connects to your machine and controls it in the way you want. You can find the right libraries to import for SDK methods, typing, interfaces, and utilities at the start of each resource’s API documentation, as well as in the individual SDK documentation sites and on GitHub.