Troubleshot documentation

Troubleshot is an industrial troubleshooting platform: capture symptoms and machine faults, find proven fixes, and coordinate escalations and shift handoffs — so your line gets back online in minutes, not hours.

This guide covers the core concepts, the issue workflow, roles and permissions, search, the API, and how to run the platform yourself.

Signing in & roles

Open the app at app.troubleshot.io and sign in with your email and password. Your role determines what you can do:

• Operator — add symptoms and faults, submit solutions for review.
• Maintenance, Controls & Engineering — everything Operators can do, plus picking up escalations at their tier.
• Admin — full access: manage users, locations, the tag catalog, and review/approve solutions.
• Viewer — read-only access.

Install the app on your phone or tablet

Troubleshot installs to the home screen like a native app — one tap from the plant floor, full screen, with the Troubleshot icon. No app store needed.

• Android — open app.troubleshot.io in Chrome and tap Install on the banner that slides down from the top (or use the browser menu → Install app).
• iPhone / iPad — open the app in Safari, tap the Share button, then Add to Home Screen. The banner at the top walks you through it.
• Computers — Chrome and Edge offer an install icon in the address bar for a dedicated app window.

The installed app opens full screen and keeps working from the same account and workspace. If you dismiss the install banner, it stays out of your way for 30 days.

Quick start

1. Add an issue. From the dashboard, add a Symptom (something an operator observed) or a Fault (a machine error code). Tag it, pin it to a location in the plant hierarchy, and attach photos or video — including straight from the phone camera with Take photo/video. Submitting escalates it in the same action, so support is engaged (and radio capture opens, where installed) immediately.
2. Search before you start. Use unified search to see if this fault has been solved before — pull up the step-by-step fix.
3. Continue with your own findings. Whoever picks up the escalation continues the issue: the original report stays read-only and their findings append to the investigation history.
4. Link a solution or hand off. Found a fix? Link it and submit it for review. End of shift? Hand off to the next crew with full context.

Symptoms

A symptom is an operator-observed problem — "belt stopped suddenly", "drive cabinet feels hot". Symptoms carry a continuous narrative:

• Original report — the first description, preserved no matter who works the issue later. Only the original reporter (or an admin) can reword it.
• Investigation history — an append-only timeline of attributed findings from each responder who works the issue.
• Machine state — Running, Changeover, CIP, or Start-Up, with conditional fields (e.g. previous/new product for a changeover).

Faults

A fault is a machine error or alarm. It records the error code/message, the source (HMI, VFD, PLC, or Sensor), a severity (Low → Critical), and its location. Faults share the same ownership, workflow, and investigation-history model as symptoms — responder findings append to faults exactly the same way.

Solutions & fixes

A solution is a documented way to address an issue. Each has a category:

• Temporary Fix / Permanent Fix — what was done to resolve it.
• Contact — who to reach (e.g. OEM support).
• Escalation / Direction — guidance on next steps.

A solution can hold one or more fixes — step-by-step procedures with a skill level and time estimate. Each step is added individually, can be reordered, and carries its own photos, videos, or documents, so a procedure reads like a walk-through with the right picture next to the right instruction. Solutions are linked to the symptoms and faults they resolve, and go through a review workflow before they're trusted in the library.

Locations

Model your facility as a hierarchy: Plant → Area → Line → Section → Equipment. Every symptom, fault, and machine-scoped solution can be pinned to a node, which powers breadcrumbs and location-aware search. Admins manage the hierarchy under Locations.

Preventative log

The preventative maintenance log records routine checks and their outcomes, optionally linked to a solution, with a root-cause verification status (Verified / Pending / N/A). Anyone but a Viewer can add entries; you can edit or delete your own (admins can manage all).

Ownership

Every issue tracks who's responsible:

• Original reporter — who opened it (immutable).
• Active responder — who currently owns working it.
• Contributors — everyone who previously held the lead.

Edit access is granted to an admin, the reporter, the active responder, or any contributor. Delete is restricted to the reporter or an admin.

Escalation ladder

Adding a symptom or fault escalates it in the same action — the record is created already routed to the next support tier (and radio capture opens where a TRN-1 device is installed). The target tier is computed from the creating/escalating user's role:

