What This Tool Does

The Amiga Inspector is a field onboarding and diagnostic tool for Bonsai Amiga autonomous tractors. It structures the entire first-visit workflow: capturing farm site data, identifying machine hardware and software, verifying autonomy readiness, and deriving a capabilities assessment with a recommended next action.

It runs entirely in the browser. No server, no login, no internet required after loading. Data persists in your browser's LocalStorage and exports as JSON or Markdown.

Tab Workflow

Onboarding a Machine

Onboarding means establishing the machine's identity, confirming its software version, and creating a baseline snapshot. There are two methods:

Method 1: Manual SSH & Paste

Open System tab → expand Manual SSH. SSH into the brain, run the diagnostic commands, copy the output, paste it into the text area. The Inspector parses the output, auto-populates Machine fields, detects the software generation (2.x or 3.0), and creates a snapshot.

Method 2: Collector Script

Open System tab → expand Collector Script. Download the Python script, run it from your laptop terminal. It SSHs into the brain automatically, collects 25+ diagnostic fields, and saves a JSON file. Import the JSON using the Import Collector JSON button in the System tab's collector section. This method captures more data (WiFi signal, load average, video devices, app manifests, etc.).

Both methods produce the same result: a snapshot in the machine's history. The first snapshot becomes the baseline automatically.

Snapshots, Baselines & Diffs

Every time you paste SSH output or import a collector JSON, a timestamped snapshot is saved. The Overview tab shows:

• Baseline — the first snapshot captured. Locked reference point. Click any snapshot in history to reassign.
• Latest — the most recent snapshot.
• Diff — auto-highlights what changed between baseline and latest (packages added/removed, version changes, network changes).

Snapshots include: software generation, packages, installed apps, hostname, WiFi, disk, memory, load, timezone, uptime, video devices, and more.

Exports

Export Encrypted Workspace (header → Export) saves the complete state: all sites, all machines, all snapshots, all photos, all workflows, issues, and notes. The file is encrypted with your password using AES-256-GCM. You need the same password to import it on another device. Import still accepts plain (unencrypted) JSON files from older exports or collector snapshots.

Machine Report (machine bar) generates a Markdown field report with tables summarizing the selected machine's capabilities, checklist status, and recommendations. Use it for stakeholder communication.

Data auto-saves to browser LocalStorage on every field change. This is browser-specific — always export an encrypted JSON backup before leaving the field.

Photos

Photos are captured directly on the Site Profile tab (field/bed photos) and Machine tab (machine/screen/tool/wiring photos). Images are resized to max 1200px wide, compressed to JPEG quality 0.7, and stored as base64 in the machine record. They export with the JSON.

Each photo gets a caption and tag (machine, screen, tool, field, wiring, other). Storage limit is approximately 5MB total in LocalStorage — roughly 3-5 photos per machine. A warning appears when storage is getting full.

Version Detection

Visual Check

• Brain launcher says farm-ng → V2.x (AmigaOS 2.x)
• Brain launcher says Bonsai or unfamiliar UI → V3.0

Definitive SSH Check

ssh amiga@<robot-ip>
pip list | grep -E 'farm-ng|farm_ng'

• farm-ng-amiga → V2.x
• farm_ng_adk → V3.0

Dashboard → Settings → ID → firmware version provides additional confirmation.

Service Port Maps

V2.x Service Ports (gRPC)

V3.0 Ports (NNG / Nexus)

Teach-and-Repeat (Autoplot)

The primary operational pattern for the Amiga. No code required.

1. Teach: Drive the path manually (teleop or walking with pendant). The Autoplot app records waypoints as a track.
2. Save: Name the track. It persists on the brain.
3. Repeat: Load the saved track in Autoplot. The robot follows the recorded path autonomously.

Requirements: RTK GPS fix (converged filter), saved track, clear path, operator supervising with pendant.

# V2.x track waypoint structure
waypoint.a_from_b.translation = [x, y, 0]
waypoint.a_from_b.rotation = quaternion(heading)

# V3.0 uses Amiga class
from farm_ng.adk import Amiga
amiga = Amiga()
# Track operations via amiga.track_follower

Tool Control

The Amiga controls implements via CAN bus. Two primary mechanisms:

• H-Bridge outputs: Bidirectional motor control for powered implements (e.g., finger weeders, rotary tools). Controlled via canbus service.
• PTO (Power Take-Off): Continuous rotational power for compatible implements.

Tool engagement and disengagement can be tied to track lifecycle events (start, end) or triggered manually via pendant.

# V2.x gRPC tool control
from farm_ng.canbus import canbus_pb2
from farm_ng.core.events_file_reader import proto_from_json_file

# Connect to canbus service
channel = grpc.insecure_channel('localhost:6001')

# Send tool control command
# H-bridge duty cycle: -1.0 to 1.0
# PTO RPM: 0 to max

# V3.0 NNG tool control
from farm_ng.adk import Amiga

amiga = Amiga()
# Tool control via amiga.canbus
# Uses NNG request socket on port 54388
# H-bridge and PTO commands through Nexus API

Track Follower Failure Modes

Common reasons the robot stops or deviates during autonomous replay:

USB Serial Console — Validate Onsite

Status: unverified — check on first visit.

The Amiga brain uses a Jetson module (Xavier NX or Orin). Jetson hardware includes a micro-USB or USB-C debug port that provides UART serial console access. If physically accessible on the Amiga, this would provide a fallback shell connection without WiFi.

What to check onsite

• Is there an exposed micro-USB or USB-C debug port on the brain enclosure?
• Does connecting a USB cable from your laptop to that port create a serial device? (Mac: check ls /dev/tty.usb*)
• Can you open a console? Try: screen /dev/tty.usbmodem* 115200
• If a shell appears, run whoami and hostname to confirm access

If USB serial works

• Pre-WiFi access: get a shell before knowing the IP or configuring WiFi
• Recovery: access the brain when WiFi or SSH is broken
• Same diagnostics: all Layer 1 commands work the same through serial as through SSH

What would NOT work over USB serial

• The collector Python script (uses SSH subprocess, not serial)
• Network-dependent checks (internet reachability, NTRIP)

If validated, a USB Serial method could be added to the System tab as a third onboarding path alongside Manual SSH and Collector Script.

Battery & Safety

• Operating range: Do not run below 20% SOC. Performance degrades below 15%.
• Charging: Use the supplied charger only. Charge in a ventilated area.
• E-Stop: Red mushroom button on pendant. Always keep pendant in hand during autonomous operation.
• Transport: Power off, engage parking brake, secure on trailer.
• Weather: Avoid operation in heavy rain. Electronics are water-resistant, not waterproof. Mud buildup on wheels affects traction and tracking accuracy.

# Connect to a V2.x service
from farm_ng.core.event_client import EventClient
from farm_ng.core.event_service_pb2 import EventServiceConfig

config = EventServiceConfig(
    name="canbus",
    port=6001
)
client = EventClient(config)

# Subscribe to canbus state
async for event, msg in client.subscribe(
    SubscribeRequest(
        uri=Uri(path="/state"),
        every_n=1
    )
):
    state = msg  # AmigaRpdo1 proto
    print(f"Speed: {state.meas_speed}")

# Connect to a V3.0 Amiga
from farm_ng.adk import Amiga

amiga = Amiga()

# Three NNG sockets:
# Request (54388) - send commands
# Feedback (54389) - receive state
# Stream (54390) - high-bandwidth data

# Get robot state
state = await amiga.get_state()
print(f"Control: {state.control_state}")
print(f"Speed: {state.measured_speed}")