Workstation-Setup/Xhorse-MultiPROG-Script-Development-Resources.md

# Xhorse Multi-PROG Script Development Resources

Generated: 2026-08-29

## Official Documentation

### Multi-PROG Script Function Manual (PDF)
https://www.xhorsevvdi.com/upload/pro/24040217120425363837.pdf

Notes:
- Official JavaScript scripting manual
- Local Scripts and Released Features
- Script publishing (.mjs)
- Built-in functions window
- Uint8Array examples
- Device/file/interface APIs

### Multi-PROG User Manual (PDF)
https://www.xhorsevvdi.com/upload/pro/23122817038226585731.pdf

Notes:
- EEPROM workflows
- MCU workflows
- ECU/TCU workflows
- Third-party script support

## Script Development Guides

### How to Make First Script with Xhorse Multi-Prog
https://blog.xhorsetool.com/how-to-make-first-script-with-xhorse-multi-prog/

Notes:
- JavaScript-based scripting
- Importing scripts
- Publishing scripts
- Volkswagen MED9.5.10 example
- Script toolbar buttons

### BMW CAS4+ KM Script Example
https://blog.xhorsevvdi.com/xhorse-multi-prog-bmw-cas4-km-repair-script-test/

Notes:
- Demonstrates importing and running a released script
- Shows script toolbar integration

## Official Product and Support Pages

### Multi-Prog Main Product Page
https://www.xhorsevvdi.com/wholesale/vvdi-multi-prog.html

### Multi-Prog Support Portal
https://www.xhorsevvdi.com/service/how-to-use-xhorse-multi-prog-programmer.html

### Multi-Prog Category Archive
https://blog.xhorsevvdi.com/category/multi-prog/

Useful for:
- New examples
- ECU clone articles
- Connection diagrams
- User-reported solutions

## Multi-PROG Script Workspace Structure

Recommended workspace:

Multi-PROG/
├── Documentation/
├── Scripts/
│   ├── Libraries/
│   ├── Templates/
│   ├── Examples/
│   └── Released/
├── TestData/
└── Backups/

Keep exported `.mjs` files in `Scripts/Released`, use only copies in `TestData`, and retain
verified original reads in `Backups`. The setup script creates this layout under
`P:\PortableApps\Automotive\Xhorse\Multi-PROG` when P: is available, with a local C: fallback.
Its created directories are `Documentation`, `Scripts/Libraries`, `Scripts/Templates`,
`Scripts/Examples`, `Scripts/Released`, `TestData`, and `Backups`.

## Official Software Installers (opt-in)

Running the setup script with `-InstallXhorseSoftware` downloads these installers directly from
Xhorse's own download servers to the shared `P:\Install\Xhorse\...` folders and launches each one
interactively. Nothing is installed silently: complete the license terms, installation path, and
dongle pairing prompts yourself, and connect the hardware only when the installer asks for it.

### Multi-PROG software installer
https://dl.xhorse.com/product/multiProg/Multi-PROG.exe

### VVDI-MLB software installer
http://dl.xhorse.net.cn/product/vvdimlb/VVDI-MLB.exe

### MVCI PRO (J2534 pass-thru) software installer
http://dl.xhorse.com/product/mvci/MVCI_PRO-J2534.exe

Notes:
- Xhorse's MVCI PRO CDN returns HTTP 403 over HTTPS, so this asset is fetched over plain HTTP.
  Verify the downloaded file (e.g. digital signature, vendor-published hash if published) before
  running it on a production machine.
- MVCI PRO user manual: http://dl.xhorse.com/p/vd06/userManual.pdf

## JavaScript References

### MDN JavaScript
https://developer.mozilla.org/en-US/docs/Web/JavaScript

### Uint8Array Reference
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array

### ArrayBuffer Reference
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer

### DataView Reference
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView

## Portable VS Code Extensions

The workstation setup installs these extensions into the portable VS Code instance after `Code.exe`
is available. They support offline analysis and development; they do not program or communicate
with a vehicle module unless a user explicitly configures separate, authorized hardware tooling.

