1. Ubuntu manual

This Ubuntu manual is applicable to Firefly Ubuntu Desktop & Minimal system. Some introductions related to UI display are only for Desktop system.


The features of Ubuntu Desktop system are as follows:

  • The desktop environment uses LXDE, Lubuntu+Firefly custom theme, simple and beautiful. (Ubuntu 20.04 uses LXQt)

  • Xserver uses GPU + RGA for 2D acceleration, runs smoothly, and takes up less CPU resources.

  • For embedded platforms, streamline system services.

  • Provide OpenGL and OpenCL support based on Arm Mali GPU.

  • Provide video hard codec support based on Rockchip VPU + Mpp.

  • Adapt to QT, Docker, Electron and other development frameworks.

  • Provide a series of interfaces to operate onboard resource devices.

  • The system adopts overlayfs file system, supports exporting rootfs, secondary packaging, restoring factory settings and other functionsa.

The features of Ubuntu Minimal system are as follows:

  • No desktop environment, less resources, after simplifying network management, only 40M memory.

  • For embedded platforms, streamline system services.

  • Adapt to QT, Docker, Electron and other development frameworks.

  • Provide a series of interfaces to operate onboard resource devices.

  • The system adopts overlayfs file system, supports exporting rootfs, secondary packaging, restoring factory settings and other functions.

1.1. User and password

1.1.1. Ubuntu Desktop system

After the Firefly Linux Desktop system boots up, it will automatically log in to the firefly user.

If there is a debugging serial port connected, the serial terminal automatically logs in to the root user.

  • Firefly user password: firefly

  • Root user: No root password is set by default. Firefly users configure the root password by themselves through the sudo passwd root command.

1.1.2. Ubuntu Minimal system

  • After the Firefly Linux Minimal system is booted, it will automatically log in to the root user with the password firefly

  • The system has added OpenGL ES, OpenCL, DRM support.

  • Due to security policy, sshd does not support remote login via root user by default, it can be turned on by the following method

sed -i -e 's/#PermitRootLogin.*/PermitRootLogin yes/g' /etc/ssh/sshd_config

1.2. ADB use

1.2.1. ADB

Connect the device and the host with a Type-C data cable, then enter the following commands:

adb devices
adb shell

1.2.2. Network ADB

Check the IP address of the development board and access the PC through the network:

adb connect + IP
adb shell


Core-3399-JD4 needs to modify kernel/arch/arm64/boot/dts/rockchiprk3399-firefly-aiojd4.dts to support the use of ADB, set usbdrd_dwc3_0 to peripheral mode, then the usb can only be used as a slave device use.

