This page describes the format of a TouchUp backup, so that a script or another tool can read it without TouchUp, and so that you can keep backups in Git or in an archive for years. It applies to the backups of Fanuc and Yaskawa controllers.

A backup is a plain folder: the files of the controller as they were received, and one JSON file that lists them with their checksums. Two files help you read it: the script [read_backup.py](/touchup/documentation/backup-format/read_backup.py) and the [JSON schema](/touchup/schemas/touchup-backup.schema.json) of the manifest.

## Folder layout

TouchUp creates one subfolder per backup in the folder that you choose:

```text
D:/Backups/                           the folder that you chose
└─ Cell 3 Fanuc-2026-10-04-0212/      one subfolder per backup: <controller name>-<yyyy-MM-dd-HHmm>, local time
   ├─ touchup-backup.json             the manifest
   ├─ mastering.json                  Fanuc only: the mastering snapshot
   ├─ files/                          the files of the controller, text and binary, as received
   │  ├─ PICK.LS                      Fanuc: the folder of the controller (MD:) is dropped
   │  └─ ...
   └─ binary/                         Yaskawa only, when the CMOS backup was asked for
      └─ CMOSBK.BIN
```

- A subfolder whose name starts with a dot is a backup in progress or a failed one. TouchUp writes the whole backup in that hidden folder and renames it at the end, so a folder without the dot is complete. Ignore the hidden ones.
- Two backups of the same controller in the same minute get `-2`, `-3` after the name.
- `files/` holds the files at the path that the type of backup gives them. A Fanuc backup puts every file in `files/` (`/MD/PICK.LS` is `files/PICK.LS`). A Yaskawa backup keeps the folders of the controller: `files/JOB/MAIN.JBI`, `files/DAT/VAR.DAT`, `files/PRM/RS.PRM`.
- A controller that lists two names that differ only by upper and lower case fails the backup, because Windows could not keep both.
- The bytes of a file in `files/` are the bytes that TouchUp received. A text file is decoded from the controller and written again with the encoding of its entry. A binary file is written as it came. TouchUp never changes a file afterwards.
- A backup taken before the fix of the Shift JIS encoding of Fanuc files may hold the character U+FFFD in such a file. This is what the controller sent to TouchUp, and a restore writes it back.

## The manifest: touchup-backup.json

The manifest is strict JSON, in UTF-8, with keys in camel case. `schemaVersion` is `1`.

```json
{
  "schemaVersion": 1,
  "controller": {
    "id": "6f1c0a52-3c55-4c3b-9a43-0f3e1d1b7a10",
    "name": "Cell 3 Fanuc",
    "brand": "fanuc",
    "model": "R-30iB Plus",
    "software": "V9.40P/27",
    "serial": "F12345"
  },
  "takenAt": "2026-10-04T02:00:12+00:00",
  "takenBy": "jdupont@WS-12",
  "touchupVersion": "1.0.0",
  "sdkVersion": "UnderAutomation.Robotics 1.0.0",
  "files": [
    {
      "path": "files/PICK.LS",
      "size": 5123,
      "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "normalizedSha256": "60303ae22b998861bce3b28f33eec1be758a213c86c93c076dbe9f558c11c752",
      "encoding": "shift_jis"
    }
  ],
  "normalization": { "rules": "fanuc", "version": 3 },
  "profile": { "name": "All of above", "version": 1, "id": "fanuc-all-of-above" },
  "skipped": [{ "path": "/MD/PARAM.PRM", "reason": "The controller refused the file: it is open in the editor" }],
  "binary": [{ "path": "binary/CMOSBK.BIN", "size": 8388608, "sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae" }],
  "summary": "2 changed, 0 added, 0 removed"
}
```

### Fields

