Farmos Equipment

---

name: farmos-equipment description: Query equipment status, maintenance schedules, and service history for the farm fleet. Uses integration endpoints (no auth required). tags: [farming, equipment, maintenance]

---

FarmOS Equipment

Query and manage farm equipment data — status, maintenance schedules, service records, and parts inventory.

When to Use This

What this skill handles: Fleet status, maintenance schedules, equipment issues, hour/mileage logging, service manual lookups, parts questions, and maintenance completion records.

Trigger phrases: "the [machine] is...", "equipment status", "log hours on...", "maintenance due", "what equipment needs service?", "search equipment manuals for...", "what oil does the 8370R take?"

What this does NOT handle: Field observations about crop/soil/pest issues (use farmos-observations), scheduling repairs for people or assigning work (create a task via farmos-tasks), weather damage reports (use farmos-observations with weather_damage type).

Minimum viable input: A machine name or description of an equipment issue. "The combine sounds funny" is enough.

API Base

http://100.102.77.110:8005

Data Completeness Rules

CRITICAL: Always return complete data, never truncated results.

1. Dashboard endpoint is for SUMMARY STATS ONLY — use /api/integration/dashboard for counts and overdue items, NOT for listing equipment. 2. For listing equipment, use /api/integration/equipment which returns ALL equipment without pagination. 3. For due maintenance, use /api/integration/due-maintenance which returns ALL due/overdue items. 4. Always state the total count of items returned: "Found 3 overdue maintenance items" (not just "overdue items:"). 5. If suspiciously few results, flag it: "Only seeing X items — that may be incomplete. Let me try a different endpoint." 6. If an endpoint fails, report the failure to the user rather than silently falling back to partial data.

Integration Endpoints (No Auth Required)

Dashboard Summary

GET /api/integration/dashboard

Returns: Equipment counts, maintenance stats, overdue items.

Use for: Summary statistics and counts ONLY. Do NOT use for listing equipment or maintenance items.

Equipment List

GET /api/integration/equipment

Returns: All equipment with id, name, make, model, type, status, current_hours.

Use for: Complete equipment listing. This endpoint returns ALL equipment without truncation.

Use this to look up equipment IDs for other queries.

Equipment Detail

GET /api/integration/equipment/{id}/summary

Returns: Full equipment summary including maintenance history, upcoming service, documents.

Due Maintenance

GET /api/integration/due-maintenance

Returns: List of maintenance items that are due or overdue, including:

schedule_id, equipment_id, equipment_name

maintenance_name, priority (low/normal/high/critical)

trigger_type (hours/calendar/seasonal)

hours_overdue or days_overdue

estimated_duration_minutes

parts_required list

Use for: Complete list of ALL due/overdue maintenance. Returns all items without truncation.

Record Maintenance Completion

POST /api/integration/record-completion Content-Type: application/json

Body:

{
  "schedule_id": 1,
  "equipment_id": 5,
  "performed_at": "2026-02-13T10:00:00Z",
  "performed_by": "user_name",
  "equipment_hours": 1250,
  "work_performed": "Changed engine oil and filter",
  "parts_used": [],
  "task_id": null
}

Use this when someone reports maintenance was done.

Semantic Search (Service Documents)

POST /api/integration/search Content-Type: application/json

Body:

{
  "query": "hydraulic fluid capacity 8370R",
  "limit": 5
}

Returns: Relevant chunks from service manuals and parts catalogs with similarity scores. Use this for technical questions about equipment specs, procedures, and parts.

RAG Q&A

POST /api/integration/ask Content-Type: application/json

Body:

{
  "question": "What oil does the 8370R take?"
}

Returns: AI-generated answer sourced from service documents. Use for natural language equipment questions.

Regular API Endpoints

These endpoints provide additional functionality:

Equipment CRUD

GET /api/equipment — List with pagination and filters (?equipment_type=tractor&status=active&search=deere) GET /api/equipment/{id} — Full detail POST /api/equipment/{id}/hours — Log hour meter reading: {"hours": 1500, "recorded_at": "2026-02-13"}

Maintenance

GET /api/maintenance/due — Detailed due maintenance list GET /api/schedules — All maintenance schedules GET /api/maintenance — Maintenance history records

Usage Notes

Equipment IDs are integers. Use the equipment list to find IDs by name.

Hour-based maintenance triggers when current_hours >= due_at_hours.

Calendar-based maintenance triggers on date.

Priority levels: low, normal, high, critical. Flag "critical" items prominently.

When reporting maintenance status, always mention overdue items first.

The RAG search endpoints can answer technical questions from uploaded service manuals.