&usbdrd_dwc3_0 {
     dr_mode = "peripheral";

Similarly, AIO-3399Pro-JD4 needs to modify kernel/arch/arm64/boot/dts/rockchip/rk3399pro-firefly-aioc.dts to support the use of ADB.

Then recompile and flash the Kernel.

Core-3399-JD4 and AIO-3399Pro-JD4 use dual male USB data cables to connect the device usb3.0 interface and the PC host.

1.3. Display version information

  • ffgo

The ffgo command provided by Firefly can easily view the firmware information, which is convenient for developers to debug and locate problems.

When users need to feedback information to Firefly, they need to attach the version information displayed by ffgo version.

root@firefly:~# ffgo
         ffgo: show this usage
         ffgo update: update ffgo
         ffgo version: get version
         ffgo cmdlist: get support cmd list
         ffgo [cmd]: run cmd in cmd list

root@firefly:~# ffgo update
update success
root@firefly:~#  ffgo version
OS:      Ubuntu 18.04.5 LTS
MODEL:   Firefly RK3566-ROC-PC HDMI(Linux)
FIREFLY: v2.04-1-g618089a
DATE:    20210316-1035
KERNEL:  Linux version 4.19.172 (liaoxt@tchip16) (gcc version 6.3.1 20170404 (Linaro GCC 6.3-2017.05), GNU ld (Linaro_Binutils-2017.05) #107 SMP Mon Apr 19 09:01:32

1.4. linux-headers and linux-image

linux-headers and linux-image are deb packages can be installed into Debian/Ubuntu system.

linux-headers include header files, can make the device able to compile drivers.

linux-image includes driver modules, install them into device for kernel to use. Besides, if device support extboot, self-building linux-image will also include a kernel, install it will update your device’s kernel.

How to check if device is using extboot? Please see specific board’s wiki Compile Ubuntu firmware page, Partial compilation part. If there’s no extboot related content, that means it does not support extboot.

1.4.1. How to get Download from Firefly

Firefly officially provides linux-headers and linux-image, which are convenient for customers to compile drivers on the development board. Packages provided by us include no kernel, will not update kernel after installation, can be used in many boards.

For the package download of each board, please go to the official Firefly Download page to download. After selecting the board, click the Download page, it is generally in the Resources section, and the name is linux-headers. Build from SDK

The version of headers and image downloaded above may mismatch your firmware, and they are not helpful with customization needs. So build them from SDK is recommended.

Prepare environment, get SDK and comfigure for compile, please check the specific deivce’s wiki.

Build under SDK root directory:

# select board config
./build.sh xxxx.mk
# build
./build.sh kerneldeb

Output files are in SDK root directory:


If SDK is using extboot, then linux-image inludes kernel, so it can only be used in specific model of boards that you select in ./build.sh xxxx.mk.

1.4.2. Install

The following takes the installation of ROC-RK3568-PC as an example:

Put deb packages in device to install, for headers, you have to compile them after installation

For device supports extboot, reboot to update kernel after installing image, then compile headers

# Install
sudo dpkg -i linux-headers-4.19.172_4.19.172-189_arm64.deb
sudo dpkg -i linux-image-4.19.172_4.19.172-189_arm64.deb

# Prepare
sudo apt install -y build-essential python libssl-dev

# Compile
cd /usr/src/linux-headers-4.19.172
make headers_check
make headers_install

# make scripts may go wrong but it doesn't matter
make scripts

1.6. Export device system

This chapter applies to: When the user has completed the deployment of the work environment on one device, the current environment needs to be completely exported for batch deployment to other devices on the same platform.Users can also backup the current development environment by exporting the device file system.

The export device system is divided into two steps

  1. Export the device rootfs on the board

  2. Re-package the complete firmware, re-package rootfs and other firmware components to generate complete firmware

1.6.1. Export device rootfs

  1. In ubuntu18.04 environment, install fireflydev

     sudo apt update
     sudo apt install fireflydev
  2. Use ff_export_rootfs to export the root file system

  • It is recommended to use a mobile hard disk with a larger capacity

  • The export tool will perform operations such as apt clean to reduce the file system size

  • Export the root file system to the /media/firefly/AC91-C4AE/ directory, the actual example is as follows:

    root@firefly:~# ff_export_rootfs
            ff_export_rootfs </path/to/store> [-t <ext4|btrfs>]
    ff_export_rootfs /media/firefly/AC91-C4AE/
  • Compresses the root file system and removes unnecessary empty space to reduce memory usage

        #Some customers say that the exported rootfs size is 3.3G, but only 3G is actually used, because the rootfs is not compressed
        e2fsck -p -f Firefly_Ubuntu_18.04.6_rootfs.img
        resize2fs  -M Firefly_Ubuntu_18.04.6_rootfs.img

1.6.2. Second package complete firmware

  • Tool download: firefly-linux-repack

  • Operating environment: PC (because the provided tool is an x86 program, it needs to be used on the PC)

  • Install the necessary software packages on the PC side: sudo apt-get install lib32stdc++6

    ├── bin
    │ ├── afptool
    │ └── rkImageMaker
    ├── pack.sh
    ├── Readme_en.md
    ├── Readme.md
    └── unpack.sh
  1. Unpack Copy the officially released firmware to the current directory, rename it to update.img, execute unpack.sh After unpacking is complete, the generated file is in the output directory.

  2. Combined package Keep the current directory structure, file name, etc. unchanged, replace the file with the same name under output/ with the customer’s own file Execute pack.sh, after execution, generate new_update.img, which is the packaged firmware The rootfs file name must be rootfs.img The file name of parameter.txt must be parameter.txt

  • Note: During the package process, if the rootfs partition is not the last partition, the program will follow the size of the rootfs file, Automatically modify the size of the rootfs partition in parameter.txt. If the user himself changes parameter.txt, please pay attention to the entire package process.

tar -xzf firefly-linux-repack.tgz
cd firefly-linux-repack
mv /xxx/FIREFLY-RK3399-UBUNTU18.04-GPT-20200714-1510.img update.img

cp /customer/rootfs.img output/Image/rootfs.img

ls new_update.img

1.7. Screen rotation

Firefly Ubuntu Desktop uses the ff_rotate script to control screen rotation:

  • ff_rotate

root@firefly:~# ff_rotate

        rotate screen and touchscreen
                run as root
                ff_rotate <orientation>
                        orientation: left, right, normal, inverted
#Image output flip
root@firefly:~# ff_rotate inverted

1.8. Restore factory settings

Firefly Ubuntu supports restoring factory settings.

Note that this factory setting means that the device is restored to its initial state after the last firmware upgrade

root@firefly:~# recovery
Usage: update <option>

Options are:
        ota | update [path]:
                update firmware, if no path, use default path
        factory | reset:
                reset to factory

Use recovery reset to restore to factory settings

1.9. Startup program

Firefly Ubuntu18.04 Desktop can use the following methods to set the boot-up program, but you need to pay attention to the operating permissions and current environment variables:

$ vim /home/firefly/.config/lxsession/Lubuntu/autostart
@/bin/mkdir /home/firefly/ssddd

Each command starts with @, and the above example will create the /home/firefly/ssddd directory

Firefly Ubuntu20.04 Desktop you can open LXQt start menu and click Preferences > LXQt Setings > Session Settings, choose Autostart page in the popped window to add autostart applications

Or you can add application’s .desktop file under /etc/xdg/autostart/

1.10. Use root to log in to the system interface

  • autologin-user=root

root@firefly:~# cat /etc/lightdm/lightdm.conf.d/20-autologin.conf

1.11. On-screen keyboard

The official Ubuntu system comes with an on-screen keyboard, you can click to open it in the menu bar: _images/onboard.jpg