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. Multi-screen and Rotation

You can config the rotation of screen, and postiton, extension, copy of screens in system preferences.

The settings usually named “Monitor Settings” or “Display”.

If you are using touchscreens, multi-screen or rotation may has problems, here’s the solutions:

  • Screen rotated but the touch stays

So you need to rotate the touch, too. First use xinput to find the input device.

root@firefly:~# xinput 
⎡ Virtual core pointer                          id=2    [master pointer  (3)]
⎜   ↳ Virtual core XTEST pointer                        id=4    [slave  pointer  (2)]
⎜   ↳ PixArt USB Optical Mouse                          id=7    [slave  pointer  (2)]
⎜   ↳ himax-touchscreen                                 id=10   [slave  pointer  (2)]
⎣ Virtual core keyboard                         id=3    [master keyboard (2)]
    ↳ Virtual core XTEST keyboard                       id=5    [slave  keyboard (3)]
    ↳ adc-keys                                          id=6    [slave  keyboard (3)]
    ↳ rk805 pwrkey                                      id=8    [slave  keyboard (3)]
    ↳ fe6e0030.pwm                                      id=9    [slave  keyboard (3)]
    ↳ himax-touchscreen                                 id=11   [slave  keyboard (3)]

In Virtual core pointer we can see the touch device is himax-touchscreen with id 10.

Then change the content of /etc/X11/xorg.conf.d/05-touchscreen.conf like this:

Section "InputClass"
        Identifier "ff_touchscreen"
        MatchProduct "himax-touchscreen"
        Driver "libinput"
        Option "CalibrationMatrix" "1 0 0 0 1 0 0 0 1"

Identifier is just a name

MatchProduct need to be the device name we just found

And the key point is Option “CalibrationMatrix”

Normal it should be "1 0 0 0 1 0 0 0 1"
Rotate to left, change to "0 -1 1 1 0 0 0 0 1"
Rotate to right, change to "0 1 0 -1 0 1 0 0 1"
Invert (rotate 180), change to "-1 0 1 0 -1 1 0 0 1"

If you have more than one touchscreen, just add more InputClass to match.

Save the file and reboot to take effect.

  • Touch one screen but result shows on another screen

That is because input device is not mapping with the right output screen. First use xinput to find input device. Let’s say it is still himax-touchscreen id 10

Then use xrandr to find display device:

root@firefly:~# xrandr
Screen 0: minimum 320 x 200, current 2720 x 1280, maximum 8192 x 8192
HDMI-1 connected primary 1920x1080+0+0 (normal left inverted right x axis y axis) 0mm x 0mm
   1920x1080     60.00*+  59.94  
   1920x1080i    60.00    59.94  
   800x600       60.32  
   720x480       60.00    60.00    59.94    59.94    59.94  
DSI-1 connected 800x1280+1920+0 (normal left inverted right x axis y axis) 0mm x 0mm
   800x1280      59.98*+

There are two monitors, HDMI-1 and DSI-1, the himax-touchscreen is DSI-1, then start to map, run:

xinput map-to-output 10 DSI-1

10 is the id of himax-touchscreen, map it to DSI-1.

Now see if it works, if everything is fine, create a new file /etc/X11/Xsession.d/90-touchscreen-map, put the mapping cmd in that file to make it persistent.

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