Birds Like Wires

Pop search terms in here.

Feed the Birds

Debian & Ubuntu for OpenFrame

Latest Release: Kernel 3.16

Download Debian Buster (10.3) for OpenFrame (soonish)
Download Ubuntu Bionic (18.04) for OpenFrame (~160 MB)

These images can be used on any OpenFrame 1 (O2 Joggler, Telefonica Orby) or OpenFrame 2 (Cisco Home Energy Controller, Telio Touch) device, running either from USB storage or internal memory. External storage is recommended as it will be much faster with plenty of space available.

The goal here was to make small-but-useful command line systems which can be customised all the way up to a lightweight desktop. There are a few built-in ‘of-’ commands to make life easier, including installers for software such as SqueezePlay, which are explained below. Once up and running there is very little difference between these images and the experience you would have running Debian or Ubuntu on any other device.

Unless you choose to write the operating system to the device’s internal memory, running from an external USB device will make no permanent changes to your OpenFrame, so there’s no risk to trying it out.

Installing

The recommended way of using an image is to write it to USB storage using the Raspberry Pi Imager, which is available for Windows, macOS and Ubuntu.

Raspberry Pi Imager, also useful for other systems. Click CHOOSE OS and scroll to the bottom for Custom option. Choose your target device and click WRITE. Verification will happen. Done!

Click ‘CHOOSE OS’ in the Imager and scroll to the bottom of the list where you’ll find ‘Use custom’. Pick the image file you downloaded, which may end in .gz or .img (some browsers try to be helpful by automatically decompressing files). Then pick your target device (all USB storage devices are shown, not just SD cards) and click ‘WRITE’.

If you wish to install to the internal memory, follow the same instructions, but write the Reflash System for OpenFrame to your USB device. Unplug it and then plug it back in to mount the drive, then copy the .gz and matching .gz.md5 files to the ‘reflash’ folder on your USB device. Connect to your OpenFrame and power on.

Configuring

Once the image is written to the drive, unplug and plug it back in to your computer to mount it. You should see a volume called ‘BIO-BOOT’ or similar, depending upon which operating system you’ve written. At the moment only network settings can be modified from here, but a few more options may be added in future.

Network Settings

If the plan is to connect to your wifi network you will need to provide your network name and password. This can be done by editing the network.yaml file with a text editor (Notepad, TextEdit or similar). Open the file and you should see this:

network:
  version: 2
  renderer: networkd
  ethernets:
    eth0:
      dhcp4: true
  wifis:
    wlan0:
      dhcp4: true
      access-points:
        YOURWIFINAME:
          password: YOURWIFIPASSWORD

Change ‘YOURWIFINAME’ and ‘YOURWIFIPASSWORD’ as appropriate, but remember to leave the colon ‘:’ at the end of your wifi name.

Save the file, eject the drive, connect it to your OpenFrame and power up. The login prompt should show the device’s IP addresses:

Ubuntu 18.04.4 LTS openframe tty1 wlan0:192.168.1.10 eth0:192.168.1.11
openframe login: _

If you plan on connecting to your network with a cable, you don’t need to do any of the above. The system is configured to grab a network address from your router using DHCP by default. You can use both interfaces simultaneously just as you would expect.

If you would like to make more advanced changes, please check the Netplan documentation.

Issues

If you’re using an OpenFrame 2 the wireless connection does work… sort of. Performance is absolutely terrible and I’ve not been able to do anything about it. Maybe it’s my test device which is at fault, but feedback would be appreciated. We’re using the brcmsmac driver; the b43 driver was worse and broke Bluetooth for me. The broadcom-wl driver might do the trick, but there are licensing issues, so I can’t distribute it. Good luck!

Access

PuTTY.

Once booted you should be looking at a command prompt login on the OpenFrame’s screen. There are two ways to go from here; use a keyboard connected to the OpenFrame to log in, or connect over a Secure Shell (SSH) session from your computer.

The keyboard option can be a little tricky, as we only have one external USB port to play with and not all keyboards with USB hubs pass enough power to the storage device, so you can end up with some odd errors or boot failures. But if you can power the storage device separately this usually works well.

On the OpenFrame 1, if you’re using the device as a ‘mini desktop’ you could always replace the internal wifi card with a USB dongle for a wireless keyboard and mouse. The internal port is a perfectly normal USB 2.0 Type A socket, which provides some interesting options, and the case is pretty easy to open and close.

However, the most appropriate option is likely to be an SSH connection from your PC, as most people use their OpenFrames as music players or web-connected display devices, so wouldn’t normally have a permanent keyboard and mouse attached. On macOS and Ubuntu the Terminal application is already installed. On Windows, download PuTTY.

The default login details are:

Username: of
Password: joggler

In the Terminal applications the command to connect is:

ssh of@192.168.1.11

Replace 192.168.1.11 with the IP address shown by your OpenFrame. With PuTTY you pop the IP address into the “Host Name (or IP address)” box.

Helpful Commands

There are some tasks which people want to achieve quickly when they’ve set up a new device. Grubbing around the web looking for the right commands can be frustrating, particularly if you’re not certain the solution even applies to your system!

