Cheatsheet for Setting up Pi Devices

Table of Contents

Nowadays it is quite easy to deploy open-source projects on a well-configured server, especially those in the Python ecosystem. However, it is not “that” easy if you need to setup a development board from scratch, especially for new beginners. Even an expeirenced developer might need to deal with possible exceptions. Anyway, it’s always good to have a TODO list to ensure the setup process is quick and nothing is missed —— so comes this cheatsheet.

This is mostly based on my personal development requirements. It is best applicable for boards like Orange Pi and Raspberry Pi.

Hardware

Network connection

Wired or wireless

Keyboard, mouse, and display

For first-boot setup and local debugging

TF (MicroSD) card with OS flashed

  • Ubuntu latest LTS recommended for general development
    • I prefer server OS over desktop ones cuz it’s more lightweight
    • It also prevents the GUI affecting performance measurement
  • If money allows, buy a larger card yourself (>=256GB in my case)
    • The default 32/64GB is insufficient for many tasks
  • Imaging tools: BalenaEtcher (general), and Raspberry Pi Imager (R Pi)
    • R Pi Imager supports headless setup through customized configuration

System

Set/change the username and password if required

  • Recommended format: device (raspi, orangepi) [+ user info (if not shared)]

Connect to the (wireless) network

  • On R Pi, you can perform a headless setup to automatically connect
    • The network is managed by cloud-init, netplan, and networkd by default.
    • I switched to NetworkManager as it’s more familiar.
  • On others, use the NetworkManager with Ubuntu
    • Detect available networks: nmcli dev wifi
    • Connect by ssid: nmcli dev wifi connect <ssid> password <passwd>

Configure the network if required

  • Tsinghua TUNET authentication: GoAuthing
  • Setup the proxy: TODO
    • Make sure not to allow LAN connection in public network

Install/update necessary packages

  • Switch sources when needed
  • Update and upgrade first: sudo apt update && sudo apt upgrade

Setup SSH server for remote access

  • sshd to launch the SSH server
  • ifconfig to view the device IP
  • ssh -p <port> user@ip to test login
  • ssh-copy-id for key auth

Others

(Optional) use vendor-provided tools like raspi-config (for Raspberry Pi) and orangepi-config (for Orange Pi) for more interactive configuration.

Environment

Basic tools and packages

  • tmux: sudo apt install tmux
  • git: sudo apt install git
    • Copy SSH public key to GitHub to clone with SSH
    • Config username and email to commit
  • code-server (if platform doesn’t support VSC Remote)

Build tools and compilers

  • CMake (>=3.22 for most projects)
  • GCC
    • Install via apt: sudo apt install build-essential
  • LLVM + Clang
    • Install from official website: download page
    • One-liner to install latest: bash -c "$(wget -O - https://apt.llvm.org/llvm.sh)"
  • Note: when multiple compilers (GCC, Clang, and different versions) are installed, make sure the $CC and $CXX enviroment variables are correctly set, or the building tools (e.g., CMake) might use the wrong compiler and cause errors

Python environments

  • Miniconda
    • Preferred for most cases
    • One-liner installation (mind the OS and arch)
      • curl -O https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-aarch64.sh
      • bash ~/Miniconda3-latest-Linux-aarch64.sh
        • No sudo or will be installed to another location
      • Press Enter and type yes after reading the agreement
  • Virtualenv
    • If the project specifies
    • Install via apt: sudo apt install python3-venv
  • Note: when both conda and virtualenv are installed, make sure the correct environment is activated (they seem the same from the terminal)

Containers

  • Docker: TODO

Quick Fix

CMake update

Update latest CMake on Ubuntu (generated by Claude):

sudo apt remove --purge cmake
sudo apt purge cmake
sudo apt autoremove

wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | gpg --dearmor - | sudo tee /etc/apt/trusted.gpg.d/kitware.gpg >/dev/null

sudo add-apt-repository "deb https://apt.kitware.com/ubuntu/ $(lsb_release -cs) main"
sudo apt update
sudo apt install cmake

Compiler

Install latest standard library: sudo apt install libstdc++-12-dev

Git Clone

One-liner to use SSH url: sed -i 's/https:\/\/github.com\//git@github.com:/' .gitmodules

Recursive script:

# Function to update .gitmodules and sync
update_modules() {
    sed -i 's/https:\/\/github.com\//git@github.com:/' .gitmodules
    git submodule sync
    git submodule update --init
}

# Function to process each level
process_level() {
    # 1. Update current .gitmodules
    update_modules
    
    # 2. For each currently cloned submodule
    git submodule foreach '
        # 3. Update their .gitmodules if exists
        if [ -f ".gitmodules" ]; then
            sed -i "s/https:\/\/github.com\//git@github.com:/" .gitmodules
            # 4. Update their immediate submodules
            git submodule sync
            git submodule update --init
        fi
    '
}

# 5. Repeat multiple times to ensure all nested levels are processed
for i in {1..5}; do
    echo "Processing level $i"
    process_level
done

Huggingface

HF mirror: export HF_ENDPOINT=https://hf-mirror.com

Mindscope: https://www.modelscope.cn/home