Common Customization¶

APT Repository Configuration¶

Check System Version¶

lsb_release -a

Example output:

Distributor ID: Ubuntu
Description:    Ubuntu 20.04.6 LTS
Release:        20.04
Codename:       focal

Configuration File Paths¶

Format Type	Configuration File Path	Applicable Systems
One-Line-Style (legacy)	`/etc/apt/sources.list`	Debian ≤11 / Ubuntu ≤22.04
DEB822 (new)	`/etc/apt/sources.list.d/debian.sources`	Debian ≥12
DEB822 (new)	`/etc/apt/sources.list.d/ubuntu.sources`	Ubuntu ≥24.04

Switching to USTC Mirror¶

sources.list Format¶

sudo sed -i "s/deb.debian.org/mirrors.ustc.edu.cn/g" /etc/apt/sources.list
sudo apt update

DEB822 Format¶

# Debian
sudo sed -i "s/deb.debian.org/mirrors.ustc.edu.cn/g" /etc/apt/sources.list.d/debian.sources

# Ubuntu
sudo sed -i "s/deb.debian.org/mirrors.ustc.edu.cn/g" /etc/apt/sources.list.d/ubuntu.sources

sudo apt update

Note

Users in China are advised to replace the mirror with mirrors.ustc.edu.cn. Alternatives include mirrors.aliyun.com, mirrors.tuna.tsinghua.edu.cn, and other mirrors.

Startup Scripts¶

The system comes with a pre‑configured startup script at /etc/init.d/kickpi.sh. Simply append commands at the end of the script to have them executed at boot.

Example¶

sudo vim /etc/init.d/kickpi.sh

Add the following after dmesg -n1:

sudo sh /usr/bin/test_boot.sh

Startup Services (systemd)¶

Use systemd service units to manage auto‑start tasks.

Step 1: Create a Service Unit¶

sudo vim /usr/lib/systemd/system/test-boot.service

Content:

[Unit]
Description=boot test service
After=graphical.target

[Service]
Type=simple
ExecStart=/usr/bin/test.sh
User=root
Environment=DISPLAY=:0

[Install]
WantedBy=graphical.target

Step 2: Create the Execution Script¶

sudo vim /usr/bin/test.sh

#!/bin/bash
echo "hello test boot service" > /tmp/test.log

sudo chmod 777 /usr/bin/test.sh

Step 3: Enable / Disable the Service¶

# Enable (auto‑start at boot)
sudo systemctl enable test-boot.service

# Disable
sudo systemctl disable test-boot.service

Tip

After starting, check /tmp/test.log to verify the service is running.

Serial Console Auto‑Login¶

serial-getty@.service manages terminal login over serial ports (/dev/ttyS0/ttyS1, etc.). Modify the ExecStart line in /lib/systemd/system/serial-getty@.service to enable auto‑login.

Configuration Reference¶

Scenario	ExecStart Line
Default (requires credentials)	`ExecStart=-/sbin/agetty -o "-p -- \\u" --keep-baud 115200,57600,38400,9600 - $TERM`
Auto‑login as kickpi	`ExecStart=-/sbin/agetty --autologin kickpi --keep-baud 115200,38400,9600 %I $TERM`
Auto‑login as root	`ExecStart=-/sbin/agetty --autologin root --keep-baud 115200,38400,9600 %I $TERM`

User Management¶

Default Accounts¶

System	Username	Password
Debian	linaro	linaro
Debian	kickpi	kickpi
Debian	root	root
Ubuntu	kickpi	kickpi
Ubuntu	root	root
Buildroot	root	root

Changing Passwords¶

sudo passwd root           # Change root password
sudo passwd $(whoami)      # Change current user password

Switching Users¶

The desktop version defaults to user kickpi. For root privileges, prefix commands with sudo or switch with su root.

su <username>              # e.g., su root

Check Current Display Manager¶

cat /etc/X11/default-display-manager

SLiM¶

