ISU - Format

The “isu_format” module includes structure definitions for the binary ISU format and provides an API to interact with those files. In previous versions of this project, you had to select the appropriate ISUInspector class. However, with recent updates, this class is no longer required, making the API more user-friendly.

Here’s an example of how to use the API:

>>> from fsapi.isu_format import ISU
>>> isu = ISU.parse_file("/path/to/file")
>>> # Or with the lshift operator
>>> isu = ISU << "/path/to/file"

By calling the parse_file method from the ISU class and providing the path to the file, you will now be able to inspect the binary.

Structures

This section comprises a list of structures used internally for parsing ISU files. In this documentation, all structures will be presented in a pattern format that can be employed within the ImHex editor.

isu::Header
 1// header structure
 2struct ISUHeader {
 3    le u32 magic; // 0x1176; file signature
 4    le u32 length;
 5    le u32 isu_version;
 6
 7    char version[32]; // version string (padded)
 8    char customisation[64];// firmware string (padded)
 9
10    if (this.length == 0xA2) {
11        // Extended headers contain major and minor version strings
12        char major_version[6];
13        char minor_version[32];
14    }
15
16    type::GUID uuid; // maybe a UUID (never valid)
17};

Note

You can access all fields displayed in a structure definition within python code. For instance:

>>> isu = ISU.parse_file("firmware.isu.bin")
>>> header = isu.header
>>> header.customisation
'ir-mmi-FS2026-0500-0795'

Integer types will be mapped to int, string fields to python strings, function declarations to python functions and so on. Optional values will be None if not present

isu::DataField and isu::DataSection
 1struct ISUDataField {
 2    le u16 length; // the size of this struct
 3    le u16 unknown_1;
 4    le u16 name_length;
 5    le u16 flags; // not sure
 6    char name[16]; // padded
 7
 8    if (this.length == 32) {
 9        le u32 value;
10        le u32 unknown_2;
11    }
12};
13
14// Use this field with caution
15struct DataSection {
16    le u8 magic; // always 128 = 0x80
17    le u8 length;
18    le u8 data[this.length];
19};

Directory Archive Structures

The Python implementation of directory archive structures is special and will be demonstrated using Python class definitions.

class IndexEntryType(enum.IntEnum):
    File = 0x00
    Directory = 0x01

class ISUArchiveIndexEntry:
    type: IndexEntryType
    name_length: int
    name: str
    content: ISUArchiveIndexDirectoryEntry | ISUArchiveIndexFileEntry

class ISUArchiveIndexFileEntry:
    size: int
    offset: int
    compressed_size: int

class ISUArchiveIndexDirectoryEntry:
    entry_count: int
    entries: list[ISUArchiveIndexEntry]

class ISUArchiveIndex:
    length: int
    name: bytes # always 0
    entry_count: int
    entries: list[ISUArchiveIndexEntry]

class ISUArchive:
    magic: bytes
    size: int
    unknown_1: int
    index_size: int
    index: ISUArchiveIndex
    data: bytes