Bringing up a new operating system on embedded hardware often requires navigating through fragmented documentation, configuring build environments, and troubleshooting unexpected issues. prplOS, an open-source operating system based on OpenWrt, is designed for carrier-grade networking devices, offering modularity, security, and interoperability. 

This guide provides a structured walkthrough for setting up prplOS on the Banana Pi R3, covering essential steps such as cloning the repository, configuring the build, compiling the system, and flashing the image onto the device. While prplOS offers a wide range of advanced features, this article focuses on the fundamental setup required to get the system running efficiently. 

What is prpl Foundation? 

The prpl Foundation is an open-source community that brings together service providers, OEMs, silicon vendors, ISVs, and developers to create standardized solutions for carrier-grade Customer Premises Equipment (CPE). The foundation is structured into several working groups, each focusing on a specific aspect of the ecosystem: 

• prplOS – an embedded operating system based on OpenWrt 

• prplMesh – a framework for multi-vendor mesh networking 

• LCM (Life-Cycle Management) – tools for managing device software lifecycle 

• High-Level API – standardized interfaces for application development 

• Low-Level API – hardware abstraction for improved platform compatibility 

• Security – mechanisms ensuring data protection and device integrity 

• Certification – compliance standards and testing 

This article focuses specifically on prplOS, an open-source operating system designed to meet the requirements of telecommunications and network service providers. Built on OpenWrt, prplOS provides a flexible, modular foundation for developing and deploying custom networking solutions. 

Why choose prplOS? 

• Interoperability – supports multiple hardware platforms 

• Security – integrates secure boot, firmware updates, and sandboxing 

• Flexibility & Modularity – allows customization and future expansion 

• Efficiency – optimized for resource-constrained devices 

• Community-Driven – developed collaboratively by industry leaders 

Where to find prplOS documentation? 

While much of the technical detail about prplOS can be found directly in the source code, additional documentation is available to help navigate its structure and features. Many prplOS modules include a README.md file within their respective Git repositories, serving as a valuable starting point for understanding their functionality. 

For more in-depth information, the prplMesh wiki provides documentation on specific aspects of the project: 

🔗 prplMesh Wiki 

Additionally, prpl Foundation’s YouTube channel contains presentations and discussions covering broader organizational and technical topics related to prplOS and its ecosystem. 

prplOS repositories and build setup 

PrplOS git repository can be found at gitlab: 

https://gitlab.com/prpl-foundation/prplos/prplos 

We can clone it via command  

Then in prplos directory we have everything to start compiling for any existing target or prepare new profiles to build our own targets. As we plan to build for banana pi R3 device we need to create a profile for that target. Profile is special yml file that provides build parameters like what is the target and what are compilation options. Here is the list of profiles:  

To apply one or more profiles, we must run following script:  

Here also we can list available profiles:  

Usage of that script is quite intuitive, for example if we want to build for x86 target, built with plplmesh and enabled debuging tools and logs, we can use such command:  

This script will take care of all configurations, so .config file will be prepared, all needed packages will be updated and installed in build project. Once the gen_config script completes, the only remaining step is to build the project using make. 

In case of build problems, we can rerun it with that command:  

to see what the problem is.  

Before we start to build project for a new platform, we have to prepare a profile yml file. 

In that yml profile file we can distinguish the following sections:  

• profile, target and subtarget which correspond to the same parameters of openwrt. 

• packages – which are the packages that we want to add to our openwrt build, like iperf if we need to run some iperf tests, 

• diffconfig – there are some additional config options that do not add package but configure some parameters or enabling features, like CONFIG_DRIVER_11AX_SUPPORT.  

After preparing build configuration of prplOS for banana pi R3 device it can be run: 

then

Successful build will generate few types of images.  

One of them is sdcard image, which can be written to sdcard and then used in banana pi R3 board to boot prplOS for the first time. 

Configuring prplOS After Installation 

Some configuration parameters need to be set up by uci entry prplmesh: 

After flashing prepared prplos firmware not everything might be set. So missing parameters should be setup accordingly, like:  

My bpi-r3 device after upgrading with already prepared prplOS boots up in agent mode: 

This is the default mode after first boot. 

Other router parameters can be set via data model. There are few ways of doing that. 

One way is to use ubus-cli tool:  

Example:

The second way is to use data model dmtui tool, which is accessible only via ssh connection not serial console.  

To do this we need IP address of br-lan interface:  

Then

and

Generally, all configuration of prplOS router should be done via data model except prplmesh parameters set up via uci. 

At the beginning we have serial port access to the board. To use ssh via ethernet we must setup IP address of br-lan interface. The default IP address is 192.168.1.1. But as we plan to have few such devices, and our test network has already a different IP addresses range, it would be good to change that IP address. 

We can do this via command:  

Then after connecting ethernet cable from our PC to BPI-R3 lan port, we can start using ssh:  

EasyMesh specify two types of devices: 

•  multi-ap device with multi-ap controller and multi-ap agent, this is so called gateway, 

•  multi-ap device with only multi-ap agent this is extender.  

So, let’s start with first type of device. 

This can be done via uci commands:  

This can be verified like that:  

So now when multi-ap controller is setup and running we can start configuring WiFi interfaces. 

BPI-R3 device has two wifi cards, so we have two radios. We can start setting up regulatory domain for those radios:  

then we can set channel for each radio:  

And SSID.

For 2.4G band: 

For 5G band: 

Then we just need to enable access points: 

And at the end we enable all radios:  

At this moment we have single wireless access point working on prplOS. And this is just beginning, we can start working on more sophisticated functionalities that are possible to run on prplOS. To list only few:  

prplMesh – functionality to setup EasyMesh network, 

LCM(Life Cycle Management) – functionality to give operators flexible and efficient way to manage the lifecycle of applications and services on embedded devices, 

Remote management – functionality implementing standardized by Broadband Forum like TR-069 or TR-369. 

Final Thoughts and Next Steps 

Setting up prplOS on the Banana Pi R3 involves cloning the repository, configuring a build profile, compiling the system image, and flashing it onto the board. Once installed, additional runtime parameters can be adjusted via UCI or ubus to align with specific network requirements. 

Beyond basic setup, prplOS includes advanced features such as prplMesh for EasyMesh networking, Life-Cycle Management (LCM) for remote software updates, and standardized remote management interfaces. These capabilities enable flexible deployment and integration into carrier-grade environments. 

For further customization, the official documentation and source repositories provide additional resources on configuration, debugging, and feature expansion. 

marek puzyniak

Senior Software Engineer

Passion And Execution

Who We Are

At Holisticon Connect, our core values of Passion and Execution drive us toward a Promising Future. We are a hands-on tech company that places people at the centre of everything we do. Specializing in Custom Software Development, Cloud and Operations, Bespoke Data Visualisations, Engineering & Embedded services, we build trust through our promise to deliver and a no-drama approach. We are committed to delivering reliable and effective solutions, ensuring our clients can count on us to meet their needs with integrity and excellence.