Metadata-Version: 2.4
Name: migratorisk
Version: 0.3.0
Summary: Local-first NCS / Zephyr SDK upgrade risk analyzer
Author: VelocityCreate
License-Expression: Apache-2.0
Project-URL: Homepage, https://velocitycreate.com
Keywords: nrf-connect-sdk,ncs,zephyr,firmware,sdk-migration,embedded,nordic
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Embedded Systems
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jinja2>=3.1
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: setuptools>=77; extra == "dev"
Requires-Dist: twine>=6.1; extra == "dev"
Dynamic: license-file

# Migratorisk by VelocityCreate

Free, local-first assessment of a planned **nRF Connect SDK**, **Zephyr**,
**ESP-IDF** or **Silicon Labs Gecko SDK / Simplicity SDK** upgrade, including moves to the
**NCS 3.4 LTS** line and from Gecko SDK to Simplicity SDK. Every NCS release from
1.0.0 to 3.4.2 can be used as the source or target, Zephyr releases up to 4.5.0 are
supported, ESP-IDF releases from 1.0 to 6.1 (including GNU Make projects) (`--from esp-idf-4.4.6 --to esp-idf-6.1.0`), and Silicon Labs Gecko SDK 4.0 to 4.5 and Simplicity SDK 2024.6 to 2026.6 (`--from gsdk-4.4.0 --to sisdk-2025.6.3`). Migratorisk scans your firmware project's configuration, build,
devicetree, partition and source files on your own computer, then writes a
report of likely migration work: what was found, why it matters, and what to
check next.

- **Your source code stays on your computer.** Scanning makes no network connections.
- **Full results without sign-up.** The local report includes every finding in scope.
- **Sharing is optional.** You can preview a sanitized summary and choose whether
  to send it to VelocityCreate if you want help with the migration.

Migratorisk predicts migration risk from project evidence and
official-source-backed rules. It does not prove that a migration is correct,
complete, or safe to ship. Builds, device tests and OTA verification are still
required.

## Requirements

- Python 3.12 or newer (`python --version`)
- Windows, macOS or Linux

## Install

Recommended, with [pipx](https://pipx.pypa.io/) (keeps Migratorisk in its own environment):

```bash
pipx install migratorisk
```

Or with pip:

```bash
python -m pip install --user migratorisk
```

On Windows you can use `py -m pip install --user migratorisk`.

Check the install:

```bash
migratorisk --version
```

## Scan your firmware

1. Find your SDK versions. List what this version can check:

   ```bash
   migratorisk supported
   ```

2. Run the scan on your **application folder** (the folder with `prj.conf` and
   `CMakeLists.txt`, not the SDK or west workspace root):

   ```bash
   migratorisk scan --project path/to/your-app --from ncs-2.9.0 --to ncs-3.0.0 --out report.html
   ```

   Optional: `--board <board-name>` and `--profile <short label>` (for example
   `ble_ota`) add context to the findings.

   **Tip:** build the project once with your current SDK (`west build`) before
   scanning. Migratorisk then also reads the configuration the build actually
   uses (every image's merged `.config`, enabled devicetree nodes, the generated
   flash layout, the board and the SDK version), so
   features the SDK turns on by default are covered. It looks in
   `<project>/build`; point it elsewhere with `--build-dir`, or skip it with
   `--no-build`. If the build was made with a different SDK than `--from`, the
   report says so.

3. Open `report.html` in your browser. A `report.json` copy is written next to it.

The scan reads files only. It does not build, modify or upload your project.
It only reads a build folder that already exists.

## Share a sanitized summary (optional)

If you would like VelocityCreate to review the assessment or quote the
migration, you can share a sanitized summary. First see exactly what would be
sent. This command sends nothing:

```bash
migratorisk export-share --report report.json --out shared-report.json
```

The shared summary contains only the SDK versions, the scanner and rule-pack
versions, a fingerprint of the bundled rule catalog, the time it was generated,
and the IDs of the findings. Explanations are looked up from the published rule
catalog, not taken from your project. It does **not** contain source code or
snippets, configuration values, build logs, file names or paths, board or
profile names. Your full local report always stays on your computer.

To send it, get a one-time upload token from the Migratorisk assessment website
("Prepare optional report sharing"); the site shows the exact command, which
looks like:

```bash
migratorisk share --report report.json --server <assessment site address> --token <token>
```

The command prints the exact JSON and asks you to confirm before anything is
sent. After sharing it saves `sharing-receipt.json`: keep it private, because
it contains the key that lets you delete the shared report. The results link on
its own cannot delete the report. If sharing fails, your local report is
unaffected. Contact details are only collected if you choose to request a
migration discussion on the website.

## Troubleshooting

| Problem | What to do |
|---|---|
| `migratorisk` is not recognized / command not found | Run `python -m migratorisk ...` (Windows: `py -m migratorisk ...`), or run `pipx ensurepath` and open a new terminal. |
| `requires a different Python` or install fails on version | Install Python 3.12 or newer and use it explicitly, e.g. `py -3.12 -m pip install --user migratorisk`. |
| `Unsupported upgrade path` | Check spelling with `migratorisk supported`. Paths that are not covered are reported as unsupported rather than given a risk rating. |
| Scan is slow or reports SDK files | Point `--project` at your application folder, not the west workspace that contains the SDK checkout. |
| No findings | No matching findings were detected in the checks performed. This does not prove the upgrade is safe; see the coverage notes in the report. |

## About

Migratorisk is made by [VelocityCreate](https://velocitycreate.com), which
offers SDK migration implementation for embedded teams. The assessment is
free; migration work is quoted separately. Licensed under Apache-2.0.