- Hex Editor (`ms-vscode.hexeditor`): inspect EEPROM, flash, and binary files without altering the source file.
- Serial Monitor (`ms-vscode.vscode-serial-monitor`): observe authorized bench serial output.
- Python (`ms-python.python`), C/C++ (`ms-vscode.cpptools`), CMake Tools (`ms-vscode.cmake-tools`), and Makefile Tools (`ms-vscode.makefile-tools`): build offline parsers, diff tools, and documented test utilities.
- PowerShell (`ms-vscode.powershell`): maintain the Windows automation scripts.
- YAML (`redhat.vscode-yaml`), XML (`redhat.vscode-xml`), and Even Better TOML (`tamasfe.even-better-toml`): inspect structured configuration and metadata files.

Extension installs use VS Code's `--install-extension <publisher.extension>` command with `--force`
to update an existing extension. Individual extension failures are logged and do not stop the rest
of the workstation setup.

## Reverse-Engineering Workspace

The setup creates `C:\Automotive\Projects\ReverseEngineering` with `Originals`, `WorkingCopies`,
`Disassembly`, `Decompiled`, `Signatures`, `Scripts`, and `Reports` subdirectories, plus a Desktop
and Start Menu shortcut. Preserve source reads in `Originals`, perform analysis only on duplicates
in `WorkingCopies`, and save derived artifacts separately. The workstation does not add routines
for vehicle-module programming, erase, or write operations.

## Useful Open Source Libraries

### CyberChef
https://github.com/gchq/CyberChef

### ImHex
https://github.com/WerWolv/ImHex

### jq
https://github.com/jqlang/jq

### yq
https://github.com/mikefarah/yq

## Research and Binary Analysis Tools

### Ghidra
https://github.com/NationalSecurityAgency/ghidra

### Binwalk
https://github.com/ReFirmLabs/binwalk

### Kaitai Struct
https://github.com/kaitai-io/kaitai_struct

### Frhed
https://frhed.sourceforge.io/

## Suggested Safe Starter Scripts

1. Buffer Compare
2. EEPROM Inspector
3. VIN Finder
4. DTC Pattern Search
5. Header Decoder
6. Generic XOR Checksum Tester
7. Generic Additive Checksum Tester
8. File Structure Analyzer
9. Binary Diff Report Generator
10. Backup Verification Utility

## Recommended Development Workflow

1. Create script in Local Scripts.
2. Use read-only functions first.
3. Test against sample files.
4. Save original backups.
5. Use Debug > Test.
6. Review Messages window.
7. Publish to .mjs.
8. Import into Released Features.
9. Run on test data.
10. Version-control all scripts.


## GitHub Multi-PROG Script Repositories

### CarKeyGuyNL / Multi-Prog-Scripts
https://github.com/CarKeyGuyNL/Multi-Prog-Scripts

Repository contents currently include an Xhorse Multi-PROG `.mjs` example and import instructions. Treat third-party scripts as untrusted until reviewed offline. Do not run scripts that alter security, keys, odometer, airbag, or module data without explicit authorization and a verified backup.

The repository's currently listed example is an EWS code calculator. It is intentionally not
included in the generated workspace: do not import or run code-generation, key, security, or
module-write scripts unless they are authorized, version-matched, independently reviewed, and
tested on non-production data.

### MHH Auto Forum
https://mhhauto.com/

MHH Auto can be useful for locating discussion and compatibility reports, but access and content
vary by forum section. Treat every attachment and script as untrusted: verify authorship and
license, scan it offline, inspect all device and file-write paths, and never use forum material as
the sole source for pinout, voltage, checksum, or security-data decisions.

## Included Read-Only Script Pack

The setup script creates these JavaScript files under `Scripts/Examples`. They are self-contained,
use only standard JavaScript and `Uint8Array`, and do not call Multi-PROG device, erase, write,
security, key, or odometer APIs.

### ReadOnlyBinaryAnalysis.js
- Finds exact byte sequences in a supplied buffer.
- Lists printable ASCII runs with their offsets.
- Produces a bounded hexadecimal preview.

### ChecksumTestVectors.js
- Verifies generic modulo-256 additive and byte-wise XOR helper logic against known values.
- Does not identify, validate, or correct an ECU checksum.