sudo vim /etc/slim.conf

Modify:

#default_user        kickpi    →    default_user        root

Reboot for changes to take effect.

LightDM¶

Configuration file paths (varies by system):

/etc/lightdm/lightdm.conf
/etc/lightdm/lightdm.conf.d/50-myconfig.conf

Modify the auto‑login user:

autologin-user=kickpi

Enable root login (comment out the restriction line):

sudo vim /etc/pam.d/lightdm-autologin

#auth required pam_succeed_if.so user != root quiet_success

Command‑Line / Desktop Mode Switching¶

Check Current Mode¶

sudo systemctl get-default

Switch to Command‑Line Mode (no desktop)¶

sudo systemctl set-default multi-user.target
sudo reboot

Restore Desktop Mode¶

sudo systemctl set-default graphical.target
sudo reboot

Locale Configuration¶

Changes take effect after reboot.

Set to English¶

sudo locale-gen en_US.UTF-8
sudo sed -i "s/^# *\\(en_US.UTF-8\\)/\\1/" /etc/locale.gen
sudo sh -c 'echo "LANG=en_US.UTF-8" >> /etc/default/locale'
sudo sh -c 'echo "export LC_ALL=en_US.UTF-8" >> /etc/profile.d/lang.sh'
sudo sh -c 'echo "export LANG=en_US.UTF-8" >> /etc/profile.d/lang.sh'
sudo sh -c 'echo "export LANGUAGE=en_US:en" >> /etc/profile.d/lang.sh'

Set to Chinese¶

sudo locale-gen zh_CN.UTF-8
sudo sed -i "s/^# *\\(zh_CN.UTF-8\\)/\\1/" /etc/locale.gen
sudo sh -c 'echo "LANG=zh_CN.UTF-8" >> /etc/default/locale'
sudo sh -c 'echo "export LC_ALL=zh_CN.UTF-8" >> /etc/profile.d/lang.sh'
sudo sh -c 'echo "export LANG=zh_CN.UTF-8" >> /etc/profile.d/lang.sh'
sudo sh -c 'echo "export LANGUAGE=zh_CN:zh" >> /etc/profile.d/lang.sh'

sudo reboot

Timezone Configuration¶

Changes take effect after reboot.

# Check current timezone
timedatectl

# Set to Shanghai timezone
sudo timedatectl set-timezone Asia/Shanghai

# Verify
date

Alternative (compatible with all systems):

# Set to Beijing time
sudo ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime

# Set to New York time
sudo ln -sf /usr/share/zoneinfo/America/New_York /etc/localtime

Time Configuration¶

System Time¶

date -s "2026-04-14 15:30:00"           # Set both date and time
date -s "2026-04-14"                    # Set date only
date -s "15:35:00"                      # Set time only
date                                    # View system time

Hardware RTC Time¶

hwclock -r                              # Read RTC
hwclock -r --rtc=/dev/rtc0              # Specify RTC device
hwclock -w                              # System time → RTC
hwclock --systohc                       # System time → RTC
hwclock -s                              # RTC → System time
hwclock --hctosys                       # RTC → System time

RTC Nodes¶

cat /sys/class/rtc/rtc0/date
cat /sys/class/rtc/rtc0/time

Auto‑Sync RTC → System Time at Boot¶

Edit /etc/init.d/kickpi.sh and change:

[ -f /dev/rtc0 ] && hwclock --systohc

to:

[ -f /dev/rtc0 ] && hwclock --hctosys

Note

--systohc = write system time to RTC; --hctosys = write RTC time to system.

Network Configuration¶

Common ifconfig Commands¶

ifconfig -a                             # View all interfaces
ifconfig eth0                            # View a specific interface
ifconfig eth0 192.168.1.101 netmask 255.255.255.0    # Set IP (temporary)
ifconfig eth0 up                         # Enable interface
ifconfig eth0 down                       # Disable interface
ifconfig eth0 hw ether 00:11:22:33:44:55             # Set MAC (requires down first)

