Sometimes, making the right payload involves more than just shell scripting. For advanced payloads with extra needs, please keep the following guidelines in mind!

Binary payloads

The WiFi Pineapple Pager uses a MIPS processor in little endian, identified as a mipsel.

Payloads may optionally execute custom binaries, but there are a few important things to keep in mind.

  1. Currently, payloads will not be accepted into the Payload Repository with binary components. This is primarily for user safety - it is possible to inspect a normal payload shell script relatively easily, but much more difficult to do so with a precompiled binary. We are currently working on a mechanism which will allow binary payloads to be submitted as source, and a build environment they must compile under. We will be refining the build environment we will expect submitted payloads to build in and the policies for accepting binary payloads; Expect custom binary payloads to be accepted in the future!
  2. A payload must have a payload.sh, even if the work is done in a binary. The payload.sh script should be used to set permissions and launch the custom binary.
  3. Assume your binary does not have execute permissions. Users may download payloads as zip files, and often download them on Windows based systems which have no concept of executable state. You should expect to set the executable bit in payload.sh, for instance with chmod +x "${PAYLOAD_HOME}/bin/mybinary"

Third-party packages

The WiFi Pineapple Pager supports packages from the OpenWRT package repository via opkg.

When using packages in a payload, some important things to keep in mind include:

  1. The Pager may not be online. Be sure to handle errors in updating and fetching packages and warn the user!
  2. The package list is likely not present (or not up to date). An opkg update may be required.
  3. Packages may be removed any time during a firmware upgrade (more on this in the next section). You must check on every payload launch that the tools you expect are present, and prompt the user to install them!
  4. There may be no room on the system to install packages (more on this in the next section).
  5. You must not remove or replace preinstalled system packages.

Package locations

Packages installed via opkg default to installing on the overlay to the rootfs. This is stored on the boot flash chip, which is extremely limited in size and speed.

Packages can be installed to the eMMC storage (a much larger and faster flash chip, where /root lives) with the opkg option -d:

  opkg install -d mmc python3

Packages installed to the root overlay will not be preserved during a firmware upgrade. Packages installed to mmc will still be present after a firmware upgrade - with the important caveat that future firmware releases may change the system in ways that break older packages.

System packages

The Pager requires specific system packages, due to library versions, local modifications, or specific behavior.

Payloads must not update, remove, or replace existing packages, or install alternate builds of system packages which have the effect of replacing the system package.

Not all packages work, or work well

Remember: Just because a package for it exists, doesn’t mean it will work, or be considered usable!

The Pager has been heavily optimized to perform well with a limited amount of storage and RAM - this includes what tools, services, and scripting environments come pre-installed on the system. The OpenWRT package repository includes a large number of packages for multiple types of systems - please keep in mind that just because a package exists, doesn’t mean it will be appropriate to try to run on the Pager.