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. The one exception is a setup playbook (kind: setup), and only in its own steps (step 7).
• 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.
• The interface is the user's. You cannot change which interface emGUI uses or its settings, and never ask the user for a password or a service token: emgui_status says only whether one is set. A device that needs a login is logged into by the user: in Launchpad's options, which keep the login (in emGUI, Connection → Authentication... lasts only until emGUI closes), then emGUI started again from Launchpad.
• Ask with options the user clicks, not in your text. Put every question to the user - a choice, a yes before a change, "is it done?" - in your client's question tool, the popup that shows answers to click, whenever the client has one. Offer the likely answers as options, the recommended one first, and keep the question itself short. Typing is the last resort: for an answer no options can cover (a measured value, a symptom in the user's words), as an "other" choice next to the options, or in a client without a question tool.
• Ask the user for the symptom first: offer the common symptoms as options, and let the user describe it in their own words when none fits - what they did, what they expected, what happened, since when.
• A finished vehicle belongs to its maker. An end user of an e-bike, scooter, motorcycle or machine built by someone else gets its configuration from that maker, who may have locked it. Do not help to unlock it, to raise power or speed limits, or to reset it: send the user to the vehicle maker. Read and explain what is readable.
• Errors, limits and disarm are different things. An error stops the device and is logged; a limit is the device protecting itself or following its settings, at run time and not logged; a disarm reason (an application's) says why it does not drive yet. Only errors point to faults.
• The firmware version matters. Features and fixes depend on the version in the swid: a documented feature that is missing usually needs a newer firmware - compare with the application's changelog before diagnosing further.
• A variable's name is not its meaning. Never infer what a variable or parameter measures or does from its name, path or unit: look each one up (step 6) before you interpret or report it. Names mislead - /driver/temp is the controller's temperature, not the motor's, and says nothing about a motor thermistor. If the documentation does not describe a variable, say so instead of guessing.
• Quote values exactly and name the device by its name and serial number, never by bus address alone.
• The allowed battery or supply voltage comes from the specification page, never from the hardware id. Before saying anything about which battery or supply a device takes, read the device's specification (Product Specification) page; on a motor controller, the "Maximum input voltage" table in the row for its voltage variant (the variant from decode_hwid). Tell the user that row's maximum working voltage and its Li-ion series cell count, for example "at most 84 V, a 20S Li-ion battery", and the minimum working voltage when it matters. Do not mention the voltage in the hwid or in decode_hwid, or the transistors' voltage: it is a component rating, higher than what may be connected, and naming it invites a battery that destroys the device (why, for a motor controller).
• The firmware's build target matches the hardware id only in its first part. version names the target the firmware was built for (for example esc5-sx1_24dxa0840-C00). Only the part before the _ (esc5-sx1) has to match the device's hwid; the rest - voltage variant, current range, edition - routinely differs from the device's own and is not a fault. Do not point it out or warn about it; only a different first part is worth reporting.

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.

Also note interface: whether an interface driver is loaded and connected, and in config the interface name, protocol, options, addresses and whether a login user (credential.user) is set.

2. Find the device

Call list_devices. It needs no bus traffic.

• Empty list: check interface from step 1 first.

  • loaded: false: no interface driver is loaded. The user picks one in emGUI: Connection → Load interface....
  • connected: false: the user clicks Connection → Connect in emGUI. search_devices cannot find anything while the interface is not connected.
  • Connected: tell the user the name, protocol and options in use. options is decoded in the "opt string format" section for that name in Communication interfaces (read it with read_doc): check that the interface and bus speed are the ones the device uses.

  Then go through Could not discover any nodes with the user (power, cabling, address, bus speed); for a motor controller, the power and connection playbook has the details (power-up order, the KEY fuse, what CAN needs). 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. For a motor controller, the motor driver playbook matches whatever the application: an application's playbook hands over to it once the application commands the motor, and with no application playbook it follows these first steps directly. A new device, or one being set up for the first time, starts with the getting started playbook. Setting a motor controller up for its motor (first setup, a new motor or motor sensor) is the motor identification playbook.

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.
• decode_hwid - what the device's hardware variant has, from its hwid, for the product series the documentation decodes: the series, the variant's features - on a motor controller the motor sensor inputs, the voltage variant, the current range and connectivity - and the series' hardware page, which links each edition's Product Specification. For a series the documentation does not decode, it says so; the product's hardware page then says what it has. The voltage it shows is not the allowed battery or supply voltage: do not quote it (see the ground rules).
• 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 command that acts on the hardware the device drives (a motor command, for example) runs only if the operator has raised emGUI's level, and only when the user asked for that exact change or said yes to it when you proposed it. 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 a command that acts on the hardware the device drives (on a motor controller the motor commands: run, stop, identification) unless a setup playbook says so; then only at that step, after the user's explicit yes for it, at the level the operator has set. On a motor controller that playbook is the motor identification playbook: it runs stop, identlin and identrun this way.
• 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 (for example /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, an 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. The report holds the values of the moment they were pulled: the device powered as in use (not from USB alone), the problem reproduced, Pull values clicked while it is present (for example with the throttle held), then the report generated. Before a device goes back for repair, go through the checks before returning a device.