Getting Started With Multi-PROG Scripts and the SDK

This guide is the starting point for developing safe, authorized XHorse Multi-PROG scripts with this repository. The SDK is an offline development scaffold: it helps with structure, binary utilities, validation, reporting, and tests, but it does not replace the Multi-PROG application's own Help reference or device-specific procedures.

Before You Begin

Use this material only for hardware and vehicles you own or are explicitly authorized to service. Keep customer data, security values, credentials, and real vehicle dumps inside the approved private workflow. Use synthetic buffers or published test vectors while learning.

Install or have access to:

Xhorse Multi-PROG and the target installation's built-in Script Help.
Node.js for offline tests outside Multi-PROG.
A text editor such as VS Code.
A case or change identifier for every authorized job.

Do not assume that Node.js modules, Buffer, filesystem APIs, package imports, or modern JavaScript features are available inside the Multi-PROG host.

Find the Right Starting Point

03_Script_Starter_Kit/ contains dependency-free binary helpers and small examples.
17_MultiPROG_SDK/ contains reusable templates, utilities, schemas, examples, and offline tests.
18_Documentation/SCRIPT_WRITING_GUIDE.md gives the short authoring rules.
18_Documentation/MULTIPROG_SCRIPT_LIFECYCLE.md describes the development stages.
04_Workflows/AUTHORIZED_REPAIR_WORKFLOW.md covers intake, acquisition, validation, and release controls.

Start with template_readonly.mjs, template_validator.mjs, or template_reporting.mjs. Use write-oriented templates only after the read-only and validation behavior is understood.

First Offline Prototype

Create a working copy outside the collected-source directories.
Select a template from 17_MultiPROG_SDK/templates/.
Write down the input shape, expected output, allowed ranges, and failure conditions.
Keep the transformation in pure functions that accept and return Uint8Array values where possible.
Use synthetic data, for example:

const sample = new Uint8Array([0x10, 0x20, 0x30, 0x40]);

Validate buffer lengths, offsets, identifiers, and checksum parameters before changing data.
Preserve the original buffer and produce a diff or structured report for every proposed change.

The SDK utilities are useful here. For example, utilities/crc_engine.mjs provides configurable CRC models, while the templates show patterns for comparison, checksums, allow-listed changes, and reporting.

Run the Offline Tests

From the repository root, use the installed Node.js executable on Windows if node is not on PATH:

& 'C:\Program Files\nodejs\node.exe' 17_MultiPROG_SDK/tests/buffer_helpers.test.mjs
& 'C:\Program Files\nodejs\node.exe' 17_MultiPROG_SDK/tests/crc_engine.test.mjs
& 'C:\Program Files\nodejs\node.exe' 17_MultiPROG_SDK/tests/encoding_helpers.test.mjs
& 'C:\Program Files\nodejs\node.exe' 17_MultiPROG_SDK/tests/template_catalog.test.mjs
& 'C:\Program Files\nodejs\node.exe' 17_MultiPROG_SDK/tests/workflow_templates.test.mjs

The package metadata also defines an npm test command when npm is available:

Set-Location 17_MultiPROG_SDK
npm test

Keep tests deterministic and offline. Add synthetic fixtures for malformed input, boundary offsets, wrong lengths, checksum mismatches, and disallowed write ranges.

Adapt to Multi-PROG

Only after the offline behavior is correct:

Open Multi-PROG's built-in Script Help for the installed version.
Verify each host API name, argument order, return type, buffer type, and error behavior.
Replace placeholder host calls at a small wrapper boundary.
Keep the binary and validation logic independent from host UI and device calls.
Test read-only behavior first in the Multi-PROG editor or test environment.
Confirm the script's metadata, buttons, dialogs, and output paths using a non-production fixture.

Do not copy Node.js imports or package dependencies into a Multi-PROG script unless the target installation explicitly supports them. Prefer small, dependency-free routines copied from the SDK and re-tested in both environments.

Authorized Read and Write Workflow

For an authorized service case:

Record authorization, case ID, vehicle/module identity, and source references.
Acquire two independent reads and compare them byte-for-byte.
Hash and preserve the original files before any transformation.
Work on a copy and maintain an explicit write allow-list.
Log every changed range, including original and replacement bytes.
Verify size, identifiers, blank regions, checksums, and the final diff.
Preserve rollback files and record the Multi-PROG software and firmware versions.

Stop when reads disagree, an identifier is unexpected, a checksum model is uncertain, or a requested change falls outside the documented allow-list.

Package a Script

A useful script package should include:

The script and a clear version identifier.
A metadata record describing purpose, inputs, outputs, assumptions, and host compatibility.
Offline tests and synthetic vectors.
A change report or validation report.
Source attribution and license information for reused code.
A SHA-256 hash of the release bundle.
Test results and the Multi-PROG version used for host testing.

Keep unverified downloads and suspicious files in their existing source or quarantine locations. Do not promote them into the SDK without provenance, license review, and offline validation.

Troubleshooting

The script works in Node but not Multi-PROG: check imports, Buffer, filesystem calls, unsupported syntax, and every host API signature.
A checksum does not match: confirm the region, stored offset, length, endian, polynomial, initial value, reflection settings, and final XOR value.
A write is rejected: verify the buffer length and allow-listed range; do not broaden the range just to make a test pass.
Tests cannot start on Windows: use the full path to node.exe shown above, or select the configured Node.js interpreter in VS Code.
A collected example is unclear: treat it as reference material, inspect its provenance, and do not execute it on a vehicle or connect it to credentials.

6.6 KiB Raw Permalink Blame History