Alchemy is a command line tool for modifying and transforming Matter spec documents.

It can:

• Format your spec documents, aligning table cells, removing unneeded spacing, etc.
• Disco-ball your spec documents, aligning them with Matter spec style guidelines
• Generate ZAP XML files for clusters and device types
• Generate Data Model XML files
• Generate basic test plans for clusters
• Compare the Matter spec to the SDK and generate a list of differences
• Present the Matter spec as a MySQL-compatible database to run queries against
• Print English-language explanations of Matter conformance strings

Download the latest releases from the GitHub release page.

There are two builds for each architecture: plain and db. The db build includes the DB Feature below, but at the expense of a larger binary.

Alchemy is written in pure Go, so to build from source:

1. Install Go 1.22 or greater
2. Clone the alchemy repo
3. In the root of the alchemy repo, run go build

Format does not alter the content of the document, but does make it easier to read the source:

• Aligns table cells so that table delimiters correctly line up with other cells in the same column
• Removes extraneous spacing in tables and lists
• Normalizes properties

Format a single document:

alchemy format connectedhomeip-spec/src/app_clusters/Thermostat.adoc

Format all documents in a directory:

alchemy format connectedhomeip-spec/src/app_clusters/*.adoc

Recursively format all documents in the spec:

alchemy format connectedhomeip-spec/src/\*\*/*.adoc

Disco-ball is more aggressive than format, and attempts to rewrite the document to the disco-ball standard:

• Everything format does
• Rearranges the document into disco-ball order for clusters and device-types
• Rearranges data types into bitmap, enum, struct order
• Promotes inline data types into the Data Types section and creates references for them
• Normalizes all references to the ref_PascalCase format
• Adds missing columns to tables for each type of section
• Reorders columns in tables to match disco ball order
• Renames headers in columns to match disco ball header names
• Re-formats access columns into disco ball order and spacing
• Re-formats constraint columns to be more readable (e.g. an uint with the constraint "0 to 60" -> "max 60", )
• Fixes command directions to client (<=/=>) server format
• Appends suffixes to sections when needed (e.g. "XyzBitmap" -> "XyzBitmap Type" or "MyField" -> "MyField Field")
• Uppercases all hexadecimal numbers
• Adds spaces after punctuation, when needed
• Adds labels to anchors when missing
• Removes extra spaces at the end of lines
• Fixes common section naming mistakes

Disco-ball a single document:

alchemy disco connectedhomeip-spec/src/app_clusters/Thermostat.adoc

Disco-ball the whole spec:

alchemy disco --specRoot connectedhomeip-spec

Disco-ball a single document, but update any other documents if needed (e.g. rewriting a reference):

alchemy disco --specRoot connectedhomeip-spec connectedhomeip-spec/src/app_clusters/Thermostat.adoc

ZAP generates zap-template XMLs from a spec, creating new XML files for provisional clusters, and amending existing XML files with changes.

alchemy zap --attribute="in-progress"  --sdkRoot=./connectedhomeip/ --specRoot=./connectedhomeip-spec/ ./connectedhomeip-spec/src/app_clusters/Thermostat.adoc

Compare loads the spec and the ZAP template XMLs and returns their differences in JSON format.

alchemy compare --sdkRoot=./connectedhomeip/ --specRoot=./connectedhomeip-spec/

Conformance parses a provided conformance string and explains its meaning in plain English. It can also take a series of defined identifiers and return whether the provided conformance would consider it mandatory, optional, etc.

$ alchemy conformance "[LT | DF & CF]"
description: optional if (LT or (DF and CF))

$ alchemy conformance "AB, [CD]"
description: mandatory if AB, otherwise optional if CD
$ alchemy conformance "AB, [CD]" AB CD
description: mandatory if AB, otherwise optional if CD
conformance: Mandatory
$ alchemy conformance "AB, [CD]" EF CD
description: mandatory if AB, otherwise optional if CD
conformance: Optional
$ alchemy conformance "AB, [CD]" EF
description: mandatory if AB, otherwise optional if CD
conformance: Disallowed

Data Model generates the Data Model XML files from the spec.

Testplan generates basic test plan adoc files from the spec.

Alchemy-db is provided as a separate binary. It loads up a set of spec docs or ZAP templates and exposes their contents as tables in a local MySQL server you can query.

alchemy-db --sdkRoot=./connectedhomeip/ --specRoot=./connectedhomeip-spec/