Static IP Configuration¶

Note: Choose only one method. Do not use both to avoid conflicts.

Method A: Netplan (Debian requires installation; Ubuntu usually includes it)¶

sudo apt update
sudo apt install -y netplan.io
sudo mkdir -p /etc/netplan

sudo tee /etc/netplan/01-static-ip.yaml << "EOF"
network:
  version: 2
  renderer: networkd
  ethernets:
    eth0:
      dhcp4: no
      addresses:
        - 192.168.199.100/24
      routes:
        - to: 0.0.0.0/0
          via: 192.168.199.3
      nameservers:
        addresses: [8.8.8.8, 8.8.4.4]
EOF

sudo netplan apply

Verification:

ip addr show eth0                        # Check IP
ping -c 3 192.168.199.3                  # Test gateway
ping -c 3 8.8.8.8                        # Test external network

Restore DHCP:

sudo rm /etc/netplan/01-static-ip.yaml && sudo reboot

Method B: nmcli (NetworkManager)¶

nmcli con show   # Check connection name (e.g., "Wired connection 1")

nmcli con mod "Wired connection 1" \
  ipv4.method manual \
  ipv4.addresses 192.168.199.100/24 \
  ipv4.gateway 192.168.199.3 \
  ipv4.dns "8.8.8.8 8.8.4.4"

nmcli con down "Wired connection 1" && nmcli con up "Wired connection 1"

Restore DHCP:

nmcli con mod "Wired connection 1" ipv4.method auto ipv4.addresses "" ipv4.gateway "" ipv4.dns ""
nmcli con down "Wired connection 1" && nmcli con up "Wired connection 1"

Parameter Reference¶

Parameter	Example Value	Description
IP Address	`192.168.199.100`	Adjust as needed
Subnet Mask	`255.255.255.0` (i.e., /24)	Adjust to your actual subnet
Gateway	`192.168.199.3`	Check with `ip route \\| grep default`
DNS	`8.8.8.8`, `8.8.4.4`	Can use `114.114.114.114` as alternative

WiFi Hotspot¶

Check AP Mode Support¶

iw list | grep AP

Output containing AP / AP/VLAN indicates hardware support.

Method 1: Virtual Interface Hotspot (does not affect existing WiFi connection)¶

# 1. Install dependencies
sudo apt-get install -y util-linux hostapd dnsmasq iptables iproute2 haveged make

# 2. Create virtual interface (wlan0 → wlo2)
sudo iw dev wlan0 interface add wlo2 type __ap

# 3. Set MAC address for the virtual interface
sudo ip link set dev wlo2 address 22:33:44:55:66:00

# 4. Install create_ap
git clone https://github.com/oblique/create_ap
cd create_ap && sudo make install

# 5. Start hotspot (-c 11 = channel)
sudo create_ap -c 11 wlo2 wlan0 MySSID MyPassword

Note

Virtual interfaces are lost after reboot and need to be re‑created.

If Device or resource busy appears, stop it first:

sudo create_ap --stop wlo2

Method 2: Physical Interface Hotspot (dedicates the WiFi adapter)¶

# 1. Install dependencies + create_ap
sudo apt-get install -y util-linux hostapd dnsmasq iptables iproute2 haveged make
git clone https://github.com/oblique/create_ap
cd create_ap && sudo make install

# 2. Switch firewall to legacy iptables mode
sudo update-alternatives --set iptables /usr/sbin/iptables-legacy
sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy

# 3. Create hotspot MyAccessPoint password 12345678 sharing eth0 network (background)
sudo create_ap --no-virt wlan0 eth0 MyAccessPoint 12345678 &

# 4. Restore WiFi interface
sudo create_ap --fix-unmanaged

Build Toolchain¶

Includes gcc, g++, make, and other core build tools.

sudo apt update && sudo apt install -y build-essential manpages-dev

# 1. Install
sudo apt install samba samba-common

