farmos-equipment

# 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 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.