Guide to Installing Omada Software Controller on Raspberry Pi OS - V5
Update - 4 October 2025
The latest Raspberry Pi OS (Debian Base Pixie) broke some of the install repo's and the install instructions have been updated and tested to work wih a fresh install of the current Raspberry Pi OS as of this date.
The Raspberry Pi OS (Legacy) based on Debian Bookworm was tested and does not work out of box either, so does not offer any benefit - the installation instructions is now based on the default Raspberry Pi OS version available at this date.
This is a bare metal install on 64 bit Raspberry Pi OS - no Ubuntu server, no Docker. Tested with version 5.15.24 of the Controller software. I have it running on a Model 4B and Model 5 Pi. The recent versions of the Omanada SDN Controller does not run on the Model 3B, 3B+
To update the Controller version on a working Raspberry Pi without updating Raspberry Pi OS, do the following
sudo tpeap stop
sudo apt remove omadac
- During the uninstall process select the option to save the current settings. This allows the existing settings to be applied automatically to the updated version
wget https://static.tp-link.com/upload/software/2025/202508/20250802/omada_v5.15.24.19_linux_x64_20250724152622.deb
sudo dpkg -i omada_v5.15.24.19_linux_x64_20250724152622.deb
Links have been updated and verified on most recent install
Instructions:
1. Download & install latest 64 bit LITE version of Raspberry pi OS to new sd card of your choice from the link below. Note - the legacy version of Raspberry Pi OS will not work
https://downloads.raspberrypi.org/raspios_lite_arm64/images/
This is not a guide to installing Raspberry Pi OS so I won't provide detailed instructions on that.
2. Download and install libssl1.1 manually
wget http://security.debian.org/debian-security/pool/updates/main/o/openssl/libssl1.1_1.1.1w-0+deb11u4_arm64.deb
sudo dpkg -i libssl1.1_1.1.1w-0+deb11u4_arm64.deb
3. Download and install version 4.4.18 of MongoDB mongodb-server from https://www.mongodb.com/download-center/community/releases/archive
wget https://repo.mongodb.org/apt/ubuntu/dists/focal/mongodb-org/4.4/multiverse/binary-arm64/mongodb-org-server_4.4.18_arm64.deb
sudo dpkg -i mongodb-org-server_4.4.18_arm64.deb
Note this post explaining that MongoDB V4.4.19 will not work.
3. Check that curl is installed
apt list curl
5. Download and install openjdk-21
sudo apt install openjdk-21-jdk-headless
6. Install jsvc
sudo apt install jsvc
7. If you have multiple versions of OpenJDK installed then you need to tell system which java to use
sudo update-alternatives --config java
Selection Path Priority Status
------------------------------------------------------------
0 /usr/lib/jvm/java-11-openjdk-arm64/bin/java 1111 auto mode
1 /usr/lib/jvm/java-11-openjdk-arm64/bin/java 1111 manual mode
* 2 /usr/lib/jvm/java-8-openjdk-arm64/jre/bin/java 1081 manual mode
Press <enter> to keep the current choice[*], or type selection number:
Now select the option pointing to the version of OpenJDK you want to use.
8. Download and install latest version Omada SDN controller
wget https://static.tp-link.com/upload/software/2025/202508/20250802/omada_v5.15.24.19_linux_x64_20250724152622.deb
sudo dpkg -i omada_v5.15.24.19_linux_x64_20250724152622.deb
If all went well the controller should start and you should get the following message
Install Omada Controller succeeded!
==========================
Omada Controller will start up with system boot. You can also control it by [/usr/bin/tpeap].
check omada
Starting Omada Controller. Please wait.........................................................................................................................
Started successfully.
You can visit http://localhost:8088 on this host to manage the wireless network.
========================
Now you can access the web interface of the Omada Controller by pointing you web browser from any PC on the same network to
http://<IP_address_of_Omada_Controller>:8088
- Copy Link
- Subscribe
- Bookmark
- Report Inappropriate Content
I am using the "legacy 64 bit OS" in the other OS tab for the pi 3b
Do I need to use a different one, please tell me which one specifically if so.
- Copy Link
- Report Inappropriate Content
@CarterKraft Definitely need the LATEST Raspberry Pi OS Lite (64bit) - some of the packages to be installed wont run on the legacy version. The current download is at the link below, but may change as they release updates
https://downloads.raspberrypi.com/raspios_lite_arm64/images/raspios_lite_arm64-2023-12-11/2023-12-11-raspios-bookworm-arm64-lite.img.xz
Also, after new install of the OS and before you start installing Omada Controller you need to do
sudo apt update
and
sudo apt upgrade
- Copy Link
- Report Inappropriate Content
- Copy Link
- Report Inappropriate Content
All went well on the newest OS, it got to the same part where the OmadaC was loading stuck at 60% for 15 minutes. I closed the ssh connection and power cycled the Pi.
I logged back in to SSH and tried to start OmadaC but it says it is already running.
:~ $ sudo /usr/bin/tpeap start
Omada Controller is already running. You can visit http://localhost:8088 on this host to manage the wireless network.
I can't seem to access it though via the localhost, I have used the IP address in the "local host" is that all I need to do?
I pinged the IP in the windows CMD and it was 100%.
What do I need to do?
- Copy Link
- Report Inappropriate Content
I tried to cycle the Omadac vai SSH and it appeared to work?
@omadacloud:~ $ sudo /usr/bin/tpeap status
Omada Controller is running. You can visit http://localhost:8088 on this host to manage the wireless network.
@omadacloud:~ $ sudo /usr/bin/tpeap version
Omada Controller v5.12.7 for Linux (X64)
@omadacloud:~ $ sudo /usr/bin/tpeap stop
Stopping Omada Controller
Stop successfully.
@omadacloud:~ $ sudo /usr/bin/tpeap start
check omada
Starting Omada Controller. Please wait................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
Started successfully.
You can visit http://localhost:8088 on this host to manage the wireless network.
- Copy Link
- Report Inappropriate Content
@CarterKraft This screen indicates that it is working correctly.
Now point you web browser to http://<IP_address_of_raspberry_pi>:8088 and you should be in business
- Copy Link
- Report Inappropriate Content
I can stop/start it via ssh but when I try to connect via browser I have had limited success.
One time it loaded a setup wizard with 6 steps, I filled out each field but when I tried to "finish" it didn't seem to complete the icon just say and spun.
I tried a different pi3B I have with a fan case and nothing changed there either.
- Copy Link
- Report Inappropriate Content
@CarterKraft Perhaps time to try a more modern Pi. I have 2 active installations, one on a Pi4B and One on a Pi5, both with 4GB RAM. Both run perfectly.
In the past I ran on a Pi3B+ as well, but that was in the days of OpenJDK8.
Inf you want to try to install OpenJDK8 and see how that runs on the Pi3B+ it may be worth trying, otherwise may be time for a hardware upgrade
- Copy Link
- Report Inappropriate Content
- Copy Link
- Report Inappropriate Content
I am going to retry with the lite 64 bit OS
- Copy Link
- Report Inappropriate Content
Information
Helpful: 12
Views: 117938
Replies: 143
Voters 3
