TSUNAGI///Matrix — MAPPING

matrix-tsunagi — TSUNAGI///Matrix

The calculations behind TSUNAGI's BMW E46 M3 tools, as a library, a command line and MCP servers. Read an MSS54HP DME image and a drive log, and get the VE map correction the drive supports. Read an SMG II gearbox image, and decode and compare its calibration. Read a DME backup or a cluster EEPROM backup, and check what it holds. On your own machine, with no car and no cable.

npx matrix-tsunagi mapping ve --sample

--sample runs on the practice files shipped in the package. Replace it with --bin --log for your own.

Installing it for an AI assistant (Claude, ChatGPT and others): see INSTALL.md. It is written so that you can hand this repository to the assistant and it installs what fits its client.

TSUNAGI///M is TSUNAGI's family of tools for the E46 M3 (S54 engine, MSS54HP DME, SMG II). Owners meet the tools on m3.tsunagi.app; AI assistants meet them here. TSUNAGI///Matrix is the family's gate for AI assistants: it computes nothing of its own, and carries each tool's own code to the assistant, one category at a time. This package carries two categories. MAPPING: MSS54HP CSL CONVERT /// TUNER and E46M3SMG2 /// MAPPING. MIGRATION: it reads the backups of MSS54HP CSL CONVERT /// BOOT and E46 M35080 /// MIGRATION, and only reads them.

Ask it

How do I correct the VE (alpha-N) map of my CSL-converted MSS54HP from a Testo log?

npx matrix-tsunagi mapping ve --bin my.bin --log drive.csv --out tuned.bin

Which cells change and by how much, which need more driving and how to drive them, and — with --out — the tuned BIN with its checksums corrected. That file is byte-for-byte what TUNER's DOWNLOAD TUNED gives for the same two files.

What is in my MSS54HP bin? Are its checksums right? Which patches are on it?

npx matrix-tsunagi mapping bin my.bin

Why did most of my log get thrown away?

npx matrix-tsunagi mapping log drive.csv --bin my.bin

Every reason a sample was left out (cold engine, transient, full load, overrun…), each with what to change on the next drive.

What rf_korr table does my drive support? *(experimental)*

npx matrix-tsunagi mapping rfkorr --bin my.bin --log drive.csv

The exhaust-temperature density correction (KF_RF_KORR_DRREL), cell by cell, with the evidence behind each.

What are my SMG II shift points? What is this SMG image?

npx matrix-tsunagi mapping smg2 image smg.bin

npx matrix-tsunagi mapping smg2 read smg.bin --xdf Siemens_SMG_II_510_512K.xdf --item "A1 Speed"

smg2 image needs nothing else: it says whether the image is the 24 KiB calibration window or the full 512 KiB flash, and gives the ZB number and whether the CRC checksums hold. smg2 read decodes every item the MS4X definition names, through E46M3SMG2 /// MAPPING's corrections to it. That includes shift speed thresholds per gear and program, gear ratios, and clutch and launch settings. The definition (Siemens_SMG_II_510_24K.xdf or _512K.xdf) is the MS4X Dev Team's and is not shipped here, so pass your own. The WORKS build of E46M3SMG2 /// MAPPING carries it.

What changed between two SMG II calibrations?

npx matrix-tsunagi mapping smg2 compare before.bin after.bin --xdf Siemens_SMG_II_510_512K.xdf

Which bootloader is in my DME backup, and what is left of the CSL conversion?

npx matrix-tsunagi migration boot backup dme-backup.bin

From BOOT's full 1 MiB backup: standard M3 or CSL bootloader on each processor, whether each bootloader CRC holds, the program number, and the stages left. migration boot compare a.bin b.bin names where two backups differ.

What mileage does this cluster EEPROM hold? Is the dump even a real read?

npx matrix-tsunagi migration m35080 read eeprom.bin

From a 1 KB M35080 backup: whether it is a real chip read (a dead or shorted bus reads as one repeated byte), the mileage in the secure counter, the layout and checksums, and whether the VIN copies agree. migration m35080 compare a.bin b.bin shows which area changed between two dumps.

MIGRATION only reads. The functions that would change an image are not in this package, and npm run verify checks the bundle for them. The VIN and the DME's identity record are never printed, because what a command prints goes into the conversation with the assistant.

What can it do?

npx matrix-tsunagi describe

For AI assistants

• Run npx matrix-tsunagi describe once. Every command prints JSON on stdout, and errors come as JSON on stderr with exit code 1.
• Each result has a summary to relay, result with the numbers, and source, which says which tool and version computed it and whether the calculation is experimental.
• apply appears only when the owner would have to write the result to the car. It names the app, says whether the app is free or WORKS, and says how. apply.how and source.note are in English and Japanese.
• With no files yet, add --sample to show the command working on the practice BIN and drive.
• Nothing is sent anywhere. Files are read from the paths you give.

Claude plugin

