Skip to content

Commit 5281497

Browse files
jfreed-devclaude
jfreed-dev
and
claude
committed
Add Armbian build instructions for Turing RK1
- Create comprehensive docs/ARMBIAN-BUILD.md with: - Build prerequisites and system requirements - Quick start build commands - Customization options (SSH keys, static IPs, packages) - Multi-node automated build script - Troubleshooting guide - Update README with Building Armbian section 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 2c5ba97 commit 5281497

File tree

2 files changed

+341
-2
lines changed

2 files changed

+341
-2
lines changed

‎README.md‎

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,8 @@ Deploy a 4-node K3s cluster on Turing Pi with:
2626

2727
- Terraform >= 1.5
2828
- Ansible >= 2.15
29-
- Turing Pi BMC access (10.10.88.70)
30-
- Armbian image with NPU support from [armbian.com/turing-rk1](https://www.armbian.com/turing-rk1/)
29+
- Turing Pi BMC access
30+
- Armbian image (see [Building Armbian](#building-armbian) or download from [armbian.com/turing-rk1](https://www.armbian.com/turing-rk1/))
3131

3232
## Quick Start
3333

@@ -146,6 +146,28 @@ Requires Armbian with Rockchip vendor kernel (6.1.x).
146146
> **Note**: Dev tools (rknn-toolkit2, ezrknpu) are not installed by default.
147147
> For model conversion, install them manually or use a separate dev machine.
148148
149+
## Building Armbian
150+
151+
Build custom Armbian images with NPU support using the [Armbian build framework](https://github.com/armbian/build):
152+
153+
```bash
154+
# Clone build framework
155+
git clone --depth=1 https://github.com/armbian/build ~/armbian-build
156+
cd ~/armbian-build
157+
158+
# Build image with vendor kernel (required for NPU)
159+
./compile.sh build \
160+
BOARD=turing-rk1 \
161+
BRANCH=vendor \
162+
RELEASE=bookworm \
163+
BUILD_MINIMAL=no \
164+
BUILD_DESKTOP=no
165+
```
166+
167+
Output: `~/armbian-build/output/images/Armbian-*_Turing-rk1_bookworm_vendor_*.img`
168+
169+
For advanced options (custom packages, static IPs, SSH keys), see **[docs/ARMBIAN-BUILD.md](docs/ARMBIAN-BUILD.md)**.
170+
149171
## Development
150172

151173
### Local Testing

‎docs/ARMBIAN-BUILD.md‎

Lines changed: 317 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,317 @@
1+
# Building Armbian for Turing RK1
2+
3+
This guide covers building a custom Armbian image for Turing RK1 compute modules using the official [Armbian build framework](https://github.com/armbian/build).
4+
5+
## Why Build Your Own Image?
6+
7+
- **NPU Support**: The vendor kernel (6.1.x) includes the rknpu driver required for NPU inference
8+
- **Customization**: Pre-configure users, SSH keys, network settings, and packages
9+
- **Reproducibility**: Consistent builds for all cluster nodes
10+
- **Latest Updates**: Get newer packages than pre-built images
11+
12+
## Prerequisites
13+
14+
### System Requirements
15+
16+
| Requirement | Minimum | Recommended |
17+
|-------------|---------|-------------|
18+
| OS | Ubuntu 22.04+ / Debian 12+ | Ubuntu 24.04 |
19+
| RAM | 4 GB | 8+ GB |
20+
| Disk | 30 GB free | 50+ GB SSD |
21+
| Docker | Required | Latest version |
22+
23+
### Install Dependencies
24+
25+
```bash
26+
# Ubuntu/Debian
27+
sudo apt update
28+
sudo apt install -y git curl docker.io
29+
30+
# Add user to docker group (logout/login required)
31+
sudo usermod -aG docker $USER
32+
```
33+
34+
## Quick Start
35+
36+
### Clone the Build Framework
37+
38+
```bash
39+
git clone --depth=1 https://github.com/armbian/build ~/armbian-build
40+
cd ~/armbian-build
41+
```
42+
43+
### Build with Default Settings
44+
45+
```bash
46+
./compile.sh build \
47+
BOARD=turing-rk1 \
48+
BRANCH=vendor \
49+
RELEASE=bookworm \
50+
BUILD_MINIMAL=no \
51+
BUILD_DESKTOP=no \
52+
KERNEL_CONFIGURE=no
53+
```
54+
55+
### Output Location
56+
57+
```
58+
~/armbian-build/output/images/Armbian-unofficial_<version>_Turing-rk1_bookworm_vendor_<kernel>.img
59+
```
60+
61+
## Build Parameters
62+
63+
### Required Parameters
64+
65+
| Parameter | Value | Description |
66+
|-----------|-------|-------------|
67+
| `BOARD` | `turing-rk1` | Target board definition |
68+
| `BRANCH` | `vendor` | Kernel branch (vendor = Rockchip BSP with NPU) |
69+
| `RELEASE` | `bookworm` | Debian 12 (recommended) |
70+
71+
### Optional Parameters
72+
73+
| Parameter | Default | Description |
74+
|-----------|---------|-------------|
75+
| `BUILD_MINIMAL` | `no` | `yes` = minimal image, `no` = full packages |
76+
| `BUILD_DESKTOP` | `no` | `yes` = include desktop, `no` = server only |
77+
| `KERNEL_CONFIGURE` | `no` | `yes` = interactive kernel config |
78+
| `COMPRESS_OUTPUTIMAGE` | `sha,img` | Compression options |
79+
| `EXPERT` | `no` | Show advanced options |
80+
81+
### Kernel Branches
82+
83+
| Branch | Kernel | NPU Support | Use Case |
84+
|--------|--------|-------------|----------|
85+
| `vendor` | 6.1.x | Yes | **Production with NPU** |
86+
| `current` | 6.6.x | Limited | Mainline features |
87+
| `edge` | 6.x | No | Testing only |
88+
89+
## Customization
90+
91+
### Pre-configure Root Password and SSH Keys
92+
93+
Create a customization script that runs during build:
94+
95+
```bash
96+
# Create userpatches directory
97+
mkdir -p ~/armbian-build/userpatches
98+
99+
# Create customization script
100+
cat > ~/armbian-build/userpatches/customize-image.sh << 'EOF'
101+
#!/bin/bash
102+
103+
# Set root password (change this!)
104+
echo "root:YourSecurePassword" | chpasswd
105+
106+
# Add SSH public key
107+
mkdir -p /root/.ssh
108+
chmod 700 /root/.ssh
109+
cat > /root/.ssh/authorized_keys << 'KEYS'
110+
ssh-ed25519 AAAA... your-key-here
111+
KEYS
112+
chmod 600 /root/.ssh/authorized_keys
113+
114+
# Install additional packages
115+
apt-get update
116+
apt-get install -y \
117+
htop \
118+
vim \
119+
curl \
120+
wget \
121+
git \
122+
jq \
123+
python3-pip
124+
125+
# Enable SSH
126+
systemctl enable ssh
127+
EOF
128+
129+
chmod +x ~/armbian-build/userpatches/customize-image.sh
130+
```
131+
132+
### Pre-configure Static IP (Per Node)
133+
134+
For cluster deployments, build separate images with static IPs:
135+
136+
```bash
137+
# Build image for node 1 (control plane)
138+
cat > ~/armbian-build/userpatches/customize-image.sh << 'EOF'
139+
#!/bin/bash
140+
141+
# Set hostname
142+
echo "node1" > /etc/hostname
143+
144+
# Configure static IP
145+
cat > /etc/netplan/10-static.yaml << 'NETPLAN'
146+
network:
147+
version: 2
148+
ethernets:
149+
end0:
150+
dhcp4: no
151+
addresses:
152+
- 10.10.88.73/24
153+
routes:
154+
- to: default
155+
via: 10.10.88.1
156+
nameservers:
157+
addresses:
158+
- 10.10.88.1
159+
- 8.8.8.8
160+
NETPLAN
161+
EOF
162+
163+
chmod +x ~/armbian-build/userpatches/customize-image.sh
164+
165+
# Build
166+
./compile.sh build BOARD=turing-rk1 BRANCH=vendor RELEASE=bookworm
167+
168+
# Rename output
169+
mv output/images/Armbian-*.img output/images/armbian-node1.img
170+
```
171+
172+
Repeat for nodes 2-4 with appropriate IPs (10.10.88.74-76).
173+
174+
### Add Custom Packages
175+
176+
```bash
177+
# Create package list
178+
cat > ~/armbian-build/userpatches/lib.config << 'EOF'
179+
PACKAGE_LIST_ADDITIONAL="htop vim curl wget git jq nfs-common cryptsetup"
180+
EOF
181+
```
182+
183+
## Automated Multi-Node Build
184+
185+
Build all 4 node images with a script:
186+
187+
```bash
188+
#!/bin/bash
189+
# build-cluster-images.sh
190+
191+
NODES=(
192+
"node1:10.10.88.73"
193+
"node2:10.10.88.74"
194+
"node3:10.10.88.75"
195+
"node4:10.10.88.76"
196+
)
197+
198+
GATEWAY="10.10.88.1"
199+
SSH_PUBKEY="ssh-ed25519 AAAA... your-key"
200+
201+
cd ~/armbian-build
202+
203+
for node_config in "${NODES[@]}"; do
204+
HOSTNAME="${node_config%%:*}"
205+
IP="${node_config##*:}"
206+
207+
echo "Building image for $HOSTNAME ($IP)..."
208+
209+
cat > userpatches/customize-image.sh << EOF
210+
#!/bin/bash
211+
echo "$HOSTNAME" > /etc/hostname
212+
213+
cat > /etc/netplan/10-static.yaml << 'NETPLAN'
214+
network:
215+
version: 2
216+
ethernets:
217+
end0:
218+
dhcp4: no
219+
addresses:
220+
- $IP/24
221+
routes:
222+
- to: default
223+
via: $GATEWAY
224+
nameservers:
225+
addresses:
226+
- $GATEWAY
227+
- 8.8.8.8
228+
NETPLAN
229+
230+
mkdir -p /root/.ssh
231+
echo "$SSH_PUBKEY" > /root/.ssh/authorized_keys
232+
chmod 700 /root/.ssh
233+
chmod 600 /root/.ssh/authorized_keys
234+
EOF
235+
236+
chmod +x userpatches/customize-image.sh
237+
238+
./compile.sh build \
239+
BOARD=turing-rk1 \
240+
BRANCH=vendor \
241+
RELEASE=bookworm \
242+
BUILD_MINIMAL=no \
243+
BUILD_DESKTOP=no \
244+
KERNEL_CONFIGURE=no
245+
246+
mv output/images/Armbian-*.img "output/images/armbian-${HOSTNAME}.img"
247+
done
248+
249+
echo "Build complete! Images in ~/armbian-build/output/images/"
250+
```
251+
252+
## Troubleshooting
253+
254+
### Build Fails with Docker Errors
255+
256+
```bash
257+
# Ensure Docker is running
258+
sudo systemctl start docker
259+
260+
# Verify Docker access
261+
docker run --rm hello-world
262+
263+
# Clean Docker cache if needed
264+
docker system prune -a
265+
```
266+
267+
### Out of Disk Space
268+
269+
```bash
270+
# Clean previous builds
271+
cd ~/armbian-build
272+
./compile.sh clean
273+
274+
# Remove old images
275+
rm -rf output/images/*
276+
```
277+
278+
### Kernel Configuration Issues
279+
280+
```bash
281+
# Force rebuild of kernel
282+
./compile.sh build \
283+
BOARD=turing-rk1 \
284+
BRANCH=vendor \
285+
RELEASE=bookworm \
286+
CLEAN_LEVEL=images,debs
287+
```
288+
289+
### Verify NPU Support After Flash
290+
291+
```bash
292+
# Check driver version
293+
cat /sys/kernel/debug/rknpu/version
294+
# Expected: RKNPU driver: v0.9.8
295+
296+
# Check NPU device
297+
ls -la /dev/dri/renderD129
298+
299+
# Check driver loaded
300+
dmesg | grep -i rknpu
301+
```
302+
303+
## Alternative: Download Pre-built Images
304+
305+
If you don't need customization, download official images:
306+
307+
- **Armbian**: https://www.armbian.com/turing-rk1/
308+
- **Turing Pi Ubuntu**: https://firmware.turingpi.com/turing-rk1/
309+
310+
> **Note**: Pre-built images may not have the latest vendor kernel with NPU support. Building your own ensures you get the `vendor` branch kernel.
311+
312+
## Next Steps
313+
314+
After building your images:
315+
316+
1. Flash using Terraform or `tpi` CLI (see [INSTALL.md](../INSTALL.md#flashing-nodes))
317+
2. Run Ansible playbooks to deploy K3s (see [README.md](../README.md#quick-start))

0 commit comments

Comments
 (0)