Write an inline module

Viam provides built-in support for many types of hardware and software, but you may want to use hardware that Viam doesn’t support out of the box, or add application-specific logic. Modules let you add that support yourself.

An inline module is the fastest way to get started. You write your module code directly in the Viam app’s browser-based editor – no IDE, terminal, or GitHub account required. When you click Save & Deploy, Viam builds your module in the cloud and deploys it to your machine automatically.

Inline modules implement the Generic service API – a single DoCommand method for arbitrary control logic. To write a hardware driver or use a more specific API, see Write a driver module or Write a logic module.

For background on inline modules, how they compare to externally managed modules, and the Generic service API, see the overview.

To illustrate each step, this page uses a distance-responsive servo controller as a worked example – a service that reads an ultrasonic sensor and adjusts a servo angle based on distance. The same patterns apply to any control logic; substitute your own attributes, dependencies, and command behavior.

Steps

1. Create the module

1. In the Viam app, navigate to your machine’s CONFIGURE tab.
2. Click + and select Control code.
3. In the “Choose where to host your code” dialog, select Viam-hosted and click Choose.
4. Name your module (for example, servo-distance-control) and choose a language (Python or Go).
5. Click Create module.

You can also reach this dialog from your machine’s CONNECT tab by selecting Control code sample from the sidebar and clicking Create inline module. Both paths open the same dialog and land you in the same editor.

The browser opens the code editor with a working template that includes all necessary imports and method stubs.

2. Understand the template

The editor opens a single file – your module’s main source file. The template includes three methods you need to fill in:

class MyGenericService(GenericService, EasyResource):
    MODEL: ClassVar[Model] = Model(
        ModelFamily("my-org", "servo-distance-control"), "generic-service"
    )

var (
    GenericService   = resource.NewModel("my-org", "servo-distance-control", "generic-service")
    errUnimplemented = errors.New("unimplemented")
)

func init() {
    resource.RegisterService(genericservice.API, GenericService,
        resource.Registration[resource.Resource, *Config]{
            Constructor: newGenericService,
        },
    )
}

3. Implement validate_config

The validate method runs every time the machine configuration changes. It checks that the attributes passed to your service are valid and declares dependencies on other components or services.

This example validates attributes for a distance-responsive servo controller – a service that reads an ultrasonic sensor and adjusts a servo angle based on distance.

For this example, we use:

• sensor_range_start – lowest expected sensor reading, in meters. Required.
• sensor_range_end – highest expected sensor reading, in meters. Required.
• servo_angle_min – servo angle at the low end of the sensor range, in degrees. Optional; defaults to 0.
• servo_angle_max – servo angle at the high end of the sensor range, in degrees. Optional; defaults to 180.
• reversed – if true, map the low sensor reading to the high servo angle. Optional; defaults to false.
• servo – name of the servo component the service controls. Required.
• sensor – name of the distance sensor the service reads. Required.

@classmethod
def validate_config(
    cls, config: ComponentConfig
) -> Tuple[Sequence[str], Sequence[str]]:
    attrs = struct_to_dict(config.attributes)

    # Required numeric attributes
    sensor_range_start = attrs.get("sensor_range_start")
    if sensor_range_start is None or not isinstance(
        sensor_range_start, (int, float)
    ):
        raise ValueError(
            "attribute 'sensor_range_start' is required "
            "and must be an int or float value"
        )

    sensor_range_end = attrs.get("sensor_range_end")
    if sensor_range_end is None or not isinstance(
        sensor_range_end, (int, float)
    ):
        raise ValueError(
            "attribute 'sensor_range_end' is required "
            "and must be an int or float value"
        )

    # Required dependency attributes
    required_deps: List[str] = []

    servo_name = attrs.get("servo")
    if not isinstance(servo_name, str) or not servo_name:
        raise ValueError(
            "attribute 'servo' (non-empty string) is required"
        )
    required_deps.append(servo_name)

    sensor_name = attrs.get("sensor")
    if not isinstance(sensor_name, str) or not sensor_name:
        raise ValueError(
            "attribute 'sensor' (non-empty string) is required"
        )
    required_deps.append(sensor_name)

    return required_deps, []