### SafeBufferUtilities.js
- Provides bounded range copies, byte comparisons, hexadecimal formatting, and generic checksum helpers.
- Keeps all operations read-only and leaves device/file acquisition to documented version-specific APIs.

### GitHub repository search: Xhorse Multi-PROG
https://github.com/search?q=%22Multi-PROG%22+Xhorse&type=repositories

### GitHub code search: Multi-PROG `.mjs`
https://github.com/search?q=%22Multi-PROG%22+extension%3Amjs&type=code

### GitHub topic: ECU
https://github.com/topics/ecu

Use topic results for research only. A project mentioning checksums or flashing is not automatically compatible with Multi-PROG.

## Automotive Checksum References

### VancePeterson / checksum-finder
https://github.com/VancePeterson/checksum-finder

Python toolkit for analyzing automotive diagnostic data and testing candidate checksum algorithms. Review the repository before use because it also contains security-analysis utilities unrelated to ordinary checksum validation.

### OpenRemap
https://pypi.org/project/openremap/

Offline ECU binary identification and health-checking toolkit with checksum detection coverage for several ECU families. Use detection results as supporting evidence, not as a reason to write a file automatically.

### ME7Sum
https://github.com/nyetwurk/ME7Sum

Reference implementation for checking and correcting checksums in specific Bosch Motronic ME7 firmware families. It is not a generic ECU checksum engine.

### VW Flash
https://github.com/bri3d/VW_Flash

Research reference containing checksum implementations for supported Volkswagen control-unit families. Applicability must be confirmed by exact ECU family and software version.

### CRC Catalogue and Calculator
https://reveng.sourceforge.io/crc-catalogue/
https://reveng.sourceforge.io/

Useful for identifying standard CRC parameter sets. ECU checksums are often family-specific and may not match a standard catalogue entry.

### JavaScript CRC-32 reference implementation
https://gist.github.com/diachedelic/582ac8fab84b7f2c34ff358ac5cc7cfa

Small Uint8Array-oriented CRC-32 implementation. Review and test against known vectors before adapting it to Multi-PROG.

## JavaScript Binary and Helper Libraries

### MDN Uint8Array
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array

### MDN ArrayBuffer
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer

### MDN DataView
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView

### SheetJS CRC-32
https://github.com/SheetJS/js-crc32

General JavaScript CRC-32 implementation. Multi-PROG compatibility depends on its embedded JavaScript runtime and supported syntax.

### easy-crc
https://github.com/jaehaklee/easy-crc

JavaScript/TypeScript CRC library covering multiple CRC parameter combinations. Use it as an algorithm reference if the Multi-PROG runtime cannot load Node packages directly.

### js-checksum
https://github.com/btnguyen2k/js-checksum

Configurable JavaScript hash/checksum library supporting typed arrays, ArrayBuffer, and DataView. This is mainly useful for development outside Multi-PROG or for porting individual pure functions.

### BrowserCheckSum
https://github.com/Samuel-Hinchliffe/BrowserCheckSum

Browser-oriented cryptographic hash helper for files and ArrayBuffer data. It is more suitable for backup-integrity verification than ECU-family checksum correction.

### Kaitai Struct
https://github.com/kaitai-io/kaitai_struct
https://ide.kaitai.io/

Declarative binary-format tooling useful for documenting repeatable EEPROM and firmware structures before implementing a read-only Multi-PROG parser.

### ImHex Patterns
https://github.com/WerWolv/ImHex-Patterns

Community binary-format patterns for ImHex. Patterns must be reviewed and matched to the exact target format before use.

## Recommended Library Adoption Pattern

1. Keep upstream references in `Documentation/References`.
2. Copy only small, reviewed, license-compatible pure functions into `Scripts/Libraries`.
3. Record source URL, commit/tag, license, and retrieval date in each adapted file.
4. Avoid Node-only features such as `require`, npm resolution, filesystem modules, or browser APIs unless Multi-PROG explicitly supports them.
5. Prefer `var`, ordinary functions, `Uint8Array`, bounded loops, and explicit range validation.
6. Validate checksum code with published test vectors and at least two known-good binaries.
7. Keep checksum detection separate from correction.
8. Never write a corrected file until the exact ECU family, software version, covered ranges, stored checksum locations, byte order, and algorithm parameters are independently verified.
9. Never auto-run a downloaded `.mjs`; inspect it first and test only against duplicate offline data.


