UnderAutomation
⌘Q

The format of a backup

The folder of a backup, every field of touchup-backup.json, the hashes, the profile, the files that the controller refused, the JSON schema, a Python script that reads and checks a backup without TouchUp, and the rules of versioning.

  • Folder layout
  • The manifest: touchup-backup.json
  • Fields
  • Type of backup
  • Skipped files
  • The CMOS image of a Yaskawa controller
  • The mastering snapshot of a Fanuc robot
  • Checksums
  • Links
  • Read a backup with a script
  • The JSON schema
  • Versioning
  • What to read next

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 and the JSON schema of the manifest.

Folder layout

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

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

FieldRequiredMeaning
schemaVersionyesThe version of the format: 1. See Versioning
controlleryesThe controller that was backed up
controller.idyesThe id of the controller in the TouchUp configuration. The backups of one controller share it, so that TouchUp finds the previous one
controller.nameyesThe name of the controller in TouchUp
controller.brandyesfanuc or yaskawa. A simulated controller writes simulated
controller.modelnoThe model read from the controller (R-30iB Plus, YRC1000), or null
controller.softwarenoThe software version, or null
controller.serialnoThe serial number, or null
takenAtyesThe date of the backup, in ISO 8601 with an offset. TouchUp writes UTC (+00:00)
takenByyesuser@machine of the session of the PC that took the backup
touchupVersionyesThe version of TouchUp that wrote the backup
sdkVersionyesThe library that talked to the controller
filesyesThe files of the controller, text and binary. An empty list is valid
files[].pathyesThe path below the backup folder, with /, always starting with files/
files[].sizeyesThe size of the file on the disk, in bytes
files[].sha256yesThe SHA-256 of the bytes of the file on the disk, 64 lowercase hexadecimal digits
files[].normalizedSha256noText files only: the SHA-256 of the normalized text, see Checksums
files[].encodingnoText 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
normalizationnoThe set of rules that the normalizedSha256 values were made with: rules (fanuc or yaskawa) and version. Absent when no rule applies
profilenoThe type of backup that chose the files, see Type of backup
skippednoThe files that the controller refused to send. They are not in the backup, see Skipped files
binarynoThe binary backups, below binary/: the CMOS image of a Yaskawa controller. Same entries as files, without normalizedSha256 and encoding. Compared by checksum only
summarynoWhat 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.

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.

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 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.

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 codeMeaning
0Every file is present, with the size and the checksum of the manifest
1A file is missing or differs
2The 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 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
  • Compare backups and controllers
  • Robot report and handover pack, to give backups to a customer in one file