Skip to main content
Firmware Stable

How to diagnose a siliXcon device over MCP

This is the general method. A device-specific playbook, when one matches, has the detailed steps; follow it after the first four steps here.

Ground rules​

  • Read-only. Diagnose with emgui_status, list_devices, list_variables, read_variable, list_commands, command_reference, and execute_command for log, pmlog and version only.
  • Paths are absolute and case-sensitive (/io/IN_acc, not /io/in_acc). If a path does not exist, find the right one with list_variables (pattern, path) instead of guessing. Features differ between applications and builds, so a missing path can simply mean a different build.
  • Ask the user for the symptom first, in their words: what they did, what they expected, what happened, since when.
  • Quote values exactly and name the device by its name and serial number, never by bus address alone.

1. Posture​

Call emgui_status. Note the emGUI version, how many devices it knows, and posture: read-only, writes enabled, or writes and dangerous commands enabled (the read, write and danger levels). The level is set by the operator in emGUI; you cannot change it.

2. Find the device​

Call list_devices. It needs no bus traffic.

  • Empty list: go through Could not discover any nodes with the user (power, cabling, address, bus speed). Call search_devices only after that: it rescans the bus, changes what the user sees in emGUI, and makes every earlier address stale.
  • Several devices: ask which one misbehaves, or check each.

3. Identify it​

From list_devices: the hwid starts with the family (esc = motor controller, bms = battery management, ift = display) - see HWID. The swid names the application and version - see SWID. Then call list_playbooks with the device address and apply only a playbook marked as matching the device (matches_device); it takes over from here. Applications reuse variable names and numbers with other meanings, so a playbook for another application does not apply even when its symptoms fit.

4. First reads​

Read these with list_variables (kind: state, path: /, recurse: true) or single read_variable calls:

  • Motor controller (esc): /mode (the application state; its meaning is on the application's mode page), /driver/error, /common/error, /disarm_reason if the application has it, /driver/stat. Look each value up (step 6) before interpreting it.
  • BMS and display: there is no per-application playbook yet. List the root states (list_variables, kind: state, path: /) and use search_docs for the application's state or mode page, for example search_docs("CAPRA state").

Non-zero error words and a mode that blocks operation are the leads. Do not change anything yet.

5. History​

  • execute_command log prints the device's error log. It can return -1 even when it printed entries: use the printed output. Each entry carries the power-up counter run; compare it with the device's current run permanent (read_variable /permanents/run): a smaller run is an earlier power-up; a larger one means the counter was reset since, so the entry is older still. The line format of a motor controller is in Error log.
  • pmlog prints the recorded permanents per power-down (pmlog). Optional; useful for voltage and temperature history.

6. Look facts up, do not recall them​

  • search_docs - the documentation search. Always add the application name from the swid to the exact variable name (LYNX disarm_reason 21): mode and reason numbers are per application. Cite the URLs it returns.
  • read_doc - reads one documentation page as text: use it when a hit has no snippet or a playbook links a table.
  • doc_link - the documentation page of one variable on this device. An emGUI without that tool: the doc-link API gives the same, https://docs.silixcon.com/api/doc-link?family=<esc|bms|ift>&app=<swid>&path=<path> (URL-encoded). The whole swid goes in app, so a pre-release firmware gets the matching docs version. documented: false means it fell back to a search.
  • command_reference - the syntax of a built-in command, before you run one.
  • A table in the docs (mode values, reasons, bit meanings) is the source; read it and link it in your answer rather than restating it from memory.

7. What you may do, and what never​

  • A write, save, reboot or a motor command runs only if the operator has raised emGUI's level, and only when the user asked for that exact change. A refusal is final: report it.
  • Propose one change at a time, say which variable changes from what to what, and let the user decide. A change is live only until power-down unless the user also saves it.
  • Never run motor commands (run, stop, identification) yourself, never reboot to see if it helps, never use a command flag that command_reference does not list.

8. Report​

Five lines:

  1. Device: name, serial number, swid.
  2. State: the values read, quoted exactly (/mode, error words, /disarm_reason).
  3. Cause: one sentence, with the chain of values that shows it.
  4. Fix: what the user does; which step needs a write and therefore the operator's permission.
  5. Sources: the documentation URLs you used; old log entries named as history.

9. When to ask for a diagnostic report​

If the cause is not found, a driver error comes back after a reboot, or the evidence points at hardware, ask the user for a diagnostic report and to send it to siliXcon support.