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.

 

Requirement:
- 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 nameofthekey.pub.
 

- I named the key omada and omada.pub

- 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 omada.pub 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 192.168.16.105 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@192.168.16.105

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

 

    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 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.

    wget https://dlcdn.apache.org/commons/daemon/source/commons-daemon-1.3.4-src.tar.gz

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

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

    sh support/buildconf.sh

Note: You must cd outside of support directory to run sh as is above. Otherwise it won't run. Running `sh buildconf.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

    make

 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 ~

    wget https://static.tp-link.com/upload/software/2023/202303/20230321/Omada_SDN_Controller_v5.12.7_Linux_x64.deb

    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

 

or

 

    ps -ax | grep mongo

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