type Config struct {
    SensorRangeStart float64 `json:"sensor_range_start"`
    SensorRangeEnd   float64 `json:"sensor_range_end"`
    ServoAngleMin    *int64  `json:"servo_angle_min"`
    ServoAngleMax    *int64  `json:"servo_angle_max"`
    Reversed         *bool   `json:"reversed"`
    Servo            string  `json:"servo"`
    Sensor           string  `json:"sensor"`
}

func (cfg *Config) Validate(path string) ([]string, []string, error) {
    if cfg.SensorRangeStart == 0 {
        return nil, nil, fmt.Errorf(
            "%s: 'sensor_range_start' is required and must be non-zero",
            path,
        )
    }
    if cfg.SensorRangeEnd == 0 {
        return nil, nil, fmt.Errorf(
            "%s: 'sensor_range_end' is required and must be non-zero",
            path,
        )
    }

    requiredDeps := []string{}
    if cfg.Servo == "" {
        return nil, nil, fmt.Errorf(
            "%s: 'servo' (non-empty string) is required", path,
        )
    }
    requiredDeps = append(requiredDeps, cfg.Servo)

    if cfg.Sensor == "" {
        return nil, nil, fmt.Errorf(
            "%s: 'sensor' (non-empty string) is required", path,
        )
    }
    requiredDeps = append(requiredDeps, cfg.Sensor)

    return requiredDeps, []string{}, nil
}

4. Implement the constructor

The constructor runs when the service is first created and again whenever its configuration changes. Use it to parse attributes and resolve dependencies.

@classmethod
def new(
    cls, config: ComponentConfig,
    dependencies: Mapping[ResourceName, ResourceBase]
) -> Self:
    self = super().new(config, dependencies)
    attrs = struct_to_dict(config.attributes)

    # Required attributes
    self.sensor_range_start = float(attrs.get("sensor_range_start"))
    self.sensor_range_end = float(attrs.get("sensor_range_end"))

    # Optional attributes with defaults
    self.servo_angle_min = float(attrs.get("servo_angle_min", 0))
    self.servo_angle_max = float(attrs.get("servo_angle_max", 180))
    self.reversed = attrs.get("reversed", False)

    # Resolve dependencies
    servo_name = attrs.get("servo")
    sensor_name = attrs.get("sensor")
    self.servo = dependencies[Servo.get_resource_name(servo_name)]
    self.sensor = dependencies[Sensor.get_resource_name(sensor_name)]

    return self

func NewGenericService(
    ctx context.Context, deps resource.Dependencies,
    name resource.Name, conf *Config, logger logging.Logger,
) (resource.Resource, error) {
    cancelCtx, cancelFunc := context.WithCancel(context.Background())

    // Apply defaults for optional fields
    servoAngleMin := int64(0)
    if conf.ServoAngleMin != nil {
        servoAngleMin = *conf.ServoAngleMin
    }
    servoAngleMax := int64(180)
    if conf.ServoAngleMax != nil {
        servoAngleMax = *conf.ServoAngleMax
    }
    reversed := false
    if conf.Reversed != nil {
        reversed = *conf.Reversed
    }

    // Resolve dependencies
    servoDep, err := servo.FromProvider(deps, conf.Servo)
    if err != nil {
        return nil, err
    }
    sensorDep, err := sensor.FromProvider(deps, conf.Sensor)
    if err != nil {
        return nil, err
    }

    return &genericService{
        name:             name,
        logger:           logger,
        cfg:              conf,
        cancelCtx:        cancelCtx,
        cancelFunc:       cancelFunc,
        servo:            servoDep,
        sensor:           sensorDep,
        sensorRangeStart: conf.SensorRangeStart,
        sensorRangeEnd:   conf.SensorRangeEnd,
        servoAngleMin:    servoAngleMin,
        servoAngleMax:    servoAngleMax,
        reversed:         reversed,
    }, nil
}

5. Implement DoCommand

DoCommand is where your control logic goes. This example reads a distance sensor and maps the reading to a servo angle:

async def do_command(
    self, command: Mapping[str, ValueTypes], *,
    timeout: Optional[float] = None, **kwargs
) -> Mapping[str, ValueTypes]:
    readings = await self.sensor.get_readings()
    if not readings:
        raise ValueError("No sensor readings available")

    value = next(iter(readings.values()))

    # Map sensor range to servo angle range
    t = (value - self.sensor_range_start) / (
        self.sensor_range_end - self.sensor_range_start
    )
    t = max(0.0, min(1.0, 1.0 - t if self.reversed else t))

    angle = self.servo_angle_min + t * (
        self.servo_angle_max - self.servo_angle_min
    )
    await self.servo.move(int(angle))

    return {"servo_angle_deg": angle}

func (s *genericService) DoCommand(
    ctx context.Context, cmd map[string]interface{},
) (map[string]interface{}, error) {
    readings, _ := s.sensor.Readings(ctx, nil)
    value, ok := readings["distance"].(float64)
    if !ok {
        return nil, fmt.Errorf("sensor reading 'distance' must be a float64")
    }

    // Map sensor range to servo angle range
    t := (value - s.sensorRangeStart) /
        (s.sensorRangeEnd - s.sensorRangeStart)
    if t < 0 { t = 0 } else if t > 1 { t = 1 }
    if s.reversed { t = 1 - t }

    angle := float64(s.servoAngleMin) +
        t * (float64(s.servoAngleMax) - float64(s.servoAngleMin))
    return map[string]interface{}{
        "servo_angle_deg": angle,
    }, s.servo.Move(ctx, uint32(angle), nil)
}

In this example no DoCommand payload is used. You can use the command payload to customize behavior per invocation. Attributes are constant across all invocations; the DoCommand payload can vary with each call.

6. Save and deploy

1. Click Save & Deploy in the code editor toolbar.
2. Viam uploads your code as a new version and starts a cloud build.
3. Builds typically take 2-5 minutes. You can continue editing while a build runs – your next save creates a new version.
4. If the build fails, click View Logs to see what went wrong.

Each save creates a new version in your module’s history. You can switch between versions using the version dropdown in the editor toolbar.

7. Test on a machine

Add the module to a machine

1. In the code editor, click Add to machine.
2. Select a location, machine, and part.
3. Click Add.

The Viam app navigates you to the machine’s CONFIGURE tab with your module added.

Configure the service

1. In the module section, click Add to add a model of your generic service.
2. If your service depends on any hardware that isn’t already configured on the machine, add those components now. Click the + icon next to your machine part’s name in the left sidebar and follow Configure hardware components to pick a model and set attributes. The service references components by the names you give them.
3. Configure the attributes for your generic service:

{
  "sensor_range_start": 0.05,
  "sensor_range_end": 0.3,
  "servo_angle_min": 40,
  "servo_angle_max": 270,
  "reversed": true,
  "servo": "servo-1",
  "sensor": "sensor-1"
}

4. Click Save.

Send test commands

1. On the CONFIGURE tab, expand your generic service’s Test section.
2. Expand DoCommand.
3. Enter a command (or an empty map {} if your DoCommand does not use the payload):

{}

4. Click Execute. You should see a response like:

{ "servo_angle_deg": 155.0 }

8. Automate with a scheduled job

The DoCommand section in the Viam app runs your logic once per click. To have it run automatically:

1. Click + and select Job.
2. Name the job and click Create.
3. Choose a schedule. For control logic that should always run, select Continuous.
4. Select your generic service as the resource.
5. Edit the DoCommand payload or leave it as an empty map if no payload is needed.
6. Click Save.

Try It

1. Create a new inline module from the + menu.
2. Implement validate_config, the constructor, and do_command.
3. Click Save & Deploy and wait for the build to complete.
4. Add the module to a machine and configure the service with dependencies.
5. Execute a DoCommand and verify the response.
6. Set up a scheduled job to run the logic continuously.

Troubleshooting

What’s Next

• Write a Driver Module – build a module with a typed resource API when you need to manage your own source code and build pipeline.
• Write a Logic Module – build control logic as an externally managed module with full IDE support.
• Deploy a Module – package and upload a module to the Viam registry for distribution to other machines or users.