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:
```json
{
  "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:
```json
{
  "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:
```json
{
  "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 maint

... (truncated)