OpenWISP Firmware


OpenWISP Firmware (shortly OWF) is an openwrt package that provides a daemon that periodically retrieves the configuration of the following components from an OpenWISP Manager (OWM) server:

  • wifi (currently only for madwifi-ng and ath9k)
  • networking
  • layer 2 traffic shaping
  • openvpn (layer 2, tap)
  • cronjobs

OpenWISP Firmware also provides a web GUI for: - configuring basic network parameters - configuring basic OpenWISP server settings - performing a set of test to spot and resolve most common problems that may prevent Open WISP firmware to work correctly

See the OWM wiki for more details.

Compiling OWF

In order to have a fully working OWF you have to compile it yourself.

OWF package supports an overlay configuration file that you should provide at compile time, this overlay allows you to include custom configuration. See below for more information on this file.

We strongly suggest to build OpenWRT on a GNU/Linux environment, you can find other pre-requisites here:

If you have a properly configured machine follow this steps inside the OpenWRT root directory:

cp feeds.conf.default feeds.conf
echo "src-git openwisp" >> feeds.conf
./scripts/feeds update
./scripts/feeds install openwisp-fw
make menuconfig (choice your arch and include openwisp-fw package and submodule if appropriate)
export OPENWISP_CONF="" (see below)

The full version of OWF will support UMTS and mesh capability, but will require better hardware and much more space on flash/disk, we recommends an appropriate hardware under this condition.

Our firmware should idealy run on every OpenWRT-complatible devices, but we have tested mainly atheros, x86, ar71xx platforms.

Stable version features:

  • MESH Support
  • 3G support
  • wifi support (Both drivers works alone or togheter)
  • interface failover script

Overlay Configuration File

The overlay configuration file is a tar.gz file that is extracted inside the target rootfs and can potentially overwrite any other config file or add new files inside filesytem.

Here I will provide a structural example of the overlay configuration file that should be provided to be fully compliant with OWM and OWF v1.2:

├── config
│   └── owispmanager
├── openvpn
│   ├── ca.crt
│   ├── client.crt
│   └── ta.key
└── shadow

This is an exmaple of the contents of etc/config/owispmanager:

config 'server' 'home'
  option 'address' 'my_OWM_server'
  option 'port' ''
  option 'status' 'configured'
  option 'inner_server' ''
  option 'inner_server_port' ''

config 'server' 'local'
  option 'hide_server_page' '1'
  option 'setup_wpa_psk' 'owf_safemode_wpakey'
  option 'setup_wifi_dev' ''
  option 'setup_httpd_port' ''
  option 'setup_ssid' ''
  option 'setup_ip' ''
  option 'setup_netmask' ''
  option 'setup_range_ip_start' ''
  option 'setup_range_ip_end' ''
  option 'hide_umts_page' '1'
  option 'hide_mesh_page' '1'
  option 'hide_ethernet_page' '0'

The etc/openvpn/ directory will contain the RSA certificates to establish a successfull connection with your own openvpn server (aka setup vpn) while /etc/shadow will provide a default password for the root user, here the file content for password “pass”:


The overlay configuration layer MUST be provided using the enviroment variable OPENWISP_CONF it could be a local targz file, a valid http url to download the targz or a local directory.

For and example of directory structure see tests/dummy_config and refer to .travis.yml to setup the correct build enviroment.

Beware: if you update your overlay configuration file please ensure to clean and recompile the openwisp package. This can be done using the following command inside openwrt build dir:

make package/openwisp-fw/clean

Developing the firmware

If you’d like to work locally on firmare improvement you should use a local OpenWisp Firmware repo clone and a local OpenWrt repo clone. In this configuration you should use the following commands for feed configuration:

echo "src-link openwisp /path/to/local/git/repo/" >> feeds.conf
./scripts/feeds update

Compile Openwrt for multiple architectures

Here follows an example script to compile OWF for different arch targets:


git clone git:// --depth 10
cd openwrt

#configure feeds
cp feeds.conf.default feeds.conf
echo "src-git openwisp" >> feeds.conf
./scripts/feeds update
./scripts/feeds install openwisp-fw

export OPENWISP_CONF="" (see below)

#config target
for arch in ar71xx atheros x86; do
  echo "CONFIG_TARGET_$arch=y" > .config;
  echo "CONFIG_PACKAGE_openwisp-fw=y" >> .config
  make defconfig;
  make package/openwisp-fw/clean;
  make -j 4;