Chapter 1: Development Environment Setup

Connect your computer to the robot and run your first piece of code. This chapter walks you through a complete dev environment (SSH + VS Code / Qoder + file transfer + deploy from source), so whether you want to tweak existing features or build from scratch, you start here.

In this chapter:

🧭 Reading path: First-time setup, follow 1.1 → 1.2 or 1.3; if you only want to install the system from source (not a prebuilt image), jump to 1.5.

Prerequisites:

• A robot flashed with a Luwu-OS image and powered on (see the Usage guide, “Unboxing & Basic Operations”);
• The robot and your computer on the same WiFi network, and you know the robot’s IP;
• A dev computer that can run VS Code / Qoder (8 GB+ RAM recommended).

1.1 SSH Connection

Make sure the robot and your computer are connected to the same WiFi network (to find the robot's IP: enter the RC Mode, the screen will show the IP, or check your router's client list).

Image version note: Older images use pi / pi as the default username/password; the newer Luwu-OS image uses luwu / luwu. Use the matching credentials for your image. After the first login, it is recommended to change the password with passwd.

System info: Luwu-OS runs on a Raspberry Pi CM4/CM5 (aarch64, Debian 13 trixie). All system code lives in /opt/luwu-os/, and SSH is enabled by default.

# Older image (username/password: pi)
ssh pi@<ROBOT_IP>

# Newer Luwu-OS image (username/password: luwu)
ssh luwu@<ROBOT_IP>

1.2 VS Code Remote Development (Recommended)

VS Code with the Remote-SSH extension is the best way to do secondary development on the robot. You can write code on your computer and run/debug it directly on the robot without repeatedly transferring files.

Setup:

1. Install VS Code on your computer
2. Click the Extensions icon (or press Ctrl+Shift+X), search for Remote - SSH and install it
3. Press F1 to open the command palette, select Remote-SSH: Connect to Host...
4. Enter pi@<IP> or luwu@<IP>, press Enter
5. Enter the password when prompted and wait for the connection
6. After connecting, click "Open Folder" and select /opt/luwu-os/ to browse and edit all the code

💡 On the first connection, VS Code automatically installs the VS Code Server on the robot; please wait 1–2 minutes.

Common operations:

1.3 Vibe Coding with Qoder (Recommended)

Besides writing code by hand, you can also use Qoder (an agentic AI coding platform, built on VS Code) to “vibe code” — describe what you want in natural language, and the AI writes, refines and runs the code for you. It connects to the robot over SSH just like VS Code, which makes it great for quick secondary development and on-robot debugging.

Privacy note: When you connect to the remote host, chat with the AI, or generate code, Qoder carries local context. In anything you publish, avoid exposing real IP addresses, SSH passwords, API Keys or device serial numbers (mask them or use placeholders).

1.3.1 Connect to Your Dev Machine

Open a blank window in Qoder, then connect to the robot through the Remote Development / Connect to Host entry — basically the same “open remote host” feature you already use in VS Code. After connecting, the status bar at the bottom-left shows the current remote host.

Key points:

• In the “Remote Development / Connect to Host” entry, enter luwu@<ROBOT_IP> and pick /opt/luwu-os/ as the working directory;
• Once connected, the top title bar shows luwu-os [SSH: <ROBOT_IP>], the explorer on the left lists the remote host, and you can browse, create, edit and save remote files directly;
• The bottom status bar turns green SSH, meaning you are now fixed on the remote machine;
• The Terminal tab at the bottom can run ssh, scp, rsync sync commands, or sudo bash configs/install.sh to deploy.

1.3.2 Browse the Remote Project

Once connected, the explorer on the left shows the remote project structure on the robot. All Luwu-OS code lives in /opt/luwu-os/. The most important directories (the ones you’ll edit most for secondary development):

• apps/ — application sources (e.g. apps/ai_chat_pro/, apps/voice_chat/, apps/ai/ (old dev version), apps/rc_mode/, apps/launcher/);
• libs/ — low-level motion / vision libraries (xgolib lives here);
• configs/ — system configuration and the install.sh deployment script;
• model/ — model files used by vision recognition;
• xgoBlocklyProjects/ — the run directory for Blockly / AI-generated scripts (the 前进吧.py below is placed here).

1.3.3 Write Code in Natural Language (Vibe Coding)

Pick a target file as context (here we select apps/ai_chat_pro/main.py), then type your need in one plain sentence into the AI chat panel on the right, for example:

“Write a program that makes the robot go forward and then turn right.”

The AI first explores the motion control library in the project, then gives an implementation based on the context. This is the typical chain of responses you’ll see in the chat:

1. Explore the code — the AI reads the repo (it may show “explored 4 code files”) and locates the motion library xgolib (under libs/) to learn the existing APIs;
2. Map your need to capabilities — e.g. “I know xgolib provides forward() (go forward), turn() (turn right), move_x() (go backwards)… let me write a forward program”;
3. Generate code — the AI creates a new Python file (here 前进吧.py) and fills in the full implementation (from xgolib import XGO, import time, # create a robot instance (auto-detect model & serial port), dog = XGO()).

💡 If you want the AI to base its changes on a specific file, reference it with @ in your prompt (e.g. @main.py); the AI will read that file first so the generated edits match the existing code.

1.3.4 Review and Accept the Suggestion

After the AI proposes a plan, the editor shows a diff highlighting the changes: red is removed, green is added. At the same time the AI lists item-by-item suggestions on the right, so you can decide whether to accept.

The generated action parameters look like this (left code pane of the editor):

TURN_SEC = 1.5      # time to turn (seconds)
PAUSE_SEC = 0.3     # pause between steps (seconds)
dog = XGO()         # create a robot instance (auto-detect model & serial port)

dog.forward(18)     # forward: speed 18 for 2 seconds
time.sleep(2)
dog.move_x(VX_SPEED, 1)   # step 1: forward

At the same time, the AI also lists possible runtime issues and tuning tips (green text on the right), for example:

• Not going far enough → increase FORWARD_SEC (step length ~0.2–0.3 s) or increase VX_SPEED;
• Turn less than 90° → increase TURN_SEC (~0.2 s per step) or increase TURN_SPEED;
• Motion not fluid → adjust PAUSE_SEC (0.1–0.5 s).

These parameters are affected by floor friction, battery level and robot model, so run a little first and tune on-site.

To apply the changes, choose Accept in the approval card at the bottom-right, or Discard to reject them (you’ll usually see “1 file changed, 39→7”, i.e. added/deleted line counts). After accepting, the AI will keep iterating or generate the next piece of code.

1.3.5 Generate and Run

After accepting, run it on the robot to verify. The AI usually puts the generated file in a separate run directory (here /opt/luwu-os/xgoBlocklyProjects/前进吧.py), and you can run it directly from the terminal at the bottom:

cd /opt/luwu-os/xgoBlocklyProjects
python3 前进吧.py

When you run it, the terminal prints the program output (forward, turn right, etc.). If the robot does not behave as expected, go back to the chat, describe what actually happened, and let the AI keep tuning the parameters based on the tips above.

💡 When debugging a single app on the robot, you can use run.fifo to let the launcher go through the full startup flow (applies theme / key routing automatically). See Chapter 2 and Chapter 3, section 3.4.

1.4 File Transfer

Besides dragging files into VS Code, you can also transfer files from the command line:

# Upload a file to the robot
scp /path/to/local/file pi@<IP>:/path/to/remote/
scp -r /path/to/local/dir pi@<IP>:/path/to/remote/

# Download a file to your computer
scp pi@<IP>:/path/to/remote/file /path/to/local/

# Incremental sync
rsync -avz /path/to/local/dir/ pi@<IP>:/path/to/remote/dir/

1.5 Deploy from Source (Optional)

Recommended: Most users should flash a prebuilt image with the official Luwu-Imager, which performs OS installation, SD card partitioning and initial configuration automatically. The source-based deployment below is for those who need to customize the system source.

• Windows: LuwuImager-Setup-latest.exe
• macOS: LuwuImager-Setup-latest.dmg

If you have the project source code instead of a flashed image, clone the official repository and run the one-click deployment script:

git clone https://github.com/LuwuDynamics/luwu_os.git /opt/luwu-os
cd /opt/luwu-os
sudo bash configs/install.sh
sudo reboot

⚠️ install.sh is still in active development and may not cover all hardware configurations; for a complete setup experience, prefer the Luwu-Imager approach above.

Requirements: Raspberry Pi CM4 or CM5 with a compatible carrier board; SPI LCD (ST7789V) connected via SPI0; Debian-based Linux. Tech-stack versions: Python 3.11+, C++17, Qt 5.15 (Launcher renders with EGLFS/LinuxFB), OnnxRuntime, Picamera2.

What install.sh does (14 steps in total):

pip dependencies listed in requirements.txt (packages not in apt or needing newer versions):

pyzbar>=0.1                  # QR-code WiFi provisioning (needs apt libzbar0t64 underneath)
paho-mqtt>=2.0               # MQTT (group performance)
xgolib>=1.1                  # Robot motion library
xgoedu-luwuos>=2.0           # Visual programming education library
xgo-blockly-luwuos>=1.0      # Blockly visual programming service