Create Packages

The modified firmware includes a lightweight package management system called opkg (home page) which is similar to the Debian package management system (dpkg).

Coding your package

Most of the customised firmware is written in a language called Jim/TCL, See the Jim Manual HERE with other bits in C/C++ and the Humax runs a Linux operating system.

A number of TCL classes have been created to make it easier to work with different parts of the Humax webif environment. For example the ts class provides services for working with recordings and the epg class provides access to the programme guide.

The webif also provides a large number of .hook points where packages can integrate themselves into the existing webif infrastructure. For example the browse.hook allows new actions to be added to the browse opt+ menus.

Unfortunately documentation is sparse and there is no definitive list of all the classes and their services or of the available hook points. It is largely a case of reading existing code to find out what is available and above all asking questions on the forums, Use existing packages that have similarities as a basis for your code but don't forget to credit the original authors in your comments and forum/wiki posts.

Package Repositories

The custom firmware is configured to use the package repository at hummypkg.org.uk by default.

Package Format

A package is a UNIX Archive (ar) file which itself contains three files:

debian-binary 

A file which just contains the string "2.0", a clue to the packaging system's roots.

data.tar.gz 

The files which make up the package.

control.tar.gz 

Package meta-information.

Creating a Package

The pkgtools package includes utilities for working with packages and can be used to create packages directly on the Humax itself. Before proceeding, install these utilities:

humax# opkg update
humax# opkg install pkgtools
humax# opkg install gzip

Next create a directory to hold your new package and create a directory within it called CONTROL, which will be used for the package meta-information:

humax# cd /mod/tmp
humax# mkdir my-first-package
humax# mkdir my-first-package/CONTROL

Note: Package names should not contain underscore (_) characters as these are used as delimiters in package file names. It is safest to stick to alpha-numeric characters and use - as a delimiter where appropriate, e.g. webif-iphone

Place the files which make up your package directly into the new package directory. Note that to save memory when running, compiled binaries should be stripped before packaging. In this example, we'll create a package which just installs a script called hello.

humax# cd /mod/tmp/my-first-package
humax# mkdir bin
humax# cat > bin/hello
#!/bin/sh

echo "Hello!"
^D
humax# chmod 755 bin/hello

Note: Files should be included relative to /mod (or /opt on the FoxSat) so in this example the bin/hello file will be installed as /mod/bin/hello

Create file package control file as CONTROL/control. Here's an example:

Package: jim-sqlite3
Priority: optional
Section: misc
Version: 0.71
Architecture: mipsel
Maintainer: af123@hummypkg.org.uk
Depends: jim(>=0.71-1),sqlite3
Description: Jim SQLite3 plugin.
 A plugin for the jim interpreter (a lightweight TCL interpreter) which
 provides access to SQLite3 databases (such as those used on the Humax).

The Debian project maintains documentation on the format of the control file which also applies to opkg packages, although some fields are not required.

Package 

The package name.

Priority 

Always set to optional for Humax packages.

Section 

One of misc, net, devel, etc. full list

Version 

The package version number of the format upstream_version[-opkg_version] more information

Architecture 

Always mipsel for the HD/HDR Fox T2, and mips for the FoxSat.

Maintainer 

An email address or hummy.tv/wiki username.

Depends 

A list of dependencies for this package, optionally with version constraints see Debian documentation

Description 

A description of the package. Continuation lines must be prefixed by white space.

Tags 

An optional field that contains a URL pointing to a source of further information

The CONTROL directory can also contain other package maintenance scripts such as preinst, postinst, prerm and postrm. See the Debian documentation for more details and examples. The scripts are called with various arguments during package maintenance operations. Many simple packages do not require any maintenance scripts.

Continuing with our example package, create the bare minimum control file:

humax# cat > CONTROL/control
Package: hello
Version: 1.0
Architecture: mipsel
Maintainer: af123
Description: hello
Tags: http://wiki.hummy.tv/wiki/Custom_Firmware_Overview/

The package can now be built using the opkg-pack command:

humax# cd /mod/tmp
humax# opkg-pack my-first-package
bin/
bin/hello
Packaged contents of /mod/tmp/my-first-package/ into /mod/tmp/my-first-package//../hello_1.0_mipsel.opk 532

The package can then be installed directly from the resulting file for testing.

