How to install Omada Software Controller 5.12.x on Raspberry Pi OS (Bookworm) on Raspberry Pi 4B

How to install Omada Software Controller 5.12.x on Raspberry Pi OS (Bookworm) on Raspberry Pi 4B

How to install Omada Software Controller 5.12.x on Raspberry Pi OS (Bookworm) on Raspberry Pi 4B
How to install Omada Software Controller 5.12.x on Raspberry Pi OS (Bookworm) on Raspberry Pi 4B
2023-10-12 08:08:27 - last edited 2023-11-16 01:39:40
Hardware Version: V5
Firmware Version:

This will be a fresh install on Raspberry Pi 4B with Raspberry Pi OS (Bookworm), not Bullseye. Using the Omada SDN Controller 5.12.7


Use this guide if you want to update from 5.9.31 to 5.12.x.


- Use 64-bit version full Bookworm (arm64 or aarch64)
- MicroSD card >= 32GB
- Internet connection
- Download Raspberry Pi Imager from here


Step 1: Raspberry Pi - install Raspberry Pi OS on the microSD card


A. plug in the MicroSD card
B. download Raspberry Pi Imager from .
- download for Windows 10 if you are Windows like me.
- install "imager_x.x.x.exe" with the wizard
- open Raspberry Pi Imager as Admin > click on CHOOSE OS > select Raspberry Pi OS (other) > select Raspberry Pi OS (64-bit) Bookworm


Note: I select Bookworm and Full version instead of Lite. You can try Lite if you want.

- under Storage > select your MicroSD card
- go into the Advanced option that looks like a Cog wheel >
 + Set hostname: *whateveryouwant*.local - for me: Omada.local
 + Enable SSH > using public-key authentication

