Un outil pour manipuler les fichiers d'archive des automates Schneider Electric

Cet outil permet d'extraire et de réassembler les fichiers d'archive des automates Schneider Electric, notamment les M580, M340 et Quantum. Les fichiers d'archive avec l'extension .sta sont en réalité des archives zip contenant quelques fichiers. Dans l'archive, le fichier vraiment important est nommé Station.apx. Le contenu de ce fichier est ce qui est transféré depuis/vers l'automate lors d'un téléchargement/téléversement complet du programme. Naturellement, il contient le code exécutable réel du programme de l'automate. Mais il contient également toutes les informations nécessaires pour éditer le programme de l'automate dans Control Expert Classic (ou Unity Pro). Le format du fichier .apx est propriétaire, et peu d'informations sont disponibles à son sujet. Un peu d'informations sont disponibles sur Liras en la red et Team82, mais ce travail va plus loin que ce qu'ils ont publié. Avec cet outil, les différentes « sections » du Station.apx peuvent être extraites (et décompressées si nécessaire) pour examen. L'outil peut également réassembler le Station.apx à partir de données de section et métadonnées précédemment extraites – et peut-être modifiées. Et ce fichier réassemblé s'ouvrira sans erreur dans Control Expert Classic / Unity Pro, à condition que les modifications apportées ne brisent pas la « logique des sections ».

Motivation

Il n'y a jamais eu de grand plan avec ce projet. J'utilise des automates Schneider Electric de temps en temps, et j'étais intéressé par leur fonctionnement (ou non) à un niveau plus fondamental. Il s'est avéré que cette investigation était suffisamment complexe pour me divertir (probablement comme résoudre des mots croisés pour les gens normaux), et j'ai fini par créer cet outil.

Avertissement

L'outil fait de son mieux pour extraire et réassembler les fichiers avec lesquels il travaille. Cependant, l'utilisateur doit être conscient que l'outil a été développé avec :

• Une compréhension limitée du format de fichier .apx (et .sta)
• Une validation d'entrée limitée, ce qui signifie qu'il plantera plutôt ou fera quelque chose de mal plutôt que d'abandonner sans essayer
• Écrase les fichiers précédents sans demander
• Tests limités sur différents automates et versions de logiciels de programmation
• Tests limités de la fonctionnalité du code

L'utilisation de fichiers réassemblés sur un automate réel peut causer des problèmes, surtout si vous avez modifié les sections ou les métadonnées. Il est même possible que cela puisse briquer l'automate. Téléversez donc des fichiers d'archive modifiés sur l'automate à vos propres risques.

Utilisation

L'outil s'utilise en ligne de commande avec l'interpréteur Python :

python apxutil.py -h

usage: apxutil.py [-h] [-f filaname-apx] [-F filaname-sta] [-e dir] [-E dir] [-a manifestpath] [-A manifestpath] [-d]
                  [-x] [-B] [-r]

Outil pour manipuler les fichiers .sta et .apx de Schneider Electric

options:
  -h, --help            affiche ce message d'aide et quitte
  -f, --apxfile filaname-apx
                        fichier .apx à lire ou à écrire
  -F, --stafile filaname-sta
                        fichier .sta à lire ou à écrire
  -e, --extract-apx dir
                        extraire le contenu du fichier Station.apx
  -E, --extract-sta dir
                        extraire le contenu du fichier .sta
  -a, --assemble-apx manifestpath
                        créer un fichier Station.apx basé sur apx_manifest.ini
  -A, --assemble-sta manifestpath
                        créer un fichier .sta à partir des fichiers dans sta_manifest.ini
  -d, --decompress      décompresser les sections de Station.apx qui sont compressées
  -x, --hexdump         afficher un hexdump de Station.apx avec les informations d'en-tête
  -B, --include-apd     inclure Station.apd lors de la création de l'archive .sta
  -r, --restart-offsets
                        redémarrer les offsets à 0 pour chaque section dans l'hexdump (utile pour le diff)

L'aide devrait être assez explicite. En général, les options raccourcies en lettres majuscules fonctionnent sur les fichiers .sta, et les lettres minuscules sur les fichiers .apx. Quelques exemples d'utilisation sont donnés ci-dessous.

Pour extraire le contenu d'un fichier .sta dans le répertoire « extracted », vous utiliseriez :

python apxutil.py -F archive.sta -E extracted

Pour extraire le contenu de Station.apx dans le répertoire « contents », vous utiliseriez :

python apxutil.py -f extracted/BinAppli/Station.apx -e contents -d

L'option « -d » signifie que les sections compressées seront décompressées, mais peut être omise si les données brutes de la section sont souhaitées.

Pour réassembler Station.apx, vous utiliseriez :

python apxutil.py -f extracted/BinAppli/Station.apx -a contents

Cela assemblera le Station.apx basé sur le apx_manifest.ini trouvé dans le répertoire contents, en compressant les données de section si elles étaient précédemment décompressées. Les tailles de section et les CRC seront recalculés, et non lus depuis le apx_manifest.ini.

Pour réassembler un fichier .sta, vous utiliseriez :

python apxutil.py -F modified-archive.sta -A extracted

Cela exclura par défaut le fichier Station.apd (qui semble être principalement une vérification d'intégrité pour l'en-tête du fichier Station.apx). Si vous souhaitez l'inclure, ajoutez l'option « -B ». Mais cela pourrait très bien signifier que Control Expert Classic échouera à ouvrir le fichier d'archive du projet.

Pour « visualiser » directement le contenu du fichier Station.apx, la commande suivante peut être utilisée :

python apxutil.py -F modified-archive.sta -x

Cela affichera un « hexdump canonique » du fichier Station.apx, ce qui signifie que vous voyez les offsets, les données hexadécimales et les données ASCII, 16 octets à la fois, y compris les métadonnées. L'option « -d » peut être utilisée pour décompresser les sections compressées (mais attention, les offsets n'ont alors plus beaucoup de sens). L'option « -r » peut être utilisée pour redémarrer l'offset à 0 pour chaque section. Ceci est utile si vous avez effectué des modifications et souhaitez pouvoir les « differ » sans offsets.

Structure du format de fichier APX

Si vous voulez comprendre le format de fichier APX (au niveau de moi-même et de cet outil), la meilleure façon est vraiment de regarder le code source de apxutil.py. Le code ne devrait pas être trop difficile à lire même avec peu d'expérience en programmation. Mais il pourrait rendre les vrais programmeurs nauséeux. En tout cas, un aperçu de haut niveau du format de fichier est donné ici. Le fichier APX commence par un en-tête de fichier de 32 octets. Le reste du fichier est divisé en différentes sections, chacune avec une structure similaire. Chaque section commence par un en-tête de section, dont la longueur dépend du type de section (défini au début de l'en-tête). L'en-tête de section est suivi d'un RTE (en-tête). Après le RTE viennent les données de la section (si présentes). Et après les données de la section, la section suivante (en-tête) commence. Il semble que l'en-tête de section soit plus lié au format Station.apx et le RTE plus lié à l'environnement d'exécution (RunTime Environment ou RealTime Environment peut-être ?), mais ce n'est pas une distinction claire.