engineerisaac/drivers-driverpackager

Python scripts to build (optionally encrypted) Control4 .c4z driver files

Driver Packager

Versions

• dp: Driver Packager for Python 2
• dp3: Driver Packager for Python 3
• dplite: Driver Packager Lite for Python 2
• dplite3: Driver Packager Lite for Python 3

It is recommended that new Driver Packager users use dp3.

ONLY dp3 IS GUARANTEED TO BE MAINTAINED AND UPDATED IN THE FUTURE.

The rest of this README is specific to Driver Packager 3, although much of it may also apply to other versions.

Requirements

Driver Packager requires:

• A working installation of Python 3 (https://www.python.org/downloads/)
• M2Crypto installed for your Python installation (if encrypting your driver) (https://gitlab.com/m2crypto/m2crypto)
• Lua installed (if squishing your driver) (https://www.lua.org/download.html)

Using Driver Packager to build a .c4z

usage: driverpackager.py [-h] [-v] [-u] [-ae] srcdir dstdir [manifest]

• required arguments:

  • srcdir: Directory where c4z source files are located
  • dstdir: Directory where c4z files are placed
  • manifest: [optional] Filename of manifest xml file

• optional arguments:

  • -h, --help: show help message and exit
  • -v, --verbose: Enable verbose
  • -u, --unzip: Unzip the c4z in the target location
  • -ae, --allowexecute: Allow Execute in Lua Command window even for encrypted driver (adds C4:AllowExecute(true) to Lua source)

Using Driver Packager in Github Actions

This repository can also be used to build your c4z projects as a GitHub Action. You'll need to use another action or script to push the file output where it needs to go next.

uses: control4/drivers-driverpackager@v1
with:
  # Directory (relative to the root of your Git repo) that contains the .c4zproj to build
  projectDir: ''
  # Filename for the c4z project to build
  c4zproj: ''
  # Directory (relative to projectDir) to output the built c4z file to
  # Defaults to the parent directory ('./../')
  outputDir: ''

Manifest File format

The manifest.xml file is an XML file, with the following format:

<Driver type="c4z" name="c4z_base_filename" squishLua="false">
  <Items>
    <Item type="file" name="driver.xml" />
    <Item type="file" name="driver.lua" />
    <Item type="file" c4zDir="www" name="www/documentation.rtf" />
    <Item type="file" name="id_ds2.gif" />
  </Items>
</Driver>

Notes:

• c4z_base_filename within the Driver tag should be replaced with the output .c4z name.
• Items with a 'c4zDir' attribute will get added to the .c4z in the specified directory.
• Items 'name' attribute is relative to the directory the manifest file is in.

Driver Packager source files:

driverpackager.py:

Main Driver Packager Python script.

build_c4z.py:

Used by driverpackager to squish and zip the source files into the .c4z output.

usage: build_c4z.py [-h] [-v] [-x | -c] c4z dir

• Arguments:

• c4z: path to the C4Z file

• dir: path to the C4Z contents directory

• Optional arguments:

• -h, --help: show help message and exit

• -v, --verbose: Enables verbose output

• -x, --extract: Extracts the C4Z

• -c, --compress: Compresses the C4Z (default)

encrypt_c4z.py:

Used by driverpackager to encrypt the driver.lua source file (and any squished with it) using S-MIME encryption (DriverWorks Encryption V2).

usage: encrypt_c4z.py input_path output_path

squish:

Used by driverpackager to combine multiple Lua source files into a single Lua output file, which can then be encrypted.

Documentation for Squish can be found here: http://matthewwild.co.uk/projects/squish/readme.html