> ## Documentation Index
> Fetch the complete documentation index at: https://docs.embedder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SigmaStudio to XMOS

> Convert a SigmaStudio DSP project or other firmware into a reviewed plan and an XMOS implementation with Migration mode.

Migration mode ports an existing design to the XMOS board selected for your project. Use it for a SigmaStudio project (ADAU17xx or ADAU14xx `.dspproj`), or for MCU, DSP, FPGA, or older XMOS firmware. Embedder converts the source into a text design, plans the port with you, and implements the approved plan.

<Note>
  Migration mode appears only when the session's project targets an XMOS platform, including XK- and XD- board names. Select the target board before you start. See [XMOS](/supported-hardware/xmos).
</Note>

## Prerequisites

* An Embedder project whose platform is an XMOS board.
* For SigmaStudio: the `.dspproj` file and, ideally, its exported system files.
* Optionally, the original product's project folder: host code, tests, recordings, and schematics.

SigmaStudio+ (`.ssprj`) projects aren't supported.

## Export files from SigmaStudio

In SigmaStudio, choose **Action → Export System Files**. The export compiles without the board attached. Provide these files with the `.dspproj`:

| File | What Embedder reads from it |
| - | - |
| `<name>.params` | Every parameter of every block: name, address, value, and raw words. |
| `<name>.xml` | The same parameters plus each block's settings at export time. Embedder compares these with the saved project. |
| `<name>_IC_<n>_PARAM.h` | The number format of each parameter (`5.23`, `8.24`, and others) and full-precision values. |
| `<name>_NetList.xml` | The compiled blocks and links. Adds SigmaStudio's toolbox names and checks the decoded wiring. |

Embedder finds exports named after the project next to the `.dspproj`, in its `Export/` folder, or anywhere in the project folder you provide. Other export files (`_IC_<n>.h`, `_REG.h`, `.hex`, `.dat`, E2Prom) repeat this data, and Embedder skips them.

## Start a migration

<Tabs>
  <Tab title="VS Code">
    1. Choose **Migration** from the mode menu beside the chat input, or press `Shift+Tab` until the migration start dialog opens. The session switches to Migration mode when the migration starts; cancelling the dialog keeps the current mode.
    2. Under **Migrating from**, choose a source:
       * **SigmaStudio project**: choose the `.dspproj`. Add or remove export files, and optionally choose a **Project folder**. Embedder reads the folder in place and never uploads it.
       * **Something else**: choose the source folder, describe what the firmware does and what must carry over, or both.
    3. Review the live preview of blocks, inputs and outputs, sample rate, and blocks that need custom code.
    4. For a SigmaStudio project, optionally add **Notes for the agent**. Then select **Start migration plan**.
  </Tab>

  <Tab title="Terminal UI">
    Pass the project file or a folder to `/migration`:

    ```text theme={"system"}
    /migration hardware/dsp/amp.dspproj
    ```

    A folder that contains a `.dspproj` starts a SigmaStudio migration, and Embedder uses the folder as the project folder. If the folder contains more than one `.dspproj`, pass the project file instead. Any other folder starts a migration from that source folder.

    ```text theme={"system"}
    /migration ../legacy-amp
    ```

    `/migration` without a path switches to Migration mode without converting a source.
  </Tab>
</Tabs>

When the migration starts, Embedder:

1. Converts the source into `.embedder/migration/<slug>/`.
2. Switches the session to Migration mode.
3. Loads the `xmos-migration` and `xmos-shared-memory` [skills](/core-concepts/skills) along with the board's XMOS skills. SigmaStudio migrations also load `sigmastudio-migration` and `xmos-audio-dsp`.
4. Sends a start message that summarizes the source, the target board, and the converted design.

## Review the converted design

A SigmaStudio migration folder contains:

| Path | Content |
| - | - |
| `design.txt` | The decoded SigmaStudio design, one record per line. |
| `data/` | Long arrays (FIR taps, tables), large parameter lists, and register snapshots referenced from `design.txt`. |
| `README.md` | Device, sample rate, block counts, issues, and the project folder's file tree when you provided one. |
| `source/` | Copies of the `.dspproj` and the export files used. |

A migration from another source writes only a `README.md` with a survey of the source folder.

`design.txt` replaces the binary `.dspproj` as the source of truth for the migration. It lists the device and sample rate, I/O cells, every block, its parameters, and the wires between blocks. Each block carries an `xmos=` status that says how it maps to XMOS:

| Status | Meaning |
| - | - |
| `stage` | A `lib_audio_dsp` stage implements the block. |
| `module` | A `lib_audio_dsp` module function covers it in custom C. |
| `approx` | A stage comes close but differs. Embedder states the difference and asks you to accept it. |
| `custom` | Nothing in `lib_audio_dsp` does it. Embedder writes new C, a Python model, and a unit test. |
| `io` | An input or output cell to map to a codec channel, I²S/TDM slot, or S/PDIF. |
| `unknown` | Embedder does not recognize the algorithm and asks you about it. |

```text theme={"system"}
block id=B12 path="Main/Volume" kind=volume class=SingleSliderMed alg=Gain1940AlgNS xmos=stage stage=VolumeControl in=1 out=1
param id=B12 path="Main/Volume" name=gain value=-6 unit=dB min=-80 max=0 res=40 scale=log control=slider
wire from=B7.out0 to=B12.in0 from_path=Main/EQ1 to_path="Main/Volume"
```

Embedder copies `design.txt` and `data/` into the XMOS app so parameter scripts and reference models build from files in the repository.

### Warnings in `design.txt`

Problems appear as `issue` records. Two depend on the export files:

* **`stale_export`**: a setting differs between the saved `.dspproj` and its exports. Embedder asks which version the product ships instead of picking one. Re-export from SigmaStudio if the project is the current version.
* **`missing_internals`**: an ADI fixed-function block keeps values that the `.dspproj` never stores, and the export files don't supply them. Affected blocks include DC block, level detectors, band analyzers, signal detect, dynamic bass, Super Bass, Phat Stereo, curve-table compressors, slewed mutes, and oscillators. Provide the export folder to resolve it. Otherwise, Embedder designs the block from ADI's documentation, reports it as an approximation, and checks it against recordings of the original hardware when you have them.

Other issue kinds flag unknown blocks, cycles, unconnected pins, protected boards, and exports that disagree with the project (`export_mismatch`).

## Plan, approve, and implement

Migration mode works like [Plan mode](/core-concepts/modes#plan-review-an-approach-before-implementation) until you approve the plan. Embedder studies the design and the board, then asks only what the files cannot answer: I/O mapping, sample rate and latency, which controls stay tunable, and each approximate or unsupported block. The plan covers the feature map, architecture and cycle budget, test steps, and risks.

After you approve the plan, Embedder implements it in Act mode. An approved plan can assign independent steps to [subagents](/core-concepts/subagents).

```text theme={"system"}
Keep the carrier frequency adjustable over I²C, map Input1 to the board's ADC
channel 0, and compare the output against the captures in tests/recordings/.
```

For general porting practice, see [Platform migrations](/solutions/platform-migrations).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.