Escalated issues appear on the Escalations queue. Whoever picks one up presses Continue symptom / Continue fault — one click makes them the active responder and opens the findings workflow; the previous responder is kept as a contributor and the issue leaves the waiting queue, showing Active troubleshooting. Eligibility: an admin or the listed active responder may always continue; otherwise the user's role must match the target tier.

Continuing an issue

Continuing opens a dedicated continuation page — the next-level responder works on top of the original report, never over it:

• The original report, investigation history, and workflow timeline are shown as read-only context (with the context card where applicable).
• The responder adds their own findings, which append to the investigation history with their name, role, and timestamp.
• Prior context is preserved: the location stays locked to the original report, and earlier users' machine sections, tags, keywords, documents, and photos/video can't be removed — each responder adds their own on top. Accidentally removed a tag or keyword you just added? Ctrl+Z / Cmd+Z (or the inline Undo) restores it.
• Media follows the issue: photos, video, and documents attached at any stage stay with the record and are browsable in a gallery on the issue's detail, continuation, and review pages.
• New context: additional machine sections, tags, keywords, documents, and photos/video — including Take photo/video, which opens the camera on phones and tablets or an in-app webcam capture on computers.
• From the same page they can Save, Handoff (shift change), Escalate to next tier, or Add solution — Add solution prefills the solution form with the responder's findings and lets them attach the step-by-step fix procedure in the same submission.

Shift handoffs

At end of shift, use Handoff to turn an issue over to the next crew with a required summary and optional production impact. The issue lands on the Shift Handoffs queue. The next person continues it from the same continuation page to assume ownership.

Solution review

New solutions start as pending. A solution and its step-by-step fix procedure are submitted together as one review package — each step can carry its own photos, videos, or documents. While a solution is awaiting approval, the linked issue's active responder is cleared (no named lead during review). The admin opens the item from the Review Queue into a full-detail review page — the submitted package alongside the originating issue's complete context — and then:

• Approves it (approved) — the package joins the trusted library; or
• Returns it with a note (returned) — ownership of the linked issue goes back to the solution's author, who edits and resubmits.

Linking a Permanent Fix to a symptom that's pending escalation automatically clears that escalation.

Audit trail

Every workflow action — open, escalate, handoff, transfer, continue, and the solution submit/approve/return events — is appended to an immutable lead-event timeline on the issue, so you always know who did what and when.

Radio capture

Radio capture turns the two-way radio call that follows an escalation into an automatic context card for the responding technician — so whoever picks up the escalation already knows what was said on the radio, with no one typing it up.

1. An operator adds an issue — submitting escalates it — then makes the normal radio call.
2. A plant-floor TRN-1 module records that call and uploads the audio.
3. Troubleshot transcribes it and builds a context card from the full escalation record — the original report, prior responders' findings, tags, and location, with the radio call as the dispatch signal.
4. The responder sees the card on the issue automatically — including what has already been checked or attempted.

On an escalated issue, a Context panel shows the generated summary to everyone with access. The raw audio clips and transcripts are visible to admins only. Admins register and manage devices under Administration → Radio Devices, where each device gets a scoped, one-time token.

Roles & permissions

Search

Unified search spans symptoms, faults, and solutions. It tokenizes your query (dropping stop-words), requires all terms to match, and ranks results — with a bonus for exact phrase matches and for fixes/solution text. You can also filter by tag. Search is location-aware: the full breadcrumb of an issue is searchable.

API reference

The API lives at https://api.troubleshot.io/api. Authenticate by sending Authorization: Bearer <token> obtained from login.

# Log in
curl -X POST https://api.troubleshot.io/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"••••••••"}'
# → { "token": "...", "user": { ... } }

Scaling & data

Each company gets its own isolated workspace, and your data is yours — you can request a copy of it or request deletion at any time. Troubleshot comfortably handles single-site and multi-site operations: large catalogs of symptoms, faults, and solutions, with fast search across all of them.

Hosting & availability

Troubleshot is offered as a fully managed, cloud-hosted service — nothing to install or maintain on your servers (the mobile app installs straight from the browser, no app store or MDM required). Live service status is published at troubleshot.io/status.

Organizations that require it can run Troubleshot in their own environment (private cloud or on-premises) under a separate agreement. For self-hosting, custom hosting, or SLAs, reach out at hello@troubleshot.io.