The ‘of-’ scripts are included to help with this, and can be updated to the most recent versions without re-imaging. They live in /usr/local/sbin, but please don’t modify them directly. Some system services rely on them and any change you make will be overwritten if they’re updated, so it’s best to edit a copy elsewhere. The key ones to know are:

of-backlight – gets or sets the backlight level
of-expand – enlarges the root partition to the full size of your drive
of-install – pre-configured installation of commonly used software
of-ip – shows current IP addresses on all interfaces
of-netplan – installs new network settings and restarts the network
of-settings – configures system options, such as hostname, auto-login and boot screens
of-timezone – configures the system time zone
of-update – updates the scripts

Type the name of a script followed by -h to receive help information on how to use it. For example, of-settings -h.

Some scripts need ‘superuser’ privileges to make their changes. Prefix any command with sudo to elevate their rights, eg. sudo of-update.

Things To Do

Expand Root Partition

Once you’re logged in to your system, unless you’ve installed to the internal memory of an OpenFrame 1, the main command to run is sudo of-expand. This grows your storage from the 1 GB default to the full size of the drive you wrote the image to. It takes a few minutes to complete (depending on your drive speed) and the resize occurs after the OpenFrame has rebooted, so you’ll have a slow system and a flashing drive LED while it finishes.

If you are running from internal memory on an OpenFrame 1 you will need to keep an eye on your space utilisation with the df -h command, as you’ll only have ~500 MB to play with. Also, when using apt to install new software, the package lists are held in RAM to save space. It’s a very sensible plan to reboot after installing to clear these lists, otherwise you’re likely to run out of memory.

Change Your Password

The only user that can log in by default is ‘of’, so the system is secure by default. Well, except for the password, which everyone knows. You should change it using the passwd command. It’ll ask you for a new password and to confirm it. Really quick, easy and important.

Updates

From here everything becomes very much like any other command line Debian or Ubuntu system. You can update the installed packages with the usual commands:

sudo apt update
sudo apt upgrade

The sudo of-update command can be run at any time to check for newer versions of the ‘of-’ scripts.

Install Software

The of-install command sets up software in a manner specific to the OpenFrame, or bundles a group of installation steps together in the best way for this platform. One example would be the installation of SqueezePlay, which also sets up appropriate system services and boot screens to support it.

For anything else you can refer to documentation written for other Debian or Ubuntu systems, and also for the Raspberry Pi, which despite running on the ARM processor platform (rather than the 32-bit x86 platform in the OpenFrame) has documentation which is directly relevant.

Of course, there’s also the Joggler Forum where people are always happy to lend a hand.

One planned change is to add a means of choosing software for of-install to set up without requiring any commands to be typed, which will be documented here when it’s sorted out.

Background

Why Have You Done This?

Always a solid question. I hate electronic waste and love a puzzle, and despite being an older piece of hardware the OpenFrames are robustly manufactured, usually found in excellent condition, cheap and capable. Also, there’s still no other nicely integrated device in this home-friendly form factor that I’ve managed to find. The closest option is a Raspberry Pi (£34), Official Raspberry Pi 7” Touchscreen Display (£60) and Case (£12). You can find an O2 Joggler most days on eBay for £20, less if it’s ‘broken’, which usually means the internal storage has failed. Use one of these images on a memory stick and it’ll likely work just fine.

Plus, I have one integrated into a cupboard door in my kitchen, so not keeping it up and running would make me unpopular.

Finally, it was the sheer number of OpenFrames still in use as SqueezePlay music devices which prompted me to work on this update. The operating system they rely upon is Ubuntu Trusty (14.04) which left standard support in April 2019, so it could potentially open up those users of my old ‘SqueezePlay OS’ to security issues. In the future I’ll be retiring Ubuntu as a platform and switching to Debian, upon which Ubuntu is based, but which is retaining 32-bit support.

How Have You Done This?

Everything is now based around an automated build system, compiling 32-bit binaries in a chroot on a 64-bit server.

Early each morning the build system checks for new a new version of the kernel or alterations to the master branches of openframe-kernel and openframe-linux on GitHub. Any changes are pulled down and a new kernel compiled or a new image built automatically.

Older versions, in case of build issues, are available in the images directory.

Can I Help?

Absolutely. Everything to do with this distribution is available in the Birds Like Wires GitHub repos. The key ones are openframe-kernel and openframe-linux, which contain all of the patches, overlay files and instructions on how to build kernels and images in your own automated build chroot, the same way as these images are generated early each morning.

If you have any programming experience, feel free to clone the repos, make changes and make pull requests. I’m particularly keen to find someone who can help with the ALSA audio switching bug which is keeping us on Kernel 3.16; the old patch stopped working on Kernel 4.x, resulting in auto-muting of the internal speakers being broken on the OpenFrame 1 when connecting to the headphone / line out 3.5mm socket.

Otherwise, if you find this software useful and have the means, I’m more than happy to accept donations to keep the lights on or support through the GitHub sponsorship programme. Or just a friendly wave on Twitter always brightens the day!

← Recent Articles