plugin/ is the Claude plugin, one package for both parts. The public part runs the MAPPING and MIGRATION servers on this computer (Claude Code), with the matrix-public Skill. The WORKS part is the TUNER WORKS connector (bridge/, sign-in on m3) with the tuner-drive Skill, so an owner can talk to TUNER WORKS while it logs the car, from the phone too. It can stage a calibration change, save the session and sync it with the owner's cloud, each after the owner says yes; connecting to the car and writing to it stay with the owner, on the screen. The Skills are only the way in: the procedures come from the servers (about_matrix's howToUse, tuner_guide), so they update with the tools without a new plugin, and the plugin runs the newest matrix-tsunagi on npm. How to install it is in INSTALL.md.

MCP

There are two servers, one per category.

The MAPPING server exposes the same calculations as tools. For TUNER: read_bin, read_log, propose_ve and propose_rfkorr. For SMG2: smg2_image, smg2_read and smg2_compare. And about_matrix. It runs locally over stdio.

The MIGRATION server (npx -y matrix-tsunagi mcp migration, or npx -y matrix-tsunagi-migration) exposes boot_backup, boot_compare, m35080_read, m35080_compare and about_matrix, all read-only.

Claude Code:

claude mcp add matrix-tsunagi-mapping -- npx -y matrix-tsunagi mcp mapping

Claude Desktop (claude_desktop_config.json):

{

"mcpServers": { "matrix-tsunagi-mapping": { "command": "npx", "args": ["-y", "matrix-tsunagi", "mcp", "mapping"] } } }

On Windows, if npx is not found, use "command": "cmd" with "args": ["/c", "npx", "-y", "matrix-tsunagi", "mcp", "mapping"].

Remote (ChatGPT)

For assistants that cannot run npm, the MAPPING server also runs remotely:

https://matrix-mcp.tsunagi.app/mcp/mapping

In ChatGPT, turn on Developer mode (Settings → Security and login), then add it as a plugin by that URL. Attach your BIN and log in the chat and ask. Files reach the server as ChatGPT file parameters: it downloads them from the temporary link ChatGPT issues, computes in memory, returns the result, and keeps nothing. It returns values only, so make the tuned BIN with the free TUNER, and it is MAPPING only, because MIGRATION's dumps carry a VIN and a mileage and stay on your machine. How it handles files is set out in section 11 of the privacy policy.

Library

import { mapping } from 'matrix-tsunagi';

import fs from 'node:fs';

const ve = mapping.proposeVe({ bin: new Uint8Array(fs.readFileSync('my.bin')), csv: fs.readFileSync('drive.csv', 'utf8'), }); console.log(ve.summary); fs.writeFileSync('tuned.bin', ve.tunedBin);

mapping.readBin, mapping.readLog and mapping.proposeRfKorr take the same inputs. For SMG2 there are mapping.smg2Image({ image }), mapping.smg2Read({ image, xdf, item }) and mapping.smg2Compare({ image, other, xdf }), where xdf is the definition's text.

Putting a result on the car

The calculations are free. Writing a result to the car is done in the apps.

The WORKS builds are for people who have bought MILE on MESH, and for owners of cars TSUNAGI has worked on, on request. They are TUNER's experimental features, E46M3SMG2 /// MAPPING, E46M3 /// MONITORING, MSS54HP CSL CONVERT /// BOOT and E46 M35080 /// MIGRATION. MILE is a one-time payment, with no subscription and no renewal. A purchaser can allocate MILE to a MILESTONE to say what they would like it spent on. That is a wish on record, not a promise of any release or date.

Inputs

• BIN: the 65,536-byte MSS54HP calibration partial ("0401 partial BIN"), the file TUNER reads and writes.
• Log: a CSV with a header row, either Testo's MSS54 export or a CSV TUNER exported. Columns are matched as Testo and TUNER spell them. If a required column is missing, the error names the headers that would be accepted.
• SMG II image: the 24,576-byte calibration window or the 524,288-byte full flash of the SMG II 510, as E46M3SMG2 /// MAPPING reads and exports them.
• DME backup: the 1,048,576-byte full MSS54HP image (master and slave), as BOOT backs it up.
• M35080 image: the 1,024-byte cluster EEPROM, as E46 M35080 /// MIGRATION backs it up.
• XDF: the MS4X Dev Team's TunerPro definition, Siemens_SMG_II_510_24K.xdf for a window or _512K.xdf for a full read. The other variant is refused rather than read at the wrong offset.

Where the numbers come from

This package does not re-implement anything. It bundles each tool's own code from its public repository, at the commit its submodule is pinned to: mushitaro/mss54hp-csl-convert-tuner (vendor/tuner) and mushitaro/e46m3smg2-mapping (vendor/smg2), mushitaro/mss54hp-csl-convert-boot (vendor/boot) and mushitaro/e46-m35080-migration (vendor/m35080). Every result names the tool, version and commit in source.

npm run verify holds the tuned BIN to a SHA-256 measured from TUNER's own DOWNLOAD TUNED, read out of that same commit. It holds SMG2's decoding to the app's own loadDefinition, item by item. Each has a control that shows the comparison can fail. The SMG2 check needs the MS4X definitions and a car's image, which are not public. Without them it reports SKIP, which is not a pass.

git clone -