Part 3: Control Logic

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

Invoke-WebRequest -Uri "https://storage.googleapis.com/packages.viam.com/apps/viam-cli/viam-cli-stable-windows-amd64.exe" -OutFile "viam.exe"

Then run as .\viam.exe or add the directory to your PATH.

Install Go:

Check your Go version:

go version

You need Go 1.21 or later. If Go isn’t installed or is outdated, download it from go.dev/dl.

Clone the starter repo:

git clone https://github.com/viamrobotics/inspection-module-starter.git
cd inspection-module-starter
go mod tidy

This repo contains a pre-built module with one method left for you to implement.

Open module.go. The key parts:

Config declares the resources your inspector needs—a camera and a vision service:

type Config struct {
    Camera        string `json:"camera"`
    VisionService string `json:"vision"`
}

Validate returns these as dependencies so Viam injects them before creating your service:

func (cfg *Config) Validate(path string) ([]string, []string, error) {
    if cfg.Camera == "" {
        return nil, nil, fmt.Errorf("camera is required")
    }
    if cfg.VisionService == "" {
        return nil, nil, fmt.Errorf("vision is required")
    }
    return []string{cfg.Camera, cfg.VisionService}, nil, nil
}

The first return value from Validate lists dependencies—Viam ensures these resources exist before creating your service.

NewInspector wires the vision service by extracting it from the injected dependencies:

detector, err := vision.FromProvider(deps, cfg.VisionService)

Your code declares what it needs in Config, and Viam provides it through dependency injection. This means the same code works whether dependencies come from a remote machine (during development) or from viam-server (in production).

DoCommand dispatches to detect, the method you’ll implement:

func (s *inspectionModuleInspector) DoCommand(ctx context.Context, cmd map[string]interface{}) (map[string]interface{}, error) {
    if _, ok := cmd["detect"]; ok {
        label, confidence, err := s.detect(ctx)
        if err != nil {
            return nil, err
        }
        return map[string]interface{}{
            "label":      label,
            "confidence": confidence,
        }, nil
    }
    return nil, fmt.Errorf("unknown command: %v", cmd)
}

DoCommand is the public API for generic services. External callers pass a command map, and the method dispatches to internal logic. This pattern keeps implementation details private while exposing a flexible interface.

The stub: detect() currently returns an error:

func (s *inspectionModuleInspector) detect(ctx context.Context) (string, float64, error) {
    return "", 0, fmt.Errorf("not implemented: fill in the detect method")
}

This is what you’ll implement in the next section.

The CLI (cmd/cli/main.go) connects to your remote machine and runs the inspector against it. It:

1. Accepts a -host flag for your machine’s address
2. Uses your viam login credentials to authenticate through vmodutils.ConnectToHostFromCLIToken
3. Converts the machine connection into dependencies your inspector can use
4. Creates an inspector instance and calls DoCommand({"detect": true})

cmd/module/main.go is the module entry point for deployment. When your module runs on the machine, this file registers your service with viam-server. You won’t modify this file.

Open module.go and find the detect method stub. Replace it with:

func (s *inspectionModuleInspector) detect(ctx context.Context) (string, float64, error) {
    detections, err := s.detector.DetectionsFromCamera(ctx, s.cfg.Camera, nil)
    if err != nil {
        return "", 0, err
    }

    if len(detections) == 0 {
        return "NO_DETECTION", 0, nil
    }

    best := detections[0]
    for _, det := range detections[1:] {
        if det.Score() > best.Score() {
            best = det
        }
    }

    return best.Label(), best.Score(), nil
}

DetectionsFromCamera tells the vision service which camera to use. The vision service grabs an image, runs the ML model, and returns structured detection results. The code finds the highest-confidence detection and returns its label and score.

go run ./cmd/cli -host YOUR_MACHINE_ADDRESS

In module.go, add a check after finding the highest-confidence detection. Insert these lines just before the final return in detect:

    // Only report failures — treat PASS as no detection
    if best.Label() != "FAIL" {
        return "NO_DETECTION", 0, nil
    }

Run again:

go run ./cmd/cli -host YOUR_MACHINE_ADDRESS