humax# opkg install hello_1.0_mipsel.opk
Installing hello (1.0) to root...
Configuring hello.
humax# hello
Hello!
humax# opkg remove hello
Removing package hello from root...

If you have any packages which you'd like published in the hummypkg.org.uk repository, then email them to packages@hummypkg.org.uk.

Using Git to store and maintain package

It is recommended that you use the Git library system to provide version control and to allow for collaborative development with others.

See Maintain packages with Git for a guide to using Git with Humax packages. Most of that page also applies to maintaining your own packages but there are also a few differences which are covered here.

As package owner you will be responsible for establishing the principal repository for the package and will work directly with that repository rather than a forked copy and you will also be responsible for merging the branches created by you or others into the master branch once you are satisfied they are working correctly and then removing empty branches.

Create a new repository for your package

On the Dashboard of the Hummy Git website click to create a New Repository

Provide the Package name, Visibility (Public is best) and Description but do not select the 'Initialize Repository' option then click on 'Create Repository' buttton On your local machine switch to the folder for the package and upload it the repository.

cd /mod/tmp/my-first-package
git init
git add .
git commit -a -m "first commit"
git remote add origin https://git.hpkg.tv/USERNAME/my-first-package.git
git push -u origin master

Merge changes into master branch

This can be done locally on your machine for changes you have made or on the web repository for Pull Requestsgo created by you or others

Local Merge

After completing changes switch to master branch, merge the changes, delete the branch and synchronize with the remote repository

git checkout master
git merge branch-name
git branch -d branch-name
git push

If the branch had bee pushed to the remote it can be deleted

git push origin --delete  branch-name
git remote prune origin

Remote Merge

On the Pull Request tab of the Hummy Git website Review the changes are OK and Approve the changes, or Request Changes if required

Once satisfied click on the "Merge Pull Request" button after which you can click on the "Delete Branch" button Synchronize your local repository

git checkout master
git pull

Unpacking an existing package

The pkgtools package also contains a utility which can be used to unpack an existing package into a directory structure for editing or just for investigation, NOTE :- you need to install the gzip Custom Firmware package in order to use opkg-unpack

humax# cd /mod/tmp
humax# opkg download webif
Downloading http://hummypkg.org.uk/hdrfoxt2/base/webif_0.6.4_mipsel.opk.
Downloaded webif as ./webif_0.6.4_mipsel.opk.
humax# opkg-unpack webif_0.6.4_mipsel.opk
Unpacked to webif_0.6.4_mipsel

If you have a Debian-based Linux machine, opkg packages can be examined and manipulated using the dkpg-deb command.

wget http://hummypkg.org.uk/hdrfoxt2/base/busybox_1.19.3-3_mipsel.opk
dpkg-deb -x busybox_1.19.3-3_mipsel.opk <tmpdir>

Packing and Unpacking Bundled Packages

An OPK file contains the executable program /s and all the set-up scripts required for a single Custom Firmware package, However this single package may require other packages to be present in order to work. An OPB file contains the main package and all the peripheral packages require for it to run in a single file, the OPK’s are tarred together to form this file and can be viewed as follows :-

humax# /bin/untar multimode_0.0.1_mipsel.opb
Extracting from multimode_0.0.1_mipsel.opb
 Extracting file multimode_0.0.1_mipsel.opk
 Extracting file webif_0.8.9_mipsel.opk
 Extracting file mongoose_3.0-6_mipsel.opk
 Extracting file jim_0.71-1_mipsel.opk
 Extracting file jim-sqlite3_0.71-1_mipsel.opk
 Extracting file sqlite3_3.7.6_mipsel.opk
 Extracting file jim-cgi_0.4-1_mipsel.opk
 Extracting file jim-oo_0.71_mipsel.opk
 Extracting file jim-pack_0.71_mipsel.opk
 Extracting file service-control_1.0_mipsel.opk
 Extracting file busybox_1.19.3-2_mipsel.opk
 Extracting file lsof_4.82_mipsel.opk
 Extracting file epg_1.0.8_mipsel.opk
 Extracting file hmt_1.1.3_mipsel.opk
 Extracting file ssmtp_2.64_mipsel.opk
 Extracting file anacron_2.3-1_mipsel.opk
 Extracting file cron-daemon_1.18.3-1_mipsel.opk
 Extracting file rs_0.4.0_mipsel.opk
End of multimode_0.0.1_mipsel.opb
humax#