| Field | Required | Meaning |
| --- | --- | --- |
| `schemaVersion` | yes | The version of the format: `1`. See [Versioning](#versioning) |
| `controller` | yes | The controller that was backed up |
| `controller.id` | yes | The id of the controller in the TouchUp configuration. The backups of one controller share it, so that TouchUp finds the previous one |
| `controller.name` | yes | The name of the controller in TouchUp |
| `controller.brand` | yes | `fanuc` or `yaskawa`. A simulated controller writes `simulated` |
| `controller.model` | no | The model read from the controller (`R-30iB Plus`, `YRC1000`), or `null` |
| `controller.software` | no | The software version, or `null` |
| `controller.serial` | no | The serial number, or `null` |
| `takenAt` | yes | The date of the backup, in ISO 8601 with an offset. TouchUp writes UTC (`+00:00`) |
| `takenBy` | yes | `user@machine` of the session of the PC that took the backup |
| `touchupVersion` | yes | The version of TouchUp that wrote the backup |
| `sdkVersion` | yes | The library that talked to the controller |
| `files` | yes | The files of the controller, text and binary. An empty list is valid |
| `files[].path` | yes | The path below the backup folder, with `/`, always starting with `files/` |
| `files[].size` | yes | The size of the file on the disk, in bytes |
| `files[].sha256` | yes | The SHA-256 of the bytes of the file on the disk, 64 lowercase hexadecimal digits |
| `files[].normalizedSha256` | no | Text files only: the SHA-256 of the normalized text, see [Checksums](#checksums) |
| `files[].encoding` | no | Text files only: the encoding of the bytes when it is not UTF-8, for example `shift_jis` (what the Japanese controllers use). A text file with no label is UTF-8. A file with no `normalizedSha256` is binary and has no label |
| `normalization` | no | The set of rules that the `normalizedSha256` values were made with: `rules` (`fanuc` or `yaskawa`) and `version`. Absent when no rule applies |
| `profile` | no | The type of backup that chose the files, see [Type of backup](#type-of-backup) |
| `skipped` | no | The files that the controller refused to send. They are not in the backup, see [Skipped files](#skipped-files) |
| `binary` | no | The binary backups, below `binary/`: the CMOS image of a Yaskawa controller. Same entries as `files`, without `normalizedSha256` and `encoding`. Compared by checksum only |
| `summary` | no | What changed since the previous backup of the same controller, as one line for people |

A field that is not required is written only when it has a value, except the `null` of the three optional fields of `controller`. The manifest of an older version of TouchUp has fewer fields and stays valid.

### Type of backup

`profile` names the type of backup, the choice of files that was made in the backup dialog:

- `name` is the name as the pendant shows it (`All of above`, `TP Programs`...). It is for people and can change in a later version.
- `version` is the version of the type, `1`.
- `id` is the stable identifier: `fanuc-all-of-above`, `fanuc-tp-programs`, `fanuc-system-files`, `fanuc-application`, `fanuc-error-log`, `yaskawa-text-files`, `yaskawa-job`, `yaskawa-job-and-data`, `yaskawa-parameter`, `yaskawa-io-data`, `yaskawa-system-data`. An id is never renamed. It is optional in the file.

To find the type: read `id` first. A manifest with a `name` and no `id` is the type of its brand with that name. A manifest with no `profile`, made before the types existed, is the default type of the brand of its controller (`fanuc-all-of-above` or `yaskawa-text-files`). Two backups of different types are compared on the files that both hold.

### Skipped files

A `skipped` entry is `{ "path", "reason" }`. The `path` is the path on the controller (`/MD/PARAM.PRM`), not a path below `files/`: the file is not in the backup. The `reason` is the message of the controller, without secrets. A skipped file is not "removed" in a compare with another backup: nothing can be said about it.

The CMOS image uses the same list. When the controller refuses it, when it takes more than 15 minutes, when the link is lost or when you cancel while it is generated, the text backup is kept and `skipped` gets an entry with the path `/SPDRV/CMOSBK.BIN` and the reason. No `binary` entry is written then.

### The CMOS image of a Yaskawa controller

On a Yaskawa controller you can ask for the CMOS backup too. TouchUp stores it as `binary/CMOSBK.BIN`, with an entry in `binary`. It is not text. A compare tells whether it is identical (same `sha256`) or different, never what changed. See [CMOS backup of a Yaskawa controller](/touchup/documentation/backup#cmos-backup-of-a-yaskawa-controller).

## The mastering snapshot of a Fanuc robot

`mastering.json` is next to the manifest. It keeps the mastering values that TouchUp read from `sysmast.va` in the same backup, so that the values of a robot at the date of the backup are not lost. It is not in the manifest and not in `files/`: the check of the checksums does not list it, and a compare never sees it. A backup without it has no snapshot. It has its own `schemaVersion`.

```json
{
  "schemaVersion": 1,
  "takenAt": "2026-10-04T02:00:12.0000000+00:00",
  "source": "files/sysmast.va",
  "groups": [
    {
      "group": 1,
      "masterDone": true,
      "refDone": true,
      "calibMode": 0,
      "masterCount": [141401, -42524, 846887, -353230, -392328, 5345317, 0, 0, 0],
      "refPos": [0, 0, 0, 0, 0, 0, 0, 0, 0],
      "refCount": [141417, -42545, 846850, -353218, -392359, 5345334, 0, 0, 0]
    }
  ]
}
```

`source` is the file of the backup that the values come from. `masterCount` is `$MASTER_COUN`, `refPos` is `$REF_POS` (degrees or millimeters) and `refCount` is `$REF_COUNT`, one value per axis: 9 values for a Fanuc robot, and an axis without a motor reads 0.

## Checksums

- `sha256` is the SHA-256 of the bytes of the file as they are on the disk, in lowercase hexadecimal. To check a backup, read the file, compare its size with `size` and its checksum with `sha256`. A difference means that the file changed after the backup, or that the copy is bad.
- `normalizedSha256` is the checksum that TouchUp compares text files with. The bytes are decoded with the `encoding` of the entry (UTF-8 when there is none). The rules named in `normalization` are applied: they drop the lines that change at every backup, such as the creation date of a Fanuc `.LS` file, they sort the blocks of a `.VA` file, and they make the line ends and the trailing spaces equal. The SHA-256 of the result, in UTF-8, is written. The rules ship with TouchUp, so a script cannot always compute this value again. Use `sha256` to check a file.
- TouchUp uses a stored `normalizedSha256` only when `normalization` is the same in both backups (`rules` and `version`). Otherwise it normalizes the file again with its current rules.
- Compare of two files: the same `sha256` means identical. A text file with another `sha256` and the same normalized checksum has a cosmetic change only (a date, a line end). Two different normalized checksums mean a functional change. A binary file is compared by its `sha256` only.
- `mastering.json` has no checksum and is never compared.

### Links

A backup can come from elsewhere: a shared drive, the pack of a colleague. A link in it could lead to any file of the PC. TouchUp therefore never reads a file below `files/` that is a link (a symbolic link or a junction), or that is in a folder that is a link. A compare, a restore or an AI tool refuses it. TouchUp never writes a link in a backup. A script of yours must do the same. `read_backup.py` reports a link, or a path with `..`, as `MISSING`.

## Read a backup with a script

[read_backup.py](/touchup/documentation/backup-format/read_backup.py) uses Python 3 only (3.8 or later), with no other package. It treats the backup as a folder that you do not trust.

```bash
python3 read_backup.py "D:/Backups/Cell 3 Fanuc-2026-10-04-0212"
python3 read_backup.py "D:/Backups/Cell 3 Fanuc-2026-10-04-0212" --show files/PICK.LS
```

It reads the manifest, checks the size and the SHA-256 of every file of `files` and `binary`, and prints the controller, the type of backup, the normalization, the files with their encoding, the skipped files and whether `mastering.json` is there. `--show` also prints one text file, decoded with its encoding: at most 1 MiB, with the control characters replaced.

```text
Backup of Cell 3 Fanuc (fanuc R-30iB Plus) taken 2026-10-04T02:00:12+00:00 by jdupont@WS-12 with TouchUp 1.0.0
Profile: All of above (id fanuc-all-of-above)
Normalization: rules fanuc, version 3
Files (2):
  OK             files/PICK.LS  (5123 bytes)  text, encoding shift_jis
  OK             files/sysmast.va  (6210 bytes)  text, encoding shift_jis
Skipped by the controller (1), not in the backup:
  /MD/PARAM.PRM: The controller refused the file: it is open in the editor
mastering.json: present (not in the manifest)
2 files checked, 0 problem(s)
```

| Exit code | Meaning |
| --- | --- |
| `0` | Every file is present, with the size and the checksum of the manifest |
| `1` | A file is missing or differs |
| `2` | The manifest is missing, is not valid, or has a `schemaVersion` that the script does not know. Also a `--show` of a file that is not in the manifest, is binary or has an unknown encoding |

## The JSON schema

The [JSON schema](/touchup/schemas/touchup-backup.schema.json) describes `touchup-backup.json` (draft-07). TouchUp uses it in the editor: when you open a `touchup-backup.json` file in VS Code, the editor checks it and completes the field names. You can use it in your own tool to check a manifest.

The schema accepts fields that it does not know, as the rules below say.

## Versioning

The format is versioned by `schemaVersion` of the manifest.

- The manifest stays at `schemaVersion` 1. A change that only adds is not a new version.
- New fields are optional and only added. A field of version 1 is never removed, renamed or given another meaning, and a field that is optional is never made required.
- A reader ignores the fields that it does not know, at the top level and in every entry. The schema does the same, so a manifest with a new field is valid.
- A breaking change raises `schemaVersion`. TouchUp then reads the old versions too: an old backup stays readable by every later TouchUp. A reader that meets a `schemaVersion` that it does not know must not guess. TouchUp leaves such a backup out of its lists, and `read_backup.py` ends with the code 2.
- `mastering.json` has its own `schemaVersion`, with the same rules.

## What to read next

- [Back up a controller](/touchup/documentation/backup)
- [Compare backups and controllers](/touchup/documentation/compare)
- [Robot report and handover pack](/touchup/documentation/report-and-handover), to give backups to a customer in one file