## Additional GitHub Repositories

### MEDC17 Checksum Tool
https://github.com/ConnorHowell/medc17-checksum-tool

Family-specific Bosch MED17/EDC17 checksum analyzer. Use its read-only analysis mode first and do not assume it supports every software variant or code-section change.

### EasyTuner
https://github.com/RKDimitrov/easytuner

Research-oriented ECU firmware analysis and map-recognition platform. Useful for studying project structure, annotations, and non-destructive analysis workflows.

### romHEX14 Community
https://github.com/ctabuyo/romHEX14-community

Open-source calibration editor with checksum-plugin architecture and tests. Its plugin interfaces are useful references for separating detection, analysis, correction, and verification.

### Awesome Binary Parsing
https://github.com/dloss/binary-parsing

Curated directory of binary parsing libraries, including JavaScript projects such as binary-parser, jBinary, Binpat, and restructure.

### binary-parser
https://github.com/keichi/binary-parser

Declarative JavaScript parser for integers, strings, arrays, bitfields, choices, and pointers. It expects a Node/module environment, so port only small pure ideas to Multi-PROG unless module loading is documented.

### jBinary
https://jdataview.github.io/jBinary/

Declarative read/write binary-data library built on jDataView. Useful as a design reference for endian-aware field readers.

## Expanded Checksum Library Usage

### Required parameters
Before calling a checksum implementation, document:

- Algorithm family and width
- Covered start/end offsets
- Included and excluded blocks
- Byte or word processing order
- Little-endian or big-endian interpretation
- Initial accumulator or CRC seed
- CRC polynomial
- Input/output reflection
- Final XOR, complement, or negation
- Stored-checksum offset and width
- Whether the stored field is zeroed, skipped, or included during calculation
- Whether a descriptor table defines multiple protected blocks

### Detection versus correction

Detection is read-only: calculate candidate values and compare them with stored values. Correction writes new checksum bytes. Keep these as separate functions and make correction require explicit, validated metadata.

### Minimum validation set

1. Run the algorithm against an untouched known-good file.
2. Confirm every expected stored checksum.
3. Change one non-checksum byte in a copy.
4. Confirm that detection reports an error.
5. Correct a new output copy, never the input.
6. Confirm only expected checksum storage bytes changed besides the deliberate edit.
7. Re-run the detector against the output.
8. Cross-check with a second independent implementation.
9. Retain hashes and binary-diff reports for input and output.

### Library roles

- ME7Sum is specific to supported Motronic ME7 images.
- MEDC17 tools are specific to supported Bosch MED17/EDC17 structures and variants.
- RevEng helps identify standard CRC parameter sets, but does not establish ECU applicability.
- Generic JavaScript CRC libraries implement math, not ECU block discovery or metadata validation.
- Cryptographic SHA/MD5 libraries are useful for file identity and backup verification, not as replacements for ECU checksums.

## JavaScript Helper Function Explanations

### Range validation
A helper should reject negative offsets, negative lengths, arithmetic overflow, and any range extending beyond the Uint8Array. Perform validation before every parse or checksum operation. Reuse one `validateRange` helper so copy and checksum functions enforce the same boundary rules.

### Endian readers
Create explicit helpers such as `readU16LE`, `readU16BE`, `readU32LE`, and `readU32BE`. Explicit names prevent a parser from silently applying the wrong byte order.

### Hex formatting
`toHexByte` and `bytesToHex` should format values without changing the underlying buffer. Formatting functions should never be mixed with write logic.

### Binary comparison
`compareBytes` should return offsets and both values. Use it to verify repeated reads and to prove that a transformation touched only expected locations.

### Checksums
`additiveChecksum8` and `xorChecksum8` are generic teaching helpers. Their output has meaning only when the exact algorithm and range are independently known.

### Runtime constraints
Multi-PROG documents JavaScript and Uint8Array support, but this does not imply Node.js or browser compatibility. Avoid `require`, npm imports, `Buffer`, DOM APIs, network calls, dynamic evaluation, and unsupported modern syntax. Prefer self-contained pure functions.