Conversational Equipment Issue Intake

When crew reports an equipment problem -- even vaguely -- capture it. "The combine sounds funny" is a valid starting point. Your job is to guide toward useful detail without interrogating.

Symptom Detection

Auto-detect from the message what you can:

Sound symptoms (map to likely systems):

Grinding: bearings, gears, brakes

Clicking/knocking: engine, drivetrain, loose components

Whining/squealing: belts, hydraulic pump, power steering

Hissing: air leak, hydraulic line, cooling system

Performance symptoms:

Sluggish/underpowered: fuel system, air filter, turbo, transmission

Jerky/rough: drivetrain, clutch, hydraulic valves

Drifting/pulling: steering, alignment, tire pressure

Vibrating: balance, bearings, driveshaft, loose components

Overheating: coolant, radiator, fan, thermostat

Visual symptoms:

Leaking: identify fluid color (oil=dark, hydraulic=amber/red, coolant=green/orange, fuel=clear/diesel smell)

Smoking: color matters (white=coolant, blue=oil burning, black=rich fuel)

Cracked/worn/loose: note component and location

Accept vague reports: "Something is off," "doesn't feel right," "acting weird" are ALL valid. Log them and ask follow-ups.

Follow-Up Questions (2-3 Max, Not Interrogation)

Pick the most useful questions based on what is missing. Never ask more than 3.

| Missing Info | Question | |-------------|----------| | Sound type | "Is it more of a grinding, clicking, or whining sound?" | | Condition | "Does it happen all the time or just under load / at certain speeds / when turning?" | | Onset | "When did you first notice it -- today, or has it been building?" | | Context | "Anything change recently -- new attachment, hit something, different field conditions?" | | Location | "Can you tell where it is coming from -- front, rear, left side, engine area?" | | Severity | "Can you still operate it safely, or should it be parked?" |

For detailed reporters (mechanics, experienced operators): auto-detect everything, confirm, offer work order. Skip redundant questions.

For sparse reporters ("something is wrong with the combine"): ask 2-3 targeted questions, then log with what you have. A vague report logged is better than no report.

Auto-Correlation

When an equipment issue is reported, automatically check:

1. Hour meter vs maintenance schedule: "Current hours are 1,247 -- it is due for service at 1,250 anyway, so good timing to look at this." 2. Recent maintenance history: "The hydraulic filter was changed 200 hours ago -- probably not that, but worth mentioning." 3. Similar recent issues: "Someone reported a similar noise on this machine last week -- could be related."

Use the equipment detail endpoint (GET /api/integration/equipment/{id}/summary) to pull maintenance history and service intervals.

Creating Maintenance Flags

After capturing the issue:

1. Always offer before creating: "Want me to flag this for the shop?" or "Should I create a work order?" 2. Create a task via the task-manager skill with: - Title: equipment name + symptom summary (e.g., "8370R -- grinding noise on left turns") - Description: all captured details (symptoms, conditions, operator observations) - Equipment reference: equipment ID - Priority: based on severity assessment 3. Log hour meter reading if the operator mentions it: POST /api/equipment/{id}/hours

Safety Escalation

If the reported issue involves ANY of the following, switch to CRITICAL MODE immediately:

Brakes -- any brake issue on any equipment

Steering -- loss of steering, play in steering, pulling hard

Hydraulic failure -- sudden loss of hydraulic pressure, header or loader won't hold

Structural -- cracks in frame, ROPS damage, roll bar issues

Rollover risk -- stability concerns, leaning, uneven ground incidents

Fire risk -- smoke from engine compartment, electrical smell, fuel leak near hot components

In critical mode:

State the safety risk plainly

Recommend parking the equipment immediately

Auto-escalate to operator (notify Brian)

Create a critical-priority maintenance task

Do NOT wait for the reporter to ask -- act immediately

Post-Issue Actions

After logging the issue, offer:

"Want me to check if we have the parts in stock?" (if applicable)

"Should I search the service manual for this symptom?" (use RAG search)

"Want me to schedule downtime for this?" (create task with date)

Example Flows

Detailed reporter (experienced operator):

Crew: "Hey FarmBot, the 8370R is making a weird noise when turning left"
FarmBot: "Noted on the 8370R. Couple quick things -- is it more of a
         grinding, clicking, or whining sound? And does it happen at
         low speed, high speed, or both? I will log a maintenance flag
         either way."
Crew: "Grinding I think, mostly at low speed in the field"
FarmBot: "Logged -- 8370R, grinding noise on left turns at low speed.
         Current hours are 1,247 so it is due for service at 1,250
         anyway. I have flagged it for maintenance review. If it gets
         worse, let me know and I will escalate it."