# 2. Set directory permissions
sudo chmod 777 /home/kickpi/

# 3. Add Samba user
sudo smbpasswd -a <username>

# 4. Edit configuration
sudo vim /etc/samba/smb.conf

Append the following at the end of the file:

[kickpi]
    comment = kickpi
    path = /home/kickpi
    public = yes
    writable = yes
    workgroup = kickpi

# 5. Restart service
sudo systemctl restart smbd

Tip

Windows access: \\<board-IP>\kickpi

Environment Setup¶

sudo apt install nfs-kernel-server rpcbind nfs-common

Server Side¶

# Configure the shared directory
mkdir -p /home/kickpi/nfs_share
chmod 777 /home/kickpi/nfs_share

sudo vim /etc/exports

Add:

/home/kickpi/nfs_share *(rw,sync,no_subtree_check,insecure)

# Start the service
sudo service nfs-kernel-server restart

# View exported shares on the server
showmount -e localhost

Client Side¶

# View the server's exported share list
showmount -e <server-IP>

# Mount
mkdir nfs_tmp
sudo mount -t nfs <server-IP>:/home/kickpi/nfs_share nfs_tmp/

# Verify
ls nfs_tmp/

SSH Configuration¶

SSH Connection¶

ssh <username>@<board-ip>

Method 1 (traditional)¶

sudo vim /etc/ssh/sshd_config           # Add PermitRootLogin yes
sudo /etc/init.d/ssh restart

Method 2 (recommended — survives upgrades)¶

echo "PermitRootLogin yes" | sudo tee /etc/ssh/sshd_config.d/root.conf
sudo systemctl restart ssh

This configuration is pre‑set in the SDK at:

debian/overlay/etc/ssh/sshd_config.d/root.conf

Remove Old SSH Keys¶

If the target Linux system has been reinstalled or SSH reset, the host key fingerprint changes. Windows may still have the old key and refuse the connection.

ssh-keygen -R <board-ip>

SCP File Transfer¶

scp <local_path> <username>@<board-ip>:<target_path>

Example¶

scp ./1.wav linaro@192.168.77.165:/home/linaro/Desktop/

Parameter	Description
`$local_path`	Local file path
`$username`	Board username
`$ip`	Board IP address
`$target_path`	Destination path

Frequently Asked Questions¶

Q1: System reboots automatically on the first boot after flashing¶

On first boot, the system automatically installs chip‑specific packages (libmali, ISP, etc.) and reboots the display service. This is normal behaviour. For custom projects, you can pre‑handle these package differences when building the image.

Q2: create_ap dnsmasq port conflict¶

dnsmasq: failed to bind DHCP server socket: Address already in use

Solution:

sudo lsof -i | grep dnsmasq             # Find the PID
sudo kill -9 <PID>

Q3: create_ap compatibility issue with iw ≥ 6.7¶

iw 6.7+ outputs frequencies with decimals (e.g., 2412.0 MHz), which create_ap regex does not match. Modify /usr/bin/create_ap:

@@ -321,9 +321,9 @@ can_transmit_to_channel() {

    if [[ $USE_IWCONFIG -eq 0 ]]; then
        if [[ $FREQ_BAND == 2.4 ]]; then
-           CHANNEL_INFO=$(get_adapter_info ${IFACE} | grep " 24[0-9][0-9] MHz \[${CHANNEL_NUM}\]")
+           CHANNEL_INFO=$(get_adapter_info ${IFACE} | grep " 24[0-9][0-9]\(\.0\+\)\? MHz \[${CHANNEL_NUM}\]")
        else
-           CHANNEL_INFO=$(get_adapter_info ${IFACE} | grep " \(49[0-9][0-9]\|5[0-9]\{3\}\) MHz \[${CHANNEL_NUM}\]")
+           CHANNEL_INFO=$(get_adapter_info ${IFACE} | grep " \(49[0-9][0-9]\|5[0-9]\{3\}\)\(\.0\+\)\? MHz \[${CHANNEL_NUM}\]")
        fi
        [[ -z "${CHANNEL_INFO}" ]] && return 1
        [[ "${CHANNEL_INFO}" == *no\ IR* ]] && return 1
@@ -339,7 +339,9 @@ can_transmit_to_channel() {

# taken from iw/util.c
ieee80211_frequency_to_channel() {
-   local FREQ=$1
+   local FREQ_MAYBE_FRACTIONAL=$1
+   local FREQ=${FREQ_MAYBE_FRACTIONAL%.*}

    if [[ $FREQ -eq 2484 ]]; then
        echo 14
    elif [[ $FREQ -lt 2484 ]]; then
@@ -356,7 +358,7 @@ ieee80211_frequency_to_channel() {
}

is_5ghz_frequency() {
-    [[ $1 =~ ^(49[0-9]{2})|(5[0-9]{3})$ ]]
+   [[ $1 =~ ^(49[0-9]{2})|(5[0-9]{3})(\.0+)?$ ]]
}

is_wifi_connected() {
    return 1
}

# 1. Change hostname
sudo hostnamectl set-hostname <new_username>

# 2. Update auto‑login configurations
/etc/lightdm/lightdm.conf
/etc/pam.d/lightdm-autologin
/lib/systemd/system/serial-getty@.service

# 3. Rename the user
sudo usermod -l <new_username> <old_username>

# 4. Migrate home directory
sudo mv /home/<old_username> /home/<new_username>
sudo usermod -d /home/<new_username> -m <new_username>

# 5. Clear graphical cache
rm -f /home/<new_username>/.Xauthority
sudo rm -rf /var/run/slim/*
sudo rm -rf /var/lib/slim/

# 6. Reconfigure slim
sudo pam-auth-update

Common Customization¶

APT Repository Configuration¶

Check System Version¶

Configuration File Paths¶

Switching to USTC Mirror¶

sources.list Format¶

DEB822 Format¶

Startup Scripts¶

Example¶

Startup Services (systemd)¶

Step 1: Create a Service Unit¶

Step 2: Create the Execution Script¶

Step 3: Enable / Disable the Service¶

Serial Console Auto‑Login¶

Configuration Reference¶

User Management¶

Default Accounts¶

Changing Passwords¶

Switching Users¶

Desktop Login Configuration¶

Check Current Display Manager¶

SLiM¶

LightDM¶

Command‑Line / Desktop Mode Switching¶

Check Current Mode¶

Switch to Command‑Line Mode (no desktop)¶

Restore Desktop Mode¶

Locale Configuration¶

Set to English¶

Set to Chinese¶

Timezone Configuration¶

Time Configuration¶

System Time¶

Hardware RTC Time¶

RTC Nodes¶

Auto‑Sync RTC → System Time at Boot¶

Network Configuration¶

Common ifconfig Commands¶

Static IP Configuration¶

Method A: Netplan (Debian requires installation; Ubuntu usually includes it)¶

Method B: nmcli (NetworkManager)¶

Parameter Reference¶

WiFi Hotspot¶

Check AP Mode Support¶

Method 1: Virtual Interface Hotspot (does not affect existing WiFi connection)¶

Method 2: Physical Interface Hotspot (dedicates the WiFi adapter)¶

Build Toolchain¶

Samba Sharing¶

NFS Sharing¶

Environment Setup¶

Server Side¶

Client Side¶

SSH Configuration¶

SSH Connection¶

Enable Root Login¶

Method 1 (traditional)¶

Method 2 (recommended — survives upgrades)¶

Remove Old SSH Keys¶

SCP File Transfer¶

Example¶

Frequently Asked Questions¶

Q1: System reboots automatically on the first boot after flashing¶

Q2: create_ap dnsmasq port conflict¶

Q3: create_ap compatibility issue with iw ≥ 6.7¶

Q4: SLiM login issues after changing username¶