OPTIONAL: SSH-gen key pair (you can do this on whatever OS you want. I'm doing it on Linux so use.


   ssh-keygen -t rsa -b 4096

Note: 2 keys are made. 1 is public key, 1 is private key. You send the public key to the machine you want to log in(Raspberry Pi). You keep the private key on the machine you use (your PC) to prove who you are. I named them nameofthekey and

- I named the key omada and

- Use SSH username and password that you made within Raspberry Pi Imager.

IMPORTANT: Before writing the OS onto the MicroSD card, Enable the SSH option with Allow public-key authentication only, so you don't have to use password to SSH.

- Copy the long string inside of that you made in ssh-keygen. Paste it into the Setting (Cog wheel) inside of Raspberry Pi Imager.
- Use the username pi if you want.
- The IP address of the pi on my network is or hostname omada. Your IP address for the Pi depends on your network.

 + Set username > username: yourname > password: yourpassword
 + for me username: omada and password: omada
NOTE: Please change these names and password to your own choosing to enhance the security.

SSH will the main method that you will interact with Raspberry Pi in the back end. So proper configure this step or you will have to re-flash the MicroSD card.


Step 2: SSH into the Pi

I'm using Terminal on Windows 10 to SSH into the Raspberry pi. I left the private key in Home user folder of Windows 10.


  ssh -i /Users/admin/omada omada@

It should looks like this when you have successfully SSH into the Pi


Step 3: Update and upgrade - to avoid older repo and old bugs


    sudo apt update && sudo apt upgrade -y

Step 4: Download and install MongoDB - please use MongoDB 4.4.18


A. Install MongoDB




    sudo apt install /home/omada/mongodb-org-server_4.4.18_arm64.deb

Note: use `arm64`. Not amd64 or i386 or arm32. Because we're on Raspberry Pi which use ARM architecture.


B. Check if mongodb is running


    sudo systemctl daemon-reload

    sudo systemctl enable mongod

    sudo systemctl start mongod

Step 5: Install curl


A. check if Raspberry Pi OS already has curl

    apt list curl

B. If not, install curl

    sudo apt install curl

Step 6: Install OpenJDK 17 and JVSC 1.1.0, fix a symbolic link

Background: Debian and Ubuntu removed repositories related to Java 8 so you cannot easily install Java 8 with a simple apt command. Java 11 is in Bullseye. Java 17 still works with Omada SDN controller so we will proceed with Java 17 on Bookworm.

A. Install the dependencies first: autoconf, make, gcc, JDK 17.


    sudo apt install autoconf make gcc

    sudo apt install openjdk-17-jdk-headless


B. Compile and install JVSC 1.1.0

Download the source codes from Apache official website, then compile and install.

Note: that the following links are for reference only and may be invalid due to version update, you can visit the website to confirm the current version and download link.

Do not download the common-daemon-1.3.4-native-src.tar.gz. Use the commons-daemon-1.3.4-src.tar.gz instead.


You can read the INSTALL.txt in unix folder if you want to understand how to compile and install.


    tar -xzf commons-daemon-1.3.4-src.tar.gz

    cd commons-daemon-1.3.4-src/src/native/unix

    sh support/

Note: You must cd outside of support directory to run sh as is above. Otherwise it won't run. Running `sh` WILL NOT WORK inside of support directory.

Note: "/usr/lib/jvm/java-17-openjdk-arm64" is the default installation path of OpenJDK-17. 

    ./configure --with-java=/usr/lib/jvm/java-17-openjdk-arm64

then you can run


 Create a soft link from your JSVC path

    sudo ln -s /home/omada/commons-daemon-1.3.4-src/src/native/unix/jsvc /usr/bin/

C. Fix a symbolic link in Java 17

    sudo mkdir /usr/lib/jvm/java-17-openjdk-arm64/lib/aarch64

    sudo ln -s /usr/lib/jvm/java-17-openjdk-arm64/lib/server /usr/lib/jvm/java-17-openjdk-arm64/lib/aarch64/


All this to avoid TP-Link Omada Controller Install Java Home Error. It might stop the Omada Controller from starting when it reboots.

It looks something like this


Starting Omada Controller. Please wait.Cannot find any VM in Java Home /usr/lib/jvm/java-17-openjdk-arm64/


D. Fix apt missing packages


    sudo apt --fix-broken install

Step 7: Download and install latest version Omada SDN controller from TP-Link Official download page

Note: We're going to use Omada_SDN_Controller_v5.12.7_Linux_x64.deb

    cd ~


    sudo dpkg --ignore-depends=jsvc -i Omada_SDN_Controller_v5.12.7_Linux_x64.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 use the IP Address of the Raspberry Pi to setup the controller in your browser of choice.


Step 8: Hold back packages so you don’t accidentally update the mongodb to a newer version.

To list packages that can be upgrade


    apt list --installed | grep "mongodb"


Hold back mongodb packages


   sudo apt-mark hold mongodb-org-server

To check if they are held back

    apt-mark showhold

To cancel the hold

    sudo apt-mark unhold mongodb


By now, everything should properly. You can go ahead and setup the Controller with the IP address:8083. But please go ahead and reboot the Pi in order to check if everything is working properly.


OPTIONAL - Step 9: use these commands to check if everything is working correctly

If you happen to lose power or reboot the Raspberry Pi, after SSH into the Pi to check if everything booted properly, use the follow commands

Note: It takes around 60s before RPi allows you to SSH. It takes around 2 minute 30 seconds before Omada Software Controller fully run.

Check the running status of the controller

    sudo tpeap status


Start the controller


    sudo tpeap start


Stop the controller


    sudo tpeap stop


Check if mongodb is running

    service mongod status




    ps -ax | grep mongo

after the first reboot to check if apt is working properly.

1 Reply
Re:How to install Omada Software Controller 5.12.x on Raspberry Pi OS (Bookworm) on Raspberry Pi 4B
2023-11-15 21:14:28 - last edited 2023-11-15 23:25:36

  @YuukiA I believe you have a type here in step 6.B:


"./configure --with-java=/usr/lib/jvm/java-17-openjdk-amd64"


It should be 


"./configure --with-java=/usr/lib/jvm/java-17-openjdk-arm64"



Helpful: 1

Views: 1223

Replies: 1

Related Articles