-
Notifications
You must be signed in to change notification settings - Fork 0
Extron IP Link driver format
There are two type of files used by Extron to distribute IP Link control system drivers: .pke and .pkn.
Under the hood they are exactly the same, but .pke is used for Serial drivers, while .pkn is used for Ethernet drivers.
From now on, to avoid confusion, .pke and .pkn files will be simply called packages.
Note
Ethernet drivers only support Telnet (or Telnet-like) communication: raw bytes over TCP connection. While this is fine for older devices, the lack of flexibility can be an issue with modern HTTP-controlled devices.
The file names of the packages are composed of 4 parts, separated by underscore:
- Abbreviation of the name of the control system manufacturer
- Number representing the device type
- Unique number representing the driver
- Major version number
Take extr_15_4643_19.pkn as an example: it is an Ethernet driver (.pkn) for a Matrix Switcher (15) from Extron (extr) and the major version is 19.
The manufacturer abbreviations and the device types are described in the C:\Users\Public\Documents\Extron\driver2\lookup.xml file created by GC3.
The .pke/.pkn packages are custom compressed archives. The specific files are described later.
The package start with a 32-byte header. The fields are described in the following table:
| Name | Size | Description |
|---|---|---|
| Magic | 4 bytes | Always NTXE (4E 54 58 45) |
| Magic2 | 4 bytes | One of GKPE (47 4B 50 45), EKPE (45 4B 50 45), IKPE (49 4B 50 45), UKPE (55 4B 50 45) |
| Major Version | 2 bytes (little endian) | See below |
| Minor Version | 2 bytes (little endian) | See below |
| Unused | 4 bytes | Usually 00 00 00 00 or 55 55 55 55 in official drivers |
| Flags | 1 byte | This value is always 0 or 1, meaning not yet clear |
| Unused2 | 11 bytes | Always 0 |
| ToC location | 4 bytes (little endian) | Position of the Table of Content in the package |
They make way more sense if read backward. Maybe there was an endianness ambiguity when first defining the file format.
As for Magic2, only GKPE is found in official drivers, but the other values are also treated as valid by GC3.
They usually match the value found the XML file, but the major=5, minor=0 combination is a wildcard and can be used regardless of the content of the XML file.
The ToC describes all the files contained in the package. The header defines the position of the ToC in the file, but not its length. This means that it can only appear at the end of the package, with the size being implicit.
The offset in the header actually point to 4 bytes representing the size of the ToC after decompression (in little endian). After that we find the actual compressed ToC. The compression algorithm is LZSS, using the original parameters from Haruhiko Okumura's 1989 implementation.
Once decompressed, the format is the following:
| Name | Size | Description |
|---|---|---|
| Number of entries | 4 bytes (little endian) | |
| Entry 1 | Variable | |
| Entry 2 | Variable | |
| ... | ... | ... |
| Entry N | Variable | |
| End of ToC | 4 bytes | All zeroes |
Each entry follows this format:
| Name | Size | Description |
|---|---|---|
| Filename length | 4 bytes (little endian) | Length of the filename following |
| Filename | Variable | Not null-terminated, length provided by previous field |
| Unused | 4 bytes | Always 0 |
| Unused2 | 4 bytes | Always 0 |
| Unknown | 9 * 4 bytes (little endian) | Not yet decoded, can be set to 0 if the file is re-written |
| Decompressed file size | 4 bytes (little endian) | File size after decompression (equal to the compressed size if the file is not compressed) |
| Compressed flag | 4 bytes (little endian) | Flag is 1 if the file is compressed, 0 if not compressed |
| Compressed file size | 4 bytes (little endian) | File size in the package |
| File position | 4 bytes (little endian) | Pointer to the start of the file in the package |
Note
- The file position is absolute (does not exclude the 32-byte header).
- If the compressed flag is 1, the file is compressed with LZSS (same parameters as the header).
A packages usually contains the following files:
- A .pdf file explaining the driver and the available commands
- A .xml file describing the commands and input values available
- A .sc file containing the logic (in C language) of the driver (used by IPL/IPCP devices)
- A .str file containing a subset of commands. Can only be present in Serial (.pke) drivers, and is used by MLC devices.
Only the .xml and .sc files are mandatory. A missing .str file means the driver is not compatible with MLC devices, while a missing PDF means you don't get a human-readable description of the driver. Any other file in the package is ignored by GC3.
Important
The name of the contained files must match the one of the package, excluding the file extension of course.
The best way to understand the format of the XML and SC files is to take a look at a bunch of extracted driver packages. Below I will give you just a small introduction to them, focusing on the remarks I found.
This file describes the driver and the available commands. It is divided in two parts.
The first part describes the models supported by the driver and their communication parameters. The second part describes the commands and their allowed values.
Important
The driver_name attribute in the driver tag must match the file name.
The driver_version and driver_minor_version attributes must match the values in the header, if the wildcard combination is not used.
It actually represents some sort of maturity status of the driver, according to the following table:
| Value | Description |
|---|---|
| 0 | Work In Progress |
| 1 | Beta |
| 2 | Released |
| 3 | Custom |
| 4 | Not Working |
| 5 | Archived Beta |
| 6 | Archived Released |
The cmd_id and state_id attributes are used to match commands and states when switching driver on the same port. It is therefore recommended to try and match them to known values from Extron's pool. Unfortunately, there is no database and the only way to find the appropriate ID would be to take a look at other drivers.
The control_type_id attribute specifies the type of the control. Other attributes in the state tag can be omitted or left blank if not used by the specific type.
The commands can be input-only, output-only or bidirectional. The output value is passed to the driver logic via the variable defined in the set_label attribute, while the input value is read in the variable specified in the query_label attribute.
Output-only. The active value is selected from a list.
Type 1 is used for simple press commands, while type 12 for toggle switches (the second press produces a different value). Type 5 is never seen in official drivers.
Input-only. The active value is selected from a list.
Bidirectional. They select or show a value in a range, with an optional measurement unit and defined incremental steps.
The difference between the two is that type 3 selects its values from a drop-down menu, while type 9 feature an actual slider in GlobalViewer.
Input-only. Unlike type 2, it gets the value directly, not from a list.
The name is not entirely accurate, since the value is actually an integer, and not text.
Bidirectional. The active value is selected from a list.
Can be seen as a combination of types 1 and 2.
Type 11 is never seen in official drivers.
This is a special type used mainly for Matrix Switcher devices. It defines only the query_label attribute but it doesn't use it.
Unlike all the other types, each state has its own variable that can be used as input or output.
The logic of the driver resides in the .sc file. The programming language used is a slightly modified version of C.
Some non-standard pre-processing directives are added to define communication parameters, headers can not be included (built-in functions are always available), and int init() is called prior to int main().
There is no documentation for this language, so I suggest copying the coding patterns found in official drivers, even if they feel counterintuitive.
The variables mentioned in the XML file are ints declared as global variables. Other types can be freely used, including pointers.
The .str file is a password-protected ZIP archive, but the ZIP magic number (PK) has its characters swapped, so 50 4B 03 04 becomes 4B 50 03 04, 50 4B 07 08 becomes 4B 50 07 08 and so on.
I don't know if this is an obfuscation measure or some kind of endianness mistake made decades ago.
Anyway, the password is the filename itself, without the extension. You can extract the zip file by manually fixing it, or by using a modified zip library.
The content of the zip file is again a .str file, but this time it is in cleartext. This inner file is just an XML.
There's not much to say about it. It is just a list of commands with the Serial command strings directly attached. It is used by MLC devices, which are much simpler than IPL/IPCP devices.
Important
If you plan to create a new .str file, or modify an existing one, make sure you can manually tune the parameters of the compression tool.
Many of them will default to ZIP64 and set various size values to FF FF FF FF.
This will lead GC3 to fail spectacularly.