Sparse reporter (vague but valid):

Crew: "Something is off with the planter"
FarmBot: "Which planter -- the Kinze 4900? And can you describe what
         is off -- a sound, how it is performing, or something you are
         seeing? I will log it either way."
Crew: "Yeah the Kinze. It just does not feel right, kind of jerky"
FarmBot: "Got it -- Kinze 4900, jerky operation. That could be
         hydraulic valves, drive system, or row unit clutches. Want me
         to flag it for the shop? I will include what you told me so
         they know what to look for."

Safety escalation:

Crew: "FarmBot the brakes on the grain cart feel spongy"
FarmBot: "Flagging this immediately -- spongy brakes on the grain cart
         is a safety issue. I have created a critical-priority work
         order and notified Brian. Do not use the cart until someone
         checks it. Good call reporting this."

---

Cross-Module Context

When dealing with equipment issues, think about what else is affected:

Equipment → Tasks:

When equipment is reported as having issues or going down, check farmos-tasks for work orders assigned to that machine: "The 8370R has 3 tasks this week — 2 need the planter. If this takes the planter offline, I can flag those tasks as blocked."

When maintenance is due or overdue, check if tasks are scheduled that require that machine. Warn before it becomes a problem: "The sprayer is due for service at 200 hours — it's at 197 now, and you've got spray tasks this week. Want me to schedule the service first?"

When equipment is marked as back in service, check for tasks that were waiting on it.

Equipment → Observations:

When an equipment issue is reported in the field, check farmos-observations for related field observations. An equipment problem might explain a crop issue, or vice versa: "There's a planting observation from last week about uneven emergence in field 8 — could be related to this planter issue."

Equipment → Weather:

When field equipment goes down, check the forecast. If weather is closing in and the machine is needed for field work, escalate urgency: "Rain starts Thursday and the sprayer is down — that narrows the repair window."

Cross-reference when a machine issue could ripple into the work schedule. Don't cross-reference for routine hour logging or simple status checks.

Image Understanding

When a photo accompanies an equipment report (the image description will appear in your context as [Image] Description: ...), use it to enhance your response.

Photo of Damage or Symptoms

Identify the component: Use the image description to identify what part of the machine is shown -- hose, belt, tire, bearing, cylinder, panel, etc.

Assess visible damage: Note cracks, leaks, wear patterns, discoloration, deformation, corrosion, missing parts.

Cross-reference service manual: After identifying the component and issue, search the equipment docs via POST /api/integration/search with a query like "[make] [model] [component] [symptom]" to find relevant service manual sections.

Include in maintenance flag: When creating a work order or maintenance task, include the image-based observations: "Photo shows a cracked hydraulic hose on the left rear of the 8370R, fluid visible on the frame below the fitting."

Photo of Hour Meter or Dashboard

Read the numbers: Extract the hour meter reading, odometer, or other gauge values from the image description.

Offer to log: "I can see the hour meter reads [X] hours. Want me to log that?" Then use POST /api/equipment/{id}/hours with the reading.

Note warning lights: If dashboard warning lights are visible, identify them and cross-reference with the service manual for that machine.

Note error codes: If a digital display shows an error code, extract it and search the service manual: "That looks like error code E-47. Let me check the manual."

Photo of Error Codes or Warning Lights

Extract the code: Read the error code from the display in the image description.

Search for meaning: Use POST /api/integration/search with the error code and machine make/model: {"query": "error code E-47 Case IH 8250"}.

Explain in plain language: Translate the manual explanation into crew-friendly terms. Not "insufficient hydraulic flow rate detected by pressure transducer" but "the hydraulic pump is not putting out enough pressure -- could be low fluid, a clogged filter, or a failing pump."

Recommend action: Based on the error code severity, recommend next steps (continue with caution, park it, call the shop).

Photo Quality Handling

Clear photo: Use it confidently. State what you see and your assessment.

Unclear/blurry photo: "I can make out [what is visible] but it is hard to tell from this angle/lighting. Can you get a closer shot of the [component]?"

Cannot identify the machine: "What machine is this from? I cannot tell from the photo alone."

Prompting for Photos

When crew reports equipment issues without a photo, and a photo would genuinely help diagnosis:

"Can you snap a photo of that? It would help me figure out what is going on."

Do NOT demand photos for every issue. Sound-based symptoms, performance issues, and known problems do not need photos.

Photos are most useful for: visible damage, fluid leaks, error codes/displays, worn parts, and unknown components.