ZeroPhone OS from Raspbian

From ZeroPhone
Jump to: navigation, search

Current Linux image for ZeroPhone is Raspbian-based, and the current way to prepare a ZeroPhone SD card image is to take an SD card, install all the necessary software on it and configure it (to enable support for ZeroPhone hardware). However, it's only advised to make an image this way if you can't trust available images (or if there aren't any images already available for download yet - as of time of writing, this is true, bue due to change soon). This page will be compiled while I (Arsenijs) will be going through gamma board SD card image preparation, but if there are any shortcomings, feel free to correct them.

Important: you only need to go through these steps if you actually have a ZeroPhone and there are no ZeroPhone images publicly available (all the download links are down), or if the existing images are significantly out-of-date. Otherwise, go to the Downloads page.

Installing power management script, WiFi and UI

Before these steps, the image will not have functions for ZeroPhone to boot properly, show UI or be able to connect to WiFi - so you will need to do these steps with a HDMI monitor, mouse and keyboard, or, alternatively, with a USB-UART adapter (will involve soldering). It's possible to plug a fresh SD card into a full-sized Raspberry Pi, do all of these steps and then move the SD card to a ZeroPhone. To begin with, flash latest Raspbian on an SD card (my tools of choice are Win32DiskImager on Windows and dd on Linux). Then, insert the card into the Pi you'll be using for initial setup, power it up and then reach its console - either by using HDMI monitor&keyboard, USB-UART or Ethernet connectivity.

Adding the ZeroPhone repository

Some ZeroPhone scripts are stored in the ZeroPhone project repository. You need to add it as a supported repository:

wget -O -|sudo apt-key add -
echo "deb stretch main" | sudo tee /etc/apt/sources.list.d/zerophone.list
sudo apt update


You'll need to have access to the internet to download WiFi drivers, so you'll likely need something like a USB WiFi dongle - unless you're doing the initial config on a Raspberry Pi 3 (I used a Pi Zero and Wi-Pi with a USB-OTG cable). First, let's add the WiFi network you can access. From console, use wpa_cli:

pi@raspberrypi:~$ wpa_cli
wpa_cli v2.3
Copyright (c) 2004-2014, Jouni Malinen <> and contributors

This software may be distributed under the terms of the BSD license.
See README for more details.
Selected interface 'wlan0'
Interactive mode

You'll need to enter the following commands, where SSID is your WiFi network's name (in " quotes) and PASSWORD is your network's password (again, in " quotes):

> add_network

This number will likely be 0, but just in case you'll have added any networks before, it could be a bigger number - you'll need to have the same number in the following commands:

> set_network 0 ssid "SSID"
> set_network 0 psk "PASSWORD"
> select_network 0
> save_config

It will attempt to connect to the network. If it'll succeed, the output will look something like this:

<3>SME: Trying to authenticate with xx:xx:xx:xx:xx:xx (SSID='SSID' freq=2472 MHz)
<3>Trying to associate with xx:xx:xx:xx:xx:xx (SSID='SSID' freq=2472 MHz)
<3>Associated with xx:xx:xx:xx:xx:xx
<3>WPA: Key negotiation completed with xx:xx:xx:xx:xx:xx [PTK=CCMP GTK=CCMP] 
<3>CTRL-EVENT-CONNECTED - Connection to xx:xx:xx:xx:xx:xx completed [id=0 id_str=]

Type "quit" to exit the wpa_cli console. You can see your IP address on the network by using "ip a". Then, proceed to Pi Zero-specific instructions:

ZeroPhone based on Pi Zero

You'll need to download and install a driver for ESP8266-based WiFi (esp8089 driver). Luckily, it's straightforward:

sudo apt install esp8089

If you can't add the repository

In the /boot/config.txt section of this page, note the "dtoverlay=sdio,poll_once=off" part - you'll need it so that the ESP8266 will be detected.

ZeroPhone based on Pi Zero W

If you're using Pi Zero W in your ZeroPhone, you're all set - the drivers should be in the default Raspbian install!


Run "sudo raspi-config" from the console and change these options:

  • 1. User password - definitely change that one
  • 2. Hostname - would be a good idea
  • 4. Localisation options - change at least the timezone and WiFi country, the keyboard layout change will be useful if you plan to use ZeroPhone with HDMI monitor
  • 5. Interfacing options - turn on SPI, I2C and Serial, at the very least. SSH will likely be your only option to get command-line access on the phone through the network, so hopefully you've changed the default password - you did, right? If so and if it's a sufficiently complicated one, feel free to enable SSH here, too.
  • 7. Advanced options - expand the filesystem, default GPU memory split of 64 is good but you need at least 128 if you plan to use the camera, also, you'll likely want to "force 3.5mm jack" in Audio settings, too.

After you're done, it's better if you reboot - if it asks you to.


This file will need quite some lines added. They're described in detail on this page, if you want to just copy-paste lines, here you go:

gpu_mem=64 #Will likely be already added by raspi-config
dtparam=audio=on #Will likely be added by raspi-config, too
enable_uart=1 #Again, likely to be added by raspi-config

WiFi configuration

If you're using a Pi Zero (no W) in your ZeroPhone (without built-in WiFi&BT), add these lines:
#dtoverlay=pi3-miniuart-bt #has to be commented out for Pi Zero-based ZeroPhone
If, instead, you're using a Pi Zero W in your ZeroPhone, add these lines:
#dtoverlay=sdio,poll_once=off #has to be commented out for Pi Zero W-based ZeroPhone

It's advisable to reboot, too - to make sure I2C and SPI are available, and so that ESP8266 driver is loaded on the next boot.

Power management

Current ZeroPhone revision has a switch that can shut off ZeroPhone power from software. That switch requires software support, otherwise your ZeroPhone won't power up completely.

sudo apt-get install zerophone-power-management
sudo systemctl enable enable_power_fet

If you can't add the repository


It's very advised to have at least the front board attached to the Pi you're working on (you can attach the ZeroPhone front board to any Pi, except the old ones with a 26-pin GPIO connector). To check if the front board is properly attached (specifically, that the ATMega-based keypad controller can be found on I2C bus), do the following:

sudo apt-get update && sudo apt-get install i2c-tools
sudo i2cdetect -y 1
pi@raspberrypi:~$ i2cdetect -y 1
     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
00:          -- -- -- -- -- -- -- -- -- -- -- -- --
10: -- -- 12 -- -- -- -- -- -- -- -- -- -- -- -- --
20: UU- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
70: -- -- -- -- -- -- -- --

If it doesn't show "12", the keypad controller is not found. If it doesn't show "UU" at intersection of "20" and "0", the driver for MCP23017 expander on the back board is not loaded - most likely, the Pi is not attached to the ZeroPhone back board, or there's a soldering problem. (if it shows "20" at that intersection, the expander is found, but the driver is not loaded - check your /boot/config.txt).

Assuming it shows "12", let's proceed to install ZPUI:

git clone

The UI should launch on the display!

Additional features

These features are not critical for ZeroPhone functionality, but nevertheless are nice to have.

Hardware random number generator support

sudo apt-get install rng-tools
echo bcm2835_rng | sudo tee /etc/modules-load.d/rng-tools.conf
sudo modprobe bcm2835_rng
echo 'HRNGDEVICE=/dev/hwrng' | sudo tee --append /etc/default/rng-tools